Skip to content

[eth-rpc]: add resumable block sync and improve CLI arguments#11153

Merged
marian-radu merged 74 commits intomasterfrom
271-eth-rpc-block-syncing-and-database-path-argument-improvements
Mar 20, 2026
Merged

[eth-rpc]: add resumable block sync and improve CLI arguments#11153
marian-radu merged 74 commits intomasterfrom
271-eth-rpc-block-syncing-and-database-path-argument-improvements

Conversation

@marian-radu
Copy link
Contributor

@marian-radu marian-radu commented Feb 23, 2026

Resumable block sync

  • New block_sync module syncs backward from the latest finalized block to the first EVM block, with restart-safe checkpoint tracking via a sync_state SQLite table.
  • On restart, fills only the top gap (new blocks) and bottom gap (remaining backfill) without re-syncing completed ranges.
  • Auto-discovers and persists first_evm_block — the lowest block with EVM support on the chain.
  • Chain identity verification: stores genesis hash in sync_state and validates on startup; detects stale boundaries after reorgs.

CLI rework

New --eth-pruning flag replaces --database-url, --cache-size, --index-last-n-blocks, and --earliest-receipt-block:

  • --eth-pruning archive (default): persistent on-disk DB with backward historical sync.
  • --eth-pruning <N>: in-memory DB keeping the latest N blocks.

CLI migration guide

Previous flag Replacement Notes
--cache-size N --eth-pruning N In-memory DB, keeps latest N blocks
--database-url sqlite::memory: --eth-pruning N --eth-pruning N always uses in-memory DB
--database-url /path/to/db.sqlite --base-path /path/to/dir Persistent DB stored as eth-rpc.db inside the directory
--index-last-n-blocks N --eth-pruning archive Syncs all finalized blocks down to the first EVM block
--earliest-receipt-block N (removed) Replaced by auto-discovered first_evm_block

Note: --dev automatically uses a temporary directory with an on-disk DB, which is deleted on exit.

Note: When --base-path is omitted, the DB is stored in the default OS data directory:

  • macOS: ~/Library/Application Support/eth-rpc/
  • Linux: ~/.local/share/eth-rpc/
  • Windows: %APPDATA%\eth-rpc\

Examples

# Local dev node (on-disk DB in a temporary directory, deleted on exit)
eth-rpc --dev

# In-memory DB, keep only the latest 512 blocks
eth-rpc --node-rpc-url wss://example.com:443 --eth-pruning 512

# Persistent DB with historical sync (default, --eth-pruning archive is implicit)
eth-rpc --node-rpc-url wss://example.com:443

# Persistent DB with historical sync at a custom path
eth-rpc --node-rpc-url wss://example.com:443 --base-path /data/eth-rpc

# Explicit archive mode
eth-rpc --node-rpc-url wss://example.com:443 --eth-pruning archive

https://github.com/paritytech/contract-issues/issues/271

@marian-radu marian-radu requested a review from a team as a code owner February 23, 2026 18:03
@marian-radu marian-radu marked this pull request as draft February 23, 2026 18:03
@marian-radu marian-radu removed the request for review from a team February 23, 2026 18:35
@marian-radu marian-radu requested review from a team as code owners March 18, 2026 15:37
- Out-of-gas failures(480 cases) after gas overrides were removed in anticipation
  of the eth-rpc binary search gas estimation (not yet merged)
- New tests added to the differential test suite
- 4 new optimization modes added to the test matrix (6 total)
@marian-radu marian-radu added this pull request to the merge queue Mar 20, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to a conflict with the base branch Mar 20, 2026
@marian-radu marian-radu added this pull request to the merge queue Mar 20, 2026
Merged via the queue into master with commit 8c6f760 Mar 20, 2026
253 of 258 checks passed
@marian-radu marian-radu deleted the 271-eth-rpc-block-syncing-and-database-path-argument-improvements branch March 20, 2026 11:47
@pgherveou pgherveou added the A4-backport-stable2603 Pull request must be backported to the stable2603 release branch label Mar 25, 2026
@paritytech-release-backport-bot

Created backport PR for stable2603:

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin backport-11153-to-stable2603
git worktree add --checkout .worktree/backport-11153-to-stable2603 backport-11153-to-stable2603
cd .worktree/backport-11153-to-stable2603
git reset --hard HEAD^
git cherry-pick -x 8c6f7606348edee72a7a1abf14807e38bec5ca17
git push --force-with-lease

marian-radu added a commit that referenced this pull request Mar 25, 2026
- New `block_sync` module syncs backward from the latest finalized block
to the first EVM block, with restart-safe checkpoint tracking via a
`sync_state` SQLite table.
- On restart, fills only the top gap (new blocks) and bottom gap
(remaining backfill) without re-syncing completed ranges.
- Auto-discovers and persists `first_evm_block` — the lowest block with
EVM support on the chain.
- Chain identity verification: stores genesis hash in `sync_state` and
validates on startup; detects stale boundaries after reorgs.

New `--eth-pruning` flag replaces `--database-url`, `--cache-size`,
`--index-last-n-blocks`, and `--earliest-receipt-block`:
- `--eth-pruning archive` (default): persistent on-disk DB with backward
historical sync.
- `--eth-pruning <N>`: in-memory DB keeping the latest N blocks.

| Previous flag | Replacement | Notes |
|---|---|---|
| `--cache-size N` | `--eth-pruning N` | In-memory DB, keeps latest N
blocks |
| `--database-url sqlite::memory:` | `--eth-pruning N` | --eth-pruning N
always uses in-memory DB |
| `--database-url /path/to/db.sqlite` | `--base-path /path/to/dir` |
Persistent DB stored as `eth-rpc.db` inside the directory |
| `--index-last-n-blocks N` | `--eth-pruning archive` | Syncs all
finalized blocks down to the first EVM block |
| `--earliest-receipt-block N` | _(removed)_ | Replaced by
auto-discovered `first_evm_block` |

> **Note:** `--dev` automatically uses a temporary directory with an
on-disk DB, which is deleted on exit.

> **Note:** When `--base-path` is omitted, the DB is stored in the
default OS data directory:
> - macOS: `~/Library/Application Support/eth-rpc/`
> - Linux: `~/.local/share/eth-rpc/`
> - Windows: `%APPDATA%\eth-rpc\`

```bash
eth-rpc --dev

eth-rpc --node-rpc-url wss://example.com:443 --eth-pruning 512

eth-rpc --node-rpc-url wss://example.com:443

eth-rpc --node-rpc-url wss://example.com:443 --base-path /data/eth-rpc

eth-rpc --node-rpc-url wss://example.com:443 --eth-pruning archive

paritytech/contract-issues#271

---------

Co-authored-by: cmd[bot] <41898282+github-actions[bot]@users.noreply.github.com>
(cherry picked from commit 8c6f760)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A4-backport-stable2603 Pull request must be backported to the stable2603 release branch feature T7-smart_contracts This PR/Issue is related to smart contracts.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants