Skip to content

Commit ca596c1

Browse files
mHaines9219cdrappi
mHaines9219
and
cdrappi
authored
chore: add CLAUDE.md with build, test, and architecture reference (#126)
Co-authored-by: Christian Drappi <christiandrappi@gmail.com>
1 parent fbd8fb9 commit ca596c1

1 file changed

Lines changed: 256 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# Summit
2+
3+
High-performance consensus client for EVM-based blockchains, built by [Seismic Systems](https://github.com/SeismicSystems). Uses the [Simplex consensus protocol](https://eprint.iacr.org/2023/463) for sub-second block finality. Communicates with any EVM execution client (Reth, Geth) via the Engine API.
4+
5+
## Commonware
6+
7+
[Commonware](https://commonware.xyz) is Summit's core infrastructure layer. Summit depends on 12 Commonware crates (version pinned in root `Cargo.toml`). Nearly every component in Summit is built on top of Commonware primitives.
8+
9+
| Crate | What it provides |
10+
| --- | --- |
11+
| `commonware-consensus` | Simplex BFT protocol — leader election, notarization (2/3+1), finalization |
12+
| `commonware-cryptography` | BLS12-381 multisig, Ed25519 identity, SHA256 hashing |
13+
| `commonware-runtime` | Async runtime abstractions — Clock, Spawner, Metrics, Signal/Stopper |
14+
| `commonware-storage` | QMDB key-value store, immutable & prunable archives |
15+
| `commonware-p2p` | Authenticated P2P connections, peer management, simulated network for tests |
16+
| `commonware-broadcast` | Buffered reliable broadcast between validators |
17+
| `commonware-codec` | Streaming encode/decode for blocks, checkpoints, and messages |
18+
| `commonware-resolver` | Request-response backfill for missing blocks from peers |
19+
| `commonware-utils` | Channels (mpsc, oneshot), ordered sets, byte utilities, non-zero types |
20+
| `commonware-macros` | `select!`/`select_loop!` async macros, `test_traced!` for instrumented tests |
21+
| `commonware-math` | Cryptographic randomness for key generation |
22+
| `commonware-parallel` | Sequential/parallel processing strategies |
23+
24+
Summit integrates with Simplex by implementing Commonware's `Automaton` and `Relay` traits (see `application/src/actor.rs`). The orchestrator spawns Simplex engines per epoch, and all inter-actor communication uses Commonware channels and async primitives.
25+
26+
### Commonware MCP Server
27+
28+
Commonware provides an MCP server for querying its library documentation directly from Claude Code. Add it with:
29+
30+
```bash
31+
claude mcp add --transport http commonware-library https://mcp.commonware.xyz
32+
```
33+
34+
This gives Claude Code searchable access to Commonware docs — useful when working with Simplex, QMDB, P2P, codec, or any other Commonware crate.
35+
36+
## Build
37+
38+
Rust workspace (edition 2024) with toolchain pinned in `rust-toolchain.toml`. The toolchain auto-installs on first build.
39+
40+
### macOS (arm64/x86_64)
41+
42+
```bash
43+
cargo build # debug
44+
cargo build --release # release
45+
```
46+
47+
### Linux (Ubuntu)
48+
49+
```bash
50+
sudo apt-get update
51+
sudo apt-get install -y build-essential pkg-config libssl-dev
52+
cargo build
53+
```
54+
55+
### Verify
56+
57+
```bash
58+
target/debug/summit --help
59+
# Usage: summit <COMMAND>
60+
# Commands: run, keys, help
61+
```
62+
63+
## Test
64+
65+
### Unit & integration tests (153 tests)
66+
67+
```bash
68+
cargo test # default features — 153 tests
69+
cargo test --all-features # includes e2e test harness — 170 tests
70+
```
71+
72+
Test breakdown by crate:
73+
74+
- `summit` (node): 40 tests (syncer, checkpointing, execution requests, deposits, withdrawals)
75+
- `summit-finalizer`: 19 tests (validator lifecycle, fork handling, state queries)
76+
- `summit-syncer`: 11 tests
77+
- `summit-types`: 75 tests (codec, consensus state, headers, withdrawals, protocol params)
78+
- `summit-rpc`: 8 integration tests
79+
80+
### CI checks (must pass before PR)
81+
82+
```bash
83+
cargo +nightly fmt --all --check # formatting (nightly rustfmt)
84+
RUSTFLAGS="-D warnings" cargo check # no warnings (default features)
85+
RUSTFLAGS="-D warnings" cargo check --all-features # no warnings (all features)
86+
```
87+
88+
### Benchmarks
89+
90+
```bash
91+
cargo bench -p summit-finalizer # consensus_state_write benchmark
92+
```
93+
94+
## Local Testnet
95+
96+
The `testnet` binary spins up a multi-node network locally — this is the main way to test end-to-end during development.
97+
98+
### Prerequisites
99+
100+
- A binary named `reth` must be in PATH. If using [seismic-reth](https://github.com/SeismicSystems/seismic-reth), the build produces a `seismic-reth` binary — symlink or copy it as `reth`:
101+
```bash
102+
ln -s /path/to/seismic-reth ~/.cargo/bin/reth
103+
```
104+
105+
### Quick start
106+
107+
```bash
108+
cargo run --bin testnet
109+
```
110+
111+
This starts 4 Reth execution nodes + 4 Summit consensus validators, all wired together via Engine API over IPC.
112+
113+
### CLI flags
114+
115+
| Flag | Default | Description |
116+
| --- | --- | --- |
117+
| `--nodes <N>` | 4 | Number of nodes to run |
118+
| `--only-reth` | off | Start only Reth execution nodes (no consensus) |
119+
| `--log-dir <PATH>` | none | Write per-node logs (`node0.log`, `node1.log`, ...) |
120+
121+
### Port layout (default 4 nodes)
122+
123+
| Service | Ports |
124+
| --- | --- |
125+
| Reth RPC | 8545, 8546, 8547, 8548 |
126+
| Summit RPC | 3030, 3040, 3050, 3060 |
127+
| P2P | 26600, 26610, 26620, 26630 |
128+
| Engine API IPC | `/tmp/reth_engine_api{0-3}.ipc` |
129+
130+
### Interact with the network
131+
132+
```bash
133+
curl -X POST http://localhost:8545 \
134+
-H "Content-Type: application/json" \
135+
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
136+
```
137+
138+
### Reset state
139+
140+
```bash
141+
cd testnet && ./reset.sh
142+
```
143+
144+
### Config files (`testnet/`)
145+
146+
- `dev.json` — Ethereum genesis with pre-funded test accounts
147+
- `jwt.hex` — Engine API auth token
148+
- `node{0-3}/` — per-node keys (`consensus_key.pem`, `node_key.pem`) and data directories
149+
150+
## Binaries
151+
152+
| Binary | Feature gate | Purpose |
153+
| ----------------------------------------- | ------------ | --------------------------------------------------- |
154+
| `summit` | — | Main validator node |
155+
| `testnet` | — | Spin up 4-node local testnet (needs `reth` in PATH) |
156+
| `genesis` | — | Generate genesis files from validator list |
157+
| `stake-and-checkpoint` | `e2e` | E2E: stake validator + checkpoint test |
158+
| `stake-and-join-with-outdated-checkpoint` | `e2e` | E2E: join with outdated checkpoint |
159+
| `withdraw-and-exit` | `e2e` | E2E: withdrawal flow test |
160+
| `protocol-params` | `e2e` | E2E: protocol parameter test |
161+
| `sync-from-genesis` | `e2e` | E2E: sync from genesis test |
162+
| `execute-blocks` | `bench` | Block execution benchmarking |
163+
164+
## Project Layout
165+
166+
```
167+
node/ Main binary crate (summit, testnet, genesis)
168+
src/engine.rs Central coordinator — component lifecycle, message routing
169+
src/args.rs CLI argument parsing (clap)
170+
src/config.rs Channel sizes, timeouts, default paths
171+
src/keys.rs Key management (generate/show)
172+
src/test_harness/ Shared test harness for e2e tests
173+
src/tests/ Integration tests (syncer, checkpointing, execution requests)
174+
src/bin/ Additional binaries (testnet, genesis, e2e, bench)
175+
176+
application/ Consensus interface — implements Simplex Automaton + Relay traits
177+
src/actor.rs Propose, verify, broadcast blocks
178+
179+
finalizer/ Block execution & finalization
180+
src/actor.rs Canonical state, fork states, Engine API calls, checkpoints
181+
src/db.rs Persistent storage (QMDB via commonware-storage)
182+
src/tests/ Validator lifecycle, fork handling, state queries
183+
184+
syncer/ Block sync & coordination hub
185+
src/actor.rs Block cache, finalization archive, subscription management
186+
src/resolver/ Backfill missing blocks from peers
187+
src/mocks/ Mock implementations for testing
188+
189+
orchestrator/ Epoch management
190+
src/actor.rs Simplex engine lifecycle, epoch transitions, channel multiplexing
191+
192+
rpc/ JSON-RPC server
193+
src/api.rs RPC method definitions
194+
src/server.rs Server setup (jsonrpsee + tower + CORS)
195+
tests/ Integration tests
196+
197+
types/ Shared types & engine client
198+
src/engine_client.rs Engine API client (forkchoice, payload building)
199+
src/consensus_state.rs Validator set, staking, epoch tracking
200+
src/checkpoint.rs Checkpoint creation & verification
201+
src/block.rs Block type definitions
202+
src/genesis.rs Genesis configuration parsing
203+
src/scheme.rs BLS12-381 multisig scheme
204+
205+
docs/ Architecture docs, protocol descriptions
206+
testnet/ Local testnet config (4 validators, JWT, genesis JSON)
207+
```
208+
209+
## Architecture
210+
211+
Actor-based design with message passing between components:
212+
213+
```
214+
Orchestrator → spawns/aborts Simplex engines per epoch
215+
↓
216+
Simplex Consensus (commonware-consensus) → leader election, notarization (2/3+1), finalization
217+
↓ Automaton + Relay traits
218+
Application → proposes & verifies blocks via Engine API
219+
↓ broadcast/verified/subscribe
220+
Syncer → block cache, finalization archive, P2P resolver, network broadcast
221+
↓ notarized/finalized block updates
222+
Finalizer → executes blocks against EVM client, manages validator set, creates checkpoints
223+
↓
224+
Engine Client → Engine API calls to Reth/Geth (forkchoice, payload, new block)
225+
```
226+
227+
See the **Commonware** section above for details on the consensus and infrastructure layer.
228+
229+
## Code Style
230+
231+
- **Edition 2024**, toolchain pinned in `rust-toolchain.toml`
232+
- `cargo +nightly fmt` for formatting (CI enforces nightly rustfmt)
233+
- No `.rustfmt.toml` or `.clippy.toml` — uses defaults
234+
- `RUSTFLAGS="-D warnings"` — zero warnings policy
235+
- Workspace dependencies in root `Cargo.toml`, crates reference via `workspace = true`
236+
- Actor pattern: each component has `actor.rs` (main logic) + `ingress.rs` (message types/mailbox)
237+
238+
## CI
239+
240+
GitHub Actions (`.github/workflows/ci.yml`) on push/PR to `main`:
241+
242+
1. **rustfmt** — `cargo +nightly fmt --all --check`
243+
2. **build** — default, no-default-features, `prom`, `jemalloc`, all-features
244+
3. **warnings** — `RUSTFLAGS="-D warnings" cargo check` (default + all-features)
245+
4. **test** — `cargo test` + `cargo test --all-features`
246+
247+
## Troubleshooting
248+
249+
| Problem | Fix |
250+
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
251+
| `rustup` installs toolchain on first build | Expected — `rust-toolchain.toml` pins the required version, auto-installed by rustup |
252+
| `testnet` binary exits immediately without `reth` | Requires `reth` in PATH. Install [seismic-reth](https://github.com/SeismicSystems/seismic-reth) or upstream reth |
253+
| `prom` feature fails to build | Pulls `reth-metrics` from `SeismicSystems/seismic-reth` git — needs network access |
254+
| `procfs` compile error on macOS with `prom` feature | `procfs` is Linux-only, gated behind `cfg(target_os = "linux")` — build `prom` on Linux or use `--features jemalloc` on macOS |
255+
| `e2e` binaries not found | Build with `cargo build --features e2e` |
256+
| `bench` binaries not found | Build with `cargo build --features bench` |

0 commit comments

Comments
 (0)