Crate pallas_network2 

A new take on the Ouroboros networking stack that prioritises P2P operation over the client / server shape used by pallas-network.

The public API is split between an Interface (where IO happens) and a Behavior (the business logic), reconciled by a Manager — a layout inspired by libp2p’s swarm.

Once this crate is thoroughly tested and adopted by downstream clients, network2 is intended to replace the original pallas-network.

Usage

A typical setup pairs a transport (an Interface impl, e.g. the TCP-backed interface::TcpInterface) with a protocol (a Behavior impl, e.g. the node-to-node behavior::InitiatorBehavior) and drives both through a Manager. The manager polls the interface for IO events, hands them to the behavior, and pushes any commands the behavior emits back at the interface — leaving you to consume the behavior’s external events.

use pallas_network2::{
    behavior::{AnyMessage, InitiatorBehavior, InitiatorCommand, InitiatorEvent},
    interface::TcpInterface,
    Manager, PeerId,
};

let interface = TcpInterface::<AnyMessage>::new();
let behavior  = InitiatorBehavior::default();

let mut manager = Manager::new(interface, behavior);

manager.execute(InitiatorCommand::IncludePeer(
    "relays-new.cardano-mainnet.iohk.io:3001".parse::<PeerId>().unwrap(),
));

while let Some(event) = manager.poll_next().await {
    match event {
        InitiatorEvent::PeerInitialized(pid, _) => println!("up: {pid}"),
        InitiatorEvent::BlockHeaderReceived(pid, header, _) => {
            println!("hdr from {pid}: {} bytes", header.cbor.len());
        }
        _ => {}
    }
}

Overview

• Manager — drives a paired Interface + Behavior. Manager::poll_next advances IO and the behavior; Manager::execute forwards an external command to the behavior.
• Interface trait — the IO side. Receives InterfaceCommand (Connect / Send / Disconnect) and yields InterfaceEvent (Connected / Disconnected / Sent / Recv / Error / Idle).
• Behavior trait — the protocol logic. Defines its own Event, Command, PeerState, and Message, and emits BehaviorOutputs.
• Message trait — describes a mini-protocol message (channel id + payload encoding).
• OutboundQueue — convenience queue of pending BehaviorOutputs ready to be polled by the manager.
• PeerId, Channel, Payload, MAX_SEGMENT_PAYLOAD_LENGTH — the primitive vocabulary.

Modules

• bearer — low-level transport for reading and writing multiplexed segments.
• interface — Interface implementations for TCP connections.
• behavior — opinionated Behavior implementations for Cardano stacks.
• protocol — the Ouroboros mini-protocol definitions (handshake, chainsync, blockfetch, …).

Feature flags

• emulation — enables the emulation module, an in-memory test harness for exercising behaviors without real network IO.

Usage as part of pallas

When depending on the umbrella pallas crate (with the network2 feature), this crate is re-exported as pallas::network2.

Modules

bearer

Low-level transport layer for reading and writing multiplexed segments.

behavior

Opinionated behavior implementations for Cardano network stacks. Opinionated standard behavior for Cardano networks

emulation

Artifacts to emulate a network interface without any actual IO

interface

Network interface implementations for TCP connections.

protocol

Ouroboros mini-protocol definitions (handshake, chainsync, blockfetch, etc.). Implementations for the different Ouroboros mini-protocols

Structs

Manager

Manager to reconcile state between a network interface and a behavior

OutboundQueue

A queue of pending BehaviorOutput items ready to be polled by the manager.

PeerId

A unique identifier for a peer in the network

Enums

BehaviorOutput

Output produced by a Behavior, either a command for the interface or an event for the external consumer.

InterfaceCommand

A low-level command to interact with the network interface

InterfaceError

An error that occurred within the network interface.

InterfaceEvent

A low-level event from the network interface

Constants

MAX_SEGMENT_PAYLOAD_LENGTH

Protocol value that defines max segment length

Traits

Behavior

Describes the behavior (business logic) of a network stack

Interface

An abstraction over the network interface where IO happens

Message

Describes a message that can be sent over the network

Type Aliases

Channel

A multiplexer channel identifier for a mini-protocol.

Payload

Raw bytes of a mini-protocol message payload.