@ledgerhq/zcash-utils 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @ledgerhq/zcash-utils
 
+## 2.2.0
+
+### Minor Changes
+
+- 0a94002: Build a transparent send without a UFVK. `buildTransaction` required a UFVK for
+  every flow, including a fully transparent one — which carries no shielded bundle
+  and reads no shielded key material. Its only key requirement is the
+  account-level transparent pubkey at `m/44'/coin'/account'`, used to derive the
+  internal change address and to verify each input's signing path. A wallet always
+  holds those bytes (they are the payload of the account xpub) whereas obtaining a
+  UFVK takes a user confirmation on the device, so the requirement forced a
+  viewing-key export on anyone spending public funds.
+
+  `ufvk` is now optional and a `transparentAccountPubkey` field accepts those 65
+  bytes (32-byte chain code ‖ 33-byte compressed pubkey) as hex. A transparent
+  send supplies the pubkey and omits the UFVK; both may be supplied together, in
+  which case the UFVK's transparent component is authoritative and the standalone
+  field only has to agree with it — a mismatch means key material from two
+  different accounts and fails the build rather than picking one. Every flow with
+  a shielded bundle (an Orchard spend, or a shielded recipient) still requires the
+  UFVK and now says so explicitly instead of failing deeper on a missing Orchard
+  component; `buildIronwoodTransaction`, whose bundle is always shielded, is
+  unchanged.
+
+  The two orchestrators now share one transparent-input decoder, so the
+  fund-safety check that ties each input's `(derivationScope, addressIndex)` to
+  its pubkey has a single implementation instead of two copies.
+
+### Patch Changes
+
+- 0a94002: Refresh the dependency lock and collapse the duplicate `shardtree`. The lock
+  carried two copies of it — our own `0.6.2` plus the `0.7.0` that
+  `zcash_client_backend` links — so the commitment-tree types existed twice under
+  identical names and a witness built against one could not cross into the other.
+  Declaring `shardtree = "0.7"` leaves a single `0.7.1` copy that both sides share.
+
+  `pczt` moves to `0.9.3`, still pinned exactly: it defines the byte stream the
+  firmware parses, so it may only move as a deliberate, tested step and never as a
+  side effect of `cargo update`. `bitcoin` stays on the `0.32.x` maintenance line
+  for the same reason — the parallel `0.32.10x` feature line sorts higher and a
+  broad update would otherwise drift onto it — and the pin is now documented in
+  `Cargo.toml` so the next refresh keeps it.
+
+  The rest is a routine refresh of transitive dependencies. No Zcash protocol crate
+  moves: `zcash_primitives`, `zcash_keys`, `zcash_transparent`, `orchard` and
+  `zcash_client_backend` all stay where they were.
+
 ## 2.1.1
 
 ### Patch Changes

package/index.d.ts

@@ -207,9 +207,37 @@ export interface TransparentInputJs {
    */
   addressIndex: number
 }
+/**
+ * Arguments for [`build_transaction`].
+ *
+ * **Invariant: supply `ufvk`, or `transparentAccountPubkey`, or both.** The two
+ * are declared independently optional because this struct crosses into JS,
+ * where "exactly one of" has no encoding — napi rejects a data-carrying enum —
+ * so the rule cannot live in the type. Supplying neither is refused up front,
+ * before any work, rather than deeper in the build. Which one a given flow
+ * needs is on each field below.
+ */
 export interface BuildTransactionParams {
   grpcUrl: string
-  ufvk: string
+  /**
+   * Unified full viewing key of the spending account. Required by every flow
+   * that carries an Orchard bundle (an Orchard spend, or a shielded
+   * recipient); omit it only for a fully transparent send, which reads no
+   * shielded key material and takes its transparent account key from
+   * `transparentAccountPubkey` instead. Spending transparent funds therefore
+   * never requires exporting a viewing key from the device.
+   */
+  ufvk?: string
+  /**
+   * 130-char hex (65 bytes: 32-byte chain code ‖ 33-byte compressed pubkey):
+   * the account-level transparent pubkey at `m/44'/coin'/account'` — the
+   * payload of the account xpub, which a wallet already holds. Used to derive
+   * the internal change address and to verify each transparent input's
+   * signing path. Optional when `ufvk` is supplied (its transparent component
+   * serves, and this field then only has to agree with it); required for a
+   * transparent send that omits the UFVK.
+   */
+  transparentAccountPubkey?: string
   network?: string
   /**
    * 64-char hex (32 bytes): ZIP-32 seed fingerprint of the wallet seed,
@@ -256,7 +284,8 @@ export interface BuildTransactionResult {
  * Supports Orchard-source (Private→*) and transparent-source (Public→*)
  * flows. Halo 2 proof generation happens here for Orchard-bundle transactions
  * (~2-5 s first call, ~hundreds of ms thereafter thanks to the process-global
- * ProvingKey cache). Transparent-only transactions skip the Orchard prover.
+ * ProvingKey cache). Transparent-only transactions skip the Orchard prover, and
+ * need no UFVK — see `ufvk` / `transparentAccountPubkey` on the params.
  *
  * Note: unlike `finalize_transaction` (purely CPU-bound, offloaded via
  * `spawn_blocking`), this is an async orchestrator that interleaves gRPC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ledgerhq/zcash-utils",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Native Zcash key derivation and shielded sync — Node.js (NAPI)",
   "main": "index.js",
   "types": "index.d.ts",