Bitcoin Core getmempooldescendants RPC: Spend-Chain Guide

This guide explains Bitcoin Core getmempooldescendants RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Target and descendants

The target must currently exist in the node’s mempool. Descendants spend one of its outputs directly or through other unconfirmed transactions. The returned set excludes the target itself while verbose aggregate descendantcount fields include each described transaction in its own totals, a distinction tests must preserve.

Terse and verbose modes

False returns transaction IDs; true returns keyed entry objects with virtual size, fees, local admission metadata, package aggregates, wtxid and direct dependencies. Choose the mode explicitly and cap response size because a broad descendant graph can be expensive to serialise and process.

Spend-chain interpretation

A large descendant set can indicate chained payments, consolidation workflows or application fan-out. It is not inherently malicious. Map direct dependencies and relevant outputs before deciding which business action is affected, and never infer customer identity from graph shape alone.

Replacement and conflicts

Replacement can remove a transaction and its descendants or introduce a different package under local policy. Monitor replacement evidence and conflicts alongside the graph. A vanished descendant may have confirmed, been evicted or become invalid after an ancestor change; absence alone does not identify the cause.

Mining and eviction

Package feerate and ancestor relationships affect block selection, while size and count limits can constrain admission. Descendant aggregates help explain local behaviour but do not promise confirmation. Compare template or acceptance results on the exact node and avoid extrapolating to every miner.

Privacy and service design

An unrestricted endpoint can reveal local unconfirmed inventory and enable repeated expensive traversal. Keep RPC private, authorise callers and rate-limit diagnostic layers. Redact customer mappings and peer details from retained incident records while preserving hashes required for technical reproduction.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

getmempooldescendants reveals downstream unconfirmed dependencies for local policy analysis. Reliable systems treat it as a changing graph, preserve count semantics and distinguish confirmation, replacement and eviction.