Documentation / 6. Backups & seeds

Chapter 6

Backups & seeds

Encrypted archives, donor snapshots, restore flow.

Every managed node can take an encrypted archive of its blockchain data directory. The pipeline:

tar β†’ gzip β†’ libsodium secretstream β†’ .ahbk on disk

The content key is sealed with libsodium secretbox using the hub’s master key (held in the vault behind fresh- ancient-confirm). Archives land in ./data/backups/ and can be:

  • Downloaded raw β€” the encrypted .ahbk, resumable via HTTP Range, decrypted locally with bin/dr-tool.mjs + the exported master key. No hub involvement in the decrypt.
  • Staged as .tar.gz β€” two-step flow: Prepare decrypts onto a staged plaintext file on the hub; Download streams it like a normal file. Expires after 30 minutes; a discard button cancels the stage.

Seeds β€” hub-wide donor snapshots

A seed is a completed backup promoted to the hub-wide donor snapshot. New installs and reseeds pull from the current seed instead of syncing the full chain from scratch β€” saves days on new-node onboarding. Seeds are delete-protected; only an Ancient Admin can retire a seed, and only by promoting a fresher one to take its place.

Managed on /admin/seeds (ancient + modern). Donor-eligibility check runs every ~23 hours; operators of eligible nodes can donate via the Seeds page. Donor contributions are rewarded with +10 Stoicism points per successful donation.

Hub-scores ledger snapshots

Separate from node backups: the hub also takes a nightly dump of its scoring tables (stoicism_accounts, stoicism_daily, stoicism_events) β€” the full ledger state β€” encrypted and stored as hub-scores-YYYY-MM-DD.ahbk. These are NOT shown in the main Backups list (operators found the tiny ~5 KB files confusing); they live in data/backups/ for ancient-admin retrieval.

Failed backup rows

Failed rows get a compact inline Delete button next to their error blurb, using the same DELETE /api/admin/backups/[id] endpoint as completed rows. No on-disk file to clean; the DB row just goes away. Double-confirm + password re-auth.

Pluggable backup destinations (local / S3 / IPFS), rule-based autonomic backup policy engine, and destination-side encryption for S3 are all queued β€” see roadmap v1.1.x.