Skip to main content

Overview

The Shinzo IndexerIndexer A client that reads blockchain data (blocks, transactions, logs), parses it, and writes normalized documents into defraDB. is a high-performance, fault-tolerant blockchain indexingIndexing The process of parsing blockchain data and storing structured, schema-compliant documents in defraDB. engine designed for deterministic, query-friendly extraction of Ethereum data. It sits between an Ethereum execution node and downstream applications, transforming raw chain data into structured, relationally linked documents stored in DefraDBdefraDB A NoSQL, document-oriented, edge-first database used by Shinzo to store encrypted or schema-defined data., all while maintaining strong guarantees around consistency, concurrency, and observability.

Purpose and Role in the Stack​

At its core, the indexerIndexer A client that reads blockchain data (blocks, transactions, logs), parses it, and writes normalized documents into defraDB. continuously consumes blocks, transactions, logs, and EIP-2930 access lists from an Ethereum node and normalizes them into a strongly-typed data model. It exposes this indexed data through Peer-2-Peer Network powered by DefraDBdefraDB A NoSQL, document-oriented, edge-first database used by Shinzo to store encrypted or schema-defined data., enabling downstream services to query block-level and transaction-level information without depending directly on JSON-RPC. This separates data access from blockchain node operations, enabling stateless microservices, cheaper infra, and deterministic historical queries.

Architecture Overview​

1. IndexerIndexer A client that reads blockchain data (blocks, transactions, logs), parses it, and writes normalized documents into defraDB. Engine (Go)​

The core indexingIndexing The process of parsing blockchain data and storing structured, schema-compliant documents in defraDB. engine is written in Go and handles concurrent block processing. It connects to managed blockchain nodes via dual WebSocket/HTTP connections and ensures deterministic document IDs, duplicate block protection, and graceful shutdown handling.

2. Current Supported Chains​

Supports connections to Ethereum Mainnet currently through a Geth client using JSON-RPC and WebSocket endpoints. Handles network-level errors with retries and timeouts.

3. DefraDBdefraDB A NoSQL, document-oriented, edge-first database used by Shinzo to store encrypted or schema-defined data.​

Acts as the primary persistence layer, providing a P2P-ready, decentralized document store with GraphQLGraphQL A query language and runtime used for retrieving structured data from defraDB, collections, and views within Shinzo. query capabilities. The indexerIndexer A client that reads blockchain data (blocks, transactions, logs), parses it, and writes normalized documents into defraDB. uses it to store:

  • Blocks
  • Transactions
  • Logs
  • AccessListEntries
  • Relationships between blockchain entities

DefraDBdefraDB A NoSQL, document-oriented, edge-first database used by Shinzo to store encrypted or schema-defined data. provides queryable, P2P-ready storage, which aligns with Shinzo Network’s distributed architecture goals.

4. GraphQLGraphQL A query language and runtime used for retrieving structured data from defraDB, collections, and views within Shinzo. API​

DefraDBdefraDB A NoSQL, document-oriented, edge-first database used by Shinzo to store encrypted or schema-defined data. exposes all indexed blockchain data via GraphQLGraphQL A query language and runtime used for retrieving structured data from defraDB, collections, and views within Shinzo., enabling typed queries for both real-time and historical blockchain data.

5. Logging & Error System​

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

6. Configuration Layer (Viper)​

YAML-based configuration with environment variable overrides for:

  • Ethereum node endpoints
  • DefraDBdefraDB A NoSQL, document-oriented, edge-first database used by Shinzo to store encrypted or schema-defined data. settings (P2P, keyring, embedded/remote)
  • IndexerIndexer A client that reads blockchain data (blocks, transactions, logs), parses it, and writes normalized documents into defraDB. start height
  • Logger configuration

In summary, the Shinzo IndexerIndexer A client that reads blockchain data (blocks, transactions, logs), parses it, and writes normalized documents into defraDB. serves as a reliable bridge between Ethereum nodes and applications, providing structured, queryable blockchain data. Its design emphasizes concurrency, error handling, and observability, enabling developers to interact with consistent and deterministic data while keeping application logic decoupled from node operations.