Consensus Economics Data Aggregation and Reporting
Cedar collects and analyses Ethereum on-chain data to track three things over time:
- Total ETH supply — accounting for PoW block rewards (pre-merge), CL issuance, and EIP-1559 burn
- Staking composition — active stake, entry queue, exit queue, and pending partial withdrawals
- Validator income — CL rewards (net issuance) and EL income (priority fees and MEV payments)
The result is a local DuckDB database with a daily_stats table suitable for charting and analysis. Cedar also produces interactive HTML charts and static PNGs of staking trends.
Cedar requires two Ethereum archive nodes running locally:
| Client | Role | Default URL |
|---|---|---|
| reth | Execution layer (EL) archive node | http://localhost:8545 |
| Lighthouse | Consensus layer (CL) archive node | http://localhost:5052 |
Both nodes must be fully synced to the range you want to analyse.
You also need uv for Python environment management.
git clone <repo-url>
cd cedar
uv syncCedar's commands are designed to be run in sequence. The sync command runs all three data-collection workflows concurrently and is the normal way to keep the database up to date.
uv run cedar syncThis runs three workflows concurrently:
- [EL] processes execution-layer blocks for proposer income, burn, and PoW issuance
- [CL-T] ingests per-slot CL deposits and withdrawals
- [CL-S] takes daily snapshots of validator balances and queue state (waits for CL-T coverage)
All three workflows work backwards from the chain tip, skip already-processed data, and can be interrupted with Ctrl-C and safely resumed.
The absolute ETH supply cannot be derived from flows alone — you need one known reference point. Obtain the total supply at any epoch from beaconcha.in's supply chart and record it:
uv run cedar set-supply-anchor --epoch 8000000 --supply-eth 120456789.0 --note "beaconcha.in 2024-01-01"uv run cedar daily-statsThis populates the daily_stats table from the collected data. Re-run it any time new blocks or snapshots are available, or after updating the supply anchor. It is fully idempotent.
uv run cedar plot-statsProduces data/staking_trends.png and data/staking_trends.html — a three-pane chart showing staking fraction, queue sizes, and validator APR (CL + EL stacked). Optionally overlay key events from a Markdown file:
uv run cedar plot-stats --events events.mdThe events file uses the format # YYYY-MM-DD: Event title, one heading per event, with optional description lines below.
| Command | Description |
|---|---|
cedar sync |
Run all three data-collection workflows concurrently |
cedar process-blocks |
Run the EL block-processing workflow only |
cedar ingest-cl-transfers |
Run the CL deposits/withdrawals workflow only |
cedar aggregate-cl |
Run the CL snapshot workflow only |
cedar ingest-xatu |
Download and ingest xatu MEV relay parquet files |
cedar ingest-flashbots |
Download and ingest the Flashbots S3 relay dataset |
cedar set-supply-anchor |
Record a known ETH supply value at a given epoch |
cedar daily-stats |
Compute (or refresh) the daily_stats table |
cedar plot-stats |
Produce PNG and HTML staking trend charts |
cedar plot-relay-gaps |
Chart MEV relay data coverage by relay |
cedar spot-check |
Spot-check processed blocks against the EL node |
cedar bisect-issuance |
Binary-search for an issuance anomaly (debug) |
Run cedar <command> --help for full options on any command.
| Source | What it provides |
|---|---|
| Local reth node (JSON-RPC) | Block headers, transactions, receipts, withdrawals |
| Local Lighthouse node (Beacon API) | Validator states, balances, deposits, beacon blocks |
| ethpandaops xatu | MEV relay proposer payload data (parquet, incremental) |
| Flashbots S3 dataset | Flashbots relay data (supplements early xatu coverage) |
- Architecture — how the system works and why it is designed this way
- Database schema — all tables with field descriptions
- CL snapshots column reference — detailed breakdown of validator lifecycle buckets
- Issuance methodology — how CL issuance and APRs are calculated
MIT — see LICENSE.