From ae6744806abb56b7d7e2a41240f07d6cdd475d45 Mon Sep 17 00:00:00 2001 From: Sebastian Lorenz Date: Wed, 16 Jul 2025 13:07:10 +0200 Subject: [PATCH] add claude.md --- CLAUDE.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..ce48b9ab471 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,181 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Graph Node is a Rust-based decentralized blockchain indexing protocol that enables efficient querying of blockchain data through GraphQL. It's the core component of The Graph protocol, written as a Cargo workspace with multiple crates organized by functionality. + +## Essential Development Commands + +### Build and Run +```bash +# Build and run Graph Node +cargo run -p graph-node --release -- \ + --postgres-url $POSTGRES_URL \ + --ethereum-rpc NETWORK_NAME:[CAPABILITIES]:URL \ + --ipfs 127.0.0.1:5001 + +# Development with auto-reload (requires cargo-watch) +cargo watch \ + -x "fmt --all" \ + -x check \ + -x "test -- --test-threads=1" \ + -x "doc --no-deps" +``` + +### Testing +```bash +# Run all tests (requires test config) +GRAPH_NODE_TEST_CONFIG=`pwd`/store/test-store/config.simple.toml cargo test --workspace --exclude graph-tests + +# Run a single test +cargo test + +# Test setup using Docker Compose +./store/test-store/devel/up.sh + +# Reset test databases +./store/test-store/devel/db-reset +``` + +### Code Quality +```bash +# Format all code +cargo fmt --all + +# Check code without building +cargo check + +# Build documentation +cargo doc --no-deps +``` + +### Database Setup +```bash +# Create test database +psql -U <'; +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 + +export POSTGRES_URL=postgresql://graph:@localhost:5432/graph-node +``` + +## High-Level Architecture + +### Core Components +- **`graph/`**: Core abstractions, traits, and shared types +- **`node/`**: Main executable and CLI (graphman) +- **`chain/`**: Blockchain-specific adapters (ethereum, near, substreams) +- **`runtime/`**: WebAssembly runtime for subgraph execution +- **`store/`**: PostgreSQL-based storage layer +- **`graphql/`**: GraphQL query execution engine +- **`server/`**: HTTP/WebSocket APIs + +### Data Flow +``` +Blockchain → Chain Adapter → Block Stream → Trigger Processing → Runtime → Store → GraphQL API +``` + +1. **Chain Adapters** connect to blockchain nodes and convert data to standardized formats +2. **Block Streams** provide event-driven streaming of blockchain blocks +3. **Trigger Processing** matches blockchain events to subgraph handlers +4. **Runtime** executes subgraph code in WebAssembly sandbox +5. **Store** persists entities with block-level granularity +6. **GraphQL** processes queries and returns results + +### Key Abstractions +- **`Blockchain`** trait: Core blockchain interface +- **`Store`** trait: Storage abstraction with read/write variants +- **`RuntimeHost`**: WASM execution environment +- **`TriggerData`**: Standardized blockchain events +- **`EventConsumer`/`EventProducer`**: Component communication + +### Architecture Patterns +- **Event-driven**: Components communicate through async streams and channels +- **Trait-based**: Extensive use of traits for abstraction and modularity +- **Async/await**: Tokio-based async runtime throughout +- **Multi-shard**: Database sharding for scalability +- **Sandboxed execution**: WASM runtime with gas metering + +## Development Guidelines + +### Commit Convention +Use format: `{crate-name}: {description}` +- Single crate: `store: Support 'Or' filters` +- Multiple crates: `core, graphql: Add event source to store` +- All crates: `all: {description}` + +### Git Workflow +- Rebase on master (don't merge master into feature branch) +- Keep commits logical and atomic +- Use `git rebase -i` to clean up history before merging + +### Testing Requirements +- Unit tests inline with source code +- Integration tests require Docker Compose setup +- Tests should run with `--test-threads=1` for consistency +- Use `GRAPH_NODE_TEST_CONFIG` environment variable for test configuration + +### Environment Variables +- `POSTGRES_URL`: Database connection string +- `GRAPH_LOG=debug`: Enable debug logging +- `THEGRAPH_STORE_POSTGRES_DIESEL_URL`: For Diesel/Postgres store tests +- `GRAPH_NODE_TEST_CONFIG`: Points to test configuration file + +## Crate Structure + +### Core Crates +- **`graph`**: Shared types, traits, and utilities +- **`node`**: Main binary and component wiring +- **`core`**: Business logic and subgraph management + +### Blockchain Integration +- **`chain/ethereum`**: Ethereum chain support +- **`chain/near`**: NEAR protocol support +- **`chain/substreams`**: Substreams data source support + +### Infrastructure +- **`store/postgres`**: PostgreSQL storage implementation +- **`runtime/wasm`**: WebAssembly runtime and host functions +- **`graphql`**: Query processing and execution +- **`server/`**: HTTP/WebSocket servers + +### Key Dependencies +- **`diesel`**: PostgreSQL ORM +- **`tokio`**: Async runtime +- **`tonic`**: gRPC framework +- **`wasmtime`**: WebAssembly runtime +- **`web3`**: Ethereum interaction + +## Common Development Tasks + +### Adding New Blockchain Support +1. Create new crate under `chain/` +2. Implement `Blockchain` trait +3. Add chain-specific `TriggerData` types +4. Implement block streaming and event parsing +5. Add integration tests + +### Modifying Storage Layer +- Storage interfaces defined in `graph/src/components/store/` +- PostgreSQL implementation in `store/postgres/` +- Use migrations for schema changes +- Consider multi-shard implications + +### GraphQL Changes +- Schema parsing in `graphql/src/schema/` +- Query execution in `graphql/src/execution/` +- Resolver implementations handle entity fetching +- Consider query complexity and performance + +### Runtime Modifications +- Host functions in `runtime/wasm/src/host.rs` +- AssemblyScript bindings in `runtime/wasm/src/asc_abi/` +- Gas metering in `runtime/wasm/src/gas/` +- Security considerations for sandboxing \ No newline at end of file