Peer Discovery
← Back to Protocol Extensions and Quantum Signatures
Introduction
Before a node can participate in the XRP Ledger network, it must discover other nodes to connect with. The PeerFinder subsystem manages this critical process, maintaining knowledge of available peers, allocating connection slots, and orchestrating the bootstrap process when a node first joins the network.
Understanding PeerFinder is essential for debugging connectivity issues, optimizing network topology, and ensuring your node maintains healthy connections to the broader network.
PeerFinder Overview
The PeerFinder subsystem serves as the overlay network's "address book" and connection coordinator. It tracks known endpoints, manages connection slots, and makes intelligent decisions about which peers to connect to based on various criteria.
Key Responsibilities:
Endpoint Discovery: Learning about new potential peers from various sources
Slot Management: Allocating limited connection resources efficiently
Bootstrapping: Helping new nodes establish their initial connections
Address Quality Assessment: Evaluating the reliability and usefulness of known addresses
┌─────────────────────────────────────────────────────────────┐
│ PeerFinder │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Livecache │ │ Bootcache │ │ Fixed/Cluster IPs │ │
│ │ (ephemeral) │ │(persistent) │ │ (configured) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Slot Allocation │ │
│ │ & Connection │ │
│ │ Decisions │ │
│ └───────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘Bootstrapping: Joining the Network
When a node starts, it needs to establish connections to become part of the overlay network. The bootstrapping process follows a specific priority order to ensure reliable connectivity.
Bootstrapping Stages
The connection preference order is:
Fixed Peers (Highest Priority)
Configured in
rippled.cfgunder[ips_fixed]Always-connect peers that the node prioritizes
Connections are maintained persistently
Livecache (Medium Priority)
Ephemeral cache of recently seen, active peers
Populated from peer exchange messages
Addresses are validated through successful connections
Bootcache (Lower Priority)
Persistent cache stored between node restarts
Contains addresses ranked by historical usefulness
Used when Livecache is insufficient
Hardcoded Bootstrap Nodes (Fallback)
Built-in addresses used as last resort
Ensures new nodes can always find the network
Node Startup
│
▼
┌─────────────────────┐
│ Load Fixed Peers │
│ from Configuration │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Connect to Fixed │◄─── Highest Priority
│ Peers First │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Query Livecache │◄─── Recently Active Peers
│ for Active Peers │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Fall Back to │◄─── Persistent Storage
│ Bootcache │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Use Hardcoded │◄─── Last Resort
│ Bootstrap Nodes │
└─────────────────────┘Cache Management
PeerFinder maintains two distinct caches for endpoint information, each serving a different purpose.
Livecache (Ephemeral Cache)
The Livecache stores information about peers that have been recently active and validated:
Contents: Endpoints learned from peer exchange and successful connections
Lifetime: Exists only in memory; cleared on restart
Quality: High confidence addresses (recently verified)
Updates: Continuously refreshed as peers connect and exchange information
Bootcache (Persistent Cache)
The Bootcache provides persistent storage of known endpoints:
Contents: Historically useful addresses ranked by reliability
Lifetime: Persisted to disk; survives restarts
Quality: Variable; addresses may become stale
Updates: Updated based on connection success/failure history
The separation allows nodes to quickly reconnect to known-good peers (Livecache) while maintaining a fallback of historically useful addresses (Bootcache).
Slot Management
PeerFinder manages a finite number of connection "slots" to ensure resources are allocated efficiently. Different slot types serve different purposes.
Slot Types
Outbound
Connections initiated by this node
Yes
Inbound
Connections received from other nodes
Yes
Fixed
Connections to configured fixed peers
No*
Cluster
Connections to cluster members
No
*Fixed peers have reserved slots that don't count against normal limits.
Slot Allocation Process
When OverlayImpl wants to establish a connection, it requests a slot from PeerFinder:
void
OverlayImpl::connect(beast::IP::Endpoint const& remote_endpoint)
{
XRPL_ASSERT(work_, "ripple::OverlayImpl::connect : work is set");
auto usage = resourceManager().newOutboundEndpoint(remote_endpoint);
if (usage.disconnect(journal_))
{
JLOG(journal_.info()) << "Over resource limit: " << remote_endpoint;
return;
}
auto const [slot, result] = peerFinder().new_outbound_slot(remote_endpoint);
if (slot == nullptr)
{
JLOG(journal_.debug()) << "Connect: No slot for " << remote_endpoint
<< ": " << to_string(result);
return;
}
auto const p = std::make_shared<ConnectAttempt>(
app_,
io_context_,
beast::IPAddressConversion::to_asio_endpoint(remote_endpoint),
usage,
setup_.context,
next_id_++,
slot,
app_.journal("Peer"),
*this);
std::lock_guard lock(mutex_);
list_.emplace(p.get(), p);
p->run();
}PeerFinder evaluates:
Current slot utilization
Endpoint reputation
Connection diversity goals
Configuration limits
Configuration Options
PeerFinder behavior is controlled through several configuration parameters:
autoConnect
Automatically connect to discovered peers
true
wantIncoming
Accept incoming connections
true
maxPeers
Maximum total peer connections
21
outPeers
Target number of outbound connections
varies
listeningPort
Port for incoming connections
51235
ipLimit
Max connections per IP address
2
Configuration in rippled.cfg:
[peers_max]
21
[peer_private]
0
[ips_fixed]
validator1.example.com 51235
validator2.example.com 51235
[ips]
r.ripple.com 51235Endpoint Message Handling
Peers exchange endpoint information through protocol messages, helping the network maintain connectivity.
Receiving Endpoint Information
When a peer sends endpoint messages (e.g., in response to HTTP 503 with alternatives), PeerFinder processes them:
// From ConnectAttempt::processResponse
if (response_.result() == boost::beast::http::status::service_unavailable)
{
// Parse "peer-ips" header for alternative addresses
auto const ips = parse_peer_ips(response_["peer-ips"]);
if (!ips.empty())
{
// Inform PeerFinder about alternative endpoints
peerFinder().onRedirects(slot, ips);
}
}Address Quality Assessment
Not all received addresses are equally trustworthy. PeerFinder assesses quality by:
Source Reliability: Addresses from established peers rank higher
Connection Success: Successfully connected addresses are promoted
Recency: Recently validated addresses are preferred
Diversity: Addresses providing network diversity are valued
When an inbound connection succeeds, it validates that the connecting peer's advertised address is reachable, improving address quality assessment.
Peer Reservation System
The PeerReservationTable allows operators to reserve connection slots for specific trusted nodes:
Purpose: Ensure critical peers (validators, monitoring nodes) can always connect
Configuration: Specified by public key in configuration
Behavior: Reserved slots bypass normal connection limits
This is particularly useful for:
Ensuring validator connectivity
Maintaining cluster coherence
Supporting monitoring infrastructure
Integration with Overlay
PeerFinder integrates tightly with the Overlay subsystem:
┌─────────────────┐ ┌─────────────────┐
│ OverlayImpl │◄───────►│ PeerFinder │
├─────────────────┤ ├─────────────────┤
│ │ │ │
│ • connect() │────────►│ • new_outbound_ │
│ │ │ slot() │
│ │ │ │
│ • onHandoff() │────────►│ • new_inbound_ │
│ │ │ slot() │
│ │ │ │
│ • onPeer │────────►│ • on_closed() │
│ Deactivate() │ │ │
│ │ │ │
│ • Timer tick │────────►│ • autoconnect() │
│ │ │ │
└─────────────────┘ └─────────────────┘Key Integration Points:
Connection Initiation: Overlay requests slots before connecting
Slot Release: Overlay notifies PeerFinder when connections close
Auto-connect: PeerFinder periodically suggests new connections
Endpoint Updates: Overlay forwards received endpoint information
Practical Considerations
Debugging Connectivity Issues
When troubleshooting peer discovery:
Check Configuration: Verify
[ips_fixed]and[ips]sectionsMonitor Slot Usage: Use
peerscommand to see current connectionsReview Logs: PeerFinder logs connection attempts and failures
Verify Network: Ensure firewall allows port 51235 (or configured port)
Optimizing Network Position
For better network connectivity:
Configure diverse fixed peers across different geographic regions
Ensure your node accepts incoming connections if possible
Monitor and maintain good peer relationships
Consider running a public node to contribute to network health
Conclusion
PeerFinder is the intelligence behind XRP Ledger's peer-to-peer connectivity. By managing endpoint discovery, slot allocation, and bootstrapping, it ensures nodes can reliably join and maintain connections to the network. Understanding PeerFinder helps you configure nodes optimally, debug connectivity issues, and contribute to overall network health.
Last updated