feat(abstract-utxo): add zec shielded psbt and recipient resolution support

Ticket: CSHLD-1640

Author: veetragjain

modules/abstract-utxo/src/impl/zec/index.ts

@@ -1,2 +1,3 @@
 export * from './zec';
+export * from './recipients';
 export * from './tzec';

modules/abstract-utxo/src/impl/zec/recipients.ts

@@ -0,0 +1,125 @@
+/**
+ * @prettier
+ */
+import { fixedScriptWallet } from '@bitgo/wasm-utxo';
+import { Triple } from '@bitgo/sdk-core';
+
+import { getReplayProtectionPubkeys } from '../../transaction/fixedScript/replayProtection';
+
+/**
+ * How a recipient parsed from a Zcash PSBT is spent.
+ *
+ * The decode-side counterpart of utxo-core's `buildTransaction/zcash.ts` `ZcashDestination` on
+ * the build side: a shielded recipient is an Orchard/Ironwood output stored in the v6 (Ironwood)
+ * PSBT's orchard PCZT, and everything else is an ordinary transparent output. A transparent
+ * output resolved from a Unified Address carries that original UA (`zcashUnifiedTransparent`), a
+ * plain address does not.
+ */
+export type PsbtRecipientDestination =
+  | {
+      kind: 'zcashShielded';
+      /**
+       * The Unified Address the output was addressed to — the original multi-receiver UA the
+       * client passed when the PSBT stores one verbatim, otherwise a re-encoded single-receiver
+       * Orchard UA.
+       */
+      unifiedAddress: string;
+    }
+  | {
+      kind: 'zcashUnifiedTransparent';
+      /** The original Unified Address the transparent receiver was resolved from. */
+      unifiedAddress: string;
+    }
+  | { kind: 'transparent' };
+
+/** A recipient resolved from a decoded Zcash PSBT's external outputs. */
+export interface PsbtRecipient {
+  /** Amount in satoshis. */
+  amount: bigint;
+  /**
+   * The recipient address. For a shielded output this is the Unified Address the output was
+   * addressed to — the original multi-receiver UA when the PSBT stores one verbatim, otherwise a
+   * re-encoded single-receiver Orchard UA. For a transparent output it is the original Unified
+   * Address when one was stored, else the decoded transparent address.
+   */
+  address: string;
+  /**
+   * Raw receiver bytes: the 43-byte Orchard/Ironwood receiver for a shielded output, the
+   * scriptPubKey for a transparent one.
+   */
+  script: Uint8Array;
+  /**
+   * The original Unified Address the client supplied for this recipient, when the PSBT stores
+   * one: the v6 (Ironwood) PCZT for a shielded output, the transparent-output proprietary
+   * key-value map for a v4 transparent output. `undefined` when the recipient was built from a
+   * plain address (or the single-receiver UA re-encoding is byte-identical for a shielded
+   * output).
+   */
+  unifiedAddress?: string;
+  destination: PsbtRecipientDestination;
+}
+
+export type ResolvePsbtRecipientsOptions = {
+  /**
+   * Custom change wallet xpubs, when the transaction spends to a custom change wallet. Outputs
+   * matching these keys are classified as change, not recipients — matching how
+   * `explainPsbtWasm` treats them.
+   */
+  customChangeXpubs?: Triple<string>;
+};
+
+/**
+ * Resolve the recipient list of a decoded Zcash PSBT (v4 Sapling-shaped or v6 Ironwood).
+ *
+ * Mirrors the recipient resolution of wallet-platform's utxo-core `buildTransaction` in the
+ * decode direction: every non-wallet, non-custom-change output with a resolvable address is a
+ * recipient. A shielded output parses with `isShielded: true`, its `script` being the raw
+ * 43-byte receiver; when the build stored the client's original Unified Address (the v6 PCZT for
+ * shielded outputs, the transparent-output proprietary key-value map for v4), both the parsed
+ * address and `unifiedAddress` report it verbatim. Opaque outputs with no address (e.g.
+ * OP_RETURN) are skipped, as they carry no recipient.
+ */
+export function resolvePsbtRecipients(
+  psbt: fixedScriptWallet.ZcashBitGoPsbt,
+  walletKeys: fixedScriptWallet.RootWalletKeys,
+  opts: ResolvePsbtRecipientsOptions = {}
+): PsbtRecipient[] {
+  const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, {
+    replayProtection: { publicKeys: getReplayProtectionPubkeys('zec') },
+  });
+  const customChangeOutputs = opts.customChangeXpubs
+    ? psbt.parseOutputsWithWalletKeys(opts.customChangeXpubs)
+    : undefined;
+
+  const recipients: PsbtRecipient[] = [];
+  parsed.outputs.forEach((output, i) => {
+    // Wallet-owned (change) outputs.
+    if (output.scriptId !== null) {
+      return;
+    }
+    // Outputs owned by the custom change wallet, if one was supplied.
+    if (customChangeOutputs?.[i]?.scriptId != null) {
+      return;
+    }
+    // Opaque outputs (e.g. OP_RETURN) carry no recipient address.
+    if (output.address === null) {
+      return;
+    }
+    // The original client-passed Unified Address, stored verbatim in the PSBT's key-value
+    // pairs: the orchard PCZT for a shielded output (parsed `address` reports it in full), the
+    // transparent-output proprietary map for a v4 transparent output.
+    const unifiedAddress = output.isShielded ? output.address : psbt.transparentOutputUnifiedAddress(i) ?? undefined;
+    recipients.push({
+      amount: output.value,
+      address: output.address,
+      script: output.script,
+      unifiedAddress,
+      destination: output.isShielded
+        ? { kind: 'zcashShielded', unifiedAddress: output.address }
+        : unifiedAddress
+        ? { kind: 'zcashUnifiedTransparent', unifiedAddress }
+        : { kind: 'transparent' },
+    });
+  });
+  return recipients;
+}

modules/abstract-utxo/src/impl/zec/zec.ts

@@ -1,13 +1,21 @@
 /**
  * @prettier
  */
-import { address as wasmAddress, fixedScriptWallet, hasPsbtMagic, isWasmUtxoError } from '@bitgo/wasm-utxo';
+import {
+  address as wasmAddress,
+  fixedScriptWallet,
+  hasPsbtMagic,
+  isWasmUtxoError,
+  zcashAddress as wasmZcashAddress,
+} from '@bitgo/wasm-utxo';
 import { BitGoBase, ExtraPrebuildParamsOptions, Wallet } from '@bitgo/sdk-core';
 
 import { AbstractUtxoCoin } from '../../abstractUtxoCoin';
 import { stringToBufferTryFormats } from '../../transaction/decode';
 import { UtxoCoinName } from '../../names';
 
+import { resolvePsbtRecipients, ResolvePsbtRecipientsOptions, PsbtRecipient } from './recipients';
+
 /**
  * Parse `address` as a ZIP-316 Unified Address for `network`, or return `undefined` if it isn't
  * one (malformed, wrong network, or not bech32m-shaped at all).
@@ -74,7 +82,10 @@ export class Zec extends AbstractUtxoCoin {
    * implementation would.
    */
   override resolveOutputScript(address: string, unifiedRecipientPreference?: string): Uint8Array {
-    return wasmAddress.toOutputScriptWithCoin(address, this.name, unifiedRecipientPreference === 'shielded');
+    if (unifiedRecipientPreference === 'shielded') {
+      return wasmZcashAddress.toShieldedReceiverWithCoin(address, this.name);
+    }
+    return wasmAddress.toOutputScriptWithCoin(address, this.name);
   }
 
   /**
@@ -90,7 +101,10 @@ export class Zec extends AbstractUtxoCoin {
     try {
       return fixedScriptWallet.ZcashBitGoPsbt.fromBytes(buffer, this.name as 'zec' | 'tzec');
     } catch (e) {
-      if (isWasmUtxoError(e)) {
+      // `ZcashBitGoPsbt.fromBytes` signals v6 (Ironwood) bytes with a plain Error (not a
+      // WasmUtxoError) telling the caller to use `ZcashIronwoodBitGoPsbt.fromBytes` instead —
+      // see its doc comment. Fall back for that message as well as wasm-layer errors.
+      if (isWasmUtxoError(e) || (e instanceof Error && e.message.includes('v6 (Ironwood)'))) {
         return fixedScriptWallet.ZcashIronwoodBitGoPsbt.fromBytes(buffer, this.name as 'zec' | 'tzec');
       }
       throw e;
@@ -108,4 +122,22 @@ export class Zec extends AbstractUtxoCoin {
     }
     return this.decodeTransaction(string);
   }
+
+  /**
+   * Decode a Zcash PSBT (v4 Sapling-shaped or v6 Ironwood) and resolve its recipient list.
+   * The decode-side counterpart of the wallet-platform build path's recipient resolution:
+   * shielded outputs resolve to their single-receiver Orchard Unified Address, transparent
+   * outputs to their transparent address. Change and custom-change outputs are excluded.
+   */
+  resolveRecipientsFromPsbt(
+    input: Buffer | string,
+    walletKeys: fixedScriptWallet.RootWalletKeys,
+    opts: ResolvePsbtRecipientsOptions = {}
+  ): PsbtRecipient[] {
+    const psbt = this.decodeTransaction(input);
+    if (!(psbt instanceof fixedScriptWallet.ZcashBitGoPsbt)) {
+      throw new Error('expected a Zcash PSBT');
+    }
+    return resolvePsbtRecipients(psbt, walletKeys, opts);
+  }
 }

modules/abstract-utxo/test/unit/impl/zec/shieldedPrebuildAndSign.ts

@@ -0,0 +1,91 @@
+import * as assert from 'assert';
+
+import nock = require('nock');
+import { common } from '@bitgo/sdk-core';
+import { getSeed } from '@bitgo/sdk-test';
+import { fixedScriptWallet } from '@bitgo/wasm-utxo';
+
+import { getUtxoCoin, defaultBitGo } from '../../util';
+import { getDefaultWasmWalletKeys, keychainsBase58 } from '../../util/keychains';
+import { Zec } from '../../../../src/impl/zec';
+/**
+ * Exercises every client-side flow that runs BEFORE verifyTransaction/signTransaction on a
+ * shielded (v6 Ironwood) prebuild: prebuild post-processing, explanation, and recipient
+ * resolution. Each of them must decode the v6 PSBT and resolve the shielded recipient without
+ * error.
+ */
+describe('Zec shielded pre-verify flows (v6 Ironwood PSBT)', function () {
+  const zec = getUtxoCoin('tzec');
+  const bgUrl = common.Environments[defaultBitGo.getEnv()].uri;
+  const { walletKeys } = getDefaultWasmWalletKeys();
+
+  const keyDocumentObjects = keychainsBase58.map((keychain, keyIdx) => {
+    return {
+      id: getSeed(keychain.pub).toString('hex'),
+      pub: keychain.pub,
+      source: ['user', 'backup', 'bitgo'][keyIdx],
+      coinSpecific: {},
+    };
+  });
+  const IRONWOOD_RECEIVER = Buffer.from(
+    'd632c28aa0831d671be17709a42c9627e2eb687a1b2a55768ea470c9bae7499cd0bd3d0eb0484e307236b5',
+    'hex'
+  );
+  let unifiedAddress: string;
+
+  before(function () {
+    unifiedAddress = fixedScriptWallet.ZcashUnifiedAddress.encodeOrchardReceiver(
+      new Uint8Array(IRONWOOD_RECEIVER),
+      'tzec'
+    );
+  });
+
+  function buildShieldedV6PrebuildHex(): string {
+    const psbt = fixedScriptWallet.ZcashIronwoodBitGoPsbt.createEmpty('tzec', walletKeys, { blockHeight: 4200000 });
+    psbt.addWalletInput({ txid: '11'.repeat(32), vout: 0, value: 100000n }, walletKeys, {
+      scriptId: { chain: 0, index: 0 },
+    });
+    psbt.addWalletOutput(walletKeys, { chain: 1, index: 0, value: 90000n });
+    psbt.addShieldedOutputs(
+      [{ recipient: new Uint8Array(IRONWOOD_RECEIVER), amount: 5000n, unifiedAddress }],
+      new Uint8Array(32)
+    );
+    return Buffer.from(psbt.serialize()).toString('hex');
+  }
+
+  afterEach(function () {
+    nock.cleanAll();
+  });
+
+  it('sendMany recipient validation accepts the unified address', function () {
+    zec.checkRecipient({ address: unifiedAddress, amount: '5000' });
+  });
+
+  it('postProcessPrebuild decodes the v6 psbt and re-encodes it unchanged', async function () {
+    const prebuildHex = buildShieldedV6PrebuildHex();
+    nock(bgUrl).get('/api/v2/tzec/public/block/latest').reply(200, { height: 4200000 });
+    const prebuild = await zec.postProcessPrebuild({ txHex: prebuildHex, txInfo: {} });
+    assert.match(prebuild.txHex as string, /^70736274/); // PSBT magic preserved
+    const decoded = zec.decodeTransaction(prebuild.txHex as string);
+    assert.ok(decoded instanceof fixedScriptWallet.ZcashIronwoodBitGoPsbt);
+  });
+
+  it('explainTransaction decodes the v6 psbt and resolves the shielded recipient', async function () {
+    const explained = await zec.explainTransaction({
+      txHex: buildShieldedV6PrebuildHex(),
+      pubs: [keyDocumentObjects[0].pub, keyDocumentObjects[1].pub, keyDocumentObjects[2].pub],
+    });
+    assert.strictEqual(explained.outputs.length, 1);
+    assert.strictEqual(explained.outputs[0].address, unifiedAddress);
+    assert.strictEqual(explained.outputs[0].amount.toString(), '5000');
+    assert.strictEqual(explained.changeOutputs.length, 1);
+  });
+
+  it('resolveRecipientsFromPsbt resolves the shielded recipient with its original UA', function () {
+    const recipients = (zec as Zec).resolveRecipientsFromPsbt(buildShieldedV6PrebuildHex(), walletKeys);
+    assert.strictEqual(recipients.length, 1);
+    assert.strictEqual(recipients[0].destination.kind, 'zcashShielded');
+    assert.strictEqual(recipients[0].unifiedAddress, unifiedAddress);
+    assert.strictEqual(Buffer.from(recipients[0].script).toString('hex'), IRONWOOD_RECEIVER.toString('hex'));
+  });
+});