[Phase 5] Soft-fork testing roadmap (tracking)

[neverDefined]

Goal

Make go-regtest a first-class test harness for Bitcoin soft-forks (APO/eltoo, CTV and LNHANCE, CSFS, and future deployments), so application developers can write deterministic integration tests against a patched bitcoind binary.

What lives where

• Soft-fork rules live in the `bitcoind` binary (mainline Core, `bitcoin-inquisition` for APO, CTV fork, etc.). go-regtest is binary-agnostic.
• go-regtest's job is the deterministic harness around that binary: start with the right flags, observe activation state, feed transactions, surface the exact reject reasons.

The five-phase test shape every soft-fork test follows

1. Start the node with the deployment configured (`VBParams`, `AcceptNonstdTxn`).
2. Verify activation — skip if the binary doesn't expose the deployment.
3. Build the tx that exercises the new rule (your protocol code + `btcsuite/txscript`).
4. Probe with `TestMempoolAccept` — accept/reject with the exact reason.
5. Broadcast, mine, observe — optionally reorg to test sig rebinding (eltoo).

Milestones

• Phase 5.0 — Soft-fork foundation — minimum set to write the eltoo-style test shown in the plan (10 issues).
• Phase 5.1 — Soft-fork expansion — extra helpers, raw block/tx wrappers, multi-node P2P + reorg example, and the scaffolding slash command (7 issues).

Phase 5.0 — Foundation (eltoo-test-minimum)

Tier A — Foundation

• [Phase 5.A.1] Forward Config.ExtraArgs to bitcoind #66 — [Phase 5.A.1] Forward `Config.ExtraArgs` to bitcoind (bug; blocker for A2/B4)
• [Phase 5.A.2] Typed VBParams config → -vbparams #67 — [Phase 5.A.2] Typed `VBParams` → `-vbparams` (depends on [Phase 5.A.1] Forward Config.ExtraArgs to bitcoind #66)
• [Phase 5.A.3] Typed GetBlockChainInfo wrapper #68 — [Phase 5.A.3] `GetBlockChainInfo` wrapper
• [Phase 5.A.4] Typed GetDeploymentInfo wrapper #69 — [Phase 5.A.4] `GetDeploymentInfo` wrapper

Tier B — Activation ergonomics

• [Phase 5.B.3] Typed SoftForkStatus + DeploymentStatus accessor #72 — [Phase 5.B.3] `SoftForkStatus` enum + `DeploymentStatus` (depends on [Phase 5.A.4] Typed GetDeploymentInfo wrapper #69)
• [Phase 5.B.4] Config.AcceptNonstdTxn convenience flag #73 — [Phase 5.B.4] `Config.AcceptNonstdTxn` (depends on [Phase 5.A.1] Forward Config.ExtraArgs to bitcoind #66)

Tier C — Consensus-rule exercising

• [Phase 5.C.1] TestMempoolAccept wrapper #74 — [Phase 5.C.1] `TestMempoolAccept` wrapper
• [Phase 5.C.4] Chain inspection wrappers (GetBestBlockHash, GetBlockHash, GetBlock, GetBlockHeader, GetChainTips) #77 — [Phase 5.C.4] Chain inspection wrappers

Tier D — Reorg

• [Phase 5.D.1] Reorg primitives (InvalidateBlock, ReconsiderBlock, PreciousBlock) #78 — [Phase 5.D.1] Reorg primitives (InvalidateBlock / ReconsiderBlock / PreciousBlock)

Tier E — Acceptance

• [Phase 5.E.1] Worked example: activate Core's testdummy deployment #81 — [Phase 5.E.1] Worked example: activate Core's `testdummy` deployment (depends on [Phase 5.A.1] Forward Config.ExtraArgs to bitcoind #66, [Phase 5.A.2] Typed VBParams config → -vbparams #67, [Phase 5.A.4] Typed GetDeploymentInfo wrapper #69, [Phase 5.B.3] Typed SoftForkStatus + DeploymentStatus accessor #72, [Phase 5.B.4] Config.AcceptNonstdTxn convenience flag #73)

Phase 5.1 — Expansion

Tier B — Mining helpers

• [Phase 5.B.1] MineToHeight helper #70 — [Phase 5.B.1] `MineToHeight` helper
• [Phase 5.B.2] MineUntilActive helper #71 — [Phase 5.B.2] `MineUntilActive` helper (depends on [Phase 5.A.4] Typed GetDeploymentInfo wrapper #69, [Phase 5.B.3] Typed SoftForkStatus + DeploymentStatus accessor #72)

Tier C — Block & raw-tx wrappers

• [Phase 5.C.2] SubmitBlock + GetBlockTemplate wrappers #75 — [Phase 5.C.2] `SubmitBlock` + `GetBlockTemplate`
• [Phase 5.C.3] Raw transaction wrappers #76 — [Phase 5.C.3] Raw transaction wrappers

Tier D — Multi-node

• [Phase 5.D.2] Multi-node P2P: Connect / Disconnect / AddNode #79 — [Phase 5.D.2] Multi-node P2P: Connect / Disconnect / AddNode
• [Phase 5.D.3] Docs example: scripted reorg across two nodes #80 — [Phase 5.D.3] Docs example: scripted reorg across two nodes (depends on [Phase 5.C.4] Chain inspection wrappers (GetBestBlockHash, GetBlockHash, GetBlock, GetBlockHeader, GetChainTips) #77, [Phase 5.D.1] Reorg primitives (InvalidateBlock, ReconsiderBlock, PreciousBlock) #78, [Phase 5.D.2] Multi-node P2P: Connect / Disconnect / AddNode #79)

Tier E — Tooling

• [Phase 5.E.3] Claude slash command: /add-softfork-test #82 — [Phase 5.E.3] Claude slash command `/add-softfork-test` (depends on [Phase 5.E.1] Worked example: activate Core's testdummy deployment #81)

Dependency graph (critical path for Phase 5.0)

```
#66 ExtraArgs ────┬──> #67 VBParams ─────┐
└──> #73 AcceptNonstdTxn ─┤
│
#69 GetDeploymentInfo ──> #72 DeploymentStatus ──┼──> #81 testdummy example
│
#74 TestMempoolAccept ──────────────────────┘
#77 Chain inspection ──> #78 Reorg primitives (independent of above)
#68 GetBlockChainInfo (independent)
```

The unblocking path to a runnable soft-fork test is #66 → #67 → #69 → #72 → #73 → #74 → #81. Everything else can land in any order.

Related

• SigHashAnyPrevOut Softfork simulation #25 — SigHashAnyPrevOut Softfork simulation. Phase 5 is the foundation; once [Phase 5.E.1] Worked example: activate Core's testdummy deployment #81 passes, SigHashAnyPrevOut Softfork simulation #25 becomes a drop-in replacement of `testdummy` with `anyprevout` against a `bitcoin-inquisition` build.
• LNHANCE (CTV / CSFS / IKEY) uses the exact same harness, different payload. No separate plumbing needed once Phase 5 lands.

Out of scope for Phase 5 (candidates for Phase 5.2+)

• `BitcoinCoreVersion()` + documented minimum supported Core (Core 24+ is the assumed minimum).
• Additive `WarpBlocks(...) ([]chainhash.Hash, error)` that returns mined block hashes.
• PSBT wrappers (`WalletProcessPSBT`, `FinalizePSBT`).

Open a separate issue if any of these become necessary before 5.2.