|
1 | | -# CLAUDE.md |
2 | | - |
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -## Project Overview |
6 | | - |
7 | | -ev-node is a sovereign rollup framework built in Go that allows developers to build rollups on any DA layer. It provides a modular architecture where components like the data availability layer, executor, and sequencer can be plugged in. |
8 | | - |
9 | | -## Build and Development Commands |
10 | | - |
11 | | -Uses [just](https://github.com/casey/just) as the command runner. Run `just help` to list all recipes. |
12 | | - |
13 | | -### Building |
14 | | - |
15 | | -- `just build` - Builds the Testapp CLI to `./build/testapp` |
16 | | -- `just install` - Installs Testapp CLI to your Go bin directory |
17 | | -- `just build-all` - Builds all ev-node binaries |
18 | | -- `just docker-build` - Builds Docker image tagged as `evstack:local-dev` |
19 | | - |
20 | | -### Testing |
21 | | - |
22 | | -- `just test` - Runs unit tests for all go.mod files |
23 | | -- `just test-integration` - Runs integration tests (15m timeout) |
24 | | -- `just test-e2e` - Runs end-to-end tests (requires building binaries first) |
25 | | -- `just test-cover` - Generates code coverage report |
26 | | -- `just test-all` - Runs all tests including Docker E2E tests |
27 | | - |
28 | | -### Linting and Code Quality |
29 | | - |
30 | | -- `just lint` - Runs all linters (golangci-lint, markdownlint, hadolint, yamllint, goreleaser check, actionlint) |
31 | | -- `just lint-fix` - Auto-fixes linting issues where possible |
32 | | -- `just vet` - Runs go vet |
33 | | - |
34 | | -### Development Utilities |
35 | | - |
36 | | -- `just deps` - Downloads dependencies and runs go mod tidy for all modules |
37 | | -- `just proto-gen` - Generates protobuf files (requires Docker) |
38 | | -- `just mock-gen` - Generates mocks using mockery |
39 | | -- `just run-n 3` - Run multiple nodes locally (default: 1) |
40 | | - |
41 | | -## Code Architecture |
42 | | - |
43 | | -### Core Package Structure |
44 | | - |
45 | | -The project uses a zero-dependency core package pattern: |
46 | | - |
47 | | -- **core/** - Contains only interfaces and types, no external dependencies |
48 | | -- **block/** - Block management, creation, validation, and synchronization |
49 | | -- **pkg/p2p/** - Networking layer built on libp2p |
50 | | -- **pkg/sequencers/** - Modular sequencer implementations |
51 | | -- **apps/testapp/** - Reference implementation for testing |
52 | | - |
53 | | -### Key Interfaces |
54 | | - |
55 | | -- **Executor** (`core/executor.go`) - Handles state transitions |
56 | | -- **Sequencer** (`core/sequencer.go`) - Orders transactions |
57 | | -- **DA** (`pkg/da/types`) - Data availability layer abstraction |
58 | | - |
59 | | -### Modular Design |
60 | | - |
61 | | -- Each component has an interface in the core package |
62 | | -- Implementations are in separate packages |
63 | | -- Components are wired together via dependency injection |
64 | | -- Multiple go.mod files enable modular builds |
65 | | - |
66 | | -### P2P Architecture |
67 | | - |
68 | | -- Built on libp2p with GossipSub and Kademlia DHT |
69 | | -- Nodes advertise capabilities (full/light, DA layers) |
70 | | -- Automatic peer discovery with rendezvous points |
71 | | - |
72 | | -## Testing Patterns |
73 | | - |
74 | | -### Test Organization |
75 | | - |
76 | | -- Unit tests: `*_test.go` files alongside code |
77 | | -- Integration tests: `test/integration/` |
78 | | -- E2E tests: `test/e2e/` |
79 | | - |
80 | | -### Running Specific Tests |
81 | | - |
82 | | -```bash |
83 | | -# Run a single test |
84 | | -go test -run TestSpecificFunction ./package/... |
85 | | - |
86 | | -# Run with verbose output |
87 | | -go test -v ./package/... |
88 | | - |
89 | | -# Run with race detection |
90 | | -go test -race ./package/... |
91 | | -``` |
92 | | - |
93 | | -### Mock Generation |
94 | | - |
95 | | -- Mocks are defined in `.mockery.yaml` |
96 | | -- Generate with `just mock-gen` |
97 | | -- Mocks are placed in `mocks/` directories |
98 | | - |
99 | | -## Code Style Guidelines |
100 | | - |
101 | | -### Go Conventions |
102 | | - |
103 | | -- Follow standard Go formatting (enforced by golangci-lint) |
104 | | -- Use meaningful variable names |
105 | | -- Keep functions small and focused |
106 | | -- Document exported types and functions |
107 | | -- Use context.Context for cancellation |
108 | | - |
109 | | -### Error Handling |
110 | | - |
111 | | -- Wrap errors with context using `fmt.Errorf` |
112 | | -- Return errors early |
113 | | -- Use custom error types for domain-specific errors |
114 | | - |
115 | | -### Logging |
116 | | - |
117 | | -- Use structured logging (look for existing patterns) |
118 | | -- Include relevant context in log messages |
119 | | -- Use appropriate log levels |
120 | | - |
121 | | -## Common Development Tasks |
122 | | - |
123 | | -### Adding a New DA Layer |
124 | | - |
125 | | -1. Implement the `DA` interface from `pkg/da/types` |
126 | | -2. Add configuration in the appropriate config package |
127 | | -3. Wire it up in the initialization code |
128 | | -4. Add tests following existing patterns |
129 | | - |
130 | | -### Modifying Protobuf Definitions |
131 | | - |
132 | | -1. Edit `.proto` files in `types/pb/` |
133 | | -2. Run `just proto-gen` to regenerate Go code |
134 | | -3. Update any affected code |
135 | | -4. Run tests to ensure compatibility |
136 | | - |
137 | | -### Adding New Tests |
138 | | - |
139 | | -1. Place unit tests next to the code being tested |
140 | | -2. Use table-driven tests where appropriate |
141 | | -3. Mock external dependencies using mockery |
142 | | -4. Ensure tests are deterministic |
143 | | - |
144 | | -## Security Considerations |
145 | | - |
146 | | -- Never expose private keys in logs or errors |
147 | | -- Validate all inputs from external sources |
148 | | -- Use secure random number generation |
149 | | -- Follow the principle of least privilege |
150 | | -- Be careful with concurrent access to shared state |
151 | | - |
152 | | -## Performance Considerations |
153 | | - |
154 | | -- The project uses concurrent processing extensively |
155 | | -- Be mindful of goroutine leaks |
156 | | -- Use buffered channels appropriately |
157 | | -- Profile before optimizing |
158 | | -- Consider memory allocation in hot paths |
159 | | - |
160 | | -## Debugging Tips |
161 | | - |
162 | | -- Use `just run-n 2` to test multi-node scenarios locally |
163 | | -- Check logs for error messages and stack traces |
164 | | -- Use Go's built-in profiling tools for performance issues |
165 | | -- The testapp provides a simple way to test changes |
166 | | - |
167 | | -## Contributing Guidelines |
168 | | - |
169 | | -- All code must pass linting (`just lint`) |
170 | | -- All tests must pass (`just test-all`) |
171 | | -- Follow the existing code patterns |
172 | | -- Update tests when changing functionality |
173 | | -- Keep commits focused and atomic |
| 1 | +See [AGENTS.md](./AGENTS.md) |
0 commit comments