Skip to content

go-p2p

P2P networking layer for the Lethean network. Encrypted WebSocket mesh with UEPS wire protocol.

Module: forge.lthn.ai/core/go-p2p Go: 1.26 Licence: EUPL-1.2

Package Structure

go-p2p/
├── node/        P2P mesh: identity, transport, peers, protocol, controller, dispatcher
│   └── levin/   Levin binary protocol (header, storage, varint, connection)
├── ueps/        UEPS wire protocol (RFC-021): TLV packet builder and stream reader
└── logging/     Structured levelled logger with component scoping

What Each Piece Does

Component File(s) Purpose
Identity identity.go X25519 keypair, node ID derivation, HMAC-SHA256 challenge-response
Transport transport.go Encrypted WebSocket connections, SMSG encryption, rate limiting
Discovery peer.go Peer registry, KD-tree selection, score tracking, allowlist auth
UEPS ueps/packet.go, ueps/reader.go TLV wire protocol with HMAC integrity (RFC-021)
Routing dispatcher.go Intent-based packet routing with threat circuit breaker
TIM Bundles bundle.go Encrypted deployment bundles, tar extraction with Zip Slip defence
Messages message.go Message envelope, payload types, protocol version negotiation
Protocol protocol.go Response validation, structured error handling
Controller controller.go Request-response correlation, remote peer operations
Worker worker.go Incoming message dispatch, miner/profile management interfaces
Buffer Pool bufpool.go sync.Pool-backed JSON encoding for hot paths

Dependencies

Module Purpose
forge.lthn.ai/Snider/Borg STMF crypto (keypairs), SMSG encryption, TIM bundle format
forge.lthn.ai/Snider/Poindexter KD-tree peer scoring and nearest-neighbour selection
github.com/gorilla/websocket WebSocket transport
github.com/google/uuid Message and peer ID generation
github.com/adrg/xdg XDG base directory paths for key and config storage

Message Protocol

Every message is a JSON-encoded Message struct transported over WebSocket. After handshake, all messages are SMSG-encrypted using the X25519-derived shared secret.

type Message struct {
    ID        string          `json:"id"`                  // UUID v4
    Type      MessageType     `json:"type"`                // Determines payload interpretation
    From      string          `json:"from"`                // Sender node ID
    To        string          `json:"to"`                  // Recipient node ID
    Timestamp time.Time       `json:"ts"`
    Payload   json.RawMessage `json:"payload"`             // Type-specific JSON
    ReplyTo   string          `json:"replyTo,omitempty"`   // For request-response correlation
}

Message Types

Category Types
Connection handshake, handshake_ack, ping, pong, disconnect
Operations get_stats, stats, start_miner, stop_miner, miner_ack
Deployment deploy, deploy_ack
Logs get_logs, logs
Error error (codes 1000--1005)

Node Roles

const (
    RoleController NodeRole = "controller"  // Orchestrates work distribution
    RoleWorker     NodeRole = "worker"      // Executes compute tasks
    RoleDual       NodeRole = "dual"        // Both controller and worker
)

Architecture Layers

The stack has two distinct protocol layers:

  1. UEPS (low-level) -- Binary TLV wire protocol with HMAC-SHA256 integrity, intent routing, and threat scoring. Operates beneath the mesh layer. See ueps.md.

  2. Node mesh (high-level) -- JSON-over-WebSocket with SMSG encryption. Handles identity, peer management, controller/worker operations, and deployment bundles.

The dispatcher bridges the two layers, routing verified UEPS packets to registered intent handlers whilst enforcing the threat circuit breaker.