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

## Architecture overview

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:


```mermaid
graph TB
    subgraph ExtUsers["External Users & Apps"]
        USER[End Users]
        MOBILE[Mobile App]
        DESKTOP[Desktop App]
        THIRDPARTY[Third-Party Apps]
    end

    subgraph Interaction["Interaction Layer"]
        WEBUI[Web UI]
        NOTIF[Notification Server]
        AUTH[Authentication Server]
    end

    subgraph Core["Core & Governance Layer"]
        APIGW[API Gateway]
        LEDGERACCT[Ledger Accounting]
        EVENTPROC[Event Processing]
        GOVENGINE[Governance Engine]
        AMQP[RabbitMQ]
    end

    subgraph Blockchain["Blockchain Integration Layer"]
        BTCIDX[NBXplorer]
        ETHIDX[ETH Indexer]
        XRPIDX[XRPL Indexer]
        OTHERIDX[Other Indexers]
    end

    subgraph Security["Security & Key Management Layer"]
        NBRIDGE[Notary Bridge]
        NOTARY[Notary]
        VAULTCORE[Vault]
        KMSCONNECT[KMS Connect]
    end

    subgraph External["External Infrastructure"]
        HSM[HSM/KMS]
        POSTGRES[(PostgreSQL)]
        NODES[Blockchain Nodes]
    end

    USER --> WEBUI
    MOBILE --> AUTH
    DESKTOP --> AUTH
    THIRDPARTY --> APIGW
    WEBUI --> APIGW
    WEBUI --> NOTIF
    APIGW --> AMQP
    AMQP --> GOVENGINE
    AMQP --> EVENTPROC
    AMQP --> LEDGERACCT
    GOVENGINE --> POSTGRES
    GOVENGINE --> NBRIDGE
    NBRIDGE --> NOTARY
    NOTARY --> KMSCONNECT
    GOVENGINE --> VAULTCORE
    VAULTCORE --> KMSCONNECT
    KMSCONNECT --> HSM
    LEDGERACCT --> BTCIDX
    LEDGERACCT --> ETHIDX
    LEDGERACCT --> XRPIDX
    LEDGERACCT --> OTHERIDX
    BTCIDX --> NODES
    ETHIDX --> NODES
    XRPIDX --> NODES
    OTHERIDX --> NODES

    classDef trusted fill:#90EE90,stroke:#006400,stroke-width:3px
    classDef untrusted fill:#FFB6C1,stroke:#8B0000,stroke-width:2px
    classDef external fill:#87CEEB,stroke:#00008B,stroke-width:2px
    classDef hsm fill:#FF6347,stroke:#8B0000,stroke-width:3px

    class GOVENGINE trusted
    class WEBUI,NOTIF,AUTH,APIGW,LEDGERACCT,EVENTPROC untrusted
    class POSTGRES,NODES external
    class HSM,NOTARY,VAULTCORE hsm
```

### Color coding

- **🟢 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


## Interaction layer

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](/products/custody/v1.34/concepts/security).

### Web UI

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


### Desktop app and mobile app

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.

| Platform | Requirements |
|  --- | --- |
| **Desktop** | Windows only |
| **iOS** | v15.1 or later |
| **Android** | v7.0 (SDK 24) or later |


The mobile app is tested primarily on stock Android OS. While the app may function on custom Android operating systems (such as OxygenOS, GrapheneOS, LineageOS), full compatibility is not guaranteed.

### Notification server

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


### Authentication server

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


## Core and governance layer

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](/products/custody/v1.34/concepts/security).

### API gateway

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


### Governance engine

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.

### Ledger accounting service

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.

### Event processing

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.

### AMQP broker (RabbitMQ)

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](/products/custody/v1.34/system-management/events).

## Blockchain integration layer

The blockchain integration layer monitors and indexes supported blockchains.

### Indexers

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:

#### Legacy indexers

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

#### Unified Indexer Service (UIS)

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](/products/custody/v1.34/overview/architecture/unified-indexer-service).

### Supported blockchain indexers

| Indexer | Blockchains |
|  --- | --- |
| NBXplorer | Bitcoin, Litecoin, Dogecoin |
| ETH Indexer | Ethereum, Polygon, Arbitrum |
| XRPL Indexer | XRP Ledger |
| Solana Indexer | Solana |
| Other Indexers | Stellar, Tezos, and more |


## Security and key management layer

The security and key management layer handles all cryptographic operations. For detailed security architecture, see [Security](/products/custody/v1.34/concepts/security).

### Notary

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

### Vault

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)


## External infrastructure

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

### Key management system (KMS)

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

| Type | Examples |
|  --- | --- |
| Hardware HSM | Thales Luna, Ultimaco BlockSafe, Securosys Primus |
| Cloud HSM | AWS CloudHSM, IBM HPCS, Google Cloud KMS |
| MPC | Multi-Party Computation clusters |


For a list of supported KMSs and configuration guides, see [Initialize and connect a KMS](/products/custody/v1.34/get-started/deployment/deploy-kms).

### PostgreSQL database

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

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.

### Deployment infrastructure

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 components

### Compliance adapter

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

### Coinbase adapter

Optional adapter for Coinbase integration.

## Related topics

- [Security](/products/custody/v1.34/concepts/security) - Zero-trust architecture and trust model
- [Key management](/products/custody/v1.34/concepts/key-management) - Cryptographic hierarchy and key operations