Wallet Management

BTX Node uses descriptor-based HD wallets by default. This guide covers wallet creation, post-quantum addresses, backup strategies, encryption, restoration, and legacy wallet migration.

Creating a descriptor wallet

BTX does not create a default wallet on first start. Create one with the createwallet RPC:

btx-cli createwallet "mywallet"

Wallets are stored in the wallets/ subdirectory of the data directory. Each named wallet gets its own subdirectory:

Platform	Default wallet directory
Linux	~/.bitcoin/wallets/
macOS	~/Library/Application Support/BTX/wallets/
Windows	%LOCALAPPDATA%\Bitcoin\wallets\

Override the wallet location with -walletdir=/path/to/dir.

To create a wallet that is encrypted from the start, pass the passphrase at creation time:

btx-cli -named createwallet wallet_name="mywallet" passphrase="your-strong-passphrase"

Post-quantum addresses

BTX addresses use the btx1z... prefix and are secured by post-quantum cryptographic signatures:

• ML-DSA-44 (CRYSTALS-Dilithium) — primary signature scheme
• SLH-DSA-128s (SPHINCS+) — hash-based stateless backup scheme

Generate a new receiving address:

btx-cli -rpcwallet="mywallet" getnewaddress
# Returns: btx1z...

The btx1z prefix indicates a post-quantum MatRiCT (p2mr) address format unique to the BTX network. These addresses support both transparent and shielded (SMILE v2) transactions.

Backup strategies

BTX provides three tiers of wallet backup, from simple file copy to encrypted single-file archives.

backupwallet (basic)

Creates a consistent copy of the wallet database file. The destination must include the filename:

btx-cli -rpcwallet="mywallet" backupwallet /var/backups/btx/mywallet-backup.dat

backupwalletbundle (comprehensive)

Creates a directory containing the wallet backup, descriptor exports, shielded viewing-key exports, balance snapshots, integrity metadata, and a manifest:

btx-cli -rpcwallet="mywallet" -stdinwalletpassphrase \
  backupwalletbundle /var/backups/btx/mywallet-bundle

The -stdinwalletpassphrase flag prompts for the wallet passphrase on stdin without echo, and relocks the wallet after export.

backupwalletbundlearchive (encrypted single file)

Creates a single passphrase-encrypted .bundle.btx archive containing the same comprehensive bundle:

btx-cli -rpcwallet="mywallet" \
  -stdinwalletpassphrase \
  -stdinbundlepassphrase \
  backupwalletbundlearchive /var/backups/btx/mywallet.bundle.btx

This is the preferred offline backup flow when operators want a single encrypted file per wallet without relying on external archive tools.

Backup helper script

BTX ships scripts/wallet_secure_backup.py for production backup workflows that handles multiple wallets, integrity verification, and optional encrypted archive output:

python3 scripts/wallet_secure_backup.py \
  --cli build-btx/bin/btx-cli \
  --datadir /var/lib/btx \
  --output-dir /var/backups/btx \
  --encrypt-output

Backup frequency

Because BTX uses HD wallets with deterministic key derivation, a single backup is sufficient to recover all funds. However, regular backups (weekly or after significant transaction activity) preserve metadata such as labels that cannot be recovered from a chain rescan.

Wallet encryption

Encrypting a wallet protects the private keys at rest. Only private keys are encrypted; transaction history and public keys remain visible.

# Encrypt an existing wallet
btx-cli -rpcwallet="mywallet" encryptwallet "your-strong-passphrase"

# Change the passphrase
btx-cli -rpcwallet="mywallet" walletpassphrasechange "old" "new"

Warning: If the passphrase is lost, all funds in the wallet are permanently inaccessible. There is no recovery mechanism.

After encrypting or changing the passphrase, create a new backup immediately. Encryption flushes the keypool and generates a new HD seed; previous backups cannot recover coins received after the change.

Unlocking for spending

An encrypted wallet must be unlocked before signing transactions. The timeout parameter specifies how long (in seconds) the decryption key remains in memory:

btx-cli -rpcwallet="mywallet" walletpassphrase "passphrase" 120

Restoring from backup

From a basic backup

btx-cli restorewallet "restored-wallet" /var/backups/btx/mywallet-backup.dat

From an encrypted bundle archive

btx-cli -stdinbundlepassphrase \
  restorewalletbundlearchive "restored-wallet" /var/backups/btx/mywallet.bundle.btx

Verify the restoration:

btx-cli -rpcwallet="restored-wallet" getwalletinfo

The restored wallet can also be loaded in the GUI via File → Open Wallet.

HD wallet key derivation

BTX descriptor wallets use BIP 32 hierarchical deterministic key derivation. All addresses are derived from a single HD seed, which means a single backup can recover all keys and addresses at any point in time.

After migration or fresh creation, wallets use the BIP 44/49/84/86 standard derivation paths. The HD seed is generated at wallet creation time and stored encrypted if a passphrase is set.

List active descriptors:

btx-cli -rpcwallet="mywallet" listdescriptors

Migrating legacy wallets

Legacy (non-descriptor) wallets can be migrated to descriptor wallets using the migratewallet RPC:

btx-cli -rpcwallet="legacy-wallet" migratewallet

Migration may create up to three wallets:

• Primary (legacy-wallet) — descriptor wallet with all addresses and private keys.
• Watch-only (legacy-wallet_watchonly) — any watch-only scripts the original wallet tracked.
• Solvables (legacy-wallet_solvables) — scripts the wallet knows but was not watching for P2(W)SH purposes.

The same BIP 32 seed is preserved, but derivation paths switch to BIP 44/49/84/86 standards. A backup of the original wallet is saved as legacy-wallet-<timestamp>.legacy.bak in the wallet directory.

After migration, create a new backup of all resulting wallets. Addresses generated after migration use the new derivation paths and are not recoverable from pre-migration backups.