fix(coin-zcash): bound input selection to device PCZT ceilings

Author: cted-ledger

.changeset/coin-zcash-bound-input-selection.md

@@ -0,0 +1,5 @@
+---
+"@ledgerhq/coin-zcash": patch
+---
+
+Bound transparent-input and Ironwood-note selection to the device's per-PCZT ceilings on both pools, so a send from an account holding more UTXOs or notes than the device can sign in one PCZT no longer produces an unsignable transaction. A send whose full balance covers the requested amount but whose device-safe selection does not now reports a distinct, actionable error instead of a plain insufficient-balance one.

libs/coin-modules/coin-zcash/src/bridge/getTransactionStatus.test.ts

@@ -1,4 +1,5 @@
 import { BigNumber } from "bignumber.js";
+import { NotEnoughBalance } from "@ledgerhq/ledger-wallet-framework/errors";
 import { getTransactionStatus } from "./getTransactionStatus";
 import { prepareTransaction } from "./prepareTransaction";
 import {
@@ -9,10 +10,14 @@ import {
   resolveTransparentUtxos,
 } from "./statusHelpers";
 import { TRANSPARENT_OUTPUT_DUST_THRESHOLD, ZIP317_MINIMUM_FEE } from "../logic/coin-selection";
-import { ZcashAmountBelowDustThreshold } from "../types/errors";
+import { ZcashAmountBelowDustThreshold, ZcashSendTooLarge } from "../types/errors";
 import type { BitcoinOutput, Transaction, ZcashAccount, ZcashTransferType } from "../types/bridge";
 import type { SpendableNote } from "../network/types";
-import { ZCASH_SHIELDED_SPENDABILITY_DELAY_BLOCKS } from "../constants";
+import {
+  ZCASH_MAX_IRONWOOD_ACTIONS,
+  ZCASH_MAX_TRANSPARENT_INPUTS,
+  ZCASH_SHIELDED_SPENDABILITY_DELAY_BLOCKS,
+} from "../constants";
 
 const T_ADDRESS = "t1b1Rbw2shhJkP6MCnCyxCPuyFedHrwKty8";
 const U_ADDRESS =
@@ -489,6 +494,122 @@ describe("getTransactionStatus, transparent-input flows", () => {
   });
 });
 
+describe("getTransactionStatus, bounded-selection shortfall (ZcashSendTooLarge)", () => {
+  const FEE = 10_000;
+
+  it.each(["transparent", "transparent-to-shielded"] as ZcashTransferType[])(
+    "resolves without an amount error for a %s send within the bounded max, from an account above the bound",
+    async transferType => {
+      const utxoCount = ZCASH_MAX_TRANSPARENT_INPUTS + 5;
+      const acc = account({ utxos: Array(utxoCount).fill(100_000) });
+      const boundedBalance = ZCASH_MAX_TRANSPARENT_INPUTS * 100_000;
+      const recipient = transferType === "transparent" ? T_ADDRESS : U_ADDRESS;
+      const tx = transaction({
+        transferType,
+        recipient,
+        amount: new BigNumber(boundedBalance - FEE),
+        zcashFee: new BigNumber(FEE),
+      });
+
+      const status = await getTransactionStatus(acc, tx);
+
+      expect(status.errors.amount).toBeUndefined();
+    },
+  );
+
+  it.each(["transparent", "transparent-to-shielded"] as ZcashTransferType[])(
+    "rejects a %s send between the bounded max and the full balance with ZcashSendTooLarge",
+    async transferType => {
+      const utxoCount = ZCASH_MAX_TRANSPARENT_INPUTS + 5;
+      const acc = account({ utxos: Array(utxoCount).fill(100_000) });
+      const boundedBalance = ZCASH_MAX_TRANSPARENT_INPUTS * 100_000;
+      const fullBalance = utxoCount * 100_000;
+      const recipient = transferType === "transparent" ? T_ADDRESS : U_ADDRESS;
+      // amount + FEE sits strictly between boundedBalance and fullBalance.
+      const tx = transaction({
+        transferType,
+        recipient,
+        amount: new BigNumber(boundedBalance),
+        zcashFee: new BigNumber(FEE),
+      });
+
+      const status = await getTransactionStatus(acc, tx);
+
+      expect(status.errors.amount).toBeInstanceOf(ZcashSendTooLarge);
+      expect(status.errors.amount).not.toBeInstanceOf(NotEnoughBalance);
+      expect(boundedBalance + FEE).toBeLessThanOrEqual(fullBalance);
+    },
+  );
+
+  it("keeps reporting NotEnoughBalance for a genuine shortfall, on an account below the bound", async () => {
+    const acc = account({ utxos: [10_000, 10_000, 10_000] }); // full balance 30_000, well below the bound
+    const tx = transaction({
+      amount: new BigNumber(100_000),
+      zcashFee: new BigNumber(FEE),
+    });
+
+    const status = await getTransactionStatus(acc, tx);
+
+    expect(status.errors.amount).toEqual(new NotEnoughBalance());
+    expect(status.errors.amount).not.toBeInstanceOf(ZcashSendTooLarge);
+  });
+
+  it("resolves without an amount error for a shielded send within the bounded max, from a pool above the bound", async () => {
+    const noteCount = ZCASH_MAX_IRONWOOD_ACTIONS + 5;
+    const acc = account({ ironwoodNotes: Array(noteCount).fill(100_000) });
+    const boundedTotal = ZCASH_MAX_IRONWOOD_ACTIONS * 100_000;
+    const selectedNotes = Array.from({ length: ZCASH_MAX_IRONWOOD_ACTIONS }, (_, i) =>
+      note(100_000, i),
+    );
+    const tx = transaction({
+      transferType: "shielded",
+      recipient: U_ADDRESS,
+      amount: new BigNumber(boundedTotal - FEE),
+      selectedNotes,
+      zcashFee: new BigNumber(FEE),
+    });
+
+    const status = await getTransactionStatus(acc, tx);
+
+    expect(status.errors.amount).toBeUndefined();
+  });
+
+  it("rejects a shielded send between the bounded and full pool with ZcashSendTooLarge, not the generic insufficiency error", async () => {
+    const noteCount = ZCASH_MAX_IRONWOOD_ACTIONS + 5;
+    const acc = account({ ironwoodNotes: Array(noteCount).fill(100_000) });
+    const boundedTotal = ZCASH_MAX_IRONWOOD_ACTIONS * 100_000;
+    const fullTotal = noteCount * 100_000;
+    const tx = transaction({
+      transferType: "shielded",
+      recipient: U_ADDRESS,
+      amount: new BigNumber(boundedTotal),
+      zcashFee: new BigNumber(FEE),
+    });
+
+    const status = await getTransactionStatus(acc, tx);
+
+    expect(status.errors.amount).toBeInstanceOf(ZcashSendTooLarge);
+    expect(status.errors.amount).not.toEqual(new Error("Insufficient shielded balance"));
+    expect(boundedTotal + FEE).toBeLessThanOrEqual(fullTotal);
+  });
+
+  it("keeps reporting the generic insufficiency error for a genuine shielded shortfall, on a pool below the bound", async () => {
+    const acc = account({ ironwoodNotes: [10_000, 10_000] }); // pool 20_000, well below the bound
+    const tx = transaction({
+      transferType: "shielded",
+      recipient: U_ADDRESS,
+      amount: new BigNumber(100_000),
+      selectedNotes: [note(20_000)],
+      zcashFee: new BigNumber(FEE),
+    });
+
+    const status = await getTransactionStatus(acc, tx);
+
+    expect(status.errors.amount).toEqual(new Error("Insufficient shielded balance"));
+    expect(status.errors.amount).not.toBeInstanceOf(ZcashSendTooLarge);
+  });
+});
+
 describe("getTransactionStatus, note-spending flows", () => {
   it("refuses to price anything before the shielded scan has run", async () => {
     const status = await getTransactionStatus(

libs/coin-modules/coin-zcash/src/bridge/getTransactionStatus.ts

@@ -3,18 +3,26 @@ import { NotEnoughBalance } from "@ledgerhq/ledger-wallet-framework/errors";
 import type { AccountBridge } from "@ledgerhq/types-live";
 import type { Transaction, TransactionStatus, ZcashAccount } from "../types/bridge";
 import { ZIP317_MINIMUM_FEE } from "../logic/coin-selection";
-import { ZcashAmountBelowDustThreshold, ZcashMemoTooLong } from "../types/errors";
+import {
+  ZcashAmountBelowDustThreshold,
+  ZcashMemoTooLong,
+  ZcashSendTooLarge,
+} from "../types/errors";
 import { ZCASH_MEMO_MAX_BYTES } from "../constants";
 import {
   computeAmountError,
   computeRecipientError,
+  hasBoundedTransparentShortfall,
   hasShieldedKey,
   isTransparentInputTransfer,
   isTransparentOutputDust,
   resolveTransparentUtxos,
 } from "./statusHelpers";
 import { getReservedNullifiers } from "./note-reservation";
-import { getSpendableIronwoodBalance } from "../logic/account/spendability";
+import {
+  getSpendableIronwoodBalance,
+  hasBoundedIronwoodShortfall,
+} from "../logic/account/spendability";
 
 const encoder = new TextEncoder();
 
@@ -54,7 +62,9 @@ function getTransparentInputStatus(
   if (tx.amount.lte(0) && !tx.useAllAmount) {
     errors.amount = new Error("Amount must be positive");
   } else if (totalSpent.gt(transparentBalance)) {
-    errors.amount = new NotEnoughBalance();
+    errors.amount = hasBoundedTransparentShortfall(account, tx, totalSpent)
+      ? new ZcashSendTooLarge()
+      : new NotEnoughBalance();
   } else if (tx.transferType === "transparent" && isTransparentOutputDust(tx.amount)) {
     errors.amount = new ZcashAmountBelowDustThreshold();
   }
@@ -99,7 +109,8 @@ export const getTransactionStatus: AccountBridge<
   // Shielded sends spend the Ironwood pool, so validate the amount against the
   // mature, unreserved figure -- the same one selection draws from, so the
   // status can never accept an amount selection cannot cover.
-  const poolBalance = getSpendableIronwoodBalance(account, getReservedNullifiers(account));
+  const reserved = getReservedNullifiers(account);
+  const poolBalance = getSpendableIronwoodBalance(account, reserved);
   const fee = transaction.zcashFee ?? new BigNumber(ZIP317_MINIMUM_FEE);
   const totalSpent = transaction.amount.plus(fee);
 
@@ -110,16 +121,20 @@ export const getTransactionStatus: AccountBridge<
   );
   if (recipientError) errors.recipient = recipientError;
 
-  const amountError = computeAmountError(transaction, totalSpent, poolBalance);
-  if (amountError) {
-    errors.amount = amountError;
-  } else if (
-    transaction.transferType === "shielded-to-transparent" &&
-    isTransparentOutputDust(transaction.amount)
-  ) {
-    // A shielded-to-transparent (z->t) recipient is also a transparent
-    // output, so it needs the same dust check as a t->t send.
-    errors.amount = new ZcashAmountBelowDustThreshold();
+  if (hasBoundedIronwoodShortfall(account, reserved, totalSpent)) {
+    errors.amount = new ZcashSendTooLarge();
+  } else {
+    const amountError = computeAmountError(transaction, totalSpent, poolBalance);
+    if (amountError) {
+      errors.amount = amountError;
+    } else if (
+      transaction.transferType === "shielded-to-transparent" &&
+      isTransparentOutputDust(transaction.amount)
+    ) {
+      // A shielded-to-transparent (z->t) recipient is also a transparent
+      // output, so it needs the same dust check as a t->t send.
+      errors.amount = new ZcashAmountBelowDustThreshold();
+    }
   }
 
   return {

libs/coin-modules/coin-zcash/src/bridge/mapping.ts

@@ -75,6 +75,14 @@ export async function mapTransparentInputs(
   );
 }
 
+/**
+ * Always exactly one requested output. The native builder adds at most one
+ * change output on top (craft.rs) -- coin-zcash itself never requests more
+ * than one, so the transparent/shielded output count this module can produce
+ * is capped at 2 regardless of account size, comfortably under either pool's
+ * device output ceiling. This is why input/spend selection is bounded but
+ * outputs are not: there is nothing to bound on the output side.
+ */
 export function mapOutputs(tx: Transaction): OutputRequestJs[] {
   return [
     {