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 the read models used by DALP APIs, dashboards, reports, and operational review.
It connects two facts that can differ during normal operation. The transaction may already exist on the EVM chain while DALP has not yet processed the events from that block.
This architecture explanation describes indexed-state production and catch-up. It also states the consistency guarantees operators should expect. The page 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. Restarted indexers 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 when network configuration allows that signal. | 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 the safer point 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. |
How reads become visible
Indexed state is current to the indexer's processed checkpoint.
A transaction can be mined on-chain before it appears in DALP read surfaces. Indexed visibility can lag while the indexer catches up, drains contract backfill, or builds a reindex deployment.
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 supported events and writes the DALP read model.
- Pending backfill work drains newly discovered contract history before listeners are told that a block height is ready.
- APIs, dashboards, and reports read the indexed model.
- Monitoring shows whether the indexer is caught up, lagging, backfilling, or recovering.
That distinction matters for support and operations. If a transaction is visible in an explorer but missing from a DALP dashboard, check whether the processed checkpoint has reached the transaction block, whether the relevant contract is registered for indexing, and whether backfill work is still pending for that contract.
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. Those checks 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.
Before requesting a reindex
A reindex is a controlled rebuild of indexed read models. It is not the first response to every missing dashboard row.
Check the live signals first:
- Confirm the transaction succeeded on the EVM network and emitted an event that DALP supports.
- Check whether the indexer's processed checkpoint has reached that transaction block.
- Check whether the contract is registered for indexing and whether pending or backfilling work remains.
- Check RPC health and chain-head freshness when checkpoints stop moving.
- Request reindexing only when the current read model needs to be rebuilt, not when the indexer is simply behind and still catching up.
The reindex endpoint accepts a chain ID and acknowledges that the request was accepted. A conflict means another reindex is already in progress. Operators should keep watching deployment state, pending backfill, and block lag until the rebuilt schema becomes the served read model.
What the indexer covers
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 responsibilities
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.
Overview
Architecture-level map for operating DALP deployments: telemetry, PostgreSQL persistence, workflow durability, high availability handoffs, and failure behavior.