Backing Up and Exporting Wallets

The SDK provides methods for backing up and exporting wallets to a new device.

How it works

Backup and restore is a two-phase process: creating a backup, and later restoring from one.

Checking what can be exported

Some assets can't be included in a backup: specifically, any hardware-bound keys (keys created with Secure Element or Android Keystore) and anything that depends on them, including identifiers, DIDs, and credentials tied to those keys.

Call backupInfo() at any time to preview what would be excluded, without creating a backup file. This is the best way to check before starting a backup/restore flow, especially if you want to warn a user about what they would lose.

The same breakdown is returned as unexportable in the response from createBackup(), so you don't need a separate backupInfo() call just to find out what was left out of a backup you've already made.

warning

Assets tied to hardware-bound keys are never included in a backup and cannot be recovered by restoring one. These assets cannot be transferred to a new device.

Creating a backup

Call createBackup(password, outputPath) to encrypt the current wallet database and write it to a file. The password derives the encryption key, so it's required again to unpack the backup later; there's no recovery without it.

The response includes the backup file path, a historyId for the backup event, and the same unexportable breakdown described above.

Restoring a backup

Restoring follows a two-phase commit:

1. unpackBackup(password, inputPath) — decrypts the backup and makes it the active database for subsequent SDK calls. Returns metadata about the backup (database version, hash, creation timestamp).

2. Inspect the restored state as needed.

3. Either finalizeImport() to commit, replacing and deleting the original database, or rollbackImport() to discard the restored data and continue on the original.

Only one restore can be pending at a time; unpackBackup fails if a prior restore hasn't been finalized or rolled back yet.

Method reference

Method	Description
createBackup(password, outputPath)	Creates an encrypted backup file of the wallet database.
backupInfo()	Returns what would be excluded from a backup, without creating one.
unpackBackup(password, inputPath)	Decrypts a backup and activates it for the current session. Must be followed by finalizeImport or rollbackImport.
finalizeImport()	Commits to the restored database, replacing the original.
rollbackImport()	Discards the restored database and reverts to the original.

History

Backup and restore actions are recorded in wallet history (Backup entity, Created / Restored actions), so they're auditable like any other operation.