Skip to content

Commit 09e7712

Browse files
AskAlexSharovAskAlexSharov
authored
Merge branch 'main' into trie-fix-log
2 parents 6ba27d3 + 0723407 commit 09e7712

File tree

687 files changed

+24614
-10884
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

687 files changed

+24614
-10884
lines changed

‎.claude/settings.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"Bash(make test-all:*)",
55
"Bash(go test:*)",
66
"Bash(go get:*)",
7-
"Bash(GOEXPERIMENT=synctest go vet:*)",
7+
"Bash(go vet:*)",
88
"Bash(make lint:*)",
99
"Bash(git fetch:*)",
1010
"Bash(go mod tidy:*)"

‎.claude/skills/erigon-seg-integrity/SKILL.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: erigon-seg-integrity
3+
description: Run integrity checks on Erigon datadirs using the 'erigon seg integrity' command. Use this when the user wants to verify snapshot/segment file integrity or during the snapshot publishing process.
4+
allowed-tools: Bash, Read
5+
---
6+
7+
# Erigon Segment Integrity Check
8+
9+
The `erigon seg integrity` command runs integrity checks on an Erigon datadir to verify that snapshot and segment files are valid and consistent.
10+
11+
## Prerequisites
12+
13+
1. **Erigon must be stopped** - The command requires exclusive access to the datadir
14+
2. **Binary must be built** - Run `/erigon-build` first if the binary doesn't exist
15+
3. **Datadir must exist** - A synced Erigon datadir with blockchain data
16+
17+
## Command Syntax
18+
19+
```bash
20+
./build/bin/erigon seg integrity --datadir=<path>
21+
```
22+
23+
Replace `<path>` with the actual path to your Erigon data directory.
24+
25+
## Available Flags
26+
27+
- `--check` — Comma-separated list of specific checks to run (default: all default checks)
28+
- `--skip-check` — Comma-separated list of checks to exclude from the run
29+
- `--failFast` — Stop after the first problem is found (default: `true`). Set to `false` to continue and collect all warnings
30+
31+
## Discovering Available Checks
32+
33+
The list of available checks is **dynamic and changes over time** as new checks are added or removed. Do NOT assume a fixed list. Instead, discover the current checks by running:
34+
35+
```bash
36+
./build/bin/erigon seg integrity --help
37+
```
38+
39+
Look at the `--check` flag description in the output — it lists all currently available check names.
40+
41+
## Workflow
42+
43+
When the user wants to run integrity checks:
44+
45+
1. **Ask for the datadir path** if not already provided
46+
2. **Verify prerequisites**
47+
- Check the datadir exists
48+
- Ensure Erigon is not running (file lock will prevent concurrent access)
49+
- Build the binary if needed
50+
3. **Discover available checks** by running `--help` if the user wants to run or skip specific checks
51+
4. **Execute the command** with the appropriate flags
52+
5. **Interpret the output** — report any errors or warnings found
53+
54+
## Examples
55+
56+
### Run all default checks
57+
```bash
58+
./build/bin/erigon seg integrity --datadir=/data/erigon
59+
```
60+
61+
### Run a specific check only
62+
First discover available checks via `--help`, then:
63+
```bash
64+
./build/bin/erigon seg integrity --datadir=/data/erigon --check=<check_name>
65+
```
66+
67+
### Skip a specific check
68+
```bash
69+
./build/bin/erigon seg integrity --datadir=/data/erigon --skip-check=<check_name>
70+
```
71+
72+
### Continue past failures instead of stopping
73+
```bash
74+
./build/bin/erigon seg integrity --datadir=/data/erigon --failFast=false
75+
```
76+
77+
## Important Notes
78+
79+
- **File Lock**: If Erigon is running, the command will fail due to file lock
80+
- **Long running**: Integrity checks can take significant time on large datadirs, especially mainnet
81+
- **Discover checks dynamically**: Always use `--help` to find the current list of available checks rather than assuming fixed names

‎.claude/skills/erigondb-sync-integration-test-plan/SKILL.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
name: erigondb-sync-integration-test-plan
3+
description: Integration test plan for erigondb.toml settings resolution across 3 runtime scenarios (legacy, fresh+downloader, fresh+no-downloader)
4+
allowed-tools: Bash, Read
5+
user-invocable: false
6+
---
7+
8+
# erigondb.toml Integration Test Plan
9+
10+
Verify that `erigondb.toml` settings are correctly resolved across three distinct runtime scenarios: legacy datadirs, fresh sync with downloader, and fresh sync without downloader.
11+
12+
Use this plan after any changes to the erigondb.toml resolution logic (creation, defaults, legacy detection, downloader delivery) to confirm all paths still work.
13+
14+
## Parameters
15+
16+
Two values must be provided by the caller:
17+
18+
| Parameter | Description | Example |
19+
|-----------|-------------|---------|
20+
| **chain** | Chain name passed to `--chain=` | `hoodi`, `mainnet` |
21+
| **legacy datadir** | Path to an existing Erigon datadir that has `preverified.toml` but **no** `erigondb.toml` | `~/eth-nodes/erigon33-hoodi-stable` |
22+
23+
All scenarios use `--prune.mode=archive`.
24+
25+
## Pre-requisites
26+
27+
1. **Built binary** — invoke `/erigon-build` if `./build/bin/erigon` does not exist.
28+
2. **Legacy datadir** — the user-provided path must contain `snapshots/preverified.toml` and must **not** contain `snapshots/erigondb.toml`.
29+
3. **Port availability** — use `/erigon-network-ports` for reference. Each scenario uses a different port offset (+100, +200, +300) via `/erigon-ephemeral` conflict detection.
30+
31+
## Scenario A: Legacy datadir
32+
33+
**Goal**: Starting on a legacy datadir (has `preverified.toml`, no `erigondb.toml`) creates `erigondb.toml` with legacy settings (`step_size = 1562500`).
34+
35+
### Steps
36+
37+
1. Create an ephemeral clone of the user's legacy datadir using `/erigon-ephemeral` (Mode B: clone). This gives an isolated copy so the original is untouched.
38+
2. Confirm pre-conditions on the clone:
39+
- `snapshots/preverified.toml` exists
40+
- `snapshots/erigondb.toml` does **not** exist
41+
3. Start erigon with port offset **+100** (via `/erigon-ephemeral` port conflict detection):
42+
```
43+
./build/bin/erigon \
44+
--datadir=<clone-path> \
45+
--chain=<chain> \
46+
--prune.mode=archive \
47+
<port flags at +100 offset>
48+
```
49+
4. Wait for startup (~15s). Check logs for a message indicating legacy settings detection (e.g., `Creating erigondb.toml with LEGACY settings`).
50+
5. Verify the generated file:
51+
```bash
52+
cat <clone-path>/snapshots/erigondb.toml
53+
```
54+
Expected: `step_size = 1562500`
55+
6. Kill the process and clean up the ephemeral datadir.
56+
57+
## Scenario B: Fresh sync with downloader
58+
59+
**Goal**: A fresh datadir (no `preverified.toml`, no `erigondb.toml`) starts with code defaults (`step_size = 1562500`), then the downloader delivers the network's `erigondb.toml` during the header-chain phase, which may have different settings (e.g., `step_size = 390625` for hoodi).
60+
61+
### Steps
62+
63+
1. Create an empty ephemeral datadir using `/erigon-ephemeral` (Mode A: empty).
64+
2. Start erigon with port offset **+200**:
65+
```
66+
./build/bin/erigon \
67+
--datadir=<empty-path> \
68+
--chain=<chain> \
69+
--prune.mode=archive \
70+
<port flags at +200 offset>
71+
```
72+
3. Check early logs for a message indicating defaults are being used (e.g., `erigondb.toml not found, using defaults`) with `step_size=1562500`.
73+
4. Wait for the header-chain download phase to complete (~30-120s depending on network). Watch logs for:
74+
- `[1/6 OtterSync] Downloader completed header-chain`
75+
- `Reading DB settings from existing erigondb.toml`
76+
- `erigondb stepSize changed, propagating` (if the network's settings differ from the code defaults)
77+
5. Verify the delivered file:
78+
```bash
79+
cat <empty-path>/snapshots/erigondb.toml
80+
```
81+
The values come from the network's published `erigondb.toml` (check the chain's webseed for the canonical values).
82+
6. Kill the process and clean up the ephemeral datadir.
83+
84+
## Scenario C: Fresh sync with `--no-downloader`
85+
86+
**Goal**: A fresh datadir with `--no-downloader` immediately writes `erigondb.toml` with code defaults (`step_size = 1562500`).
87+
88+
### Steps
89+
90+
1. Create an empty ephemeral datadir using `/erigon-ephemeral` (Mode A: empty).
91+
2. Start erigon with port offset **+300** and `--no-downloader`:
92+
```
93+
./build/bin/erigon \
94+
--datadir=<empty-path> \
95+
--chain=<chain> \
96+
--prune.mode=archive \
97+
--no-downloader \
98+
<port flags at +300 offset>
99+
```
100+
3. Check logs for a message indicating defaults were written immediately (e.g., `Initializing erigondb.toml with DEFAULT settings`) with `step_size=1562500`.
101+
4. Verify the file exists immediately:
102+
```bash
103+
cat <empty-path>/snapshots/erigondb.toml
104+
```
105+
Expected: `step_size = 1562500` (code defaults, since no downloader to provide network settings)
106+
5. Kill the process and clean up the ephemeral datadir.
107+
108+
## Success Criteria
109+
110+
| Scenario | Condition | Expected step_size | File timing |
111+
|----------|-----------|-------------------|-------------|
112+
| A (legacy) | `Creating erigondb.toml with LEGACY settings` log | 1,562,500 | Written immediately on startup |
113+
| B (fresh+downloader) | `erigondb.toml not found, using defaults` then `erigondb stepSize changed, propagating` | Code default 1,562,500 then network value (chain-dependent) | After downloader delivers it |
114+
| C (fresh+no-downloader) | `Initializing erigondb.toml with DEFAULT settings (nodownloader)` log | 1,562,500 | Written immediately on startup |
115+
116+
## Cleanup
117+
118+
After all scenarios complete, ensure all ephemeral datadirs and processes are cleaned up. Use `/erigon-ephemeral` Step 5 (cleanup) for each instance, or Step 6 (leftover detection) to find any stragglers.

‎.claude/skills/launch-bal-devnet-2/SKILL.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
name: launch-bal-devnet-2
3+
description: Launch erigon + Lighthouse on the bal-devnet-2 ethpandaops devnet (EIP-7928 Block Access Lists). Manages start/stop of both EL and CL clients with proper port offsets and JWT auth.
4+
allowed-tools: Bash, Read, Write, Edit, Glob
5+
allowed-prompts:
6+
- tool: Bash
7+
prompt: start, stop, and manage erigon and lighthouse processes for bal-devnet-2
8+
---
9+
10+
# Launch bal-devnet-2 (EIP-7928 BAL Devnet)
11+
12+
Run erigon (EL) + Lighthouse (CL) on the bal-devnet-2 ethpandaops devnet for testing EIP-7928 Block Access Lists.
13+
14+
## Network Details
15+
16+
| Parameter | Value |
17+
|-----------|-------|
18+
| Chain ID | 7033429093 |
19+
| Genesis timestamp | 1770388190 |
20+
| Amsterdam timestamp | 1770400508 (epoch 32) |
21+
| Lighthouse image | `ethpandaops/lighthouse:bal-devnet-2-65bb283` |
22+
| Lighthouse version | v8.0.1 (commit 65bb283, branch bal-devnet-2) |
23+
| Explorer | https://explorer.bal-devnet-2.ethpandaops.io |
24+
| Faucet | https://faucet.bal-devnet-2.ethpandaops.io |
25+
| RPC | https://rpc.bal-devnet-2.ethpandaops.io |
26+
| Checkpoint sync | https://checkpoint-sync.bal-devnet-2.ethpandaops.io |
27+
28+
## Working Directory
29+
30+
Ask the user where they want the working directory. Default suggestion: `~/bal-devnet-2/`.
31+
Use `$WORKDIR` throughout to refer to the chosen path.
32+
33+
```
34+
$WORKDIR/
35+
├── genesis.json # EL genesis
36+
├── config.yaml # CL beacon config
37+
├── genesis.ssz # CL genesis state
38+
├── testnet-config/ # Lighthouse testnet dir (config.yaml + genesis.ssz + deploy files)
39+
├── start-erigon.sh # Erigon start script (run FIRST)
40+
├── start-lighthouse.sh # Lighthouse start script (run SECOND)
41+
├── stop.sh # Stop both erigon + Lighthouse
42+
├── clean.sh # Stop, wipe data, re-init genesis
43+
├── erigon-data/ # Erigon datadir (contains jwt.hex)
44+
├── lighthouse-data/ # Lighthouse datadir
45+
├── erigon-console.log # Erigon stdout/stderr
46+
└── lighthouse-console.log # Lighthouse stdout/stderr
47+
```
48+
49+
## Port Assignments (offset +100)
50+
51+
| Service | Port | Protocol |
52+
|---------|------|----------|
53+
| Erigon HTTP RPC | 8645 | TCP |
54+
| Erigon Engine API (authrpc) | 8651 | TCP |
55+
| Erigon WebSocket | 8646 | TCP |
56+
| Erigon P2P | 30403 | TCP+UDP |
57+
| Erigon gRPC | 9190 | TCP |
58+
| Erigon Torrent | 42169 | TCP+UDP |
59+
| Erigon pprof | 6160 | TCP |
60+
| Erigon metrics | 6161 | TCP |
61+
| Lighthouse P2P | 9100 | TCP+UDP |
62+
| Lighthouse QUIC | 9101 | UDP |
63+
| Lighthouse HTTP API | 5152 | TCP |
64+
| Lighthouse metrics | 5264 | TCP |
65+
66+
## Workflow
67+
68+
### Step 1: Check Prerequisites
69+
70+
1. Verify erigon binary exists at `./build/bin/erigon`. If not, invoke `/erigon-build`.
71+
2. Verify the Lighthouse Docker image is available:
72+
```bash
73+
docker image inspect ethpandaops/lighthouse:bal-devnet-2-65bb283 > /dev/null 2>&1
74+
```
75+
If not, pull it:
76+
```bash
77+
docker pull ethpandaops/lighthouse:bal-devnet-2-65bb283
78+
```
79+
3. Verify config files exist in `$WORKDIR` (genesis.json, testnet-config/).
80+
If not, download them:
81+
```bash
82+
mkdir -p $WORKDIR/testnet-config
83+
curl -sL -o $WORKDIR/genesis.json https://config.bal-devnet-2.ethpandaops.io/el/genesis.json
84+
curl -sL -o $WORKDIR/testnet-config/config.yaml https://config.bal-devnet-2.ethpandaops.io/cl/config.yaml
85+
curl -sL -o $WORKDIR/testnet-config/genesis.ssz https://config.bal-devnet-2.ethpandaops.io/cl/genesis.ssz
86+
echo "0" > $WORKDIR/testnet-config/deposit_contract_block.txt
87+
echo "0" > $WORKDIR/testnet-config/deploy_block.txt
88+
```
89+
90+
### Step 2: Initialize Datadir (first run only)
91+
92+
If `$WORKDIR/erigon-data/chaindata` does not exist:
93+
```bash
94+
./build/bin/erigon init --datadir $WORKDIR/erigon-data $WORKDIR/genesis.json
95+
```
96+
97+
### Step 3: Create Scripts (first run only)
98+
99+
If the start/stop/clean scripts don't exist yet, generate them. The scripts must use absolute paths based on `$WORKDIR`. Key details:
100+
101+
**start-erigon.sh** — Runs erigon with `--externalcl`. Must start FIRST (creates JWT secret).
102+
- Env vars: `ERIGON_EXEC3_PARALLEL=true`, `ERIGON_ASSERT=true`, `ERIGON_EXEC3_WORKERS=12`, `LOG_HASH_MISMATCH_REASON=true`
103+
- Flags: `--datadir=$WORKDIR/erigon-data`, `--externalcl`, `--networkid=7033429093`, all 16 EL bootnodes, erigon static peers, `--prune.mode=minimal`, all offset ports (see port table), `--http.api=eth,erigon,engine,debug`, `--pprof`, `--metrics`
104+
- EL bootnodes: fetch from `https://config.bal-devnet-2.ethpandaops.io/api/v1/nodes/inventory` (extract enode URLs from `execution.enode` fields)
105+
106+
**start-lighthouse.sh** — Runs Lighthouse via Docker with `--network=host`. Must start SECOND.
107+
- Checks JWT exists at `$WORKDIR/erigon-data/jwt.hex`
108+
- Docker container name: `bal-devnet-2-lighthouse`
109+
- Mounts: `$WORKDIR/testnet-config:/config:ro`, `$WORKDIR/lighthouse-data:/data`, JWT as `/jwt.hex:ro`
110+
- Flags: `--testnet-dir=/config`, `--execution-endpoint=http://127.0.0.1:8651`, `--execution-jwt=/jwt.hex`, all 15 CL ENR bootnodes, offset ports, `--checkpoint-sync-url=https://checkpoint-sync.bal-devnet-2.ethpandaops.io`
111+
- CL bootnodes: fetch from same inventory URL (extract ENR entries from `consensus.enr` fields)
112+
113+
**stop.sh** — Stops Lighthouse (`docker stop bal-devnet-2-lighthouse`) then erigon (`pkill -f "datadir.*bal-devnet-2/erigon-data"`).
114+
115+
**clean.sh** — Runs `stop.sh`, removes erigon chain data (chaindata, snapshots, txpool, nodes, temp) and lighthouse data, re-initializes genesis.
116+
117+
### Step 4: Start Erigon (FIRST)
118+
119+
Erigon must start first because it creates the JWT secret that Lighthouse needs.
120+
121+
```bash
122+
cd $WORKDIR && nohup bash start-erigon.sh > erigon-console.log 2>&1 &
123+
```
124+
125+
Verify it started:
126+
- Check `tail $WORKDIR/erigon-console.log` for startup messages
127+
- Check JWT exists: `ls $WORKDIR/erigon-data/jwt.hex`
128+
- Check port binding: `ss -tlnp | grep 8651`
129+
130+
### Step 5: Start Lighthouse (SECOND)
131+
132+
After erigon is running and JWT exists:
133+
134+
```bash
135+
cd $WORKDIR && nohup bash start-lighthouse.sh > lighthouse-console.log 2>&1 &
136+
```
137+
138+
Verify it started:
139+
- Check `tail $WORKDIR/lighthouse-console.log` for "Lighthouse started"
140+
- Look for "Loaded checkpoint block and state" (checkpoint sync)
141+
- Look for `peers: "N"` showing peer connections
142+
143+
### Step 6: Monitor
144+
145+
```bash
146+
# Erigon sync progress
147+
tail -f $WORKDIR/erigon-console.log
148+
149+
# Lighthouse sync progress
150+
tail -f $WORKDIR/lighthouse-console.log
151+
152+
# Check erigon block height via RPC
153+
curl -s http://localhost:8645 -X POST -H "Content-Type: application/json" \
154+
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | python3 -m json.tool
155+
156+
# Check lighthouse sync status
157+
curl -s http://localhost:5152/eth/v1/node/syncing | python3 -m json.tool
158+
```
159+
160+
### Step 7: Stop
161+
162+
```bash
163+
bash $WORKDIR/stop.sh
164+
```
165+
166+
This stops Lighthouse (via `docker stop`) then erigon (via `pkill`).
167+
168+
### Step 8: Clean (wipe data and re-init)
169+
170+
```bash
171+
bash $WORKDIR/clean.sh
172+
```
173+
174+
This runs `stop.sh`, removes erigon chain data (chaindata, snapshots, txpool, nodes, temp) and lighthouse data, then re-initializes genesis. After clean, start again with Steps 4-5.
175+
176+
## Troubleshooting
177+
178+
| Problem | Solution |
179+
|---------|----------|
180+
| JWT auth fails | Ensure erigon started first and `jwt.hex` exists. Lighthouse must mount the same file. |
181+
| No EL peers | Check firewall allows port 30403. Try adding `--nat=extip:<your-ip>`. |
182+
| No CL peers | Check firewall allows port 9100/9101. ENR bootnodes may have changed — re-fetch from inventory. |
183+
| "Head is optimistic" | Normal during initial sync. Erigon is behind Lighthouse. Will resolve as erigon catches up. |
184+
| Engine API timeout | Check erigon is running and authrpc port 8651 is accessible. |
185+
| Port conflict | Check `ss -tlnp | grep <port>`. Kill conflicting process or use higher offset. |

0 commit comments

Comments
 (0)