Skip to content

Architecture

The Manifest

The manifest is the only channel through which a running network is reconfigured. It is how a client, holding nothing but the root public key, learns where the network currently lives — and how the operator moves the network without touching a single client.

What it is

A root-signed, versioned document:

manifest v47   (signed by root key)
  cells:    [ { id, parameters, cert-fingerprint }, ... ]
  policy:   { N, rotation_rate, bucket_seconds, skew, low_water, ... }
  expires:  <timestamp>

Clients cache the last manifest they saw and accept a replacement only if it is root-signed and has a higher version. That version gate is the entire anti-rollback story.

Distribution is opportunistic

There is no single manifest server to attack or seize. A client needs only one path to a fresh manifest, and there are several:

  • served by any Barid node on connect,
  • gossiped peer-to-peer between clients,
  • a cold-start path (a static signed object) for a client whose every known endpoint is dead.

You do not need to reach every client — you need to reach one path per client.

What it can and cannot do

A compromised node can serve a stale manifest — it can try to keep a client on an old view of the network. It cannot forge one, because the root key that signs manifests was never on any server. The version gate means a stale manifest is at worst a delay, never a redirect to attacker infrastructure.

sequenceDiagram
    participant C as Client (has v47)
    participant N as Barid node
    C->>N: connect (derived address)
    N-->>C: manifest v48 (root-signed)
    Note over C: verify root signature ✓<br/>48 > 47 ✓ → accept
    C->>C: converge on v48

    Note over C,N: A malicious node serving v46?<br/>46 < 47 → rejected. Stale, not dangerous.

Why policy lives here, not in config

Rotation cadence, channel count N, bucket duration, skew, refresh thresholds — all of it rides in the manifest, not in client config files or server flags. Retuning any of them is a single root signature: no client update, no server redeploy.

Tunables are root-signed manifest policy

N, rotation rate, bucket granularity, mean lifetime, and the low-water threshold are carried in the manifest. They are expected to change during development, and the protocol must never assume any particular value.

Burning a server, end to end

  1. Sign manifest v48 without the compromised node.
  2. Stand up the replacement (new cert, re-signed from the root device).
  3. Publish v48 through any available path.
  4. Clients converge on their own. No client was touched.

This is the payoff of the whole trust model: reconfiguration is a signature and a publish, and the client side never moves.

Read next: address derivation — how a client turns a cell secret and the clock into an endpoint to dial.