Nunchuk Wallet Management

Nunchuk Wallet Management

If auth or network setup is the blocker, use nunchuk-setup.

If the user asks about Platform key inspection or policy updates on an existing wallet, use nunchuk-platform-key.

Inspect

List wallets:

nunchuk wallet list

List wallets without balance lookup (faster, does not require internet):

nunchuk wallet list --no-balance

Get wallet details:

nunchuk wallet get <wallet-id>
nunchuk wallet get <wallet-id> --no-balance

Get a fresh receive address:

nunchuk wallet address get <wallet-id>

Export and Recover

Export backup material:

nunchuk wallet export <wallet-id>

Export descriptor only:

nunchuk wallet export <wallet-id> --type descriptor

Export descriptor in all format:

nunchuk wallet export <wallet-id> --type descriptor --format all

Export BSMS only:

nunchuk wallet export <wallet-id> --type bsms

Save export output to a file:

nunchuk wallet export <wallet-id> > wallet-backup.txt
nunchuk wallet export <wallet-id> --type bsms > wallet-backup.bsms

Recover from a backup file:

nunchuk wallet recover --file wallet-backup.bsms

Recover from a descriptor with a custom name:

nunchuk wallet recover --file descriptor.txt --name "Recovered Wallet"

Rename and Delete

Rename a wallet:

nunchuk wallet rename <wallet-id> --name "My Wallet"

Delete a wallet:

nunchuk wallet delete <wallet-id>

Wallet Replacement

Use wallet replacement when the user wants to replace keys or create a replacement sandbox for an existing finalized wallet.

Replacement workflow:

• If starting the replacement, run wallet replace create <wallet-id>.
• If another participant started it, run wallet replace list <wallet-id> and then wallet replace accept <wallet-id> <group-id>.
• Open the replacement sandbox with sandbox get <group-id>.
• Add or replace only the changed signer slots with sandbox add-key.
• Finalize the replacement with sandbox finalize <group-id> once every required slot is filled and synced.
• For Taproot multisig, use sandbox finalize <group-id> --value-key-set <indexes> if the user wants to choose the Value Key Set.
• After finalizing, get a fresh receive address and export a backup if the user wants one.

Create a replacement sandbox:

nunchuk wallet replace create <wallet-id>

List replacement sandboxes:

nunchuk wallet replace list <wallet-id>

Accept and join a replacement sandbox:

nunchuk wallet replace accept <wallet-id> <group-id>

Decline a replacement sandbox locally:

nunchuk wallet replace decline <wallet-id> <group-id>

Dummy Transactions

Currently dummy transactions are used to approve Platform key policy changes.

They are built as dummy PSBTs that use a dummy input and send back to the same wallet. They are only for collecting the required wallet signatures for approval, and they cannot be broadcast to the blockchain.

List pending dummy transactions:

nunchuk wallet dummy-tx list <wallet-id>

Get one dummy transaction:

nunchuk wallet dummy-tx get <wallet-id> --dummy-tx-id <id>

Sign a dummy transaction:

nunchuk wallet dummy-tx sign <wallet-id> --dummy-tx-id <id>

Cancel a dummy transaction:

nunchuk wallet dummy-tx cancel <wallet-id> --dummy-tx-id <id>

Defaults

• Prefer wallet export <wallet-id> with default options unless the user asked for a specific backup format.
• Use --json when the user needs exact machine-readable output.
• Use --no-balance for faster local wallet lookup without Electrum balance fetch.
• Treat wallet delete as destructive and only run it when the user clearly asked for removal.
• Treat wallet replacement as a sandbox workflow: create or accept the replacement, update signer slots, then finalize.

Gotchas

• wallet export defaults to descriptor export.
• wallet export supports --type descriptor and --type bsms.
• --format only applies to descriptor export.
• Export output is raw content, so redirect it to a file when the user wants a backup file.
• wallet recover accepts a descriptor file or a BSMS 1.0 backup file.
• wallet dummy-tx get shows the request type, old state, new state, and signature progress.
• wallet dummy-tx sign can use auto-detected stored keys, --fingerprint, or --xprv.
• If the recovered wallet already exists locally, the command returns already_exists instead of overwriting it.
• wallet replace create starts from the current finalized wallet signer set; if the wallet has a Platform key, that Platform key slot is cleared for replacement and the policy is carried into the sandbox.
• wallet replace accept joins the replacement sandbox and submits unchanged local wallet signers, so only changed slots normally need new keys.
• wallet replace decline records a local decline and does not delete the server-side replacement group.
• wallet delete deletes the wallet from the server and removes the local copy.