ave-network

Peer-to-peer networking layer for the Ave ledger stack.

ave-network provides the libp2p-based transport and routing runtime used by Ave nodes. It packages discovery, request-response messaging, peer monitoring, connection policies, and network sizing into a single crate that higher-level runtimes can embed directly.

This crate is meant for consumers that need the network subsystem without pulling in the full ave-core runtime.

What this crate provides

• NetworkWorker<T>, the main event loop that drives the network runtime
• NetworkService, the command interface used by the rest of the application
• Config, RoutingConfig, and ControlListConfig for network setup
• libp2p transport composition with TCP, DNS, Noise, Yamux, Identify, Kademlia, and request-response
• node role modelling through NodeType
• monitoring integration through the Monitor actor
• metrics registration hooks
• host-aware sizing through MachineSpec and MachineProfile

When to use ave-network

Use ave-network when you need:

• Ave-compatible peer discovery and messaging
• a reusable libp2p worker that can be embedded in another runtime
• control over the network layer independently of the full ledger runtime

If you need the complete node stack, use ave-core instead.

Installation

[dependencies]
ave-network = "0.9.1"

Core concepts

NetworkWorker<T>

NetworkWorker<T> is the main runtime component. It owns the libp2p swarm, receives commands, processes swarm events, tracks peer state, and coordinates retries and buffering.

NetworkService

NetworkService is the application-facing handle used to send commands into the worker. It is the bridge between the rest of the runtime and the network event loop.

Config

Config defines:

• safe mode (safe_mode)
• node role (Bootstrap, Addressable, or Ephemeral)
• listen and external addresses
• boot nodes
• routing settings
• control-list settings
• memory-based connection limits
• message and queue byte caps

MachineSpec

MachineSpec and MachineProfile let the network backend tune itself to a target machine class. If you do not provide one, the crate auto-detects host RAM and CPU parallelism.

Configuration example

[network]
safe_mode = false
node_type = "bootstrap"
listen_addresses = ["/ip4/0.0.0.0/tcp/4001"]
external_addresses = ["/dns4/node.example.com/tcp/4001"]

[[network.boot_nodes]]
peer_id = "12D3KooW..."
address = ["/dns4/bootstrap.example.com/tcp/4001"]

[network.memory_limits]
type = "percentage"
value = 0.8

The memory limit policy can also be disabled or configured as an absolute MB threshold.

Safe mode

Config::safe_mode starts the networking layer in an isolated maintenance mode.

In this mode the worker still starts, listens, and reports Running, but it:

• does not bootstrap or dial peers
• does not send outbound application messages
• does not deliver inbound application traffic to the runtime
• closes or discards network traffic instead of participating normally

This is useful when a higher-level runtime wants local queries and maintenance operations without joining the peer-to-peer network.

Embedding example

use ave_common::identity::{KeyPair, KeyPairAlgorithm};
use ave_network::{Config, NetworkWorker, NodeType};
use tokio_util::sync::CancellationToken;

fn build_config() -> Config {
    Config::new(
        NodeType::Bootstrap,
        vec!["/ip4/0.0.0.0/tcp/4001".to_string()],
        Vec::new(),
        Vec::new(),
    )
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let keys = KeyPair::generate(KeyPairAlgorithm::Ed25519)?;
    let config = build_config();
    let graceful = CancellationToken::new();
    let crash = CancellationToken::new();

    let _worker = NetworkWorker::<()>::new(
        &keys,
        config,
        None,
        graceful,
        crash,
        None,
        None,
    )?;

    Ok(())
}

In a real application, the worker is polled asynchronously and connected to the rest of the runtime through NetworkService.

Network roles

• Bootstrap: intended to be reachable and participate in peer discovery
• Addressable: intended to accept inbound connectivity while operating as a regular node
• Ephemeral: intended for short-lived or non-addressable participants

Message flow

At a high level:

• the application sends commands through NetworkService
• NetworkWorker translates those commands into libp2p actions
• inbound events are processed and optionally forwarded to helper components
• monitor actors receive network state changes for runtime visibility

The worker also keeps bounded per-peer and global pending queues so disconnections do not turn into unbounded memory growth. Pending outbound messages are retried with backoff and can be dropped on hard send errors, queue limits, byte limits, or retry exhaustion; they are not kept forever waiting for the target peer to reconnect.

Feature flags

Ecosystem fit

ave-network sits below ave-core and above the shared types from ave-common. It is the right level if you want the Ave networking behavior without the higher-level request, governance, and persistence machinery.