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-21. 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), #229 (Cadence benchmark out-of-memory fix) and #237 (Boost ≥ 1.91 backport).

Order of operations

1. ci: wait for a newer run instead of failing on an earlier one's result #231 once its CI is green. It's independent of the stack.
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, then get CI and Codex on their new heads.
3. Fix rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236's conflict. Rebase its 6 commits onto net: hybrid handshake outcomes, 3-strike fallback and load shedding (#184 part 5) #235's new head, linearly with no merge commits. In p2p_v2_previous_release.py keep both sides' imports: itertools, os and shutil, BitcoinTestFramework, SkipTest, and TestNodeCLI, release_info. Nothing else conflicts; the merged test passes against the real v1.0.0 binaries. Then rebase test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239's 4 commits onto rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236's new head.
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, then test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239, each once it meets the criteria. Every merge rebases the PRs above it again.
5. doc, bench: operator guide, release note and handshake benchmark for hybrid v2 transport #240 (part 8): link it into the stack (gh stack link with the stack's PRs in order, ending in 240) and label it pq-transport, after test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239 is rebased. Then CI and Codex.
6. 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.
7. 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: green CI, then merge
• multi_index: fix compilation failure with boost >= 1.91 (backport bitcoin#35175) #237: merged
• test, ci: foundations for hybrid v2 transport (Python ML-KEM, qbit releases, v1.0.0 interop, PQ CI, canary tools) #224: green CI, then merge
• rpc, init: -v2pqtransport, getpqtransportinfo and hybrid peer fields (#184 part 6) #236: resolve the import conflict after test, ci: foundations for hybrid v2 transport (Python ML-KEM, qbit releases, v1.0.0 interop, PQ CI, canary tools) #224 merges; rebase test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239 on it
• 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 → test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239 in order
• doc, bench: operator guide, release note and handshake benchmark for hybrid v2 transport #240 (part 8): link into the stack, label, CI, Codex, merge after test: end-to-end hybrid transport tests, Python hybrid peer, misbehaving peers and fallback (#184 part 7) #239
• contrib, doc: v2flood harness, handshake benchmark, operator guide and release note (#184 part 8) #215's flood tooling (H1), out of doc, bench: operator guide, release note and handshake benchmark for hybrid v2 transport #240's scope; R3 needs a plan for it
• 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 self-hosted runners' disk fills up. They share one 234 GB disk on one host, and two PRs' Full Validation runs at once fill it. Sanitizer, CentOS and i686 jobs then fail together, within seconds, with Disk space is too low! in the log; the code is fine. Let one PR's Full Validation run at a time, then rerun the failed jobs. The host needs pruning or more disk.
• 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) broke txmempool.h on branches without multi_index: fix compilation failure with boost >= 1.91 (backport bitcoin#35175) #237, which is now merged. The macOS PQ jobs build Boost through depends either way.
• pq-functional (nightly, or on a named dispatch) hasn't run on GitHub yet. Its 45-minute limit is twice the measured cold 4-core build plus the whole --v2pqtransport suite. Check the first run's duration.

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.
• The load-shedding functional test runs on a frozen steady clock, using the regtest-only -test=pq_low_shed_threshold and -test=mock_steady_clock. It has no real-time or skip path.