fix(abstract-utxo): check the descriptor policy spend rules when a descriptor wallet signs

[OttoAllmendinger]

Description

Follow-up to #9987 (stacked on it; this PR targets its branch and should be retargeted to master once #9987 merges).

#9987 makes the offline vault PoX-5 spend policy branch-aware, but it only covers the offline vault. A hot descriptor wallet signs through coin.signTransaction (transaction/signTransaction.ts), which only validated the descriptor policy and that each input matches a known descriptor. Nothing checked nLockTime, sequence, the principal preimage or the single-lockup-input rule before the SDK user key signed a PoX-5 exit, for late and early exits alike.

The check hangs off the descriptor policy instead of being called from the generic sign path:

• DescriptorValidationPolicy gets an optional validateSpend(psbt, descriptorMap): it throws when a spend of a descriptor the policy covers must not be signed, and does nothing for inputs it does not recognize. The policy combinators (every, some, eachOneOf) forward it to the policies they are made of.
• The PoX-5 lockup validator implements it with assertPox5SpendPolicy: exactly one lockup input; late exit: nLockTime at or above the unlock height and below 500,000,000, non-final sequence; early exit: nLockTime 0 and a single PSBT_IN_SHA256 record matching the descriptor stakerCommitment.
• signTransaction makes one generic call, policy.validateSpend?.(psbt, descriptorMap), and does not know about PoX-5. PoX-5 is named only where it already was (the lockup validators in validatePolicy.ts).
• Outside of prod getPolicyForEnv still accepts any descriptor, but it keeps the prod policy's validateSpend, so spends are checked in every environment.

PSBTs without a PoX-5 lockup input are unaffected. To let the descriptor policy use it, offlineVault/descriptor/pox5.ts moves to descriptor/pox5SpendPolicy.ts (no behavior change; the offline vault imports it from there). The offline vault still calls assertPox5SpendPolicy directly; moving it onto the policy hook is left for a follow-up.

Issue Number

Refs: SI-1971

Type of change

• Bug fix (non-breaking change which fixes an issue)

Behavior change to be aware of

A hot descriptor wallet now refuses to sign a PoX-5 lockup spend that violates the policy, where it signed it before. Wallet Platform builds late exits with nLockTime at the unlock height and a non-final sequence, and early exits with nLockTime 0 and the preimage, so correctly built exits are unaffected. This has not been run against the live matrix.

How Has This Been Tested?

modules/abstract-utxo:

• new test/unit/transaction/descriptor/signTransactionPox5.ts through coin.signTransaction with a descriptor wallet: late exit signs at the unlock height and is rejected below it or with a final sequence; early exit signs with nLockTime 0 and keeps the preimage, and is rejected with a non-zero nLockTime or a preimage the descriptor does not commit to. The policy of prod, adminProd, test and mock all check the spend. Without the validateSpend call the rejection tests fail.
• npx mocha --recursive test/unit/transaction test/unit/signTransaction.ts test/unit/offlineVault: 446 passing.

Early exit on the hot path is still blocked at the HSM, which rejects early-exit-key partial signatures (SI-2002), and that is not addressed here.

[linear-code]

SI-1971

[github-actions]

⚠️ Unit tests are failing on Node 26.x (Current release line, non-blocking). This is not an LTS version yet, so it does not block merge, but it signals an incompatibility to fix before Node 26.x becomes LTS.

View run