# Cold vaults

Executive summary
**Cold vaults isolate the signing environment from network-connected systems.**

- Cold vault signing uses the same governance approval model as hot vault signing.
- The difference is transport: operations move between the online system and the air-gapped workstation as `.dat` files.
- A cold bridge runs on the air-gapped workstation and provides the local interface that the vault polls for signing work.
- Accounts, transactions, and manifests created for a cold vault remain `Pending` until the signed payload is imported back into Ripple Custody.
- Cold vault operations trade speed and automation for stronger physical isolation.


Why this matters
Cold storage reduces the attack surface for high-value assets because the signing environment is not reachable from the online deployment. Even if an online component is compromised, the attacker still cannot directly reach the cold vault signing environment.

**For architects and operators**: Cold vaults require operational discipline. You need an air-gapped workstation, controlled transfer media, clear verification steps before signing, and recovery procedures for the workstation, vault configuration, and KMS material.

Prerequisites
Before using cold vaults, you should understand:

- [Vaults](/products/custody/v1.36/identity-and-access/vault-management) - How vaults relate to KMS, accounts, and governance-approved signing.
- [Transaction processing](/products/custody/v1.36/transactions/processing) - How approved transactions move to signing and broadcast.
- [Key management planning](/products/custody/v1.36/deployment/planning/key-management) - How KMS choices affect signing and recovery.


## Cold vault architecture

A cold vault uses a physically isolated signing environment. The online deployment prepares operation payloads, an operator transfers those payloads to the air-gapped workstation, the cold bridge makes the payload available to the local vault, and the signed result is transferred back for import.


```mermaid
flowchart LR
    subgraph Online["Online Ripple Custody environment"]
        UI["UI or API"]
        Core["Core services"]
    end

    subgraph Transfer["Manual transfer"]
        DatOut["Unsigned .dat file"]
        DatIn["Signed .dat file"]
    end

    subgraph Cold["Air-gapped workstation"]
        Bridge["Cold bridge"]
        Vault["Vault"]
        KMS["KMS<br/>HSM or MPC"]
        Bridge --> Vault --> KMS
    end

    UI --> Core
    Core --> DatOut --> Bridge
    Bridge --> DatIn --> Core
```

| Component | Role |
|  --- | --- |
| Online Ripple Custody environment | Creates accounts, transactions, and manifests as governed operations. Exports pending cold vault operations. |
| Transfer media | Moves `.dat` payloads between the online environment and the air-gapped workstation. |
| Cold bridge | Runs on the air-gapped workstation. Provides the local UI and API used to upload, inspect, sign, and download operation payloads. |
| Vault | Polls the cold bridge for signing work, verifies the notary attestation, builds the transaction, and signs. |
| KMS | Protects the signing key material and performs cryptographic operations. |


## Hot vaults and cold vaults

Both vault types follow the same governance and approval process. They differ after the operation is prepared for vault signing.

| Factor | Hot vault | Cold vault |
|  --- | --- | --- |
| Connectivity | Network-connected. | Air-gapped. |
| Signing path | Vault polls the online API for operation queries. | Vault polls the local cold bridge for operation queries. |
| Operator involvement | Automated after approval. | Manual export, transfer, signing, and import. |
| Typical use | Frequent transactions, payments, and operational liquidity. | High-value reserves and cold storage. |


## Signing workflow


```mermaid
sequenceDiagram
    participant User as User
    participant Online as Online system
    participant Media as Transfer media
    participant Bridge as Cold bridge
    participant Vault as Vault

    User->>Online: Submit and approve operation
    Online->>Online: Prepare cold vault operation
    Online->>Media: Export unsigned .dat file
    Media->>Bridge: Transfer to air-gapped workstation
    Bridge->>Vault: Vault polls for signing work
    Vault->>Vault: Verify notary attestation and sign
    Vault->>Bridge: Return signed payload
    Bridge->>Media: Download signed .dat file
    Media->>Online: Import signed operations
    Online->>User: Continue account, transaction, or manifest processing
```

## First-time cold vault handshake

When a cold vault is first registered, it can appear in a `Pending` state because it cannot automatically connect to the online deployment. Complete the manual handshake before using the vault for accounts, transactions, or manifests.

At a high level:

1. Register the cold vault using the standard vault registration flow.
2. Download the vault data from the cold bridge on the air-gapped workstation.
3. Transfer the `.dat` file to the online environment.
4. Import the file into Ripple Custody.
5. Verify that the vault status is `Completed`.


For steps, see [Process cold vault operations in the UI](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-ui#complete-the-first-time-vault-handshake) or [Process cold vault operations with the API](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-api#complete-the-first-time-vault-handshake).

## Operational responsibilities

| Responsibility | Why it matters |
|  --- | --- |
| Air-gap controls | The workstation must remain isolated from networks so signing cannot be reached remotely. |
| Transfer media controls | `.dat` files move between the online environment and the air-gapped workstation. Use approved media and handling procedures. |
| Payload verification | Operators should inspect operation details before allowing the cold vault to sign. |
| KMS recovery | Cold vault recovery depends on protected KMS material and vendor recovery procedures. |
| Configuration backup | Recovery requires the same vault configuration, including the vault UUID and public key. |


## Next steps

| Task | Page |
|  --- | --- |
| Plan the air-gapped workstation | [Cold vault workstation planning](/products/custody/v1.36/deployment/planning/cold-vault-workstation) |
| Deploy the cold bridge | [Deploy a cold bridge](/products/custody/v1.36/deployment/install/cold-bridge-deployment) |
| Register, view, update, lock, or unlock vaults | [Manage vaults](/products/custody/v1.36/identity-and-access/vault-management/manage-vaults) |
| Process cold vault operations in the UI | [Process cold vault operations in the UI](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-ui) |
| Process cold vault operations with the API | [Process cold vault operations with the API](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-api) |
| Recover cold vault operations after workstation loss | [Recover a cold vault](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-recovery) |