Skip to content

Commit 2544e17

Browse files
fubhyfubhy
committed
add CLAUDE.md
1 parent 126aa26 commit 2544e17

File tree

1 file changed

+212
-0
lines changed

1 file changed

+212
-0
lines changed

‎CLAUDE.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## ⚠️ CRITICAL MANDATORY STEP ⚠️
6+
**ALWAYS run `cargo fmt --all` after editing ANY .rs file - NO EXCEPTIONS!**
7+
- This is REQUIRED after every single Rust code change
8+
- Must be run from the project root directory
9+
- Must be done BEFORE committing any changes
10+
- If you forget this, you have failed to follow instructions
11+
12+
This document assumes that your human has already set up all database configuration required for the test suite to run.
13+
14+
## Project Overview
15+
16+
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.
17+
18+
## Essential Development Commands
19+
20+
### Unit Tests
21+
22+
```bash
23+
# Run unit tests (integration tests are excluded due to missing environment dependencies)
24+
cargo test --workspace --exclude graph-tests
25+
26+
# Run specific tests
27+
cargo test --package graph data_source::common::tests
28+
cargo test <specific_test_name>
29+
```
30+
31+
### Integration Tests
32+
33+
⚠️ **Only run integration tests when explicitly requested or when changes require full system testing**
34+
35+
Integration tests require external services and are more complex to run than unit tests. They test the full system end-to-end and should not be run by default during development. Use unit tests (`cargo test`) for regular development and only run integration tests when:
36+
37+
- Explicitly asked to do so
38+
- Making changes to integration/end-to-end functionality
39+
- Debugging issues that require full system testing
40+
- Preparing releases or major changes
41+
42+
**Prerequisites:**
43+
1. Docker and Docker Compose **OR** Nix for operating up environment dependencies
44+
2. Yarn (v1)
45+
3. Foundry (for smart contract compilation)
46+
47+
**Running Integration Tests:**
48+
```bash
49+
# Build graph-node and test binaries
50+
cargo build --bin graph-node --test integration_tests
51+
52+
# Run all integration tests
53+
cargo test -p graph-tests --test integration_tests -- --nocapture
54+
```
55+
56+
**Important Notes:**
57+
- Integration tests take significant time (several minutes)
58+
- Tests automatically reset the database between runs
59+
- Logs are written to `tests/integration-tests/graph-node.log`
60+
61+
### Code Quality
62+
```bash
63+
# 🚨 MANDATORY: Format all code IMMEDIATELY after any .rs file edit
64+
cargo fmt --all
65+
66+
# 🚨 MANDATORY: Check code for warnings and errors - MUST have zero warnings
67+
cargo check
68+
```
69+
70+
🚨 **CRITICAL REQUIREMENTS for ANY implementation**:
71+
1. `cargo fmt --all` MUST be run before any commit
72+
2. `cargo check` MUST show zero warnings before any commit
73+
3. The unit test suite MUST pass before any commit
74+
75+
Forgetting any of these means you failed to follow instructions. No exceptions!
76+
77+
## High-Level Architecture
78+
79+
### Core Components
80+
- **`graph/`**: Core abstractions, traits, and shared types
81+
- **`node/`**: Main executable and CLI (graphman)
82+
- **`chain/`**: Blockchain-specific adapters (ethereum, near, substreams)
83+
- **`runtime/`**: WebAssembly runtime for subgraph execution
84+
- **`store/`**: PostgreSQL-based storage layer
85+
- **`graphql/`**: GraphQL query execution engine
86+
- **`server/`**: HTTP/WebSocket APIs
87+
88+
### Data Flow
89+
```
90+
Blockchain → Chain Adapter → Block Stream → Trigger Processing → Runtime → Store → GraphQL API
91+
```
92+
93+
1. **Chain Adapters** connect to blockchain nodes and convert data to standardized formats
94+
2. **Block Streams** provide event-driven streaming of blockchain blocks
95+
3. **Trigger Processing** matches blockchain events to subgraph handlers
96+
4. **Runtime** executes subgraph code in WebAssembly sandbox
97+
5. **Store** persists entities with block-level granularity
98+
6. **GraphQL** processes queries and returns results
99+
100+
### Key Abstractions
101+
- **`Blockchain`** trait: Core blockchain interface
102+
- **`Store`** trait: Storage abstraction with read/write variants
103+
- **`RuntimeHost`**: WASM execution environment
104+
- **`TriggerData`**: Standardized blockchain events
105+
- **`EventConsumer`/`EventProducer`**: Component communication
106+
107+
### Architecture Patterns
108+
- **Event-driven**: Components communicate through async streams and channels
109+
- **Trait-based**: Extensive use of traits for abstraction and modularity
110+
- **Async/await**: Tokio-based async runtime throughout
111+
- **Multi-shard**: Database sharding for scalability
112+
- **Sandboxed execution**: WASM runtime with gas metering
113+
114+
## Development Guidelines
115+
116+
### Commit Convention
117+
Use format: `{crate-name}: {description}`
118+
- Single crate: `store: Support 'Or' filters`
119+
- Multiple crates: `core, graphql: Add event source to store`
120+
- All crates: `all: {description}`
121+
122+
### Git Workflow
123+
- Rebase on master (don't merge master into feature branch)
124+
- Keep commits logical and atomic
125+
- Use `git rebase -i` to clean up history before merging
126+
127+
### Implementation Success Criteria
128+
Before any commit or PR, ALL of the following MUST be satisfied:
129+
130+
1. **🚨 MANDATORY**: The unit test suite MUST pass
131+
2. **🚨 MANDATORY**: `cargo check` MUST show zero warnings
132+
3. **🚨 MANDATORY**: `cargo fmt --all` MUST be run after editing ANY .rs file
133+
134+
**Testing Notes**:
135+
- Unit tests are inlined with source code
136+
- Integration tests require environment dependencies that can be provided **EITHER** through Docker & Docker Compose **OR** through Nix
137+
138+
## Crate Structure
139+
140+
### Core Crates
141+
- **`graph`**: Shared types, traits, and utilities
142+
- **`node`**: Main binary and component wiring
143+
- **`core`**: Business logic and subgraph management
144+
145+
### Blockchain Integration
146+
- **`chain/ethereum`**: Ethereum chain support
147+
- **`chain/near`**: NEAR protocol support
148+
- **`chain/substreams`**: Substreams data source support
149+
150+
### Infrastructure
151+
- **`store/postgres`**: PostgreSQL storage implementation
152+
- **`runtime/wasm`**: WebAssembly runtime and host functions
153+
- **`graphql`**: Query processing and execution
154+
- **`server/`**: HTTP/WebSocket servers
155+
156+
### Key Dependencies
157+
- **`diesel`**: PostgreSQL ORM
158+
- **`tokio`**: Async runtime
159+
- **`tonic`**: gRPC framework
160+
- **`wasmtime`**: WebAssembly runtime
161+
- **`web3`**: Ethereum interaction
162+
163+
## Test Environment Requirements
164+
165+
### ✨ New: Process Compose Setup (Recommended)
166+
167+
The repository includes a process-compose-flake setup that provides native, declarative service management.
168+
169+
**Unit Tests:**
170+
```bash
171+
# Start PostgreSQL + IPFS for unit tests (run manually, or Claude can launch with --detach)
172+
# PostgreSQL: localhost:5432, IPFS: localhost:5001
173+
nix run .#unit-tests
174+
175+
# Alternatively, Claude can run services in background:
176+
nix run .#unit-tests -- --detach
177+
178+
# In another terminal (or same if using --detach), run unit tests
179+
cargo test --workspace --exclude graph-tests
180+
```
181+
182+
**Integration Tests:**
183+
```bash
184+
# Start all services for integration tests (run manually, or Claude can launch with --detach)
185+
# PostgreSQL: localhost:3011, IPFS: localhost:3001, Anvil: localhost:3021
186+
nix run .#integration-tests
187+
188+
# Alternatively, Claude can run services in background:
189+
nix run .#integration-tests -- --detach
190+
191+
# In another terminal (or same if using --detach), run integration tests
192+
cargo test -p graph-tests --test integration_tests
193+
```
194+
195+
**Services Configuration:**
196+
The services are configured to use the test suite default ports for unit- and integration tests respectively.
197+
198+
| Service | Unit Tests Port | Integration Tests Port | Database/Config |
199+
|---------|-----------------|------------------------|-----------------|
200+
| PostgreSQL | 5432 | 3011 | `graph-test` / `graph-node` |
201+
| IPFS | 5001 | 3001 | Data in `./.data/ipfs-*` |
202+
| Anvil (Ethereum) | - | 3021 | Deterministic test chain |
203+
204+
**Service Configuration:**
205+
The setup combines built-in services-flake services with custom multiService modules:
206+
207+
**Built-in Services:**
208+
- **PostgreSQL**: Uses services-flake's postgres service with a helper function (`mkPostgresConfig`) that provides graph-specific defaults including required extensions.
209+
210+
**Custom Services** (located in `./nix/`):**
211+
- `ipfs.nix`: IPFS (kubo) with automatic initialization and configurable ports
212+
- `anvil.nix`: Ethereum test chain with deterministic configuration

0 commit comments

Comments
 (0)