WEAVE Protocol Architecture

ELI5

WEAVE is four postal-sorting machines stacked inside one box: the first sorts letters into a causal order (proto.rs), the second picks the fastest van route (network.rs), the third decides which van is root of the delivery tree (convergence.rs), and the fourth stamps each letter with a tamper-proof seal (crdt.rs). No post office — every van is equal.

Technical Deep Dive

Module Map

flowchart TD
    APP["Application Layer"]
    APP --> PROTO["proto.rs\nDAG construction\nAlgorithm 1"]
    APP --> NET["network.rs\nTransport selection\nEMA latency"]
    APP --> CONV["convergence.rs\nSpanning tree\nClock discipline"]
    APP --> CRDT["crdt.rs\nAutomerge IPLD\nstate hash"]
    PROTO --> TRANS["Network Transports\nWebRTC · QUIC · BLE · Wi-Fi Direct"]
    NET --> TRANS
    CONV --> TRANS
    CRDT --> PROTO

WEAVE sits between the application layer and the physical transports. The four modules are imported through lib.rs, which re-exports LCBMessage, DAGNode, DAGState, Transport, TransportType, LatencyMetric, SpanningTree, ClockDiscipline, and AutomergeState.

Module Interplay on Peer Join

Sourced from the Examples scenario at the bottom of this card (new peer, five-node LAN, strict mode):

sequenceDiagram
    participant App as Application
    participant Proto as proto.rs (DAGState)
    participant Net as network.rs (Transport)
    participant Conv as convergence.rs (SpanningTree)
    participant CRDT as crdt.rs (Automerge)
    App->>Proto: add_message(genesis LCBMessage)
    Proto-->>App: enqueue (dependencies_remaining = 0)
    App->>Net: update_latency(peer, measured_ms)
    Net-->>Net: EMA = 0.8·old + 0.2·measured
    Conv->>Conv: recompute() every tree_recompute_interval_ms
    Conv-->>App: root = min-latency peer
    App->>CRDT: merge(op)
    CRDT-->>App: new state_hash

Six Formal Theorems

WeaveConfig Presets

Source: mesh-node/src/lib.rs lines 94–121.

TimeChain Standard Integration

WEAVE is one of three nodes in the TimeChain Standard:

• Architecture A: WEAVE → TNP
• Architecture B: WEAVE → ForkNode → VEST
• Architecture C: WEAVE → ForkNode-VEST (combined)

The server-demotion principle means any peer may declare itself document-authoritative, but no peer is privileged by code. Every operation is content-addressed with BLAKE3(DAG-CBOR(op)).

Key Terms

• LCB → Latency-Based Causal Broadcast; the core WEAVE primitive combining physics-aware latency bounds with Byzantine tolerance
• WeaveConfig → Runtime configuration struct; controls P99 targets, delivery bounds, clock tolerance, and spanning-tree refresh rate
• Server demotion → Design principle: servers are ordinary peers; no peer is privileged in protocol code
• TimeChain Standard → Family of protocols (WEAVE, ForkNode/FNP, VEST) sharing cryptographic foundations
• MsgID → 32-byte Blake3-based message identifier used for deduplication across routes

Q&A

Q: What happens if clock_tolerance_ms is exceeded at runtime? A: ClockDiscipline::within_tolerance() returns false. The default WeaveConfig sets clock_tolerance_ms: 1, so a ±2 ms peer clock drift already fails the tolerance check, which should trigger rejection or quarantine of the offending peer’s messages per LC1 budget.

Q: Why does WeaveConfig::new() not exist — only default(), strict(), and relaxed()? A: The three presets map directly to deployment scenarios (production, lab/strict testing, WAN/relaxed). Freeform construction is not exposed to prevent misconfigured p99_latency_ms values that would silently invalidate Theorem 1.

Q: Which module is the single source of truth for duplicate detection? A: DAGState in proto.rs. The messages: BTreeMap<MsgID, DAGNode> map serves as the deduplication index; add_message returns Err("Duplicate message") if the key exists.

Examples

A new peer joins a five-node LAN running strict mode. Its first message has no parents (genesis node in the DAG). proto.rs adds it to delivery_queue immediately (zero dependencies_remaining). convergence.rs is concurrently running Prim’s algorithm every 100 ms; it elects the peer with latency_ms = 3 as tree root. network.rs updates EMA for the new peer’s BLE link. crdt.rs stamps a new state_hash after the operation merges. Total path: ≤ 5 ms under strict config.