AGENTS.md

1# Agent Guidelines for Blockscout
2 
3## Separate API / Indexer Mode Architecture
4 
5Blockscout supports running as a single combined application or as separate API and indexer instances via the `APPLICATION_MODE` environment variable.
6 
7### Mode Configuration
8 
9`APPLICATION_MODE` environment variable (defined in `config/config_helper.exs`):
10- `all` (default) — both API and indexer run together
11- `api` — API-only instance, no indexing
12- `indexer` — indexer-only instance, no API serving
13 
14The current mode is accessible via `Explorer.mode()` (defined in `apps/explorer/lib/explorer.ex`), which returns `:all`, `:api`, `:indexer`, or `:media_worker`.
15 
16`:media_worker` is a special standalone mode for NFT media processing. It is not set via `APPLICATION_MODE` — it activates when `nft_media_handler[:standalone_media_worker?]` is true, overriding the configured mode. In this mode, `Explorer.Application` starts only libcluster — no base_children or configurable_children. The process mode filtering rules below do not apply to `:media_worker`.
17 
18Related environment variables:
19- `DISABLE_INDEXER` — forces indexer off (auto-set when `APPLICATION_MODE=api`)
20- `DISABLE_API` — forces API off (compile-time, controls `BlockScoutWeb.Endpoint`)
21 
22### Rules for Assigning Processes to Modes
23 
24When adding or modifying processes started by `Explorer.Application`, `Indexer.Application`, or `BlockScoutWeb.Application`, follow these rules:
25 
26**Start in `:indexer` mode only:**
27- Active periodic updaters — GenServers that periodically query the DB and write results to `last_fetched_counters` table (e.g., `ContractsCount`, `NewPendingTransactionsCount`, `Transactions24hCount`). The API side reads directly from the DB table without needing a local process.
28- Data migrators (`Explorer.Migrator.*`) — one-time or ongoing data transformations.
29- Catalogers and tag importers (`AddressTag.Cataloger`, `CertifiedSmartContractCataloger`).
30- Block gap scanning (`MinMissingBlockNumber`).
31- Indexer-specific caches that are written and read by indexer only (`LatestL1BlockNumber`).
32 
33**Start in `:api` mode only:**
34- Passive on-demand ETS/in-memory caches — GenServers that manage an ETS table and populate it on API request (e.g., `AddressTransactionsCount`, `TokenHoldersCount`, `BlockBurntFeeCount`, `AverageBlockTime`). ETS is local to the process, so these must run on the instance serving requests.
35- On-demand fetchers triggered by API requests (`CheckBytecodeMatchingOnDemand`, `FetchValidatorInfoOnDemand`, `LookUpSmartContractSourcesOnDemand`).
36- API access control (`AddressesBlacklist`).
37- Contract verification tooling (`SolcDownloader`, `VyperDownloader`).
38- Read-only DB replicas (`Explorer.Repo.Replica1`).
39- API-only caches (`OptimismFinalizationPeriod`, `CeloEpochs`, `Rootstock.LockedBTCCount`).
40 
41**Start in both modes (`:all`, `:api`, `:indexer`):**
42- Core infrastructure: main `Explorer.Repo`, `Explorer.Vault`, `Registry.ChainEvents`, `Redix`.
43- Event system: `Explorer.Chain.Events.Listener` (mode-controlled via its own `:enabled` config).
44- Cluster discovery (`libcluster`) — needed for node communication in separate mode.
45 
46### Helper Functions in Explorer.Application
47 
48- `configure(process)` — starts if `Application.get_env(:explorer, process)[:enabled] == true`. No mode check.
49- `configure_mode_dependent_process(process, mode)` — starts if `:enabled` is true AND `Explorer.mode()` matches. Use for processes that have `:enabled` config in `runtime.exs`.
50- `only_in_mode(process, mode)` — starts if `Explorer.mode()` matches. No `:enabled` check. Use for processes without `:enabled` config (e.g., repos, downloaders, unconditional entries).
51- `configure_chain_type_dependent_process(process, chain_type)` — starts if chain type matches. Can be piped with mode filters.
52 
53Piping pattern for combined restrictions:
54```elixir
55SomeProcess
56|> configure_mode_dependent_process(:indexer)
57|> configure_chain_type_dependent_process(:optimism)
58```
59 
60### Cache Pattern Reference
61 
62How to distinguish active updaters from passive caches when deciding the mode:
63- **Active periodic updater**: has `schedule_next_consolidation()`, `handle_info(:consolidate)`, writes to `last_fetched_counters` via `LastFetchedCounter.upsert()` -> `:indexer`
64- **Passive on-demand ETS cache**: has `fetch()` with cache expiry check, stores in ETS via `Helper.put_into_ets_cache()`, may update model columns -> `:api`
65- **MapCache (ConCache)**: uses `use Explorer.Chain.MapCache`, implements `handle_fallback` -> `:api`
66