# Vaults

Executive summary
**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.


Why this matters
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.

Prerequisites
Before reading this page, you should understand:

- [Security model](/products/custody/overview/security-model) - The zero-trust security model and the role of trusted components.
- [Key management](/products/custody/overview/security/cryptographic-trust-model) - How user, notary, vault, and blockchain keys are protected.
- [Accounts](/products/custody/accounts-and-assets/accounts/overview) - How accounts relate to vaults and ledgers.


## What is a vault?

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](/products/custody/deployment/planning/key-management#hardware-security-modules-hsms) |
| 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](/products/custody/deployment/planning/key-management#multi-party-computation-mpc) |


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.

## Vaults in the trust model

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.


```mermaid
flowchart LR
    Intent["Approved transaction intent"]
    Notary["Notary / policy evaluation"]
    Vault["Vault"]
    KMS["KMS<br/>HSM or MPC"]
    Chain["Blockchain network"]

    Intent -->|"Policy workflow"| Notary
    Notary -->|"Signed attestation"| Vault
    Vault -->|"Sign request"| KMS
    KMS -->|"Signature only"| Vault
    Vault -->|"Signed transaction"| Chain
```

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.

## How vaults relate to domains, accounts, and ledgers

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.


```mermaid
flowchart TD
    subgraph Root["Root domain"]
        VaultEntity["Registered vault entity"]
    end

    subgraph DomainA["Domain A"]
        AccountA["Account<br/>providerDetails.vaultId"]
    end

    subgraph DomainB["Domain B"]
        AccountB["Account<br/>providerDetails.vaultId"]
    end

    VaultEntity -->|"Used by"| AccountA
    VaultEntity -->|"Used by"| AccountB
    AccountA -->|"Ledger IDs"| LedgerA["Blockchain ledgers"]
    AccountB -->|"Ledger IDs"| LedgerB["Blockchain ledgers"]
```

## Key strategies and backup implications

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](/products/custody/accounts-and-assets/accounts/account-key-derivation-and-ledger-compatibility).

## Hot and cold vaults

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.


```mermaid
flowchart TD
    Approved["Approved transaction intent"]
    Prepared["Notary-attested operation query"]
    Choice{"Vault type"}
    Hot["Hot vault<br/>polls API and signs"]
    ColdExport["Export pending operations"]
    ColdSign["Cold vault signs offline"]
    ColdImport["Import signed operations"]
    Broadcast["Ledger service broadcasts"]

    Approved --> Prepared --> Choice
    Choice --> Hot --> Broadcast
    Choice --> ColdExport --> ColdSign --> ColdImport --> Broadcast
```

## Vault lifecycle


```mermaid
stateDiagram-v2
    [*] --> Deployed: Deploy vault component
    Deployed --> Registered: v0_CreateVault
    Registered --> UsedByAccounts: Create accounts with vaultId
    UsedByAccounts --> Signing: Approved transactions
    Signing --> Locked: v0_LockVault
    Locked --> UsedByAccounts: v0_UnlockVault
    UsedByAccounts --> Updated: v0_UpdateVault
    Updated --> UsedByAccounts
```

| 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. |


## Backup, recovery, and key rotation

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](/products/custody/operations-and-maintenance/backup-and-restore#what-to-back-up) |
| Route operators to the correct backup procedure | [Backup procedures](/products/custody/operations-and-maintenance/backup-and-restore#backup-procedures) |
| Rotate a vault wrapping key for an IBM HSM-backed vault | [IBM HSM wrapping key rotation](/products/custody/identity-and-access/vault-management/vault-wrapping-key-rotation-ibm-hsm) |
| Rotate a vault wrapping key for an MPC-backed vault | [MPC wrapping key rotation](/products/custody/identity-and-access/vault-management/vault-wrapping-key-rotation-mpc) |
| Plan platform-level restore validation | [Restore procedures](/products/custody/operations-and-maintenance/backup-and-restore#restore-procedures) and [Backup validation](/products/custody/operations-and-maintenance/backup-and-restore#validation) |
| Recover cold-vault operations after a workstation or environment failure | [Cold vault recovery](/products/custody/identity-and-access/vault-management/cold-vault-recovery) |


## Next steps

| Task | Page |
|  --- | --- |
| Register, view, update, lock, or unlock vaults | [Manage vaults](/products/custody/identity-and-access/vault-management/manage-vaults) |
| Understand cold vault operations | [Cold vaults](/products/custody/identity-and-access/vault-management/cold-vaults) |
| Process air-gapped vault operations | [Process cold vault operations with the API](/products/custody/identity-and-access/vault-management/cold-vault-setup-api) or [Process cold vault operations in the UI](/products/custody/identity-and-access/vault-management/cold-vault-setup-ui) |
| Determine backup, recovery, or key-rotation scope | [Backup, recovery, and key rotation](/products/custody/identity-and-access/vault-management/backup-recovery-and-key-rotation) |
| Plan KMS selection | [Key management planning](/products/custody/deployment/planning/key-management) |
| Create accounts that use a vault | [Manage accounts in the UI](/products/custody/accounts-and-assets/accounts/manage-accounts-ui) or [with the API](/products/custody/accounts-and-assets/accounts/manage-accounts-api) |