GO — Healthy across the board

• Last commit 1d ago
• 6 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Graph Node is a Rust-based blockchain indexing engine that extracts, transforms, and serves blockchain data via GraphQL. It reads events and state from blockchains (Ethereum, NEAR, etc.) through Firehose providers or RPC, stores normalized data in PostgreSQL, and exposes it as queryable GraphQL APIs. It's the core infrastructure behind The Graph Protocol's decentralized indexing network. Monorepo with Cargo workspace. Core logic in core/ (indexing state machine), chain/ (Ethereum, NEAR adapters), store/postgres/ (PostgreSQL persistence layer), runtime/wasm/ (WASM execution for subgraph mappings), and server/ (HTTP, GraphQL, JSON-RPC endpoints). Shared types in graph/ crate. Firehose protocol support via chain/common/proto/near-filter-substreams.proto. See Cargo.toml for workspace member list.

Subgraph developers who deploy indexing services to The Graph Network, contributors building blockchain data infrastructure, and DevOps teams running production indexers. Subgraph developers test locally before deployment; core contributors extend chain support or optimize indexing performance.

Highly mature and production-ready. Version 0.43.0 with active CI/CD (see .github/workflows), comprehensive test coverage across chain/ethereum, store/postgres, and runtime modules. Workspace spans 12 member crates with solid dependency management (alloy, diesel-async, async-graphql). Active development: recent stable Rust toolchain enforcement and modern async/await patterns throughout.

Low immediate risk but complexity-heavy. Large monorepo with tight coupling between indexing state machine (core), storage layer (store/postgres with diesel-async), and WASM runtime (runtime/wasm). Protobuf schemas in chain/common/proto and chain/ethereum/proto require protoc toolchain. PostgreSQL 12+ with specific extensions (pg_trgm, btree_gist, postgres_fdw) is mandatory—misconfiguration blocks all indexing. Heavy async code with potential deadlock complexity in graph-core synchronization primitives.

Active development on blockchain adapter stability (chain/ethereum/src/adapter.rs, chain/ethereum/src/codec.rs for event decoding), PostgreSQL query optimization, and WASM runtime improvements. Dependabot enabled (.github/dependabot.yml). Recent focus on modern async patterns (diesel-async 0.8.0, axum 0.8.9) and Alloy 2.0.4 integration for Ethereum RPC.

rustup install stable
git clone https://github.com/graphprotocol/graph-node.git
cd graph-node
psql -U postgres <<'EOF'
create user graph with password 'graph';
create database "graph-node" with owner=graph template=template0 encoding='UTF8' locale='C';
create extension pg_trgm;
create extension btree_gist;
create extension postgres_fdw;
grant usage on foreign data wrapper postgres_fdw to graph;
EOF
DATABASE_URL=postgres://graph:graph@localhost/graph-node \
  ETHEREUM_RPC_URL=http://localhost:8545 \
  IPFS_HOST=http://localhost:5001 \
  cargo run --release -p graph-node

Requires: PostgreSQL 12+, Protobuf compiler, IPFS daemon, Ethereum RPC (local or Infura/Alchemy), and Rust 1.80+.

Daily commands:

cargo build --release
cargo test --all --release
# Run indexer with local Ethereum node at :8545
DATABASE_URL=postgres://graph:graph@localhost/graph-node \
  ETHEREUM_RPC_URL=http://localhost:8545 \
  IPFS_HOST=http://localhost:5001 \
  GRAPHQL_LISTEN_ADDR=0.0.0.0:8000 \
  cargo run --release -p graph-node
# GraphQL available at http://localhost:8000/subgraphs/id/<subgraph-id>

Use .devcontainer/docker-compose.yml for full local stack: docker-compose up (includes Postgres, IPFS, test Ethereum node).

• Cargo.toml — Workspace root configuration defining all member crates, dependencies (alloy, tokio, etc.), and version management—essential for understanding the entire build and dependency graph.
• chain/ethereum/src/lib.rs — Entry point for Ethereum chain integration; defines core trait implementations and adapters that all blockchain indexing flows depend on.
• core/src/amp_subgraph/manager.rs — Core subgraph lifecycle management; orchestrates deployment, execution, and state tracking for all indexed subgraphs.
• chain/ethereum/src/chain.rs — Ethereum-specific chain abstraction implementing block streaming, transaction handling, and chain event ingestion logic.
• chain/ethereum/src/ingestor.rs — Block ingestion pipeline that handles polling/streaming blocks and feeding them into the indexing engine—critical data entry point.
• README.md — Project overview explaining Graph Node's role in blockchain data indexing and its primary use cases for both developers and contributors.
• .github/workflows/ci.yml — CI/CD pipeline definition controlling build, test, and deployment processes; essential for understanding quality gates and release procedures.

Add Support for a New Blockchain

1. Create a new crate under chain/{blockchain}/ with Cargo.toml following the ethereum pattern (chain/ethereum/Cargo.toml)
2. Define chain-specific protobuf messages for blocks and transactions (chain/ethereum/proto/ethereum.proto)
3. Implement the Adapter trait for your blockchain's RPC communication (chain/ethereum/src/adapter.rs)
4. Implement Chain trait for block streaming and trigger detection (chain/ethereum/src/chain.rs)
5. Implement Codec trait to serialize/deserialize chain-specific data (chain/ethereum/src/codec.rs)
6. Register your new chain module in the workspace Cargo.toml members list (Cargo.toml)

Add a New Subgraph Management Command

1. Create a new command module in the deployment commands directory (core/graphman/src/commands/deployment/mod.rs)
2. Implement the command struct following pause.rs pattern with Execute trait (core/graphman/src/commands/deployment/pause.rs)
3. Register the command in the command handler registry (core/graphman/src/commands/mod.rs)
4. Wire the command into the subgraph manager's deployment interface (core/src/amp_subgraph/manager.rs)

Extend Ethereum Contract ABI Handling

1. Add new ABI encoding/decoding logic to the runtime ABI module (chain/ethereum/src/runtime/abi.rs)
2. Update the call helper to support new function signatures (chain/ethereum/src/call_helper.rs)
3. Extend the buffered call cache if needed for performance (chain/ethereum/src/buffered_call_cache.rs)
4. Add integration tests in the Ethereum test suite (chain/ethereum/src/tests.rs)

Add a Custom Data Source Trigger

1. Define the trigger type in the Ethereum data source module (chain/ethereum/src/data_source.rs)
2. Implement trigger matching logic in the chain module (chain/ethereum/src/chain.rs)
3. Update the trigger enum in the module namespace (chain/ethereum/src/trigger.rs)
4. Register the trigger in subgraph execution context (core/src/amp_subgraph/manager.rs)

• Rust + Tokio async runtime — High-performance, memory-safe language critical for processing high-throughput blockchain data streams without GC pauses; Tokio enables efficient concurrent block processing and network I/O.
• WebAssembly (WASM) for subgraph mappings — Sandboxed, deterministic execution environment for user-provided subgraph code; prevents malicious or buggy mappings from crashing the indexer.
• PostgreSQL for entity storage — Reliable ACID transactions, complex query support, and proven scalability for storing billions of indexed entities with rich indexing.
• Protocol Buffers for blockchain data serialization — Efficient, language-agnostic serialization for blockchain state (blocks, transactions) supporting backward compatibility and interoperability with Firehose.
• GraphQL for query interface — Declarative query language allowing clients to fetch exactly the indexed data they need; aligns with Web3 data discovery patterns.

• Synchronous block-by-block processing rather than parallel block processing

  • Why: Simplifies deterministic state management and ordering guarantees; prevents race conditions in entity storage.
  • Consequence: Maximum indexing throughput is constrained by sequential block latency (12-15s per block on Ethereum); mitigated by batching and optimized storage.

• WASM runtime for mapping execution instead of native Rust

  • Why: Enables safe execution of user-provided code; maintains isolation between subgraphs.
  • Consequence: WASM overhead (~20-50% slower than native code); justified by security and multi-tenant safety.

• PostgreSQL as sole backing store instead of append-only event log

  • Why: Simpler operational model
  • Consequence: undefined

PostgreSQL version/extensions: Must use PostgreSQL 12+. Extensions pg_trgm, btree_gist, postgres_fdw are required and will cause silent failures if missing—check with \dx in psql. Reorg handling: Ethereum block reorg detection relies on canonical chain tracking in store; misconfigured chain RPC can cause inconsistent indexing—monitor store/postgres logs. WASM host function mismatch: Subgraph mappings expect specific host functions (eth.call, datastore.set, etc.). Missing or renamed functions cause cryptic WASM instantiation errors—see runtime/wasm/src/host_exports.rs. Protobuf regeneration: Editing .proto files requires running build.rs in chain/ethereum/build.rs; cargo clean may be needed. Async deadlocks: Heavy use of Tokio channels in core state machine—misuse of blocking_on or sync Mutex in async code causes hangs. Environment variables case-sensitive: DATABASE_URL vs database_url matters; see .devcontainer/docker-compose.yml for correct names. IPFS connectivity: Subgraph ABIs loaded from IPFS—unavailable IPFS daemon silently fails subgraph instantiation.

• Blockchain reorg detection — Graph Node must handle chain reorgs (detected via canonical hash tracking in store/postgres) and rewind indexing to a safe block height. Incorrect reorg handling causes inconsistent or duplicate indexed data.
• WebAssembly (WASM) sandboxing — Subgraph mappings run as WASM modules (runtime/wasm) to safely execute untrusted transformation logic. Failing to sandbox or providing wrong host functions breaks indexing.
• Diesel async ORM with connection pooling — Graph Node uses diesel-async with deadpool connection pooling (store/postgres) to handle concurrent database access without blocking. Misunderstanding pool exhaustion or query lifecycle causes hangs.
• Protobuf code generation for RPC schemas — Chain support uses .proto files (chain/common/proto, chain/ethereum/proto) to define Firehose block/transaction structures. Missing protoc or stale generated code breaks chain adapters.
• Ethereum ABI event decoding — chain/ethereum/src/codec.rs decodes EVM event logs using contract ABIs. Incorrect decoding or type mismatch silently loses indexed data.
• GraphQL schema derivation from subgraph manifests — Graph Node introspects subgraph manifests to generate a GraphQL schema matching entity types. Schema generation errors prevent query serving.
• Event-sourced indexing with idempotency — Graph Node replays blocks from chain to rebuild index (idempotent operations). Non-idempotent handlers cause duplicate entities on reindex.

• graphprotocol/subgraph — Defines subgraph manifest schema and AssemblyScript SDK—what Graph Node executes; essential companion for understanding indexing specs
• graphprotocol/graph-cli — CLI tool for subgraph development, codegen, and deployment—what subgraph developers use to create manifests Graph Node indexes
• streamingfast/firehose-ethereum — Alternative high-performance block source for Ethereum via Firehose protocol—Graph Node integrates with this for production indexing
• graphprotocol/graph-tooling — Test utilities and testing framework for subgraph developers—used to validate mapping logic before deployment to Graph Node
• ethereum/go-ethereum — Geth Ethereum node implementation—Graph Node queries against Geth RPC endpoints; understanding Geth's JSON-RPC API and state access is critical

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for Ethereum adapter transport layer

The chain/ethereum/src/transport.rs and chain/ethereum/src/ethereum_adapter.rs files lack dedicated integration tests. Given that Graph Node's core value is blockchain data indexing, the transport layer (which handles RPC communication with Ethereum nodes) is critical infrastructure. Currently, chain/ethereum/tests/ only contains a README.md. Adding tests would catch regressions in RPC error handling, connection pooling, and protocol upgrades, which directly impact production data integrity.

• [ ] Create chain/ethereum/tests/test_transport.rs with tests for successful and failed RPC calls
• [ ] Add tests for connection timeout and retry logic in chain/ethereum/src/transport.rs
• [ ] Create chain/ethereum/tests/test_ethereum_adapter.rs for adapter initialization and capability detection
• [ ] Test codec serialization/deserialization in chain/ethereum/src/codec.rs with various Ethereum block types
• [ ] Document test setup in chain/ethereum/tests/README.md with instructions for mocking Ethereum nodes

Add GitHub Actions CI workflow for validating Protobuf definitions across chains

The repo maintains Protocol Buffer definitions across multiple chains (chain/common/proto/near-filter-substreams.proto, chain/ethereum/proto/ethereum.proto) but lacks explicit CI validation for proto compilation and generated code. The workspace currently has audit.yml, ci.yml, and gnd-binary-build.yml in .github/workflows/, but none specifically validate that proto files compile correctly across all chain implementations or that breaking changes are caught early. This prevents silent proto compatibility issues from entering main.

• [ ] Create .github/workflows/protobuf-validate.yml with buf (protobuf linter) checks
• [ ] Add proto compilation tests for chain/common, chain/ethereum, and chain/near in the workflow
• [ ] Validate that generated Rust code in chain/ethereum/src/protobuf/ matches committed versions
• [ ] Run protobuf breaking change detection against previous releases using buf breaking
• [ ] Document proto development guidelines in CONTRIBUTING.md with proto update instructions

Refactor oversized Ethereum codec and ABI runtime modules into sub-crates

The chain/ethereum/src/runtime/abi.rs and chain/ethereum/src/codec.rs files likely contain substantial logic for ABI encoding/decoding and data serialization. Based on the workspace structure which already separates concerns (runtime/wasm, runtime/derive, runtime/test), these codec responsibilities should be extracted into dedicated crates. This would improve build times (parallel compilation), enable code reuse in chain/near, and clarify dependencies. The Cargo.toml workspace already has 18 members, suggesting the maintainers value modular organization.

• [ ] Analyze chain/ethereum/src/runtime/abi.rs and chain/ethereum/src/codec.rs to identify shared logic suitable for extraction
• [ ] Create new crate runtime/ethereum-codec/ with Cargo.toml and move ABI/codec logic there
• [ ] Update chain/ethereum/Cargo.toml to depend on the new runtime/ethereum-codec crate
• [ ] Add runtime/ethereum-codec to workspace.members in root Cargo.toml
• [ ] Create chain/ethereum/tests/test_abi_codec.rs to test the new crate's public API in isolation
• [ ] Update .cargo/config.toml if needed to optimize build ordering for the new crate

• Add missing unit tests for chain/ethereum/src/buffered_call_cache.rs—this RPC result caching layer has no test coverage visible in the repo. Implement tests for cache hit/miss and eviction strategies.
• Improve error messages in store/postgres/src by adding context with .context() from anyhow crate—many Diesel errors are currently logged without human-readable context, making production debugging difficult. Example: src/relational.rs entity save operations.
• Add integration test for NEAR chain adapter (chain/near/) following the pattern of chain/ethereum/tests/ if any exist—NEAR support was added but test coverage appears minimal compared to Ethereum, making it risky for production.

• High · Outdated Rust Edition — Cargo.toml (workspace.package). The workspace is configured with edition = '2024', which does not exist. Valid editions are 2015, 2018, and 2021. This indicates a configuration error that may prevent proper compilation and security features from being applied. Fix: Update to a valid edition: 2021 (recommended for modern Rust) or 2018. Use 'edition = "2021"' in the workspace package configuration.
• High · Incomplete Dependency Information — Cargo.toml. The Cargo.toml file provided is truncated at the diesel-dynamic-schema dependency definition. This makes it impossible to fully audit all dependencies for known vulnerabilities. The complete dependency list cannot be verified. Fix: Provide the complete Cargo.toml file. Run 'cargo audit' and 'cargo-deny' to check for known vulnerabilities in all dependencies. Consider enabling security audits in CI/CD pipeline.
• Medium · Broad TLS Provider Configuration — Cargo.toml (workspace.dependencies - rustls). The rustls dependency is configured with 'aws_lc_rs' as the default provider, which is transitively pulled in by multiple dependencies (alloy via aws_lc_rs and object_store via reqwest with ring). While aws_lc_rs is a valid provider, this creates a complex dependency chain that may be difficult to audit and could introduce supply chain risks. Fix: Review the necessity of having both aws_lc_rs and ring providers. Consider using only aws_lc_rs consistently across all dependencies. Document the TLS provider strategy and ensure it's justified for your security requirements.
• Medium · Deprecated Diesel Feature Flag — Cargo.toml (workspace.dependencies - diesel). The diesel dependency includes 'i-implement-a-third-party-backend-and-opt-into-breaking-changes' feature flag. This flag is designed for third-party backends and should not be used for standard PostgreSQL implementations. It indicates the codebase may be using unstable APIs. Fix: Remove the 'i-implement-a-third-party-backend-and-opt-into-breaking-changes' feature flag unless implementing a custom database backend. Use only standard diesel features for PostgreSQL: 'postgres', 'serde_json', 'numeric', 'r2d2', 'chrono'.
• Medium · Missing Dependency Pinning Strategy — Cargo.toml (workspace.dependencies). Most dependencies use loose version constraints (e.g., '0.8.0', '1.0', '2.0.4'). Without explicit lockfile requirements or semantic versioning locks, transitive dependencies could introduce breaking changes or vulnerabilities in patch/minor updates. Fix: Review and pin critical security-sensitive dependencies. Use '=' prefix for exact versions on security-critical crates. Ensure Cargo.lock is committed to version control and updated regularly. Run 'cargo update' periodically and review changes.
• Medium · Protobuf Compiler Dependency Risk — chain/ethereum/build.rs, chain/near/build.rs. The codebase uses Protocol Buffers (.proto files) with build.rs files (chain/ethereum/build.rs, chain/near/build.rs). If protobuf compilation is not properly validated, this could lead to arbitrary code execution risks during the build process. Fix: Ensure build.rs scripts validate all code generation outputs. Use 'prost' or 'protobuf' crates with security best practices. Verify proto files come from trusted sources. Add build script sandboxing if possible.
• Low · Multiple License Declarations — Cargo.toml (workspace.package - license). The workspace is licensed under 'MIT OR Apache-2.0', which is dual-licensed. While not a security vulnerability, this requires license compliance verification for all dependencies. Fix: Verify all dependencies are compatible with MIT/Apache-2.0 licensing. Use tools like 'cargo-license' and 'cargo-deny' to ensure compliance and catch GPL or other incompatible licenses.
• Low · No Security Policy File — undefined. No SECURITY.md or security policy file visible in the repository structure. This makes it unclear how to report security vulnerabilities responsibly. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/graphprotocol/graph-node shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live graphprotocol/graph-node repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/graphprotocol/graph-node.

What it runs against: a local clone of graphprotocol/graph-node — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in graphprotocol/graph-node | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of graphprotocol/graph-node. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/graphprotocol/graph-node.git
#   cd graph-node
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of graphprotocol/graph-node and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "graphprotocol/graph-node(\\.git)?\\b" \\
  && ok "origin remote is graphprotocol/graph-node" \\
  || miss "origin remote is not graphprotocol/graph-node (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "chain/ethereum/src/lib.rs" \\
  && ok "chain/ethereum/src/lib.rs" \\
  || miss "missing critical file: chain/ethereum/src/lib.rs"
test -f "core/src/amp_subgraph/manager.rs" \\
  && ok "core/src/amp_subgraph/manager.rs" \\
  || miss "missing critical file: core/src/amp_subgraph/manager.rs"
test -f "chain/ethereum/src/chain.rs" \\
  && ok "chain/ethereum/src/chain.rs" \\
  || miss "missing critical file: chain/ethereum/src/chain.rs"
test -f "chain/ethereum/src/ingestor.rs" \\
  && ok "chain/ethereum/src/ingestor.rs" \\
  || miss "missing critical file: chain/ethereum/src/ingestor.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/graphprotocol/graph-node"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.