WARPNET ARCHITECTURE

This document outlines the architectural structure of Warpnet, including its core components and how they interact.

CORE COMPONENTS

1. NODE

Each Warpnet instance is a self-contained node responsible for:

• Storing the user's data locally (using BadgerDB)

• Connecting to other peers via libp2p

• Exchanging encrypted messages

• Enforcing local moderation policies: per-user blocks, mutes and keyword filters

• Queueing outbound messages for peers that are currently offline and delivering them on reconnect

Nodes form the backbone of the network. There is no central server — only independent peers.

Node types:

Warpnet defines three node roles. All nodes are technically equal in protocol rights; these roles are defined by behavior and configuration, not by protocol-level enforcement.

1. Relay Node

• Stable, publicly reachable entry point for peer discovery

• Historically called the "bootstrap node"; on the wire it still reports the legacy owner marker bootstrap for backwards compatibility

• Does not store user content or application-layer content

• Provides circuit-relay v2 service for peers behind NAT

• Fully in-memory: peerstore and routing table are discarded on shutdown

2. Member Node

• Standard user node

• Stores profile, timeline, chats, media and peer data locally

• Fully participates in message exchange

• Ships in three build flavours that differ only in how the user reaches it: the Wails desktop app, a headless remote build that serves the same UI over HTTP/WebSocket, and a headless echo service node

3. Moderator Node

• Runs a local LLM (Llama Guard 3 1B via llama.cpp) and votes on reports

• Never acts alone: every verdict is the outcome of a multi-moderator vote (see MODERATION)

• Signs every verdict it announces, so results cannot be forged

There is no "business node" role.

2. IDENTITY

Each Warpnet node has a cryptographic identity defined by the libp2p stack. This identity is used to uniquely identify peers at the transport layer and establish encrypted channels.

• Every node uses an Ed25519 keypair. No other key type is supported.

• The key is not random. It is derived deterministically:

  • a member node derives it from the user's username, password and network name, hashed with SHA-256 and used as the Ed25519 seed

  • a relay or moderator node derives it from the operator-supplied --node.seed value

• Because derivation is deterministic, the same credentials reproduce the same identity on any machine. This is how an account is recovered: there is no key file to back up, and no server that could reset it. It also means the password cannot be changed without changing the node's identity.

• The Peer ID is the multihash of the marshalled public key. For Ed25519 the key is short enough that libp2p inlines it directly (identity multihash) instead of hashing it, so the public key can be recovered from the Peer ID itself.

• The Peer ID is used for:

  • Stream routing

  • Peer discovery

  • Signature verification of message envelopes

  • Noise handshake

Warpnet does not expose Peer IDs as usernames or global handles. They are used strictly within the transport and trust layer.

Example:

12D3KooWMKZFrp1BDKg9amtkv5zWnLhuUXN32nhqMvbtMdV2hz7j ← libp2p Peer ID (Base58 of the inlined Ed25519 public key)

PSK and network access:

In addition to identity, Warpnet uses a Pre-Shared Key (PSK) to define network access boundaries.

• The PSK is injected into the libp2p transport layer using libp2p/pnet (private networks)

• Peers must prove possession of the same PSK to connect

• Even valid Peer IDs are rejected if the PSK does not match

Peer identity does not equal network membership. Only peers with a valid PSK can participate in the Warpnet overlay.

3. NETWORKING

Warpnet uses libp2p for peer discovery and transport abstraction. Networking includes:

• Direct peer-to-peer connections over TCP (IPv4 and IPv6)

• Relay node discovery via a hardcoded, per-network list of static multiaddresses

• Gossip-style broadcast (pubsub) for timeline and discovery propagation

• Circuit-relay v2 routing for peers that cannot be reached directly

• Peer prioritisation, so publicly reachable peers and relays are preferred over unreachable ones

NAT traversal uses libp2p's built-in mechanisms: AutoNAT v2 for reachability detection, DCUtR hole punching, a NAT service and UPnP/NAT-PMP port mapping. When a punch fails, the connection falls back to a relay circuit and keeps working.

Traffic camouflage:

All Warpnet transports are wrapped in a camouflage layer designed to survive Deep Packet Inspection:

• The Noise handshake and all application data travel inside a real TLS tunnel, established with a genuine browser fingerprint (uTLS) on the client side and a plausible certificate chain on the server side. To a middlebox, a Warpnet connection looks like ordinary HTTPS.

• The first bytes of the TLS ClientHello are split across very small TCP segments with randomised delays, so signature-based DPI that only inspects the first segment cannot match it.

• Active probing is resisted through SNI/ALPN consistency validation and configurable handshake timeouts.

Peer discovery and topology:

• Relay nodes provide the initial peer list via static multiaddresses compiled into the client, one list per network

• After the first connection, peers exchange further addresses

• Peers are cached locally and reconnected opportunistically

• Warpnet ingests discovery from four independent sources: the DHT, gossip (pubsub), direct streams, and mDNS on the local network

• mDNS runs on member nodes only; relay nodes use DHT and gossip

• The DHT runs in server mode under a per-network protocol prefix, and nodes announce themselves under a per-network rendezvous namespace, so separate networks never see each other

Networks:

Warpnet runs two separate networks — warpnet (mainnet) and testnet — with separate relay lists, separate PSKs and separate local databases.

4. STORAGE LAYER

Storage is local by default. Each node keeps its data in an embedded BadgerDB store on the user's own machine, and private data — chats, drafts, bookmarks, settings — never leaves it.

Two things do converge across the network automatically, by design:

• Engagement counters (views, reactions, retweets, replies, poll votes) are replicated as CRDT PN-counters over gossip, so a post's stats look the same everywhere. Each writer owns its own sub-counter, which makes the counters correct even after a node loses its local data entirely and re-syncs from peers.

• Undelivered outbound messages are queued locally and re-sent when the destination peer comes back online.

Beyond that, nothing is replicated unless the user configures backup or export manually.

5. MODERATION

Warpnet has no moderation team and no admin. Moderation is decided by a vote among independent moderator nodes, and each user additionally controls what their own node shows.

Network-level moderation:

• Anyone can run a moderator node. Each one runs Llama Guard 3 1B locally via llama.cpp.

• Only public posts and public profiles can be reported. Direct messages are never moderated — there is no mechanism for it.

• A report is broadcast to all moderators at once. Each computes its own place in an unpredictable order derived from the report itself, so nobody can arrange to judge a particular report; roughly three moderators pick it up and the rest stay out.

• Each judge fetches the content, runs its own model and votes independently, without seeing the others' opinions.

• After a ~30 second window the votes are tallied. Action requires a strict majority. The count is always made odd by a rule every node computes identically, so a tie cannot happen — and a tie or a failure to reach a majority always falls in favour of the content.

• One moderator announces the outcome, chosen by the same deterministic ordering; if it goes offline, the next in line takes over.

• Every verdict is Ed25519-signed by the announcing moderator and verified by receiving nodes against the key embedded in its Peer ID.

• Enforcement is isolation, not deletion: the verdict is published to observers, not to the offender's node, so their local view is unchanged while everyone else hides the object.

• Moderators spot-check each other with signed audit challenges drawn from already-decided content.

Local moderation:

Independently of the above, each node enforces its owner's own blocks, mutes and keyword filters locally.

6. SECURITY MODEL

Warpnet employs a layered security architecture spanning peer-to-peer transport, user interface communication, and message-level authenticity.

Peer-to-Peer Transport Security (Noise + PSK):

All connections between Warpnet nodes are secured using the Noise Protocol Framework via the libp2p transport layer.

• The Noise XX handshake provides mutual authentication and forward secrecy

• Session keys are derived using ephemeral key exchanges

• All communication is encrypted and authenticated

• The whole handshake is additionally wrapped in the camouflage TLS tunnel described under NETWORKING

Additionally, all nodes must present a valid Pre-Shared Key (PSK) to participate in the Warpnet overlay. The PSK acts as a cryptographic admission token.

Message-level authenticity:

Every protocol message carries an Ed25519 signature over its body and timestamp, verified against the public key recovered from the sender's Peer ID. Moderation verdicts are signed the same way and dropped if verification fails.

PSK Generation:

The PSK is deterministically derived from:

• The network identifier (warpnet or testnet; the alias mainnet normalises to warpnet)

• The major version number of the release

• A fixed domain constant, iterated through SHA-256

The three inputs are concatenated and hashed with SHA-256.

This means a node can only join peers running the same network and the same major version. Note that the PSK does not attest to the node's source code — a codebase-integrity check is not part of PSK derivation.

7. CONSISTENCY MODEL

Warpnet implements a hybrid consistency model combining local transactional guarantees with eventual global consistency across the peer-to-peer network.

Local Consistency (ACID):

Each Warpnet node uses an embedded BadgerDB key-value store, which provides:

• ACID properties for local operations

• Strict write ordering for messages and state transitions

• Deterministic merge behavior via sortable keys (prefixed by a reversed timestamp)

This ensures that within a single node:

• Messages are stored and processed in a defined, conflict-free order

• Timeline entries and chats are persisted reliably, even across crashes

• Local views are fully consistent and fault-tolerant

Global Consistency (Eventual):

Between nodes, Warpnet relies on eventual consistency:

• Messages may arrive in any order and with delay

• Engagement counters converge through CRDT PN-counters replicated over gossip, so they need no coordination and survive total local data loss

• There is no global clock, only logical timestamps and per-node counters

• Timeline reconstruction is based on:

  • Origin node ID

  • Origin user ID

  • Local message timestamp

Each node independently merges remote updates into its local view. Apart from the CRDT counters, there is no centralized coordination or conflict resolution mechanism.

Summary:

Local state is strictly ordered and consistent. Global state is eventually convergent but unordered.

MEMBER NODE ARCHITECTURE

A Member Node is the core unit of Warpnet used by regular users. It consists of several internal components that handle message intake, routing, storage, and optional propagation to the network. The architecture is designed to separate responsibilities, enforce local privacy boundaries, and support modular extension.

INPUT LIFECYCLE (USER → NETWORK)

1. FRONTEND INPUT

A member node exposes exactly one canonical handler per route, and three different front ends reach it:

• Desktop: a Vue 3 single-page app bundled into the binary and rendered by Wails as a Site Specific Browser (SSB) — a dedicated application window for a single source, without the menus, toolbars and browser chrome unrelated to that one site. UI calls reach the node in-process over a loopback stream, using the same protocol IDs as the network.

• Remote: the same Vue app served over HTTP by a headless build of the member node, with calls carried over a WebSocket. Frames are encrypted with AES using a key derived from the node password, so the dashboard can be reached from a browser on another machine.

• Mobile: the Android client (a Tusky fork) runs its own thin libp2p node, pairs with the user's member node over a dedicated stream route, and is then advertised as an alias of that node.

Whichever path a request takes, it is dispatched to the same handler and the same repository code.

2. BACKEND COMPONENT

• The backend (or "core") handles persistence and network propagation

• It receives the message from the frontend layer and:

  • Writes it to BadgerDB using a deterministic key

  • Optionally forwards it to other peer nodes via libp2p (using gossip broadcast or a direct stream)

3. NETWORK DISSEMINATION (OPTIONAL)

Based on node settings and message type, the message may be:

• Published to the author's gossip topic (public posts)

• Sent directly to specific recipients (private messages)

• Withheld entirely (private or draft content)

WARPNET RELAY NODE ARCHITECTURE

A Relay Node (historically called a bootstrap node, and still identified that way on the wire for backwards compatibility) is a special-purpose libp2p node used to help new peers join the network. It performs peer discovery, propagates routing information, and relays traffic for peers that cannot be reached directly. It does not access or store user content or timelines.

RESPONSIBILITIES

• Accept inbound peer connections using Noise + PSK

• Act as an entry point for peer discovery

• Provide circuit-relay v2 service for nodes behind NAT

• Host a DHT server and participate in the discovery pubsub topic

• Answer node metadata requests on a single public stream route

Relay nodes do not coordinate with each other and run no consensus protocol of their own.

INTERNAL COMPONENTS

1. CORE

The Relay Node is initialized with:

• Noise protocol (encrypted and authenticated transport), wrapped in the camouflage TLS layer

• PSK-gated access

• Static public address, listening on both IPv4 and IPv6

• Circuit-relay v2 service, with per-peer reservation and circuit limits

• Full resource manager and connection limits

2. DISCOVERY

Handles:

• Initial peer exchange

• Maintenance of a known-node address book

• Exposure to the gossip layer

• Rate limiting of inbound discovery, so a burst of peers cannot exhaust the node

3. PUBSUB

• Enables lightweight gossip-based dissemination of discovery announcements

4. DISTRIBUTED HASH TABLE (DHT)

• Runs in server mode under a per-network protocol prefix

• Provides routing for peer lookup and rendezvous-based discovery

• State is ephemeral (in-memory only)

5. IN-MEMORY PEERSTORE

• Stores peer information (Peer ID, addresses)

• Does not persist to disk

• Cleared on shutdown

STREAM BEHAVIOR

Relay Nodes do not respond to or emit user-level content streams (e.g. timeline, chat). They register exactly one stream handler:

• Node metadata retrieval: /public/get/info/0.0.0

All Warpnet protocol IDs carry a version suffix; the bare path without it is not a valid protocol ID.

PSK AND ACCESS CONTROL

• The PSK is derived and required at startup

• If the connecting peer does not present a matching PSK, the connection is rejected before the Noise handshake can complete

• This prevents unauthorized nodes from discovering or accessing the Relay Node

NETWORK BEHAVIOR

• Relay Nodes force public reachability, overriding AutoNAT detection: they sit on a static public address by definition, and NATed peers need the relay before they can help confirm it

• Circuit-relay v2 is enabled so NATed peers can communicate through them

• Hole punching (DCUtR) and the NAT service are enabled to help connecting peers upgrade to a direct connection

Note that relay service, hole punching and the NAT service are enabled on every node role, not only on relays — a member node with a static public address can relay for others too. What is unique to a Relay Node is the forced public reachability and the absence of any application state.

PERSISTENCE AND MEMORY

• All data is kept in memory

• No filesystem writes occur

• Relay nodes are stateless and disposable by design