Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 1addffb

Browse files
committed
all: add flake.nix setup and CLAUDE.md documentation
1 parent 8929c43 commit 1addffb

File tree

6 files changed

+647
-1
lines changed

6 files changed

+647
-1
lines changed

‎.gitignore

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,12 @@ lcov.info
3232

3333
# Docker volumes and debug logs
3434
.postgres
35-
logfile
35+
logfile
36+
37+
# Nix related files
38+
.direnv
39+
.envrc
40+
.data
41+
42+
# Local claude settings
43+
.claude/settings.local.json

‎CLAUDE.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
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 -p 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+
# Run all integration tests
50+
cargo test -p graph-tests --test integration_tests -- --nocapture
51+
52+
# Run a specific integration test case (e.g., "grafted" test case)
53+
TEST_CASE=grafted 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+
# Human: Start PostgreSQL + IPFS for unit tests in a separate terminal
172+
# PostgreSQL: localhost:5432, IPFS: localhost:5001
173+
nix run .#unit
174+
175+
# Claude can then run unit tests
176+
cargo test --workspace --exclude graph-tests
177+
```
178+
179+
**Integration Tests:**
180+
```bash
181+
# Human: Start all services for integration tests in a separate terminal
182+
# PostgreSQL: localhost:3011, IPFS: localhost:3001, Anvil: localhost:3021
183+
nix run .#integration
184+
185+
# Claude can then run integration tests
186+
cargo test -p graph-tests --test integration_tests
187+
```
188+
189+
**Services Configuration:**
190+
The services are configured to use the test suite default ports for unit- and integration tests respectively.
191+
192+
| Service | Unit Tests Port | Integration Tests Port | Database/Config |
193+
|---------|-----------------|------------------------|-----------------|
194+
| PostgreSQL | 5432 | 3011 | `graph-test` / `graph-node` |
195+
| IPFS | 5001 | 3001 | Data in `./.data/unit` or `./.data/integration` |
196+
| Anvil (Ethereum) | - | 3021 | Deterministic test chain |
197+
198+
**Service Configuration:**
199+
The setup combines built-in services-flake services with custom multiService modules:
200+
201+
**Built-in Services:**
202+
- **PostgreSQL**: Uses services-flake's postgres service with a helper function (`mkPostgresConfig`) that provides graph-specific defaults including required extensions.
203+
204+
**Custom Services** (located in `./nix/`):**
205+
- `ipfs.nix`: IPFS (kubo) with automatic initialization and configurable ports
206+
- `anvil.nix`: Ethereum test chain with deterministic configuration

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /