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 following diagram shows how UIS components fetch blockchain data, normalize it, and expose indexed events to internal consumers such as Ledger Accounting.

Data flow:

1. Ledger Adapters connect to blockchain nodes and fetch blockchain data. For EVM chains with node authentication configured, the Ledger Adapter routes requests through the Node Gateway sidecar, which injects the required credentials before forwarding to the node.
2. The Generic Indexer orchestrates data fetching through adapters. Each ledger and network combination has its own stateful Generic Indexer instance.
3. After data is fetched, the Generic Indexer indexes the data and stores it in the outbox table.
4. The Processor reads the outbox table and generates standardized events.
5. The Processor writes events to the database.
6. The Events API reads from the database and provides indexed data to consumers.
7. Ledger Accounting pulls events through the Events API.
8. Ledger APIs provide stateless access to live blockchain data from nodes, not indexed data.

The UIS consists of several components that work together:

All installed UIS components are required for proper operation. The system is designed as an integrated whole, and removing any component will cause failures.

For example, if you are using Solana:

Each component plays a critical role in the data flow pipeline.

The UIS uses the Bulkhead Pattern for fault isolation. Three components are run for each ledger and network combination:

• Ledger API - Provides access to live blockchain data for that specific ledger/network
• Ledger Adapter - Translates blockchain-specific data for that ledger/network
• Generic Indexer - Orchestrates data fetching for that specific ledger/network

These three components are duplicated for each ledger and network. This means:

• Network-level isolation: If XRPL testnet goes down, XRPL mainnet remains unaffected
• Ledger-level isolation: If Solana experiences issues (node failure, resource spike), it does not impact XRPL, TRON, or other ledgers
• Independent scaling: Each ledger/network combination can be scaled independently based on its specific needs

This isolation ensures that failures are contained and do not cascade across the system.

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: