Unified Indexer Service

The Unified Indexer Service (UIS) is the blockchain indexing architecture used by Ripple Custody for ledger-specific indexing, event processing, and ledger APIs. UIS uses a decomposed, chain-specific adapter architecture with isolated ledger and network components.

For a complete and up-to-date list of which ledgers are supported, please refer to the Supported blockchain ledgers page.

The Unified Indexer Service indexes blockchain data and exposes it to Ripple Custody through a small set of services:

For on-premises deployments, each indexer connects to a blockchain node that you provision — see On-premises node requirements below.

Ripple Custody supports a wide range of blockchains. Depending on the chain, indexing is handled either by UIS or by a standalone indexer. For on-premises deployments from v1.26:

• Solana, TRON, and XRPL use UIS automatically and do not require a per-network UIS configuration setting.
• Arbitrum, Base, and Optimism require UIS and must be explicitly configured with type: "uis" to be operable.
• Ethereum, Polygon, and Stellar continue to use existing standalone indexers unless you explicitly configure them to use UIS.

For an on-premises deployment of UIS, you are responsible for provisioning and maintaining your own blockchain nodes. The service must be able to connect to these nodes to index transactions. The following table lists minimum node requirements for on-premises UIS deployments. Check the configuration packaged with your release for release-specific changes.

For SaaS deployments, UIS is enabled and managed by Ripple for supported chains.

For on-premises deployments, UIS is available from v1.26 or later.

Use UIS automatically:

Must be explicitly configured to use UIS:

To enable UIS for a specific chain, set the type parameter to "uis" in that network's configuration block within your Helm chart's values.yaml file.

The example code below shows the correct structure for enabling the UIS for an Optimism Sepolia testnet:

ledgers:
  evm:
    networks:
      - name: optimism-sepolia
        type: "uis"  # Enable UIS for this network
        raw_config: |
          tracker.opindexer-sepolia.base-url = "http://api-management-uis"
          ...
        indexer:
          ...
          node:
            # URL for your provisioned Optimism Sepolia node.
            url: "http://your-optimism-sepolia-node-url"

For complete step-by-step migration instructions, including pre-migration setup, database preparation, and validation steps, see the UIS on-premises migration guide.

If your EVM blockchain node requires authentication (for example, a Besu node that issues short-lived JWTs, or a third-party provider that expects a static header token), add an authentication block to the network's indexer.node config. This automatically deploys a Node Gateway sidecar in the same pod as the EVM indexer.

Use mode: header to inject a fixed key-value pair into every outbound request:

ledgers:
  evm:
    networks:
      - name: mainnet
        type: "uis"
        indexer:
          node:
            url: "https://eth-node-provider.internal/"
            authentication:
              mode: header
              header:
                key: "x-auth-token"
                value: "secret"

Use mode: customJwt when the node requires a short-lived bearer token fetched from a separate token endpoint. Node Gateway fetches and caches the token, refreshing it before expiry.

ledgers:
  evm:
    networks:
      - name: testnet-goerli
        type: "uis"
        indexer:
          node:
            url: "https://example-mas-node.internal/"
            authentication:
              mode: customJwt
              customJwt:
                tokenUrl: "https://example.com/api/generate-access-token"
                tokenMethod: POST
                apiKeyHeader: "x-api-key"
                apiKeyValue: "your-api-key"
                requestBody:
                  signature: "your-signature"
                tokenJsonPath: data
                tokenExpirySeconds: 3600
                refreshBufferSeconds: 300

customJwt field reference: