Deploy a cold bridge

Use this page when deploying cold vault operations. Only cold storage deployments require the cold bridge.

The cold bridge runs on the air-gapped cold vault server and provides:

• A local UI for cold vault operations.
• A local API for uploading, decoding, and downloading operation payloads.
• Optional payload encryption and decryption for .dat files.
• A local endpoint that the vault component polls for signing work.

For server requirements, see Cold vault server planning.

The cold bridge is stateless and uses in-memory storage for workloads. It does not require a database or persistent volume.

Before installing the cold bridge:

1. Build the server according to Cold vault server planning.
2. Verify that network connectivity is disabled.
3. Install the hardened operating system from verified media.
4. Install KMS or HSM drivers, if applicable.
5. Prepare approved transfer media for moving .dat files.

Transfer the cold bridge, vault-release, and KMS container images, together with their configuration files, to the air-gapped cold vault server using approved physical media.

Install the components using the deployment method agreed for your environment. Deploy the cold bridge and vault together so the vault can poll the local cold bridge endpoint for signing work.

Cold bridge payload encryption is enabled by default and uses AES-256. The same passphrase must be configured on:

• The cold bridge.
• The core-extensions service in the online deployment, which processes cold bridge payloads.

If the passphrase differs between the air-gapped cold vault server and the online system, neither side can decrypt the other's operation payloads. Contact your Customer Partner Engineer (CPE) for the specifics of configuring or changing the passphrase.

After startup, call the status endpoint from the air-gapped cold vault server:

curl -X GET "{ColdBridgeURL}/v1/feed/status"

Expected response shape:

{
  "accountToSign": 0,
  "accountSigned": 0,
  "transactionToSign": 0,
  "transactionSigned": 0,
  "manifestToSign": 0,
  "manifestSigned": 0
}

1. On the cold vault server, check the vault-release container logs for the vault UUID and public key.

2. Register the cold vault with the standard vault registration process, using the UUID and public key from the logs:

   • Register a vault in the UI
   • Register a vault with the API

After registration, the vault can appear as Pending because the cold vault cannot automatically connect to the online deployment.

Complete the manual handshake by transferring the initial vault payload from the cold bridge to the online system:

1. On the cold vault server, download the payload from the cold bridge.
2. Transfer the .dat file to the online environment.
3. Import the .dat file into Ripple Custody by calling Import signed operations, the same operation used to import any signed cold vault payload.
4. Verify that the vault status is Completed.

For exact UI and API steps, see:

• Complete the first-time vault handshake in the UI
• Complete the first-time vault handshake with the API

Before using the cold vault for production operations:

1. Create a test account using the cold vault.
2. Export pending operations from the online environment.
3. Transfer the .dat file to the cold vault server.
4. Upload the file to the cold bridge.
5. Confirm that the operation appears in the signing queue.
6. Download the signed .dat file.
7. Transfer the signed file back to the online environment.
8. Import the signed operations and verify the result.

For day-to-day operation steps, see Process cold vault operations with the API.