A side-by-side visualization of Bitcoin Core's legacy mempool against the cluster-mempool redesign (merged to master in PR #33629, Nov 2025; shipping in Bitcoin Core 31.0, expected late 2026) and the TRUC admission rules (BIP 431, live since Core 28.0). Built at the MIT Bitcoin Hackathon 2026.
Live demo: https://stalesamy.github.io/cluster-mempool-viz/ Source: https://github.com/Stalesamy/cluster-mempool-viz
If the embed doesn't play, download the .mp4 or open the release page.
Deployment status as of April 2026: cluster mempool is not live on mainnet yet. It's merged to Core master and slated for 31.0 (expected late 2026). Bitcoin Core 30.0, the current stable release, does not contain it. Since cluster mempool is policy (not consensus), it has no activation event — it takes effect on each node individually when that node upgrades to 31.0.
The mempool is one of the most load-bearing and least visible parts of Bitcoin Core. It decides which transactions relay, which get into block templates, and which replacements are accepted. Almost every pinning attack, fee-bumping UX failure, and Layer-2 policy workaround traces back to its data model — a flat set of transactions with ancestor/descendant tracking and BIP-125 RBF rules.
The most concrete motivator: Antoine Riard's Lightning replacement-cycling attack (CVE-2023-40231..34), disclosed October 2023. Real CVE, real L2 money at risk, attributable to the legacy mempool's policy model.
Cluster mempool (Suhas Daftuar, Pieter Wuille, Anthony Towns — merged November 2025 via PR #33629) replaces that model. Transactions are grouped into size-bounded clusters. Each cluster has a computed linearization, chopped into chunks of monotonically-decreasing feerate. Block assembly becomes "pick the highest-feerate chunk across all clusters, repeat." RBF becomes a single criterion: the post-replacement mempool's feerate diagram must dominate the pre-replacement diagram everywhere.
Replayed against 2023 mainnet data, cluster mempool produced strictly better block templates in 72.8% of blocks, averaging +153,615 sat/block (sdaftuar, 2024). The L2-pinning and free-relay story is just as important, but the mining-revenue number is the one to cite when critics ask "does this actually matter?"
This project makes those objects — clusters, linearizations, chunks, feerate diagrams, dominance — visible. It also makes the critiques visible: scenarios for the common case where cluster mempool and legacy produce identical output, the residual pinning that cluster mempool alone doesn't fix, and the incomparable-diagram partitioning attack that's an inherent limit of the approach.
For each scenario, the app renders two synchronized panels:
| Left: Legacy mempool | Right: Cluster mempool |
|---|---|
| Flat DAG of transactions | DAG colored by chunk; cluster structure explicit |
| Ancestor-feerate block template | Per-cluster linearization and chunk list |
| BIP-125 rule-3 verdict for replacements | Feerate diagram overlay (pre vs post) with green/red dominance shading |
Nine scenarios across four categories:
| Category | Scenarios |
|---|---|
| Foundation | Normal mempool · RBF race |
| Wins for cluster mempool | Lightning pinning · Free-relay attack |
| Critiques & edge cases | Common case (no diff) · Residual pinning · Partitioning (incomparable diagrams) |
| Cluster + TRUC: full fix | TRUC defeats the pin |
Every scenario has a built-in takeaway grounded in linked public sources.
A correction worth making, since it's widely misrepresented:
- Peter Todd is a cluster-mempool advocate, not opponent. He opposes TRUC specifically, preferring a one-shot replace-by-feerate alternative (petertodd.org/2024/one-shot-replace-by-fee-rate).
- Primary authors (Daftuar · Wuille · Towns) are the champions. Gloria Zhao (TRUC/BIP 431 author) supports cluster mempool but has flagged the CPFP-carve-out deployment cliff.
- Greg Sanders (instagibbs) provided multi-round ACKs and is actively building on top (package-relay work).
- No loud, organized opposition to cluster mempool itself. What exists is reviewer conservatism about a multi-thousand-line refactor and domain-specific concerns about TRUC's opt-in policy surface.
src/
sim/ pure-TS simulator (no React, no DOM)
types.ts Tx, Cluster, Chunk, FeerateDiagram
clusters.ts union-find → connected components
linearize.ts ancestor-feerate linearization (LIMO seed)
chunks.ts monotone-decreasing chunk merging
diagram.ts feerate diagram + dominance check
legacy.ts legacy block template + BIP-125 rule-3 emulation
truc.ts BIP 431 admission rules
scenarios/ nine hand-authored event streams + types
components/ React + D3 (dagre layout + SVG) + framer-motion
Hero.tsx problem / solution / tool strip
ScenarioGrid.tsx four category cards
PlaybackBar.tsx play/pause/speed/progress
ClusterDAG.tsx animated DAG, chunk-colored, with overlay states
FeerateDiagram.tsx diagram with green/red dominance shading
LegacyPanel.tsx left panel + BIP-125 verdict stamp
ClusterPanel.tsx right panel + diagram verdict stamp
MetricsBar.tsx mempool counts, fees, cluster stats
useScenarioState.ts replays a scenario up to step i
usePlayback.ts RAF-driven auto-play timer
App.tsx / App.css layout and theming
- Linearization is ancestor-feerate (the LIMO seed). Real cluster mempool uses SFL (spanning-forest linearization) with tunable work budgets; the seed is what matters for every visualization concept here.
- Policies are pure functions, not a real
bitcoind. No P2P, no mining, no fee estimator. - BIP-125 is rules 3 and 5. Rules 1/2/4/6 don't change any scenario's outcome.
- TRUC covers the admission rules that matter (v3-v3 only, 1 unconfirmed ancestor, 1000 vB child cap, single-child). Other TRUC details (witness weight, sigops) are elided.
npm install
npm run dev
Build:
npm run build
npm run preview
- Suhas Daftuar, "Cluster mempool: a theory of mempool representation" — seminal thread
- Suhas Daftuar, "An overview of the cluster mempool proposal" — Jan 2024 overview
- Pieter Wuille, "Cluster mempool — definitions & theory" — algebraic theorems
- Pieter Wuille, "Cluster mempool block building with sub-chunk granularity" — future "absorption sets"
- Suhas Daftuar, "Research into effects of cluster-size-limited mempool in 2023" — the 72.8% / +153,615 sat/block paper
- PR #33629 — merged cluster mempool, Nov 2025
- Bitcoincore.reviews #31444 transcript — review-club discussion
- Bitcoin Optech cluster-mempool topic: bitcoinops.org/en/topics/cluster-mempool/
- stefanwouldgo, "Cluster mempool partitioning attacks" — incomparable-diagrams critique; sipa acknowledges
- Optech #313, 2024-07-26 — CPFP-CO deployment cliff; Todd-RBFR alternative
- PR #30126 — why SFL replaced CSS (99p ~9 ms add pre-optimization)
- Issue #29319 — cluster mempool / CPFP-CO / v3 policy interaction tracking
- Gloria Zhao et al., BIP 431
- Bitcoin Optech TRUC topic: bitcoinops.org/en/topics/truc/
- Peter Todd, "One-shot replace-by-fee-rate" — alternative to TRUC
- Antoine Riard, replacement-cycling attack disclosure (October 2023) — CVE-2023-40231..34. Postmortem.
- Pieter Wuille, "Cluster mempool" — Bitcoin++ Austin 2025. See btcplusplus.dev/conf/atx25.
MIT.