# 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 you begin:** Familiarize yourself with the UIS architecture, components, and data flow by reading the [Unified Indexer Service](/products/custody/v1.36/overview/architecture/unified-indexer-service) architecture documentation. ## Prerequisites Before starting the migration, ensure you understand the following: ### Understanding the architecture 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](/products/custody/v1.36/overview/architecture/unified-indexer-service#architecture) and [Components](/products/custody/v1.36/overview/architecture/unified-indexer-service#components) sections. ### Node requirements Ensure your blockchain nodes meet the required specifications before migration. See the [On-premises node requirements](/products/custody/v1.36/overview/architecture/unified-indexer-service#on-premises-node-requirements) section for detailed node version and configuration requirements for each supported blockchain. ### Database readiness 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 ## Installation and configuration This guide assumes the use of helm-next for deployment to your Kubernetes cluster. ### Step 1: Update and deploy UIS components 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). ### Step 2: Configuration This section explains what needs to be changed in your helm-next configuration to migrate from local indexers to UIS. #### What to disable (legacy local indexers) 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 Do not remove old indexer configuration before migration is complete. The system needs access to the last indexed block number from the old indexer to ensure data continuity. #### What to enable (UIS components) For on-premises deployments, UIS is automatically enabled for certain chains upon upgrade to v1.26: **Automatically migrated to UIS (no configuration required):** | Chain | Status | | --- | --- | | Solana | Will automatically use UIS | | XRPL | Will automatically use UIS | | TRON | Will be added to UIS (new chain, not a migration) | **Must be explicitly configured to use UIS:** | Chain | Status | | --- | --- | | Arbitrum | Required to use UIS (will not work without it) | | Base | Required to use UIS (will not work without it) | | Optimism | Required to use UIS (will not work without it) | | Ethereum | Optional (can continue using legacy indexer or migrate to UIS) | | Polygon | Optional (can continue using legacy indexer or migrate to UIS) | | Stellar | Optional (can continue using legacy indexer or migrate to UIS) | #### Example helm-next configuration To enable UIS for a specific chain, set the `type` parameter to `"uis"` in that network's configuration block: ```yaml 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. Migration is one-way. Once a chain is migrated to UIS, it cannot be rolled back to the legacy indexer. Plan your migration carefully. For more configuration examples and details, see the [Configuration](/products/custody/v1.36/overview/architecture/unified-indexer-service#configuration) section in the UIS architecture documentation. ## Automated migration process 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. ### How migration works 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 ### Monitoring the migration process 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. This is not an error - the Processor is designed to wait for tracking to begin before it can process events. ## Validation and decommissioning Once the logs confirm the migration is complete and the system is in the Ready state, perform the final validation before cleaning up. ### Final validation 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 ### Decommission of old indexers 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 The old indexer disposal is not automated. You must manually remove the old indexer configuration and pods after confirming successful migration. ## Frequently Asked Questions (FAQ) ### Which chains are migrated to UIS? When you upgrade to v1.26: | Chain | Migration Status | | --- | --- | | Solana | Automatically migrated to UIS | | XRPL | Automatically migrated to UIS | | TRON | Added to UIS (new chain, not a migration) | **Other chains:** | Chain | Status | | --- | --- | | Arbitrum, Base, Optimism | Only available with UIS (no legacy indexer support) | | Ethereum, Polygon, Stellar | Can use either UIS or legacy indexer (requires explicit configuration) | ### Do I need all UIS components? Yes. All installed UIS components are required for proper operation: | Component | Requirement | | --- | --- | | Generic Indexer | Required for data fetching | | Processor | Required for event generation | | Events API | Required for Ledger Accounting to consume events | | Ledger Adapters | Required for chain-specific data translation | | Ledger APIs | Required for accessing indexed data | Removing any component will cause system failures. ### Which version of v1.26 includes UIS support? UIS is available from **v1.26.0**. ### What if the Processor keeps crash looping? 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. ### Can I roll back to the old indexer after migration? 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. ### How do I know if migration is complete? 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 ### What happens to the old indexer data? 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. ## Related documentation - [Unified Indexer Service Architecture](/products/custody/v1.36/overview/architecture/unified-indexer-service) - Detailed architecture, components, and configuration reference - [Supported blockchain ledgers](/products/custody/v1.36/reference/supported-ledgers) - Complete list of supported blockchains ## Support For additional assistance with UIS migration, please contact your Customer Platform Engineering (CPE) team or Ripple Support.