tsunagi/docs/mainline-dht.md

# Mainline rendezvous

`tsunagi up` enables public Mainline DHT discovery. `--no-dht` disables it;
`--dht` explicitly selects the default. `--reach local` always disables it.
Manual `--peer` entries work alongside DHT or on their own. Library callers
opt in with `AgentConfig::with_dht(MainlineDiscovery::default())`; merely
constructing a configuration opens no DHT socket.

One Mainline client serves an agent's active networks. Each network gets its
own BEP44 signing seed, derived with the new `mainline-rendezvous-write-v1`
HKDF label. Existing network IDs, discovery keys and handshake keys are
unchanged. The semi-public `DiscoveryKey` is not used as signing material.
No network name, secret, or signing seed is included in a record or log.

## First contact and recovery

Each active network starts publication and lookup independently. Lookup
streams candidates to the existing dial loop, starting connections before
all slots have been read. Failed/empty rounds retry with increasing delay
(5 to 30 seconds, with jitter). An empty lookup never proves a network empty.
The first successful membership handshake, including an incoming handshake,
stops lookup. Publication continues while there are connected peers.

After the last authenticated session ends, known peers continue to be retried.
If none connects within 60 seconds, DHT lookup resumes. A successful handshake
stops it again. This policy is per network. DHT does not heal a partition in
which every component still has an authenticated neighbor.

Publisher and lookup tasks run outside the network actor, with deadlines,
bounded candidate delivery, and cancellation on deactivation or shutdown.
An unreachable DHT never prevents status, normal sessions or manual bootstrap.
The client socket is released on agent shutdown. The library uses no global
client, runtime, or mutable rendezvous table.
Client clones share that lifetime: create a new `MainlineDiscovery` for a new
agent after shutdown, including when injecting a local test client.

## Records and concurrency

The protocol uses 16 BEP44 salts (`tsunagi-rendezvous-v1` followed by the slot
byte) under the network's signing key. Every publisher chooses two distinct
slots deterministically from SHA-256 of its endpoint ID. Each value describes
only its writer: a format version, publication time, endpoint ID, one relay
URL and up to eight IP addresses. Bencoded values stay within BEP44's 1000-byte
limit. Decoding bounds every field before allocation and rejects unknown
versions, malformed records, timestamps too far in the future and stale data.

Slots hold a changing sample, not the complete membership. Overwrites are
expected and 16 is not a network-size limit. Publishing reads the latest
sequence, increments it, and uses BEP44 CAS with bounded retry on conflict.
CAS is local to each storage node and is not a distributed lock. Valid records
encountered during publication may become candidates on the next explicit
lookup; they never cause connected networks to start dialing from publication.
Lookup queries at most four slots concurrently and returns up to 16 distinct
candidates. At most 16 discovery candidates are retained by default; failed
candidates can be replaced rather than permanently excluding later results.

Values are signed but not encrypted. Possession of a discovery result grants
no network access: iroh authenticates the device and the control handshake
proves membership. Public rendezvous is not an anonymity mechanism.

## Freshness and durable state

Every five minutes (20% jitter), and on an observed endpoint-address change,
the agent publishes fresh data. The address monitor checks every five seconds
by default. Readers accept records for 15 minutes, allowing up to two minutes
of future clock skew. The host clock must therefore be reasonably accurate.
This is application freshness, not a request for DHT nodes to delete data.

BEP44 has no deletion operation. Deactivation stops publication; it never
deletes a shared slot that another member may now occupy. Records expire from
our readers even if storage nodes keep them. A restart restores identity and
active networks from `state.sqlite`, computes the same rendezvous location,
and publishes the current address. Old DHT entries and disposable cache are
not required. A publish reads sequence numbers from DHT, so restarts do not
reset the sequence of a surviving mutable item.

## Tests

The default suite uses Mainline Testnet nodes bound to loopback, real iroh
connections, real membership handshakes, and SQLite in temporary directories.
It covers concurrent publication, colliding slots, network-secret isolation,
record validation, bootstrap after all DHT records and cache disappear,
connected-state lookup suppression, isolation recovery and hung backends.
Public DHT and relay checks are opt-in and are not part of the offline suite.

Run the optional public check with:

```sh
cargo test --locked -p tsunagi --test mainline public_dht_finds_and_authenticates_two_agents -- --ignored --exact
```