# Architecture and responsibilities

Ripple Custody supports Canton through a *bring your own validator* (BYOV) model. You or a node provider that you contract operate the Canton validator. Ripple Custody connects to that validator and manages your parties.

In Canton Network terms, Ripple fills the [Party Management](https://docs.canton.network/global-synchronizer/understand/validator-roles#party-management) role, and you or your node provider fill the [Validator Operator](https://docs.canton.network/global-synchronizer/understand/validator-roles) role.

## Architecture

```mermaid
flowchart LR
    subgraph Custody["Ripple Custody"]
        Core["Core and policy engine"]
        Vault["Vault<br/>(HSM or KMS)"]
        UIS["Unified Indexer Service v2<br/>(Canton indexer)"]
    end
    subgraph Customer["You or your node provider"]
        Validator["Canton validator<br/>(Splice Validator App)"]
        ValParty["Validator service party<br/>(validator-held key)"]
    end
    DAR["DA Registry"]
    Net["Canton Network<br/>(Global Synchronizer)"]

    Core --> UIS
    Vault -- "signs for your parties" --> UIS
    UIS -- "Ledger API (gRPC)<br/>Validator API (REST)" --> Validator
    UIS -- "DA Registry API (REST)" --> DAR
    Validator --> Net
    ValParty --- Validator
```

When you submit a Canton transaction order:

1. The Ripple Custody policy engine evaluates the intent and collects approvals, as on every other ledger.
2. The Canton indexer prepares the transaction on your validator.
3. The vault decodes the prepared transaction and checks it against the approved intent. For a transfer, it checks the receiver, amount, and instrument. For an `Accept`, `Reject`, or `Withdraw`, it checks the exact contract ID. For every operation, it checks the synchronizer ID. If anything doesn't match, the vault refuses to sign.
4. The vault signs with the account's Ed25519 key.
5. The indexer submits the signed transaction through your validator.
6. The indexer observes the committed update and marks the transaction as confirmed.


Each intent results in one prepared transaction, one vault signature, and one submission.

## Deployment models

The Ripple Custody deployment model and the validator model are independent. In every deployment model, you provide the validator.

| Deployment | Who runs Ripple Custody | Who runs the Canton indexer | Validator network access |
|  --- | --- | --- | --- |
| Hybrid | Ripple (SaaS) or you | Ripple, as a dedicated indexer instance connected to your validator | Allow the Ripple indexer IP addresses through your validator firewall. |
| On-premises | You | You, as part of your Custodian Helm installation | The indexer connects from inside your network. |


SaaS customers use Canton through the hybrid model only. Ripple runs a dedicated Canton indexer for your validator. Ripple Custody doesn't offer a shared Canton indexer.

In the hybrid model, your indexer instance can reach only your own validator.

For the environment requirements, see [Validator prerequisites](/products/custody/accounts-and-assets/blockchains/canton/connect-your-validator#validator-prerequisites).

## Shared responsibilities

| Responsibility | You or your node provider | Ripple |
|  --- | --- | --- |
| Operate, secure, and monitor the validator node | Yes |  |
| Keep the Splice Validator App on the latest release | Yes |  |
| Install and update the DARs for the CIP-56 tokens that you hold | Yes |  |
| Provide Ledger API, Validator API, and DA Registry API endpoints over TLS, with credentials | Yes |  |
| Grant the Ledger API user rights that Ripple Custody needs | Yes |  |
| Keep a Canton Coin balance on the validator operator party for network fees | Yes |  |
| Hold the validator service party key, and collect validator rewards | Yes |  |
| Move rewards from the validator service party to a Ripple Custody account, if you want them in custody | Yes |  |
| Allow the Ripple indexer IP addresses through your firewall (hybrid) | Yes |  |
| Provision and operate the Canton indexer (hybrid) |  | Yes |
| Provision and operate the Canton indexer (on-premises) | Yes |  |
| Configure the validator endpoints and credentials in Ripple Custody (hybrid) | Provide them to Ripple | Yes |
| Configure the validator endpoints and credentials in Ripple Custody (on-premises) | Yes |  |
| Register the Canton ledger and tickers with `v0_CreateLedger` and `v0_ValidateTickers` intents | Yes |  |
| Generate and protect each account's Ed25519 party key in your vault |  | Yes, through your vault's HSM or KMS |
| Check every transaction against its approved intent before signing |  | Yes |
| Apply your policies, approvals, quarantine rules, and audit trail to Canton operations |  | Yes |
| Index balances and transaction history |  | Yes |
| Migrate parties from another custodian | Yes, if applicable: create new Ripple Custody parties, transfer the balances, and retire the old parties |  |


## Security model

- Ripple Custody doesn't run validator infrastructure and doesn't hold validator keys.
- Your validator hosts your parties but doesn't hold their signing keys. It can't move your Ripple Custody assets without a signature from your vault.
- The validator service party's key stays with the validator, because the Canton Network requires it to sign autonomously for traffic top-ups, reward collection, and pre-approval renewals. This key doesn't control any Ripple Custody account, and running a validator doesn't put Ripple Custody assets at risk. It does mean that you or your node provider keep an operational signing responsibility outside Ripple Custody.
- A policy-approved `v0_CreateLedger` intent sets the validator operator party, the DSO party, and the DA Registry operator once. Ripple Custody stores these values in its trusted collections and reads them back for every later check, instead of fetching them again from the network.
- In the BYOV model, account data sits on your validator, which puts data residency under your control.