Skip to content

Commit aea7ba0

Browse files
10d9e10d9e
committed
feat: Add comprehensive documentation for CLAUDE, cross-platform build guide, and dependencies
- Introduced CLAUDE.md to provide guidance on project structure, build commands, and architecture. - Created CROSS_PLATFORM.md detailing build instructions for macOS, Linux, and Windows, including dependency management. - Added DEPENDENCIES.md outlining required external libraries for EVM precompile support and installation instructions. - Ensured documentation covers testing strategies, common tasks, and troubleshooting for a smoother development experience.
1 parent 5b4f1e2 commit aea7ba0

File tree

3 files changed

+744
-0
lines changed

3 files changed

+744
-0
lines changed

‎CLAUDE.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
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+
ZEVM is a high-performance Ethereum Virtual Machine (EVM) implementation written in Zig. It is a port of the Rust [revm](https://github.com/bluealloy/revm) implementation, providing:
8+
9+
1. **Complete EVM Implementation**: Full support for Ethereum protocol up to Prague hardfork
10+
2. **Production-Ready Precompiles**: All 18 standard Ethereum precompiled contracts implemented
11+
3. **Cross-Platform Support**: Works on macOS, Linux, and Windows with static linking
12+
4. **Type-Safe Design**: Leverages Zig's compile-time guarantees for safety and performance
13+
14+
The project maintains **100% feature parity** with the Rust revm reference implementation, verified through comprehensive testing and comparison.
15+
16+
## Build and Development Commands
17+
18+
### Essential Commands
19+
20+
```bash
21+
# Build using Makefile (recommended - auto-detects OS and installs deps)
22+
make
23+
make build # Build only
24+
make install-deps # Install dependencies only
25+
make test # Run all tests
26+
make clean # Clean build artifacts
27+
28+
# Manual Zig build commands
29+
zig build # Build all targets
30+
zig build test # Run tests
31+
zig build -Dblst=false # Build without blst library
32+
zig build -Dmcl=false # Build without mcl library
33+
34+
# Build specific examples
35+
zig build precompile_example
36+
zig build zevm-test
37+
zig build zevm-bench
38+
```
39+
40+
### Platform-Specific Notes
41+
42+
- **macOS**: Uses Homebrew for dependencies (`/opt/homebrew/include`)
43+
- **Linux**: Uses apt-get/dnf for dependencies (`/usr/local/include`)
44+
- **Windows**: Uses vcpkg (see CROSS_PLATFORM.md)
45+
46+
The Makefile automatically detects the OS and installs dependencies accordingly.
47+
48+
## Architecture
49+
50+
The project follows a modular architecture mirroring revm's structure:
51+
52+
### Core Modules
53+
54+
- **`src/primitives/`**: Core types (U256, Address, Hash), constants, and hardfork definitions
55+
- **`src/bytecode/`**: Opcode definitions, bytecode analysis, and EIP-7702 support
56+
- **`src/state/`**: Account info, storage, and state transitions
57+
- **`src/database/`**: Pluggable database interface with in-memory implementation
58+
- **`src/context/`**: Block, transaction, and configuration management
59+
- **`src/interpreter/`**: Stack-based EVM interpreter with gas tracking
60+
- **`src/precompile/`**: All 18 Ethereum precompiled contracts
61+
- **`src/handler/`**: Transaction execution orchestration
62+
- **`src/inspector/`**: Debugging and profiling tools
63+
64+
### Key Design Patterns
65+
66+
1. **Modular Structure**: Each module is self-contained with a `main.zig` entry point
67+
2. **Static Linking**: All crypto libraries (`blst`, `mcl`) are statically linked for self-contained binaries
68+
3. **Spec-Based Execution**: Hardfork support via `SpecId` enum, with precompiles adapting gas costs per spec
69+
4. **Error Handling**: Uses Zig's error union types (`PrecompileError`, `InstructionResult`, etc.)
70+
5. **Memory Safety**: Leverages Zig's memory management (no GC, explicit allocators)
71+
72+
### Important Interfaces
73+
74+
1. **PrecompileId**: Union enum identifying precompiles, supports Custom variants
75+
2. **PrecompileSpecId**: Enum for hardfork specs (Homestead, Byzantium, Istanbul, Berlin, Cancun, Prague, Osaka)
76+
3. **Database Interface**: Pluggable state storage (see `src/database/main.zig`)
77+
4. **Inspector Interface**: Hooks for transaction tracing and debugging
78+
5. **Context**: Manages execution state, environment, and configuration
79+
80+
## Precompiles
81+
82+
All 18 standard Ethereum precompiles are implemented:
83+
84+
### Core Precompiles
85+
- **Identity** (0x04): Data copy
86+
- **SHA256** (0x02): SHA-256 hash function
87+
- **RIPEMD160** (0x03): RIPEMD-160 hash function
88+
- **ECRECOVER** (0x01): Elliptic curve signature recovery (libsecp256k1)
89+
90+
### Advanced Precompiles
91+
- **ModExp** (0x05): Modular exponentiation (Byzantium/Berlin/Osaka variants)
92+
- **BN254** (0x06-0x08): BN254 curve operations (mcl library)
93+
- **Blake2F** (0x09): Blake2 compression function
94+
- **KZG Point Evaluation** (0x0A): KZG commitment verification (blst library)
95+
- **BLS12-381** (0x0B-0x11): All 7 BLS12-381 precompiles (blst library)
96+
- **P256Verify** (0x100): secp256r1 signature verification (OpenSSL)
97+
98+
### Precompile Features
99+
100+
- **PrecompileId.name()**: Returns EIP-7910 standardized names
101+
- **PrecompileId.precompile()**: Gets spec-appropriate precompile implementation
102+
- **PrecompileId.Custom**: Support for custom precompile identifiers
103+
- **Gas Cost Adaptation**: Precompiles automatically adjust gas costs based on hardfork
104+
105+
## Dependencies
106+
107+
### Required External Libraries
108+
109+
1. **libsecp256k1**: ECRECOVER precompile (typically via package manager)
110+
2. **OpenSSL**: P256Verify precompile (typically via package manager)
111+
3. **blst**: BLS12-381 and KZG operations (built from source or installed)
112+
4. **mcl**: BN254 operations (built from source or installed)
113+
114+
### Dependency Management
115+
116+
- **Makefile**: Automatically installs dependencies via OS-specific package managers
117+
- **build.zig**: Handles linking and include paths for all libraries
118+
- **Static Linking**: All binaries statically link `blst` and `mcl` for portability
119+
- **Fallback**: Libraries can be disabled with `-Dblst=false` or `-Dmcl=false`
120+
121+
See `CROSS_PLATFORM.md` and `DEPENDENCIES.md` for detailed installation instructions.
122+
123+
## Reference Implementation
124+
125+
This project is a port of **revm** (Rust EVM). When implementing new features:
126+
127+
1. **Check revm first**: Look at `revm/crates/` for reference implementation
128+
2. **Maintain parity**: Ensure behavior matches revm exactly
129+
3. **Test vectors**: Use Ethereum test suite and revm's test cases
130+
4. **Documentation**: See `PRECOMPILE_FEATURE_PARITY.md` for comparison
131+
132+
### Key Differences from Rust
133+
134+
- **Memory Management**: Zig uses explicit allocators, no RAII
135+
- **Error Handling**: Zig error unions vs Rust Result types
136+
- **Generics**: Zig uses `comptime` for compile-time polymorphism
137+
- **Pattern Matching**: Zig uses `switch` expressions instead of `match`
138+
139+
## Testing Strategy
140+
141+
1. **Unit Tests**: Each module has comprehensive unit tests (`src/precompile/tests.zig`)
142+
2. **Integration Tests**: Full EVM execution tests (`src/test.zig`)
143+
3. **Precompile Tests**: 73+ unit tests covering all precompiles
144+
4. **Gas Cost Verification**: Tests verify gas costs match revm exactly
145+
5. **Cross-Platform**: CI runs tests on both Ubuntu and macOS
146+
147+
### Running Tests
148+
149+
```bash
150+
make test # Run all tests via Makefile
151+
zig build test # Run tests via Zig build system
152+
zig test src/test.zig # Run specific test file
153+
```
154+
155+
## Important Files
156+
157+
### Build System
158+
- **`build.zig`**: Main Zig build configuration, handles library linking
159+
- **`Makefile`**: Cross-platform build automation and dependency management
160+
- **`src/version.zig`**: Version information and release metadata
161+
162+
### Documentation
163+
- **`README.md`**: Main project documentation
164+
- **`CHANGELOG.md`**: Version history and changes
165+
- **`RELEASE_NOTES.md`**: Detailed release notes
166+
- **`CROSS_PLATFORM.md`**: Platform-specific build instructions
167+
- **`DEPENDENCIES.md`**: Dependency installation guide
168+
- **`PRECOMPILE_FEATURE_PARITY.md`**: Comparison with revm implementation
169+
170+
### Reference Implementation
171+
- **`revm/`**: Rust reference implementation (submodule or copy)
172+
- Used for understanding behavior and maintaining parity
173+
174+
## Code Conventions
175+
176+
### Naming
177+
- **Modules**: `snake_case` for file names (`main.zig`, `secp256k1.zig`)
178+
- **Types**: `PascalCase` for structs, enums, unions (`PrecompileId`, `PrecompileResult`)
179+
- **Functions**: `camelCase` for public functions (`precompile`, `execute`)
180+
- **Constants**: `UPPER_SNAKE_CASE` for module-level constants (`P256VERIFY`, `BYZANTIUM`)
181+
182+
### Error Handling
183+
- Use Zig error unions: `PrecompileResult = union(enum) { success: PrecompileOutput, err: PrecompileError }`
184+
- Return errors explicitly: `return PrecompileResult{ .err = PrecompileError.OutOfGas }`
185+
- Use `try` for error propagation
186+
187+
### Memory Management
188+
- Use explicit allocators: `std.heap.c_allocator` for global, or pass allocators to functions
189+
- Prefer stack allocation when possible
190+
- Use `std.ArrayList` for dynamic arrays
191+
192+
### Precompile Implementation Pattern
193+
194+
```zig
195+
// Define precompile constant
196+
pub const PRECOMPILE = main.Precompile.new(
197+
main.PrecompileId.Sha256,
198+
main.u64ToAddress(2),
199+
sha256Run,
200+
);
201+
202+
// Implementation function
203+
pub fn sha256Run(input: []const u8, gas_limit: u64) main.PrecompileResult {
204+
const gas_cost = main.calcLinearCost(input.len, 60, 12);
205+
if (gas_cost > gas_limit) {
206+
return main.PrecompileResult{ .err = main.PrecompileError.OutOfGas };
207+
}
208+
// ... implementation
209+
return main.PrecompileResult{ .success = main.PrecompileOutput.new(gas_cost, result) };
210+
}
211+
```
212+
213+
## Current Development Context
214+
215+
### Recent Changes (v0.3.1)
216+
- Fixed ModExp Osaka gas calculation to match EIP-7883
217+
- Fixed EIP-7823 input size limits (1024 bytes)
218+
- Added PrecompileId.Custom variant and convenience methods
219+
- Verified Fusaka upgrade parity with revm
220+
221+
### Ongoing Maintenance
222+
- Maintain feature parity with revm
223+
- Keep up with Ethereum hardfork changes
224+
- Ensure cross-platform compatibility
225+
- Optimize performance where possible
226+
227+
## Common Tasks
228+
229+
### Adding a New Precompile
230+
1. Create implementation file in `src/precompile/`
231+
2. Add PrecompileId variant in `src/precompile/main.zig`
232+
3. Register in appropriate spec in `Precompiles.forSpec()`
233+
4. Add tests in `src/precompile/tests.zig`
234+
5. Update `PRECOMPILE_FEATURE_PARITY.md`
235+
236+
### Updating Gas Costs
237+
1. Check revm implementation for reference
238+
2. Update gas calculation function
239+
3. Add tests for new gas costs
240+
4. Verify against Ethereum test suite
241+
242+
### Fixing Cross-Platform Issues
243+
1. Check `build.zig` for platform-specific logic
244+
2. Update `Makefile` if needed
245+
3. Test on target platform
246+
4. Update `CROSS_PLATFORM.md` if instructions change
247+
248+
## Getting Help
249+
250+
- **Reference Implementation**: Check `revm/crates/` for Rust implementation
251+
- **Ethereum Specs**: See EIPs and Ethereum execution specs
252+
- **Zig Documentation**: https://ziglang.org/documentation/
253+
- **Build Issues**: See `CROSS_PLATFORM.md` and `DEPENDENCIES.md`
254+

0 commit comments

Comments
 (0)
⚡