indexer/LLM.md

Explorer

Overview

Single-binary block explorer. Indexes EVM and multi-chain networks, serves explorer API v2, embeds the frontend. SQLite by default, PQ encrypted streaming backups to S3. No PostgreSQL, no Elixir, no external services.

Package Information

• Module: github.com/luxfi/explorer
• Binary: explorer (NOT lux-explorer)
• Go: 1.26.1
• Image: ghcr.io/luxfi/explorer

Architecture

explorer (single binary)
│
├── Indexer goroutines      Write → SQLite (WAL, sole writer)
├── Base HTTP server        Read → SQLite (RO, 8 conns)
│   ├── /v1/explorer/*      Explorer API v2 REST
│   ├── /v1/explorer/graphql GraphQL
│   ├── /v1/explorer/ws     WebSocket/SSE realtime
│   └── /*                  Embedded Next.js frontend (go:embed)
├── Replicate sidecar       WAL → S3 (age PQ encrypted)
└── ZapDB KV             Fast hash/height lookups

Storage

• SQLite WAL: default, zero-config, concurrent readers
• ZapDB: KV layer for O(1) hash lookups
• PostgreSQL: optional via -tags postgres
• No Redis: ZapDB replaces it

PQ Encrypted Streaming Backups

Every SQLite WAL write is streamed to S3, encrypted with post-quantum cryptography:

• Algorithm: ML-KEM-768 + X25519 hybrid (NIST FIPS 203)
• Library: luxfi/age v1.4.0
• Transport: hanzoai/replicate WAL streaming
• Chunk size: 64KB ChaCha20-Poly1305 AEAD per chunk
• Forward secrecy: fresh ephemeral keys per WAL segment
• Restore: point-in-time to any TXID from S3

SQLite WAL → Replicate → age (ML-KEM-768 ∥ X25519) → S3

Enable: REPLICATE_S3_ENDPOINT + REPLICATE_AGE_RECIPIENT env vars.

Rust Services (Optional)

Pure Go implementations exist for everything. Rust originals available as static library via CGO:

explorer-rs/ffi/ → libexplorer_ffi.a (staticlib)
  ├── smart-contract-verifier  C ABI: explorer_verify_solidity()
  ├── sig-provider             C ABI: explorer_lookup_signature()
  └── memory mgmt              C ABI: explorer_free()

rustffi/verifier.go            Go CGO bindings (build tag: rustffi)

Build without Rust: go build ./cmd/explorer/ (default, pure Go) Build with Rust: CGO_ENABLED=1 go build -tags rustffi ./cmd/explorer/

Directory Structure

cmd/explorer/           Unified binary entry point
cmd/indexer/            Per-chain indexer (legacy)
cmd/evmchains/          Multi-EVM (shared DB)
cmd/multichain/         100+ chain parallel indexer

explorer/               API layer (imports hanzoai/base as library)
  explorer.go           Plugin registration, read-only SQLite conn
  handlers.go           /v1/explorer/* route handlers (30 endpoints)
  format.go             Explorer v2 response formatters
  collections.go        User data: watchlists, tags, custom ABIs
  testutil/factory.go   Test data factory

evm/                    EVM indexer
  adapter.go            Main indexer (2330 lines)
  api/server.go         REST + GraphQL + WebSocket + JSON-RPC
  api/repository.go     Database queries
  api/graphql.go        GraphQL schema
  contracts/            Verification, proxy detection, ABI decode
  defi/                 DeFi protocol indexing
  account/              User accounts, API keys
  erc4337.go            Account Abstraction
  mev.go                MEV detection
  blob.go               EIP-4844

storage/                Dual-layer storage
  unified.go            KV + Query combined
  kv/                   ZapDB
  query/sqlite.go       SQLite (default)
  query/postgres.go     PostgreSQL (build tag)

rustffi/                Optional CGO bindings to Rust static lib
{x,a,b,q,t,z,k}chain/  DAG chain adapters
pchain/                 Platform chain adapter
chain/, dag/            Shared libraries
migrations/             SQL schema (4 files)
e2e/                    End-to-end tests

API Routes

All under /v1/explorer/:

Endpoint	Description
GET /blocks	List blocks (cursor pagination)
GET /blocks/{id}	Block by hash or number
GET /blocks/{id}/transactions	Block's transactions
GET /transactions	List transactions
GET /transactions/{hash}	Transaction details
GET /transactions/{hash}/token-transfers	Token transfers in tx
GET /transactions/{hash}/internal-transactions	Internal calls
GET /transactions/{hash}/logs	Event logs
GET /addresses/{hash}	Address details + balance
GET /addresses/{hash}/transactions	Address transactions
GET /addresses/{hash}/tokens	Token balances
GET /tokens	List tokens
GET /tokens/{addr}/holders	Token holders
GET /smart-contracts/{addr}	Verified contract + ABI
POST /smart-contracts/{addr}/verify	Submit verification
GET /search	Full-text search
GET /stats	Chain statistics
POST /graphql	GraphQL queries
WS /ws	Realtime subscriptions

White-Label

Zero branding in code. Configure at runtime:

explorer --chain-name="My Chain" --coin=MYC --chain-id=12345

EVM Feature Parity

What the Go indexer covers, and where it stops:

• Block indexing (consensus, uncle, EIP-4844 blobs)
• Transaction types 0-3 (legacy, access list, EIP-1559, EIP-4844)
• Internal transaction tracing (3 tracers: callTracer, jsTracer, parityTracer)
• Token tracking: ERC-20, ERC-721, ERC-1155 (single + batch), ERC-404. One decoder reads them all — evm/decodeTransfers — so a movement has one reading whichever indexing path saw the block. ERC-20 and ERC-721 share the Transfer signature and are told apart by topic arity: the ERC-721 id is indexed and rides in topics[3].
• NFT items: /tokens/{addr}/instances and /instances/{id} — id, current owner (the destination of the item's last transfer), and the URI the contract gives it. The URI is an eth_call; the document behind it is not fetched, so uri_state says whether the chain answered ("ok"), named nothing ("absent"), or has not been asked ("unread"). image_url and metadata stay null rather than assert media nobody read.
• Contract verification: Solidity (all versions), Vyper, Standard JSON
• Proxy detection: EIP-1967, EIP-1822, EIP-1167, Gnosis Safe, OpenZeppelin
• Account Abstraction: ERC-4337 UserOps, bundlers, paymasters
• MEV detection: sandwich, frontrun, backrun, liquidation
• DeFi: AMM V2/V3, perps, lending, staking, bridges, CLOB orderbook
• evm/defi additionally carries event signatures for Seaport, LooksRare, Blur, X2Y2, Rarible and Zora. Nothing imports the package and no Lux chain has a marketplace contract deployed, so no marketplace is indexed today. migrations/004_nft_marketplace.sql is that same unbuilt venue's schema and is not applied — the live API reads the SQLite tables evm/indexer.go creates.
• Charts, statistics, gas oracle
• User accounts, API keys, watchlists, address tags

Testing

go test ./...                    # All tests (431+ across 22 packages)
go test ./explorer/...           # API layer (35 tests)
go test ./evm/...                # EVM indexer
go test ./storage/...            # Storage backends

Dependencies

Package	Purpose
hanzoai/base	HTTP server, collections, SSE, IAM
hanzoai/replicate	SQLite WAL streaming to S3
luxfi/age	PQ encryption (ML-KEM-768 + X25519)
luxfi/database	ZapDB KV wrapper
luxfi/zap	Zero-copy wire protocol

What This Replaced

Before (6 containers)	After (1 binary)
Elixir backend	evm/ Go package
Rust verifier	evm/contracts/verifier.go
Rust sig-provider	evm/contracts/abi.go
PostgreSQL	SQLite WAL
Redis	ZapDB KV
Graph Node + subgraphs	G-Chain native GraphQL