feat(zcash): add support for v6 transaction format

[veetragjain]

This branch adds the foundational Zcash v6 (Ironwood / NU6.3) transaction support to wasm-utxo, implemented as a standalone, hand-rolled codec (no librustzcash dependency) so the existing v4 transparent path is completely untouched and non-breaking. It introduces the v6 wire format parse/encode (IronwoodAction/IronwoodBundle/ZcashV6Transaction), the ZIP-244 five-component txid computation, the shared ironwood_digest utility, a crate-local BLAKE2b-personalization helper, and ZIP-316 Unified Address parsing(Bech32m + F4Jumble)

[linear-code]

CSHLD-1059

[OttoAllmendinger]

Suggested split into multiple PRs

The code layers naturally by dependency, and this split also isolates each of the two main review findings into a different PR.

Dependency shape

PR1  blake2b helper  (shared primitive)
      ├── PR2  ZIP-316 Unified Address parsing
      └── PR3  v6 codec + ZIP-244 txid

blake2b.rs is the only thing both features share. UA parsing and the v6 codec don't touch each other, so PR2 and PR3 are independent siblings — reviewable/mergeable in parallel once PR1 lands.

PR 1 — BLAKE2b-256 personalization helper (base)

• src/zcash/blake2b.rs
• src/zcash/mod.rs → pub mod blake2b;
• Cargo.toml, Cargo.lock (the blake2 = "0.10" direct dep)

~90 lines, self-contained, ships with its own unit tests. Small and easy to approve; unblocks the other two.

PR 2 — ZIP-316 Unified Address parsing (off PR1)

• src/zcash/unified_address.rs + pub mod unified_address;
• mod.rs bindings: zcash_parse_unified_address, zcash_resolve_unified_address_component, zcash_is_address_component_of
• ZcashBitGoPsbt.ts: parseUnifiedAddress, resolveUnifiedAddressComponent, isAddressComponentOf
• Fixture: unified_address.json; the UA tests from zcashIronwood.ts
• Good place to fold in the API-design feedback (boolean-flag / duplicate-method redesign) while the surface is still draft.

PR 3 — v6 (Ironwood) codec + ZIP-244 txid (off PR1)

• src/zcash/v6.rs + pub mod v6;
• src/zcash/transaction.rs (v6/Ironwood version-group IDs + the v6-detection guard)
• mod.rs binding: zcash_compute_v6_txid; ZcashBitGoPsbt.ts: computeV6Txid
• Fixtures: v6_*_rawtx.hex / v6_*_txid.hex; the txid tests from zcashIronwood.ts
• Good place to fold in the robustness fix (unbounded Vec::with_capacity on the untrusted Ironwood action count).

One thing to watch

test/fixedScript/zcashIronwood.ts mixes UA and v6-txid tests, so it has to be split across PR2/PR3 (e.g. zcashUnifiedAddress.ts + zcashIronwood.ts). mod.rs, ZcashBitGoPsbt.ts, and zcash/mod.rs each get clean, non-overlapping additions per PR — no conflicts if PR1 merges first.

Base branch for all three can stay zcash-v6-transaction (the current integration branch), unless stacking onto master is preferred.

---

Generated by Claude Code

[OttoAllmendinger]

Code review

Reviewed the full diff (v6 codec, unified-address parsing, blake2b helper, WASM bindings, TS wrapper, tests, fixtures).

Strengths

• Excellent test coverage. Three real captured testnet transactions decode → re-encode byte-identically → reproduce their canonical txids. That validates the whole ZIP-244 hash tree (header/transparent/sapling/orchard/ironwood digests), F4Jumble⁻¹ (against the official ZIP-316 vector and real UAs), and round-trip stability. The right way to validate a hand-rolled codec.
• Clean separation of concerns: empty Sapling/Orchard slots and non-empty bundles are rejected with clear errors rather than mis-parsed.
• Good doc comments citing the exact ZIP-244/316 layouts; personalization constants asserted to be 16 bytes.
• Follows the Uint8Array convention at the WASM/TS boundary (CONVENTIONS §1) — no hex/base64 variants.

Issues

1. (Robustness) Unbounded Vec::with_capacity from an attacker-controlled action count — v6.rs

let n = usize::try_from(n_actions_ironwood).map_err(...)?;
let mut actions = Vec::with_capacity(n);   // n is an uncapped CompactSize (up to 2^64)
for _ in 0..n { let a = take_bytes(&mut r, IRONWOOD_ACTION_SIZE)?; ... }

n_actions_ironwood comes from a bare VarInt::consensus_decode, which is not capped (the MAX_VEC_SIZE guard lives in Decodable for Vec<T>, not in VarInt). A malformed tx declaring nActionsIronwood = 0xFFFFFFFF... triggers a huge pre-allocation before the per-iteration byte-availability check → OOM / WASM abort. decode_v6_transaction is reachable from the public zcash_compute_v6_txid binding with arbitrary bytes.
Fix: validate remaining input before reserving (e.g. r.len() >= n * IRONWOOD_ACTION_SIZE), or drop/cap the capacity hint. (The later spend_auth_sigs with_capacity(n) is fine — n is already bounded by having consumed n×820 bytes.)

2. (CONVENTIONS §3 — boolean trap + duplicate API) UA accessor design

• Boolean flag selecting return semantics. parseUnifiedAddress(addr, net, ironwood: boolean) returns either a 43-byte Orchard receiver or a 25-byte transparent scriptPubKey depending on true/false. parse(addr, net, true) is unreadable at the call site, and one return type carries two unrelated meanings. §3 favors as const unions over magic flags — e.g. a ReceiverKind = ["shielded", "transparent"] as const.
• Inconsistent naming. The sibling method names the same flag resolveShieldedComponent, this one names it ironwood.
• Redundant surface. resolve_unified_address_component is literally parse_unified_address under a renamed bool. Exposing both as public WASM + TS methods is API bloat — collapse to one.

3. (Minor) Network handling

• hrp_for_network accepts zcashRegtest/uregtest, but transparent_address_to_receiver only handles zec/tzec, so is_address_component_of on regtest with a transparent candidate errors despite the container decoding fine. Support it consistently or document the limitation.
• is_address_component_of distinguishes UA vs transparent candidate via candidate.starts_with("u1"/"utest1"). Works for Zcash (transparent addrs start with t), but a try-UA-decode-then-fallback would be less fragile.

4. (Minor) Footguns

• computeV6Txid returns internal byte order; every caller must .reverse() for display. Documented and tested, but consider returning display order (or naming it ...Internal) to avoid silent misuse.
• f4jumble_inv enforces the ZIP-316 minimum length but not the maximum. Not security-critical (bech32-bounded input), but cheap to add.
• debug_assert! on BLAKE2b out_len compiles out in release; current call sites can't violate it, so fine — just noting it isn't a real guard.

Verdict

Solid, well-tested implementation with strong golden-vector validation. #1 is the one I'd fix before merge (untrusted pre-allocation); #2 is a real conventions violation worth resolving while the API is still draft. #3–#4 are polish.

---

Generated by Claude Code

[OttoAllmendinger]

additions should go to zec-namespaced file, maybe take some zcash scoped funcs here with you as well

[OttoAllmendinger]

copy the spec to the repo

[OttoAllmendinger]

why not a method on a psbt? why take txBytes?

[OttoAllmendinger]

Same "opaque bytes" concern as the computeV6Txid thread above, on the return side: these return a bare Uint8Array whose meaning depends on the boolean arg — an Orchard receiver (43 bytes) when true, a transparent scriptPubKey (25 bytes) when false. The caller has to remember which shape they asked for.

Prefer a structured return: decode once into a typed UnifiedAddress with named accessors (.orchardReceiver, .transparentScript), or a discriminated union { kind: "shielded" | "transparent"; ... }. That also removes the boolean flag (CONVENTIONS §3) and collapses parseUnifiedAddress/resolveUnifiedAddressComponent, which are currently the same function under a renamed bool.

---

Generated by Claude Code