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.

Generated with the assistance of AI (Claude).

Co-Authored-By: HAL 9000

Author: tnull

contrib/ldk-server-config.toml

@@ -9,6 +9,15 @@ 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 and no legacy `keys_seed` file exists, a fresh
+# 24-word mnemonic is generated on first start. Defaults to "<storage_dir>/keys_mnemonic".
+#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. 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 present on installs initialized before mnemonic support)
   tls.crt                # TLS certificate (PEM)
   tls.key                # TLS private key (PEM)
   <network>/                # e.g., bitcoin/, regtest/, signet/
@@ -161,6 +162,20 @@ 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.
+- `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`.
+
+For backwards compatibility, if neither field is configured and a `keys_seed` file exists at the
+storage root, ldk-server will continue to use it.

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 present on installs initialized before mnemonic support. |
 | `<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, on legacy installs, `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.