# Unified Indexer Service

The Unified Indexer Service is the blockchain indexing architecture used by Ripple Custody for ledger-specific indexing, event processing, and ledger APIs. It has two versions: UIS v1 and its rewrite, UIS v2. UIS v2 runs one indexer for each network, plus a processor, a Blockchain API, and a configuration service (Cockpit) that all networks share.

For a complete and up-to-date list of which ledgers are supported, please refer to the [Supported blockchain ledgers](/pt-br/products/custody/reference/supported-ledgers) page.

This page describes UIS v2, which SaaS deployments have run since version 1.40 and on-premises deployments run starting in version 1.43. To move an on-premises deployment to UIS v2, see [Deployment-affecting changes](/pt-br/products/custody/support/change-history/v143#deployment-affecting-changes) in the version 1.43 release notes.

## How it works

UIS v2 indexes blockchain data and exposes it to Ripple Custody through a small set of services:

| Service | Description |
|  --- | --- |
| Indexer | Reads blocks from a blockchain node and records them. One indexer runs per ledger and network (for example, Solana devnet and Solana mainnet each run their own indexer), so an issue on one network does not affect the others. |
| Processor | Turns indexed blocks into the transaction events consumed by Ripple Custody. Shared across all ledgers. |
| Blockchain API | The single interface for blockchain operations — retrieves events, checks balances, prepares and broadcasts transactions. Shared across all ledgers. |
| Cockpit | Holds the ledger and network configuration that UIS v2 runs against. This configuration is managed by Ripple Custody. |


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

## Supported chains and indexer types

The following table lists the chains that each indexer serves:

| Indexer | Chains | Status in version 1.43 |
|  --- | --- | --- |
| Legacy indexers | Ethereum, Polygon, Avalanche C-Chain, and Binance Smart Chain (ETH Indexer); Stellar (Stellar Indexer). | Not supported. Migrate to UIS v2. |
| UIS v1 | [EVM ledgers](/pt-br/products/custody/reference/supported-ledgers#ethereum-virtual-machine-evm-ledgers), Solana, Stellar, TRON, and XRPL. | Not supported. Migrate to UIS v2. |
| UIS v2 | The same chains as UIS v1, plus Canton and Sui: [EVM ledgers](/pt-br/products/custody/reference/supported-ledgers#ethereum-virtual-machine-evm-ledgers), Solana, Stellar, TRON, XRPL, Canton, and Sui. | Required for these chains. |
| Chain-specific indexers | Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, and Dash (NBXplorer); Cardano; Algorand; Hedera; Polkadot (Substrate Indexer); Tezos. | Unchanged. |


Starting in version 1.43, EVM, Solana, Stellar, TRON, and XRPL networks are served by UIS v2 only, as part of [ledger accounting refactor phase 2](/pt-br/products/custody/support/change-history/v140#ledger-accounting-refactor-phase-2). On-premises deployments migrate to UIS v2 on version 1.43.

UIS v2 is available as follows:

| Deployment type | UIS v2 available from | Migration |
|  --- | --- | --- |
| SaaS | Version 1.40 | Ripple runs the migration. |
| On-premises | Version 1.43 | You run the migration. See the [Ledger accounting phase 2 migration guide](/pt-br/products/custody/operations-and-maintenance/upgrading/ledger-accounting-phase-2-migration). |


Change for on-premises deployments in version 1.43
Starting in version 1.43, on-premises deployments can move to UIS v2, and you run the migration yourself. EVM, Solana, Stellar, TRON, and XRPL networks that use legacy indexers or UIS v1 (`type: "uis"`) need to move to UIS v2 (`type: "uis-v2"`). For the prerequisites and the procedure, see the [Ledger accounting phase 2 migration guide](/pt-br/products/custody/operations-and-maintenance/upgrading/ledger-accounting-phase-2-migration).

## On-premises node requirements

For an on-premises deployment of UIS v2, 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 v2 deployments. Check the configuration packaged with your release for release-specific changes.

| Blockchain | Node type | Minimum version | Connection | Archive requirement | Additional details |
|  --- | --- | --- | --- | --- | --- |
| **Arbitrum** | Geth compatible | v3.7.X | JSON-RPC over HTTP | Non-Archive | Debug mode must be enabled. |
| **Base** | Geth compatible | v0.14.1 | JSON-RPC over HTTP | Non-Archive | Debug mode must be enabled. |
| **Ethereum** | Geth | v1.16.4 | JSON-RPC over HTTP | Archive (Required) | Debug APIs must be enabled. High request volume (~1.2k - 300k/hour). |
| **Optimism** | Geth compatible | v1.101511 | JSON-RPC over HTTP | Non-Archive | Debug mode must be enabled. |
| **Polygon** | Geth compatible | v1.16.4 | JSON-RPC over HTTP | Archive (Required) | Debug mode must be enabled. |
| **Solana** | Agave | mainnet 2.3.10 / devnet 3.0.0 | JSON-RPC over HTTP | Archive Recommended | Estimated request volume is ~9000/hour. No debug mode needed. |
| **Stellar** | Horizon | v23.0.0 | HTTP | Archive (Preferred) | Requires `application/x-www-form-urlencoded` content-type for broadcasting transactions. |
| **TRON** | FullNode | v4.8.0 | RPC over HTTP | Archive (Preferred) | Estimated request volume is ~150k/day. |
| **XRPL** | FullNode | 2.6.X | HTTP | Archive Recommended | Request volume is not based on tracked accounts. |


## Configuration

### SaaS deployments

For SaaS deployments, Ripple runs UIS v2 for supported chains, and Ripple runs the migration to UIS v2.

### On-premises deployments

For on-premises deployments, configure each EVM, Solana, Stellar, TRON, and XRPL network in the `ledger-accounting` values with `type: "uis-v2"`, and set the URL of the node that you provisioned under `indexer.values.node`:

```yaml
ledgers:
  <chain>:
    networks:
      - name: <network>
        type: "uis-v2"
        indexer:
          values:
            node:
              url: "https://<your-node-url>"
```

Keep your existing chain keys and network names, and change only `type`.

If a network uses `raw_config`, also declare `ledger.<name>.indexer-network-name` in it. For other networks, the `ledger-accounting` chart generates this value automatically. Without it, chart rendering fails, and the error message shows the exact line to add.

To move an existing deployment to UIS v2, follow the [Ledger accounting phase 2 migration guide](/pt-br/products/custody/operations-and-maintenance/upgrading/ledger-accounting-phase-2-migration). For any questions about the deployment process, contact your Customer Partner Engineer (CPE) or the Support team.

### Node authentication

If a blockchain node requires a login, add an `authentication` block next to `node.url`. It takes either a static `header` or a `customJwt` token fetched from a token server:

```yaml
ledgers:
  <chain>:
    networks:
      - name: <network>
        type: "uis-v2"
        indexer:
          values:
            node:
              url: "https://<private-node>"
              authentication:
                # A static header. For Basic authentication, use the key Authorization
                # and the value "Basic <base64 of user:password>".
                header:
                  key: x-api-key
                  value: <api-key>
                # Or a token fetched from a token server:
                # customJwt:
                #   tokenUrl: https://<token-server>/token
                #   apiKeyHeader: x-api-key
                #   apiKeyValue: <api-key>
                #   requestBody:           # optional
                #     signature: <signature>
                #   tokenJsonPath: data    # optional; the reply field that holds the token (default: data)
```

When at least one network has an `authentication` block, the chart deploys a node gateway (`uis-v2-node-gateway`) with a Service and a Secret. The gateway adds the login to each call and forwards it to `node.url`.

- Networks without an `authentication` block call their node directly. If no network has one, the chart doesn't deploy the gateway.
- `authentication` accepts only `header` and `customJwt`. Any other key fails the installation. OAuth2 isn't supported.
- Credentials (`header.value`, `customJwt.apiKeyValue`, `customJwt.requestBody`, and `httpProxy.password`) are stored in the `uis-v2-node-gateway` Secret, so the pod specification shows only the Secret name.
- If your nodes are reachable only through an outbound proxy, set `nodeGateway.httpProxy` (`url`, and optionally `username`, `password`, and `noProxy`). The gateway doesn't send `customJwt` token requests through the proxy, so the token server must be reachable directly.
- The gateway runs at least two replicas (`nodeGateway.replicas`), and a PodDisruptionBudget keeps one gateway pod running during node drains.
- To allow only the UIS v2 pods of the release to call the gateway, set `nodeGateway.networkPolicy.enabled` to `true`. This setting takes effect only if your cluster's network plugin enforces NetworkPolicy.