Ethereum Pectra Paper — Replication Package

This repository contains the data, scripts, SQL queries, and generated figures for the paper "When Staking Rewards Compound: Measuring the Impact of Ethereum's Pectra Upgrade" (NBC 2026). It reproduces every figure and every number in the paper from scratch, starting from raw beaconcha.in and Dune Analytics extracts.

Repository layout

.
├── data/                Raw + processed datasets (Git LFS — see note below)
│   └── 2026-04-07/      Primary snapshot used in the paper
├── figures/             Generated figures (SVG in-tree, PNG in LFS)
│   ├── svg/
│   └── png/
├── scripts/             Python analysis pipeline
│   ├── empirical/       Empirical analysis (figures 8–15, tables 4–5)
│   ├── simulation/      CL APR simulation (figures 3–5, tables 1–3)
│   ├── base_plot.py
│   └── plotly_scienceplots_style.py
├── sql/                 Dune SQL and beaconcha.in API queries
│   ├── beaconchain/
│   └── dune/
└── requirements.txt     Python dependencies

Prerequisites

1. Python 3.11+ and pip.
2. Git LFS (for the large CSVs under data/). Install from https://git-lfs.github.com/ and run git lfs install once.
3. A TeX distribution (TeX Live / MacTeX) only if you want to build the paper itself; the scripts themselves do not need LaTeX.

After cloning, make sure LFS has pulled the data:

git lfs pull

Setup

git clone git@github.com:benseddikmo/eth_pectra_paper_replication_package.git
cd eth_pectra_paper_replication_package
git lfs pull

python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -r requirements.txt

API keys

Several scripts under scripts/empirical/fetch_*.py pull live data from third-party APIs. They read credentials from a local .env file (not committed). Create .env in the repository root with the keys you have:

# beaconcha.in — https://beaconcha.in/api/v1/docs
# Free tier key from your beaconcha.in account → Profile → API Keys
BEACONCHAIN_API_KEY=...

# Dune Analytics — https://dune.com/settings/api
# Paid plan required for programmatic query execution; free plan works
# for exporting query results as CSV from the web UI.
DUNE_API_KEY=...

Where to get the keys

• beaconcha.in: sign up for a free account at https://beaconcha.in/ and generate an API key under your profile settings. The free tier is sufficient for the validator, reward, and consolidation endpoints used by scripts/empirical/fetch_rewards_data.py and scripts/empirical/fetch_consolidation_data.py.
• Dune Analytics: create an account at https://dune.com/ and generate an API key under Settings → API. Programmatic query execution requires a paid plan; alternatively, every Dune query used in the paper is checked in under sql/dune/ and can be run from the Dune web UI with the CSV result exported directly into data/2026-04-07/.

Replicating the Dune queries

All Dune queries are stored under sql/dune/ as .sql files named after the CSV they produce. To replicate them without an API key:

1. Open https://dune.com/ and create a new query.
2. Paste the content of the corresponding .sql file.
3. Run the query and export the result as CSV.
4. Save the CSV under data/2026-04-07/ using the same filename the scripts expect (see the pd.read_csv calls at the top of each script for the expected filename).

For example, to reproduce consolidations_raw_daily.csv, run the query in sql/dune/consolidations_raw_daily.sql and save the export under data/2026-04-07/consolidations_raw_daily.csv.

Running the pipeline

Each script is self-contained and writes its outputs to figures/svg/, figures/png/, and sometimes back into data/2026-04-07/. Run them in numerical order from the repository root:

cd scripts/empirical

# Simulation figures and tables (Section 3)
python ../simulation/cl_apy_curve.py
python ../simulation/cl_rewards_simulation.py
python ../simulation/cl_rewards_comparison.py
python ../simulation/validator_balance_simulation.py

# Empirical figures and tables (Section 4)
python 05_0x02_adoption_over_time.py
python 06_consolidation_requests.py
python 07_0x02_entity_distribution.py
python 08_consolidation_flow.py
python 09_effective_balance_histogram.py
python 10_validator_queue.py
python 11_rewards_analysis.py
python 11_solo_vs_providers_stake.py
python 12_consolidation_eth_analysis.py
python 13_consolidation_sankey.py
python 14_statistical_tests.py          # writes paper_apr_stats.tex sidecar
python 15_statistical_charts.py
python generate_combined_boxplot.py

The statistical pipeline (14_statistical_tests.py → 15_statistical_charts.py → generate_combined_boxplot.py) is the one that drives Tables 4–5 and Figures 13–15. Re-running these three scripts after any data refresh is sufficient to rebuild every number cited in Section 4.5 of the paper — 14_statistical_tests.py emits a paper_apr_stats.tex sidecar with \newcommand definitions that the paper source \inputs so nothing has to be copied by hand.

Dataset snapshot

The primary analysis in the paper uses the data/2026-04-07/ snapshot, which corresponds to the 335-day post-Pectra window:

• Pectra activation: 7 May 2025
• Snapshot cut-off: 7 April 2026

All per-validator statistics (effective balance, reward accumulators, entity tags) are as reported by beaconcha.in and Dune at the cut-off time.

Citing this work

If you use this replication package, please cite the paper. A BibTeX entry will be added once the proceedings are published.

License

Code is released under the MIT License. Data under data/ is redistributed under the terms of the respective upstream sources (beaconcha.in, Dune Analytics); see the upstream terms of service for each provider.