This guide covers everything you do before a disaster: understanding how Wallet-as-a-Service backups work, making the key decisions, setting up the infrastructure, preparing for disaster recovery, and maintaining your backups over time. As an owner or administrator, you are responsible for this setup and its upkeep.
When something goes wrong and you need to restore a corrupted node or recover wallets without the platform, use the Disaster recovery guide instead. For AWS specifics (policy JSON, ARNs, troubleshooting), see the AWS backup infrastructure reference.
You and your team don't perform backups yourselves. After you configure them, the platform runs them automatically:
- For every key created under a quorum that has a backup kit assigned, Wallet-as-a-Service generates recovery data encrypted to your RSA public key. Each wallet key gets one backup, so an organization with a million wallets has a million backups.
- Wallet-as-a-Service always writes the encrypted recovery data to a Wallet-as-a-Service-managed S3 bucket. If you configure your own AWS infrastructure, it writes an additional copy to your S3 bucket through an IAM role that Wallet-as-a-Service assumes. If you configure AWS KMS, Wallet-as-a-Service uses KMS for S3 server-side encryption of the object in your bucket.
- Only you hold the RSA private key needed to decrypt the recovery data after you retrieve it from S3.
This design ensures that Wallet-as-a-Service never has unilateral access to your backup data: Wallet-as-a-Service encrypts every copy to your public key before it writes the copy. Recovery requires the RSA private key that you control. If the S3 object uses SSE-KMS, you also need AWS access to read and decrypt the object from the bucket before you run recovery.
Backups fail closed: if Wallet-as-a-Service can't write the recovery data to S3, wallet creation fails rather than producing an unbacked-up wallet. Wallet-as-a-Service doesn't retry, so re-request the wallet after you fix the storage issue. The upside is a guarantee: every active wallet under a backup-enabled quorum has a backup. A failed write can still leave some recovery_shard files behind in either bucket, so you might find backup folders for key IDs that never became wallets. Check folders against your wallet inventory rather than treating every folder as a wallet.
When you combine a backup with the Wallet-as-a-Service Wallet Recovery CLI, you can eject the raw private key for a wallet and sign transactions with it directly, without any Wallet-as-a-Service infrastructure. This capability is what makes recovery independent of Ripple possible.
When you create a backup kit, you choose between two storage configurations. Ripple recommends Use own AWS configuration because it's the only option that lets you recover without Ripple.
| Option | Where backups live | Recovery independent of Ripple? |
|---|---|---|
| Use own AWS configuration (Recommended) | The managed bucket plus your own S3 bucket | Yes. You can retrieve and recover backups without any involvement from Ripple. |
| Wallet-as-a-Service AWS configuration (default) | Only the Wallet-as-a-Service-managed bucket | No. You currently have no self-service way to retrieve backup files from the managed bucket. |
If your disaster recovery plan requires recovering assets without Ripple's involvement, select Use own AWS configuration so that Wallet-as-a-Service writes a copy of every backup to a bucket you control. Make this choice before you create quorums. You can't add or change a kit's S3 configuration after you create the kit, and you can't change a quorum's kit after you create the quorum.
Decide who holds the recovery private key and where to store it. Common approaches:
| Approach | Pros | Cons |
|---|---|---|
| HSM-protected storage | Tamper-resistant custody of a wrapping key, auditable access | The recovery CLI reads the private key from a file and has no HSM integration, so you can't use a non-exportable HSM key directly. Instead, keep the recovery private key encrypted under a non-exportable wrapping key in the HSM and unwrap it to a file at recovery time. You build and maintain that tooling. |
| Encrypted offline storage (USB, air-gapped machine) | Low cost, simple | Relies on physical security |
| Split across multiple custodians | No single point of failure | Coordination required for recovery |
A backup kit can hold multiple recovery public keys, and each wallet gets a separate recovery file for each one. Any single key is sufficient for recovery. For resilience, consider generating several key pairs on geographically separate, isolated machines and adding all their public keys to the kit.
If you lose the recovery private key, you can't decrypt backups. Never store it on the same systems or accounts that hold the backups.
Use separate AWS infrastructure for sandbox and production backups:
- Different S3 buckets
- Different IAM roles
- Different KMS keys
- Different recovery key pairs (recommended)
This prevents a sandbox misconfiguration from affecting production backups.
The setup has four steps across three surfaces. The AWS backup infrastructure reference provides the commands, policy JSON, and troubleshooting for each step. This table tells you what each step is for.
| Step | What you do | Where | Details |
|---|---|---|---|
| 1. Generate a recovery key pair | Create an RSA-4096 key pair with the recovery CLI's generate-recovery-keypair command (optionally password-protecting the private key with --encrypt-private-key) or with OpenSSL. Upload the public key to Wallet-as-a-Service; store the private key offline. Use validate-private-key to confirm the password works. | Your workstation | Key generation |
| 2. Create an S3 bucket | Create a bucket with versioning, KMS encryption, and a bucket policy that enforces TLS and encryption. | Your AWS account | Bucket setup |
| 3. Create an IAM role | Create a role that Wallet-as-a-Service's MPC service can assume, with permissions to write to your bucket and use your KMS key. | Your AWS account | IAM role setup |
| 4. Create the backup kit | Enter a name, upload your public keys (up to five per kit), then select Use own AWS configuration and enter your bucket name, role ARN, region, external ID, and KMS key ARN. Wallet-as-a-Service validates the AWS configuration before it saves the kit (pre-flight validation). | Settings > Backup & Recovery > Manage backups > Create backup | Console fields and pre-flight |
After setup, apply the security hardening checklist in the reference: CloudTrail data events, S3 Object Lock, minimal IAM permissions, MFA Delete, and CloudWatch alarms.
Assign the backup kit to an MPC quorum during quorum creation. Wallet-as-a-Service backs up only quorums created with an assigned backup kit, and you can't add, remove, or change the kit later through quorum restructuring. See Manage MPC quorums.
Wallet-as-a-Service doesn't back up wallets in a Mixed quorum. The console doesn't offer a backup kit when you create a Mixed quorum, and CloudSign devices generate recovery data only in Cloud quorums. Without a backup, you can't use the recovery CLI to recover a Mixed quorum wallet. If you need key shard backups, create a Cloud or Mobile quorum and assign a backup kit to it.
Then verify the pipeline end to end:
- Create a wallet using the quorum.
- Check your S3 bucket for backup files in the expected folder structure (
<key_id>/recovery_shard-*.txt, where the key ID is the wallet ID). See the data structure reference for what the files contain. - Confirm CloudTrail logged the write operation.
Backups alone don't make you recoverable. You must complete everything in this checklist while the platform is available. If you skip these steps, your backups might be unrecoverable when you need them.
[ ] Configure your own S3 bucket (above). Without the platform, you can't retrieve backups that exist only in the managed bucket.
[ ] Download the recovery CLI now. Download the Wallet-as-a-Service Wallet Recovery CLI binary for your platform (or build it from source with Go) and store it offline alongside your recovery materials. Don't assume you can download it during a disaster.
[ ] Secure the recovery private key according to your custody decision, and record its password in a secure location such as a password manager or vault. Periodically verify the key with
wallet-recovery-cli validate-private-key. The command tests decryption without modifying the file.[ ] Maintain an offline wallet inventory. The
recovercommand requires the quorum ID, key ID, and key type for each wallet, and the backup files don't store the quorum ID anywhere, so without your inventory, you can't recover wallets from the backups alone. Keep a CSV file or secure database with these columns, and store it somewhere you can access without the platform (an encrypted file on your own infrastructure, a hardware-encrypted drive, or a secrets manager):Column Description Example key_idWallet key UUID (same as the wallet ID) a1b2c3d4-...quorum_idQuorum UUID the wallet belongs to e5f6a7b8-...key_typeKey algorithm SECP256K1orED25519blockchainBlockchain name ethereum,solana,bitcoinaddressWallet address on chain 0x1234...The wallets list API (
POST /v2/wallets:list) returns the wallet ID, quorum ID, and key algorithm for every wallet. The API paginates the response: followfilter.nextPageTokenuntil it's empty, or your inventory silently omits wallets. Refresh the inventory whenever you create wallets. In the console, the quorum's detail page shows the quorum ID.[ ] Record where Wallet-as-a-Service stores your backups. Note the S3 bucket name, region, and, if you use SSE-KMS, which AWS credentials can read and decrypt the objects.
[ ] Prepare an air-gapped machine. Recovery ejects a raw private key; plan to run it on a machine with no network connection, with the CLI binary already installed.
[ ] Rehearse in sandbox. Run the full recovery procedure against a sandbox wallet at least annually, and make sure the team members responsible know where you store the recovery keys and inventory. There's no dry-run mode. A test recovery produces a live private key, so securely destroy it afterward, just as you would in a real recovery.
Backups aren't one-time configurations. Maintain them throughout the life of your organization:
| Event | Required action |
|---|---|
| Key reshare or quorum restructure | You don't need to take any action on key shard backups, and you can't. Resharing and restructuring replace the key shards without changing the wallet's underlying key, and Wallet-as-a-Service binds each backup file to the wallet's key ID and quorum ID, neither of which changes. The backup file doesn't store the quorum ID, so keep it in your offline wallet inventory. Wallet-as-a-Service can't regenerate a key shard backup for an existing key. Take fresh CloudSign node backups after every reshare or restructure, and never restore a node snapshot taken before one. See Disaster recovery. |
| Personnel change | If the person who held the recovery key leaves, create a new backup kit with the new recovery public key for future quorums. You can't update existing quorums to use a different backup kit, so plan migration or replacement with Ripple support if you must retire that key. |
| Shard-holding device permanently lost | You don't need to take any backup action. Replace the device by restructuring the quorum. See Replace a lost shard-holding device. Key shard backups stay valid, because the wallet key doesn't change. |
| Annual review | Verify your recovery private key still decrypts with the password you hold. Rehearse a recovery in sandbox. Confirm your offline wallet inventory is up to date. Without it, you can't recover wallets if the platform is unavailable. |
Ongoing best practices:
- Monitor backup creation: Use CloudTrail logs to confirm Wallet-as-a-Service writes backups to S3 as expected.
- Set retention policies: configure S3 lifecycle rules to manage backup retention, but always keep the most recent backup, and never add rules that could transition or expire recovery data you still need.
- Document your backup architecture: Record which S3 buckets, IAM roles, and KMS keys each environment uses, and who has access to the recovery private key.
Key shard backups are one of two backup layers. The other is operational: each CloudSign node stores its encrypted key shards in a local embedded database (under /var/cloudsign) or in PostgreSQL. Back up this data regularly (for example, with encrypted EBS snapshots or standard PostgreSQL backups), and always take a backup before you upgrade a node. These backups protect against failed upgrades and database corruption without requiring key recovery.
See Set up and run CloudSign for storage options, and Disaster recovery for the restore procedure and its constraints.
- Disaster recovery: Restore a node database or recover wallets when something has gone wrong
- AWS backup infrastructure reference: Policy JSON, ARNs, key generation commands, pre-flight details, and troubleshooting
- Manage MPC quorums: Assign backup kits to quorums