Warpnet Protocol

This document describes the peer-to-peer communication layer of Warpnet, including transport channels, routing logic, and delivery semantics. It focuses on how nodes exchange encrypted messages over libp2p.

1. Transport Protocols

Warpnet uses libp2p as its networking layer. Communication between nodes occurs over authenticated and encrypted channels using the Noise protocol and a shared PSK.

What is a libp2p stream?

A libp2p stream is:

• A logical connection, established between two peers on top of an existing libp2p connection

• Identified by a protocol ID string, such as /private/post/tweet/0.0.0

• Multiplexed: multiple streams can share a single physical connection (e.g., TCP + Noise)

• Bidirectional: both peers can read and write from/to the stream

• Automatically encrypted and authenticated using the Noise protocol + PSK

How streams are used in Warpnet

Every operation between two Warpnet nodes uses a distinct libp2p stream. For example:

• A timeline post opens a stream using protocol /private/post/tweet/0.0.0

• A request to fetch the user's timeline opens a stream /private/get/timeline/0.0.0

• A public message broadcast to a peer opens a stream /public/post/message/0.0.0

Each stream is:

1. Opened by the initiating node

2. Processed by the recipient’s stream handler, which is registered per protocol route

3. Closed once the operation is complete

Stream-level Isolation

• Stream operations are sandboxed by protocol

• Each handler in the node is registered to a specific protocol path

• Streams are subject to authorization middleware, especially for private routes (see 4. Stream Authentication Middleware)

All WarpNet protocols follow a structured URI-style format that encodes access level, operation type, resource domain, and version. This convention is used to route and dispatch messages between peers, and also to enforce access boundaries.

>>> /{visibility}/{operation}/{domain}/{version}

Where:

Segment Meaning Example visibility public or private access /private/... operation get, post, delete, etc. /post/... domain Logical entity (e.g., tweet, message, user) /tweet/, /chat/ version Semantic version of protocol /0.0.0

This makes the protocol self-descriptive and extensible without breaking compatibility. Example:

>>> /private/post/tweet/0.0.0

A private POST call to submit a new tweet using protocol version 0.0.0

Benefits of Structured Protocols

• Self-documenting: Each protocol clearly communicates its purpose

• Modular dispatch: Handlers can be dynamically mapped via URI parsing

• Access control: Easy to enforce public/private rules by prefix

• Versionable: Future changes can use semantic versions without breaking older clients

All application-layer messages are serialized as raw JSON (or binary encoding TBD), and transmitted over multiplexed libp2p streams.

Stream Format

All stream payloads are currently:

• Serialized as JSON objects (subject to change)

• Encapsulated per stream: no interleaving, each stream handles a single logical operation

• Length-prefixed (handled by libp2p's stream muxer)

2. Message Routing

When a message arrives at the node, it is routed based on its type:

• Public timeline post → sent to all known friends via public/post/timeline/0.0.0

• Private message → dialed directly to recipient via /private/get/chat/0.0.0

Routing logic is implemented in the client node, while message storage and broadcast happens in the main node.

3. Delivery Semantics

Warpnet operates under best-effort, eventually-consistent delivery:

• No strict delivery guarantees are provided

• Duplicate messages are allowed and must be filtered locally

• Each message includes a unique identifier and timestamp

• Timeline merge is deterministic per node based on user ID and timestamp

There is no centralized queue or acknowledgment mechanism. All reliability must be handled by retry or idempotent storage.