Ripple Custody separates interaction services, asynchronous workflows, and isolated signing boundaries. Users, applications, and services submit requests through the interaction layer. The platform accepts mutation requests for asynchronous processing, runs the relevant workflow state machine, evaluates policy, persists operational state, and uses protected signing components only through narrow interfaces.
- Mutation requests use intents: Administrative changes, account and vault changes, endpoint updates, transaction orders, and compliance operations enter the governed workflow as intents.
- API intake is asynchronous: Intent proposal, approval, and rejection calls return
202 Acceptedwhen the request is accepted for processing. The workflow then continues through queued SAGA-style state transitions. - Sensitive operations run in protected boundaries: The notary evaluates policy and protects trusted state. The vault independently verifies notary attestations before signing blockchain transactions.
- Private keys stay protected: User keys, notary keys, vault keys, Gateway system-signing keys where enabled, and blockchain signing keys stay outside general application services.
- Operational dependencies are explicit: PostgreSQL, AMQP, blockchain nodes, certificates, secrets, KMS/HSM/MPC backends, and identity providers provide the operating foundation.
Architecture decisions in Ripple Custody directly affect asset safety, recovery, auditability, and operational resilience. Use this page to understand the main components, trust boundaries, runtime flows, and design questions before you plan deployment, governance, key management, or integrations.
| Principle | What it means |
|---|---|
| Governed by default | Domain, user, policy, vault, account, endpoint, transaction order, and compliance mutation operations use the intent workflow. |
| Asynchronous request-response | API calls that start governed work accept the request, return a request ID, and let the workflow state machine complete the work asynchronously. |
| Narrow protected boundary | Policy evaluation, trusted-state attestation, and raw blockchain transaction signing happen only inside protected notary and vault boundaries. |
| Isolated key material | KMS, HSM, or MPC systems perform sensitive key operations. General application services do not receive private keys. |
| Verifiable state | Database records, queued work, and service outputs are not trusted by placement alone. Trusted state and signing operations are checked with cryptographic controls. |
| Explicit dependencies | Infrastructure services are part of the runtime system boundary, but deployment topics cover how those services are hosted and operated. |
The platform is easier to reason about as five cooperating areas:
- Interaction and identity: Web UI, API clients, service callers, GraphQL, API Gateway, identity provider, and notifications.
- Workflow and accounting: AMQP-backed workflow state machines, Approval/Notary Bridge, Ledger Accounting, and Event Processing.
- Protected trust boundary: Notary, vault, cold vault bridge, KMS Connect, and KMS/HSM/MPC backends.
- Blockchain integration: Ledger APIs, adapters, processors, blockchain indexing services, and blockchain nodes.
- Infrastructure dependencies: PostgreSQL, AMQP broker, certificates, secrets, container registry, blockchain nodes, and external providers.
A useful mental model is "user space" and "kernel space." Most platform services run in user space: they authenticate users, accept API calls, queue work, display data, and coordinate workflows. Sensitive security operations run in kernel space: policy evaluation and trusted-state attestation in the notary, and raw blockchain transaction signing in the vault. The interface between the two areas is intentionally narrow and cryptographically checked.
Ripple Custody uses a zero-trust model. In this context, "trusted" does not mean "important." It means a component is part of the cryptographic boundary that prevents unauthorized trusted-state changes or unauthorized transaction signing.
| Boundary | Includes | Role | Design question |
|---|---|---|---|
| Client and interaction boundary | Web UI, API clients, service callers, API Gateway, GraphQL, identity provider, notification services | Authenticates callers, accepts requests, exposes data, and routes work. These services do not make a state mutation trusted by themselves. | Which users, service callers, tokens, certificates, and ingress paths are allowed? |
| Workflow and accounting boundary | AMQP workflows, Approval/Notary Bridge, Ledger Accounting, Event Processing | Runs workflow state machines, coordinates approvals, accounts for balances, persists operational state, and processes events. | Which components must be singleton, horizontally scaled, or monitored for backlog? |
| Protected trust boundary | Notary, vault, KMS Connect, KMS/HSM/MPC, Vault Bridge or Cold Bridge | Evaluates policies, protects trusted state, validates signatures, prevents state rewind, and signs blockchain transactions only after vault verification of notary attestation. | Where do notary, vault, and KMS run, and how are they isolated from workflow and interaction services? |
| Infrastructure dependencies | PostgreSQL, AMQP broker, blockchain nodes, secrets, certificates, registry, network routes | Provides persistence, messaging, ledger access, and operational security. | Which dependencies must be available for each runtime flow? |
| External integration boundary | Compliance providers, webhook receivers, third-party node providers, corporate proxies | Extends the platform to screening, event delivery, or ledger connectivity outside the platform. | What happens when an external provider is unavailable, slow, or misconfigured? |
For the detailed security model, see Security model. For HA, DR, and ownership categories, see Resilience planning.
Ripple Custody runs in three deployment models. The trust boundaries above are the same in all three; what changes is who deploys and operates each component. In both SaaS models, the customer keeps operating the key-material side of the protected trust boundary, so neither party can sign transactions alone.
| Component | On-premises | SaaS (Vault with HSM) | SaaS (MPC) |
|---|---|---|---|
| Core platform services (API gateway, workflows, accounting, notary, event processing) | Customer | Ripple | Ripple |
| Web and API applications | Customer | Ripple | Ripple |
| Blockchain indexers | Customer | Ripple | Ripple |
| PostgreSQL and AMQP broker | Customer | Ripple | Ripple |
| Vault and KMS Connect | Customer | Customer | Ripple |
| KMS/HSM backend | Customer | Customer | Not used; MPC key management replaces the HSM |
| MPC Nodes 0 and 1, Relay Server | Not applicable | Not applicable | Ripple |
| MPC Nodes 2 and 3 | Not applicable | Not applicable | Customer |
- On-premises: you deploy and operate the full stack in your own infrastructure.
- SaaS (Vault with HSM): Ripple hosts the platform; you deploy and operate the vault, KMS Connect, and the HSM that holds your key material in your own environment.
- SaaS (MPC): Ripple hosts the platform, the vault, MPC Nodes 0 and 1, and the Relay Server; you deploy and operate MPC Nodes 2 and 3 in your own infrastructure. Signing uses a 3-of-4 threshold across the four nodes, so neither party can sign alone. See the MPC overview.
Most administrative and operational changes use the same intent lifecycle: submit, accept for asynchronous processing, evaluate policy, collect approvals where required, execute the relevant workflow transition, and record auditable state.
User-signed intents include a user author and a client-side signature. API-only system-signed proposals omit the user author and client-side payload signature; the Gateway signs them internally only when system-signed intent processing, trusted public key registration, and matching SystemSigned policies are in place. For the request structures, see Intent request structure.
Outgoing blockchain transactions add an attestation, signing, and broadcast phase after governance approval. The notary does not push a signing order to the vault. The vault independently polls for work, verifies the notary attestation and request data, builds the ledger-specific transaction, and asks its KMS backend for the protected signing operation.
Hot vaults perform the vault signing steps online. Cold vaults replace the online vault polling and upload steps with an operator-mediated air-gapped flow. For status details, see Transaction status.
Incoming transfers and on-chain status updates start from blockchain observation rather than user initiation.
Indexing services identify ledger activity relevant to custody accounts and normalize chain-specific data. Ledger Accounting pulls indexed events and persists the resulting operational state. Product-level Events API and webhook delivery expose platform events to customer systems. For details, see Unified Indexer Service.
| Component | Primary role | Trust and state model | Runtime shape | More detail |
|---|---|---|---|---|
| Web UI | Back-office interface for operators and administrators. | Interaction layer; stateless. | Multiple replicas. | Use the UI |
| Auth and Sign app | Stores user signing material and signs UI authentication or intent operations. | Client-side user key holder. | User device application. | Register and log in with the UI |
| API Gateway | Public API entry point for clients and components; validates JWTs and request shape. | Interaction layer; stateless. | Multiple replicas. | Use the API |
| GraphQL | Data layer for Web UI v2. | Interaction layer; stateless. | Multiple replicas. | Resilience planning |
| Identity provider | Issues JWTs for UI, API, and service callers. | Security dependency; configuration-sensitive. | Keycloak or external OIDC provider. | Authentication |
| Notification server and core extensions | Delivers WebSocket and email/user-invitation notifications. | Interaction layer; stateless. | Multiple replicas where enabled. | Notifications configuration |
| Intent workflow state machines | Drive asynchronous SAGA-style processing for proposals, approvals, transaction orders, and other mutation operations. | Workflow layer; stores operational progress through Ledger Accounting and PostgreSQL. | Depends on workflow and queue topology. | Manage intents and approvals |
| Approval / Notary Bridge | Moves workflow messages between AMQP-backed services and the notary boundary. | Bridge into protected trust boundary; stateless. | Singleton. | Notary configuration |
| Notary | Evaluates policies, validates trusted state, signs Merkle roots and trusted-state attestations, and maintains anti-rewind protection. | Protected trust boundary; stateful through ARF and append-only trusted-state data. The notary does not write platform state directly to PostgreSQL. | Singleton. | Data integrity and governance |
| Vault | Verifies notary attestations, derives account keys, builds ledger-specific transactions, and signs blockchain transactions through KMS/HSM/MPC. | Protected trust boundary; stateless at runtime. | Two or more replicas for hot vaults; cold vaults use an air-gapped pattern. | Manage vaults |
| Vault Bridge / Cold Bridge | Supports air-gapped cold vault signing workflows. | Secure signing support component. | One per cold vault environment. | Cold vaults |
| KMS Connect | Connects notary, vault, or Gateway-dedicated system-signing components to a selected KMS backend. | Key-management adapter; private keys remain protected by backend controls. | Sidecar or connected service depending on integration. | KMS integration |
| Ledger Accounting | Tracks balances, transaction state, ledger-specific processing, compliance-related accounting, and persisted workflow outcomes. | Workflow and accounting layer; operational state in PostgreSQL. | Singleton. | Transactions and transfers |
| Blockchain indexing services | Monitor blockchain nodes, normalize ledger activity, and expose indexed data that Ledger Accounting consumes. | Blockchain integration; state stored in PostgreSQL or component-specific tables. | One per ledger/network pattern; UIS isolates ledger/network components. | Unified Indexer Service |
| Event Processing | Consumes AMQP messages and performs asynchronous work such as event updates and webhook delivery. | Workflow layer; stateless. | One or more replicas depending on queue setup. | Events and webhooks |
| AMQP broker | Queues requests and asynchronous tasks. | Infrastructure dependency; stateful queues. | Highly available RabbitMQ or compatible AMQP v0.9 broker. | Message queue planning |
| PostgreSQL | Stores platform state, operational records, indexer state, and wrapped key material where applicable. | Infrastructure dependency; stateful. Trusted-state integrity is verified cryptographically. | Production HA database. | Database planning |
| KMS / HSM / MPC | Protects cryptographic keys and performs signing or key-generation operations. | Cryptographic dependency. | HSM HA cluster, cloud HSM, or MPC network. | Key management planning |
| Blockchain nodes | Provide ledger RPC access for broadcast, status checks, fee data, and indexing. | Customer-managed or third-party dependency. | Redundant node endpoints recommended. | Blockchain node planning |
| Compliance services and adapter | Run transaction-screening and Travel Rule compliance workflows through configured providers. | Optional integration layer. | Enabled when transaction screening or Travel Rule integrations are required. | Compliance |
| Topic | Description |
|---|---|
| Security model | Zero-trust model, key management, secure communication, and data integrity. |
| Governance model | Domains, policies, intents, approvals, and genesis design. |
| Data integrity and governance | Trusted entities, Merkle tree, ARF, and signature verification. |
| Secure communication | TLS, JWTs, mTLS, application-layer signatures, and dependency connections. |
| Deployment overview | Planning, installation, configuration, and verification sequence. |
| Resilience planning | Component ownership, state, HA, and DR model. |