@ledgerhq/zcash-utils 1.0.3 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @ledgerhq/zcash-utils
 
+## 1.0.4
+
+### Minor Changes
+
+- Report the fee a transaction actually paid and the addresses its shielded outputs paid, through the new `transactionDetails` function
+- Report the transparent bundle of a scanned transaction, via `transparentOut` and `hasTransparentInputs` on `ShieldedTransaction`
+
+# @ledgerhq/zcash-utils
+
 ## 1.0.3
 
 ### Patch Changes

package/index.d.ts

@@ -94,6 +94,19 @@ export interface ShieldedTransaction {
   blockTime: number
   /** Transaction fee in zatoshis (shielded bundles only). */
   fee: number
+  /**
+   * Sum of the transparent outputs, in zatoshis. Zero without a transparent bundle.
+   *
+   * A shielded→transparent send leaves no decrypted output to account for the
+   * value it moved — only an `internal` change note, or none at all. This is
+   * what tells such a send apart from a self-transfer.
+   */
+  transparentOut: number
+  /**
+   * Whether the transaction spends transparent inputs, in which case those
+   * inputs — rather than the shielded pools — may be paying `transparentOut`.
+   */
+  hasTransparentInputs: boolean
   /** Decrypted Sapling notes belonging to this account. */
   saplingNotes: Array<ShieldedNote>
   /** Decrypted Orchard notes belonging to this account. */
@@ -251,6 +264,92 @@ export interface BuildTransactionResult {
  * single `spawn_blocking` call — the proving cost is borne inline.
  */
 export declare function buildTransaction(params: BuildTransactionParams): Promise<BuildTransactionResult>
+/**
+ * One Ironwood note to spend. Identical shape to [`OrchardSpendInputJs`];
+ * kept as a distinct type for clarity on the JS side.
+ */
+export interface IronwoodSpendInputJs {
+  /** 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 Ironwood commitment tree. */
+  position: string
+}
+export interface IronwoodOutputRequestJs {
+  /**
+   * Destination address: t-addr (P2PKH/P2SH) or u-addr (Orchard receiver —
+   * the same receiver selects the Ironwood pool here). Sapling z-addresses
+   * and TEX (ZIP-320) addresses are rejected.
+   */
+  address: string
+  valueZat: string
+  memo?: string
+}
+export interface BuildIronwoodTransactionParams {
+  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 Rev 1 and derives the (always
+   * Ironwood) change from it rather than computing a fee itself.
+   */
+  feeZat: string
+  spends: Array<IronwoodSpendInputJs>
+  /** Transparent (P2PKH) UTXOs to spend. Empty for Ironwood→* flows. */
+  transparentInputs: Array<TransparentInputJs>
+  outputs: Array<IronwoodOutputRequestJs>
+  anchorHeight?: number
+}
+export interface BuildIronwoodTransactionResult {
+  /**
+   * Hex-encoded canonical PCZT bytes (`PCZT` magic + u32 LE version +
+   * postcard payload), serialized in the **v2** wire format and redacted
+   * (required for any V6 / Ironwood-bearing PCZT — see
+   * `zcash_crypto::craft::build_ironwood_transaction`).
+   */
+  pcztHex: string
+  /** Decimal fee in zatoshis. */
+  feeZat: string
+  /** Block height the Merkle paths were computed against. */
+  anchorHeight: number
+  /** Ironwood action count after dummy padding. */
+  nActionsIronwood: number
+  /** Transparent input count. */
+  nTransparentInputs: number
+  /** Transparent output count. */
+  nTransparentOutputs: number
+}
+/**
+ * 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`).
+ *
+ * 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).
+ */
+export declare function buildIronwoodTransaction(params: BuildIronwoodTransactionParams): Promise<BuildIronwoodTransactionResult>
 /** Parameters for finalizing a PCZT with device-provided signatures. */
 export interface FinalizeTransactionParams {
   /** Hex-encoded canonical PCZT bytes from `buildTransaction`. */
@@ -293,6 +392,65 @@ export declare function finalizeTransaction(params: FinalizeTransactionParams):
  * `errorMessage`) or on a gRPC transport failure.
  */
 export declare function broadcastTransaction(grpcUrl: string, txHex: string): Promise<string>
+/** A transparent output being spent, and its value. */
+export interface TransparentPrevout {
+  /**
+   * 64-char hex txid of the transaction that created the output, in
+   * big-endian display order.
+   */
+  txid: string
+  index: number
+  /** Value in zatoshis, as a decimal string (avoids f64 precision loss). */
+  value: string
+}
+/** A transaction to be resolved. */
+export interface TransactionDetailsRequest {
+  /** 64-char hex txid, big-endian display order. */
+  txid: string
+  /**
+   * Height of the block containing the transaction — determines the
+   * consensus branch the transaction is parsed against.
+   */
+  height: number
+  /**
+   * Value of every transparent output the transaction spends. Omitting any
+   * of them makes the fee unknown; a fully-shielded transaction needs none.
+   */
+  prevouts: Array<TransparentPrevout>
+}
+/** What a transaction's raw bytes reveal that an explorer cannot see. */
+export interface TransactionDetailsResult {
+  txid: string
+  /**
+   * Fee in zatoshis as a decimal string, or `null` when it could not be
+   * established (missing prevout value, or the transaction could not be
+   * fetched or parsed).
+   */
+  fee?: string
+  /**
+   * Addresses of the shielded outputs the account created, in bundle order.
+   * Empty without a viewing key, or when the transaction pays no shielded
+   * address of someone else's.
+   */
+  payees: Array<string>
+}
+/**
+ * Read from each transaction what only its raw bytes hold: the fee it paid,
+ * and where its shielded outputs went. Transactions are fetched by txid.
+ *
+ * A transaction's fee spans every pool: value entering the shielded pools is
+ * not a fee, and value leaving them is not an output the transparent bundle
+ * can account for. Deriving the fee from transparent inputs and outputs alone
+ * is therefore wrong for any transaction that crosses that boundary.
+ *
+ * The payees of shielded outputs are encrypted, and recoverable only by the
+ * account that created them — pass `ufvk` to recover them, omit it to skip.
+ *
+ * Both answers come from the same fetched transaction. One that cannot be
+ * fetched, parsed, or fully priced yields a `null` fee and no payees, rather
+ * than an approximation.
+ */
+export declare function transactionDetails(grpcUrl: string, requests: Array<TransactionDetailsRequest>, network?: string | undefined | null, ufvk?: string | undefined | null): Promise<Array<TransactionDetailsResult>>
 /** PCZT header (`common::Global`) fields. */
 export interface PcztGlobal {
   /** Transaction version (V5 = 5). */

package/index.js

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

package/package.json

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