ethereum-rnd

# Ethereum R&D Reference Lookup You have access to 17 Ethereum R&D resources for answering questions about Ethereum protocol development. ## Local Clone Strategy (Preferred) **Clone repos locally for fast, reliable access.** Run the setup script from the plugin repo: ```bash bash scripts/clone-repos.sh [base-dir] # default: ~/ethereum-repos ``` Once cloned, use `grep`, `find`, and `cat` to search and read content directly: ```bash # Search consensus specs for a function grep -r "process_attestation" ~/ethereum-repos/consensus-specs/specs/ --include="*.md" # Read a specific spec file cat ~/ethereum-repos/consensus-specs/specs/electra/beacon-chain.md # Find all EIPs mentioning a topic grep -rl "blob" ~/ethereum-repos/EIPs/EIPS/ | head -20 # Search beacon API endpoints grep -r "post_beacon_blocks" ~/ethereum-repos/beacon-APIs/apis/ # Find where a function is defined across client repos grep -rn "processAttestation\|process_attestation" ~/ethereum-repos/lodestar/packages/ ~/ethereum-repos/lighthouse/consensus/ --include="*.ts" --include="*.rs" ``` **Why local clones are better than WebFetch:** - Instant access (no network latency) - Can use grep/find for powerful cross-file search - Works offline - No rate limits or URL guessing - Can diff between versions **Keep repos updated:** Re-run `clone-repos.sh` periodically (it does `git pull` on existing clones). **Fallback:** If repos aren't cloned locally, use WebFetch with the raw GitHub URLs documented below for each resource. ## Quick Reference: Which Resource to Use | Question type | Go to | |---|---| | How does the beacon chain handle X? | consensus-specs | | What beacon API endpoint does Y? | beacon-APIs | | What JSON-RPC method does Z? | execution-apis | | How does the EL implement X? | execution-specs (EELS) | | How does MEV/builder API work? | builder-specs | | How does peer discovery/networking work? | devp2p | | What does EIP-NNNN specify? | EIPs | | Why was X designed this way? | annotated-spec, eth2book | | What did ACD decide about X? | pm, forkcast | | What are researchers discussing about X? | ethresear.ch | | What's the governance status of EIP-NNNN? | ethereum-magicians | | What's happening with consensus redesign? | leanroadmap | | What's the overall roadmap status? | strawmap | | What did R&D Discord say about X? | eth-rnd-archive | --- ## 1. ethereum/consensus-specs — Consensus Layer Specifications The canonical source for Ethereum's proof-of-stake protocol. **Structure:** Specs are organized by fork in `specs/{fork}/` with consistent filenames. **Forks (in order):** - `phase0` (epoch 0) — foundational beacon chain - `altair` (epoch 74240) — light client support, sync committees - `bellatrix` (epoch 144896) — the merge - `capella` (epoch 194048) — withdrawals - `deneb` (epoch 269568) — blob transactions (EIP-4844) - `electra` (epoch 364032) — validator consolidation, max EB - `fulu` (epoch 411392) — data availability sampling - `gloas` (in development) — builder integration, inclusion lists - `heze` (in development) — next after gloas **Key files per fork:** - `beacon-chain.md` — state transition, data structures, epoch processing - `validator.md` — validator duties, attestation, proposal - `fork-choice.md` — fork choice rule (LMD-GHOST + Casper FFG) - `p2p-interface.md` — gossipsub topics, req/resp protocols - `fork.md` — fork transition logic - `light-client/` — light client sync protocol (altair+) **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/consensus-specs/master/specs/{fork}/{file}.md ``` Example — fetch the Electra beacon chain spec: ``` WebFetch: https://raw.githubusercontent.com/ethereum/consensus-specs/master/specs/electra/beacon-chain.md ``` **Additional content:** - `ssz/simple-serialize.md` — SSZ serialization spec - `configs/` — network configuration (mainnet, minimal) - `presets/` — parameter presets --- ## 2. ethereum/beacon-APIs — Beacon Node REST API OpenAPI 3.0 specification for the beacon node and validator client REST APIs. **Format:** YAML OpenAPI spec. Main file: `beacon-node-oapi.yaml` **Key directories:** - `apis/` — individual endpoint definitions - `types/` — shared data type schemas - `params/` — parameter definitions **API categories:** - Beacon endpoints — chain state, blocks, validators, attestations - Config endpoints — spec values, fork schedule - Debug endpoints — chain heads, state dumps - Events endpoints — SSE event stream - Node endpoints — identity, peers, sync status - Validator endpoints — duties, block production, attestation **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/beacon-APIs/master/apis/{category}/{endpoint}.yaml ``` **Rendered docs (human-readable):** ``` https://ethereum.github.io/beacon-APIs/ ``` --- ## 3. ethereum/execution-apis — Execution Layer APIs OpenRPC specification for JSON-RPC and Engine API. **Format:** YAML split across multiple files in `src/`, compiled to `openrpc.json`. **Two API surfaces:** - **JSON-RPC** (`eth_*` namespace) — standard client API for users/apps - **Engine API** (`engine_*` namespace) — authenticated CL↔EL communication **Key directories:** - `src/eth/` — JSON-RPC method specs - `src/engine/` — Engine API specs (organized by fork) - `src/schemas/` — shared type definitions **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/execution-apis/main/src/engine/{fork}.md https://raw.githubusercontent.com/ethereum/execution-apis/main/src/eth/{method}.yaml ``` **Rendered docs:** ``` https://ethereum.github.io/execution-apis/ ``` --- ## 4. ethereum/execution-specs (EELS) — Executable Execution Layer Spec Python implementation of the execution layer that serves as the formal specification. **Language:** Python 3.11+. Prioritizes readability over performance. **Structure:** Fork modules from Frontier (2015) through Prague/Osaka (2025+), each containing the full EL state transition logic. **Key paths:** - `src/ethereum/forks/{fork}/` — fork-specific implementation - `src/ethereum/forks/{fork}/vm/` — EVM implementation for that fork - `tests/` — test suite **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/execution-specs/forks/amsterdam/src/ethereum/forks/{fork}/{file}.py ``` --- ## 5. ethereum/builder-specs — Builder API (PBS) OpenAPI specification for proposer-builder separation. Defines how consensus clients source blocks from external builders. **Format:** YAML OpenAPI spec. Main file: `builder-oapi.yaml` **Key directories:** - `apis/builder/` — builder endpoint definitions - `specs/` — specs organized by fork - `types/` — shared types **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/builder-specs/main/specs/{fork}/builder.md ``` **Rendered docs:** ``` https://ethereum.github.io/builder-specs/ ``` --- ## 6. ethereum/devp2p — Networking Protocol Specifications Peer-to-peer networking specs for node discovery and communication. **Key spec files:** | File | Protocol | |---|---| | `rlpx.md` | RLPx transport protocol (encrypted TCP) | | `discv4.md` | Node Discovery v4 (Kademlia-based) | | `discv5/discv5.md` | Node Discovery v5 (current generation) | | `enr.md` | Ethereum Node Records (peer identity) | | `dnsdisc.md` | DNS-based node discovery | | `caps/eth.md` | Ethereum Wire Protocol (eth/68) | | `caps/snap.md` | Snapshot Sync Protocol (snap/1) | | `caps/les.md` | Light Ethereum Subprotocol (les/4) | **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/devp2p/master/{file}.md https://raw.githubusercontent.com/ethereum/devp2p/master/caps/{protocol}.md ``` --- ## 7. ethereum/EIPs — Ethereum Improvement Proposals All EIPs as individual markdown files. **File pattern:** `EIPS/eip-{number}.md` **Categories:** - **Core** — consensus protocol changes - **Networking** — p2p layer changes - **Interface** — user/app interaction standards - **Meta** — process/governance - **Informational** — guidelines **How to fetch a specific EIP:** ``` https://raw.githubusercontent.com/ethereum/EIPs/master/EIPS/eip-{number}.md ``` **Or the rendered version:** ``` https://eips.ethereum.org/EIPS/eip-{number} ``` **Note:** ERCs (token/contract standards) are now in a separate repo `ethereum/ERCs`. --- ## 8. ethereum/annotated-spec — Vitalik's Design Rationale Annotated versions of the consensus spec focused on explaining *why* things were designed the way they are, not just *what* they do. **Coverage:** phase0, altair, merge (not "bellatrix"), capella, deneb, phase1 (does not cover electra+) **Note:** The Bellatrix fork is named `merge` in this repo's directory structure. **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/annotated-spec/master/{fork}/beacon-chain.md ``` **When to use:** When someone asks "why does the protocol do X?" rather than "what does the protocol do?" --- ## 9. ethereum/research — Protocol Research Code Vitalik's research codebase. Python scripts and notebooks covering cryptography, data structures, economic analysis, and protocol experiments. **Topics include:** zkSNARKs, zkSTARKs, Verkle tries, Casper, sharding, erasure coding, polynomial commitments, beacon chain simulations **Note:** Explicitly unmaintained — code is offered as-is. Useful as reference for understanding research concepts, not as production code. **How to fetch:** ``` https://raw.githubusercontent.com/ethereum/research/master/{topic}/{file}.py ``` --- ## 10. ethereum/pm — AllCoreDevs Meeting Notes Central coordination hub for Ethereum protocol development. **Key directories:** - `AllCoreDevs-EL-Meetings/` — Execution Layer calls (ACDE) - `AllCoreDevs-CL-Meetings/` — Consensus Layer calls (ACDC) - `Breakout-Room-Meetings/` — specialized topic discussions - `Network-Upgrade-Archive/` — historical upgrade coordination **Schedule:** Alternating weeks — one week CL focus, next week EL focus. **How to fetch meeting notes:** ``` https://raw.githubusercontent.com/ethereum/pm/master/AllCoreDevs-CL-Meetings/call_{number}.md https://raw.githubusercontent.com/ethereum/pm/master/AllCoreDevs-EL-Meetings/Meeting_{number}.md ``` --- ## 11. forkcast.org — Protocol Call Tracker Comprehensive tracker for all Ethereum protocol development calls. JS-rendered SPA — requires Playwright MCP for full access, but URL patterns are predictable. **Call series tracked:** - **ACDC** — All Core Devs Consensus (consensus layer) - **ACDE** — All Core Devs Execution (execution layer) - **ACDT** — All Core Devs Testing - **Breakouts** — FOCIL, EPBS, BAL, RPC, PQTS, PRICE, TLI, ZKEVM, ETM, AWD **Per-call detail includes:** - Embedded YouTube recording with timestamps - Full timestamped transcript with speaker labels - AI-generated summary (highlights + action items) - Link to agenda (GitHub pm issue) **Also tracks network events:** Pectra/Fusaka devnet launches, testnet activations, mainnet upgrades, blob parameter changes (BPO1/BPO2). **URL patterns:** ``` https://forkcast.org/calls — full call list + calendar https://forkcast.org/calls/acdc/{number} — specific ACDC call https://forkcast.org/calls/acde/{number} — specific ACDE call https://forkcast.org/calls/acdt/{number} — specific ACDT call https://forkcast.org/calls/{breakout}/{number} — specific breakout call (focil, epbs, bal, etc.) ``` **How to use:** Navigate with Playwright MCP to get transcripts and summaries. For the call list, the page loads without JS issues. Individual call pages need a brief wait for transcript data to load. **When to use:** When someone asks what was discussed or decided in a specific ACD call, or wants to find the most recent call for a topic. Prefer forkcast over raw pm meeting notes — it has richer content (transcripts, summaries, YouTube links). --- ## 12. ethereum/eth-rnd-archive — Eth R&D Discord Archive Machine-readable archive of all discussions in the Eth R&D Discord server. Updated weekly. **Format:** JSON files per day per channel: `{channel}/YYYY-MM-DD.json` Each message contains: author, category, content, timestamp, attachments. **115+ channels including:** - `consensus-dev`, `execution-dev` — core client development - `evm`, `pos-consensus` — specific protocol areas - `cryptography`, `formal-methods`, `post-quantum` — research - `networking`, `el-networking` — p2p layer - `pectra-upgrade`, `fusaka-upgrade` — upgrade coordination - `beacon-network`, `portal-network` — network protocols - `account-abstraction`, `light-clients` — features **How to search for a topic:** 1. Identify the likely channel(s) from the list above 2. Fetch recent daily JSON files from that channel: ```