Back up, restore, and migrate the RGB wallet
Protect local RGB state, restore encrypted backups, and choose a privacy-aware v1-to-v2 migration.
The seed and local RGB database are separate recovery inputs. Test both before funding the wallet.
Create an encrypted backup
const backup = account.createBackup({
password: backupPassword,
backupPath: '/secure-backups/rgb-wallet.backup',
})
console.log(backup.message)Store the backup and password as sensitive recovery material, with access controls and separation appropriate to your threat model. Test readability and retention; a successful method return is not a completed recovery drill.
Restore into an empty directory
Create a fresh manager with the same seed and network. Call restoreAccountFromBackup() before opening a normal account in the destination directory.
import WalletManagerRgb from '@utexo/wdk-wallet-rgb'
const restoredManager = new WalletManagerRgb(seedPhrase, {
network: 'testnet',
indexerUrl: trustedIndexerUrl,
transportEndpoint: trustedTransportEndpoint,
})
try {
const restored = await restoredManager.restoreAccountFromBackup({
backupFilePath: '/secure-backups/rgb-wallet.backup',
password: backupPassword,
dataDir: '/app-private/wdk/rgb-restored',
})
await restored.registerWallet()
restored.syncWallet()
restored.refreshWallet()
console.log({
address: restored.getAddress(),
assets: restored.listAssets(),
transactions: restored.listTransactions(),
})
} finally {
restoredManager.dispose()
}Use an empty, private destination and do not run the original and restored wallet concurrently against the same state.
Validate the restore
Compare more than the address:
- vanilla and colored derivation paths;
- asset IDs, precision, and settled balances;
- RGB transfer history and status;
- Bitcoin transactions and unspents;
- ability to create a new backup;
- a low-value receive and transfer on a test network.
Migrate from v1
Version 1 relied on a remote RGB Node. The maintainer migration guide warns that the node operator may have learned wallet xpubs and transaction-graph metadata.
Choose one of two paths:
Privacy-preserving reset
- Create a v2 wallet with a new seed and new persistent
dataDir. - Generate recipient invoices on the new wallet.
- Transfer assets from the old wallet.
- Verify settlement and back up the new state.
- Retire the old seed according to your incident and retention policy.
This is the maintainer-recommended path when historical metadata exposure matters.
Same-seed state migration
- In a separate environment pinned to the v1 package, create and securely download the v1 backup.
- Stop and dispose the v1 wallet.
- Install v2 and restore the backup into a new local directory.
- Open v2 with the same seed, network, and restored
dataDir. - Verify all state before retiring the remote-node setup.
A same-seed restore preserves identity and state but cannot undo information already disclosed to a legacy remote node. An upgrade is not a privacy reset.
Use normal package imports in each pinned environment. A package version suffix inside an ESM import specifier, such as import x from 'package@version', is not valid npm package import syntax.