Bitcoin Core getmemoryinfo RPC: Locked-Memory Guide

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

Stats mode scope

Default stats describes the locked-memory manager, not resident set size, database cache, mempool or operating-system pressure. Used and free refer to current arenas and total is their managed sum. Compare with host telemetry before diagnosing an out-of-memory condition.

Locked versus total

The locked field records bytes successfully locked against swapping. If it is smaller than total, locking failed at some point and key-related data could have been swapped to disk. Treat the mismatch as a security and host-configuration signal requiring investigation, not proof that a key leaked.

Chunk counters

chunks_used and chunks_free describe allocator blocks within the managed arenas. Trends can help identify fragmentation or lifecycle changes, but counts are not byte sizes. Compare identical workloads and version-pinned builds before calling an increase a memory leak.

mallocinfo mode

On compatible glibc builds, mallocinfo returns allocator XML rather than the stats object. Availability and schema depend on the platform and allocator. Parse defensively, restrict RPC access and avoid forwarding full dumps because allocation patterns may reveal operationally sensitive information.

Operating-system controls

Memory locking can be limited by process rlimits, service-manager settings, container permissions or host policy. Confirm the effective limit and startup logs on the deployed service account. Do not grant broad privileges merely to remove a warning; use the narrowest supported capability and retain rollback.

Monitoring policy

Alert on locked below total, mode failure, abrupt managed-memory growth and correlation with wallet operations. Add RSS, swap activity, page faults, database cache and mempool metrics. Store aggregate results rather than detailed allocator data where privacy and attack-surface concerns outweigh diagnostic value.

Reproduction matrix

On a disposable encrypted wallet, test normal startup, constrained lock limits, wallet use, restart and unsupported mallocinfo. Verify byte arithmetic, conditional result types and warning routes. Never use production keys or attach raw allocator XML to a public support ticket.

Conclusion

getmemoryinfo is most valuable for confirming sensitive-memory locking and allocator behaviour. It must be combined with host telemetry and handled as potentially sensitive diagnostic evidence.