P2P Networking

Stack overview

flowchart TB
  subgraph Discovery["Peer discovery"]
    BS["Bootstrap nodes"]
    MDNS["mDNS (LAN)"]
    KDHT["Kademlia DHT random walk"]
  end

  subgraph Transport["Connection"]
    TCP["TCP/IP"]
    WS["WebSockets"]
    DNS["DNS resolution"]
  end

  subgraph Security["Upgrade"]
    Noise["Noise Protocol — encryption"]
    Yamux["Yamux — multiplexing"]
    MS["Multistream-Select negotiation"]
  end

  subgraph Protocols["Substream protocols"]
    Ping["Ping — liveness"]
    RR["Request-Response — block/tx queries"]
    Notif["Notifications — gossip, finality, sync"]
  end

  Discovery --> Transport
  Transport --> Security
  Security --> Protocols

Discovery mechanisms

Bootstrap nodes

• Predefined trusted peers in network configuration (hard-coded identities + addresses).
• On startup, the node connects to bootstrap peers to join the network and learn about additional peers.

mDNS (multicast DNS)

• Discovers peers on the same LAN via UDP broadcast.
• Useful for development, testnets, or co-located deployments.
• Enable/disable via network settings.

Kademlia DHT (random walk)

• Once connected to at least one peer, the node performs a Kademlia-based random walk on each configured chain's DHT.
• Sends

  FIND_NODE

  queries to discover more peers.
• Builds a resilient, expanding view of the network over time.

flowchart LR
  Start["Node starts"] --> Boot["Connect to bootstrap"]
  Boot --> Learn["Learn peer addresses"]
  Learn --> Walk["Kademlia random walk"]
  Walk --> More["More peers discovered"]
  More --> Walk
  MDNS["mDNS on LAN"] -.-> Learn

Connection establishment

1. Establish direct connections.
2. Negotiate shared protocol capabilities (transport, security, multiplexing).

Transport layer

Encryption and multiplexing

sequenceDiagram
  participant A as Alice
  participant B as Bob

  A->>B: TCP / WebSocket connect
  A->>B: Multistream-Select (Noise)
  Note over A,B: Encrypted channel
  A->>B: Multistream-Select (Yamux)
  Note over A,B: Multiplexed substreams
  A->>B: Open Ping / Request-Response / Notifications

Substream protocols

Peer identification

• Each node has a unique Ed25519 public key for P2P identity.
• This keypair is separate from consensus message signing keys.
• Exchanged during handshake; used to authenticate peers for the session.

midnight-cryptography/

Related skills

• midnight-consensus/

  — what validators gossip (blocks, finality)

• midnight-cryptography/

  — Noise, Ed25519 peer identity

• midnight-rpc/

  — external client access (complements P2P sync)