test(abstract-utxo): Pearl transaction flow and live-node cross-validation

[manojkumar138]

Summary

Test coverage for the Pearl (Duplex) fixed-script lifecycle — 42 tests across two files:

File	Tests	What it establishes
transactionFlow.ts	27	the PSBT lifecycle is internally consistent
sandboxVectors.ts	15	our output agrees with a real pearld node

The split is deliberate. The first file builds transactions whose inputs reference txids that never existed, so it can only prove our libraries agree with themselves. The second checks against output captured from a live pearld 1.0.2 regtest node during sandboxing (coins-sandbox#898).

Scope — what is and isn't covered

Stage	Covered	How
Address generation	✅	derived + cross-validated against node scriptPubKeys
PSBT construction	⚠️	synthetic inputs (sha256 txids, not real UTXOs)
Unspent selection	❌	not exercised
Fee calculation	❌	values hardcoded; no fee-rate logic involved
Signing (2-of-3 taproot)	✅	real BIP-340 sigs, all three taptree leaves
Finalize / extract	✅	valid raw tx with a real txid
Transaction parsing	✅	parses the node's own raw transaction
Consensus validity	⚠️	structure matches what the node accepted; bytes never submitted
Broadcasting	❌	needs a live node or Pearl in the BitGo test env (CECHO-1802)

Single-input/single-output only; no dust boundaries, multi-recipient, or RBF.

What is genuinely node-verified

Transaction deserialization. Given the node's raw coinbase hex, our library computes the node's own txid 272e5b8a…d295 and round-trips byte-exactly. The node published both the bytes and the txid, so agreement is external.

Address encoding. For the node's real p2tr scriptPubKeys, our bech32m data part matches the node exactly — e.g. efxxurpnufae39uq0gcquq3msh27rhdau2rjh38mf9ndlhflk9js. Only HRP and checksum differ, as they must: the node ran regtest (rprl) and wasm-utxo has no Pearl regtest CoinName. Decoding restores the node's scriptPubKey exactly.

Witness shape. 4 stack items, 64-byte BIP-340 signatures with no sighash byte, leaf version 0xc0 — the shape the node accepted.

Taptree depth. Control block size is 1 + 32 + 32*depth, so it reveals each leaf's position. The measured depths confirm the TDD's taptree: user+bitgo shallow at depth 1, user+backup and backup+bitgo at depth 2. The node's 65-byte sample was a user+bitgo spend, which is why it saw depth 1.

⚠️ Known divergence — the sandbox taptree is not BitGo's taptree

The sandbox spends set the BIP-341 NUMS point as the internal key and produced 70-byte leaf scripts. BitGo's p2tr chain instead derives an internal key from the wallet keys and produces 68-byte leaves.

This is BitGo's house construction, not a Pearl bug — building the same input for btc yields a byte-identical witness, and the derived internal key is identical across both coins. But it has two consequences worth attention:

1. The sandbox's on-chain-verified addresses and signatures describe a different script than the SDK generates, so they cannot be asserted against our output.
2. BitGo's actual Pearl taptree has not yet been accepted by a pearld node. The sandbox proof does not transfer.

Three tests pin this so it cannot drift unnoticed, including one that fails if BitGo ever moves to a NUMS internal key (at which point the sandbox vectors become comparable).

Worth noting the TDD lists "NUMS internal key" as a chain parameter, which is misleading — it was a property of the sandbox's hand-rolled script. Anything else derived from that section may inherit the same assumption.

Three assumptions the tests corrected

The TDD's third taptree leaf is written backwards. It says [bitgo+backup]; wasm-utxo only accepts backup+bitgo and rejects the reverse with Could not find control block for leaf script.

sign()'s return value proves nothing. It returns the input index even for a key outside the chosen leaf. verifySignature is the source of truth; finalization enforces the leaf.

One test was vacuous until mutation testing caught it. "Rejects non-taproot chains" passed even with chain 30 substituted in, because chain 30 also throws without a signPath — a different error. It now supplies a signPath and matches /Unsupported script type/.

Mutation testing

I mutated each suite rather than trusting a green run. All caught:

Mutation	Result
reverse the third taptree leaf order	2 tests fail
put a taproot chain in the reject list	1 test fails
corrupt the node txid by one character	1 test fails
corrupt a node scriptPubKey byte	2 tests fail
wrong merkle depth for user+backup	1 test fails

Verification

abstract-utxo: 1594 passing (1552 → +42), zero failures. Prettier and eslint clean.

Next step to close the remaining gap

A regtest broadcast of an SDK-built transaction — that is the only thing that proves BitGo's Pearl taptree is consensus-valid. Blocked by the TDD's own risks: no public pearld Docker image, and ZK-PoW CGo crashes on Apple Silicon.

Related

• PR 1 feat(statics): add Pearl to statics #9347 (statics), PR 2 feat(abstract-utxo): add Pearl fixed-script wallet surface #9360 (abstract-utxo + sdk-coin-pearl), PR 3 feat(bitgo): register Pearl in the coin factory #9366 (coinFactory) — all merged
• TDD: Duplex/Pearl full onboarding

TICKET: CECHO-1806

🤖 Generated with Claude Code

[linear-code]

CECHO-1806