atlas-p2p

Summary

atlas-p2p is the networking crate for validator-to-validator communication in the Rust workspace. It wraps libp2p, defines the Atlas network protocol payloads, manages peer sets, and exposes an adapter plus publisher interface that the node runtime uses to publish proposals, votes, heartbeats, and state-sync requests.

This crate is the transport layer, not the consensus engine itself. Consensus and runtime code depend on it to move messages and track peers, while keeping the higher-level protocol decisions elsewhere.

Why This Crate Exists

• encapsulate libp2p setup and swarm behavior
• define Atlas-specific request/response and gossip message structures
• provide a transport adapter that turns swarm events into runtime-facing events
• manage peer discovery, active/reserve peer sets, and address knowledge
• expose a narrow publisher interface for the node runtime and proposal service

Current Role In The Workspace

atlas-p2p currently owns five related concerns:

1. libp2p swarm construction and behavior wiring
2. Atlas-specific network protocol messages and bundles
3. adapter event translation between libp2p and runtime code
4. peer management and peer scoring
5. test and fallback network abstractions such as the in-memory network

It is the main transport dependency of the runtime. atlas-node builds a Libp2pAdapter, and atlas-consensus relies heavily on its peer manager and related abstractions.

Public Surface

Top-Level Modules

• adapter
• behaviour
• builder
• codec
• config
• error
• events
• in_memory
• key_manager
• message
• peer_manager
• ports
• protocol
• telemetry
• traits
• utils

Main Public Reexports

• Libp2pAdapter
• P2pConfig
• PeerManager

Important Types

• P2pConfig
• Libp2pAdapter
• AdapterCmd
• AdapterEvent
• P2pBehaviour
• PeerManager
• PeerCommand
• PeerEvent
• TxRequest
• TxBundle
• CheckpointState
• AdapterHandle

Important Traits

• ports::P2pPublisher
• traits::Network

Key Modules

• `lib.rs`: public export surface
• `config.rs`: network configuration model
• `builder.rs`: swarm construction, transport setup, gossipsub config, and bootstrap dialing
• `behaviour.rs`: composed libp2p behavior and core topic subscription
• `adapter.rs`: runtime-facing libp2p adapter and main event loop
• `events.rs`: composed libp2p event enum and runtime-facing adapter events
• `protocol.rs`: request/response protocol for tx fetches, state sync, checkpoints, and pending-by-sender queries
• `ports.rs`: P2pPublisher trait and AdapterHandle implementation
• `peer_manager.rs`: peer registration, scoring, active/reserve rotation, and peer stats updates
• `message.rs`: higher-level cluster message wrapper for proposal and vote traffic
• `in_memory.rs`: test-oriented in-memory network implementation with dedup behavior
• `telemetry.rs`: transport-level metrics

Inputs And Outputs

Inputs

• P2P configuration such as listen addresses, bootstrap peers, and keypair path
• runtime publish commands for topics and request/response messages
• swarm events from libp2p
• peer information and node stats updates

Outputs

• gossiped proposal, vote, heartbeat, and tx traffic
• request/response exchanges for state sync and pending transaction retrieval
• runtime-facing AdapterEvent values
• updated peer manager state and address knowledge
• transport telemetry counters

Internal Dependencies

Workspace Dependencies

• atlas-common

This crate sits directly on top of the shared types layer and below consensus/runtime logic.

External Dependencies That Shape The Design

• libp2p for transport, discovery, gossip, request/response, identify, ping, and Kademlia
• tokio for async orchestration
• serde and bincode for protocol serialization
• sha2 and hex for dedup-style message IDs and hashing helpers
• metrics for network instrumentation

Used By

These packages depend directly on atlas-p2p today:

• atlas-consensus
• atlas-node

Observed usage in the workspace includes:

• `runtime/builder.rs`: node runtime creates Libp2pAdapter, command channels, and AdapterHandle
• `rpc/server.rs`: proposal gRPC service is generic over P2pPublisher
• `block_producer.rs`: block producer publishes over P2pPublisher
• `maestro/events.rs`: node runtime reacts to AdapterEvent values and updates peer stats
• `sync_driver/request.rs`: sync driver uses P2pPublisher to request state and pending transactions
• `cluster/core.rs`: consensus runtime owns a shared PeerManager
• `consensus/engine.rs`: consensus engine uses peer data and address conversion helpers

Protocol Model

The network behavior assembled in `behaviour.rs` combines:

• identify
• ping
• optional mdns
• optional kademlia
• gossipsub
• request/response

The current core gossip topics are:

• atlas/heartbeat/v1
• atlas/proposal/v1
• atlas/vote/v1
• atlas/tx/v1

The request/response protocol in `protocol.rs` supports:

• transaction fetches by tx ID
• state sync requests by height and last hash
• checkpoint-assisted state bundles
• pending transaction retrieval by sender and nonce range

Runtime Integration Model

The main runtime-facing seam is the Libp2pAdapter in `adapter.rs`.

Its role is to:

• run the swarm event loop
• translate low-level libp2p events into AdapterEvent
• accept AdapterCmd commands from higher layers
• perform heartbeat and maintenance ticks
• keep address knowledge and peer state in sync

AdapterHandle then exposes a smaller P2pPublisher interface to the rest of the runtime so those layers do not need to manipulate the swarm directly.

Peer Management Model

PeerManager in `peer_manager.rs` keeps:

• known peers
• active peers
• reserve peers
• max sizes for active and reserve sets

It also includes:

• score comparison based on reliability and latency
• demotion and reserve placement on disconnect
• one-step rotation between reserve and active peers
• stats updates tied to last-seen freshness

This is one of the main ways consensus and runtime logic reason about peer quality without directly touching libp2p internals.

Testing

The crate relies on module-local tests rather than a separate integration test suite.

Coverage includes:

• configuration cloning and option preservation
• address parsing and swarm builder helper behavior
• stable gossipsub content-based message IDs
• topic subscription set shape
• adapter command wrapping in AdapterHandle
• peer manager registration, rotation, and scoring behavior
• protocol serialization roundtrips
• in-memory network delivery and dedup behavior
• error rendering and telemetry labels

Risks Or Design Tension

Mixed Abstraction Layers

This crate exposes both:

• a real libp2p transport adapter used by runtime code
• a higher-level Network trait with an in-memory implementation used for tests and abstraction

That is useful, but it means the crate carries both production transport code and a parallel simulated-network seam.

Broad Surface Area

atlas-p2p bundles transport setup, peer management, protocol messages, adapter orchestration, and testing utilities in one place. The crate boundary is still coherent, but it is fairly wide.

PeerManager Is Widely Shared

PeerManager is used beyond the adapter itself, especially by consensus code. That makes it a de facto shared policy object, not just a transport helper.

Feature-Gated Discovery

mDNS is behind a crate feature and configuration flag, while Kademlia is runtime-toggle-based. That flexibility is useful, but it means discovery behavior depends on both build-time and runtime switches.

Open Questions

• should the Network trait and InMemoryNetwork remain here long term, or move to a more explicitly test-oriented crate
• should peer scoring and rotation policy stay transport-local, or migrate toward consensus/runtime ownership
• should the Atlas protocol message layer split more cleanly from libp2p adapter code if the transport surface grows

Relevant Files

• `Cargo.toml`
• `lib.rs`
• `config.rs`
• `builder.rs`
• `behaviour.rs`
• `adapter.rs`
• `events.rs`
• `protocol.rs`
• `ports.rs`
• `peer_manager.rs`
• `message.rs`
• `in_memory.rs`
• `telemetry.rs`
• `runtime/builder.rs`
• `rpc/server.rs`
• `cluster/core.rs`