P2P Networking

The peer-to-peer (P2P) layer connects Midnight nodes and enables data exchange across the decentralized network. Midnight uses the default Polkadot SDK Rust libp2p implementation.

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

To join the network, a node must discover and connect to peers.

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

After discovery, peers:

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

This foundation supports higher-level sync and gossip protocols.

Transport layer

When node A (Alice) connects to node B (Bob):

Encryption and multiplexing

After the base transport connects, peers upgrade via negotiated protocols:

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

Each substream runs a dedicated application-level protocol:

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.

See midnight-cryptography/ for Ed25519 usage in libp2p vs GRANDPA.

Related skills

• midnight-consensus/ — what validators gossip (blocks, finality)
• midnight-cryptography/ — Noise, Ed25519 peer identity
• midnight-rpc/ — external client access (complements P2P sync)