Bitcoin Core getpeerinfo RPC: Peer Diagnostics Guide

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

Identity and privacy

addr, addrbind and addrlocal can reveal remote peers, local interfaces, proxies and externally reported addresses. Keep the RPC private, redact routine exports and avoid public dashboards that fingerprint topology. Peer subversion strings are self-declared, not authenticated identity.

Services and relay

Decode services with version-specific definitions and use relaytxes to understand what the peer requested. Offered capability does not prove correct behaviour. Verify actual headers, blocks and transactions received and distinguish block-relay roles from full transaction relay.

Traffic and time

lastsend, lastrecv and connection time use Unix seconds; byte counters are per connection. Calculate rates with a monotonic collector and handle reconnection resets. A quiet long-lived peer can still be useful, while frequent traffic can be redundant or hostile.

Latency fields

pingtime, minping and pingwait are conditional and measure round-trip behaviour, not validation speed. Avoid ranking peers by a single ping sample. Use distributions, duration and sync contribution, and do not disconnect diverse peers solely because a nearby peer is faster.

Direction and provenance

inbound distinguishes accepted from initiated connections; addnode identifies manual or connect-driven origins. Healthy topology needs role-appropriate outbound diversity and may include inbound reachability. Manual peers should not silently become the only chain view.

Synchronisation and inflight

startingheight is the peer’s advertised initial height, while synced_headers and synced_blocks show common progress and inflight lists requested block heights. Compare with the local tip and request age. Stale values require context during initial download and reorganisations.

Diagnostic matrix

On an isolated network, create inbound, outbound, manual, lagging, non-relaying and high-latency peers. Rotate connections and block responses. Verify redaction, optional-field parsing, byte resets, sync alarms and that whitelist or ban score does not substitute for content validation.

Conclusion

getpeerinfo is the principal historical peer diagnostic, but it exposes topology and unauthenticated claims. Safe monitoring combines redaction, role-aware diversity and observed relay and synchronisation behaviour.