Step-by-step guide to setting up a BTQ wallet, generating Dilithium addresses, sending transactions, and managing keys in BTQ Core

Wallet Basics

BTQ Core wallets fully support Dilithium key management alongside traditional ECDSA keys, enabling quantum-resistant transactions.

Creating a Wallet

Standard Wallet

btq-cli createwallet "my_wallet"

Descriptor Wallet (Recommended)

btq-cli createwallet "my_wallet" false false "" false true

Both wallet types support Dilithium operations.

Generating Dilithium Addresses

New Address

# P2MR Dilithium receive address (the only supported type)
btq-cli -rpcwallet="my_wallet" getnewdilithiumaddress

# With label
btq-cli -rpcwallet="my_wallet" getnewdilithiumaddress "Mining"

# Extract just the address string
btq-cli -rpcwallet="my_wallet" getnewdilithiumaddress | jq -r '.address'

Since v0.4.2-testnet this RPC returns a JSON object — address, p2mr_id, scriptPubKey, merkle_root — not a bare address string, and the only accepted address_type is "p2mr". The older "legacy", "bech32", and "p2sh-segwit" arguments are rejected. See Dilithium Addresses.

Example

$ btq-cli -rpcwallet="my_wallet" getnewdilithiumaddress "Savings"
{
  "address": "qbtc1z...",
  "p2mr_id": "...",
  "scriptPubKey": "...",
  "merkle_root": "..."
}

Receiving Funds

Dilithium addresses work exactly like ECDSA addresses for receiving:

# Mine blocks to your Dilithium address (regtest)
btq-cli generatetoaddress 101 "qbtc1z..."

# Check balance
btq-cli -rpcwallet="my_wallet" getbalance

Sending Transactions

Create Raw Transaction

# List unspent outputs
btq-cli -rpcwallet="my_wallet" listunspent

# Create transaction
btq-cli createrawtransaction \
  '[{"txid":"abc123...","vout":0}]' \
  '{"qbtc1z...":25.0}'

Sign with Dilithium

btq-cli -rpcwallet="my_wallet" signtransactionwithdilithium "0200000001..."

Response:

{
  "hex": "02000000000101...",
  "complete": true
}

Dilithium-signed transactions are approximately 3,824 bytes (vs ~250 bytes for ECDSA), due to larger signatures and public keys.

Broadcast

btq-cli sendrawtransaction "signed_hex"

Message Signing

Sign a Message

btq-cli -rpcwallet="my_wallet" signmessagewithdilithium \
  "qbtc1z..." \
  "Hello, quantum world!"

Response: Base64-encoded signature (~3.2KB)

Verify a Message

btq-cli verifydilithiumsignature \
  "Hello, quantum world!" \
  "qbtc1z..." \
  "MEUCIQDw..."

Response: true or false

Key Import/Export

Import Dilithium Key

btq-cli -rpcwallet="my_wallet" importdilithiumkey "private_key_hex"

Dump Private Key (Future)

# Not yet implemented
btq-cli -rpcwallet="my_wallet" dumpdilithiumkey "qbtc1z..."

Key Storage

How Keys Are Stored

Unencrypted Wallet:

Database Key: (DILITHIUM_KEY, KeyID)
Database Value: Raw 2,560-byte secret key

Encrypted Wallet:

Database Key: (DILITHIUM_CRYPTED_KEY, KeyID)
Database Value: AES-256-CBC(secret_key)

The KeyID is the 160-bit hash of the public key: RIPEMD160(SHA256(pubkey))

Wallet Encryption

Dilithium keys are encrypted using the same master key as ECDSA keys:

# Encrypt wallet
btq-cli -rpcwallet="my_wallet" encryptwallet "passphrase"

# Unlock for operations
btq-cli -rpcwallet="my_wallet" walletpassphrase "passphrase" 60

Backup

Always backup your wallet! Dilithium keys are 2,560 bytes each—much larger than ECDSA keys.

Backup Wallet

btq-cli -rpcwallet="my_wallet" backupwallet "/path/to/backup.dat"

Important Notes

HD Derivation: Not yet supported for Dilithium. Each key is standalone.
Seed Phrases: Do not recover Dilithium keys. You must backup wallet.dat.
Storage: Ensure sufficient space for larger key backups.

Transaction Workflow

Complete Example

# 1. Start BTQ Core (regtest)
btqd -regtest -daemon

# 2. Create wallet
btq-cli -regtest createwallet "test"

# 3. Generate Dilithium address
ADDR=$(btq-cli -regtest -rpcwallet="test" getnewdilithiumaddress | jq -r '.address')
echo "Address: $ADDR"

# 4. Mine some blocks to fund it
btq-cli -regtest generatetoaddress 101 "$ADDR"

# 5. Check balance
btq-cli -regtest -rpcwallet="test" getbalance

# 6. Get unspent outputs
UTXO=$(btq-cli -regtest -rpcwallet="test" listunspent | jq '.[0]')
TXID=$(echo $UTXO | jq -r '.txid')
VOUT=$(echo $UTXO | jq -r '.vout')

# 7. Create destination address
DEST=$(btq-cli -regtest -rpcwallet="test" getnewdilithiumaddress | jq -r '.address')

# 8. Create raw transaction
RAW=$(btq-cli -regtest createrawtransaction \
  "[{\"txid\":\"$TXID\",\"vout\":$VOUT}]" \
  "{\"$DEST\":49.99}")

# 9. Sign with Dilithium
SIGNED=$(btq-cli -regtest -rpcwallet="test" signtransactionwithdilithium "$RAW" | jq -r '.hex')

# 10. Broadcast
btq-cli -regtest sendrawtransaction "$SIGNED"

# 11. Check mempool
btq-cli -regtest getrawmempool

RPC Reference

Command	Description
`getnewdilithiumaddress`	Generate new Dilithium address
`signtransactionwithdilithium`	Sign transaction with Dilithium
`signmessagewithdilithium`	Sign arbitrary message
`verifydilithiumsignature`	Verify Dilithium signature
`importdilithiumkey`	Import Dilithium private key

P2MR Wallet Workflows

For protocol-level documentation of the end-to-end P2MR wallet lifecycle, see:

Performance

Operation	Time
Key Generation	~2ms
Message Signing	~3ms
Signature Verification	~1.5ms
Transaction Signing	~3ms per input

Storage Requirements

Component	ECDSA	Dilithium	Ratio
Private Key	32 bytes	2,560 bytes	80x
Public Key	33 bytes	1,312 bytes	40x
Signature	~71 bytes	2,421 bytes	34x
Transaction	~250 bytes	~3,824 bytes	15x

Plan for increased storage requirements when using Dilithium extensively.

Wallet Basics

On this page