Bitcoin Core getnodeaddresses RPC: Peer Discovery Sampling Guide

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

Purpose

Use the RPC as a local alternative input to peer discovery, not as an authoritative network directory. Address-manager contents reflect this node’s history, policy and possible attacker influence.

Count cap

Validate a non-negative requested count and expect fewer rows. Core caps results at min(2500, 23 per cent of known entries), limiting bulk topology extraction.

Timestamps

time is Unix epoch seconds for when the node was last seen. It is not a proof of freshness, successful connection or honest clock and must be sanity-bounded.

Services

The numeric service field is a bit mask of advertised capabilities. Decode against the historical protocol version and verify capabilities after connection rather than trusting the record.

Address and port

Treat endpoints as untrusted network input. Parse address family and port, prevent injection into shells or logs and apply egress and private-range policy.

Privacy and diversity

Repeated large samples can expose local topology. Restrict callers and avoid public dumps. Bootstrap selection should favour network, ASN and transport diversity rather than only recent timestamps.

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

getnodeaddresses exposes a bounded sample of local peer-discovery memory. It can seed connections, but every endpoint, timestamp and service claim still needs independent network validation.