Handover: #184 hybrid post-quantum transport, state as of 2026-10-06 #238

Start here

This is the state of the #184 work (hybrid post-quantum v2 transport) as of 2026-10-06. All of it is on GitHub; nothing depends on any one machine.

1. Every p2p: add hybrid post-quantum key exchange (ML-KEM-1024) to BIP324 v2 transport #184 PR targets feature/pq-transport. Draft Hybrid post-quantum v2 transport (#184) — integration #233 tracks the whole thing and merges it into 1.x.x at the end, with one approval.
2. Merge criteria: a PR merges only when its CI is complete and green, including the Required Merge Gate, and its agentic review (Codex) is clean on the current head commit. Stacked PRs merge bottom-up.
3. Merge ci: wait for a newer run instead of failing on an earlier one's result #231 early. It fixes a merge-gate bug that causes most of the false red gates described below.

Where everything is

Already merged into feature/pq-transport: #223 (I2P post-quantum leasesets), #228 (RPC docs CI checkout fix) and #229 (Cadence benchmark out-of-memory fix).

Order of operations

1. ci: wait for a newer run instead of failing on an earlier one's result #231 and multi_index: fix compilation failure with boost >= 1.91 (backport bitcoin#35175) #237 whenever each meets the criteria. They're independent.
2. test, ci: foundations for hybrid v2 transport (Python ML-KEM, qbit releases, v1.0.0 interop, PQ CI, canary tools) #224. GitHub then auto-rebases the stacked PRs (crypto: vendor mlkem-native and build ML-KEM-1024 with runtime backend selection #225, net: hybrid post-quantum v2 handshake with key confirmation (#184 part 4) #230, net: hybrid handshake outcomes, 3-strike fallback and load shedding (#184 part 5) #235) onto the updated base. Refetch those branches before doing anything on them.
3. Fix rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236's conflict. Rebase its 5 commits onto net: hybrid handshake outcomes, 3-strike fallback and load shedding (#184 part 5) #235's new head, linearly with no merge commits. Resolve p2p_v2_previous_release.py by keeping test, ci: foundations for hybrid v2 transport (Python ML-KEM, qbit releases, v1.0.0 interop, PQ CI, canary tools) #224's check (skip unless the v1.0.0 qbitd and qbit-cli are present) together with part 6's changes.
4. crypto: vendor mlkem-native and build ML-KEM-1024 with runtime backend selection #225, then net: hybrid post-quantum v2 handshake with key confirmation (#184 part 4) #230, then net: hybrid handshake outcomes, 3-strike fallback and load shedding (#184 part 5) #235, then rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236, each once it meets the criteria.
5. Part 7 (test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239): add G3 as described in the table, then merge test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239 after rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236.
6. Part 8: implement from contrib, doc: v2flood harness, handshake benchmark, operator guide and release note (#184 part 8) #215, stacked on rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236.
7. Hybrid post-quantum v2 transport (#184) — integration #233: finish its checklist (Guix builds with hashes and ELF notes, remove the CI branch-list entry, merge the latest 1.x.x), mark it ready, get one approval.
8. Release gate release: hybrid v2 transport release gate and default-on (#184 part 9) #222, updated for the shortened plan: no mainnet canary, a short testnet4 soak, then mainnet. R4 (outside review) still needs a decision.

Remaining work

• ci: wait for a newer run instead of failing on an earlier one's result #231: clean Codex pass on 8fc28a8 and green CI, then merge
• multi_index: fix compilation failure with boost >= 1.91 (backport bitcoin#35175) #237: rerun the dead Windows fuzz job, then merge
• test, ci: foundations for hybrid v2 transport (Python ML-KEM, qbit releases, v1.0.0 interop, PQ CI, canary tools) #224: clean Codex on the last two commits and green CI, then merge
• rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236: resolve the conflict after test, ci: foundations for hybrid v2 transport (Python ML-KEM, qbit releases, v1.0.0 interop, PQ CI, canary tools) #224 merges
• crypto: vendor mlkem-native and build ML-KEM-1024 with runtime backend selection #225 → net: hybrid post-quantum v2 handshake with key confirmation (#184 part 4) #230 → net: hybrid handshake outcomes, 3-strike fallback and load shedding (#184 part 5) #235 → rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236 in order
• test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239: add G3 (union conflict resolution), then merge after rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236
• Part 8 (contrib, doc: v2flood harness, handshake benchmark, operator guide and release note (#184 part 8) #215)
• Hybrid post-quantum v2 transport (#184) — integration #233 checklist, then approval
• release: hybrid v2 transport release gate and default-on (#184 part 9) #222 release gate (R1 default-on, R2 fuzz campaign, R3 flood measurement, R6 short testnet4 soak, R7 release decision; R4 to decide)

CI gotchas (each cost real time)

• Stacked PRs need a label to get full CI. A PR opened before it joins a stack only runs Core Checks and RPC Docs. Adding any label (we use pq-transport) starts Full Validation and the Required Merge Gate.
• The merge gate can read stale results until ci: wait for a newer run instead of failing on an earlier one's result #231 lands. On a rerun, reopen or label of the same commit, the gate can judge an earlier run's cancelled or failed check and fail within seconds. Once the real jobs are green, rerun just the gate: gh run rerun <gate-run> --failed. ci: wait for a newer run instead of failing on an earlier one's result #231 fixes this by matching each check to the event that started it.
• Runner starvation. Many PRs pushed at once fill the GitHub-hosted job limit. Jobs that wait about 15 minutes are cancelled, and the gates then fail. Push PRs one at a time.
• The Blacksmith Windows runners sometimes die. The job then shows "failure" with no steps and no log. Rerun it.
• GitHub auto-rebases stacks when a PR merges into the base. Keep stacked branches linear (no merge commits), or GitHub stops and leaves the PR conflicting. Rebased commits are committed by GitHub.
• Don't run bench_sanity_check or bare bench_qbit on branches that predate bench: bound the Cadence benchmark chain without -asymptote #229. The Cadence benchmark there allocates without bound until the machine runs out of memory. Build those branches with -DBUILD_BENCH=OFF.
• Boost ≥ 1.91 (Homebrew) breaks txmempool.h until multi_index: fix compilation failure with boost >= 1.91 (backport bitcoin#35175) #237 lands. The macOS PQ jobs avoid it by building through depends.

Decisions already made

• All p2p: add hybrid post-quantum key exchange (ML-KEM-1024) to BIP324 v2 transport #184 work integrates on feature/pq-transport first, because approvals on 1.x.x weren't available.
• The release gate is shortened (release: hybrid v2 transport release gate and default-on (#184 part 9) #222): no mainnet canary, a short testnet4 soak, then mainnet.
• -nov2pqtransport and -mlkemportable with non-numeric or double-negative values warn whenever the result is ON. The argument parser itself is unchanged, to stay aligned with upstream.
• -mlkemportable exists as a hidden option (part 6), and the local-fault warning names it.
• Shutdown wipes PQ secrets but records no outcome (part 5).
• Merge gate (ci: wait for a newer run instead of failing on an earlier one's result #231): a cancelled check is never a verdict.