Canton configuration

Use this page to configure the Canton network endpoints and credentials in your Helm values. For the full Canton setup, including ledger and ticker registration, see Connect your validator.

This page applies to on-premises deployments only. In the hybrid model, which SaaS customers use, Ripple configures the Canton indexer: send your validator details to your Ripple liaison. For current defaults and the full supported schema, use the configuration packaged with your release.

Before you begin

Make sure that your validator meets the validator prerequisites. You need the following for each Canton network:

The Ledger API address (gRPC), the Validator API address (REST), and the DA Registry API address (REST).
The authentication method for each endpoint: none, a static JWT, or an OAuth2 client-credentials grant. For OAuth2, you also need the token endpoint and client ID.
The synchronizer ID and the DSO party ID of the network. For the DSO party IDs, see Network identifiers.

Configure the network

Add each Canton network as an entry under indexers, with setup.protocol.type set to canton. Set the authentication method for each endpoint in ledgerAuth, validatorAuth, and daRegistryAuth. This example configures Canton DevNet with OAuth2 for the Ledger API and the Validator API. The DA Registry is a public registry, so it doesn't need authentication.

indexers:
  canton-devnet:
    enabled: true
    chainIdentification: "canton-devnet"
    databaseSchema: "canton_devnet"
    setup:
      rpcUrl: "https://participant.example:5001"
      nativeCurrency: { symbol: "CC", name: "Canton Coin", decimals: 10 }
      protocol:
        type: canton
        synchronizerId: "global-domain::1220..."
        dsoParty: "DSO::1220..."
        validatorUrl: "https://validator.example:5003"
        daRegistryUrl: "https://validator.example:5003"
        ledgerAuth:
          method: oauth2
          tokenEndpoint: "https://keycloak.example.com/realms/canton/protocol/openid-connect/token"
          clientId: "uis-canton"
        validatorAuth:
          method: oauth2
          tokenEndpoint: "https://keycloak.example.com/realms/canton/protocol/openid-connect/token"
          clientId: "uis-canton"
        daRegistryAuth:
          method: none

Parameter	Type	Required	Description
`enabled`	boolean	Yes	Enables this network entry.
`chainIdentification`	string	Yes	The network ID, such as `canton-devnet`.
`databaseSchema`	string	Yes	The database schema for the network's indexer tables, such as `canton_devnet`.
`setup.rpcUrl`	string	Yes	Ledger API address (gRPC).
`setup.nativeCurrency`	object	Yes	Canton Coin: `symbol` `CC`, `name` `Canton Coin`, and `decimals` `10`.
`setup.protocol.type`	string	Yes	`canton`
`setup.protocol.synchronizerId`	string	Yes	The network's synchronizer ID.
`setup.protocol.dsoParty`	string	Yes	The network's DSO party ID.
`setup.protocol.validatorUrl`	string	Yes	Validator API address (REST).
`setup.protocol.daRegistryUrl`	string	Yes	DA Registry API address (REST).
`setup.protocol.ledgerAuth` `setup.protocol.validatorAuth` `setup.protocol.daRegistryAuth`	object	No	The authentication for the Ledger API, the Validator API, and the DA Registry API.
`<endpoint>Auth.method`	string	No	`none`, `static` for a static JWT, or `oauth2` for an OAuth2 client-credentials grant.
`<endpoint>Auth.tokenEndpoint`	string	`oauth2` only	The token endpoint of your identity provider.
`<endpoint>Auth.clientId`	string	`oauth2` only	The client ID of the OAuth2 client.

For OAuth2, create a client-credentials client in your identity provider, such as Keycloak, Auth0, or Okta. Don't put a token or client secret in the Helm values. Store it in a Secret instead.

Store the endpoint credentials

Store the static JWT or OAuth2 client secret for each authenticated endpoint in a Kubernetes Secret. An endpoint with method: none doesn't need a Secret key. Each Secret key follows the pattern CANTON_<NETWORK>_<ENDPOINT>_<CREDENTIAL>:

Part	Value
`<NETWORK>`	The network ID, in uppercase, with every non-alphanumeric character replaced by `_`. For example, `canton-devnet` becomes `CANTON_DEVNET`.
`<ENDPOINT>`	`LEDGER`, `VALIDATOR`, or `DA_REGISTRY`.
`<CREDENTIAL>`	`TOKEN` for `method: static`, or `CLIENT_SECRET` for `method: oauth2`.

For the Canton DevNet example, the Secret holds the client secrets for the Ledger API and the Validator API:

apiVersion: v1
kind: Secret
metadata:
  name: canton-devnet-auth
type: Opaque
stringData:
  CANTON_CANTON_DEVNET_LEDGER_CLIENT_SECRET: "<ledger-client-secret>"
  CANTON_CANTON_DEVNET_VALIDATOR_CLIENT_SECRET: "<validator-client-secret>"

Provision the Secret from your secret store, such as HashiCorp Vault or AWS KMS. For more information, see Advanced secret management.

Always provide credentials through a Secret, never as plain Helm values. If a referenced Secret or key doesn't exist, the endpoint runs without authentication.

Mount the Secrets

List the Secrets in canton.credentialSecrets. The service mounts every key in each Secret as an environment variable.

canton:
  credentialSecrets:
    - canton-devnet-auth

Parameter	Type	Required	Description
`canton.credentialSecrets`	list of strings	Yes	Names of the Kubernetes Secrets that hold the endpoint credentials for each Canton network.

With OAuth2, the service requests its own access token and refreshes it before it expires. The service reads each Secret once, at startup. After you add an authenticated network or rotate a credential, restart the pods.

Enforce HTTPS

Ripple Custody requires https for all three addresses. For the endpoint and proxy requirements, see Validator prerequisites.

Parameter	Type	Default	Description
`cockpit.enforceHttps`	boolean	`true`	Enforces `https` for the Canton endpoint addresses. Set it to `false` only for an in-cluster overlay that reaches the validator over plain `http`.

Next steps

After you deploy the updated values, register the Canton ledger and tickers. For more information, see Register the Canton ledger.