fix(utxo-lib): serialize Zcash Sapling valueBalance as signed int64 - #9454
Draft
bitgo-ai-agent-dev[bot] wants to merge 1 commit into
Draft
fix(utxo-lib): serialize Zcash Sapling valueBalance as signed int64#9454bitgo-ai-agent-dev[bot] wants to merge 1 commit into
bitgo-ai-agent-dev[bot] wants to merge 1 commit into
Conversation
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
Contributor
ralph-bitgo
Bot
force-pushed
the
WCN-1961-zcash-negative-valueBalance
branch
from
August 7, 2026 20:10
c561d96 to
3f508c3
Compare
bitgo-ai-agent-dev
Bot
force-pushed
the
WCN-1961-zcash-negative-valueBalance
branch
from
August 7, 2026 20:11
3f508c3 to
9d7a86c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
saplingValueBalance: Bufferfield toZcashTransaction(initialized to all-zero bytes, copied throughclone())fromBufferV4now stores the raw 8-bytevalueBalancefield intx.saplingValueBalanceinstead of throwingUnsupportedTransactionErrorwhen the value is non-zero; non-empty shielded spend/output vectors still throw (unchanged restriction)toBufferV4writestx.saplingValueBalanceback verbatim (was hardcoded toVALUE_INT64_ZERO), enabling exact round-tripping for any Sapling tx with empty shielded bundleshashForSignatureByNetworkusestx.saplingValueBalanceso sighash computation is also correcttest/bitgo/zcash/ZcashTransaction.tswith round-trip tests for a minimal Sapling v4 tx withvalueBalance = -5Why
valueBalanceis a signed 64-bit field — it is negative whenever value flows from the transparent pool into the shielded pool (t→z shielding). These are ordinary, consensus-valid mainnet transactions.UnsupportedTransactionError("valueBalance must be zero")infromBufferand always wrote zeros intoBufferandhashForSignature. This meant any custody or deposit-detection pipeline callingTransaction.fromBuffer(rawTx, zcash).getId()on a shielding transaction would crash, leaving funds stranded in the processing pipeline with no way to confirm receipt.fromBuffer→toBuffer/getIdas long as the shielded bundle vectors are empty (the case where our lib can faithfully represent the tx bytes). Populated shielded bundles still throwUnsupportedTransactionErrorviareadEmptySaplingBundle, preserving the existing restriction on fully-shielded transactions.Test plan
test/bitgo/zcash/ZcashTransaction.ts: parses a Sapling v4 tx withvalueBalance = -5, verifiessaplingValueBalanceraw bytes, round-tripstoBuffer, callsgetId()without throwing, and verifiesclone()preserves the fieldhashZip0244.tstest vectors continue to pass (zerovalueBalancepath is unchanged)Ticket: WCN-1961