# BIP39 seed phrases (SilentDragonXLite-compatible)

DragonX full-node wallets can be created from and restored to a **BIP39 24-word
seed phrase** that is **byte-for-byte compatible with SilentDragonXLite**: the
same words produce the same transparent (t-) and shielded (z-) addresses in
either wallet, so funds move between the light wallet and the full node with one
backup.

## What makes them compatible

Compatibility requires the mnemonic, the seed derivation, and every HD path to
match exactly. They do:

| Detail | Value (both wallets) |
|---|---|
| Word list | BIP39 English, 2048 words |
| Passphrase | empty (no "25th word") |
| Mnemonic → seed | PBKDF2-HMAC-SHA512, 2048 rounds, salt `"mnemonic"`, 64-byte output |
| Coin type | 141 (KMD SLIP-0044) |
| Shielded path | `m/32'/141'/i'` (ZIP-32) |
| Transparent path | `m/44'/141'/0'/0/i` (BIP44) |

The node stores the 32-byte BIP39 **entropy** (SilentDragonXLite's on-disk
convention) and expands it to the 64-byte seed on demand for derivation. The
node's vendored BIP39 library (`src/crypto/bip39`) is byte-identical to
SilentDragonXLite's `tiny-bip39` 0.6.2, and the derivation is anchored by a
known-answer test (`src/gtest/test_mnemonic_compat.cpp`).

## Restore from a phrase

Start the node once, on a **fresh/empty datadir**, with the phrase:

```
dragonxd -mnemonic="word1 word2 ... word24"
```

or, preferably (keeps the phrase out of your shell history and process list),
put it in `DRAGONX.conf` with tight permissions:

```
mnemonic=word1 word2 ... word24
```

On restore the node pre-derives keys and rescans from genesis to recover funds:

* `-hdtransparentgaplimit=<n>` — HD transparent keys to pre-derive (default 1000)
* `-mnemonicsaplinggap=<n>` — shielded addresses to pre-derive (default 100)

Raise these if the wallet used many addresses. Restore only works on a wallet
with no seed yet (a brand-new datadir); it refuses to overwrite an existing seed.

## Create a new phrase on the node

By default new node wallets use a random (non-mnemonic) seed. To create a new
wallet from a fresh 24-word phrase instead — so you can export it and use it in
SilentDragonXLite — start with:

```
dragonxd -usemnemonic
```

## Show / back up the phrase

For a mnemonic wallet (created with `-usemnemonic` or restored with `-mnemonic`):

```
dragonx-cli z_exportmnemonic
```

returns the 24 words and the seed fingerprint. The wallet must be unlocked.
Guard the phrase like a private key.

## Limitations

* **English + empty passphrase only.** Any other word list or a BIP39 passphrase
  would break compatibility, so they are not accepted.
* **Legacy / random-seed wallets have no phrase.** A wallet created before this
  feature (or without `-usemnemonic`) has a random seed; `z_exportmnemonic`
  returns an error for it — use `z_exportwallet` to back up the raw seed. Such
  wallets are not SilentDragonXLite-compatible.
* **Scope.** Recovers HD-derived shielded funds and transparent coinbase (see
  [hd-transparent-keys.md](hd-transparent-keys.md) for why only coinbase lands on
  t-addresses on this `ac_private=1` chain). Keys imported with `z_importkey` are
  not seed-derived and are not recovered by the phrase.

## On-disk compatibility

Mnemonic wallets set `CHDChain` version 3 (`VERSION_HD_MNEMONIC`). Older wallet
records load unchanged. Downgrading a mnemonic wallet to an older binary is not
supported.
