P2P-NETWORK

Timeline

• 2026-05-29 — 67e498e — chore: fix math issues (#350)
• 2026-05-28 — d45eed2 — Chore: mirror blochain specs into github/mdbook (#347)
• 2026-05-18 — 58b5698 — chore(blockchain): migrate contributor emails to @logos.co (#338)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-01-19 — f24e567 — Chore/updates mdbook (#262)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-09-25 — a3a5b91 — Created nomos/raw/p2p-network.md file (#169)

Revision History

Introduction

The Logos Blockchain peer-to-peer (P2P) network serves as the comprehensive communication layer connecting Logos Blockchain nodes. Its primary functions include facilitating the mempool for transaction dissemination and enabling block propagation. This specification leverages established, publicly available protocols to ensure robust performance. The Logos Blockchain P2P network is designed to scale according to the project's requirements, supporting efficient communication with low bandwidth and minimal latency.

Participants, or peers, operating Logos Blockchain nodes encompass a diverse array of machine specifications, ranging from laptops to dedicated servers, as well as various operating systems and geographic locations. A key priority is to streamline communication for non-technical users, ensuring accessibility. This entails enabling peers to remain reachable—ideally even with limited connectivity or when situated behind a router—thereby enhancing inclusivity and usability across the network.

Overview

The Logos Blockchain network constitutes a foundational element of the communication infrastructure, addressing several critical challenges:

• Peer Connectivity: Establishing mechanisms for peers to join and connect to the network.
• Peer Discovery: Enabling peers to locate and identify other participants within the network.
• Message Transmission: Facilitating the efficient exchange of messages among peers across the network.

The Logos Blockchain network uses production-tested protocols to ensure all of the above is achieved.

Network Protocols Details

Transport

The Logos Blockchain network extensively leverages the libp2p suite of plug-and-play protocols, which forms a foundational component for delivering the essential functionalities outlined previously.

At its core, the Logos Blockchain network employs the QUIC transport protocol. QUIC provides rapid connection establishment and offers several advantages, including enhanced NAT traversal capabilities stemming from its UDP foundation. Additionally, its default multiplexing feature simplifies configuration processes.

Peer Discovery

Following an evaluation of existing protocols and network requirements, the optimal approach for the Logos Blockchain is to leverage the established libp2p stack, incorporating libp2p-kad for peer discovery. This provides a robust, modular, and scalable solution that seamlessly integrates with other libp2p protocols (e.g., gossipsub, identify, ping), enabling support for large-scale, dynamic networks with eventual consistency and resilience.

The Logos Blockchain P2P network integrates a combination of libp2p's Kademlia and Identify protocols to facilitate peer discovery. Kademlia enables the identification and connection to new peers by employing proximity-based heuristics, optimizing the discovery process. Complementing this, the Identify protocol supports the exchange of peer information, including details about the protocols each peer supports, thereby enhancing interoperability and network coordination.

The specific protocols to be negotiated are:

• Kademlia: /logos-blockchain/kad/{version} for main network and /logos-blockchain-testnet/kad/{version} for public testnet.
• Identify: /logos-blockchain/identify/{version} and /logos-blockchain-testnet/identify/{version} for public testnet.

Current versions are 1.0.0.

The Logos Blockchain team acknowledges that the current Kademlia DHT implementation is only optimal for the V1 solution, as it is a heavier protocol for the limited utility the Logos Blockchain actually requires. However, it remains a viable interim approach. An ideal protocol would feature:

• A lightweight design, excluding the DHT which is of no use for the Logos Blockchain network.
• Lightweight and highly-scalable eventual consistency for network membership, supporting +10k nodes (ideally unbounded in practice).

This will be worked on in the future.

NAT Traversal

Network Address Translation (NAT) poses a common challenge in peer-to-peer networks. The Logos Blockchain network prioritizes seamless, configuration-free connections among peers to accommodate participants with varying levels of technical expertise, ranging from none to advanced. Simplicity is a critical objective, given the goal of enabling nodes to operate on standard hardware, such as laptops.

To achieve this, the Logos Blockchain employs a tailored set of solutions adapted to the user's specific configuration. Comprehensive details are provided in the NAT Solution Specification.

[1.0.1] P2P Nat Solution

Gossiping

The Logos Blockchain leverages gossipsub for its messaging capabilities. This works in combination with the above exposed peer discovery protocol and NAT traversal solution as they are members of the same libp2p stack. It automatically leverages kademlia connections to keep an updated list of available peers in the network.

Logos Blockchain gossiping uses two major topics. One dedicated to mempool and one for block dissemination:

• Mempool: /logos-blockchain/mempool/{version} for mainnet. /logos-blockchain-testnet/mempool/{version} for testnet. Current version is 1.0.0.

• Blocks: /logos-blockchain/cryptarchia/{version} for mainnet. /logos-blockchain-testnet/cryptarchia/{version}for testnet. Current version is 1.0.0.

  gossipsub is openly customizable but it is encouraged to have a peering degree of at least 8 peers.

Bootstrapping

The Logos Blockchain P2P network is engineered for simplicity and ease of use. Upon initial connection, nodes in the network connect to publicly designated nodes to acquire the essential information required to become fully operational. Further details regarding this process are elaborated in the bootstrapping specification.

[1.0.1] P2P Network Bootstrapping

Message Encoding

Messages that goes through wire follow a specific encoding scheme defined in the following specification.

[1.0.1] Network Wire Format