fix(utxo-lib): serialize Zcash Sapling valueBalance as signed int64

Zcash's Sapling valueBalance is a signed 64-bit field — it is negative
whenever value flows from the transparent pool into the shielded pool
(t->z shielding). The previous code in fromBufferV4 threw
UnsupportedTransactionError for any non-zero valueBalance, preventing
deposit-detection pipelines from computing txids for shielding
transactions even when the shielded bundle vectors are empty.

In toBufferV4 and hashForSignatureByNetwork the field was always written
as eight zero bytes (VALUE_INT64_ZERO), so even if parsing had succeeded
the re-serialized transaction would have had the wrong bytes and produced
a wrong txid.

Changes:
- ZcashTransaction gains a `saplingValueBalance: Buffer` field,
  initialised to VALUE_INT64_ZERO and preserved through clone().
- fromBufferV4 stores the raw 8-byte slice in saplingValueBalance instead
  of throwing when the field is non-zero. Non-empty shielded bundles still
  throw UnsupportedTransactionError via readEmptySaplingBundle, keeping
  the existing restriction against fully-shielded transactions.
- toBufferV4 writes tx.saplingValueBalance back verbatim, enabling exact
  round-tripping of fromBuffer→toBuffer/getId for any Sapling tx whose
  shielded bundle vectors are empty.
- hashForSignatureByNetwork uses tx.saplingValueBalance so sighash
  computation is also correct.
- Add test/bitgo/zcash/ZcashTransaction.ts with round-trip tests for a
  minimal Sapling v4 tx with valueBalance = -5.

Security: WCN-1961 / FND-002 (funds-loss, medium severity). A
custody pipeline calling fromBuffer(shieldingTx).getId() would
previously crash or silently produce a wrong txid; with this fix it
correctly round-trips for the case of empty shielded bundles, and
throws UnsupportedTransactionError for populated shielded bundles.

Ticket: WCN-1961
Session-Id: e7382333-471f-41ac-9109-8dbfc6acb8ea
Task-Id: ffe9c655-62ea-463d-a151-7d634b267c81

Author: davidkaplanbitgo

modules/utxo-lib/src/bitgo/zcash/ZcashBufferutils.ts

@@ -91,11 +91,10 @@ export function fromBufferV4<TNumber extends number | bigint>(
   }
 
   if (tx.isSaplingCompatible()) {
-    const valueBalance = bufferReader.readSlice(8);
-    if (!valueBalance.equals(VALUE_INT64_ZERO)) {
-      /* istanbul ignore next */
-      throw new UnsupportedTransactionError(`valueBalance must be zero`);
-    }
+    // valueBalance is a signed int64; negative for t->z shielding transactions.
+    // Store raw bytes so toBuffer/getId can round-trip the tx without mutation.
+    // https://github.com/zcash/zcash/blob/v4.5.1/src/primitives/transaction.h#L283
+    tx.saplingValueBalance = bufferReader.readSlice(8);
 
     // https://github.com/zcash/zcash/blob/v4.5.1/src/primitives/transaction.h#L863
     readEmptySaplingBundle(bufferReader);
@@ -167,7 +166,7 @@ export function toBufferV4<TNumber extends number | bigint>(
   }
 
   if (tx.isSaplingCompatible()) {
-    bufferWriter.writeSlice(VALUE_INT64_ZERO);
+    bufferWriter.writeSlice(tx.saplingValueBalance ?? VALUE_INT64_ZERO);
     bufferWriter.writeVarInt(0); // vShieldedSpendLength
     bufferWriter.writeVarInt(0); // vShieldedOutputLength
   }

modules/utxo-lib/src/bitgo/zcash/ZcashTransaction.ts

@@ -114,6 +114,10 @@ export class ZcashTransaction<TNumber extends number | bigint = number> extends
   // Block height after which this transactions will expire, or 0 to disable expiry
   expiryHeight = 0;
   consensusBranchId: number;
+  // Raw 8-byte little-endian signed int64 valueBalance field for Sapling v4 txs.
+  // Negative when value flows from the transparent pool into the shielded pool
+  // (t->z shielding). Stored verbatim so toBuffer/getId round-trip correctly.
+  saplingValueBalance: Buffer = VALUE_INT64_ZERO;
 
   constructor(public network: ZcashNetwork, tx?: ZcashTransaction<bigint | number>, amountType?: 'bigint' | 'number') {
     super(network, tx, amountType);
@@ -123,6 +127,7 @@ export class ZcashTransaction<TNumber extends number | bigint = number> extends
       this.overwintered = tx.overwintered;
       this.versionGroupId = tx.versionGroupId;
       this.expiryHeight = tx.expiryHeight;
+      this.saplingValueBalance = tx.saplingValueBalance;
 
       if (tx.consensusBranchId !== undefined) {
         consensusBranchId = tx.consensusBranchId;
@@ -378,7 +383,7 @@ export class ZcashTransaction<TNumber extends number | bigint = number> extends
     bufferWriter.writeUInt32(this.locktime);
     bufferWriter.writeUInt32(this.expiryHeight);
     if (this.isSaplingCompatible()) {
-      bufferWriter.writeSlice(VALUE_INT64_ZERO);
+      bufferWriter.writeSlice(this.saplingValueBalance);
     }
     bufferWriter.writeInt32(hashType);
 

modules/utxo-lib/test/bitgo/zcash/ZcashTransaction.ts

@@ -0,0 +1,43 @@
+import * as assert from 'assert';
+import { networks } from '../../../src';
+import { ZcashTransaction } from '../../../src/bitgo';
+
+// Minimal Sapling v4 transaction with valueBalance = -5 (t->z shielding).
+// Built as: header(0x80000004) | versionGroupId(0x892F2085) | vin(0) | vout(0) |
+//           locktime(0) | expiryHeight(0) | valueBalance(-5 as int64le) |
+//           vSpendsSapling(0) | vOutputsSapling(0) | vJoinSplit(0)
+const SHIELDING_TX_HEX = '0400008085202f8900000000000000000000fbffffffffffffff000000';
+
+describe('ZcashTransaction (Sapling valueBalance)', function () {
+  describe('round-trip for t->z shielding tx (negative valueBalance)', function () {
+    it('parses without throwing', function () {
+      const tx = ZcashTransaction.fromBuffer(Buffer.from(SHIELDING_TX_HEX, 'hex'), false, 'number', networks.zcash);
+      // saplingValueBalance stores raw bytes; -5 in int64le is fb ff ff ff ff ff ff ff
+      assert.strictEqual(tx.saplingValueBalance.toString('hex'), 'fbffffffffffffff');
+    });
+
+    it('re-serializes to the same hex (toBuffer round-trip)', function () {
+      const tx = ZcashTransaction.fromBuffer(Buffer.from(SHIELDING_TX_HEX, 'hex'), false, 'number', networks.zcash);
+      assert.strictEqual(tx.toBuffer().toString('hex'), SHIELDING_TX_HEX);
+    });
+
+    it('computes getId() without throwing', function () {
+      const tx = ZcashTransaction.fromBuffer(Buffer.from(SHIELDING_TX_HEX, 'hex'), false, 'number', networks.zcash);
+      // Just verify it does not throw; the exact txid is deterministic from the hex above.
+      assert.doesNotThrow(() => tx.getId());
+    });
+
+    it('clones correctly', function () {
+      const tx = ZcashTransaction.fromBuffer(Buffer.from(SHIELDING_TX_HEX, 'hex'), false, 'number', networks.zcash);
+      const cloned = tx.clone();
+      assert.strictEqual(cloned.toBuffer().toString('hex'), SHIELDING_TX_HEX);
+    });
+  });
+
+  describe('round-trip for transparent tx (zero valueBalance)', function () {
+    it('saplingValueBalance defaults to all-zero bytes', function () {
+      const tx = new ZcashTransaction(networks.zcash);
+      assert.strictEqual(tx.saplingValueBalance.toString('hex'), '0000000000000000');
+    });
+  });
+});