Merge pull request #35 from engineeredsoftware/v30/gate-3-bitcoin-taproot-psbt-fee-rigor

V30 Gate 3: Bitcoin Taproot PSBT Fee Rigor

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -81,6 +81,7 @@ jobs:
             node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
             node scripts/check-v30-gate1-roadmap-and-gating.mjs --skip-branch-check
             node scripts/check-v30-gate2-protocol-package-api-boundaries.mjs --skip-branch-check
+            node scripts/check-v30-gate3-bitcoin-taproot-psbt-fee-rigor.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30.md

@@ -183,7 +183,9 @@ The V30 domain model extends V29 operationally:
 - `SettlementUnlock`: BTC fee proof, BTD range/read-license/right transfer, paid disclosure decision, delivery admission, and reconciliation state.
 - `BtcFeeQuote`: deterministic BTC fee quote with quote root, measurement root, purpose, network, sats, pricing version, expiration, and lifecycle state.
 - `WalletSignerSessionRecovery`: signer-session posture proving whether the Reader wallet can sign a PSBT without server custody.
-- `BtcFeeOperationPosture`: operational state over quote, signer, PSBT, broadcast, finality, replacement, reorg, failure, and blocked readiness.
+- `BtcFeeNetworkPolicy`: proof-rooted environment and network admission posture over local, staging-testnet, and production-mainnet value-bearing BTC settlement.
+- `BtcFeeTaprootPsbtPosture`: proof-rooted Taproot commitment, script path, PSBT handoff, broadcast observation, replacement, reorg, and finality posture.
+- `BtcFeeOperationPosture`: operational state over quote, signer, network policy, Taproot/script posture, PSBT, broadcast, finality, replacement, reorg, failure, and blocked readiness.
 - `BtdAssetPackMintReceipt`: typed receipt binding AssetPack id, BTD range, depositor ownership, source-safe preview root, mint measurement root, settlement conservation root, and ledger projection root.
 - `BtdReadReceipt`: typed receipt binding Reader, read request, accepted Need, Finding Fits result root, source-safe preview root, paid/unpaid disclosure state, read-right state, and delivery admission.
 - `BtdRightsTransferReceipt`: typed receipt binding BTC fee finality, BTD owner or license transition, range projection, paid unlock, delivery proof, and reconciliation status.
@@ -317,7 +319,9 @@ The operation model must contain:
 - quote lifecycle: quoted, accepted, expired, superseded, and failed;
 - deterministic quote root over quote id, purpose, network, sats, measurement root, issue time, and expiration;
 - signer recovery: missing, prepared authorization required, stored authorization requiring live reconnect, expired, revoked, failed, network mismatch, capability missing, server-custody rejected, or live authorized;
-- PSBT handoff: accepted quote prepares a PSBT; the wallet signs; the signed PSBT broadcasts;
+- network policy: local and staging-testnet may exercise value-bearing BTC settlement for QA; production-mainnet value-bearing settlement remains blocked until explicit operational approval is attached and proof-rooted;
+- Taproot/script posture: Bitcoin fee and anchor paths default to Taproot, name the admitted script path, and expose non-Taproot posture as audit evidence rather than silently treating it as equivalent;
+- PSBT handoff: accepted quote prepares an unsigned PSBT; the wallet signs; the signed PSBT is ready for broadcast; broadcast and finality observations are separate states;
 - finality states: prepared, signed, broadcast, confirmed, replaced, reorged, and failed;
 - blocked-readiness receipts naming the blocker id, summary, required action, quote id, wallet session id, receipt id, and no-server-custody posture;
 - Terminal read rows and metrics for state, network, sats, confirmations, quote root, wallet session, payer wallet, PSBT handoff, txid, server custody, and next action.

BITCODE_SPEC_V30_DELTA.md

@@ -116,6 +116,22 @@ Closure acceptance:
 - testnet/mainnet distinction is policy-enforced and proof-rooted;
 - focused BTD/API tests prove fee lifecycle and blocked-readiness behavior.
 
+Gate 3 implementation centers these semantics in
+`packages/btd/src/btc-fee-operation.ts` and `packages/btd/src/bitcoin-fees.ts`.
+`BtcFeeNetworkPolicy` admits local and staging-testnet fee operation while
+blocking value-bearing production-mainnet settlement unless explicit operational
+approval is attached. `BtcFeeTaprootPsbtPosture` names the Bitcoin commitment
+method, script path, PSBT handoff state, and broadcast observation state so
+prepared, signed, broadcast, confirmed, replaced, reorged, and failed receipts
+remain distinguishable. Signed receipts require a signed PSBT, quote timestamps
+must be usable for PSBT preparation, and server-custody signer sessions remain
+fail-closed before handoff.
+
+Gate 3 evidence is covered by
+`packages/btd/__tests__/btc-fee-operation.test.ts`,
+`packages/api/src/routes/__tests__/btd-crypto.test.ts`, and
+`scripts/check-v30-gate3-bitcoin-taproot-psbt-fee-rigor.mjs`.
+
 ### Gate 4: BTD AssetPack Mint And Read Receipts
 
 Gate 4 creates typed BTD receipt boundaries.

BITCODE_SPEC_V30_NOTES.md

@@ -90,6 +90,24 @@ standalone demonstration imports.
 3. **Gate 3: Bitcoin Taproot PSBT Fee Rigor**
    - Harden BTC fee quote, signer recovery, PSBT, Taproot/script posture, broadcast, replacement, reorg, finality, and testnet/mainnet boundaries.
 
+## Gate 3 Bitcoin Taproot PSBT fee rigor notes
+
+Gate 3 makes BTC fee operation inspectable before any later BTD receipt,
+projection, or interface depends on it. `BtcFeeOperationPosture` now carries the
+network policy, Taproot/PSBT posture, PSBT handoff state, and broadcast
+observation state beside quote, signer, receipt, and blocked-readiness data.
+
+The network policy deliberately treats staging-testnet as the operational lane
+for current QA. Production-mainnet value-bearing settlement is not admitted by
+default. It must carry explicit operational approval before the posture leaves
+blocked-readiness, and that approval state contributes to the policy proof root.
+
+The PSBT path distinguishes prepared unsigned PSBT, signed ready-to-broadcast
+PSBT, broadcast submission, finality observation, replacement/reorg repair, and
+failure. Signed receipt advancement requires a signed PSBT. Broadcast,
+confirmed, replaced, and reorged observations require transaction id evidence.
+Server-custody signer posture remains rejected before PSBT handoff.
+
 4. **Gate 4: BTD AssetPack Mint And Read Receipts**
    - Make BTD mint, read, and rights-transfer receipts typed, proof-rooted, stored, streamed, and source-safe.
 

BITCODE_SPEC_V30_PARITY_MATRIX.md

@@ -56,7 +56,7 @@ No `_legacy/` source is active source truth.
 | Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V30.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v30/gate-1-roadmap-and-gating` | drafted | V30 family validates in draft mode over active V29 and `check:v30-gate1` passes. |
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V29 active, V30 draft, and coherent V31-V37 responsibilities. |
 | Protocol package API boundaries | Gate 2 | `packages/btd/src/api-boundaries.ts`, `packages/api/src/routes/btd-crypto.ts`, package READMEs/tests | drafted | Shared Protocol/BTD objects have package-owned builders, parsers, validators, JSON-safe serializers, and tests. |
-| Bitcoin Taproot PSBT fee rigor | Gate 3 | BTD fee/signer/PSBT primitives, API route adapters, tests | pending | BTC fee and signer states are typed, testnet/mainnet-safe, no-custody, and proof-rooted. |
+| Bitcoin Taproot PSBT fee rigor | Gate 3 | `packages/btd/src/btc-fee-operation.ts`, `packages/btd/src/bitcoin-fees.ts`, BTD/API tests, gate checker | drafted | BTC fee and signer states are typed, testnet/mainnet-safe, no-custody, Taproot/PSBT aware, and proof-rooted. |
 | BTD AssetPack mint/read receipts | Gate 4 | BTD receipt primitives, asset-pack postprocess, harness evidence, Terminal/API readback | pending | Mint, read, and rights-transfer receipts bind BTD range, preview, paid unlock, delivery, and ledger projection. |
 | Testnet ledger projection hardening | Gate 5 | BTD reconciliation, Supabase readback, object-storage evidence, repair tests | pending | Ledger/database/object-storage projections are synchronized or blocked with deterministic repair posture. |
 | Source-to-shares proof cleanup | Gate 6 | BTD/source-to-shares proof primitives, settlement conservation tests | pending | Measurement contribution, fee allocation, zero-cell/refit tail, and conservation invariants are testable. |
@@ -112,6 +112,26 @@ No `_legacy/` source is active source truth.
 - Gate 2 does not introduce bridge chain-of-record behavior.
 - Gate 2 does not admit value-bearing mainnet settlement.
 - Gate 2 does not remove existing API route persistence adapters; it narrows their policy and receipt derivation responsibilities to package calls.
+
+## Gate 3 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| BTC fee quotes validate PSBT-usable timestamp windows | `packages/btd/src/btc-fee-operation.ts`, `packages/btd/__tests__/btc-fee-operation.test.ts` | drafted |
+| Wallet signer recovery rejects server custody explicitly | `buildWalletSignerSessionRecovery`, `packages/btd/__tests__/btc-fee-operation.test.ts` | drafted |
+| PSBT handoff is typed across prepared, signed, broadcast, finality, replacement/reorg repair, and failure | `BtcFeePsbtHandoffState`, `deriveBtcFeePsbtHandoffState`, `BtcFeeOperationPosture` | drafted |
+| Taproot/script posture is proof-rooted and attached to fee operation posture | `BtcFeeTaprootPsbtPosture`, `buildBtcFeeTaprootPsbtPosture`, API route tests | drafted |
+| Testnet/mainnet distinction blocks value-bearing production-mainnet settlement unless explicitly approved | `BtcFeeNetworkPolicy`, `buildBtcFeeNetworkPolicy`, `network-policy` blocked-readiness tests | drafted |
+| Signed receipts require signed PSBT evidence before broadcast | `packages/btd/src/bitcoin-fees.ts`, `packages/btd/__tests__/btc-fee-operation.test.ts` | drafted |
+| API settlement route serializes the added operation posture safely | `packages/api/src/routes/__tests__/btd-crypto.test.ts` | drafted |
+| Gate checker protects the BTC fee rigor surface | `scripts/check-v30-gate3-bitcoin-taproot-psbt-fee-rigor.mjs`, `pnpm run check:v30-gate3`, gate-quality workflow | drafted |
+
+## Gate 3 accepted boundaries
+
+- Gate 3 does not admit value-bearing production-mainnet settlement by default.
+- Gate 3 does not implement a bridge chain-of-record path.
+- Gate 3 does not custody Reader private keys or sign PSBTs server-side.
+- Gate 3 does not replace later Gate 4 BTD mint, read, and rights-transfer receipts.
 - Gate 1 does not promote `BITCODE_SPEC.txt` to V30.
 - Gate 1 may retarget workflows to active V29 / draft V30 so later gates are greenable.
 - Gate 1 may update roadmap scope for V31-V37 to align with V28/V29 promotion learning without opening those versions.

package.json

@@ -56,6 +56,7 @@
     "check:v29-gate10": "node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs",
     "check:v30-gate1": "node scripts/check-v30-gate1-roadmap-and-gating.mjs",
     "check:v30-gate2": "node scripts/check-v30-gate2-protocol-package-api-boundaries.mjs",
+    "check:v30-gate3": "node scripts/check-v30-gate3-bitcoin-taproot-psbt-fee-rigor.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/api/src/routes/__tests__/btd-crypto.test.ts

@@ -667,6 +667,17 @@ describe('BTD crypto API builders', () => {
       phase: 'psbt_ready',
       canSignPsbt: true,
       noServerCustody: true,
+      psbtHandoffState: 'prepared_unsigned',
+      broadcastState: 'not_broadcast',
+      networkPolicy: {
+        admitted: true,
+        environment: 'staging-testnet',
+        mainnet: false,
+      },
+      taprootScriptPosture: {
+        commitmentMethod: 'taproot',
+        taprootAdmitted: true,
+      },
       quote: { quoteId: 'quote-api-1' },
     });
     expect(prepared.terminalJournalEntry.transactionKind).toBe('btc_fee_payment');
@@ -1069,6 +1080,12 @@ describe('BTD crypto API builders', () => {
     expect(body.operationPosture).toMatchObject({
       phase: 'psbt_ready',
       canSignPsbt: true,
+      psbtHandoffState: 'prepared_unsigned',
+      broadcastState: 'not_broadcast',
+      networkPolicy: {
+        admitted: true,
+        environment: 'staging-testnet',
+      },
       quote: {
         quoteId: 'quote-api-1',
         sats: '1200',

packages/btd/README.md

@@ -11,6 +11,9 @@ This package owns:
 - contributor allocation, access evaluation, ancestry review, and revenue routing
 - wallet-signed BTC fee receipts, ledger anchors, Exchange rights transfers,
   Terminal journals, reconciliation, telemetry, and upgrade receipts
+- BTC fee operation posture, including quote lifecycle, signer recovery,
+  no-server-custody PSBT handoff, Taproot/script posture, broadcast/finality
+  observation, replacement/reorg repair, and testnet/mainnet network policy
 - Terminal operational health reads that compose deployment lanes, telemetry,
   upgrade posture, provider readiness, settlement-network posture, synthetic
   testnet minting, journal rows, ledger anchors, and reconciliation state

packages/btd/__tests__/btc-fee-operation.test.ts

@@ -1,8 +1,10 @@
 import {
   advanceBtcFeeQuote,
   advanceBtcFeeTransactionReceipt,
+  buildBtcFeeNetworkPolicy,
   buildBtcFeeOperationPosture,
   buildBtcFeeQuote,
+  buildBtcFeeTaprootPsbtPosture,
   buildPreparedBtcFeeTransactionReceipt,
   buildWalletSignerSessionRecovery,
   createWalletSignerSession,
@@ -31,7 +33,7 @@ function authorizedSession(overrides = {}) {
   });
 }
 
-function acceptedQuote() {
+function acceptedQuote(overrides = {}) {
   return advanceBtcFeeQuote(
     buildBtcFeeQuote({
       quoteId: 'quote-1',
@@ -43,6 +45,7 @@ function acceptedQuote() {
       relatedAssetPackId: 'asset-pack-1',
       issuedAt,
       expiresAt,
+      ...overrides,
     }),
     { state: 'accepted' },
   );
@@ -92,6 +95,109 @@ describe('BTC fee quote lifecycle', () => {
       /Invalid BTC fee quote transition/,
     );
   });
+
+  it('fails closed when quote timestamps cannot support PSBT preparation', () => {
+    expect(() =>
+      buildBtcFeeQuote({
+        quoteId: 'quote-expired-at-issue',
+        feePurpose: 'licensed_read',
+        network: 'testnet',
+        sats: 1200n,
+        measurementRoot: 'need-fit-measurement-root',
+        issuedAt,
+        expiresAt: issuedAt,
+      }),
+    ).toThrow('BTC fee quote expiresAt must be after issuedAt.');
+  });
+
+  it('models PSBT handoff, replacement, and reorg repair states explicitly', () => {
+    const prepared = preparedReceipt();
+    expect(() =>
+      advanceBtcFeeTransactionReceipt(prepared, { finalityState: 'signed' } as never),
+    ).toThrow('signedPsbt must be a non-empty string.');
+
+    const signed = advanceBtcFeeTransactionReceipt(prepared, {
+      finalityState: 'signed',
+      psbt: 'signed-psbt',
+    });
+    const broadcast = advanceBtcFeeTransactionReceipt(signed, {
+      finalityState: 'broadcast',
+      txid: 'txid-repair',
+    });
+    const replaced = advanceBtcFeeTransactionReceipt(broadcast, {
+      finalityState: 'replaced',
+      txid: 'replacement-txid',
+    });
+
+    expect(buildBtcFeeTaprootPsbtPosture({ network: 'testnet', receipt: prepared })).toMatchObject({
+      psbtHandoffState: 'prepared_unsigned',
+      broadcastState: 'not_broadcast',
+      taprootRequired: true,
+    });
+    expect(buildBtcFeeTaprootPsbtPosture({ network: 'testnet', receipt: signed })).toMatchObject({
+      psbtHandoffState: 'signed_ready_to_broadcast',
+      broadcastState: 'not_broadcast',
+    });
+    expect(buildBtcFeeTaprootPsbtPosture({ network: 'testnet', receipt: replaced })).toMatchObject({
+      psbtHandoffState: 'replacement_or_reorg_repair_required',
+      broadcastState: 'replaced',
+    });
+  });
+
+  it('blocks value-bearing mainnet settlement unless operationally approved', () => {
+    expect(
+      buildBtcFeeNetworkPolicy({
+        network: 'mainnet',
+        environment: 'production-mainnet',
+      }),
+    ).toMatchObject({
+      admitted: false,
+      operationalApprovalRequired: true,
+      mainnet: true,
+      proofRoot: expect.stringMatching(/^btc-fee-network-policy-/),
+    });
+
+    const mainnetQuote = acceptedQuote({ network: 'mainnet', quoteId: 'quote-mainnet-1' });
+    const mainnetSession = authorizedSession({
+      walletSessionId: 'wallet-session-mainnet',
+      walletId: 'wallet-mainnet',
+      address: 'bc1qbitcodereader0000000000000000000000000',
+      network: 'mainnet',
+    });
+    const blocked = buildBtcFeeOperationPosture({
+      quote: mainnetQuote,
+      payerSession: mainnetSession,
+      environment: 'production-mainnet',
+      at: issuedAt,
+    });
+    expect(blocked).toMatchObject({
+      phase: 'blocked',
+      networkPolicy: {
+        admitted: false,
+        blocker: 'Value-bearing BTC fee settlement on mainnet requires explicit operational approval.',
+      },
+      blockedReadiness: {
+        blockerId: 'network-policy',
+        noServerCustody: true,
+      },
+    });
+
+    expect(
+      buildBtcFeeOperationPosture({
+        quote: mainnetQuote,
+        payerSession: mainnetSession,
+        environment: 'production-mainnet',
+        valueBearingMainnetApproved: true,
+        at: issuedAt,
+      }),
+    ).toMatchObject({
+      phase: 'quoted',
+      networkPolicy: {
+        admitted: true,
+        operationalApprovalRequired: true,
+      },
+    });
+  });
 });
 
 describe('wallet signer recovery', () => {
@@ -133,6 +239,23 @@ describe('wallet signer recovery', () => {
       canSign: false,
     });
   });
+
+  it('rejects server-custody signer sessions before PSBT handoff', () => {
+    const recovery = buildWalletSignerSessionRecovery({
+      session: {
+        ...authorizedSession(),
+        serverCustody: true,
+      } as never,
+      network: 'testnet',
+      at: issuedAt,
+    });
+
+    expect(recovery).toMatchObject({
+      state: 'server_custody_rejected',
+      canSign: false,
+      blocker: 'Wallet signer session implies server custody.',
+    });
+  });
 });
 
 describe('BTC fee operation posture', () => {
@@ -195,6 +318,8 @@ describe('BTC fee operation posture', () => {
       phase: 'psbt_ready',
       canSignPsbt: true,
       canBroadcast: false,
+      psbtHandoffState: 'prepared_unsigned',
+      broadcastState: 'not_broadcast',
     });
 
     const signed = advanceBtcFeeTransactionReceipt(prepared, {
@@ -220,6 +345,12 @@ describe('BTC fee operation posture', () => {
     ).toMatchObject({
       phase: 'broadcast',
       canObserveFinality: true,
+      psbtHandoffState: 'broadcast_submitted',
+      broadcastState: 'broadcast',
+      taprootScriptPosture: {
+        commitmentMethod: 'taproot',
+        taprootAdmitted: true,
+      },
     });
     expect(
       buildBtcFeeOperationPosture({
@@ -232,6 +363,8 @@ describe('BTC fee operation posture', () => {
       phase: 'confirmed',
       canSettle: true,
       noServerCustody: true,
+      psbtHandoffState: 'finality_observed',
+      broadcastState: 'confirmed',
     });
   });
 });

packages/btd/src/bitcoin-fees.ts

@@ -124,6 +124,10 @@ export function advanceBtcFeeTransactionReceipt(
   const txid = next.txid ?? receipt.txid;
   const confirmations = next.confirmations ?? receipt.confirmations;
 
+  if (next.finalityState === 'signed') {
+    assertNonEmptyString(next.psbt, 'signedPsbt');
+  }
+
   if (['broadcast', 'confirmed', 'replaced', 'reorged'].includes(next.finalityState)) {
     assertNonEmptyString(txid, 'txid');
   }