Crate karyon_p2p 

Karyon p2p

A lightweight, extensible, and customizable peer-to-peer network stack. Multi-transport (TCP, TCP/TLS, QUIC) with pluggable custom protocols via the Protocol trait, pluggable discovery with a built-in Kademlia DHT.

Install

$ cargo add karyon_p2p

Example

An echo node: it attaches a custom protocol that broadcasts back every message it receives.

use std::sync::Arc;

use async_trait::async_trait;

use karyon_core::async_runtime::global_executor;
use karyon_p2p::{
    keypair::{KeyPair, KeyPairType},
    protocol::{PeerConn, Protocol, ProtocolID},
    Config, Error, Node, Version,
};

pub struct EchoProtocol {
    peer: PeerConn,
}

impl EchoProtocol {
    fn new(peer: PeerConn) -> Self {
        Self { peer }
    }
}

#[async_trait]
impl Protocol for EchoProtocol {
    async fn start(self: Arc<Self>) -> Result<(), Error> {
        loop {
            match self.peer.recv().await {
                Ok(msg) => self.peer.broadcast(msg).await,
                Err(Error::PeerShutdown) => break,
                Err(e) => return Err(e),
            }
        }
        Ok(())
    }

    fn version() -> Result<Version, Error> {
        "0.1.0, 0.1.0".parse()
    }

    fn id() -> ProtocolID {
        "ECHO".into()
    }
}

async {
    let key_pair = KeyPair::generate(&KeyPairType::Ed25519);

    let config = Config {
        listen_endpoints: vec!["tcp://0.0.0.0:8000".parse().unwrap()],
        discovery_endpoints: vec![
            "tcp://0.0.0.0:7000".parse().unwrap(),
            "udp://0.0.0.0:7000".parse().unwrap(),
        ],
        ..Default::default()
    };

    let node = Node::new(&key_pair, config, global_executor());

    node.attach_protocol(EchoProtocol::new)
        .await
        .expect("Attach echo protocol");

    node.run().await.expect("Run the node");

    node.shutdown().await;
};

Feature Flags

Feature	Description
smol	Use smol async runtime (default)
tokio	Use tokio async runtime
quic	Enable QUIC transport
serde	Enable serde support for p2p types

# Default (smol + TCP/TLS)
karyon_p2p = "1.0"

# With QUIC
karyon_p2p = { version = "1.0", features = ["quic"] }

# With tokio
karyon_p2p = { version = "1.0", default-features = false, features = ["tokio", "quic"] }

Architecture

                          Node
                            |
   +------------+-----------+-----------+
   |            |                       |
Discovery   PeerPool             Connector / Listener
   |            |                       |
Routing     Peers + Protocols       ConnQueue
table           |                       |
                +------- Handshake -----+
                             |
                          karyon_net (TCP / TLS / QUIC)

• Node: top-level lifecycle. Creates the discovery, pool, connector, and listener; wires them together; exposes the public API.
• Discovery: finds peers and yields them as DiscoveredPeer. Default is Kademlia DHT; custom implementations of the Discovery trait plug in.
• Connector / Listener: dial and accept connections over the configured transports, then hand them to ConnQueue.
• ConnQueue: short-lived bridge between accept/dial and handshake.
• Handshake: version + protocol negotiation. Verifies peer identity bound to the secure transport’s certificate.
• PeerPool: registry of post-handshake peers. Owns the per-peer Peer state and broadcasts lifecycle events.
• Peer / Protocol: per-peer read loop dispatching to the registered protocols. Custom protocols implement the Protocol trait.

Transport

Peers can listen and connect over multiple transports simultaneously. Configuration uses endpoint URLs (tcp://, tls://, quic://); TLS uses self-signed certs derived from the node’s keypair, and QUIC multiplexes one stream per protocol.

Discovery

Implementations of the Discovery trait yield candidate peers; the Node dials them. The default is a Kademlia DHT; plug in your own (mDNS, static, …) by implementing the trait.

Protocols

A built-in Ping keep-alive runs on every connection; everything else is a custom protocol. For TCP/TLS, protocols share a single framed connection. For QUIC, each protocol gets its own bidirectional stream.

Protocol::flags() defaults to ProtocolFlags::PREFERRED. Override to ProtocolFlags::REQUIRED for protocols every peer must speak, or ProtocolFlags::empty() for protocols that should not be advertised. Flags combine with |. Bits from ProtocolFlags::USER up are free for user meaning: Kademlia advertises such items without letting them affect peer selection; custom Discovery implementations may interpret them.

Monitor

Subscribe to node.monitor() to observe what the network is doing - connections opening and closing, peer add/remove, handshake failures, discovery lookups and refreshes. Each topic is a separate event type with its own listener; every subscriber gets every event independently.

let listener = node.monitor().register::<ConnectionEvent>();
while let Ok(ev) = listener.recv().await {
    println!("conn event: {} {:?}", ev.event, ev.endpoint);
}

Available event types: ConnectionEvent, PeerPoolEvent, DiscoveryEvent. Gated by Config::enable_monitor.

Network Security

TLS is available for TCP connections. QUIC has built-in TLS 1.3. The p2p layer generates self-signed certificates from the node’s key pair for mutual authentication.

Examples

See examples/ for a basic peer node and a chat application.

Modules

access_control 🔒

codec 🔒

config 🔒

conn_queue 🔒

connector 🔒

discovery 🔒

endpoint

error 🔒

handshake 🔒

keypair

listener 🔒

message 🔒

monitor

Responsible for network and system monitoring. Read More

node 🔒

peer 🔒

peer_pool 🔒

protocol

Defines the protocol trait. Read More

protocols 🔒

slots 🔒

tls_config 🔒

util

Bincode encode/decode helpers.

version 🔒

Structs

AllowAll

Default policy. Allows everything.

Config

Configuration for the p2p network.

DiscoveredPeer

Represents a discovered peer that the discovery protocol wants the Node to connect to.

KademliaDiscovery

Node

Central entry point for the p2p network.

Peer

A connected peer. Holds a Wire that hides the wire shape (single framed pipe vs. per-protocol streams).

PeerAddr

A peer address with protocol and priority. Lower priority number means higher preference.

PeerCandidate

A peer that has completed the handshake but has not joined the pool yet.

PeerID

Represents a unique identifier for a peer.

PeerPool

Version

Represents the network version and protocol version used in karyon p2p.

Enums

Action

The purpose of the connection.

ConnDirection

Error

Represents karyon’s p2p Error.

PeerEvent

Peer-lifecycle events. Each registered listener receives every event independently.

Protocol

Transport protocol used by a peer address.

Subject

The party being evaluated.

Traits

AccessControl

Policy that decides which peers this node talks to, and for what.

Discovery

Trait that any discovery protocol must implement.

Type Aliases

PeerEventListener

Listener returned by register_peer_events.

Result