@ledgerhq/zcash-utils 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,51 +1,36 @@
 # @ledgerhq/zcash-utils
 
+## 2.3.0
+
+### Minor Changes
+
+- 9defc44: Relicense to `Apache-2.0`, aligning with the Ledger device stack this package belongs to: the Device Management Kit, the Zcash device signer kit and the Zcash device app are all `Apache-2.0`. Nothing in the repository stated a license authoritatively before — `package.json` declared `MIT`, the four Rust crates declared `MIT OR Apache-2.0`, and no LICENSE file existed at all.
+
+  The declaration now lives in `[workspace.package]` of the root `Cargo.toml`, inherited by every crate, and is mirrored in `package.json`. The full Apache 2.0 text ships as `LICENSE.md`, which npm includes in the tarball even though the `files` field does not name it, so the published package now carries its own license text.
+
+### Patch Changes
+
+- 57b3588: Document the whole published API in the README, which had drifted to covering three of the eleven exports. Everything the send path is made of — `buildTransaction`, `buildIronwoodTransaction`, `parsePczt`, `finalizeTransaction`, `broadcastTransaction` — plus `findBlockHeight`, `transactionDetails` and `orchardAddressFromUfvk` were absent, as were the note fields that make a note spendable (`nullifier`, `rho`, `rseed`, `cmx`, `position`, `recipient`, `isSpent`), `knownNullifiers` / `spentKnownNullifiers`, and `transparentOut` / `hasTransparentInputs`.
+
+  The README now walks the send round trip through the device rather than listing functions, and states the two encoding conventions a caller has to get right: zatoshis are JS numbers on the scanning path but decimal strings on the crafting path, and txids come in display order everywhere except `TransparentInputJs.txid`, which is internal order. Its install step names the Artifactory registry the package actually publishes to.
+
 ## 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.
+- 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.
+- 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.
+  `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.
+  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
 
@@ -73,17 +58,12 @@
 
   Since 0.3.1 the addon grew from a scan-only library into a full Orchard send pipeline:
 
-  - V5 PCZT transaction builder supporting Orchard send flows and mixed
-    transparent + Orchard inputs, with bip32 derivation stamped on the change
-    output and every transparent input
-  - `buildTransaction`, `finalizeTransaction`, and `broadcastTransaction` to
-    build, finalize, and submit a shielded transaction
-  - `parsePczt(pcztHex)` to decode canonical PCZT bytes into a structured
-    `PcztTransaction` consumed by `@ledgerhq/device-signer-kit-zcash`
+  - V5 PCZT transaction builder supporting Orchard send flows and mixed transparent + Orchard inputs, with bip32 derivation stamped on the change output and every transparent input
+  - `buildTransaction`, `finalizeTransaction`, and `broadcastTransaction` to build, finalize, and submit a shielded transaction
+  - `parsePczt(pcztHex)` to decode canonical PCZT bytes into a structured `PcztTransaction` consumed by `@ledgerhq/device-signer-kit-zcash`
   - On-demand Orchard ShardTree witness computation at craft time
   - `findBlockHeight(grpcUrl, timestamp)` binary search over block timestamps
-  - NU6.2-aware crate versions for correct branch-id resolution and shielded
-    parsing at/above the NU6.2 activation height
+  - NU6.2-aware crate versions for correct branch-id resolution and shielded parsing at/above the NU6.2 activation height
 
 ### Minor Changes
 
@@ -124,8 +104,7 @@
   - `zcash_crypto::tree::{build_witnesses, WitnessInputs, WitnessOutput, ShardLeaves}`
   - `zcash_sync::witness::{compute_witnesses, WitnessRequest, NoteRef}`
 
-  Witness data is fetched and assembled on demand at craft time. No tree state
-  is persisted between calls.
+  Witness data is fetched and assembled on demand at craft time. No tree state is persisted between calls.
 
 - 68d013b: Add `buildIronwoodTransaction` for the Ironwood (NU6.3) shielded pool: builds, proves, and serializes an unsigned V6 PCZT carrying an Ironwood bundle (spends and/or outputs), reusing the existing Orchard V5 crafting lifecycle against the updated Action circuit. Ironwood outputs use the `0x03` quantum-recoverable note plaintext, the emitted PCZT is redacted and serialized in the v2 wire format (required for any V6 transaction), and a dedicated non-zero-anchor check rejects an all-zero Ironwood commitment-tree root before it can be silently embedded. Anchor/witness resolution reuses the existing Ironwood sync path (`fetchIronwoodAnchor` / Ironwood witness computation). The shipped Orchard V5 send flow (`buildTransaction`) is unchanged. Like the V5 builder, this is device-coupled (not exposed via the CLI) and depends on release-candidate wallet-side crates (`pczt`, `zcash_client_backend`) pending stable NU6.3 releases.
 - 65c6a95: Add `transactionDetails`, which fetches transactions by txid and reads from each what only the raw bytes hold: the fee it actually paid, and the addresses its shielded outputs paid.

package/LICENSE.md

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026-present Ledger
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,129 +1,206 @@
 # @ledgerhq/zcash-utils
 
-Native Node.js (NAPI) addon for Zcash shielded transaction scanning — built in Rust via [napi-rs](https://napi.rs).
+Native Node.js (NAPI) addon for Zcash wallet operations — built in Rust via [napi-rs](https://napi.rs).
+
+It covers the two halves of a shielded wallet that cannot be done in TypeScript: **scanning** the chain for notes belonging to an account (trial decryption of every compact block), and **crafting** a send as a PCZT for a Ledger device to sign, then reassembling and broadcasting the signed transaction. Halo 2 proving, PCZT (postcard) serialization, and the binding signature all happen here, in Rust.
+
+Spending key material never enters this layer. It reads a Unified Full Viewing Key and an account-level transparent pubkey; every signature comes from the device.
 
 ## 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>/
+```
+
 ```sh
-npm install @ledgerhq/zcash-utils
-# or
 pnpm add @ledgerhq/zcash-utils
 ```
 
-## Quick start
+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).
+
+## Quick start — scanning
 
 ```typescript
 import { startSync, getChainTip } from "@ledgerhq/zcash-utils";
 
-const tip = await getChainTip(
-  "https://zaino-zec-testnet.nodes.stg.ledger-test.com/",
-);
+const grpcUrl = "https://zaino-zec-testnet.nodes.stg.ledger-test.com/";
+const tip = await getChainTip(grpcUrl);
 
 const stream = await startSync({
-  grpcUrl: "https://zaino-zec-testnet.nodes.stg.ledger-test.com/",
+  grpcUrl,
   viewingKey: "uviewtest1...",
   startHeight: tip - 1000,
   endHeight: tip,
   network: "testnet",
+  // Skips all Sapling crypto work. Ledger wallets are Orchard-only, but the
+  // default is false. Ironwood notes are decrypted regardless of this flag.
   orchardOnly: true,
+  // Nullifiers of still-unspent notes from previous scans, so a note spent
+  // in this range is detected across the incremental sync boundary.
+  knownNullifiers: [],
 });
 
 let tx;
 while ((tx = await stream.next()) !== null) {
-  console.log(tx.txid, tx.orchardNotes);
+  // Each note carries its spending fields (nullifier, rho, rseed, cmx,
+  // position, recipient) — persist them, they are the inputs to a later send.
+  console.log(tx.txid, tx.orchardNotes, tx.ironwoodNotes);
 }
 
 const stats = await stream.stats();
+// stats.spentKnownNullifiers — previously-stored notes to mark as spent.
 console.log(`Scanned ${stats.blocksScanned} blocks in ${stats.elapsedMs}ms`);
 ```
 
+## Sending: the full flow
+
+A send is a round trip through the device. This package owns every step except the signing itself.
+
+1. **Craft** — `buildTransaction` (Orchard and/or transparent source) or `buildIronwoodTransaction` (Ironwood source) selects change, computes Merkle witnesses against an anchor, generates the Halo 2 proof, and returns canonical PCZT bytes as hex. The spend inputs are notes found by a previous scan; the fee is chosen by the caller and validated against ZIP-317.
+2. **Parse** — `parsePczt` decodes those bytes into the structured `PcztTransaction` the device signer consumes. The PCZT postcard format is not trivially parseable in TypeScript, which is why this exists.
+3. **Sign** — `signPcztTransaction` from [`@ledgerhq/device-signer-kit-zcash`](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/signer-zcash) streams the PCZT to the device over APDUs and returns one RedPallas `spendAuthSig` per _real_ shielded spend, plus one secp256k1 signature per transparent input. Dummy padding spends are not signed on device; they are self-signed host-side, which is why the counts line up with the unsigned actions this package expects back.
+4. **Finalize** — `finalizeTransaction` injects those signatures, computes the binding signature host-side, and extracts the signed V5 (ZIP-225) or V6 (ZIP-230) transaction.
+5. **Broadcast** — `broadcastTransaction` submits it and returns the txid.
+
+```typescript
+import {
+  buildTransaction,
+  parsePczt,
+  finalizeTransaction,
+  broadcastTransaction,
+  type PcztTransaction,
+  type ShieldedNote,
+} from "@ledgerhq/zcash-utils";
+
+// A note found by a previous scan — its spending fields are what make it
+// spendable (see Quick start above).
+declare const note: ShieldedNote;
+
+// Your wrapper around the signer kit's device action. It answers in bytes —
+// `{ orchard: [{ spendAuthSig }], ironwood: [...], transparentInputSigs: [] }`
+// — so hex-encoding the result is the caller's step. See the signer kit's own
+// documentation for its exact shape.
+declare function signOnDevice(pczt: PcztTransaction): Promise<{
+  orchardSignatures: string[];
+  transparentSignatures: string[];
+}>;
+
+const { pcztHex } = await buildTransaction({
+  grpcUrl,
+  // Required by any flow carrying an Orchard bundle. A fully transparent send
+  // omits it and passes `transparentAccountPubkey` instead — spending public
+  // funds must not require a viewing-key export from the device.
+  ufvk: "uviewtest1...",
+  network: "testnet",
+  // Both read from the device: they let it confirm the PCZT is its own seed's.
+  seedFingerprint: "<64-char hex>",
+  accountIndex: 0,
+  // Caller-owned, decimal zatoshis. Validated against ZIP-317, and change is
+  // derived from it — this crate does not compute a fee.
+  feeZat: "15000",
+  spends: [
+    {
+      recipient: note.recipient!, // 86-char hex
+      valueZat: String(note.amount),
+      rho: note.rho!, // 64-char hex
+      rseed: note.rseed!, // 64-char hex
+      cmx: note.cmx!, // 64-char hex
+      position: note.position!, // decimal u64 string
+    },
+  ],
+  // Always present, empty for a shielded-only send.
+  transparentInputs: [],
+  outputs: [{ address: "u1...", valueZat: "85000", memo: "thanks!" }],
+});
+
+const { orchardSignatures, transparentSignatures } = await signOnDevice(parsePczt(pcztHex));
+
+const { txHex, txid } = await finalizeTransaction({
+  pczt: pcztHex,
+  orchardSignatures, // one 128-hex-char RedPallas sig per real Orchard spend
+  // Supply the list matching the PCZT's shielded bundle; the other may be
+  // empty or omitted. Each is length-checked against the PCZT's unsigned
+  // actions, so signatures for a pool the PCZT does not spend fail closed.
+  ironwoodSignatures: [],
+  transparentSignatures, // one DER-hex secp256k1 sig per transparent input
+});
+
+await broadcastTransaction(grpcUrl, txHex);
+```
+
+Only t-addresses (P2PKH/P2SH) and u-addresses with an Orchard receiver are accepted as destinations. Sapling z-addresses and TEX (ZIP-320) addresses are rejected.
+
 ## API
 
-### `startSync(params: SyncParams): Promise<TransactionStream>`
+Full signatures, every field, and its constraints are in [`index.d.ts`](index.d.ts), generated by napi-rs from the Rust doc comments — that file is the reference, not this table.
 
-Starts scanning a range of compact blocks and returns a transaction stream. The scan runs in the background immediately in Rust — no JS event loop blocking. `GetTransaction` is called only for matched transactions.
+### Chain queries
 
-### `getChainTip(grpcUrl: string): Promise<number>`
+| Export | Purpose |
+| --- | --- |
+| `getChainTip(grpcUrl)` | Current chain tip height. |
+| `findBlockHeight(grpcUrl, timestamp)` | Height of the latest block at or before a Unix timestamp, by interpolation search. Clamps to genesis / tip. |
 
-Returns the current chain tip height from the gRPC endpoint.
+### Scanning
 
-### `TransactionStream`
+| Export | Purpose |
+| --- | --- |
+| `startSync(params)` | Starts scanning a block range in the background and returns a `TransactionStream`. Trial decryption runs entirely in Rust; `GetTransaction` is called only for matched transactions. |
+| `TransactionStream` | Async iterator: `next()` yields the next match or `null` at end of scan, `cancel()` aborts the background task, `stats()` returns scan statistics once exhausted. |
+| `transactionDetails(grpcUrl, requests, network?, ufvk?)` | Reads from raw transaction bytes what an explorer cannot: the true cross-pool fee, and — with a `ufvk` — the payees of shielded outputs. A transaction that cannot be fetched, parsed, or fully priced yields a `null` fee rather than an approximation. |
 
-Async iterator over matched shielded transactions.
+### Sending
 
-| Method                                         | Description                                                                                       |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `next(): Promise<ShieldedTransaction \| null>` | Returns the next matched transaction, or `null` when the scan is complete.                        |
-| `cancel(): void`                               | Cancels the background scan immediately. Buffered transactions are still consumable via `next()`. |
-| `stats(): Promise<SyncStats>`                  | Returns scan statistics once the stream is exhausted.                                             |
+| 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. |
+| `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. |
 
-## Types
+### Receiving
 
-### `SyncParams`
+| Export | Purpose |
+| --- | --- |
+| `orchardAddressFromUfvk(ufvk)` | The Orchard-only unified address, derived exactly as the device derives it (external scope, diversifier index 0, single receiver) — so it passes on-device verification. Use this for the Receive flow. |
 
-```typescript
-interface SyncParams {
-  /** gRPC endpoint URL */
-  grpcUrl: string;
-  /** Unified Full Viewing Key (UFVK) for the account to scan */
-  viewingKey: string;
-  /** First block height to scan (inclusive) */
-  startHeight: number;
-  /** Last block height to scan (inclusive) */
-  endHeight: number;
-  /** "mainnet" or "testnet" (default: "testnet") */
-  network?: string;
-  /**
-   * When true, only Orchard actions are processed — eliminates all Sapling
-   * crypto work. Set to true for Ledger wallets (Orchard-only support).
-   */
-  orchardOnly?: boolean;
-  /**
-   * Maximum retry attempts per range on transient errors.
-   * The failing range is split in half on each retry. Defaults to 3.
-   */
-  maxRetries?: number;
-  /** Emit per-phase timing diagnostics to stderr every 10 seconds */
-  verbose?: boolean;
-}
-```
+Key derivation is deliberately **not** exported here: it lives in the `zcash-crypto` crate and the `ledger-zcash-cli` binary. A wallet gets its keys from the device.
 
-### `ShieldedTransaction`
+## Value encoding
 
-```typescript
-interface ShieldedTransaction {
-  txid: string; // Transaction ID (big-endian hex)
-  hex: string; // Raw transaction bytes (hex)
-  blockHeight: number;
-  blockHash: string; // Block hash (big-endian hex)
-  blockTime: number; // Unix timestamp (seconds)
-  fee: number; // Fee in zatoshis
-  saplingNotes: ShieldedNote[];
-  orchardNotes: ShieldedNote[];
-  ironwoodNotes: ShieldedNote[]; // Ironwood (NU6.3) pool notes
-}
-```
+The same quantity is not spelled the same way everywhere in this API. Read this before wiring anything up.
 
-### `ShieldedNote`
+**Zatoshi amounts.** The scanning path returns them as JS numbers (`ShieldedNote.amount`, `ShieldedTransaction.fee`, `transparentOut`). Every crafting and PCZT field instead uses a **decimal string** (`valueZat`, `feeZat`, `value`, `spendValue`, `valueBalance`), which avoids the precision loss of a `u64`/`i128` round-tripping through an f64.
 
-```typescript
-interface ShieldedNote {
-  amount: number; // Amount in zatoshis
-  transferType: string; // "incoming", "outgoing", or "internal"
-  memo: string;
-  pool: string; // "sapling", "orchard", or "ironwood" — the shielded pool this note belongs to
-}
-```
+**Txid byte order.** Three fields, three conventions:
 
-### `SyncStats`
+| Field | Order |
+| --- | --- |
+| `ShieldedTransaction.txid`, `FinalizeTransactionResult.txid`, `TransactionDetailsRequest.txid`, `TransparentPrevout.txid` | Big-endian _display_ order — matches explorers and the Ledger Live operation hash. |
+| `TransparentInputJs.txid` | Little-endian _internal_ order. Ledger Live surfaces txids in display order, so callers must reverse before passing. |
+| `PcztTransparentInput.prevoutTxid` | Internal byte order, as stored in the PCZT. |
 
-```typescript
-interface SyncStats {
-  blocksScanned: number;
-  elapsedMs: number;
-}
-```
+**`scriptPubKey`** keeps its canonical Bitcoin/Zcash casing, rather than napi's default camelCasing of the Rust field name (`scriptPubkey`).
+
+## Ironwood (NU6.3) status
+
+`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).
+
+Ironwood notes on the scanning path are complete and not gated by `orchardOnly`: `ShieldedTransaction.ironwoodNotes` is populated alongside `orchardNotes`, and `ShieldedNote.pool` distinguishes them.
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md) — crate layout, dependency graph, design decisions
+- [`docs/key-derivation.md`](docs/key-derivation.md) — BIP-39 → ZIP-32 → UFVK pipeline
+- [`docs/block-sync.md`](docs/block-sync.md) — gRPC trial + full decryption
+- [`docs/ffi-node.md`](docs/ffi-node.md) — this addon in depth, with worked examples
+- [`docs/build-targets.md`](docs/build-targets.md) — build scripts and prerequisites
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — building, testing, CLI usage, release process
 
 ## License
 
-MIT OR Apache-2.0
+[Apache-2.0](LICENSE.md), as the rest of the Ledger device stack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ledgerhq/zcash-utils",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Native Zcash key derivation and shielded sync — Node.js (NAPI)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,10 +21,11 @@
     "@changesets/cli": "^2.29.8",
     "@napi-rs/cli": "^2.18.0",
     "@types/node": "^25.5.2",
+    "prettier": "^3.9.6",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "scripts": {
     "// ── NAPI (Node.js / Electron) ──────────────────────────────────────": "",
     "build": "./scripts/build-napi.sh",
@@ -40,6 +41,9 @@
     "// ── Coverage ───────────────────────────────────────────────────────": "",
     "coverage": "./scripts/coverage.sh",
     "coverage:open": "OPEN_REPORT=1 ./scripts/coverage.sh",
+    "// ── Formatting ─────────────────────────────────────────────────────": "",
+    "format": "prettier --write \"**/*.md\"",
+    "format:check": "prettier --check \"**/*.md\"",
     "// ── Rustdoc ────────────────────────────────────────────────────────": "",
     "doc": "cargo doc --workspace --no-deps",
     "doc:open": "cargo doc --workspace --no-deps --open",