eth-docs/project-dependencies.md

Ethereum statediff infrastructure projects

This document lists all projects involved in the Ethereum state-diffing infrastructure maintained by Vulcanize/Cerc. The infrastructure consists of 20 repositories spanning core plugins, utilities, IPLD/database layers, RPC servers, and supporting tools.

Core plugin components

plugeth

Geth fork with plugin architecture for extending Ethereum client functionality without modifying core code.

Dependencies: none

Used by: plugeth-statediff

plugeth-utils

Utility library providing shared functionality for plugeth plugins.

Dependencies: none

Used by: plugeth-statediff, plugeth

plugeth-statediff

Core state-diffing plugin that extracts Ethereum state changes between blocks as a plugeth plugin.

Dependencies:

• plugeth
• plugeth-utils

Used by:

• eth-statediff-service
• ipld-eth-db-validator
• Integration tests (via stack-orchestrator)

Utility tools

eth-testing

Ethereum testing utilities and helpers.

Dependencies: geth directly

Used by:

• eth-statediff-service
• ipld-eth-state-snapshot

eth-iterator-utils

Iterator utilities for traversing Ethereum state tries, including PrefixBoundIterator and SubtrieIterators.

Dependencies: geth directly

Used by: eth-ipfs-state-validator

eth-dump-genblock

Tool to generate genesis blocks from Geth configuration files.

Dependencies: geth directly

eth-statediff-compliance

Tooling to verify correctness and benchmark performance of statediff results.

Dependencies: geth directly

Used by: plugeth-statediff integration tests

IPLD and database abstraction layer

ipld-eth-db

Postgres database schemas and utilities for storing Ethereum IPLD objects.

Dependencies: none (defines schemas)

Used by:

• ipld-eth-statedb
• ipld-eth-server
• All services that index or query Ethereum data

ipfs-ethdb

Implementation of ethdb interfaces for Ethereum data stored in IPFS/Postgres.

Dependencies: none (interface definitions)

Used by:

• ipld-eth-statedb
• ipld-eth-db-validator
• eth-ipfs-state-validator

ipld-eth-statedb

StateDB implementations for different access patterns (direct_by_leaf, trie_by_cid). Provides state access backed by IPFS/Postgres instead of LevelDB.

Dependencies:

• plugeth-statediff (for state diffing)
• ipfs-ethdb (for database access)

Used by:

• eth-ipfs-state-validator
• ipld-eth-server
• ipld-eth-db-validator

RPC server and validation

ipld-eth-server

JSON-RPC server providing Ethereum RPC endpoints backed by indexed IPLD objects in Postgres.

Dependencies:

• eth-ipfs-state-validator
• ipld-eth-statedb

Used by:

• ipld-eth-db-validator (for verification)
• chain-chunker (for verification)
• External clients querying indexed data

eth-ipfs-state-validator

Validates completeness and correctness of IPFS-backed Ethereum state data.

Dependencies:

• ipld-eth-statedb
• eth-iterator-utils

Used by: ipld-eth-server

Standalone services

ipld-eth-db-validator

Validates indexed Ethereum IPLD objects stored in Postgres database.

Dependencies:

• ipfs-ethdb
• ipld-eth-server
• ipld-eth-statedb
• plugeth-statediff

eth-statediff-service

Standalone service for performing state diffing on a geth database.

Dependencies:

• eth-testing
• plugeth-statediff

Used by: chain-chunker

ipld-eth-state-snapshot

Extracts Ethereum state at specific block heights for offline processing.

Dependencies: eth-testing

Used by: chain-chunker

chain-chunker

Orchestrates offline statediffing and data import pipeline.

Dependencies:

• eth-statediff-service
• ipld-eth-state-snapshot
• ipld-eth-server (for verification)

Supporting infrastructure

lighthouse

Ethereum consensus client (beacon chain) used in test networks, forked to apply minor patches.

Dependencies: none (external dependency)

Used by: fixturenet-eth-stacks

stack-orchestrator

Deployment tool for setting up, building, and deploying Docker-based service stacks.

Used by: Integration tests for plugeth-statediff and other services

fixturenet-eth-stacks

Stack-orchestrator stack definitions for deploying local Ethereum testnets for development and integration testing. Contains two main stacks:

• fixturenet-eth: Basic geth + lighthouse testnet
• fixturenet-plugeth: Full state-diffing integration stack with plugeth, indexing, and RPC server

Dependencies:

• stack-orchestrator (deployment tool)
• lighthouse (consensus client)
• plugeth (for fixturenet-plugeth stack)
• plugeth-statediff (for fixturenet-plugeth stack)
• ipld-eth-db (for fixturenet-plugeth stack)
• ipld-eth-server (for fixturenet-plugeth stack)

Used by: Integration tests and development workflows for plugeth-statediff and related services

system-tests

End-to-end system integration tests.

Used by: Integration tests for plugeth-statediff

Dependency graph overview

Foundational layer:
  plugeth-utils → plugeth → plugeth-statediff

Database/IPLD layer:
  ipld-eth-db (schemas)
  ipfs-ethdb (interfaces) → ipld-eth-statedb

Server layer:
  eth-ipfs-state-validator + ipld-eth-statedb → ipld-eth-server

Services layer:
  plugeth-statediff + eth-testing → eth-statediff-service
  eth-testing → ipld-eth-state-snapshot
  eth-statediff-service + ipld-eth-state-snapshot + ipld-eth-server → chain-chunker

Validation:
  multiple deps → ipld-eth-db-validator

Utilities:
  geth → eth-testing, eth-iterator-utils, eth-dump-genblock, eth-statediff-compliance

Integration testing:
  lighthouse + plugeth + plugeth-statediff + ipld-eth-db + ipld-eth-server
    → fixturenet-eth-stacks (deployed via stack-orchestrator)

Update order for Ethereum fork upgrades

When updating for a new Ethereum fork or other major change, follow this sequence:

1. Utility tools (can be done in parallel):

   • eth-testing
   • eth-iterator-utils
   • eth-dump-genblock
   • eth-statediff-compliance

2. Core plugin stack (sequential):

   • plugeth-utils
   • plugeth
   • plugeth-statediff

3. IPLD/database layer:

   • ipfs-ethdb
   • ipld-eth-statedb

4. Validation and server:

   • eth-ipfs-state-validator
   • ipld-eth-server

5. Standalone services:

   • ipld-eth-db-validator
   • eth-statediff-service
   • ipld-eth-state-snapshot
   • chain-chunker

6. Supporting infrastructure:

   • stack-orchestrator (config updates as needed)
   • fixturenet-eth-stacks (stack definition updates if needed)
   • system-tests

See plugeth-statediff-upgrade-guide.md for a more comprehensive guide.