Unified Indexer Service (UIS) on-premises migration guide (v1.26 LTS)

This guide provides the required steps to install and migrate from an existing local indexer deployment to the on-premises version of the Unified Indexer Service (UIS).

The UIS is available from v1.26 LTS and uses a decomposed, component-based architecture. For on-premises deployments, the migration process is fully automated by the Ledger Accounting (LA) component, which orchestrates the transition in the background.

Before starting the migration, ensure you understand the following:

The UIS uses a modern, component-based architecture with several key components:

• Generic Indexer - Orchestrates data fetching for each ledger/network
• Processor - Generates standardized events from indexed data
• Ledger Adapters - Chain-specific translation layers
• Ledger APIs - Provide access to live blockchain data
• Events API - Primary interface for consuming indexed data

For detailed information about data flow and each component, see the UIS architecture and Components sections.

Ensure your blockchain nodes meet the required specifications before migration. See the On-premises node requirements section for detailed node version and configuration requirements for each supported blockchain.

The UIS architecture requires more database connections than the legacy monolithic indexer due to its component-based design.

Actions:

1. Increase connection limit: Increase max_connections in PostgreSQL to accommodate UIS components. Monitor your actual connection usage during deployment to determine the appropriate limit for your environment.
2. Monitor connection pool: Watch connection pool usage during migration
3. Verify resources: Ensure database has sufficient CPU, memory, and IOPS

This guide assumes the use of helm-next for deployment to your Kubernetes cluster.

The new UIS architecture introduces several components (Generic Indexer, Processor, Ledger Adapters) that run as isolated containers.

Actions:

1. Download new charts: Download the latest helm-next charts for v1.26.3 or later.
2. Update configuration: Modify your values.yaml file to enable UIS for the desired chains (see Step 2 below for details and examples).

This section explains what needs to be changed in your helm-next configuration to migrate from local indexers to UIS.

When migrating to UIS, you do NOT need to manually disable the old local indexers. The migration process handles this automatically:

• The Ledger Accounting component will automatically stop using the old indexer once UIS is available

• The old indexer pods will continue running but will not be actively used

• You can manually remove the old indexer configuration after confirming successful migration

For on-premises deployments, UIS is automatically enabled for certain chains upon upgrade to v1.26:

Automatically migrated to UIS (no configuration required):

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:

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: "http://your-optimism-sepolia-node-url"

For XRPL and Solana, no additional configuration is required - they will automatically use UIS when you upgrade to v1.26.

For more configuration examples and details, see the Configuration section in the UIS architecture documentation.

Once the new UIS components are deployed, the Ledger Accounting (LA) component automatically handles the migration logic during its startup sequence. You do not need to manually trigger the migration - it happens automatically.

The migration process is fully automated:

1. Detection: When Ledger Accounting starts, it detects that UIS is available for certain chains (Solana, XRPL, TRON)
2. Data continuity: The system reads the last indexed block number from the old indexer
3. Handoff: UIS begins indexing from that block number to ensure no data gaps
4. Automatic switch: Ledger Accounting automatically starts consuming events from UIS instead of the old indexer

Actions:

• Ensure your Ledger Accounting configuration is updated to point to the new UIS service endpoint (this is typically handled automatically by the helm chart)
• The Ledger Accounting service will flag that a migration is needed for any ledger that uses UIS

The migration process happens very quickly and is largely automated. The Ledger Accounting component performs the following steps:

Migration process:

1. Database check - Ledger Accounting checks for existing database
2. Deployment type check - Verifies if running on-premises
3. Last block retrieval - Ledger Accounting sends API call to Events API to get the last indexed block number
4. Event consumption - When complete, Ledger Accounting makes API calls to /uis/ledger/events endpoint to start consuming events

Monitoring:

Due to the speed of the migration process, it's not practical to monitor individual stages in real-time. Instead, check the Ledger Accounting logs for:

• API calls to the Events API endpoint
• Successful event retrieval from UIS
• Any error messages related to UIS connectivity

Expected behavior during migration:

During the initial deployment, you might observe the Processor component restarting or "crash looping" briefly. This is expected behavior while it waits for the first address to be tracked. Once the LA completes the Address Sync stage, the Processor will stabilize and start running normally.

Once the logs confirm the migration is complete and the system is in the Ready state, perform the final validation before cleaning up.

Verify successful migration:

1. Check transaction processing: Verify that new blockchain transactions are appearing in your system and that the Ledger Accounting sequence numbers are incrementing correctly
2. Monitor UIS components: Check the logs of the new UIS components (Generic Indexer, Processor) to ensure there are no connection errors or timeouts.
3. Verify data continuity: Confirm that there are no gaps in indexed blocks between the old indexer and UIS
4. Test operations: Perform test transactions on the migrated chains to ensure end-to-end functionality

The legacy local indexer is now redundant. However, do not remove it immediately:

1. Wait for confirmation: Keep the old indexer running for at least 24-48 hours after migration to ensure stability

2. Verify configuration: Confirm that Ledger Accounting configuration points to UIS. Note: Indexer selection is based on configuration only - there is no automatic fallback mechanism, so Ledger Accounting will always use the configured indexer.

3. Safe removal: Once confirmed, you can safely stop or uninstall the legacy indexer deployment

4. Clean up resources: Remove any associated resources (deployment configs, containers) for the old indexer from your OCP cluster

When you upgrade to v1.26:

Other chains:

Yes. All installed UIS components are required for proper operation:

Removing any component will cause system failures.

UIS is available from v1.26.0.

This is expected behavior during initial deployment. The Processor will crash loop until the first address is tracked. Once Ledger Accounting syncs addresses to UIS, the Processor will stabilize. If it continues crash looping after address sync is complete, check the Processor logs for errors.

No. Migration to UIS is a one-way process and cannot be rolled back. Plan your migration carefully and test in a non-production environment first if possible.

Monitor the Ledger Accounting logs for migration completion messages. You should see confirmation that:

• Address sync is complete
• Block handover is successful
• UIS is actively indexing new blocks
• Ledger Accounting is consuming events from UIS

The old indexer data remains in the database. UIS will start indexing from the last block indexed by the old indexer to ensure data continuity. The old indexer pods can be removed after confirming successful migration.

• Unified Indexer Service Architecture - Detailed architecture, components, and configuration reference
• Supported blockchain ledgers - Complete list of supported blockchains

For additional assistance with UIS migration, please contact your Customer Platform Engineering (CPE) team or Ripple Support.