System architecture

The Ripple Custody platform is built on a layered architecture that separates concerns between user interaction, business logic, blockchain integration, and security. This page provides an overview of the system architecture and all its components.

The components of the Ripple Custody infrastructure are organized into the following layers:

• Interaction layer: Customer-facing components (Web UI, mobile/desktop apps, notifications, authentication)
• Core and governance layer: Business logic, API gateway, governance engine, and message processing
• Blockchain integration layer: Indexers that monitor and interact with blockchain networks
• Security and key management layer: notary and vault services with KMS backends
• External infrastructure: Customer-managed databases, blockchain nodes, and deployment infrastructure

The following diagram shows these layers and how they interact:

• 🟢 Green (Trusted): Governance Engine - the only trusted component
• 🔴 Pink (Untrusted): All other application components (defense in depth)
• 🔵 Blue (External): Customer-managed infrastructure (database, blockchain nodes)
• 🔴 Red (Security): notary, vault, and HSM/KMS backends

The interaction layer enables consumption of the core services for customer-facing applications. All services in the interaction layer are untrusted. For more information, see Security.

The Web UI is a back-office user interface for Ripple Custody. It provides administrators and operators with a graphical interface to manage the platform. Available in two versions:

• Web UI v1: Connects to the API Gateway via HTTP (REST)
• Web UI v2: Uses GraphQL for improved performance

These apps perform authorization and authentication functions for the Web UI. They can be used interchangeably to approve transactions and authenticate users via push notifications.

The notification server manages notifications for the Web UI and mobile/desktop apps. It:

• Pushes notifications via WebSocket
• Acts as an intermediary for dynamic message passing (e.g., triggering authorization requests)
• Handles SMTP-based email delivery with TLS/SSL support

The authentication server is an OpenID Connect (OIDC) server used for JSON Web Token (JWT) generation and authentication. Ripple Custody follows a "batteries included but replaceable" model:

• Default: Keycloak (appears as "harmonize" provider in the GUI/APIs)
• Alternative: External OAuth/OIDC provider of your choice

The core and governance layer contains the main business logic. These components orchestrate all system functions and provide governance, accounting, and transaction execution services.

The only trusted component in this layer is the governance engine. All others are untrusted. For more information, see Security.

The API gateway exposes the REST API and performs validation checks when accepting user requests. It:

• Validates authentication tokens (JWTs)
• Routes traffic to the correct internal service
• Forwards requests to the AMQP message queue for processing
• Supports HTTP (REST) and gRPC protocols

The governance engine is the only trusted component in the platform. It enforces system governance and updates the system state when all conditions of the governance workflow are fulfilled. It:

• Stores a record of the complete state of all trusted entities with revision history
• Validates every proposed change against a tamper-proof Merkle tree
• Executes system updates regulated by the governance framework
• Cryptographically signs all critical data before writing to the database

The governance engine must run as a singleton because it performs Merkle tree operations that cannot be parallelized.

The ledger accounting service handles:

• System accounting, balance, and transaction management
• Ledger-specific business logic
• Reading from and writing to the indexers
• Chain update management
• Core compliance processes (e.g., quarantine management for incoming transfers)

This service runs as a singleton by design.

The event processing service consumes messages from the AMQP broker. It processes events and executes asynchronous tasks, such as updating a transaction's state after indexing.

The AMQP (Advanced Message Queuing Protocol) broker queues requests and distributes events. It:

• Enables asynchronous processing
• Supports persistent, replicated queues (Quorum Queues)
• Can be deployed internally or externally

For more information, see Event tracking.

The blockchain integration layer monitors and indexes supported blockchains.

Indexers act as intermediaries between the ledger accounting service and blockchain nodes. They:

• Fetch blocks from blockchain nodes
• Identify transactions related to Ripple Custody accounts
• Pass transaction data to the ledger accounting service for processing

Ripple Custody supports two indexer architectures:

Chain-specific services that actively monitor blockchain nodes. Each indexer runs as a single replica per chain, with state stored in PostgreSQL.

Available from Ripple Custody v1.26, the UIS provides a component-based architecture:

• Generic indexer: Orchestrates data fetching.
• Processor: Handles business logic
• Ledger adapters: Translates blockchain-specific data.

The UIS uses a bulkhead pattern where each ledger runs in an isolated container, preventing failures in one chain from affecting others.

For more information, see Unified Indexer Service.

The security and key management layer handles all cryptographic operations. For detailed security architecture, see Security.

The notary service approves transactions and signs them with the master key. It consists of:

• notary bridge: Proxy service between the governance engine and notary (supports HTTP or gRPC)
• notary service: Performs transaction-signing operations
• KMS Connect Sidecar: Platform-specific KMS connectivity

The notary must run as a singleton and stores its state in the Anti-Rewind File (ARF).

The vault maintains the safety of key material and performs signing operations. It:

• Executes transaction orders only after approval from the governance engine
• Derives account keys and signs blockchain transactions
• Verifies notary signatures before performing key operations
• Connects to KMS backends via the KMS Connect sidecar

The vault consists of:

• Vault core: Key derivation and custody operations (port 10054)
• Vault bridge: Bridge service for vault operations
• KMS Connect Sidecar: Platform-specific KMS connectivity (port 10000)

You can use multiple vaults for different purposes:

• Key storage with different KMS types
• Key isolation (hot vault for online wallets, cold vault for offline wallets)

These components are customer-managed and interact with the core platform.

The KMS protects cryptographic keys and performs signing operations. Ripple Custody supports:

For a list of supported KMSs and configuration guides, see Initialize and connect a KMS.

The PostgreSQL database stores:

• System state and configuration
• Transactions and accounts
• Policies and user data
• Indexer state

The database requires:

• Production-grade HA solution (e.g., 3-node cluster with Patroni, or AWS RDS Multi-AZ)
• Synchronous replication (highly recommended)
• Regular backups synchronized with ARF backups

Blockchain nodes receive transactions from indexers and return blockchain information. Options include:

• Self-hosted: Bitcoin, XRPL, Solana nodes with RPC/Basic Auth
• Third-party providers: Infura, Alchemy, QuickNode (API key authentication)

Use a load balancer to provide a single, highly-available endpoint.

Ripple Custody is deployed on Kubernetes with:

• Namespaces: custody-core and custody-vault (security isolation)
• Container registry: Private registry with image mirroring and cosign verification.
• Secrets manager: HashiCorp Vault, CyberArk Conjur (External Secrets Operator).
• Ingress: TLS termination and routing

Optional services that connect to third-party compliance and screening API providers (e.g., Chainalysis, Elliptic) for transaction screening and regulatory compliance.

Optional adapter for Coinbase integration.

• Security - Zero-trust architecture and trust model
• Key management - Cryptographic hierarchy and key operations