Swarm Cache

Self-hosted instances can share public ESI data with each other: market history, type names, corporation and alliance records, and player structure names, so the whole swarm asks ESI for each record once instead of once per instance. Nothing private ever leaves an instance: no character data, no tokens, no accounts.

It is off unless SHARED_CACHE says open (or on) or allowlist (see Configuration):

• open shares with every instance holding the secret.
• allowlist additionally waits for each instance to be approved on the Admin page.

Joining

The secret (SHARED_CACHE_SECRET, at least 32 random characters) is the swarm's membership proof. Enabling sharing without one refuses to start, and the secret is never shown on any page.

New instances find the swarm through the SHARED_CACHE_SEEDS directory nodes, then membership spreads peer to peer about once a day. Any instance can serve as a seed for the rest, and there can be several seeds. Afterwards an operator can also add an instance by address by hand on the Admin page.

Spending fetch capacity

Pages never wait on the swarm: a miss renders its not-yet-known state and fills in when the record lands.

A dedicated warming node (SHARED_CACHE_WARM) fetches the swarm's misses of the kinds it covers on its own ESI budget and serves them. An instance that a dedicated node covers leaves a miss of that kind to the swarm for 15 minutes before spending its own call, so its budget is the last resort. A kind no dedicated node covers is fetched as before.

Trust

Trust is cryptographic and reputational:

• Every shared entry is signed by the instance that fetched it (Ed25519). The signature and shape are verified before anything is stored, and pulls require signatures: there is no bearer fallback.
• Verification against ESI is sampled, not exhaustive: new signers are checked every time, then the check rate falls with trust, drawn unpredictably per entry.
• A failed check counts against its signer with growing weight; sustained failures exclude the signer on their own. Passing checks rebuild trust, so a fixed peer earns its way back, and the operator's re-admit is the way home.
• When a signer is excluded, the worker takes back what it supplied that this instance has not fetched for itself since, and fetches it from ESI instead.
• The first key seen for an instance is the one kept. A later sighting under another key is refused and marked; removing the instance is the only way its key changes. Every member signs its own address with its own key, so an address is always its owner's word.

The member list itself is private to the swarm: fetching it needs the shared secret, and the list is sealed under a key derived from that secret. Pages show gossip-learned members under stable aliases instead of their addresses; only instances added by hand and the configured seeds show plainly.

The Sync page's Swarm Cache card shows entries applied, ESI calls saved, spot checks for and against, and each instance's trust. The operator can always add an instance by address, approve, exclude, re-admit, or remove one on the Admin page.