validator-reward-analytics

Unified CLI for relay bid + transaction segment analytics, backed by SQLite.

What it does

• Combines relay-observer and transaction-observer workflows into one binary.
• Persists all fetched data to SQLite instead of keeping it in-memory.
• Provides:
  • populate: fetches and stores slot data for a range.
  • browse: runs analytics subcommands from stored data.

Data stored

• slots: per-slot beacon/canonical block metadata.
• relay_builder_bids: builder traces per relay/slot.
• relay_delivered_bids: delivered traces per relay/slot.
• execution_blocks: per-slot execution block metadata.
• block_segments: per-block segment aggregates for transaction analysis.
• relays + metadata: relay config and run metadata.

Build

go mod tidy
go build -o validator-reward-analytics .

Populate

Fetches and stores data for a slot range.

./validator-reward-analytics populate \
  --db analytics.db \
  --beacon-endpoint http://127.0.0.1:5052 \
  --rpc-url https://your-rpc-endpoint \
  --relays "flashbots=https://boost-relay.flashbots.net,ultrasound=https://relay.ultrasound.money,ethgas=https://ethgas.xyz" \
  --start-slot 13753000 \
  --end-slot 13753100 \
  --segments 8 \
  --beacon-concurrency 16 \
  --block-batch-size 50 \
  --relay-max-rps 5 \
  --with-receipts \
  --receipt-workers 16 \
  --receipt-batch-size 25

Populate notes

• Always fetches both relay endpoints for each slot:
  • /relay/v1/data/bidtraces/builder_blocks_received
  • /relay/v1/data/bidtraces/proposer_payload_delivered
• Beacon requests run independently from relay requests.
• Relay worker count defaults to one worker per configured relay.
• Execution blocks are fetched from RPC in batches (--block-batch-size).
• Block/segment/receipt processing begins as soon as beacon block hashes are ready and does not wait for relay completion.
• Receipt requests are batched across all fetched blocks (--receipt-batch-size).
• Relay requests are rate-limited per relay (--relay-max-rps) to reduce bottleneck/rate-limit pressure.
• Uses shared retry/backoff logic for beacon, relay, and ETH RPC calls.
• Recovery behavior: populate tracks per-slot relay completion and resumes only unfinished slots; if non-relay data is already checkpointed, restart will skip beacon/block/receipt calls and continue with relay collection only.
• Re-running overlapping ranges is safe: slot rows and related bid/segment rows are rewritten (upsert/replace), so updates do not fail on duplicates.

Browse

Lateness vs reward

./validator-reward-analytics browse lateness-vs-reward \
  --db analytics.db \
  --start-slot 13753000 \
  --end-slot 13753100 \
  --bucket-ms 100

Per-relay bids

./validator-reward-analytics browse per-relay-bids \
  --db analytics.db \
  --start-slot 13753000 \
  --end-slot 13753100

ETHGas relay stats

./validator-reward-analytics browse ethgas-relay-stats \
  --db analytics.db \
  --start-slot 13753000 \
  --end-slot 13753100 \
  --ethgas-pool-address 0x1234567890abcdef1234567890abcdef12345678

Transaction segment analysis

./validator-reward-analytics browse transaction-segments \
  --db analytics.db \
  --start-slot 13753000 \
  --end-slot 13753100

EthGas-only transaction segment analysis

./validator-reward-analytics browse ethgas-transaction-segments \
  --db analytics.db \
  --start-slot 13753000 \
  --end-slot 13753100

Slot detail

./validator-reward-analytics browse slot \
  --db analytics.db \
  --slot 13753042

Retry flags (populate)

• --max-retries
• --retry-backoff
• --retry-max-backoff
• --http-timeout

These are applied across relay, beacon, and Ethereum RPC requests.