Vaults connect Ripple Custody to the key material used for blockchain transaction signing.
- A vault is an external signing component that securely manages blockchain transaction signing.
- The vault uses a KMS, HSM, or MPC backend for blockchain key operations. Other protected components, such as the notary and configured system-signing path, can also use KMS-backed keys.
- Vaults are trusted entities and must be registered before accounts can use them.
- Accounts in different domains can use the same vault because a vault is not tied to a domain.
- Hot vaults sign automatically. Cold vaults are air-gapped and require an export/import workflow.
Vault design affects security, transaction processing, account recovery, and day-to-day operations. A vault links governance-approved activity to protected signing keys: policies decide whether a transaction can proceed, and the vault verifies the notary attestation before building and signing the blockchain transaction.
For architects and operators: Choose the KMS model, key derivation strategy, and hot/cold vault pattern before creating accounts. These choices determine which keys must be backed up, which operational procedures are required, and how quickly transactions can move from approval to broadcast.
Before reading this page, you should understand:
- Security model - The zero-trust security model and the role of trusted components.
- Key management - How user, notary, vault, and blockchain keys are protected.
- Accounts - How accounts relate to vaults and ledgers.
A vault is the signing component that connects Ripple Custody to a KMS, HSM, or MPC backend for blockchain key operations. It is responsible for transaction signing and for interacting with the protected key material behind the vault.
The KMS may be based on:
| KMS model | How keys are protected | See |
|---|---|---|
| HSM | A hardware security module generates, stores, and uses private keys internally. Only cryptographic outputs, such as signatures, are exported. | Key management planning |
| MPC | Key material is distributed as shards. A threshold of MPC nodes collaborates to produce a signature without reconstructing the complete private key. | Key management planning |
Each time you initialize and register a new vault, specify whether it uses HSM or MPC. When the vault is registered, Ripple Custody stores the vault entity, including its public key, so the system can verify information returned by the vault.
From a data-integrity perspective, the notary and vault are trusted components. The notary signs trusted state, and the vault signs blockchain transactions. The database, API gateway, and other application components are treated as untrusted because trusted data must be verified cryptographically.
The vault verifies the notary attestation before building and signing a transaction. This keeps signing tied to the approved operation rather than to an unaudited request.
A vault is not tied to a domain. Accounts in different domains can use the same vault, and each account stores its vault relationship in providerDetails.vaultId.
During account creation, choose:
| Account setting | Why it matters |
|---|---|
| Vault ID | Identifies the vault that stores or derives the account's signing keys. |
| Key strategy | Determines how account keys are created and what must be backed up. |
| Ledger IDs | Defines the ledgers associated with the account. |
After a vault creation intent is approved and executed, the vault details include supportedDerivations. Use this list when choosing the key strategy for new accounts.
Each vault uses a key strategy that determines how account keys are created and what must be backed up for recovery.
| Strategy | How keys are created | Backup implication |
|---|---|---|
| Deterministic derivation | Account keys are derived from a master seed using the configured derivation strategy. | The master seed or wrapped seed material is critical to account recovery. |
| MPC | Key material is split into MPC shares and protected by the MPC deployment. | If customer-held MPC backups are required, follow the MPC backup workflow through the operations backup guidance. |
| Random key strategy | Account keys are generated without a deterministic relationship to a master seed. | The database becomes critical for recovery because accounts cannot be regenerated from a seed backup. |
For most new vaults, VaultHard is the default key derivation strategy. VaultSoft and Random require explicit enablement and have additional backup implications.
For the full derivation model, see Key derivation.
Ripple Custody supports hot and cold vault transaction-signing flows.
| Vault type | How signing works | Use case |
|---|---|---|
| Hot vault | The vault is network-connected and polls for operation queries. After approval, it verifies the notary attestation, builds the transaction, signs it, and submits the signed transaction for broadcast. | Frequent transactions, trading, payments, and operational liquidity. |
| Cold vault | The vault is air-gapped. Operators export pending operations, move them to the cold vault, sign them, and import the signed operations back into Ripple Custody. | Large treasury reserves and cold storage. |
Both hot and cold vaults follow the same governance and approval process. They differ in how the vault receives the operation query and returns the signed transaction.
| Lifecycle stage | What happens |
|---|---|
| Deploy | The vault component is deployed with its KMS backend. |
| Register | A v0_CreateVault intent creates the vault entity in Ripple Custody. Vaults are registered from the root domain. |
| Use | Accounts reference the vault through providerDetails.vaultId; approved transactions can be prepared for vault signing. |
| Update | A v0_UpdateVault intent changes mutable vault details such as alias, description, custom properties, or parameters. |
| Lock or unlock | v0_LockVault prevents transaction orders related to the vault from executing. v0_UnlockVault re-enables the vault. |
Vault strategy affects what operators must preserve for recovery. Platform backup and restore procedures live with operations guidance; vault recovery and wrapping-key rotation procedures live in this section.
| Need | Start with |
|---|---|
| Determine backup scope | Back up, restore, and recover |
| Route operators to the correct backup procedure | Backup procedures |
| Rotate a vault wrapping key for an IBM HSM-backed vault | IBM HSM wrapping key rotation |
| Rotate a vault wrapping key for an MPC-backed vault | MPC wrapping key rotation |
| Plan platform-level restore validation | Restore procedures and Backup validation |
| Recover cold-vault operations after a workstation or environment failure | Cold vault recovery |
| Task | Page |
|---|---|
| Register, view, update, lock, or unlock vaults | Manage vaults |
| Understand cold vault operations | Cold vaults |
| Process air-gapped vault operations | Process cold vault operations with the API or Process cold vault operations in the UI |
| Determine backup, recovery, or key-rotation scope | Backup, recovery, and key rotation |
| Plan KMS selection | Key management planning |
| Create accounts that use a vault | Manage accounts in the UI or with the API |