Descendant Limit

What Is the Descendant Limit?

The descendant limit is a mempool policy rule in Bitcoin Core that restricts how many unconfirmed child transactions can chain off a single unconfirmed parent transaction. Under the default configuration used from Bitcoin Core 0.12 through version 30, no transaction in the mempool could have more than 25 descendants (including itself), and the combined virtual size of all those descendants could not exceed 101 kvB (kilovirtual bytes). A symmetric limit applies to ancestors: no transaction could have more than 25 unconfirmed ancestors totaling 101 kvB.

These are relay and mempool-admission policies, not consensus rules. Miners can include any valid transaction in a block regardless of how many unconfirmed relatives it has. However, because almost all nodes enforce these defaults, transactions violating the limits will not propagate through the network and will not reach miners under normal conditions.

The limits were introduced by developer Alex Morcos in 2015 (merged in PR #6654 and PR #6771) to bound the computational cost of maintaining the mempool. Every time a node evaluates whether to accept, evict, or mine a transaction, it must traverse the chain of dependent transactions. Without limits, an attacker could construct arbitrarily long chains that consume excessive CPU and memory during these operations.

How It Works

When a new transaction arrives at a Bitcoin Core node, the mempool admission logic checks two package constraints before accepting it:

1. Ancestor check: count every unconfirmed transaction that the new transaction depends on (directly or transitively). If the count exceeds the ancestor limit or the combined virtual size exceeds the ancestor size limit, the transaction is rejected.
2. Descendant check: for every ancestor of the new transaction already in the mempool, count how many descendants it would have after the new transaction is added. If any ancestor would exceed the descendant limit or the descendant size limit, the transaction is rejected.

Node operators can adjust these limits using command-line arguments, but deviating from defaults means the node will relay transactions that most peers will reject, reducing propagation effectiveness.

Default Values (Pre-Cluster Mempool)

From Bitcoin Core 0.12 through version 30, the default limits were:

# Bitcoin Core configuration options
-limitancestorcount=25      # Max unconfirmed ancestors (including tx itself)
-limitancestorsize=101      # Max total kvB of ancestor package
-limitdescendantcount=25    # Max unconfirmed descendants (including tx itself)
-limitdescendantsize=101    # Max total kvB of descendant package

These four values together defined a "transaction package": the set of all connected unconfirmed transactions that must be considered as a group for fee evaluation and block template construction.

Cluster Mempool (Bitcoin Core 31.0+)

Bitcoin Core 31.0, released in April 2026, replaced the per-transaction ancestor and descendant limits with a cluster-based approach. Under the new model, all connected unconfirmed transactions form a "cluster," and the limits apply to the cluster as a whole:

# Bitcoin Core 31.0+ cluster limits
Cluster transaction limit: 64
Cluster size limit: 101 kvB

This design simplifies fee evaluation. Transactions within a cluster are ranked by chunk feerate: the feerate of the optimal set that would be mined together. This ranking drives block template selection, mempool eviction, and fee estimation. The higher per-cluster transaction count (64 vs. 25) gives protocols more room to attach children without hitting limits, while the total size cap prevents memory exhaustion.

Why It Matters

CPFP Fee Bumping

The descendant limit directly impacts child-pays-for-parent (CPFP) fee bumping. CPFP works by creating a high-fee child transaction that spends from a low-fee parent. Miners evaluate the parent and child together, and the child's high fee pulls the effective feerate of the package above the threshold for inclusion in a block.

If the parent already has 24 descendants in the mempool, the descendant limit prevents any additional child from being added. This means the parent transaction cannot be fee-bumped via CPFP. For single-party transactions this is rarely a problem, but for multi-party protocols like Lightning, it creates a critical vulnerability.

Transaction Pinning

Transaction pinning exploits the descendant limit to prevent an honest party from fee-bumping a shared transaction. In a Lightning commitment transaction, both channel parties have outputs they may need to spend. A malicious counterparty can fill the descendant budget by attaching many low-fee children to their own output, blocking the honest party from adding a CPFP child to their output.

This attack is especially dangerous for time-sensitive transactions. If a Lightning commitment transaction cannot be confirmed before an HTLC timeout, the honest party may lose funds. For a detailed analysis of these dynamics, see Bitcoin fee market dynamics and transaction pinning attacks.

Use Cases

CPFP Carve-Out

To address the pinning problem for two-party protocols, Bitcoin Core 0.19.0 introduced the CPFP carve-out. This exception allows one additional descendant beyond the limit, provided the extra child is small (under 10 kvB) and has exactly one unconfirmed ancestor. The carve-out was specifically designed for Lightning's two-party commitment transactions, ensuring that each party could always attach at least one CPFP child.

The carve-out was removed in Bitcoin Core 31.0 as part of the cluster mempool transition, since it was incompatible with the new cluster-based architecture. Its functionality has been superseded by TRUC (v3) transactions and ephemeral anchors.

Anchor Outputs in Lightning

Lightning's anchor output design works within the descendant limit by adding two small outputs to each commitment transaction: one for each channel party. All non-anchor outputs are locked with a one-block relative timelock (using OP_CHECKSEQUENCEVERIFY), preventing them from being spent while the commitment transaction is unconfirmed. This ensures neither party can fill the descendant budget through non-anchor outputs.

Each party can then spend only their own anchor output to create a CPFP child. Combined with the carve-out (pre-v31) or TRUC transactions (post-v28), this guarantees each party can always fee-bump the commitment transaction.

TRUC Transactions and Ephemeral Anchors

TRUC (v3) transactions, introduced in Bitcoin Core 28.0 via BIP 431, enforce a much stricter topology: exactly one unconfirmed parent and one unconfirmed child. The parent can be up to 10,000 vB and the child up to 1,000 vB.

# TRUC (v3) transaction topology rules
V3_DESCENDANT_LIMIT = 2   # Parent + one child only
Max parent size: 10,000 vB
Max child size: 1,000 vB

This tight constraint eliminates descendant-based pinning entirely: there is no room for an adversary to attach extra children. Combined with ephemeral anchors (BIP 433) and pay-to-anchor (P2A) outputs, the newer design replaces Lightning's two anchors with a single keyless anchor. The commitment transaction pays zero fee, and all fee responsibility shifts to the CPFP child.

Package Relay

Package relay allows nodes to evaluate and relay groups of related transactions together rather than individually. Bitcoin Core 28.0 introduced one-parent-one-child (1p1c) opportunistic package relay, enabling a low-feerate parent to propagate alongside its fee-bumping child. Full ancestor package relay (BIP 331) remains under active development.

Package relay interacts with descendant limits because the package must satisfy all policy rules as a unit. Under the cluster mempool, packages are evaluated against the cluster limits rather than the legacy per-transaction limits, which simplifies relay logic and reduces edge cases.

Risks and Considerations

Pinning Remains Possible

While TRUC transactions solve descendant-based pinning for protocols that opt in, non-TRUC transactions still face the standard cluster limits. Multi-party protocols using legacy transaction versions can still be pinned if an adversary fills the cluster budget. Protocol designers must carefully choose transaction versions and output structures to mitigate this risk.

Consolidation and Batching Constraints

Exchanges and payment processors that batch withdrawals often create long chains of unconfirmed transactions. If a batch transaction has many outputs and recipients spend them before the batch confirms, the descendant limit (or cluster limit) can prevent further spending. This forces operators to manage UTXO consolidation carefully and avoid creating deep unconfirmed chains during network congestion.

Policy vs. Consensus

The descendant limit is a policy rule, not a consensus rule. Different nodes can run different limits, and miners can override them entirely. This means that a transaction rejected by default policy may still appear in a block if a miner accepts it directly. However, relying on direct miner submission bypasses the peer-to-peer relay network and introduces centralization risk, since only well-connected parties can submit transactions out-of-band.

Transition Period

The shift from per-transaction limits (25 ancestors/descendants) to per-cluster limits (64 transactions) in Bitcoin Core 31.0 changed how protocols interact with the mempool. Wallet software, Lightning implementations, and fee-bumping tools all required updates. During the transition, nodes running different versions may disagree on which transactions are acceptable, temporarily reducing relay consistency. For a deeper look at how the cluster mempool redesign affects fee estimation and mining, see the cluster mempool research article.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.