Skip to main content
This document covers the peer-to-peer networking layer that manages connections between StableNet nodes.
It focuses on the p2p.Server architecture, peer lifecycle management, connection types, and protocol multiplexing. For peer discovery mechanisms, see Discovery Mechanisms.
For blockchain synchronization protocols, see Chain Synchronization.
For protocol handler implementations, see Protocol Handlers.

​
Server Architecture

The P2P layer is centered around the p2p.Server structure, which manages all peer connections and implements the core networking functionality of a StableNet node.
It unifies inbound and outbound connections and acts as an intermediary between discovery protocols and protocol handlers.

​
Server Structure

The Server structure maintains the following core components:

​
Server Configuration and Initialization

Server initialization proceeds through the following steps:
  1. setupLocalNode()
    Generates the local node ID and ENR from the private key and initializes the node database.
  2. setupListening()
    Starts the TCP listener on the configured network address.
  3. setupDiscovery()
    Initializes Discovery v4/v5 and configures the discovery mixer.
  4. setupDialScheduler()
    Creates the dial scheduler for static and discovered nodes.
  5. run()
    Starts the server’s main event loop for peer event handling.
  6. listenLoop()
    Continuously accepts inbound connections.

​
Server Main Loop

The server’s main event loop performs the following tasks:
  • Handles peer addition and removal events
  • Processes connection requests from the dial scheduler
  • Gracefully shuts down all peers on termination signals
  • Broadcasts peer state changes via the event feed

​
Peer Lifecycle

Each connected peer is represented by a Peer structure that encapsulates connection state, protocol handlers, and lifecycle metadata.

​
Connection Establishment Flow

Peer connections follow this sequence:
  1. TCP connection establishment
  2. Encrypted handshake
  3. Protocol handshake and capability negotiation
  4. Protocol multiplexing setup
  5. Peer registration and event emission

​
Handshake Protocols

Connection setup consists of two handshake phases:
  1. Encryption Handshake (doEncHandshake)
    Establishes an RLPx-encrypted communication channel.
  2. Protocol Handshake (doProtoHandshake)
    Negotiates supported protocols and versions.
The protoHandshake structure includes:

​
Protocol Multiplexing

After the handshake, the server matches commonly supported protocols and assigns message code ranges to each protocol.
  • Base P2P messages: codes 0–15
  • First matched subprotocol: starting at code 16
  • Subsequent protocols: offset increased by the previous protocol’s length
This design allows multiple protocols to be safely multiplexed over a single connection.

​
Connection Types and Management

The P2P server uses connFlag values to distinguish connection types:

​
Peer Limits and Capacity

Default peer capacity control policies include:
  • MaxPeers: total peer count limit
  • MaxPendingPeers: limit on pending connection attempts (default 50 per direction)
  • DialRatio: outbound peer ratio (default 1/3)

​
Dial Scheduler

The dialScheduler manages outbound connection attempts:
  • Tracks recent dial history to avoid excessive retries
  • Prioritizes static nodes over discovered nodes
  • Enforces maximum concurrent dial limits
  • Uses exponential backoff to throttle retries for failed endpoints

​
Peer Operations and Lifecycle

​
Adding and Removing Peers

The server manages its peer set using the following methods:

​
Disconnect Reasons

Disconnect reasons are recorded using DiscReason codes:

​
Peer Event Feed

The server emits peer state changes via PeerEvent notifications:

​
Integration with the Ethereum Backend

The Ethereum backend integrates with the P2P server through protocol registration. Integration flow:
  1. eth.Ethereum.Protocols() – returns protocol definitions
  2. eth.MakeProtocols() – creates eth subprotocol handlers
  3. snap.MakeProtocols() – creates snap protocol handlers (if enabled)
  4. node.Stack.RegisterProtocols() – registers protocols with the P2P server
  5. handler.Start() – begins protocol message processing

​
Backend Access to the P2P Server

The backend maintains a reference to the P2P server for RPC services, used for:
  • NetAPI – network information queries
  • AdminAPI – peer management RPCs
  • Dynamic ENR updates

​
Configuration Flags

Key flags used to configure the P2P network include: These configuration values are applied during node initialization via SetP2PConfig() and setNodeKey().