Document mnemonic-based node entropy configuration

Update the example config and operator-facing docs to reflect the new
default of a BIP39 mnemonic at `<storage_dir>/keys_mnemonic`, the
mutually exclusive `[node.entropy]` options, and the legacy `keys_seed`
backwards-compatibility path. Update the backup table to list both
files so legacy operators don't lose track of their existing seed.


Co-Authored-By: HAL 9000

Author: tnull

contrib/ldk-server-config.toml

@@ -9,6 +9,18 @@ alias = "ldk_server"                          # Lightning node alias
 #rgs_server_url = "https://rapidsync.lightningdevkit.org/snapshot/v2/"  # Optional: RGS URL for rapid gossip sync
 #async_payments_role = "client"               # Optional async payments role: "client" or "server"
 
+# Node entropy settings
+[node.entropy]
+# Path to a BIP39 mnemonic file. If unset, a fresh 24-word mnemonic is generated on
+# first start. Defaults to "<storage_dir>/keys_mnemonic".
+# CLI/env: --node-entropy-mnemonic-file / LDK_SERVER_NODE_ENTROPY_MNEMONIC_FILE
+#mnemonic_file = "/tmp/ldk-server/keys_mnemonic"
+# Legacy: path to a raw 64-byte seed file used by ldk-server installs initialized before
+# BIP39 mnemonic support. Configure this explicitly to keep using an existing keys_seed file.
+# CLI/env: --node-entropy-seed-file / LDK_SERVER_NODE_ENTROPY_SEED_FILE
+# Mutually exclusive with `mnemonic_file`.
+#seed_file = "/tmp/ldk-server/keys_seed"
+
 # Storage settings
 [storage.disk]
 dir_path = "/tmp/ldk-server/"                 # Path for LDK and BDK data persistence, optional, defaults to ~/Library/Application Support/ldk-server/ on macOS, ~/.ldk-server/ on Linux

docs/configuration.md

@@ -151,7 +151,8 @@ Two resolution methods are supported via the `mode` field:
 
 ```
 <storage_dir>/
-  keys_seed              # Node entropy/seed
+  keys_mnemonic          # BIP39 mnemonic (default for new installs)
+  keys_seed              # Legacy raw seed (only used when explicitly configured)
   tls.crt                # TLS certificate (PEM)
   tls.key                # TLS private key (PEM)
   <network>/                # e.g., bitcoin/, regtest/, signet/
@@ -161,6 +162,23 @@ Two resolution methods are supported via the `mode` field:
     ldk_server_data.sqlite # Payment and forwarding history
 ```
 
-The `keys_seed` file is the node's master secret, required to recover on-chain funds.
-`ldk_node_data.sqlite` holds channel state, both are required to recover channel funds. See
-[Operations - Backups](operations.md#backups) for backup guidance.
+The mnemonic (or, for legacy installs, the raw seed) is the node's master secret, required to
+recover on-chain funds. `ldk_node_data.sqlite` holds channel state, both are required to recover
+channel funds. See [Operations - Backups](operations.md#backups) for backup guidance.
+
+### Node entropy (`[node.entropy]`)
+
+By default, ldk-server reads or generates a 24-word BIP39 mnemonic at `<storage_dir>/keys_mnemonic`,
+which can be imported into any standard BIP39-compatible wallet to recover on-chain funds. The
+defaults can be overridden under `[node.entropy]`:
+
+- `mnemonic_file`: path to the BIP39 mnemonic file. Defaults to `<storage_dir>/keys_mnemonic`. If
+  the file does not exist on first start, a fresh 24-word mnemonic is generated and written.
+  CLI/env: `--node-entropy-mnemonic-file` / `LDK_SERVER_NODE_ENTROPY_MNEMONIC_FILE`.
+- `seed_file`: path to a raw 64-byte seed file. Provided for backwards compatibility with installs
+  initialized before BIP39 mnemonic support. Mutually exclusive with `mnemonic_file`.
+  CLI/env: `--node-entropy-seed-file` / `LDK_SERVER_NODE_ENTROPY_SEED_FILE`.
+
+Legacy raw-seed installs are not auto-detected. To keep using an existing
+`<storage_dir>/keys_seed`, set `seed_file` explicitly or use the corresponding CLI argument or
+environment variable.

docs/operations.md

@@ -48,7 +48,8 @@ setup):
 
 | File                                   | Priority     | Description                                                                |
 | -------------------------------------- | ------------ | -------------------------------------------------------------------------- |
-| `<storage_dir>/keys_seed`              | **Critical** | Node identity and master secret. Required to recover on-chain funds.       |
+| `<storage_dir>/keys_mnemonic`          | **Critical** | BIP39 mnemonic. Required to recover on-chain funds. Default for new installs. |
+| `<storage_dir>/keys_seed`              | **Critical** | Legacy raw seed file. Only used when explicitly configured. |
 | `<network_dir>/ldk_node_data.sqlite`   | **Critical** | Channel state and on-chain wallet data. Required to recover channel funds. |
 | `<network_dir>/ldk_server_data.sqlite` | Nice-to-have | Payment and forwarding history                                             |
 
@@ -195,6 +196,6 @@ Data is stored in per-network subdirectories (`bitcoin/`, `testnet/`, `signet/`,
 etc.) under the storage root. This means you can run multiple networks from one storage
 directory without conflicts.
 
-The `keys_seed` file is shared across networks (stored at the storage root, not per-network).
-Keys are split by network at the derivation path level, so the same seed will produce
-different keys.
+The `keys_mnemonic` file, or an explicitly configured legacy `keys_seed`, is shared across
+networks (stored at the storage root, not per-network). Keys are split by network at the
+derivation path level, so the same mnemonic/seed will produce different keys.