README
¶
ethindexer
ethindexer is a lightweight Go library for indexing Ethereum logs.
It handles backfilling, live indexing, checkpointing, reorg recovery, and resumable restarts so handlers only need to implement application-specific indexing logic.
Install
go get github.com/LeTamanoir/ethindexer
Usage
See examples/weth for a complete example.
How it works
Sync restores the latest finalized checkpoint, backfills to the node's current finalized block, and saves a new finalized checkpoint.
Process ingests new heads after Sync returns. Each header is checked against the current head. If a gap is detected, the indexer fills it. If a parent hash mismatch is detected, the indexer restores the finalized checkpoint and replays the canonical chain.
Start block Finalized block Staged Latest
| | | |
S --------[...]----------- F ------------------- S --------- L
<- FinalityDepth ->
The indexer keeps two checkpoints:
- Finalized (
F): durable restart point. - Staged (
S): pending checkpoint promoted once it is old enough.
This lets the indexer resume quickly while avoiding committing state that may still be affected by reorgs.
Development
just check
go test ./...
License
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BlobStore ¶
type BlobStore interface {
// Read returns the data stored under key. A missing key returns (nil, nil).
Read(ctx context.Context, key string) ([]byte, error)
// Write stores data under key, replacing any existing value.
Write(ctx context.Context, key string, blob []byte) error
// Move atomically transfers data from srcKey to dstKey, replacing any
// existing value under dstKey.
Move(ctx context.Context, srcKey, dstKey string) error
}
BlobStore provides keyed byte storage.
type ChainReader ¶
type ChainReader interface {
FilterLogs(context.Context, ethereum.FilterQuery) ([]types.Log, error)
HeaderByNumber(context.Context, *big.Int) (*types.Header, error)
}
ChainReader provides access to Ethereum logs and block headers.
type Config ¶
type Config struct {
// MaxBlockRange is the maximum block span per backfill request.
MaxBlockRange uint64
// FinalityDepth is the block depth considered finalized.
FinalityDepth uint64
// CheckpointInterval is the minimum number of blocks between staged checkpoints.
CheckpointInterval uint64
// MaxConcurrency bounds concurrent header fetches.
MaxConcurrency int
}
Config holds the indexer's tunables.
type FileStore ¶
type FileStore struct {
// contains filtered or unexported fields
}
FileStore implements BlobStore using files in a directory.
func NewFileStore ¶
NewFileStore creates a FileStore rooted at dir.
type Filter ¶
type Filter struct {
// FromBlock is the first block to index.
FromBlock uint64
// Addresses restrict logs to the given contract addresses.
// See [ethereum.FilterQuery.Addresses].
Addresses []common.Address
// Topics restrict logs by indexed event topics.
// See [ethereum.FilterQuery.Topics].
Topics [][]common.Hash
}
Filter specifies which logs the indexer fetches.
type Handler ¶
type Handler interface {
// Filter specifies which logs the indexer fetches.
Filter() Filter
// Snapshot returns the current handler state.
Snapshot(context.Context) ([]byte, error)
// Restore restores a previously captured state.
Restore(context.Context, []byte) error
// Process applies matching logs in block order.
Process(context.Context, []types.Log) error
}
Handler defines the application-specific indexing logic.
type Indexer ¶
type Indexer struct {
// contains filtered or unexported fields
}
Indexer indexes Ethereum logs from a finalized block onward, handling reorgs and checkpointing.
func OpenContext ¶
OpenContext returns an Indexer synced to the finalized head.
type Options ¶
type Options struct {
// Client provides access to Ethereum logs and block headers.
Client ChainReader
// Handler receives logs and owns the indexed state.
Handler Handler
// Store persists checkpoints and cached log batches.
Store BlobStore
// LogFunc receives indexer log events.
LogFunc func(msg string, args ...any)
Config Config
}
Options configures an Indexer.
Source Files