Your Node's Seed & Entropy

Introduction

One master secret, many keys — by design.

Almost everything cryptographic on this node — its identity, its Nostr keys, its mesh transport keys, its Lightning wallet — grows from a single master seed: 32 bytes (256 bits) of randomness drawn once, shown to you once as a 24-word recovery phrase, and never stored in raw form anywhere.

This page explains, in both plain and technical language: where those 32 bytes come from, the guardrails that make sure they're genuinely random, how they're protected on disk, everything that is derived from them, everything that deliberately isn't, and what happens in every failure and recovery scenario.

The Big Picture

From kernel randomness to every key on the node.

Where Randomness Comes From

One named source. No mixing. No silent defaults.

Technically

The master seed is generated by MasterSeed::generate() in core/archipelago/src/seed.rs. It fills a 32-byte buffer using rand::rngs::OsRng — a thin wrapper around the getrandom(2) system call, which reads the kernel's CSPRNG (the same source as /dev/urandom, but immune to file-descriptor exhaustion and chroot tricks).

• Exactly 32 bytes / 256 bits — the maximum BIP-39 strength, encoding to 24 words.
• The RNG is named at the call site. No function anywhere in the codebase generates key material with a "default" or implicit RNG anymore (see Recent Hardening for why this is stated so emphatically).
• The RNG type is compiler-enforced. Key-generation functions only accept RNGs on a sealed allowlist (KeyGenRng in core/archipelago/src/entropy.rs). The list has exactly one production member: OsRng. No other module — not even a future refactor — can add a weaker RNG without editing the allowlist file itself.
• The buffer is zeroized (securely wiped from memory) on every path, success or failure.

// core/archipelago/src/seed.rs — the actual draw
let mut entropy = [0u8; 32];
crate::entropy::draw_key_bytes(&mut rand::rngs::OsRng, &mut entropy)?;  // guarded draw
let mnemonic = bip39::Mnemonic::from_entropy(&entropy)?;               // → 24 words
entropy.zeroize();                                                      // wipe the raw bytes

The 24 words are then stretched into the 64-byte master seed using standard BIP-39: PBKDF2-HMAC-SHA512, 2048 rounds, empty passphrase. (There is no "25th word" passphrase — your login password protects the stored backup instead, see The Encrypted Envelope.) That 64-byte seed exists only in memory, is re-computed from the words whenever needed, and is never written to disk in any form.

When the Seed Is Born

At onboarding — not at first boot.

The Five Guardrails

Defence in depth around a single random draw.

What the degenerate check does — and doesn't — do

The check (is_degenerate in entropy.rs) is deliberately closed-form: it recognises exactly three catastrophic failure shapes (all-zero, all-identical, ±1 counter). It is not a statistical entropy estimator — those can't actually distinguish good randomness from a cleverly broken RNG, and they introduce false positives. The real security load is carried by guardrails 1, 3 and 4; the degenerate check is a tripwire for total RNG failure (e.g. a zeroed buffer that was never filled).

Recent Hardening (the KEY-05 work)

This system was audited and rebuilt in early August 2026.

Triggered by the COLDCARD-class of entropy defects, a full entropy & seed-generation audit (docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md) reviewed every random draw in the codebase. The headline finding: the library used for mnemonic generation was silently choosing its own RNG via a transitive default. It happened to be a secure one — but nothing guaranteed that, and a dependency update could have changed it without any diff in Archipelago's own code.

What's Kept on Disk

The words, encrypted — and the keys, materialised. Never the raw seed.

The Encrypted Envelope

How master_seed.enc is built.

Revealing the words later (Settings → Backup → Reveal) requires an authenticated session plus re-entering your password plus your 2FA code if enabled, is rate-limited, and the words are returned only to your browser — never written to logs.

The Derivation Tree

Every key, its exact derivation, and where it lands.

All HKDF derivations are HKDF-SHA256 with a distinct, versioned info-label (the /v1 suffix means a future algorithm migration can introduce /v2 labels without ambiguity). Personal Nostr keys intentionally use the NIP-06 standard path instead of HKDF so that the same 24 words typed into any NIP-06-compliant Nostr client reproduce the same npub — your social identity is portable beyond Archipelago.

The Lightning Special Case

The one branch of the tree with a one-way gate in it.

LND (the Lightning node) uses its own seed format called aezeed, which is not BIP-39. Archipelago derives deterministic entropy from your master seed and hands it to LND at wallet-creation time — but LND then wraps it with its own internal random salt, so the resulting aezeed cannot be re-derived from your 24 words afterwards. The node therefore captures the aezeed exactly once, at init, and stores it encrypted alongside your other identity files. The Lightning seed backup screen shows it to you with the same tap-to-reveal flow as the main phrase.

Second-Order Keys

Derived from the node key — so still fully recoverable from the words.

Several subsystems derive their keys from the node identity key rather than the master seed directly. Since the node key is itself seed-derived, these all regrow from your 24 words too — the chain is words → master seed → node key → subsystem key.

What Is NOT Derived From the Seed

Independent randomness — deliberately outside the tree.

Plenty of secrets are freshly random rather than seed-derived. That's intentional: things that should die with a session, rotate freely, or belong to a third-party app must not be recoverable from your words (and mostly you wouldn't want them to be).

Failure Modes & Fallbacks

What happens when something goes wrong — at every stage.

The Restore Flow

Typing 24 words into a fresh node, step by step.

What Comes Back — and What Doesn't

SeedQR

Your words as a scannable code — using the open SeedSigner standard.

Wherever the phrase is displayed, a QR code tab is offered alongside the words. For the main (BIP-39) phrase the default format is SeedQR: each word becomes its 4-digit position in the official wordlist (24 words → 96 digits), encoded as a compact numeric QR. Hardware wallets like Passport, SeedSigner and Keystone import this format directly — so you can move your on-chain identity into cold storage without ever typing the words. A plain-text QR fallback exists for wallets that read the phrase as text.

• The QR contains exactly the same secret as the words — treat a printout or screenshot of it with identical care.
• The Lightning aezeed is deliberately never SeedQR-encoded — it isn't BIP-39, hardware wallets can't import it, and pretending otherwise would be dishonest. It gets a plain-text QR with an explanation instead.
• Restore is by typed/pasted words; there's no camera-based SeedQR scanner on the restore path today.

Honest Edges

Known trade-offs and open hardening items, stated plainly.

The audit that produced this system also tracked what it didn't fix. None of these are secrets — honest security means naming the edges:

• The words cross the RPC boundary. During onboarding the phrase travels (over HTTPS/localhost) to your browser to be displayed, sits in the browser's session storage for the wizard's duration, and is held in server memory for the 10-minute idempotence window. This is the deliberate price of a refresh-proof, display-once flow.
• Argon2 parameters are the library defaults (≈19 MiB, 2 passes) rather than the heavier profile the design doc calls for. Still memory-hard and slow for attackers; scheduled for tightening.
• 2FA backup codes carry a slight statistical bias from a modulo operation — cosmetically imperfect, cryptographically irrelevant at their length, and queued for cleanup.
• The lint ban covers the main workspace, but one small helper crate outside the workspace isn't reached by it yet.
• Best-effort backup sealing: if writing master_seed.enc fails during setup, the node continues (keys exist; only reveal is lost) — a loud failure might arguably be better, and this trade-off is under review.

Verify It Yourself

Don't trust — recompute.

Because every derivation is deterministic and label-fixed, you can independently confirm that your node's keys really do come from your words:

• Independent re-derivation script: scripts/verify-seed-derivation.py in the Archipelago source — pure-standard-library Python, no Archipelago code. Paste your mnemonic (on a trusted, offline machine) and it recomputes node_key, nostr_secret and fips_key, byte-comparing them against /var/lib/archipelago/identity/.
• Known-answer tests: the test suite pins the exact expected keys for a fixed test mnemonic; any change to the derivation math, however subtle, turns the build red.
• Non-determinism regression test: 64 consecutive generated mnemonics are asserted unique — a canary against the "predictable RNG" failure class.
• Your entropy audit trail: /var/lib/archipelago/security/csprng-readiness.jsonl records, append-only, the kernel randomness verdict at every key-generation event on this node — including the moment your seed was born.

Archipelago — Seed & Entropy Guide · reflects the KEY-05 hardened implementation (August 2026) · see also the LoRa & Mesh Guide