Skip to main content

Overview

The Shinzo IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. is a lightweight sidecar that runs alongside an existing Ethereum execution client and reads from it. It pulls block dataBlock Data Raw blockchain data: blocks, transactions, and logs. The indexer fetches this from source chains such as Ethereum and structures it into defraDB documents. out of the node and writes it into a local DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. in a shape that is easy to query.

The IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. is not an RPC node. It does not replace GethGeth Go-Ethereum, the Go implementation of an Ethereum node. Each indexer runs alongside a Geth node and connects over WebSocket (port 8546) and JSON-RPC (port 8545) to fetch block data., Reth, Nethermind, or any other execution client, and it does not serve JSON-RPC traffic to applications. Instead, the IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. consumes upstream RPC and WebSocket endpoints from a node you already have access to: a local execution client, a node co-located with your validatorValidator An entity that participates in a chain's consensus. On Ethereum, a validator's withdrawal key signs an EIP-712 message on the outpost to authorize an operator key as its indexer., or a managed provider. It transforms the raw chain data those endpoints return into structured, relationally linked documents stored in its local DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. instance.

Purpose and role in the stack​

The IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. continuously pulls blocks, transactions, logsLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens., and EIP-2930EIP-2930 An Ethereum standard that adds optional access lists to transactions, pre-declaring which storage slots a transaction will read or write. The indexer stores these as `AccessListEntry` documents. access lists from whichever upstream Ethereum node you point it at, then normalizes them into a strongly-typed data model. It exposes this indexed data through a peer-to-peer network powered by DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p., so downstream services can query block-level and transaction-level information without going through JSON-RPC themselves. The execution client still does the work of being an execution client. The IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. just reads from it and reshapes the data for query.

Architecture overview​

Indexer engine (Go)​

The core indexingIndexing The process of parsing blockchain data and storing it as structured, schema-compliant documents in defraDB. engine is written in Go and handles concurrent block processing. It connects to an upstream Ethereum node over HTTP and WebSocket, and provides deterministic document IDs, duplicate block protection, and graceful shutdown handling. The upstream node is supplied by you. The IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. does not run one.

Currently supported chains​

The IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. currently supports Ethereum Mainnet. It works with any execution client that exposes a standard Ethereum JSON-RPC and WebSocket interface (GethGeth Go-Ethereum, the Go implementation of an Ethereum node. Each indexer runs alongside a Geth node and connects over WebSocket (port 8546) and JSON-RPC (port 8545) to fetch block data., Reth, Nethermind, Erigon, or a managed provider). Network-level errors are handled with retries and timeouts. Supported chains can also be found at shinzo.network/chains.

DefraDB​

DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. is the IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication.'s local persistence layer. It is a peer-to-peer document store with GraphQL query capabilities. The IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. writes the following into its local DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. instance:

  • Blocks.
  • Transactions.
  • LogsLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens..
  • AccessListEntries.
  • Relationships between blockchain entities.

DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. provides the queryable, P2P-ready storage that the rest of the Shinzo Network reads from.

GraphQL API​

DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. exposes the indexed data via GraphQL for typed queries against both real-time and historical data. This is the IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication.'s read interface; it is not an Ethereum JSON-RPC endpoint.

Logging and error system​

  • Uber Zap for structured logging with context (block number, tx hash, etc.).
  • The IndexerError system: typed errors (NetworkError, DataError, StorageError, SystemError) with severity levels, structured context, and retry logic.

Configuration layer (Viper)​

YAML-based configuration with environment variable overrides for:

  • Upstream Ethereum node endpoints (RPC and WebSocket URLs supplied by you).
  • DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. settings (P2P, keyring, embedded/remote).
  • IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. start height.
  • Logger configuration.

The Shinzo IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. is a client that reads from an Ethereum node you already have and writes structured data into a local DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p.. It does not replace your execution client, and it does not expose JSON-RPC. Applications query the normalized data instead of talking to the chain directly.