Wallet Management

BTX Node uses descriptor-based HD wallets by default. This guide covers wallet creation, post-quantum P2MR addresses, backup strategies, encryption, restoration, shielded recovery caveats, and pre-upgrade 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

Current BTX transparent receive and change addresses are P2MR only. They 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 or raw change address:

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

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

The btx1z prefix indicates a post-quantum P2MR (p2mr) address format unique to the BTX network. getnewaddress and getrawchangeaddress reject legacy, SegWit, and bech32m address types; omit the type or pass p2mr.

PQ multisig

Legacy multisig address creation is disabled by BTX post-quantum policy. Use addpqmultisigaddress with ML-DSA-44 and/or SLH-DSA-128s public keys to create a P2MR multisig descriptor.

btx-cli -rpcwallet="mywallet" addpqmultisigaddress \
  2 \
  '["<mldsa_key_hex_1>","<mldsa_key_hex_2>","pk_slh(<slh_key_hex>)"]' \
  "treasury" \
  true

Shielded wallet status

Current shielded wallet support is for viewing, accounting, strict shielded-to-transparent exits, and recovery workflows. Historical private z-to-z sends, re-shielding, z_shieldfunds, z_shieldcoinbase, and z_fundpsbt are pre-sunset compatibility paths or disabled once shielded pool credits are disabled at height 125000.

Browser .btxwallet interoperability (v0.33.1+)

Browser wallet bundles are plaintext recovery files containing the PQ master seed. Handle them like private keys. Use restorewalletbundle to create a new native descriptor wallet, or importwalletbundle only for an existing blank descriptor wallet:

btx-cli restorewalletbundle "webwallet" "/secure/offline/btx-wallet.btxwallet.json" null true

btx-cli -rpcwallet="webwallet" importwalletbundle "/secure/offline/btx-wallet.btxwallet.json" true

exportwalletbundle intentionally writes a browser-compatible plaintext recovery file. Prefer backupwalletbundlearchive for routine encrypted native-node backups:

btx-cli -rpcwallet="webwallet" exportwalletbundle "/secure/offline/webwallet.btxwallet.json"

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 hierarchical deterministic key derivation. All current transparent receive and change addresses are P2MR descriptors, which means a single complete wallet backup can recover the wallet's derived P2MR keys and metadata.

Fresh wallets derive P2MR external and change descriptors. Legacy wpkh, bech32, bech32m, and non-P2MR transparent receive paths are not current BTX receive/change paths.

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 descriptor-managed P2MR paths. 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.