|
| 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. |
0 commit comments