Indexer trait by zancas · Pull Request #53 · zingolabs/zingo-common

zancas · 2026-03-13T05:29:30Z

Fixes: #52

When tested against zingolib all lints and (140) tests pass.

This trait-based interface is going to be very useful for mocking out calls to the indexer. I wanted it to test offline-mode.

zingo-netutils/src/lib.rs

dorianvp · 2026-03-26T21:49:35Z

This may be relevant: #55 (comment)

zancas · 2026-03-26T23:17:58Z

Does #55 block this PR, or can it be addressed next?

dorianvp · 2026-03-26T23:19:47Z

I think the only blocker, or question, is whether we want to expose zcash_client_backend (a higher-level library) at such low level.

…h callers

Add `globally-public-transparent` feature gating all transparent address methods (get_taddress_*, get_address_utxos*) including the new client-streaming get_taddress_balance_stream(Vec<Address>). Off by default so consumers must opt in to transparent functionality. Add `back_compatible` opt-in feature providing get_zcb_client() which returns zcash_client_backend's CompactTxStreamerClient for pepper-sync compat during migration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

● All three clean — default, ping-only, and all features. Commit message: gate Ping RPC behind ping-very-insecure feature Add the Ping(Duration) -> PingResponse method to the Indexer trait, gated behind `ping-very-insecure`. The feature name mirrors the lightwalletd CLI flag `--ping-very-insecure` that must be set server-side to enable this endpoint. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Move all transparent address methods into a TransparentIndexer: Indexer sub-trait with a single TransparentError associated type. The trait definition and GrpcIndexer impl live in src/globally_public.rs, gated by one #[cfg(feature = "globally-public-transparent")] on the module. Also: - Add ping-very-insecure feature gate for Ping RPC (name mirrors the lightwalletd --ping-very-insecure CLI flag required server-side) - Bound all associated error types with std::error::Error - Rename GetTreesError to GetTreeStateError to match the proto/method - Strengthen doc comments across all trait methods Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Addresses #53 (comment) ● verify trait-to-proto agreement and fix get_tree_state signature Change get_tree_state to accept BlockId instead of u64, matching the proto: GetTreeState(BlockID) returns (TreeState). Callers who have a height construct BlockId { height, hash: vec![] }; callers with a block hash can now use it directly. Endpoint-by-endpoint proto agreement audit: Exact matches (13): GetTreeState(BlockID) -> TreeState GetBlock(BlockID) -> CompactBlock GetBlockNullifiers(BlockID) -> CompactBlock GetBlockRange(BlockRange) -> stream CompactBlock GetBlockRangeNullifiers(BlockRange) -> stream CompactBlock GetTransaction(TxFilter) -> RawTransaction GetTaddressTxids(TABF) -> stream RawTransaction GetTaddressTransactions(TABF) -> stream RawTransaction GetTaddressBalance(AddressList) -> Balance GetMempoolTx(GetMempoolTxRequest) -> stream CompactTx GetSubtreeRoots(GetSubtreeRootsArg) -> stream SubtreeRoot GetAddressUtxos(GetAddressUtxosArg) -> GetAddressUtxosReplyList GetAddressUtxosStream(GetAddressUtxosArg) -> stream GetAddressUtxosReply Ping(Duration) -> PingResponse Intentional divergences (7): get_info() — hides Empty request arg get_latest_block() — hides ChainSpec request arg get_mempool_stream() — hides Empty request arg get_latest_tree_state() — hides Empty request arg send_transaction(Box<[u8]>) -> String — abstracts RawTransaction input and SendResponse output into raw bytes / txid string get_taddress_balance_stream(Vec<Address>) — models client-streaming as Vec, impl converts to stream internally ping(ProtoDuration) — alias avoids std::time::Duration collision Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Introduce src/proto_agreement.rs with 20 dead-code async fns that reference both the generated CompactTxStreamerClient method and the corresponding Indexer/TransparentIndexer trait method with explicit type annotations. If either side drifts from the proto, the test module fails to compile. The proto source of truth is walletrpc/service.proto from the lightwallet-protocol crate (version pinned in Cargo.toml), compiled from https://github.com/zingolabs/lightwallet-protocol-rust. TransparentIndexer tests are grouped in a `mod transparent` sub-module gated once by #[cfg(feature = "globally-public-transparent")]. Ping is gated by #[cfg(feature = "ping-very-insecure")]. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

#53 (comment)

● fix get_block_range doc: support ascending and descending order The proto spec says: "If range.start <= range.end, blocks are returned increasing height order; otherwise blocks are returned in decreasing height order." Our doc incorrectly claimed ascending-only. Fixed to document both directions. Added integration test `tests::get_block_range_supports_descending_order` that verifies descending order against zec.rocks (passes). Addresses #53 (comment) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zancas · 2026-03-27T19:03:52Z

Adding explicit 1:1 method-error-enums where they were missing...

Replace RpcError and TransparentError with 20 dedicated error enums, one per trait method. Each enum has a GetClientError variant (connection failure) and a method-specific tonic::Status variant. SendTransactionError adds SendRejected(String). All error definitions live in src/error.rs with transparent errors in an error::transparent submodule gated by globally-public-transparent. Every error enum has: - Contract documentation explaining what each variant means - A doc-test proving From conversions and variant matching - Unit tests exercising each variant Feature-gated doc-tests use #[cfg] so cargo test --doc passes with or without features, and assertions execute when the feature is enabled. README and CHANGELOG updated with the full 20-row RPC/method/error audit table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add organizing principle, feature gate table, and backwards compatibility section to the lib.rs module doc. Content is a strict subset of the README, covering what isn't directly accessible from doc comments or source: architectural intent, feature discovery, and migration guidance. Intra-doc links to feature-gated items (TransparentIndexer, Indexer::ping, GrpcIndexer::get_zcb_client) require --all-features. CI doc command updated to: RUSTDOCFLAGS="-D warnings" cargo doc --all-features --document-private-items Fix redundant explicit link in globally_public.rs module doc. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Update ci-pr.yaml to use infrastructure@672fe8a which supports the doc-all-features input. This makes the doc phase run cargo doc --all-features --document-private-items instead of cargo-checkmate run doc, so intra-doc links to feature-gated items (TransparentIndexer, Indexer::ping, GrpcIndexer::get_zcb_client) resolve. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zancas · 2026-03-27T21:18:19Z

There's a non-blocking CI-doc-test issue, that may resolve, but shouldn't prevent this code landing as I can get doc-tests to pass locally.

zancas · 2026-03-27T21:31:53Z

It passed!

I believe I have addressed all concerns.

zancas · 2026-03-28T16:37:02Z

There's a non-blocking CI-doc-test issue, that may resolve, but shouldn't prevent this code landing as I can get doc-tests to pass locally.

I have resolved this CI issue.

juanky201271

let's go...

zingo-netutils/src/error.rs

zingo-netutils/README.md

zingo-netutils/src/lib.rs

zingo-netutils/src/error.rs

zingo-netutils/src/globally_public.rs

zancas added 3 commits March 12, 2026 21:54

add GrpcIndex type, and impl new Indexer trait on it

d2c94b9

add tree_state trait method

c3db3b6

2.0.2 --> 3.0.0, cargo update

492a36b

zancas requested review from Oscar-Pepper, dorianvp, fluidvanadium and nachog00 March 13, 2026 05:29

add CHANGELOG

dac04c3

nachog00 reviewed Mar 13, 2026

View reviewed changes

zingo-netutils/src/lib.rs Outdated Show resolved Hide resolved

nachog00 reviewed Mar 13, 2026

View reviewed changes

zingo-netutils/src/lib.rs Outdated Show resolved Hide resolved

per-method enum errors, one variant per method failure mode

aa585c4

zancas marked this pull request as draft March 13, 2026 17:31

zancas added 9 commits March 13, 2026 10:38

move test code into mod tests

ae73bba

fmt

eac3f9c

simplify pem file lookup

ee03327

remove more kruft

8e47d43

start unit-test

0c6861f

move construction logic out of get_client into GrpcIndexer::new

a30775e

update test to newer interface

d2bd968

disconnect is not part of the GrpcIndexer contract

119c17b

select ring features over aws-lc-rs

d801649

pacu requested changes Mar 26, 2026

View reviewed changes

zingo-netutils/src/lib.rs Show resolved Hide resolved

add trait method doc-comments explicitly describing the contracts wit…

cf0314e

…h callers

pacu previously approved these changes Mar 26, 2026

View reviewed changes

zancas added 2 commits March 26, 2026 17:40

switch from zcb to lightwallet-protocol-rust

55a2698

use our own lightwallet protocol

bc0df28

zancas dismissed pacu’s stale review via bc0df28 March 27, 2026 01:08

zancas mentioned this pull request Mar 27, 2026

Back compat zcb #57

Closed

zancas added 11 commits March 27, 2026 10:26

update stale change-log

5026c8e

constrain errors to be std::error::Error

7a7eafd

add test proving that the references documentation is incorrect

4f06d99

#53 (comment)

ensure implementation contract is documented on deprecated end-point

ed8341b

update CHANGELOG and README

9dfb536

zancas requested review from dorianvp and pacu March 27, 2026 18:54

minor quality improvements

25e8062

zancas added 5 commits March 27, 2026 12:22

add enums and tests for all method errors

beab9ea

point at new infa commit in CI

3c9005f

juanky201271 approved these changes Mar 28, 2026

View reviewed changes

nachog00 reviewed Mar 29, 2026

View reviewed changes

zingo-netutils/src/error.rs Show resolved Hide resolved

zingo-netutils/README.md Show resolved Hide resolved

zingo-netutils/src/lib.rs Show resolved Hide resolved

zingo-netutils/src/error.rs Show resolved Hide resolved

zingo-netutils/src/globally_public.rs Show resolved Hide resolved

This was referenced Mar 29, 2026

the expansion of the definition of the indexer trait raises naming and scoping issues #59

Open

audit tests for low-quality tests #60

Closed

zancas merged commit b4a8b61 into dev Mar 29, 2026
10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Indexer trait#53

Indexer trait#53
zancas merged 41 commits intodevfrom
indexer_trait

zancas commented Mar 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dorianvp commented Mar 26, 2026

Uh oh!

zancas commented Mar 26, 2026

Uh oh!

dorianvp commented Mar 26, 2026

Uh oh!

zancas commented Mar 27, 2026

Uh oh!

zancas commented Mar 27, 2026

Uh oh!

zancas commented Mar 27, 2026

Uh oh!

zancas commented Mar 28, 2026

Uh oh!

juanky201271 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

zancas commented Mar 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dorianvp commented Mar 26, 2026

Uh oh!

zancas commented Mar 26, 2026

Uh oh!

dorianvp commented Mar 26, 2026

Uh oh!

zancas commented Mar 27, 2026

Uh oh!

zancas commented Mar 27, 2026

Uh oh!

zancas commented Mar 27, 2026

Uh oh!

zancas commented Mar 28, 2026

Uh oh!

juanky201271 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants