zingo-netutils

Test counts reflect the dev branch and update on each push.

A complete Indexer abstraction for communicating with Zcash chain indexers (lightwalletd / zainod).

Organizing principle

This crate defines the Indexer trait -- the sole interface a Zcash wallet or tool needs to query, sync, and broadcast against a chain indexer. The trait is implementation-agnostic: production code uses the provided GrpcIndexer (gRPC over tonic), while tests can supply a mock implementor with no network dependency.

All proto types are provided by lightwallet-protocol and re-exported via pub use lightwallet_protocol so consumers do not need an additional dependency.

Usage

use zingo_netutils::{GrpcIndexer, Indexer};

let uri: http::Uri = "https://zec.rocks:443".parse().unwrap();
let indexer = GrpcIndexer::new(uri)?;

let info = indexer.get_info().await?;
let tip  = indexer.get_latest_block().await?;

GrpcIndexer::new validates the URI (scheme must be http or https, authority must be present) and pre-builds the TLS endpoint. It returns Result<Self, GetClientError> -- there is no invalid-state representation.

Backwards compatibility

Code that needs a raw CompactTxStreamerClient<Channel> (e.g. pepper-sync) can still obtain one:

// Using lightwallet-protocol types (preferred)
let client = indexer.get_client().await?;

// Using zcash_client_backend types (migration aid)
// Requires: zingo-netutils = { features = ["back_compatible"] }
let client = indexer.get_zcb_client().await?;

The back_compatible feature brings in zcash_client_backend as an optional dependency and exposes get_zcb_client(), which returns zcash_client_backend's CompactTxStreamerClient<Channel>. This is a bridge for consumers that have not yet migrated to lightwallet-protocol types.

Feature gates

All features are off by default.

Error handling

Every trait method has a dedicated error enum (defined in src/error.rs). Each enum has two variants:

• GetClientError(GetClientError) — the connection was never established. InvalidScheme and InvalidAuthority are deterministic; Transport may be transient and retryable.
• A method-specific gRPC variant wrapping tonic::Status — the server received the request but returned an error.

SendTransactionError adds a third variant, SendRejected(String), for transactions the server evaluated and rejected (not retryable with the same bytes).

All error types are bounded by std::error::Error. Transparent method errors live in error::transparent (gated by globally-public-transparent).

Every error enum has a doc-test proving the contract: From<GetClientError> produces the connection variant, From<tonic::Status> produces the method-specific variant. Feature-gated doc-tests use #[cfg] so cargo test --doc passes with or without features, and assertions execute when the feature is enabled.

Building docs

Docs must be built with --all-features so intra-doc links to feature-gated items resolve:

RUSTDOCFLAGS="-D warnings" cargo doc --all-features --document-private-items

TLS

HTTPS connections use rustls with webpki root certificates (via tonic's tls-webpki-roots feature). No system OpenSSL installation is required.

gRPC endpoint audit

Every CompactTxStreamer RPC from walletrpc/service.proto is covered. The table below shows the mapping between proto RPCs and trait methods.

Exact matches (13)

Intentional divergences (7)

Compile-time enforcement

The proto_agreement test module (src/proto_agreement.rs) contains 20 dead-code async functions that reference both the generated CompactTxStreamerClient method and the corresponding trait method with explicit type annotations. If either side drifts from the proto, the module fails to compile.

Full RPC / method / error audit

Every proto RPC has a 1:1 trait method and a 1:1 error enum.

All error enums share GetClientError (connection failure) as their first variant. Each has a method-specific second variant wrapping tonic::Status. SendTransactionError adds a third variant, SendRejected(String).

License

MIT