Manage vaults

Use this page for post-installation vault operations. For the conceptual model, see Vaults. A vault is an external component that securely manages blockchain transaction signing. All external vaults must be registered in Ripple Custody before accounts can use them.

A vault is not tied to a domain, so accounts in different domains can use the same vault. Vault registration and vault updates are performed from the root domain.

For the trust model, see Trusted vs untrusted components. For key strategy and backup implications, see Vaults.

Vault changes use the standard intent flow. For signing, approval, and status checks, see Manage intents and approvals, Sign intents, and Check updates.

Whenever you deploy a new vault, register it by creating a corresponding vault entity. You can only register vaults in the root domain. You can then use the vault to execute transactions in any domain.

Before you register the vault, collect the vault's public key and ID from the vault logs, as described in First-time installation.

At registration, set the key management system (KMS) type to either HSM or MPC so the system can use the correct vault behavior. For more information about MPC key management, contact your Ripple liaison.

To register a vault:

1. Select the root domain from the Domain drop-down menu.
2. Go to Administration > Vaults.
3. Click Create a vault.
4. Enter the vault name, vault ID in UUID format, and KMS type.
5. Enter or upload the vault public key.
6. Enter any required custom properties.
7. Click Submit for Approval and sign the operation with the app.

The vault is created after the intent is approved and executed.

Create a vault by submitting a v0_CreateVault intent.

Before you register a vault, prepare:

{
  "payload": {
    "id": "92f6c08d-10c9-4cbb-8e86-ec8275eda0ee",
    "alias": "vault-hot",
    "parameters": {
      "type": "HSM"
    },
    "publicKey": "MCowBQYDK2VwAyEAIX4sz/23SbbAPWBn03zpd634Xj2uwT8Y/F7iH4XY4Ig=",
    "lock": "Unlocked",
    "description": "Hot vault",
    "customProperties": {},
    "type": "v0_CreateVault"
  }
}

Field notes:

Dry run before submitting:

curl -X POST "${CUSTODY_API_URL}/v1/intents/dry-run" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @create-vault-intent.json

After the vault creation intent is approved and executed, Ripple Custody returns a supportedDerivations list in the data object. Use this information when you create an account.

View vault details before creating accounts, confirming cold vault processing status, or checking the supported derivations exposed by the vault.

In the UI:

1. Go to Administration > Vaults.
2. Click the vault to view its details.

The UI shows general vault details, such as the vault ID, public key, and key derivations. For cold vaults, the UI also shows pending operations. For more information, see Process cold vault operations in the UI.

With the API, call List vaults to find vaults or Get vault details to retrieve a specific vault:

GET /v1/vaults/{vaultId}
Authorization: Bearer <your_jwt_token>

Use v0_UpdateVault to change mutable vault details. You can only update a vault from the root domain.

In the UI:

1. Select the root domain from the Domain drop-down menu.
2. Go to Administration > Vaults.
3. At the end of the vault row, click the contextual menu and select Edit.
4. Update the vault name, description, or custom properties.
5. Click Submit for Approval and sign the operation with the app.

With the API, submit an update intent with the current vault reference:

{
  "payload": {
    "reference": {
      "id": "92f6c08d-10c9-4cbb-8e86-ec8275eda0ee",
      "revision": 2
    },
    "alias": "vault-hot",
    "parameters": {
      "type": "HSM"
    },
    "description": "Updated hot vault description",
    "customProperties": {},
    "type": "v0_UpdateVault"
  }
}

Field notes:

The vault is updated after the intent is approved and executed.

Lock a vault when transaction orders related to that vault should not execute. Unlock the vault only after the operational reason for the lock is resolved.

Submit a v0_LockVault intent with the current vault reference:

{
  "payload": {
    "reference": {
      "id": "92f6c08d-10c9-4cbb-8e86-ec8275eda0ee",
      "revision": 2
    },
    "type": "v0_LockVault"
  }
}

Use v0_UnlockVault with the same reference shape to re-enable the vault.

Before submitting a vault-management intent:

• Confirm the vault ID and public key from the deployed vault logs.
• Confirm the KMS type and any backup or wrapping-key-rotation requirements.
• Confirm that the intent is submitted from the root domain.
• Confirm the policy that will govern the vault intent.
• Dry run the payload.
• Verify the executed change by viewing the vault details.