Skip to content

Commit 199835e

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 d034a51 commit 199835e

3 files changed

Lines changed: 348 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: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
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+
## Key Directories
10+
11+
```
12+
src/
13+
├── commands/ # 13 CLI commands (init, build, codegen, deploy, test, etc.)
14+
├── protocols/ # Multi-chain support (ethereum, near, cosmos, arweave, substreams)
15+
├── scaffold/ # Code generation for new subgraphs
16+
├── codegen/ # Type generation from ABIs and GraphQL schemas
17+
├── validation/ # Manifest and schema validation
18+
├── command-helpers/ # Shared utilities across commands
19+
├── compiler/ # WASM compilation orchestration
20+
└── migrations/ # Manifest version migrations
21+
```
22+
23+
## Commands
24+
25+
| Command | Description |
26+
|---------|-------------|
27+
| `init` | Scaffold a new subgraph |
28+
| `codegen` | Generate AssemblyScript types from schema/ABIs |
29+
| `build` | Compile subgraph to WASM |
30+
| `deploy` | Deploy to hosted service or decentralized network |
31+
| `test` | Run matchstick tests |
32+
| `create` | Create subgraph name on node |
33+
| `publish` | Publish to The Graph Network |
34+
| `add` | Add data source to manifest |
35+
| `remove` | Remove data source from manifest |
36+
| `auth` | Set deploy key |
37+
| `local` | Manage local Graph Node |
38+
| `node` | Node operations |
39+
| `clean` | Remove build artifacts |
40+
41+
## Protocol System
42+
43+
Factory pattern for multi-chain support (`src/protocols/index.ts`):
44+
45+
```typescript
46+
import Protocol from './protocols/index.js';
47+
48+
const protocol = Protocol.fromDataSources(dataSources);
49+
const manifest = protocol.getManifest();
50+
```
51+
52+
Each protocol provides:
53+
- ABI handling and type generation
54+
- Manifest schema and validation
55+
- Scaffolding templates
56+
- Chain-specific codegen
57+
58+
## Scaffolding
59+
60+
Templates in `src/scaffold/` generate:
61+
- `subgraph.yaml` manifest
62+
- `schema.graphql` entity definitions
63+
- `src/mapping.ts` event handlers
64+
- Test files
65+
66+
```typescript
67+
import Scaffold from './scaffold/index.js';
68+
69+
const scaffold = new Scaffold({
70+
protocol,
71+
network,
72+
contractName,
73+
// ...
74+
});
75+
await scaffold.generate();
76+
```
77+
78+
## Type Generation
79+
80+
`src/type-generator.ts` creates AssemblyScript classes from:
81+
- GraphQL schema -> Entity classes
82+
- Contract ABIs -> Event/Call types
83+
84+
## Development
85+
86+
```bash
87+
pnpm build # Compile TypeScript + generate oclif manifest
88+
pnpm test # Run vitest tests
89+
pnpm type-check # TypeScript type checking
90+
```
91+
92+
### Testing
93+
94+
Uses Vitest with snapshot tests in `tests/`. Key test files:
95+
- `tests/cli/init.test.ts` - Scaffolding tests
96+
- `tests/cli/validation.test.ts` - Manifest validation
97+
- `tests/cli/add.test.ts` - Data source addition
98+
99+
Run specific tests:
100+
```bash
101+
pnpm test:init
102+
pnpm test:validation
103+
```
104+
105+
## Key Patterns
106+
107+
### Command Structure
108+
109+
```typescript
110+
import { Command, Flags } from '@oclif/core';
111+
112+
export default class MyCommand extends Command {
113+
static flags = {
114+
network: Flags.string({ description: 'Network name' }),
115+
};
116+
117+
async run() {
118+
const { flags } = await this.parse(MyCommand);
119+
// ...
120+
}
121+
}
122+
```
123+
124+
### Subgraph Manifest Loading
125+
126+
```typescript
127+
import Subgraph from './subgraph.js';
128+
129+
const subgraph = await Subgraph.load('subgraph.yaml');
130+
const dataSources = subgraph.get('dataSources');
131+
```
132+
133+
## Related
134+
135+
- [packages/ts/CLAUDE.md](../ts/CLAUDE.md) - AssemblyScript library for mappings

‎packages/ts/CLAUDE.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
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 { BigInt, BigDecimal, Address, 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+
- `graph codegen` generates entity classes extending `Entity`
123+
- `graph build` compiles mappings + this library to WASM
124+
125+
## Key Patterns
126+
127+
### Result Type for Contract Calls
128+
129+
```typescript
130+
// Generated code uses ethereum.CallResult<T>
131+
let result = contract.try_someFunction();
132+
if (result.reverted) {
133+
log.warning("Call reverted", []);
134+
} else {
135+
let value = result.value;
136+
}
137+
```
138+
139+
### Dynamic Data Sources
140+
141+
```typescript
142+
import { DataSourceTemplate } from '@graphprotocol/graph-ts';
143+
144+
// Create new data source at runtime
145+
DataSourceTemplate.create("TokenTemplate", [tokenAddress.toHexString()]);
146+
```
147+
148+
## Related
149+
150+
- [packages/cli/CLAUDE.md](../cli/CLAUDE.md) - CLI for building and deploying subgraphs

0 commit comments

Comments
 (0)