Files

DanS 4caf2fc68f Add BIP39 seed phrases (SilentDragonXLite-compatible) and HD transparent keys

Derive transparent (t-addr) keys from the HD seed and add BIP39 mnemonic seed
phrases that are byte-for-byte compatible with SilentDragonXLite, so the same
24 words recover the same shielded and transparent addresses in either wallet.

HD transparent keys:
- Derive t-keys from the seed at m/44'/coin'/0'/0/i (were random CKeys).
- CHDChain gains a version-gated transparent counter; existing wallets load
  unchanged. GenerateNewKey routes through DeriveNewChildKey when enabled
  (-hdtransparent, default on).
- Restore from a seed hex via -hdseed with gap-limit pre-derivation; birthday
  pinned to genesis so the rescan is not clipped.

BIP39 seed phrases:
- Wire the vendored trezor BIP39 lib (src/crypto/bip39) into the build, fix its
  BIP39_WORDS guard, and disable the insecure mnemonic cache.
- Match SDXLite exactly: English wordlist, empty passphrase, PBKDF2 64-byte
  seed, coin type 141, ZIP-32 m/32'/141'/i' and BIP44 m/44'/141'/0'/0/i. Store
  the 32-byte entropy and expand to the 64-byte seed on demand.
- Restore via -mnemonic, create via -usemnemonic, reveal via z_exportmnemonic.

Verified by gtests including a known-answer BIP39 seed vector and z/t address
derivation checks (src/gtest/test_hdtransparent.cpp, test_mnemonic_compat.cpp).
Docs in doc/hd-transparent-keys.md and doc/seed-phrase.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-06 01:57:18 -05:00

3.3 KiB

Raw Blame History

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 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.

3.3 KiB Raw Blame History