Skip to content

VALIDATION_SUITE.md

Latest commit

 

History

History
89 lines (63 loc) · 3.07 KB

VALIDATION_SUITE.md

File metadata and controls

89 lines (63 loc) · 3.07 KB
Raw

Kona Block Validation Suite

This suite provides tools for validating blocks at scale, ensuring Kona + REVM produces identical results to op-geth.

Quick Start

Note

This fork targets Ethscriptions mainnet (chain id 0xeeee). Chain-specific details (genesis, rollup config, protocol scope) live in ETHSCRIPTIONS_MAINNET.md.

# Validate a single block
./scripts/validate.sh 6

# Validate a range of blocks
./scripts/validate.sh 1000 2000

# Validate with custom parallelism
./scripts/validate.sh 1000 10000 -j 32

# Resume a previous validation run
./scripts/validate.sh 1000000 2000000 -r validation_1000000_2000000_20241210_120000

# Validate against a remote archive node (requires debug_* RPC methods)
L2_RPC=https://mainnet.ethscriptions.com/ ./scripts/validate.sh 2000000

# Compare Ethscriptions derivation output (L1→L2 txs) vs live L2 blocks
L1_RPC=<L1_RPC> \
L2_RPC=https://mainnet.ethscriptions.com/ \
cargo run -p ethscriptions-derivation-compare -- 1999990 2000010

# (Same, via helper script)
./scripts/compare_derivation.sh 1999990 2000010

# Run a small “confidence sampling” suite (derivation + STF across several ranges)
./scripts/verify_ethscriptions_mainnet_sample.sh

Architecture

The validation suite consists of:

  1. validate.sh - Main entry point that automatically selects the appropriate validator
  2. validate_block.sh - Single block validation
  3. validate_blocks_bulk.sh - Simple parallel validation for small ranges (≤100 blocks)
  4. validate_blocks_scale.sh - Enterprise-grade validation for large ranges with:
    • Checkpointing and resume capability
    • Real-time progress monitoring and ETA
    • Automatic failure threshold detection
    • Retry logic for transient failures
    • Detailed failure analysis

How It Works

  1. Fixture Creation: Uses execution-fixture to create a complete state fixture from Geth
  2. Validation: Runs the fixture through Kona's execution engine
  3. Comparison: Verifies the resulting state root matches Geth's state root

The ethscriptions-derivation-compare example validates the derivation rules (derived payload transaction bytes) separately from STF execution.

Performance

  • Process-based parallelism for complete isolation
  • Release mode builds for maximum performance
  • Typical throughput: 100-500 blocks/minute depending on hardware
  • For 1M blocks with 32 parallel jobs: ~33 hours

Implementation Details

  • Supports 0x7d (Bluebird) deposit transactions
  • Supports custom chains not present in kona-registry

REVM Dependencies

This fork relies on patched revm and op-alloy dependencies for 0x7d deposits:

  • Default: Uses vendored sources at vendor/revm and vendor/op-alloy
  • Optional: Use ./scripts/switch-revm.sh and ./scripts/switch-op-alloy.sh to toggle patches in Cargo.toml

Testing

The validation suite has been tested with:

  • Single block validation (block 6)
  • Small-range validation (blocks 5-7, 100-200)
  • Scale validation (1000-block ranges) against https://mainnet.ethscriptions.com/:
    • 6725129..6726128
    • 2000000..2000999