@ledgerhq/zcash-utils 2.3.0 → 2.4.0

package/README.md

@@ -8,25 +8,24 @@ Spending key material never enters this layer. It reads a Unified Full Viewing K
 
 ## Installation
 
-The package is published to Ledger's internal JFrog Artifactory, not to public npm, so the `@ledgerhq` scope must be routed there:
-
 ```sh
-# ~/.npmrc
-@ledgerhq:registry=https://<artifactory-host>/
+npm install @ledgerhq/zcash-utils
 ```
 
-```sh
-pnpm add @ledgerhq/zcash-utils
-```
+Published on the public npm registry under the `@ledgerhq` scope; no registry configuration is needed.
 
-Prebuilt `.node` binaries are bundled in the package for six targets: `darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`, `win32-x64-msvc`, `win32-arm64-msvc`. On any other platform, build from source — see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+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`.
 
 ## Quick start — scanning
 
 ```typescript
 import { startSync, getChainTip } from "@ledgerhq/zcash-utils";
 
-const grpcUrl = "https://zaino-zec-testnet.nodes.stg.ledger-test.com/";
+// Any lightwalletd or Zaino endpoint. This one is public; Ledger Live points
+// at its own infrastructure.
+const grpcUrl = "https://testnet.zec.rocks:443";
 const tip = await getChainTip(grpcUrl);
 
 const stream = await startSync({
@@ -157,7 +156,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). |
-| `buildIronwoodTransaction(params)` | Same, for an Ironwood (NU6.3) source — a redacted V6 PCZT. See the status note below. |
+| `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. |
 | `broadcastTransaction(grpcUrl, txHex)` | Submits a signed transaction to a lightwalletd / Zaino endpoint; returns the txid. |
@@ -186,11 +185,13 @@ The same quantity is not spelled the same way everywhere in this API. Read this
 
 **`scriptPubKey`** keeps its canonical Bitcoin/Zcash casing, rather than napi's default camelCasing of the Rust field name (`scriptPubkey`).
 
-## Ironwood (NU6.3) status
+## Ironwood (NU6.3)
+
+Ironwood is supported on both halves of the wallet, and the crates it rests on are on their stable releases.
 
-`buildIronwoodTransaction` is exposed so the JS side can be wired up in parallel, but Rust-side Ironwood crafting is still a dry run: the wallet-side crates it depends on (`pczt`, `zcash_client_backend`) are release candidates for NU6.3. Those pins are re-confirmed and bumped to the stable releases before the mainnet build cut. See [`docs/architecture.md`](docs/architecture.md).
+Scanning is not gated by `orchardOnly`: `ShieldedTransaction.ironwoodNotes` is populated alongside `orchardNotes`, and `ShieldedNote.pool` tells the two apart. Crafting goes through `buildIronwoodTransaction`, which emits a V6 (ZIP-230) PCZT; `finalizeTransaction` and `broadcastTransaction` accept V6 as they do V5.
 
-Ironwood notes on the scanning path are complete and not gated by `orchardOnly`: `ShieldedTransaction.ironwoodNotes` is populated alongside `orchardNotes`, and `ShieldedNote.pool` distinguishes them.
+What that support is tested against is worth knowing, since the pool is young. Witness computation is checked offline against a real Ironwood anchor captured from a public testnet node, scanning from the NU6.3 testnet activation height. Trial decryption is exercised against a synthetic Ironwood action built from the `orchard` note-encryption API — genuine cryptography, but not a real on-chain transaction, because no Ironwood transaction addressed to a key we hold has been available to capture as a fixture.
 
 ## Documentation
 
@@ -203,4 +204,4 @@ Ironwood notes on the scanning path are complete and not gated by `orchardOnly`:
 
 ## License
 
-[Apache-2.0](LICENSE.md), as the rest of the Ledger device stack.
+[Apache-2.0](LICENSE.md)

package/index.d.ts

@@ -10,7 +10,10 @@
  * a seed phrase directly in this layer.
  */
 export interface SyncParams {
-  /** gRPC endpoint URL (e.g. `"https://zaino-zec-testnet.nodes.stg.ledger-test.com/"`). */
+  /**
+   * gRPC endpoint URL of a lightwalletd or Zaino server (e.g. the public
+   * `"https://testnet.zec.rocks:443"`).
+   */
   grpcUrl: string
   /** Unified Full Viewing Key (UFVK) for the account to scan. */
   viewingKey: string
@@ -368,10 +371,8 @@ export interface BuildIronwoodTransactionResult {
 /**
  * Build, prove, and serialize a redacted V6 PCZT for an Ironwood send.
  *
- * Rust-only crafting is dry-run pending the NU6.3 wallet-side crates
- * stabilizing (`pczt`, `zcash_client_backend` are release candidates); this
- * NAPI wrapper is exposed now so the JS side can be wired up in parallel and
- * re-pinned when those crates stabilize (see `docs/architecture.md`).
+ * The Ironwood counterpart of `buildTransaction`, taking Ironwood notes in
+ * 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
@@ -679,6 +680,57 @@ export declare function parsePczt(pcztHex: string): PcztTransaction
  * all available receivers and does NOT match the device address.
  */
 export declare function orchardAddressFromUfvk(ufvk: string): string
+/** TEST-ONLY. Account UFVK + transparent xpub, as derived from a mnemonic. */
+export interface TestDerivedKeys {
+  ufvk: string
+  xpub: string
+}
+/**
+ * TEST-ONLY. Derives the account UFVK and transparent xpub from a mnemonic.
+ * Not named `deriveKeys` — that name is reserved for an anticipated future
+ * production export.
+ *
+ * Exists so the `ledger-live` coin-tester can obtain the same UFVK/xpub a
+ * device would report, without a physical Ledger. Never call this from
+ * production wallet code: it holds the mnemonic (spending-key material) in
+ * process memory, which the production host must never do.
+ */
+export declare function testDeriveKeys(mnemonic: string, account: number, network: string): TestDerivedKeys
+/** TEST-ONLY. Result of [`test_sign_pczt`]. */
+export interface TestSignPcztResult {
+  /**
+   * 128-hex-char RedPallas `spendAuthSig`, one per unsigned Orchard action,
+   * in PCZT-action order. Empty when the PCZT carries no Orchard bundle.
+   */
+  orchardSignatures: Array<string>
+  /**
+   * 128-hex-char RedPallas `spendAuthSig`, one per unsigned Ironwood
+   * action, in PCZT-action order. Empty when the PCZT carries no Ironwood
+   * bundle (e.g. a V5/Orchard or transparent-only PCZT).
+   */
+  ironwoodSignatures: Array<string>
+  /**
+   * Hex DER secp256k1 signature, one per transparent input, in input order.
+   * Empty when the PCZT carries no transparent inputs.
+   */
+  transparentSignatures: Array<string>
+}
+/**
+ * TEST-ONLY. Signs whichever bundles the PCZT carries (Orchard actions,
+ * Ironwood actions, transparent inputs) using spending-key material derived
+ * from `mnemonic`. An absent bundle yields an empty list for that leg, not
+ * an error.
+ *
+ * Exists so the `ledger-live` coin-tester can act as a device stand-in in
+ * CI: `coin-zcash` routes z→z, z→t and t→z through the V6/Ironwood builder
+ * (only t→t stays V5), so both spend-auth legs are covered here. Never call
+ * this from production wallet code: it derives and holds spending-key
+ * material from a seed, which the production host must never do.
+ *
+ * CPU-bound (Orchard/Ironwood proving-key-adjacent signing work): dispatched
+ * to `tokio::task::spawn_blocking`, mirroring `finalize_transaction`.
+ */
+export declare function testSignPczt(mnemonic: string, account: number, network: string, pcztHex: string): Promise<TestSignPcztResult>
 /**
  * Async iterator over matched shielded transactions.
  *

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { TransactionStream, startSync, getChainTip, findBlockHeight, buildTransaction, buildIronwoodTransaction, finalizeTransaction, broadcastTransaction, transactionDetails, parsePczt, orchardAddressFromUfvk } = nativeBinding
+const { TransactionStream, startSync, getChainTip, findBlockHeight, buildTransaction, buildIronwoodTransaction, finalizeTransaction, broadcastTransaction, transactionDetails, parsePczt, orchardAddressFromUfvk, testDeriveKeys, testSignPczt } = nativeBinding
 
 module.exports.TransactionStream = TransactionStream
 module.exports.startSync = startSync
@@ -323,3 +323,5 @@ module.exports.broadcastTransaction = broadcastTransaction
 module.exports.transactionDetails = transactionDetails
 module.exports.parsePczt = parsePczt
 module.exports.orchardAddressFromUfvk = orchardAddressFromUfvk
+module.exports.testDeriveKeys = testDeriveKeys
+module.exports.testSignPczt = testSignPczt

package/package.json

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