Cluster Mempool Visualization

A visual comparison of Bitcoin Core's legacy mempool against the cluster-mempool redesign. Plus the threads, PRs, CVEs, and alternatives that frame the broader discussion.

Comment

Inspiration

Bitcoin Core's mempool is the part nobody sees and everyone depends on. It decides which transactions relay, which get into block templates, and which replacements are accepted. It's also the root cause of the Lightning replacement-cycling attack (CVE-2023-40231..34) disclosed by Antoine Riard in October 2023 — a real exploit that put L2 channels at risk.

The response is a redesign called cluster mempool by Suhas Daftuar, Pieter Wuille, and Anthony Towns, which merged to Bitcoin Core master in PR #33629 on November 25, 2025 and ships in Core 31.0 (expected late 2026). It's one of the biggest policy changes to the mempool in a decade. Despite that, there is almost no visual tooling that explains how it actually works, what it fixes, and — equally important — what it doesn't.

We wanted to build the tool we wished existed when we first tried to read the Delving Bitcoin threads: a side-by-side simulator that makes clusters, linearizations, chunks, feerate diagrams, and diagram-RBF visible as they happen, alongside the legacy policy doing its thing on the same inputs.

What it does

Cluster Mempool Visualization is a zero-install, auto-playing browser app that runs two mempool policies — legacy and cluster-mempool — on the same transactions and shows both verdicts live.

  • Nine scenarios across four categories: Foundation, Wins for cluster mempool, Critiques & edge cases, and Cluster + TRUC: the full fix.
  • Dual panels per scenario: on the left, the legacy mempool with ancestor-feerate mining and BIP-125 RBF. On the right, cluster mempool with chunk-colored DAGs and feerate diagrams.
  • Events rendered on the graph: evictions, admission rejections (including TRUC), incoming replacements, and diagram dominance all show up visually — red strike-throughs, dashed yellow ghosts, red X overlays, and green/red/grey diagram shading that splits exactly at the x where the pre- and post-replacement curves cross.
  • A takeaway panel for every scenario that cites primary sources and makes honest claims.
  • Nineteen Further Reading cards across Wins, Future work, and Critiques, every one linked to its source (Delving Bitcoin threads, Core PRs, Optech newsletters, or the author's own writeup).

The killer demos:

  • The pinning scenario — watching diagram dominance split at x ≈ 27,000 vB
  • The free-relay scenario — legacy accepts, cluster rejects; the asymmetry makes the point in one frame
  • The TRUC-fix scenario — Mallory's three pin attempts all rejected at admission with visible red-X animations

How we built it

Stack: TypeScript simulator (no bitcoind dependency), React, D3-style SVG rendering with dagre for DAG layout, framer-motion for animations, Vite + GitHub Actions + GitHub Pages for deploy.

Engine — src/sim/ is a framework-free set of pure functions from a transaction set to derived structures:

  • clusters.ts — union-find to partition the tx graph into connected components
  • linearize.ts — ancestor-feerate linearization (the "LIMO seed" that cluster mempool uses as a starting heuristic)
  • chunks.ts — monotone-decreasing feerate chunk merging
  • diagram.ts — feerate diagram construction with a three-way dominance check (dominates / neutral / fails)
  • legacy.ts — ancestor-feerate block templates and BIP-125 rule-3 + rule-5 emulation
  • truc.ts — BIP 431 admission rules: v3-v3 only, max 1 unconfirmed ancestor, 1000 vB child cap, single v3 child per v3 parent

UI — React layer consumes the engine through useScenarioState, a replay hook that runs a scenario's events up to a given step. usePlayback is an RAF-driven timer with speed control (0.5× / 1× / 2× / 4×) and a looping end-hold. Everything animates with spring physics on enter/exit.

Deploy pipeline — GitHub Actions builds and pushes to Pages on every commit to main. 17 commits over the hackathon, all with regular history.

Challenges we ran into

  • Getting the math actually right. Ancestor-feerate linearization, chunk merging rules, feerate diagrams, and diagram-dominance checks all had to be implemented from the public specs. Cross-checked every scenario by hand against the engine output.

  • Zero-crossing diagram shading. A naive midpoint-per-segment check collapses cases where the pre- and post- curves cross inside a segment — the pinning scenario's green-at-small-x / red-at-large-x transition was getting lost. We rewrote the shading to detect sign changes per segment and split at the exact zero crossing.

  • The "FAILS" stamp ambiguity. In the free-relay scenario, the cluster-mempool stamp reading "FAILS" next to a green "ACCEPT" on the legacy panel made it look like cluster mempool was doing the wrong thing. The fix was making both stamps speak outcome-language (ACCEPTED / REJECTED / UNCHANGED) in the big word and mechanism-language (diagram dominates / BIP-125 rule 3) in the small one.

  • Stamp/node collision. The animated verdict stamp was overlapping the DAG's incoming replacement node in several scenarios. Fixed by reserving an 88px top band in the DAG during replace events so nothing can land under the stamp.

  • Correcting the public record on Peter Todd. Early research had him as a cluster-mempool opponent. Actually digging into his writing revealed he's an advocate — his opposition is specifically to TRUC (BIP 431), and he prefers a one-shot RBFR alternative. We updated the hero, deck, and Further Reading to reflect this.

  • Free-relay scenario math bug. The replacement's fee was initially set to 5200 sat, which fails BIP-125's bandwidth rule (extra fee 1200 < required 2200 for a 2.2 kvB replacement). With those numbers, BIP-125 also rejected, killing the scenario's "legacy accepts, cluster rejects" asymmetry. Caught in final review; fixed by bumping to 6500 sat.

  • Scope management. There are so many subtopics around cluster mempool (SFL vs CSS, absorption sets, package relay interactions, privacy implications) that we had to pick the ones we could simulate vs the ones to cover in Further Reading cards.

Accomplishments that we're proud of

  • Nine scenarios that honestly cover both the wins and the critiques. Most cluster-mempool writeups are either cheerleading or critique hit pieces. This one demos the common-case no-op, the residual pinning that cluster mempool doesn't fix alone, and the partitioning-attack edge case sipa himself acknowledged — alongside the wins.
  • Every claim is sourced. 19 Further Reading cards link to primary sources: Delving Bitcoin threads, merged Core PRs, CVE disclosures, Bitcoin Magazine postmortems, Optech newsletters. No hand-waving.
  • Correctly attributing positions — including the Peter Todd correction that most online writeups miss.
  • Visual diagram-dominance shading with zero-crossing splits — the clearest visual explanation of cluster-mempool RBF we've seen anywhere. You can literally point at the x where Alice's fee-bump stops winning and the pin starts winning.
  • Citing concrete measured numbers — 72.8% better block templates, +153,615 sat/block average on 2023 mainnet replay (sdaftuar's data) — instead of generic hype.
  • Production-quality UX in 5 hours: auto-play with speed controls, animated DAG enter/exit, dominance-shaded diagrams, live metrics including a "next-block feerate" derived from the top chunk, mine/evict rings, takeaway panel, category-colored scenario grid.

What we learned

  • Cluster mempool is a bounded, principled improvement — not a silver bullet. The 72.8% better-block number matters in aggregate but is invisible on most individual blocks. The real wins are incentive-compatible RBF, removing the CPFP carve-out kludge, and enabling TRUC.
  • Diagram dominance is a partial order, not a total one. Two mempool states can be incomparable. This is a genuine limit of the approach that partitioning attacks can exploit.
  • The "full fix" for Lightning pinning is cluster mempool + TRUC, not either alone. Cluster mempool gives you the substrate; TRUC gives you the admission rules.
  • Policy changes in Core have real deployment costs even when they're not consensus changes. The CPFP-carve-out removal creates a coordination problem with every Lightning implementation.
  • Most online discussion misrepresents at least one person's position. Peter Todd's case (advocate of cluster mempool, opponent of TRUC) is the one we caught; there are probably others.
  • Visualization tools reduce review burden. A scenario that plays in 6 seconds communicates something that takes 15 paragraphs on Delving Bitcoin.

What's next for Cluster Mempool Visualization

  • Mainnet replay. Hook the simulator to a real bitcoind RPC and replay actual mempool snapshots instead of hand-authored scenarios. Compare legacy and cluster block templates side by side on a per-block basis.
  • Multi-node simulation. The partitioning-attack scenario currently demonstrates the condition in one mempool; the actual attack requires modeling divergent mempools across peers. A two-node view would make it concrete.
  • CPFP-carve-out deployment cliff as a richer phased simulation. Model the network as it transitions from v1 anchor channels to v3 TRUC commitments during the 31.0 rollout window, with a configurable fraction of upgraded nodes.
  • Absorption-sets block building once sipa's 2024 proposal ships — visualize block construction picking near-optimal partial chunks instead of whole chunks.
  • Linearization-aware package relay visualization — show how the BIP 331 package primitives interact with cluster mempool on peer-to-peer announcements.
  • Embeddable mode for Delving Bitcoin / Optech / BIP readers — a single-scenario, single-panel mode with a configurable JSON scenario so contributors can author their own cases inline in technical writeups.
  • Community-authored scenarios. A JSON upload UI that lets anyone create a scenario from their own mempool state or hypothetical attack and share it via URL.

Built With

Share this project:

Updates