[Phase 6] Inquisition + time-warp roadmap (tracking)

[neverDefined]

Goal

Make go-regtest a first-class test harness for the upcoming soft-forks shipping in Bitcoin Inquisition (BIP54 Consensus Cleanup, BIP118 ANYPREVOUT, BIP119 CTV, BIP347 OP_CAT, BIP348 OP_CHECKSIGFROMSTACK, BIP349 OP_INTERNALKEY) and to expose first-class time-warping primitives so consumers can write deterministic activation tests without learning bitcoind RPC quirks.

End state: a developer who depends on CTV/CSFS/CAT/APO sets Config.BinaryPath = "/path/to/bitcoind-inquisition", calls rt.MineUntilActiveBIP(ctx, BIP119, addr, 2000), and gets a green test. CI matrices that run on Core skip Inquisition-only tests cleanly via rt.SupportsBIP(BIP119).

What lives where

• Soft-fork rules live in bitcoind (Core or bitcoind-inquisition). go-regtest stays binary-agnostic.
• go-regtest's job is the deterministic harness: pick the right binary, feed flags, observe activation state, and now — advance time.
• The new layer: a curated BIPID registry that joins live getdeploymentinfo with BIP metadata so devs use typed constants instead of magic strings.

The shape of the change

                        ┌─────────────────────────────────────┐
                        │          Public API surface          │
                        └─────────────────────────────────────┘
 Config.BinaryPath ──┐    ┌─ rt.Variant()         ─┐    ┌─ rt.SetMockTime(ctx, unix)
                     │    │  (Core | Inquisition)  │    │  rt.MineWithTimestamp(ctx, n, ts, miner)
                     ▼    │                        │    │  rt.WarpTime(ctx, dur, miner)
            ┌──────────────────────┐               │    └──────────┬─────────────────
            │  initialize()        │               │               │
            │  (regtest.go)        │               │               ▼
            │  • LookPath chain    │               │       ┌──────────────────┐
            │  • write script      │               │       │ rawRPC(ctx, ...) │  ← rpc.go (existing)
            └─────────┬────────────┘               │       └────────┬─────────┘
                      │ BITCOIND_BIN +             │                │
                      │ BITCOIN_CLI_BIN env        │                ▼
                      ▼                            │       ┌──────────────────┐
            ┌──────────────────────┐               │       │ bitcoind RPC     │
            │ bitcoind_manager.sh  │               │       │  setmocktime     │
            │ uses $BITCOIND_BIN   │               │       │  generatetoaddr  │
            └──────────┬───────────┘               │       │  getnetworkinfo  │
                       │                           │       │  getdeployinfo   │
                       ▼                           │       └──────────────────┘
                  bitcoind /                       │                ▲
                  bitcoind-inquisition             │                │
                                                   ▼                │
                                          ┌────────────────┐        │
                                          │ deployments.go │────────┘
                                          │  registry      │
                                          │  ListDeploys   │
                                          │  SupportsBIP   │
                                          └────────────────┘

Layering: WarpTime → MineWithTimestamp → SetMockTime + WarpContext. ListDeployments/SupportsBIP → GetDeploymentInfoContext. Nothing reaches into r.client directly — every new wrapper goes through rawRPC or lockedClient per CLAUDE.md invariant #1.

Milestones

• Phase 6.0 — Inquisition foundation — binary plumbing, registry, BIP119 worked example, README. 8 issues.
• Phase 6.1 — Time-warp expansion — layered time API + worked examples. 5 issues.

Phase 6.0 — Inquisition foundation

Tier A — Binary plumbing

• [Phase 6.A.1] Config.BinaryPath + script env-var indirection #97 — [Phase 6.A.1] Config.BinaryPath + script env-var indirection (foundation)
• [Phase 6.A.2] PATH auto-detect (bitcoind-inquisition → bitcoind) #98 — [Phase 6.A.2] PATH auto-detect (bitcoind-inquisition → bitcoind) (depends on [Phase 6.A.1] Config.BinaryPath + script env-var indirection #97)
• [Phase 6.A.3] Variant() getter from getnetworkinfo.subversion #99 — [Phase 6.A.3] Variant() getter from getnetworkinfo.subversion (depends on [Phase 6.A.1] Config.BinaryPath + script env-var indirection #97)

Tier B — Deployment registry

• [Phase 6.B.1] BIPID constants + bipRegistry #100 — [Phase 6.B.1] BIPID constants + bipRegistry
• [Phase 6.B.2] ListDeployments(ctx) joining live + registry #101 — [Phase 6.B.2] ListDeployments(ctx) joining live + registry (depends on [Phase 6.B.1] BIPID constants + bipRegistry #100)
• [Phase 6.B.3] SupportsBIP(ctx, BIPID) + MineUntilActiveBIP #102 — [Phase 6.B.3] SupportsBIP(ctx, BIPID) + MineUntilActiveBIP (depends on [Phase 6.B.1] BIPID constants + bipRegistry #100)

Tier E — Acceptance + docs

• [Phase 6.E.1] Worked example: TestExampleActivateBIP119 #106 — [Phase 6.E.1] Worked example: TestExampleActivateBIP119 (depends on [Phase 6.A.1] Config.BinaryPath + script env-var indirection #97–[Phase 6.B.3] SupportsBIP(ctx, BIPID) + MineUntilActiveBIP #102)
• [Phase 6.E.2] README: Inquisition install + skip-when-missing pattern #107 — [Phase 6.E.2] README: Inquisition install + skip-when-missing pattern (depends on [Phase 6.B.3] SupportsBIP(ctx, BIPID) + MineUntilActiveBIP #102)

Phase 6.1 — Time-warp expansion

Tier C — Time API

• [Phase 6.C.1] SetMockTime(ctx, unix) wrapper #103 — [Phase 6.C.1] SetMockTime(ctx, unix) wrapper
• [Phase 6.C.2] MineWithTimestamp(ctx, blocks, ts, miner) #104 — [Phase 6.C.2] MineWithTimestamp(ctx, blocks, ts, miner) (depends on [Phase 6.C.1] SetMockTime(ctx, unix) wrapper #103)
• [Phase 6.C.3] WarpTime(ctx, duration, miner) advancing MTP #105 — [Phase 6.C.3] WarpTime(ctx, duration, miner) advancing MTP (depends on [Phase 6.C.2] MineWithTimestamp(ctx, blocks, ts, miner) #104)

Tier E — Acceptance

• [Phase 6.E.3] TestExampleTimeoutWithoutLockin via WarpTime #108 — [Phase 6.E.3] TestExampleTimeoutWithoutLockin via WarpTime (depends on [Phase 6.C.3] WarpTime(ctx, duration, miner) advancing MTP #105)
• [Phase 6.E.4] TestVariantDetection smoke test #109 — [Phase 6.E.4] TestVariantDetection smoke test (depends on [Phase 6.A.3] Variant() getter from getnetworkinfo.subversion #99)

Dependency graph

#97 BinaryPath ─────┬──> #98 PATH auto-detect ─────┐
                    │                              │
                    └──> #99 Variant() ───────┬────┤
                                              │    │
#100 BIPID + registry ──┬──> #101 ListDeployments ─┤
                        │                          │
                        └──> #102 SupportsBIP ─────┼──> #106 BIP119 example
                                                   │
                                                   └──> #107 README
                                                   │
                                              └────┴──> #109 Variant smoke test (needs #99)

#103 SetMockTime ──> #104 MineWithTimestamp ──> #105 WarpTime ──> #108 timeout-without-lockin example

The unblocking path to a runnable Inquisition test is #97 → #98 → #99 → #100 → #101 → #102 → #106 → #107. Time API (#103 → #104 → #105) is independent and can land in parallel after Phase 6.0 closes.

PR sequence

1. PR1 — closes [Phase 6.A.1] Config.BinaryPath + script env-var indirection #97 + [Phase 6.A.2] PATH auto-detect (bitcoind-inquisition → bitcoind) #98 + [Phase 6.A.3] Variant() getter from getnetworkinfo.subversion #99 (binary plumbing + Variant). Tightly coupled, single review unit.
2. PR2 — closes [Phase 6.B.1] BIPID constants + bipRegistry #100 + [Phase 6.B.2] ListDeployments(ctx) joining live + registry #101 + [Phase 6.B.3] SupportsBIP(ctx, BIPID) + MineUntilActiveBIP #102 (registry + SupportsBIP + MineUntilActiveBIP).
3. PR3 — closes [Phase 6.E.1] Worked example: TestExampleActivateBIP119 #106 + [Phase 6.E.2] README: Inquisition install + skip-when-missing pattern #107 (BIP119 example + README). Closes Phase 6.0.
4. PR4 — closes [Phase 6.C.1] SetMockTime(ctx, unix) wrapper #103 + [Phase 6.C.2] MineWithTimestamp(ctx, blocks, ts, miner) #104 + [Phase 6.C.3] WarpTime(ctx, duration, miner) advancing MTP #105 (layered time API).
5. PR5 — closes [Phase 6.E.3] TestExampleTimeoutWithoutLockin via WarpTime #108 + [Phase 6.E.4] TestVariantDetection smoke test #109 (timeout + variant examples). Closes Phase 6.1.

Per CLAUDE.md invariants: additive only, no breaking signatures, every public RPC method has a Context variant, make ai-check green before each PR.

Related

• Phase 5.0 / 5.1 ([Phase 5] Soft-fork testing roadmap (tracking) #83) — soft-fork foundation. Phase 6 builds directly on VBParams, MineUntilActive, GetDeploymentInfo, and the testdummy worked example shipped in Phase 5.
• SigHashAnyPrevOut Softfork simulation #25 — SigHashAnyPrevOut Softfork simulation. Once Phase 6 lands, SigHashAnyPrevOut Softfork simulation #25 becomes a drop-in replacement: MineUntilActiveBIP(ctx, BIP118, miner, 2000) against a bitcoind-inquisition build.

Out of scope (deferred)

• cmd/regtest-doctor diagnostic CLI — useful but not required for the API.
• Renaming/refactoring existing MineUntilActive(string, ...) to take BIPID. New MineUntilActiveBIP is additive; string variant stays per CLAUDE.md invariant Config #5.
• Bundling Inquisition build instructions into a Makefile target. README copy is sufficient.
• Default-signet support (Inquisition's other operating mode).

[neverDefined]

Phase 6 complete. Closing.

Summary

13 issues across 5 PRs (plus a docs sweep) shipped Bitcoin Inquisition support and a layered time API.

Phase 6.0 — Inquisition foundation

• add Config.BinaryPath, PATH auto-detect, and Variant() (#97, #98, #99) #111 — Config.BinaryPath, PATH auto-detect (bitcoind-inquisition → bitcoind), Variant(). Closes [Phase 6.A.1] Config.BinaryPath + script env-var indirection #97, [Phase 6.A.2] PATH auto-detect (bitcoind-inquisition → bitcoind) #98, [Phase 6.A.3] Variant() getter from getnetworkinfo.subversion #99.
• add BIPID registry, ListDeployments, SupportsBIP, MineUntilActiveBIP (#100, #101, #102) #112 — BIPID registry, ListDeployments, SupportsBIP, MineUntilActiveBIP. Deployment keys verified against Inquisition 29.2's getdeploymentinfo. Closes [Phase 6.B.1] BIPID constants + bipRegistry #100, [Phase 6.B.2] ListDeployments(ctx) joining live + registry #101, [Phase 6.B.3] SupportsBIP(ctx, BIPID) + MineUntilActiveBIP #102.
• add Inquisition worked example + README skip-when-missing pattern (#106, #107) #113 — TestExampleActivateBIP119 worked example + README skip-when-missing pattern + Inquisition build recipe. Closes [Phase 6.E.1] Worked example: TestExampleActivateBIP119 #106, [Phase 6.E.2] README: Inquisition install + skip-when-missing pattern #107.

Phase 6.1 — Time-warp expansion

• add layered time API: SetMockTime, MineWithTimestamp, WarpTime (#103, #104, #105) #115 — SetMockTime, MineWithTimestamp, WarpTime (layered). Closes [Phase 6.C.1] SetMockTime(ctx, unix) wrapper #103, [Phase 6.C.2] MineWithTimestamp(ctx, blocks, ts, miner) #104, [Phase 6.C.3] WarpTime(ctx, duration, miner) advancing MTP #105.
• add timeout-without-lockin and variant detection examples (#108, #109) #116 — TestExampleTimeoutWithoutLockin (forces signaling-suppression via -blockversion=0x20000000) and TestVariantDetection smoke test. Plus the uint32 block-timestamp cap validation that surfaced during development. Closes [Phase 6.E.3] TestExampleTimeoutWithoutLockin via WarpTime #108, [Phase 6.E.4] TestVariantDetection smoke test #109.

Bonus

• docs: post-Phase 6 audit (doc.go, README, rpc.go godoc) #114 — Post-Phase 6 docs audit: tagline, doc.go Soft-fork section, rpc.go godoc filled out, ListDeployments description corrected.

Surfaced quirks (worth knowing)

• Inquisition's getnetworkinfo.subversion is lowercase (inquisition), not (Inquisition). Caught in add Config.BinaryPath, PATH auto-detect, and Variant() (#97, #98, #99) #111 follow-up; parseVariant now case-insensitive.
• Inquisition's -vbparams parser is strict on the 3-field form (name:start:timeout). Core 24+ accepts both 3 and 4 fields. Default render now omits MinActivationHeight when zero so the same Config works against either binary.
• Inquisition uses a "heretical" deployment type (not bip9) — testdummy is present but isn't -vbparams-overridable. The Variant-based skip pattern is documented in two example tests (TestExampleActivateTestdummy, TestExampleTimeoutWithoutLockin) and TestRPC_GetBlockTemplate_SubmitBlock (BIP54-incompatible coinbase).
• Bitcoin Core's BIP9 evaluates the signaling threshold BEFORE timeout, so on regtest where every block signals by default, you have to suppress signaling via -blockversion=0x20000000 to demonstrate STARTED → FAILED. The timeout example shows the recipe.
• Block timestamps are uint32 (cap year 2106). MineWithTimestamp and WarpTime validate against this so callers see a clear error instead of bitcoind's cryptic time-too-old.

Tagging v0.2.0 as the first release with Inquisition + time-warp support.