Skip to content

Commit 004a36f

Browse files
xermicusxermicus
authored
Add CLAUDE.md and update README.md (#234)
Signed-off-by: Cyrill Leutwiler <[email protected]>
1 parent 86cadb3 commit 004a36f

File tree

2 files changed

+196
-3
lines changed

2 files changed

+196
-3
lines changed

‎CLAUDE.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
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+
Revive Differential Tests is a differential testing framework for Ethereum-compatible smart contract stacks. It compiles and executes declarative smart-contract tests against multiple platforms (Geth, Revive Dev Node, Zombienet, Polkadot Omni Node) and compares their behavior (status, return data, events, state diffs).
8+
9+
The test corpus lives in a separate repository: [resolc-compiler-tests](https://github.com/paritytech/resolc-compiler-tests) and is included as a git submodule.
10+
11+
## Build and Test Commands
12+
13+
```bash
14+
# Build release binary
15+
cargo build --release
16+
17+
# Install retester and report-processor binaries
18+
cargo install --path crates/core
19+
cargo install --path crates/report-processor
20+
21+
# Run unit tests
22+
cargo make test
23+
24+
# Linting and formatting
25+
cargo make fmt-check # Check formatting
26+
cargo make clippy # Run clippy with --deny warnings
27+
cargo make machete # Check for unused dependencies
28+
```
29+
30+
## Running Differential Tests
31+
32+
### Full Test Suite (PolkaVM with Resolc)
33+
34+
This is how the polkadot-sdk CI runs tests:
35+
36+
```bash
37+
retester test \
38+
--test ./resolc-compiler-tests/fixtures/solidity/simple \
39+
--test ./resolc-compiler-tests/fixtures/solidity/complex \
40+
--test ./resolc-compiler-tests/fixtures/solidity/translated_semantic_tests \
41+
-p revive-dev-node-polkavm-resolc \
42+
--report.file-name report.json \
43+
--concurrency.number-of-nodes 10 \
44+
--concurrency.number-of-threads 10 \
45+
--concurrency.number-of-concurrent-tasks 100 \
46+
--working-directory ./workdir \
47+
--revive-dev-node.consensus manual-seal-200 \
48+
--resolc.heap-size 528000 \
49+
--resolc.stack-size 128000
50+
```
51+
52+
### Important Resolc Parameters
53+
54+
| Parameter | Default | Description |
55+
|-----------|---------|-------------|
56+
| `--resolc.heap-size` | 131072 | Emulated EVM heap memory buffer size in bytes. Increase for tests accessing large memory offsets. |
57+
| `--resolc.stack-size` | 131072 | Contract stack size in bytes. |
58+
| `--resolc.path` | (from PATH) | Path to resolc binary. |
59+
60+
**Critical:** These are **compile-time** settings embedded in the PVM bytecode. Changing them requires clearing the compilation cache (see Troubleshooting).
61+
62+
### Test Specifiers
63+
64+
```bash
65+
# Run all tests in a directory
66+
-t ./resolc-compiler-tests/fixtures/solidity/simple
67+
68+
# Run specific test file
69+
-t path/to/test.sol
70+
71+
# Run specific case within a metadata file (case_idx is 0-indexed)
72+
-t path/to/metadata.json::0
73+
74+
# Run specific case with specific mode
75+
-t path/to/metadata.json::0::Y\ M0
76+
```
77+
78+
### Report Processing
79+
80+
```bash
81+
# Generate expectations file from test report
82+
report-processor generate-expectations-file \
83+
--report-path ./workdir/report.json \
84+
--output-path expectations.json \
85+
--remove-prefix ./resolc-compiler-tests \
86+
--include-status failed
87+
```
88+
89+
## Supported Platforms
90+
91+
| Platform CLI Name | Description |
92+
|-------------------|-------------|
93+
| `geth-evm-solc` | Go-Ethereum reference EVM + Solc |
94+
| `lighthouse-geth-evm-solc` | Geth with Lighthouse consensus + Solc |
95+
| `revive-dev-node-polkavm-resolc` | Substrate PolkaVM + Resolc |
96+
| `revive-dev-node-revm-solc` | Substrate REVM + Solc |
97+
| `zombienet-polkavm-resolc` | Zombienet Substrate + Resolc |
98+
| `zombienet-revm-solc` | Zombienet REVM + Solc |
99+
| `polkadot-omni-node-polkavm-resolc` | Polkadot Omni Node + Resolc |
100+
| `polkadot-omni-node-revm-solc` | Polkadot Omni Node + Solc |
101+
102+
## Architecture
103+
104+
The project is a Rust workspace (edition 2024, MSRV 1.87.0) with crates in `/crates/`:
105+
106+
- **core** (`retester` binary) - Main test runner and orchestrator
107+
- **config** - CLI argument parsing via Clap; defines `Context` enum (Test, Benchmark, ExportJsonSchema, ExportGenesis)
108+
- **format** - Declarative test definition format based on MatterLabs; includes `gas_overrides` support for platform-specific gas limits
109+
- **common** - Shared types including `PlatformIdentifier`, `ParsedTestSpecifier`, `Mode`, `ParsedMode`
110+
- **compiler** - Compilation abstraction for Solc and Resolc compilers
111+
- `revive_resolc.rs`: Uses `SolcStandardJsonInputSettingsSelection::new_required_for_tests()` to request `evm.bytecode` output (required for resolc 0.6.0+)
112+
- **node** - Platform/node implementations in `src/node_implementations/`
113+
- **node-interaction** - Transaction submission, gas estimation via alloy, receipt waiting
114+
- `fallback_gas_filler.rs`: Handles gas estimation for reverting transactions using debug traces
115+
- **report** - Test result aggregation and reporting (JSON format)
116+
- **report-processor** - Secondary binary for post-execution report analysis
117+
- **solc-binaries** - Solc compiler binary caching and downloads
118+
119+
## Test Format
120+
121+
Tests use the MatterLabs format with metadata either as JSON files or inline Solidity comments:
122+
123+
```
124+
Corpus (directory)
125+
└── Metadata (JSON file or Solidity with inline comments)
126+
└── Case (individual test)
127+
├── targets (optional): filter to specific platforms
128+
├── modes (optional): restrict to specific compiler modes (e.g., ["E-"] for EVM assembly only)
129+
├── gas_overrides (optional): platform-specific hardcoded gas limits
130+
└── Steps
131+
├── Transaction steps with assertions
132+
└── State assertions (balances, storage)
133+
```
134+
135+
### Gas Overrides
136+
137+
For tests that fail gas estimation (e.g., due to `consume_all_gas` behavior in resolc), use `gas_overrides`:
138+
139+
```json
140+
{
141+
"method": "test",
142+
"calldata": ["0x100000000"],
143+
"gas_overrides": {
144+
"revive-dev-node-polkavm-resolc": {
145+
"gas_limit": 10000000
146+
}
147+
}
148+
}
149+
```
150+
151+
## External Dependencies
152+
153+
**Always required:**
154+
- Solc (Solidity compiler) - auto-downloaded but resolc needs it in PATH
155+
156+
**Platform-specific:**
157+
| Platform | Required Tools |
158+
|----------|----------------|
159+
| `geth-evm-solc` | Geth |
160+
| `lighthouse-geth-evm-solc` | Geth, Kurtosis, Docker |
161+
| `revive-dev-node-*` | revive-dev-node, eth-rpc |
162+
| `zombienet-*` | Zombienet SDK binaries |
163+
| `polkadot-omni-node-*` | polkadot-omni-node, eth-rpc |
164+
165+
**For PolkaVM platforms:** Resolc compiler
166+
167+
## Troubleshooting
168+
169+
### Clearing the Compilation Cache
170+
171+
Compilation artifacts are cached in the working directory. If you change compiler settings (like `--resolc.heap-size`), you must clear the cache:
172+
173+
```bash
174+
rm -rf ./workdir
175+
```
176+
177+
### Common Issues
178+
179+
1. **"Failed to find information for contract"** - The resolc output selection doesn't include bytecode. Ensure `crates/compiler/src/revive_resolc.rs` uses `new_required_for_tests()` instead of `new_required()`.
180+
181+
2. **"OutOfGas" errors on tests with large memory offsets** - Increase `--resolc.heap-size` (e.g., to 528000) and clear the compilation cache.
182+
183+
3. **"ContractTrapped" on memory access** - The contract is accessing memory beyond the configured heap size. Increase `--resolc.heap-size`.
184+
185+
4. **Tests failing after changing resolc parameters** - Clear the compilation cache (`rm -rf ./workdir`) to force recompilation.
186+
187+
5. **Gas estimation failures for reverting transactions** - The test may need `gas_overrides` in the test metadata to specify a hardcoded gas limit.
188+
189+
## Updating the Test Submodule
190+
191+
```bash
192+
git submodule update --init --remote resolc-compiler-tests
193+
```

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,15 @@ All of the above need to be installed and available in the path in order for the
5050

5151
## Running The Tool
5252

53-
This tool is being updated quite frequently. Therefore, it's recommended that you don't install the tool and then run it, but rather that you run it from the root of the directory using `cargo run --release`. The help command of the tool gives you all of the information you need to know about each of the options and flags that the tool offers.
53+
This tool is being updated quite frequently. Therefore, it's recommended that you don't install the tool and then run it, but rather that you run it from the root of the directory using `cargo run --release --bin retester`. The help command of the tool gives you all of the information you need to know about each of the options and flags that the tool offers.
5454

5555
> [!NOTE]
5656
> Note that the tests can be found in the [`resolc-compiler-tests`](https://github.com/paritytech/resolc-compiler-tests) repository.
5757
5858
The simplest command to run this tool is the following:
5959

6060
```bash
61-
RUST_LOG="info" cargo run --release -- test \
61+
RUST_LOG="info" cargo run --release --bin retester -- test \
6262
--test ./resolc-compiler-tests/fixtures/solidity \
6363
--platform geth-evm-solc \
6464
--working-directory workdir \
@@ -109,7 +109,7 @@ sleep 5
109109
# Run the tests (logs to files as before)
110110
RUST_LOG="info" retester test \
111111
--platform "$PLATFORM" \
112-
--corpus ./revive-differential-tests/fixtures/solidity \
112+
--test ./resolc-compiler-tests/fixtures/solidity \
113113
--working-directory ./workdir \
114114
--concurrency.number-of-nodes 1 \
115115
--concurrency.number-of-concurrent-tasks 5 \

0 commit comments

Comments
 (0)