Transaction V1 Plan

This plan defines the transaction-builder requirements for Kaspa x402 batch-settlement support. It is intentionally executable as a checklist: no mainnet builder should ship until each production path has a vector with a serialized transaction body/projection, transaction id, hash, sighash input, compute budget, and fee accounting.

Batch claim and batch refund have reference transaction-v1 vectors under vectors/tx-v1/. The transaction-v1 vectors are cross-validated against kaspa-consensus-core 2.0.1 at commit ef1a093bcf8560fe05221b56f0c896f97e7d8d77 by npm run validate:tx-v1-consensus. In those vectors, serializedTransaction is the deterministic transaction hash preimage/projection, not a submit-ready RPC transaction payload. The mass field is contextual storage mass and must not be replaced with serialized-size estimates.

Canonical transaction-v1 semantics used by the vectors:

• txid rest_digest excludes signature scripts, payload, mass, and compute budget;
• transaction hash includes v1 compute budget and the v1 mass field;
• v1 sighash excludes compute budget;
• empty payload txid uses the canonical PayloadDigest empty-payload digest, while empty native sighash payload uses the zero hash;
• storage mass and estimated serialized size are calculated by canonical consensus code.

Batch Settlement Claim

• Input: the active escrow outpoint, using kaspa-x402-escrow-v1 script public key.
• Subnetwork/gas: native subnetwork only, with gas 0.
• Signature script: push(serverSig(65)) || push(voucherSig(64)) || push(amount_le64) || selector(0) || push(redeemScript).
• Outputs: exactly two outputs.
• Output covenant bindings: not used in the current script-level profile. Every output covenant field is absent/null.
• Output 0: server claim output. Its value must be less than or equal to the voucher amount, and its serialized script public key must hash to the payout hash embedded in the escrow script.
• Output 1: continuation escrow output. Its script public key must equal the spent escrow script public key and its value must be positive.
• Remainder rule: output 1 must be at least inputAmount - voucherAmount. Reference builders preserve the stronger direct-mode remainder inputAmount - claimAmount so an over-authorized voucher ceiling does not consume uncharged value.
• Fee rule: claim transaction fees come out of the server output, never the continuation output.
• Script-unit estimate: 200544.
• Compute budget: 20, derived from Toccata's compute_budget * 10000 + 9999 allowance.

Batch Settlement Refund

• Input: any refundable escrow outpoint for the channel.
• Subnetwork/gas: native subnetwork only, with gas 0.
• Signature script: push(clientSig(65)) || selector(1) || push(redeemScript).
• Output: exactly one refund output whose serialized script public key hashes to the refund hash embedded in the escrow script.
• Output covenant bindings: not used in the current script-level profile. Every output covenant field is absent/null.
• Lock rule: transaction lock time must be greater than or equal to the escrow timeout DAA score, and the input sequence must be 0.
• Fee rule: refund fees come out of the refunded value.
• Script-unit estimate: 100000.
• Compute budget: 10, derived from Toccata's compute_budget * 10000 + 9999 allowance.

Implemented Vectors

• batch-claim-transaction-body - covered by vectors/tx-v1/batch-claim.json
• batch-refund-transaction-body - covered by vectors/tx-v1/batch-refund.json
• transaction id for each transaction body
• transaction hash for each transaction body
• sighash preimage and digest for every signed input path
• compute budget for every covenant-backed path
• script-unit estimate for every covenant-backed path

Source: /spec/transaction-v1-plan.md