intermediate 60 min

Peer discovery & connection lifecycle

How nodes find peers (config, DNS, gossip, crawler) and the lifecycle of a peer connection.

Prerequisites

Complete these before starting this module:

What you'll learn

  • Explain the peer-discovery mechanisms.
  • Trace a connection from TCP/TLS to active peer.
  • Understand inbound vs outbound vs fixed connections.
Complete this module by self-assessment and a quiz. Jump to assessment

Introduction

≈60 min · Intermediate · builds on The overlay network

Watch this short video by XRPL Commons first, then dive into the details below.

How does a fresh node find anyone to talk to? In this module you'll learn the peer-discovery mechanisms (configured lists, DNS seeds, gossip and the crawler) and follow a connection's lifecycle from a raw TCP/TLS socket to an active peer, managed by PeerFinder and its slots. It's how the network heals and grows on its own.


PeerFinder Overview

In brief: the component that decides who to connect to and manages the connection slots.

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

Inside PeerFinder: the ephemeral Livecache (fresh gossip), the persistent Bootcache (survives restarts) and the configured fixed/cluster IPs all feed the slot allocation and connection decisions


Bootstrapping: Joining the Network

In brief: how a brand-new node finds its very first peers.

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:

  1. Fixed Peers (Highest Priority)
  • Configured in xrpld.cfg under [ips_fixed]
  • Always-connect peers that the node prioritizes
  • Connections are maintained persistently
  1. Livecache (Medium Priority)
  • Ephemeral cache of recently seen, active peers
  • Populated from peer exchange messages
  • Addresses are validated through successful connections
  1. Bootcache (Lower Priority)
  • Persistent cache stored between node restarts
  • Contains addresses ranked by historical usefulness
  • Used when Livecache is insufficient
  1. Hardcoded Bootstrap Nodes (Fallback)
  • Built-in addresses used as last resort
  • Ensures new nodes can always find the network

Bootstrapping in priority order: load fixed peers from configuration and connect to them first, then query the Livecache for recently active peers, fall back to the Bootcache, and as a last resort use the hardcoded bootstrap nodes

Key idea. A new node finds peers several ways at once: configured lists, DNS seeds, gossip, and the crawler. No single source is a point of failure.


Cache Management

In brief: the live and boot caches of known peer addresses.

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

In brief: how inbound, outbound, and fixed connection slots are allocated.

PeerFinder manages a finite number of connection "slots" to ensure resources are allocated efficiently. Different slot types serve different purposes.

Slot Types

Slot Type Description Counts Toward Limit
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:

PeerFinder evaluates:

  • Current slot utilization
  • Endpoint reputation
  • Connection diversity goals
  • Configuration limits

Configuration Options

PeerFinder behavior is controlled through several configuration parameters:

Parameter Description Default
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 xrpld.cfg:

[peers_max]
21

[peer_private]
0

[ips_fixed]
validator1.example.com 51235
validator2.example.com 51235

[ips]
r.ripple.com 51235

Endpoint 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:

  1. Source Reliability: Addresses from established peers rank higher
  2. Connection Success: Successfully connected addresses are promoted
  3. Recency: Recently validated addresses are preferred
  4. 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:

How Overlay and PeerFinder talk: connect() maps to new_outbound_slot(), onHandoff() to new_inbound_slot(), onPeerDeactivate() to on_closed(), and the timer tick drives 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:

  1. Check Configuration: Verify [ips_fixed] and [ips] sections
  2. Monitor Slot Usage: Use peers command to see current connections
  3. Review Logs: PeerFinder logs connection attempts and failures
  4. 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.


Connection Lifecycle


Introduction

A peer connection in the XRP Ledger overlay network goes through a well-defined lifecycle: discovery, establishment, activation, maintenance, and termination. Understanding this lifecycle is crucial for debugging connectivity issues, optimizing network performance, and implementing new networking features.

Each phase involves careful coordination between multiple subsystems, resource management decisions, and thread-safe state transitions. This lesson traces the complete journey of a peer connection through the codebase.


Lifecycle Phases

The connection lifecycle consists of five distinct phases:

The six phases of a connection: discovery (finding peers), establishment (TCP), handshake (protocol negotiation), activation (becoming an active peer), maintenance (message exchange), and termination (cleanup and removal)


Discovery Phase

Before a connection can be established, nodes must discover potential peers. The PeerFinder subsystem manages peer discovery and slot allocation.

Discovery sources include:

Fixed Peers: Configured in xrpld.cfg under [ips_fixed], these are always-connect peers that the node prioritizes.

Bootstrap Peers: Initial peers used when joining the network for the first time, typically well-known, reliable nodes.

Peer Exchange: Active peers share their known endpoints, enabling organic discovery of new nodes.


Establishment Phase

When OverlayImpl decides to connect to a peer, it creates a ConnectAttempt object that manages the asynchronous connection process:

The ConnectAttempt::run() method initiates an asynchronous TCP connection:

Using shared_from_this() ensures the ConnectAttempt object remains alive until the asynchronous operation completes, even if other references are released.


Handshake Phase

Once the TCP connection succeeds, the handshake phase begins. This involves TLS negotiation followed by protocol-level handshaking.

For outbound connections, ConnectAttempt::processResponse handles the handshake:

For inbound connections, PeerImp::doAccept handles the server side of the handshake:


Activation Phase

Once the handshake completes successfully, the peer becomes active. The OverlayImpl::activate method registers the peer in the overlay's tracking structures:

The add_active method handles the full registration process:

After activation, PeerImp::doProtocolStart begins the message exchange:


Maintenance Phase

During normal operation, peers exchange messages continuously. The maintenance phase involves:

Message Processing: Reading incoming messages and dispatching to appropriate handlers.

Health Monitoring: Tracking response times, message rates, and connection quality.

Resource Management: Ensuring fair bandwidth allocation and detecting abuse.


Termination Phase

Connections may terminate for various reasons: network errors, protocol violations, resource limits, or graceful shutdown. Proper cleanup is essential to prevent resource leaks.

The PeerImp destructor handles final cleanup:

The overlay updates its state when a peer disconnects:

void
OverlayImpl::onPeerDeactivate(Peer::id_t id)
{
    std::lock_guard lock(mutex_);
    ids_.erase(id);
}

Resource Management Throughout the Lifecycle

Every phase involves resource management decisions:

Discovery: PeerFinder limits the number of endpoints tracked to prevent memory exhaustion.

Establishment: Resource Manager checks if the endpoint has a good reputation before allowing connection.

Activation: Slots are finite resources allocated by PeerFinder based on configuration.

Maintenance: Bandwidth and message rates are monitored, with misbehaving peers penalized.

Termination: All allocated resources must be released to prevent leaks.


Thread Safety Considerations

The connection lifecycle involves multiple threads:

IO Threads: Handle asynchronous network operations.

Job Queue Threads: Process completed operations and state transitions.

Application Threads: May query peer state or initiate connections.


Conclusion

The connection lifecycle is a carefully orchestrated sequence of phases, each with specific responsibilities and resource management requirements. Understanding this lifecycle enables you to debug connectivity issues, optimize network performance, and safely implement new networking features.


Summary

This module covered how a node finds peers and manages its connections. You saw the discovery mechanisms, configured lists, DNS seeds, gossip, and the crawler, and followed a connection's lifecycle from a raw TCP/TLS socket to an active peer, managed by PeerFinder and its slots and caches. Because a node uses several discovery paths at once, no single source is a point of failure.

To remember:

  • Discovery sources: config ([ips], [ips_fixed]), DNS seeds, gossip (endpoint messages), the crawler
  • PeerFinder manages connection slots (in / out / fixed)
  • Two caches: Livecache (fresh gossip) and Bootcache (persistent, survives restarts)
  • Connection lifecycle: TCP, TLS, HTTP Upgrade, cryptographic handshake, active peer
  • /crawl on the peer port exposes overlay.active publicly: try curl -sk https://s1.ripple.com:51235/crawl
  • Fixed peers are always retried; they anchor your topology
  • Code: src/xrpld/peerfinder
  • Watch out: an unreachable peer port (NAT/firewall) leaves you outbound-only; you still work, but you give nothing back to the mesh

Next up. Connections exist; now watch them carry the real traffic. Next: the handshake and message relaying, squelching included.

Assignments

0 of 2 complete

Unlocks

Finishing this module opens up:

XRPL Academy © 2026