Chain Indexer
The Chain Indexer reads EVM logs, decodes DALP events, and writes queryable read models. It explains how checkpoints, finality, reorg handling, and reindexing affect the state shown by APIs and dashboards.
The Chain Indexer turns supported EVM events into read models for DALP APIs, dashboards, reports, and operational review.
It reads chain logs, decodes them with known contract ABIs, routes each event to a domain handler, and stores the resulting state in PostgreSQL.
This page is an architecture explanation. It describes how indexed state is produced and what consistency boundary readers should expect.
It does not document a public API contract or replace deployment-specific monitoring runbooks.
Indexing flow
What the indexer owns
| Area | Current behaviour | Consistency effect |
|---|---|---|
| Chain progress | A live watcher checks the chain head and calls the sync path when the head advances. WebSocket block subscriptions can trigger the same sync path, with polling as the steady fallback. | API and UI reads follow the latest processed checkpoint, not the raw chain head. |
| Contract discovery | Genesis and event handlers register known DALP contracts in PostgreSQL. Forward range processing is single-pass; newly discovered contracts are queued for backfill and cascade work. | Events from newly created DALP contracts can appear after follow-up backfill work, even when the parent block range has already advanced. |
| Event ordering | The log fetch path address-filters eth_getLogs, chunks block ranges, decodes ABI events, and sorts results by block number and log index before handlers run. | Replaying the same block range produces the same handler order. |
| Checkpointing | The sync path stores per-chain progress in PostgreSQL after processing ranges. It can resume from the stored checkpoint after downtime. | Reads can lag during catch-up, then converge as checkpoints advance. |
| Finality tracking | The watcher maintains a finalized-block watermark. PoS chains can use the RPC finalized tag. Private or test chains use configured confirmation depth where the network configuration allows it. | Pruning and reorg cleanup are tied to the finalized watermark rather than only to the latest observed head. |
| Reorg recovery | The sync path checks stored block hashes for reorganisations, rolls back affected indexed state, and reprocesses the canonical chain. | Recent indexed data can be corrected when the chain reorganises. Finalized data is treated as the safer boundary for cleanup. |
| Reindexing | A new indexer deployment schema can be built while the old schema continues serving reads. When the new deployment catches up across chains, public views can swap to the new schema. | Long reindex work does not need to remove the currently served read model while the replacement is being built. |
Read-model consistency boundary
Indexed state is current to the indexer's processed checkpoint.
A transaction can be mined on-chain before it appears in DALP read surfaces. This can happen when the indexer has not processed that block yet, when the service is catching up after downtime, or when a reindex deployment is still building.
Applications should treat on-chain transaction finality and indexed read visibility as related but separate facts:
- The EVM transaction decides whether the on-chain operation succeeded.
- The indexer observes the emitted events and writes the DALP read model.
- APIs, dashboards, and reports read the indexed model.
- Monitoring shows whether the indexer is caught up, lagging, backfilling, or recovering.
That boundary matters for support and operations. If a transaction is visible in an explorer but missing from a DALP dashboard, the first question is whether the indexer checkpoint has reached the transaction block and whether the relevant contract was registered for indexing.
Failure and recovery model
| Condition | What happens | Operator check |
|---|---|---|
| Indexer downtime | The service resumes from the stored checkpoint and processes missed ranges. | Check the per-chain processed block and block lag. |
| RPC interruption | The watcher keeps its loop alive and retries on later ticks. Finality advancement can pause when the configured finality signal is unavailable. | Check RPC health, latest chain head, finality lag, and indexer errors. |
| Newly discovered contract | The discovered contract is registered, then queued for backfill and cascade processing. | Check contract registration and whether backfill work remains for that contract. |
| Chain reorganisation | The indexer rolls back affected rows within the supported reorg window and reprocesses canonical blocks. | Check reorg metrics and whether the finalized watermark has advanced. |
| Reindex requested | A building deployment schema is created. The serving schema continues to back current reads until the replacement is ready to swap. | Check deployment registry state and pending backfill progress. |
Monitoring and troubleshooting signals
Use Blockchain monitoring for live chain and indexer health. The most useful signals are block lag, block age, finality lag, sync failures, handler errors, pending backfill state, and reindex deployment state.
Use the indexer troubleshooting checks before starting a reindex. They help operators distinguish normal read-model lag from RPC failure, missing contract discovery, reorg recovery, or active reindex work.
Use Observability for deployment-level metrics, logs, and traces when the observability chart is enabled. Observability helps explain why the indexer is lagging; the indexed database and blockchain monitoring surfaces show what state DALP is currently serving.
Boundaries
The Chain Indexer does not change EVM finality, provide an external proof of reserve, or guarantee an RPC provider's availability.
It turns supported chain events into DALP read models. Operators use those models and related signals to understand freshness, lag, reorg recovery, and reindex progress.
The indexer does not index arbitrary contracts by default. DALP handlers process known contract types and events registered through the platform's discovery and handler registry.
External bridges, non-EVM networks, custody-provider records, and off-chain reserve evidence need their own integration or evidence source.
See also
- Blockchain monitoring for operational health checks
- Observability for deployment telemetry
- Database for storage architecture
- Contract Runtime for contract calls and event decoding boundaries
Overview
How DALP turns EVM events into queryable platform state, where indexed reads can lag on-chain finality, and which monitoring pages operators use during indexing incidents.
Security overview
DALP security separates identity, access, wallet verification, on-chain compliance, and custody controls so reviewers can see which gate owns each asset-operation decision.