Governance wallet support for shielded voting (zodl 3.4.0, pre-orchard 0.13)

[p0mvn]

Summary

Adds governance wallet methods for shielded voting on top of upstream zcash/librustzcash, rebased onto 95b000e8893bac2440b17b7ceccaff3df48fc220 — the last upstream zcash/main commit before the sapling-crypto 0.7 / orchard 0.13 migration (badfae5a45). The zodl 3.4.0 release track is still on orchard 0.12, so this base keeps us aligned with upstream maintenance while avoiding the 0.13 jump.

The public API additions:

• pczt::roles::signer::Signer::shielded_sighash() — public getter (plus two doc-comment brace fixes near transparent_sighash).
• WalletDb::get_unspent_orchard_notes_at_historical_height(account, height) — returns every Orchard note received at or before height and unspent as of that height. Backward-looking, unlike select_unspent_notes which is forward-looking.
• WalletDb::generate_orchard_witnesses_at_historical_height(positions, frontier, height) — loads the wallet's Orchard shards and cap into an ephemeral MemoryShardStore, inserts the caller-provided frontier via Retention::Checkpoint, and generates Merkle witnesses for each requested position. The wallet DB is strictly read-only.
• Two new orchard-gated SqliteClientError variants so callers can programmatically distinguish "bad frontier" from "wallet not synced through this height":
  • HistoricalFrontierInvalid(shardtree::error::InsertionError)
  • HistoricalWitnessUnavailable { position, height }

Both new WalletDb methods are governance-specific and intentionally not on the WalletRead / WalletWrite traits.

Upstreaming status

Most of the functional changes in this PR are already in flight upstream and will disappear from this branch as they land. The mapping is one-to-one with the upstream commits:

Commits on this branch	Upstream status
Expose PCZT getters needed for shielded voting (Signer::shielded_sighash + doc fixes)	In progress — local branch roman/pczt-0.5.x/shielded-sighash-pub ready to open against upstream. The spend_auth_sig half has already merged as zcash#2281.
zcash_client_sqlite: Add method to query historical unspent Orchard notes + the three review-feedback follow-ups (mined_height, KeyScope::encode, witness-availability doc)	In review at zcash#2284 — approved by @nuttycom, all four commits mirrored one-to-one here.
zcash_client_sqlite: Add historical height witness generation + the four review-feedback follow-ups (module-level imports, MemoryShardStore, redundant-checkpoint cleanup, actionable SqliteClientError variants)	In review at zcash#2283 — all five commits mirrored one-to-one here.

Once zcash#2283 and zcash#2284 merge, this PR collapses to just the PCZT shielded_sighash commit. Once that too lands upstream, the zodl track can point at upstream zcash/main pre-orchard-0.13 with zero carry-forward patches.

Temporary dependency: valar-orchard

The workspace resolves orchard through the valar-orchard crate on crates.io (via cargo's package = rename trick). See the Resolve orchard via valar-orchard on crates.io and ci: unblock cargo-vet and readme-graph for valar-orchard rename commits.

valar-orchard is upstream orchard 0.12.0 + the same post-release fixes that our previous [patch.crates-io] entry pointed at (zcash/orchard rev 6b12c77), plus the pub visibility additions that valargroup/voting-circuits needs for the shielded-voting Halo 2 circuits (constants, spec, shared_primitives gadget).

This is a temporary arrangement. Once orchard 0.13.0 ships upstream with the required pub visibility upstreamed, we will unfork and drop valar-orchard in favor of the canonical orchard crate.

Before routing our fork through valar-orchard, consumers that also depend on voting-circuits (e.g. zcash_voting) ended up with two distinct Orchard crates in their dep graph (orchard via our patch + valar-orchard from crates.io), which Cargo treats as different crates regardless of content. That forced a byte-round-trip orchard_compat bridge at the zcash_keys / pczt boundary. Collapsing both to valar-orchard deletes the bridge.

Why this base commit

95b000e is upstream zcash/main as of 2026-04-23, immediately before badfae5a45 Migrate to sapling-crypto 0.7, orchard 0.13. The fork's valargroup/librustzcash main branch has also been fast-forwarded to 95b000e so the PR diff is clean (no upstream-sync noise).

Test plan

• cargo check -p zcash_client_sqlite --all-features --tests — OK
• cargo check -p zcash_client_sqlite --no-default-features — OK (verifies the #[cfg(feature = "orchard")] gating on Marking / ShardTree imports)
• cargo check --workspace --all-features --tests — OK
• cargo clippy -p zcash_client_sqlite --all-features --all-targets -- -D warnings — OK
• cargo test -p zcash_client_sqlite --all-features --lib historical_height:
  • wallet::commitment_tree::tests::orchard::witnesses_at_historical_height — passed
  • wallet::orchard::tests::get_unspent_orchard_notes_at_historical_height_boundary_heights — passed
• cargo vet --locked — Vetting Succeeded
• python3 .github/helpers/check-dep-graph.py — exit 0, no output

Follow-ups (out of scope)

• Bump zcash_voting/Cargo.toml librustzcash pins from 1bc3a279e3c5 (old tip) to this branch's tip.
• Validate the vote-sdk join flow + iOS signer end-to-end against the new base — main concern is interaction between the new upstream witness_stabilized / rewind_to_height behavior and historical-height witness generation.
• Thread the new HistoricalFrontierInvalid / HistoricalWitnessUnavailable variants through vote-sdk error handling so the join flow can surface a clear "sync further before voting" message to the user.
• Unfork valar-orchard once orchard 0.13.0 lands upstream with the required pub visibility changes.

Made with Cursor