We continue to add new features and functionality to OpenScan.AI and recommend updating your instance with each new release. OpenScan.AI tracks upstream Blockscout releases — check the release notes for your target version before upgrading.
Warning: If it has been a while since your last upgrade, we recommend performing incremental upgrades to ensure proper performance. For example, if you are running backend v6.9.0, first upgrade to v6.10.0 prior to upgrading to the latest 7.0 version. This reduces downtime and ensures all breaking changes are handled. Update to v7.0 before updating to v8.0, following the same process below and replacing v7 with the latest frontend and backend releases.
Getting Started
This guide walks through the process of updating to backend v7.0.2 and frontend v1.38.0 (March 2025) from v6.10.X. If you have questions about a different upgrade, reach out via the contact form. Breaking changes follow the instructions.
1) Update backend ENV variables
Warning: Backend variable renaming only applies to the 6.10.X → 7.0.X update. If you are performing a more extensive update, please check renaming & deprecations from the release notes of every minor release (6.8.0, 6.9.0 etc.) within your update range.
Newly renamed variables include the MIGRATION prefix. If a variable contained MIGRATION in the name previously, it has been moved to the beginning of the variable. All variables you need to rename:
| Old name | New name |
|---|---|
| TOKEN_ID_MIGRATION_FIRST_BLOCK | MIGRATION_TOKEN_ID_FIRST_BLOCK |
| TOKEN_ID_MIGRATION_CONCURRENCY | MIGRATION_TOKEN_ID_CONCURRENCY |
| TOKEN_ID_MIGRATION_BATCH_SIZE | MIGRATION_TOKEN_ID_BATCH_SIZE |
| SHRINK_INTERNAL_TRANSACTIONS_BATCH_SIZE | MIGRATION_SHRINK_INTERNAL_TRANSACTIONS_BATCH_SIZE |
| SHRINK_INTERNAL_TRANSACTIONS_CONCURRENCY | MIGRATION_SHRINK_INTERNAL_TRANSACTIONS_CONCURRENCY |
| TOKEN_INSTANCE_OWNER_MIGRATION_CONCURRENCY | MIGRATION_TOKEN_INSTANCE_OWNER_CONCURRENCY |
| TOKEN_INSTANCE_OWNER_MIGRATION_BATCH_SIZE | MIGRATION_TOKEN_INSTANCE_OWNER_BATCH_SIZE |
| TOKEN_INSTANCE_OWNER_MIGRATION_ENABLED | MIGRATION_TOKEN_INSTANCE_OWNER_ENABLED |
| DENORMALIZATION_MIGRATION_BATCH_SIZE | MIGRATION_DENORMALIZATION_BATCH_SIZE |
| DENORMALIZATION_MIGRATION_CONCURRENCY | MIGRATION_DENORMALIZATION_CONCURRENCY |
| TOKEN_TRANSFER_TOKEN_TYPE_MIGRATION_BATCH_SIZE | MIGRATION_TOKEN_TRANSFER_TOKEN_TYPE_BATCH_SIZE |
| TOKEN_TRANSFER_TOKEN_TYPE_MIGRATION_CONCURRENCY | MIGRATION_TOKEN_TRANSFER_TOKEN_TYPE_CONCURRENCY |
| SANITIZE_INCORRECT_NFT_BATCH_SIZE | MIGRATION_SANITIZE_INCORRECT_NFT_BATCH_SIZE |
| SANITIZE_INCORRECT_NFT_CONCURRENCY | MIGRATION_SANITIZE_INCORRECT_NFT_CONCURRENCY |
| SANITIZE_INCORRECT_NFT_TIMEOUT | MIGRATION_SANITIZE_INCORRECT_NFT_TIMEOUT |
| SANITIZE_INCORRECT_WETH_BATCH_SIZE | MIGRATION_SANITIZE_INCORRECT_WETH_BATCH_SIZE |
| SANITIZE_INCORRECT_WETH_CONCURRENCY | MIGRATION_SANITIZE_INCORRECT_WETH_CONCURRENCY |
| SANITIZE_INCORRECT_WETH_TIMEOUT | MIGRATION_SANITIZE_INCORRECT_WETH_TIMEOUT |
| REINDEX_INTERNAL_TRANSACTIONS_STATUS_BATCH_SIZE | MIGRATION_REINDEX_INTERNAL_TRANSACTIONS_STATUS_BATCH_SIZE |
| REINDEX_INTERNAL_TRANSACTIONS_STATUS_CONCURRENCY | MIGRATION_REINDEX_INTERNAL_TRANSACTIONS_STATUS_CONCURRENCY |
| REINDEX_INTERNAL_TRANSACTIONS_STATUS_TIMEOUT | MIGRATION_REINDEX_INTERNAL_TRANSACTIONS_STATUS_TIMEOUT |
| FILECOIN_PENDING_ADDRESS_OPERATIONS_MIGRATION_BATCH_SIZE | MIGRATION_FILECOIN_PENDING_ADDRESS_OPERATIONS_BATCH_SIZE |
| FILECOIN_PENDING_ADDRESS_OPERATIONS_MIGRATION_CONCURRENCY | MIGRATION_FILECOIN_PENDING_ADDRESS_OPERATIONS_CONCURRENCY |
| ARBITRUM_DA_RECORDS_NORMALIZATION_MIGRATION_BATCH_SIZE | MIGRATION_ARBITRUM_DA_RECORDS_NORMALIZATION_BATCH_SIZE |
| ARBITRUM_DA_RECORDS_NORMALIZATION_MIGRATION_CONCURRENCY | MIGRATION_ARBITRUM_DA_RECORDS_NORMALIZATION_CONCURRENCY |
2) Install the backend
Install the target backend release (for example 7.0.2) from the published Docker images or build from source via the OpenScanAI GitHub repositories.
3) Install the frontend
Install the matching frontend release (for example v1.38.0). Frontend variable updates:
| From | To | Example |
|---|---|---|
| NEXT_PUBLIC_ROLLUP_L1_BASE_URL, NEXT_PUBLIC_ROLLUP_PARENT_CHAIN_NAME | NEXT_PUBLIC_ROLLUP_PARENT_CHAIN | Current: NEXT_PUBLIC_ROLLUP_L1_BASE_URL=<L1-url>, NEXT_PUBLIC_ROLLUP_PARENT_CHAIN_NAME=<chain-name> → New: NEXT_PUBLIC_ROLLUP_PARENT_CHAIN={'name':'<chain-name>','baseUrl':'<L1-url>'} |
| NEXT_PUBLIC_RE_CAPTCHA_V3_APP_SITE_KEY | NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY | |
| NEXT_PUBLIC_HOMEPAGE_PLATE_TEXT_COLOR, NEXT_PUBLIC_HOMEPAGE_PLATE_BACKGROUND | NEXT_PUBLIC_HOMEPAGE_HERO_BANNER_CONFIG | Current: NEXT_PUBLIC_HOMEPAGE_PLATE_BACKGROUND=<my-background>, NEXT_PUBLIC_HOMEPAGE_PLATE_TEXT_COLOR=<my-text-color> → New: NEXT_PUBLIC_HOMEPAGE_HERO_BANNER_CONFIG={'background':['<my-background>'],'text_color':['<my-text-color>']} |
Deprecated frontend variables
| Deprecated |
|---|
| NEXT_PUBLIC_AUTH0_CLIENT_ID |
| NEXT_PUBLIC_AUTH_URL |
| NEXT_PUBLIC_LOGOUT_URL |
| FAVICON_GENERATOR_API_KEY |
| NEXT_PUBLIC_SENTRY_DSN |
| SENTRY_CSP_REPORT_URI |
| NEXT_PUBLIC_SENTRY_ENABLE_TRACING |
4) Install microservices
Install the matching stats microservice release, and use the latest tag for any other microservices used with your instance. See the OpenScanAI GitHub organization for the microservice repositories.
Breaking Changes
Warning:
/api/v1/health,/api/v1/health/liveness,/api/v1/health/readinesshave been removed in favor of/api/health/**endpoints.
Warning:
/api/v2/addresses/:address_hashreturns 200 instead of 404 for valid hashes which are not in the DB.
Warning:
/api/v2/tokens/:token_hash/instancesowner’sens_domain_nameproperty now preloads the ENS domain name.
Warning: Transaction hash and address hash are no longer mandatory in the
txlistinternalAPI v1 endpoint.
Warning: The
/metricsendpoint is available on the indexer pod (previously it existed only on the API pod).