Disaster recovery

Use this guide when something has gone wrong and you need to restore: a CloudSign node has failed, a device holding key shards is gone for good, you need to prove your recovery key still works, or you need to recover wallet assets without the Wallet-as-a-Service platform.

Configure backup and recovery covers everything you do in advance (configuring backups, downloading the recovery CLI, and building your wallet inventory), especially in its preparation checklist. This page assumes that you've completed that preparation.

If an upgrade fails or a node's database becomes corrupted, restore the database from your backup and restart the node against it. On startup, the node reloads its persisted quorums and rejoins them with its existing key shards, so you don't need to re-pair or regenerate keys. Keep these constraints in mind:

• Restore all of the node's stores as one consistent snapshot. With local storage, the stores live under /var/cloudsign and depend on each other. If you restore only part of the directory, or mix files from different snapshots, the node can end up unable to decrypt its own key shards. With PostgreSQL storage (DB_DRIVER=postgres), the node uses two databases, DB_DATA_SOURCE and TSM_DB_DATA_SOURCE; restore both to the same point in time.
• Restart the node with the same database encryption key. If you use KMS-based encryption (DB_ENCRYPTION_KEY_REF), the snapshot must include dbkey.encrypted, and the host must retain permission to decrypt with that exact KMS key. On the KMS path, if dbkey.encrypted is missing, CloudSign doesn't report a missing file. Instead, it generates a new database key, and the restored data then fails with decryption errors. If you use DB_ENCRYPTION_KEY_HEX, restart with the same hex key.
• Never restore a snapshot taken before a key reshare or quorum restructure. Resharing replaces the key shards without changing wallet addresses, so a pre-reshare snapshot silently mismatches the other quorum members' shards and signing fails.
• Restore the same CloudSign version you backed up. If you downgrade a data directory that you paired on a newer major version, the downgrade can wipe the keychain.
• Fix file ownership after a host-side restore. The CloudSign container runs as a non-root user. If you restore files as root, they cause permission denied errors at startup. To fix this, run chown -R 999:999 on the data directory.

See Set up and run CloudSign for storage options and upgrade procedures, and back up node databases for the backup side.

If a CloudSign node or mobile device that holds key shards is gone for good (the host is destroyed and has no usable database backup, or the phone is lost), the wallet key itself stays intact as long as the remaining devices can still reach the quorum's required-signatures threshold. You don't recover the key. Instead, you restructure the quorum to swap the lost device for a new one. The wallet's private key and addresses don't change.

1. Decide whether you really need to restructure. If the lost device is a CloudSign node and you have a consistent backup of its data directory, restore the node database instead. It's faster and involves no quorum change.
2. Check that you can still restructure the quorum. You must retain at least as many original members as the current required-signatures threshold. In a 2-of-3 quorum, you can lose one device and restructure. If you've lost two, you can't restructure, and you're in the independent recovery situation instead.
3. Pair and approve the replacement device, as the note above describes.
4. Restructure the quorum. In the console, open the quorum's detail page, select Restructure quorum from the Actions menu, add the new device, remove the lost one, and confirm. Manage MPC quorums describes the full procedure, including the maintenance-mode warning.
5. Decommission the lost device. After restructuring completes, the lost device's shards are obsolete and can no longer sign, but treat them as sensitive material anyway: disable or delete the device under Devices (see Manage devices), and revoke any credentials or cloud resources it used.

Restructuring is currently self-service for Cloud quorums running CloudSign 1.10.0 or later. The quorum must be active, and the new device set must include at least one device that isn't in the current quorum. Wallet-as-a-Service rejects a restructure that only removes devices. If Restructure quorum doesn't appear in the Actions menu, or the lost device belongs to a Mobile or Mixed quorum, contact Ripple support to coordinate the restructure.

Restructuring replaces the key shards without changing the wallet's underlying key, so your key shard backups stay valid and need no action. Wallet-as-a-Service binds each backup file to the wallet's key ID and quorum ID, and neither of them changes. The backup still holds the key shares of the devices that were in the quorum when you created the wallet. That doesn't affect recovery, because the recovery CLI reconstructs the private key from the backup itself rather than restoring shards to devices. After the restructure, don't restore node-database snapshots from before the restructure (see the restore constraints).

Your key shard backups are only as good as the RSA private key that decrypts them. Periodically verify that the key file is intact and that the password you hold still decrypts it. Do this at least at your annual review, whenever the person who holds the key changes, and before any planned recovery. To verify the key, run:

wallet-recovery-cli validate-private-key --private-key-file=recovery-private.hex

The command detects whether the file is encrypted, prompts for the password, decrypts the file in memory, and confirms that the result is a valid RSA private key. It never modifies the file, and it clears the decrypted key from memory when it finishes. On success, it prints:

Validation successful: password is correct and private key is valid

If you see Validation failed: incorrect password or corrupted file, first re-check the password against your secure record. If the password is right, the file is damaged. Restore it from your other secure copies or, as a last resort, switch to another recovery key pair in the kit. If the key file isn't encrypted, the command reports Private key file is not encrypted and exits without a password prompt.

If you lose the private key, or no password unlocks it, you can't use it to decrypt existing backups. Check whether the kit holds other recovery public keys whose private keys you still control. Any one of them is enough. Otherwise, create a new backup kit with a new key pair for future quorums, and contact Ripple support about wallets under the affected quorums. For more information, see Maintain your backups.

Follow this procedure when the platform is permanently unavailable and you need to move assets out of your wallets. The procedure uses the key shard backups that Wallet-as-a-Service writes to your S3 bucket to reconstruct each wallet's private key with the Wallet-as-a-Service Wallet Recovery CLI. Recovery is per wallet and interactive: the CLI prompts for passwords on the terminal and has no unattended mode, so you can't script it over your inventory. Repeat the procedure for each wallet, and plan the time this takes if you hold many wallets. If you need to recover a large number of wallets, contact Ripple.

Before you start, you must already have the following items from the preparation checklist:

• The recovery CLI binary, downloaded in advance
• Your RSA recovery private key, and its password if encrypted (verify it first)
• Your offline wallet inventory, which lists the quorum ID, key ID (= wallet ID), and key type for each wallet. The backup files don't store the quorum ID anywhere (the key ID is only the S3 folder name), so without the inventory, you can't recover wallets from the backups alone.
• AWS access to read your backup bucket, and to decrypt with the KMS key if the objects use SSE-KMS
• An air-gapped machine with the CLI installed

If Wallet-as-a-Service only ever stored your backups in its managed bucket (the default configuration), you have no self-service way to retrieve them. Ripple-independent recovery requires that you configured your own bucket before you created the wallets.

Download the recovery data for the key from your S3 bucket:

# List all recovery kits
aws s3 ls s3://your-backup-bucket/ --recursive

# Download a specific wallet's recovery kit (the key ID is the wallet ID)
aws s3 cp s3://your-backup-bucket/<key_id>/recovery_shard-0.txt ./recovery-kit.b64

You need only the file that matches the recovery private key you hold. If your kit has multiple recovery public keys, don't rely on the number in the filename. Either run recover with each file in turn, or decode the file (base64) and compare its recoveryPublicKeyHex field with the hex form of your public key. If a file belongs to a different key, recover stops with Recovery public key does not match the private key. before it recovers anything. recoveryPublicKeyHex is lowercase hex of the DER public key. If your public key file is binary DER (the generate-recovery-keypair default), convert it with xxd -p recovery-public.der | tr -d '\n'. For the file format, see the data structure reference.

Use removable media to transfer the following items to the air-gapped machine:

• The recovery kit file that you downloaded from S3
• Your RSA recovery private key
• The recovery CLI binary (which you downloaded in advance)
• Your inventory record of the wallet's quorum ID, key ID, and key type

Run the recover command:

wallet-recovery-cli recover \
  --recovery-kit-file=recovery-kit.b64 \
  --private-key-file=recovery-private.hex \
  --quorum-id=<QUORUM_UUID> \
  --key-id=<KEY_UUID> \
  --key-type=SECP256K1 \
  --output-file=recovered.enc \
  --encrypt-output=true

Use --key-type=ED25519 for Solana wallets. SECP256K1 (the default) covers Ethereum and other EVM chains, XRP, and Bitcoin.

The quorum ID and key ID aren't just labels. Wallet-as-a-Service binds them cryptographically into the recovery data, so recovery fails if either is wrong. The CLI validates that your RSA private key matches the public key in the recovery data, verifies the integrity of the recovery data, and then reconstructs the private key. By default, the CLI encrypts the output file with AES-256 by using a password you choose (--encrypt-output=true; passwords must be at least 8 characters).

The CLI also prints the blockchain addresses derived from the recovered key. Verify these match the wallet's addresses in your inventory before you go further. This confirms that you recovered the right key.

If you saved the output encrypted, decrypt it when you're ready to sign:

wallet-recovery-cli decrypt \
  --encrypted-private-key-file=recovered.enc \
  --decrypted-output-file=recovered-key.bin

You can re-check the derived addresses at any time with print-address. It detects an encrypted file and prompts for the password. Always pass --key-type from your inventory. Without it, the tool tries SECP256K1 first, and an ED25519 key passes that check, so for every Solana wallet it prints EVM, XRP, and Bitcoin addresses that aren't yours.

wallet-recovery-cli print-address --private-key-file=recovered.enc --key-type=<KEY_TYPE>

The decrypted output is the raw 32-byte private key with no encoding. (Without --output-file, the CLI prints it to stdout as base64.) Most tooling expects the key as hex text, so convert it first:

xxd -p recovered-key.bin | tr -d '\n'

Use the key with standard blockchain tooling to sign a transaction that sends the wallet's assets to a secure destination address (for example, a wallet at another custodian or a hardware wallet you control):

• Ethereum and EVM chains: Import the hex key into any EVM-compatible wallet or library (for example, MetaMask's import account, new ethers.Wallet('0x' + hexKey) in ethers.js, or web3.eth.accounts.privateKeyToAccount in web3.js).
• Bitcoin: Convert the key to compressed WIF and import it as a Native SegWit (P2WPKH) key, for example, with a wpkh() descriptor in Bitcoin Core or a p2wpkh: prefixed key in Electrum. The wallet's address derives from the compressed public key, so an uncompressed or legacy import produces a different address.
• XRP: Use the xrpl library with the secp256k1 key in its 33-byte hex form, which you get by prefixing the 32-byte hex key with 00.
• Solana: The output is the raw ED25519 private scalar, not the 32-byte seed that Solana tooling expects, and you can't convert a scalar back to a seed. As a result, solana-keygen, Keypair.fromSecretKey, and standard Solana wallets can't import it. Verify the recovered key with print-address --key-type ED25519, and contact Ripple support for help moving Solana assets.

Where possible, sign the transaction offline on the air-gapped machine, and broadcast the signed transaction from a separate, connected machine.

After you confirm that the assets have arrived at the destination:

1. Securely delete the recovered private key, the decrypted output files, and the recovery kit copies from the air-gapped machine and any removable media. On Linux, use shred -u <file>. On macOS, APFS doesn't support secure erase at the file level, so rely on FileVault full-disk encryption and delete normally.
2. Treat the recovered wallet as compromised. The key existed in one piece, so don't send assets to it again.

In the sandbox rehearsal from the preparation checklist, you run exactly the procedure above against a sandbox wallet. There's no dry-run or verify-only mode. A test recovery produces a live private key, so finish every rehearsal with Step 6: Clean up, including secure deletion of the recovered key.

• Configure backup and recovery: Set up backups and complete the preparation checklist this procedure depends on
• AWS backup infrastructure reference: Backup file format, folder structure, and troubleshooting
• Set up and run CloudSign: CloudSign storage options and upgrades
• Manage MPC quorums and Manage devices: Restructuring procedure and device pairing, approval, and removal
• Wallet-as-a-Service Wallet Recovery CLI: Complete CLI documentation, including generate-recovery-keypair, validate-private-key, recover, decrypt, and print-address