@ledgerhq/zcash-utils 0.3.1 → 1.0.0

package/index.d.ts

@@ -123,6 +123,271 @@ export declare function getChainTip(grpcUrl: string): Promise<number>
  * If the timestamp is after the chain tip, returns the tip height.
  */
 export declare function findBlockHeight(grpcUrl: string, timestamp: number): Promise<number>
+export interface OrchardSpendInputJs {
+  /** 86-char hex (43 bytes: 11-byte diversifier + 32-byte pk_d). */
+  recipient: string
+  /** Decimal u64 (string to avoid f64 precision loss). */
+  valueZat: string
+  /** 64-char hex (32 bytes). */
+  rho: string
+  /** 64-char hex. */
+  rseed: string
+  /** 64-char hex. */
+  cmx: string
+  /** Decimal u64 leaf position in the Orchard commitment tree. */
+  position: string
+}
+export interface OutputRequestJs {
+  /**
+   * Destination address: t-addr (P2PKH/P2SH) or u-addr (Orchard receiver).
+   * Sapling z-addresses and TEX (ZIP-320) addresses are rejected.
+   */
+  address: string
+  valueZat: string
+  memo?: string
+}
+/** One transparent (P2PKH) UTXO to spend. */
+export interface TransparentInputJs {
+  /**
+   * 64-char hex (32 bytes) prevout txid in internal (little-endian) byte order.
+   * Ledger Live surfaces txids in display (big-endian) order; callers must
+   * reverse before passing.
+   */
+  txid: string
+  /** Output index within the origin transaction. */
+  vout: number
+  /**
+   * Hex-encoded raw scriptPubKey bytes (no CompactSize length prefix).
+   * Exposed to JS as `scriptPubKey` (canonical Bitcoin/Zcash casing) rather
+   * than napi's default `scriptPubkey` camelCasing of the Rust field name.
+   */
+  scriptPubKey: string
+  /** UTXO value in zatoshis (decimal string to avoid f64 precision loss). */
+  valueZat: string
+  /** 66-char hex (33 bytes) compressed secp256k1 pubkey controlling the UTXO. */
+  pubkey: string
+  /**
+   * BIP-44 chain (scope) the controlling key lives on: `0` = external,
+   * `1` = internal (change). With `address_index` this identifies the UTXO's
+   * signing key under the account. It is verified against the UFVK (the
+   * derived pubkey must equal `pubkey`) and stamped into the PCZT as the
+   * input's `bip32_derivation`, which the Ledger device uses as the signing
+   * path (the PCZT sign APDU carries no path).
+   */
+  derivationScope: number
+  /**
+   * Non-hardened BIP-44 address index of the controlling key (see
+   * `derivation_scope`).
+   */
+  addressIndex: number
+}
+export interface BuildTransactionParams {
+  grpcUrl: string
+  ufvk: string
+  network?: string
+  /**
+   * 64-char hex (32 bytes): ZIP-32 seed fingerprint of the wallet seed,
+   * read from the device. Stamped onto each real spend so the device can
+   * confirm the PCZT belongs to its seed before signing.
+   */
+  seedFingerprint: string
+  /** ZIP-32 account index the UFVK was derived at. */
+  accountIndex: number
+  /**
+   * Caller-owned fee in zatoshis (decimal string to avoid f64 precision
+   * loss). Per FR-4 the fee is selected by ledger-live; this
+   * crate validates it against ZIP-317 and derives change from it rather
+   * than computing a fee itself.
+   */
+  feeZat: string
+  spends: Array<OrchardSpendInputJs>
+  /** Transparent (P2PKH) UTXOs to spend. Empty for Private→* flows. */
+  transparentInputs: Array<TransparentInputJs>
+  outputs: Array<OutputRequestJs>
+  anchorHeight?: number
+}
+export interface BuildTransactionResult {
+  /**
+   * Hex-encoded canonical PCZT bytes (`PCZT` magic + u32 LE version +
+   * postcard payload). Ready for the device APDU streaming layer. Carries
+   * each real spend's ZIP-32 derivation path for on-device signing.
+   */
+  pcztHex: string
+  /** Decimal fee in zatoshis. */
+  feeZat: string
+  /** Block height the Merkle paths were computed against. */
+  anchorHeight: number
+  /** Orchard action count after dummy padding. */
+  nActionsOrchard: number
+  /** Transparent input count. */
+  nTransparentInputs: number
+  /** Transparent output count (including change). */
+  nTransparentOutputs: number
+}
+/**
+ * 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.
+ *
+ * Note: unlike `finalize_transaction` (purely CPU-bound, offloaded via
+ * `spawn_blocking`), this is an async orchestrator that interleaves gRPC
+ * witness fetches with the CPU-bound proving step, so it cannot be wrapped in a
+ * single `spawn_blocking` call — the proving cost is borne inline.
+ */
+export declare function buildTransaction(params: BuildTransactionParams): Promise<BuildTransactionResult>
+/** Parameters for finalizing a PCZT with device-provided signatures. */
+export interface FinalizeTransactionParams {
+  /** Hex-encoded canonical PCZT bytes from `buildTransaction`. */
+  pczt: string
+  /**
+   * One 64-byte (128-hex-char) RedPallas `spendAuthSig` per real Orchard spend,
+   * in PCZT-action order over the unsigned actions.
+   */
+  orchardSignatures: Array<string>
+  /** One DER-hex secp256k1 signature per transparent input (empty for pure Orchard). */
+  transparentSignatures: Array<string>
+}
+/** Result of a successful `finalizeTransaction` call. */
+export interface FinalizeTransactionResult {
+  /** Hex-encoded signed V5 transaction bytes (ready for `broadcastTransaction`). */
+  txHex: string
+  /**
+   * 64-char hex transaction id, big-endian *display* order (matches the sync
+   * path's `ShieldedTransaction.txid` and the Ledger Live operation hash).
+   */
+  txid: string
+}
+/**
+ * Inject device signatures into a PCZT and extract the final signed V5 transaction.
+ *
+ * Accepts the PCZT from `buildTransaction`, one 64-byte RedPallas signature per
+ * real (unsigned) Orchard action, and one DER secp256k1 signature per transparent
+ * input. The Orchard binding signature is computed host-side.
+ *
+ * CPU-bound (Halo 2 proof verification runs here): the pure call is dispatched
+ * to `tokio::task::spawn_blocking` so the async executor is not starved.
+ */
+export declare function finalizeTransaction(params: FinalizeTransactionParams): Promise<FinalizeTransactionResult>
+/**
+ * Submit a signed transaction to a lightwalletd / Zaino endpoint.
+ *
+ * Returns the txid (64-char hex, big-endian display order — matches the sync
+ * path and the Ledger Live operation hash) on success (`errorCode == 0`).
+ * Returns a descriptive error on a non-zero `errorCode` (carrying the server's
+ * `errorMessage`) or on a gRPC transport failure.
+ */
+export declare function broadcastTransaction(grpcUrl: string, txHex: string): Promise<string>
+/** PCZT header (`common::Global`) fields. */
+export interface PcztGlobal {
+  /** Transaction version (V5 = 5). */
+  txVersion: number
+  versionGroupId: number
+  consensusBranchId: number
+  /** `null` encodes the absent optional lock time. */
+  fallbackLockTime?: number
+  expiryHeight: number
+  /** SLIP-44 coin type (133 mainnet, 1 testnet). */
+  coinType: number
+  txModifiable: number
+}
+/** A `bip32_derivation` entry for a transparent input/output. */
+export interface PcztBip32Derivation {
+  /** Derivation path (no `m/` prefix, hardened indices suffixed with `'`). */
+  signingPath: string
+  /** Compressed secp256k1 public key, 33 bytes. */
+  pubkey: Uint8Array
+  /** ZIP-32 seed fingerprint, 32 bytes. */
+  seedFingerprint: Uint8Array
+}
+/** A single transparent input. */
+export interface PcztTransparentInput {
+  /** Previous output txid, 32 bytes (internal byte order, as stored in the PCZT). */
+  prevoutTxid: Uint8Array
+  prevoutIndex: number
+  /** `null` encodes the absent optional sequence number (final `0xffffffff`). */
+  sequence?: number
+  /** Input value in zatoshis (decimal string to avoid f64 precision loss). */
+  value: string
+  scriptPubKey: Uint8Array
+  /** Sighash type (`SIGHASH_ALL` = `0x01`). */
+  sighashType: number
+  derivation: PcztBip32Derivation
+}
+/** A single transparent output. */
+export interface PcztTransparentOutput {
+  /** Output value in zatoshis (decimal string to avoid f64 precision loss). */
+  value: string
+  scriptPubKey: Uint8Array
+  /** Present (change output) or `null` (external recipient). */
+  derivation?: PcztBip32Derivation
+}
+/** A single Orchard action (spend + output halves), flattened for the device. */
+export interface PcztOrchardAction {
+  /** Value commitment, 32 bytes. */
+  cvNet: Uint8Array
+  /** Spend nullifier, 32 bytes. */
+  nullifier: Uint8Array
+  /** Randomized verification key, 32 bytes. */
+  rk: Uint8Array
+  /** Raw Orchard address of the spent note, 43 bytes. */
+  spendRecipient: Uint8Array
+  /** Spent-note value in zatoshis (decimal string to avoid f64 precision loss). */
+  spendValue: string
+  /** Spend rho, 32 bytes. */
+  spendRho: Uint8Array
+  /** Spend rseed, 32 bytes. */
+  spendRseed: Uint8Array
+  /** Spend-authorization randomizer, 32 bytes. */
+  alpha: Uint8Array
+  /** ZIP-32 derivation path of the signing key. */
+  signingPath: string
+  /** ZIP-32 seed fingerprint, 32 bytes. */
+  seedFingerprint: Uint8Array
+  /** Note commitment x-coordinate, 32 bytes. */
+  cmx: Uint8Array
+  /** Ephemeral key, 32 bytes. */
+  ephemeralKey: Uint8Array
+  encCiphertext: Uint8Array
+  outCiphertext: Uint8Array
+  /** Raw Orchard address of the output note, 43 bytes. */
+  recipient: Uint8Array
+  /** Output-note value in zatoshis (decimal string to avoid f64 precision loss). */
+  value: string
+  /** Output rseed, 32 bytes. */
+  rseed: Uint8Array
+  /** Value commitment randomness, 32 bytes. */
+  rcv: Uint8Array
+}
+/** The Orchard action bundle plus its trailer. */
+export interface PcztOrchardBundle {
+  actions: Array<PcztOrchardAction>
+  flags: number
+  /** Net value balance in zatoshis (signed decimal string, lossless for i128). */
+  valueBalance: string
+  /** Orchard commitment-tree anchor, 32 bytes. */
+  anchor: Uint8Array
+}
+/** A fully structured PCZT ready for `DmkSignerZcash.signPcztTransaction`. */
+export interface PcztTransaction {
+  global: PcztGlobal
+  transparentInputs: Array<PcztTransparentInput>
+  transparentOutputs: Array<PcztTransparentOutput>
+  /** `null` when the transaction has no Orchard actions. */
+  orchardBundle?: PcztOrchardBundle
+}
+/**
+ * Parse canonical PCZT bytes (hex, as returned by `buildTransaction`) into the
+ * structured `PcztTransaction` object the Ledger device signer consumes.
+ *
+ * The PCZT binary format (postcard) is not trivially parseable in TypeScript;
+ * this decodes it in Rust and breaks out the transparent inputs/outputs and
+ * each Orchard action field-by-field. Fails if the input is not a valid PCZT,
+ * or if a field the device requires to sign is missing from it.
+ */
+export declare function parsePczt(pcztHex: string): PcztTransaction
 /**
  * Async iterator over matched shielded transactions.
  *

package/index.js

@@ -310,9 +310,13 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { TransactionStream, startSync, getChainTip, findBlockHeight } = nativeBinding
+const { TransactionStream, startSync, getChainTip, findBlockHeight, buildTransaction, finalizeTransaction, broadcastTransaction, parsePczt } = nativeBinding
 
 module.exports.TransactionStream = TransactionStream
 module.exports.startSync = startSync
 module.exports.getChainTip = getChainTip
 module.exports.findBlockHeight = findBlockHeight
+module.exports.buildTransaction = buildTransaction
+module.exports.finalizeTransaction = finalizeTransaction
+module.exports.broadcastTransaction = broadcastTransaction
+module.exports.parsePczt = parsePczt

package/package.json

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