Glossary / Protocol & upgrades
Cluster mempool
- Definition
- Cluster mempool is the redesign of Bitcoin Core's waiting room that keeps every group of connected unconfirmed transactions sorted, so the node always knows which ones a miner would actually pick.
Unconfirmed transactions that spend each other form a dependency graph, and for years the software could only reason about it through crude caps on how many ancestors and descendants any single entry was allowed. Version 31.0 replaced those with one rule: no connected group larger than 64 transactions or 101 kB of virtual size. Fee bumping and replacement both became more predictable as a result.
How it works
A cluster is a connected component of the mempool. Take any unconfirmed transaction, follow every parent and child link in both directions, and everything you can reach belongs to the same cluster.
The old design tracked ancestors and descendants separately and capped each at 25, with a size ceiling alongside. That was cheap to compute and wrong in one important way. It told a node how large a family was without telling it what order a rational miner would take the family in, so the mempool could not answer its own central question: if I had to build a block right now, what would go into it?
Cluster mempool answers that by keeping every cluster linearised at all times. A linearisation is an ordering broken into chunks, each chunk being a set of transactions that would be mined together and sharing one effective fee rate. Sorting those chunks produces a fee rate diagram for the whole mempool, and the diagram is what decisions are now measured against.
The limits are 64 transactions and 101 kB of virtual size per cluster, and they replaced the ancestor and descendant counts entirely. The CPFP carveout, an exception that used to let one extra child slip past the descendant limit, was deleted along with them, because nothing is allowed to bypass the cluster count.
The payoff shows up in replacement. The older replace-by-fee rules were a handful of conditions bolted together, and they could be gamed by attaching cheap junk to a shared transaction until replacing it became absurdly expensive. Comparing fee rate diagrams gives one test instead: a replacement is accepted when it leaves the diagram no worse anywhere and better somewhere. Two new RPCs expose the machinery, getmempoolcluster for the contents and ordering of a cluster and getmempoolfeeratediagram for the diagram itself.
Where you see it
Cluster mempool surfaces as an error message when you chain too many unconfirmed spends together, and as a fee bump that succeeds where you expected trouble.
Wallet users meet the limit in one common situation: spending unconfirmed change over and over during a busy period. Sixty four transactions is generous for a person and tight for a service batching payments, which is roughly who the number was written for. When a wallet refuses a spend and mentions a cluster, the fix is to wait for a confirmation rather than to raise the fee.
The quieter benefit is that child-pays-for-parent now does what it claims. Bump a stuck transaction by spending its output at a high rate and the node can see immediately whether the pair beats what is already queued, so you get a straight answer in one step instead of an approximation.
Cluster mempool vs mempool
The mempool is the set of transactions a node is holding; cluster mempool is how one program organises that set internally. No consensus rule changed, no fork happened, and a node still running an older version holds the same transactions with worse bookkeeping. The distinction matters because the change is sometimes reported as though bitcoin gained a new network-wide rule about chains of transactions. It did not. This is policy, chosen node by node, and any operator can move the limits on their own machine with a command line argument.