silentmode/theseus
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

BNS indexer design: Theseus's own index is a standby behind Ariadne's

Browse source 
Theseus keeps serving bns:// itself but does not run its own indexer
process while Ariadne's is healthy (pipe answers, passes the server check,
heartbeats arrive, snapshot fresh). On failure it takes over warm from
Ariadne's last snapshot, and hands back once Ariadne has been healthy for a
while. Until the Ariadne pipe exists, Theseus's indexer stays always on.
This commit is contained in:
Local Dev 2026-10-03 14:40:30 +02:00
parent adcea19f8a
commit 8b0cc00290
1 changed files with 23 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
DESIGN-bns-indexer-service.md
View file

@ -249,6 +249,29 @@ mirrored in Theseus. It lives in `policy.json`: `"power": "performance" |
- **Desktops** (no battery) never enter Economy, and the switch is hidden.
### Theseus
Theseus has its own complete BNS resolver: the **index** (`bns-indexer.js`,
a utilityProcess) and **serving** (the `bns://` protocol handler: on-chain
`h`, Sia via the gateway, `ip` with the TLS pin, `p`, signed DNS, all under
Tor or the session proxy). Serving stays in Theseus always; it costs nothing
when not in use and is what makes `bns://` work with Tor. **The index is a
standby:**
- **While Ariadne's indexer is healthy,** Theseus does not start its own at
all. That saves about 60–75 MB and its own electrum traffic.
- **Unhealthy means any of:**
- the pipe does not answer at launch;
- the pipe fails the server-process check;
- no update has arrived within the heartbeat window (a few minutes);
- Ariadne's snapshot is older than a set limit while Ariadne reports itself
running.
- **Taking over:** Theseus starts its own indexer, warm-started from
Ariadne's last snapshot file, so there is no download and no cold sync.
Lookups meanwhile keep using the source chain; nothing waits on the switch.
- **Handing back:** once Ariadne has been healthy again for a minute or two,
Theseus stops its own indexer. The delay keeps a flapping service from
starting and stopping Theseus's indexer over and over.
- **Until the Ariadne pipe exists** (migration step 2), Theseus's indexer is
its only working source and runs always, as in 0.3.70.
- **Launch:** the source chain above. In practice: Ariadne's local snapshot
file (milliseconds, parsed in Theseus's indexer process, never on the main
thread), then `subscribe` to the pipe for changes.