Skip to content

Commit d6e3d64

Browse files
lutterclaude
lutter
and
claude
committed
docs: add CLAUDE.md files for AI-assisted development
Add documentation files to help Claude (and developers) understand the codebase structure, key patterns, and development workflows. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent d20d00a commit d6e3d64

3 files changed

Lines changed: 371 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# The Graph Protocol Tooling Monorepo
2+
3+
Tools for building and deploying subgraphs on The Graph Network.
4+
5+
## Packages
6+
7+
| Package | Description | Docs |
8+
| -------------------------- | ------------------------------------ | ------------------------------------------------ |
9+
| `@graphprotocol/graph-cli` | CLI for init, codegen, build, deploy | [packages/cli/CLAUDE.md](packages/cli/CLAUDE.md) |
10+
| `@graphprotocol/graph-ts` | AssemblyScript library for mappings | [packages/ts/CLAUDE.md](packages/ts/CLAUDE.md) |
11+
12+
## Development Setup
13+
14+
```bash
15+
# Requirements: Node.js 20+, pnpm 10
16+
pnpm install
17+
pnpm build
18+
```
19+
20+
## Common Commands
21+
22+
```bash
23+
# Build all packages
24+
pnpm build
25+
26+
# Run tests
27+
pnpm test # All packages
28+
pnpm test:cli # CLI only
29+
pnpm test:ts # graph-ts only
30+
31+
# Code quality
32+
pnpm lint # Check formatting + linting
33+
pnpm lint:fix # Auto-fix issues
34+
pnpm type-check # TypeScript type checking
35+
```
36+
37+
## Code Style
38+
39+
- ESLint with `@theguild/eslint-config`
40+
- Prettier with `@theguild/prettier-config`
41+
- TypeScript strict mode
42+
43+
## Release Process
44+
45+
Uses [Changesets](https://github.com/changesets/changesets) for versioning:
46+
47+
```bash
48+
# Add a changeset for your changes
49+
pnpm changeset
50+
51+
# Release (builds + publishes)
52+
pnpm release
53+
```
54+
55+
## Project Structure
56+
57+
```
58+
├── packages/
59+
│ ├── cli/ # @graphprotocol/graph-cli
60+
│ └── ts/ # @graphprotocol/graph-ts
61+
├── patches/ # pnpm patches for dependencies
62+
└── .changeset/ # Changesets configuration
63+
```

‎packages/cli/CLAUDE.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# @graphprotocol/graph-cli
2+
3+
CLI for building and deploying subgraphs to The Graph Network.
4+
5+
## Architecture
6+
7+
Built on [oclif](https://oclif.io/) command framework. Entry point: `bin/run.js` -> `dist/commands/`.
8+
9+
## gnd dispatch
10+
11+
By default, `graph <cmd>` execs `gnd <cmd>` (the Rust `@graphprotocol/gnd`
12+
binary). Exceptions:
13+
14+
- `graph local` always runs the TypeScript implementation — gnd has no
15+
equivalent command.
16+
- `graph dev` is an oclif shim that spawns `gnd dev`, so the command is
17+
discoverable from `graph --help` even when running in TS mode.
18+
19+
Set `GRAPH_CLI_IGNORE_GND=1` to force every command through the oclif/TS
20+
implementation. The test suite sets this automatically via
21+
`tests/cli/globalSetup.ts`.
22+
23+
The dispatch lives in `bin/run.js` and shares the spawn helper in
24+
`src/command-helpers/gnd.ts` with `src/commands/dev.ts`.
25+
26+
## Key Directories
27+
28+
```
29+
src/
30+
├── commands/ # 13 CLI commands (init, build, codegen, deploy, test, etc.)
31+
├── protocols/ # Multi-chain support (ethereum, near, cosmos, arweave, substreams)
32+
├── scaffold/ # Code generation for new subgraphs
33+
├── codegen/ # Type generation from ABIs and GraphQL schemas
34+
├── validation/ # Manifest and schema validation
35+
├── command-helpers/ # Shared utilities across commands
36+
├── compiler/ # WASM compilation orchestration
37+
└── migrations/ # Manifest version migrations
38+
```
39+
40+
## Commands
41+
42+
| Command | Description |
43+
| --------- | ----------------------------------------------------------- |
44+
| `init` | Scaffold a new subgraph |
45+
| `codegen` | Generate AssemblyScript types from schema/ABIs |
46+
| `build` | Compile subgraph to WASM |
47+
| `deploy` | Deploy to hosted service or decentralized network |
48+
| `test` | Run matchstick tests |
49+
| `create` | Create subgraph name on node |
50+
| `publish` | Publish to The Graph Network |
51+
| `add` | Add data source to manifest |
52+
| `remove` | Remove data source from manifest |
53+
| `auth` | Set deploy key |
54+
| `local` | Manage local Graph Node (always TS — gnd has no equivalent) |
55+
| `dev` | Run graph-node in dev mode (delegates to `gnd dev`) |
56+
| `clean` | Remove build artifacts |
57+
58+
## Protocol System
59+
60+
Factory pattern for multi-chain support (`src/protocols/index.ts`):
61+
62+
```typescript
63+
import Protocol from './protocols/index.js'
64+
65+
const protocol = Protocol.fromDataSources(dataSources)
66+
const manifest = protocol.getManifest()
67+
```
68+
69+
Each protocol provides:
70+
71+
- ABI handling and type generation
72+
- Manifest schema and validation
73+
- Scaffolding templates
74+
- Chain-specific codegen
75+
76+
## Scaffolding
77+
78+
Templates in `src/scaffold/` generate:
79+
80+
- `subgraph.yaml` manifest
81+
- `schema.graphql` entity definitions
82+
- `src/mapping.ts` event handlers
83+
- Test files
84+
85+
```typescript
86+
import Scaffold from './scaffold/index.js'
87+
88+
const scaffold = new Scaffold({
89+
protocol,
90+
network,
91+
contractName
92+
// ...
93+
})
94+
await scaffold.generate()
95+
```
96+
97+
## Type Generation
98+
99+
`src/type-generator.ts` creates AssemblyScript classes from:
100+
101+
- GraphQL schema -> Entity classes
102+
- Contract ABIs -> Event/Call types
103+
104+
## Development
105+
106+
```bash
107+
pnpm build # Compile TypeScript + generate oclif manifest
108+
pnpm test # Run vitest tests
109+
pnpm type-check # TypeScript type checking
110+
```
111+
112+
### Testing
113+
114+
Uses Vitest with snapshot tests in `tests/`. Key test files:
115+
116+
- `tests/cli/init.test.ts` - Scaffolding tests
117+
- `tests/cli/validation.test.ts` - Manifest validation
118+
- `tests/cli/add.test.ts` - Data source addition
119+
120+
Run specific tests:
121+
122+
```bash
123+
pnpm test:init
124+
pnpm test:validation
125+
```
126+
127+
## Key Patterns
128+
129+
### Command Structure
130+
131+
```typescript
132+
import { Command, Flags } from '@oclif/core'
133+
134+
export default class MyCommand extends Command {
135+
static flags = {
136+
network: Flags.string({ description: 'Network name' })
137+
}
138+
139+
async run() {
140+
const { flags } = await this.parse(MyCommand)
141+
// ...
142+
}
143+
}
144+
```
145+
146+
### Subgraph Manifest Loading
147+
148+
```typescript
149+
import Subgraph from './subgraph.js'
150+
151+
const subgraph = await Subgraph.load('subgraph.yaml')
152+
const dataSources = subgraph.get('dataSources')
153+
```
154+
155+
## Related
156+
157+
- [packages/ts/CLAUDE.md](../ts/CLAUDE.md) - AssemblyScript library for mappings

‎packages/ts/CLAUDE.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# @graphprotocol/graph-ts
2+
3+
AssemblyScript library for writing subgraph mappings. Imported by generated mapping code.
4+
5+
## Architecture
6+
7+
This library provides types and host interfaces that compile to WASM and run in graph-node. Uses AssemblyScript (TypeScript-like syntax targeting WebAssembly).
8+
9+
## Key Directories
10+
11+
```
12+
├── chain/ # Blockchain-specific types
13+
│ ├── ethereum.ts # Ethereum blocks, transactions, events, calls
14+
│ ├── near.ts # NEAR receipts, actions
15+
│ ├── cosmos.ts # Cosmos events, transactions
16+
│ ├── arweave.ts # Arweave blocks, transactions
17+
│ └── starknet.ts # Starknet events, transactions
18+
├── common/ # Core types
19+
│ ├── numbers.ts # BigInt, BigDecimal, Address
20+
│ ├── collections.ts # ByteArray, Bytes, Entity, TypedMap
21+
│ ├── value.ts # Value union type for store operations
22+
│ ├── json.ts # JSON parsing
23+
│ └── datasource.ts # Dynamic data source creation
24+
├── global/ # TypeId enum for WASM runtime
25+
└── index.ts # Re-exports + host namespace declarations
26+
```
27+
28+
## Core Types
29+
30+
```typescript
31+
import { Address, BigDecimal, BigInt, Bytes, Entity } from '@graphprotocol/graph-ts'
32+
33+
// Number types
34+
let amount = BigInt.fromI32(100)
35+
let price = BigDecimal.fromString('1.5')
36+
37+
// Address (20 bytes)
38+
let addr = Address.fromString('0x...')
39+
40+
// Binary data
41+
let data = Bytes.fromHexString('0xabcd')
42+
```
43+
44+
## Host Interfaces
45+
46+
Declared as namespaces that map to graph-node host functions:
47+
48+
```typescript
49+
// Entity storage
50+
store.get(entity, id)
51+
store.set(entity, id, data)
52+
store.remove(entity, id)
53+
54+
// Logging
55+
log.info('Value: {}', [value.toString()])
56+
log.warning('Issue: {}', [msg])
57+
log.error('Failed: {}', [err])
58+
59+
// IPFS access
60+
ipfs.cat(hash)
61+
62+
// Cryptography
63+
crypto.keccak256(input)
64+
65+
// ENS lookups
66+
ens.nameByHash(hash)
67+
```
68+
69+
## Entity Pattern
70+
71+
Entities implement the `Entity` interface for store operations:
72+
73+
```typescript
74+
class Transfer extends Entity {
75+
constructor(id: string) {
76+
super()
77+
this.set('id', Value.fromString(id))
78+
}
79+
80+
save(): void {
81+
store.set('Transfer', this.get('id')!.toString(), this)
82+
}
83+
84+
static load(id: string): Transfer | null {
85+
return changetype<Transfer | null>(store.get('Transfer', id))
86+
}
87+
}
88+
```
89+
90+
## Ethereum Types
91+
92+
```typescript
93+
import { ethereum } from '@graphprotocol/graph-ts'
94+
95+
// In event handler
96+
export function handleTransfer(event: ethereum.Event): void {
97+
let block = event.block // ethereum.Block
98+
let tx = event.transaction // ethereum.Transaction
99+
let receipt = event.receipt // ethereum.TransactionReceipt | null
100+
let logIndex = event.logIndex // BigInt
101+
}
102+
103+
// Contract calls
104+
let result = contract.try_balanceOf(address)
105+
if (!result.reverted) {
106+
let balance = result.value
107+
}
108+
```
109+
110+
## Build
111+
112+
Compiles to WASM via AssemblyScript:
113+
114+
```bash
115+
pnpm build # Outputs index.wasm
116+
pnpm test # Run tests
117+
```
118+
119+
## Relationship to CLI
120+
121+
The `@graphprotocol/graph-cli` package generates code that imports from this library:
122+
123+
- `graph codegen` generates entity classes extending `Entity`
124+
- `graph build` compiles mappings + this library to WASM
125+
126+
## Key Patterns
127+
128+
### Result Type for Contract Calls
129+
130+
```typescript
131+
// Generated code uses ethereum.CallResult<T>
132+
let result = contract.try_someFunction()
133+
if (result.reverted) {
134+
log.warning('Call reverted', [])
135+
} else {
136+
let value = result.value
137+
}
138+
```
139+
140+
### Dynamic Data Sources
141+
142+
```typescript
143+
import { DataSourceTemplate } from '@graphprotocol/graph-ts'
144+
145+
// Create new data source at runtime
146+
DataSourceTemplate.create('TokenTemplate', [tokenAddress.toHexString()])
147+
```
148+
149+
## Related
150+
151+
- [packages/cli/CLAUDE.md](../cli/CLAUDE.md) - CLI for building and deploying subgraphs

0 commit comments

Comments
 (0)