archetech / archon / 34134905697

87%

push

github

docs: Write down how to recover a node after losing state (#1069)

A gatekeeper database can be rebuilt from the chain and from peers, but the
node cannot reach that resync unaided: keymaster reports ready only once its
own node DID resolves, and every service that could repopulate the database
waits on keymaster being healthy. The way out is a node ID the wallet has
never seen, because keymaster creates a missing one rather than waiting for
it. None of that was written down anywhere -- deployment.md mentions
ARCHON_NODE_ID once, in an environment table, as an alias created on first run.

The procedure also makes Bitcoin and Zcash balances read zero while the
temporary ID is set, because the watch-only wallet name is derived from the
node ID. Nothing is lost -- the descriptors come from the wallet seed, and the
original Core wallet is still there under its own name -- but an operator
meeting that mid-recovery has every reason to read it as loss, so it is stated
where they will be when they see it.

A second procedure covers the hidden service that keeps being advertised after
its container dies, so the doc is not built around a single entry.

Placed beside deployment.md rather than inside it: section 12 there is
symptom-shaped, seven short "X Not Working" entries, and the file is already
933 lines against an open complaint that configuring a node means reading 402
of them (#984).

Refs #449, #915


Claude-Session: https://claude.ai/code/session_01GYGMfX3foBcVqP7AQNXjWj

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

3926 of 4515 branches covered (86.95%)

Branch coverage included in aggregate %.

8573 of 8999 relevant lines covered (95.27%)

721.29 hits per line