@ledgerhq/zcash-utils 2.4.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @ledgerhq/zcash-utils
 
+## 2.5.1
+
+### Patch Changes
+
+- c963227: The Node addon now creates Orchard and Ironwood proofs on every core, about five times faster on an Apple M1 Max; the proof itself is unchanged.
+
+## 2.5.0
+
+### Minor Changes
+
+- 6350264: Add `"regtest"` as a valid `network` value for `buildTransaction`/`buildIronwoodTransaction`. A fresh regtest chain's tip height never reaches the real mainnet/testnet NU5/NU6.3 activation heights, so both builders previously rejected every send against a local node. `network: "regtest"` now resolves to a `LocalNetwork` whose Overwinter-through-Canopy upgrades activate at height 1 and NU5/NU6/NU6.1/NU6.2/NU6.3 at height 2, matching the canonical zebra/zaino/librustzcash regtest defaults.
+
+  A regtest build now stamps derivation paths with mainnet's coin type (133), not regtest's own SLIP-44 value (1, shared with testnet) — this crate's key-derivation surface always derives regtest keys under the mainnet convention, so stamping the SLIP-44 value produced a path no caller actually derives from.
+
+  Known limitation: the PCZT's own `global.coin_type` header field (set independently by the `pczt` crate's `Creator` role from the network's type, with no accessor this crate can override afterwards) still carries regtest's SLIP-44 value (1), inconsistent with the mainnet coin type stamped into the derivation paths above. This has no effect on this crate's own device-free signing surface, which never reads that field; it would matter only to a real device, which is out of scope for regtest support.
+
+### Patch Changes
+
+- ab5930f: Compute Ironwood witnesses from the server's `GetSubtreeRoots` instead of deriving shard roots locally, and fix a shard-0 scan that could hang on either pool.
+
+  Ironwood sends previously rescanned the pool's whole history on every spend and recomputed each completed shard root from scratch, because the deployed indexer rejected `GetSubtreeRoots` for Ironwood. It now serves it, so both pools take the same route: the cost is the spend's own shard footprint rather than the pool's lifetime, and the leaf ceiling that would have failed every shielded send as the pool grew is gone. Measured on mainnet against real shard-0 notes, witness computation drops from roughly 26s to 11s, and no longer degrades as the pool fills.
+
+  Also fixes a latent hang affecting Orchard as well as Ironwood: the scan for a note in commitment-tree shard 0 started at block 1, and since both pools begin millions of blocks after genesis, `GetBlockRange` — which has no per-request timeout — streamed most of the chain instead of failing. The scan now starts at the pool's first leaf.
+
+- 7b40d6d: Move `zcash_client_backend` to its `0.24.0` stable release. The exact pin on `0.24.0-rc.7` carried a comment instructing exactly this once the stable release existed; it was published on 2026-08-19 and the pin had not followed. Nothing in the dependency tree is a release candidate any more, and the full workspace suite passes on the stable release.
+
+  Retire the claims that pin had left behind, three of which were false rather than merely stale. `buildIronwoodTransaction` was documented — in the shipped `index.d.ts`, so every consumer read it — as "dry-run pending the NU6.3 wallet-side crates stabilizing (`pczt`, `zcash_client_backend` are release candidates)". `pczt` was never a release candidate: it is pinned exactly at `0.9.3`, a stable release, because it defines the byte stream the firmware parses. And the crafting path is not a dry run: it is implemented, and its witness computation is tested offline against a real Ironwood anchor captured from a public testnet node. The README now says what the support is actually tested against instead.
+
+  Fix the two things the README got wrong about the package itself. It told readers to route the `@ledgerhq` scope to an internal registry, when the package is published on the public npm registry and `npm install` works unconfigured with no `.npmrc` entry at all. It also declared its license with a trailing editorial flourish rather than naming it plainly.
+
+  Replace the Ledger staging gRPC endpoint used as the example value throughout the public surface — `index.d.ts`, the CLI's `--grpc-url` help, `docs/ffi-node.md`, the runnable examples — with the public `https://testnet.zec.rocks:443`. The former host does not resolve outside Ledger's network, so every published example was unusable by anyone outside it. Ledger's own nodes remain the defaults in the integration tests, which are Ledger's to run.
+
+- 013e2cf: Add a test-only NAPI signing surface (`testDeriveKeys`, `testSignPczt`) so the `ledger-live` coin-tester can derive keys and sign a PCZT's Orchard actions, Ironwood (V6) actions, and transparent inputs from a seed, acting as a device stand-in in CI. Never call this from production wallet code.
+
 ## 2.3.0
 
 ### Minor Changes

package/README.md

@@ -16,7 +16,7 @@ Published on the public npm registry under the `@ledgerhq` scope; no registry co
 
 Prebuilt `.node` binaries are bundled for six targets — `darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`, `win32-x64-msvc`, `win32-arm64-msvc` — so there is no compilation step and no Rust toolchain to install. On any other platform, build from source: see [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
-Node.js 20 or later. The addon is a native module, so it runs in Node and in the Electron main process, not in a browser or a renderer without `nodeIntegration`.
+Node.js 24 or later. The addon is a native module, so it runs in Node and in the Electron main process, not in a browser or a renderer without `nodeIntegration`.
 
 ## Quick start — scanning
 
@@ -155,7 +155,7 @@ Full signatures, every field, and its constraints are in [`index.d.ts`](index.d.
 
 | Export | Purpose |
 | --- | --- |
-| `buildTransaction(params)` | Builds, proves, and serializes a V5 PCZT from Orchard notes, transparent UTXOs, or both. Bears the Halo 2 proving cost inline (~2–5 s cold, ~hundreds of ms after, via a process-global proving-key cache). |
+| `buildTransaction(params)` | Builds, proves, and serializes a V5 PCZT from Orchard notes, transparent UTXOs, or both. Halo 2 proving runs on every core, off the JavaScript thread: about five times faster than on a single core (roughly 0.35–0.4 s per action on an Apple M1 Max), plus a one-time proving-key build per circuit (cached process-wide). The Node addon enables this. A consumer of the `zcash-crypto` Rust crate proves on a single core unless it enables the crate's `multicore` feature; inside this workspace, feature unification turns it on for every build and test. |
 | `buildIronwoodTransaction(params)` | Same, for an Ironwood (NU6.3) source — a redacted V6 PCZT. See [Ironwood (NU6.3)](#ironwood-nu63) below. |
 | `parsePczt(pcztHex)` | Decodes canonical PCZT bytes into the `PcztTransaction` the device signer consumes. Fails if a field the device needs to sign is missing. |
 | `finalizeTransaction(params)` | Injects device signatures, computes the binding signature, extracts the signed transaction and its txid. CPU-bound (proof verification), dispatched to a blocking thread. |

package/index.d.ts

@@ -285,10 +285,12 @@ export interface BuildTransactionResult {
  * Build, prove, and serialize a PCZT for a send transaction.
  *
  * 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, and
- * need no UFVK — see `ufvk` / `transparentAccountPubkey` on the params.
+ * flows. Halo 2 proof generation happens here for Orchard-bundle transactions.
+ * It runs on every core, off the JavaScript thread: about five times faster
+ * than on a single core (roughly 0.35–0.4 s per action on an Apple M1 Max),
+ * plus a one-time proving-key build per circuit that the
+ * process-global ProvingKey cache then amortizes. 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
@@ -375,9 +377,10 @@ export interface BuildIronwoodTransactionResult {
  * place of Orchard ones and emitting a V6 (ZIP-230) PCZT.
  *
  * Same proving-cost profile as `buildTransaction`: Halo 2 proof generation
- * happens here for the Ironwood bundle (~2-5 s first call against the
- * `PostNu6_3` circuit, ~hundreds of ms thereafter via the process-global
- * proving-key cache).
+ * happens here for the Ironwood bundle, on every core and off the JavaScript
+ * thread (roughly 0.35–0.4 s per action on an Apple M1 Max), plus a one-time
+ * proving-key build for the `PostNu6_3` circuit that the process-global
+ * proving-key cache then amortizes.
  */
 export declare function buildIronwoodTransaction(params: BuildIronwoodTransactionParams): Promise<BuildIronwoodTransactionResult>
 /** Parameters for finalizing a PCZT with device-provided signatures. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ledgerhq/zcash-utils",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "Native Zcash key derivation and shielded sync — Node.js (NAPI)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -18,7 +18,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
+    "@changesets/cli": "^3.0.3",
     "@napi-rs/cli": "^2.18.0",
     "@types/node": "^25.5.2",
     "prettier": "^3.9.6",