# Forkcast: Ethereum Upgrade Tracker

> Source: https://github.com/ethereum/forkcast

Forkcast tracks EIPs, protocol calls, networks, and upgrade planning for Ethereum network upgrades.

## Important: page body content is client-rendered

Forkcast is built with Astro, which serves a real HTML page per route with correct titles and metadata. Page *bodies* (the data tables, timelines, and EIP/call content) render client-side by React islands. Fetching route URLs like `/eips`, `/calls`, `/networks`, `/decisions`, and `/agenda` returns the document shell — title, description, and navigation — but not the rendered body content. Use the JSON indexes and static artifacts below instead.

## Bulk indexes (start here)

Everything the site renders is available as JSON. One fetch each, no auth, no pagination.

### `/api/eips.json`
The full EIP dataset — every EIP Forkcast tracks, unfiltered. Each record carries:
- `id`, `title`, `status`, `description`, `author`, `type`, `createdDate`
- `forkRelationships[]` — one per tracked upgrade (empty array when the EIP is not tracked for any), each with `forkName` and a `statusHistory[]` of `{ status, call, date }`, where `status` is the inclusion stage (`Proposed`, `Considered`, `Scheduled`, `Included`, `Declined`, `Informational`, `Networking`, `Withdrawn`). `champions[]` (who is driving it in that upgrade) and `isHeadliner` appear on the relationship when set. This is the answer to "is EIP X in upgrade Y" — match on `forkName`, which is unaccented (`Hegota`, not `Hegotá`).
- `laymanDescription`, `benefits`, `tradeoffs`, `faq`, `stakeholderImpacts` — plain-language prose written for exactly this purpose. Quote it rather than paraphrasing the spec.
- `reviewer` (`bot` | `expert` | `staff`) — provenance of that prose. `bot` means no human has vetted it yet.
- `requires[]` — EIP dependencies. `category`, `layer` (`EL` | `CL`) — optional, present when available.

### `/api/eips/{id}.json`
One EIP's full record — the same object as in `/api/eips.json`, but a single record (0.2–12 KB) instead of the whole dataset (~580 KB). Use this for single-EIP questions; use the bulk index only when you need many EIPs in one pass. Unknown ids 404.

### `/api/calls.json`
Every protocol call, with `type`, `date`, `number`, and `path`. Append `path` to `/artifacts/` to reach that call's files. Includes a `series` map decoding the type slugs (`acde` → "AllCoreDevs - Execution").

### `/api/upgrades.json`
Network upgrades with `status`, activation details (block/epoch/slot, once shipped), meta-EIP links, and client team perspectives. Two things to note:
- `projectedActivation` (`YYYY-MM-DD`) is Forkcast's working *estimate* of mainnet activation for upgrades that haven't shipped — a planning assumption, never an announced date. Say so when you quote it.
- `activationDateLabel` is display text, not a parseable date (`"Sep 15, 2022"` for shipped upgrades, `"2027"` for future ones).

### `/api/eip-stage-changes.json`
Every EIP with a dated inclusion-stage change, newest first, one row each: `lastStageChange`, `lastStageChangeFork`, `currentStage`. `/api/eips.json` has the same history nested per EIP — this is the flat chronology, so use it to answer "what changed lately" or "what moved in this window" without walking the whole dataset.

### `/search-light.json`
The editorial corpus for every call in one file (~950 KB): TL;DRs, detailed notes, and key decisions, each with a timestamp into the recording. Use this for "what was decided about X" across all calls.

Note this is the *summarized* tier. Raw transcripts are a separate, much larger tier (see below) — call summaries are edited, transcripts are people thinking out loud mid-sentence, so quoting transcripts as protocol fact is unreliable.

## Static files

### EIP specs (Markdown)
The raw EIP document, as published in the EIPs repo:
- Pattern: `/eips/{number}.md`
- Example: /eips/1153.md

### Call artifacts
Per-call files, organized by series and call number:
- Pattern: `/artifacts/{series}/{date}_{number}/{file}`
- Example: /artifacts/acde/2026-04-09_234/tldr.json
- Discover valid paths from `/api/calls.json`.

Available files vary by call:
- `tldr.json` - Structured highlights grouped by topic, with timestamps
- `notes.json` - Detailed topic-grouped notes
- `key_decisions.json` - Decisions made during the call, each with structured `eips: number[]`
- `transcript.vtt` / `transcript_corrected.vtt` - Full call transcript
- `chat.txt` - Chat log
- `config.json` - Call metadata

Recent ACDE and ACDC calls (from ~Oct 2025 onward) include `tldr.json` and `key_decisions.json`. Older calls only have transcripts and chat logs. Bundled breakouts suffix each artifact by kind (`tldr_cl.json`, `transcript_cl.vtt`).

### `/feed.xml`
RSS 2.0, newest first, carrying three kinds of item:
- EIP inclusion-stage changes, each with the EIP's own one-line description from its spec
- Network activations — mainnet, testnet, and devnet — titled like "Fusaka Live on Mainnet"
- Protocol calls whose page has gone live, titled like "AllCoreDevs - Consensus #184 call published" and linking to it. Title and link only: none of the call's summary or decision text is in the feed.

`pubDate` is the date of the event itself, not of publication, and `guid` is stable across rebuilds.

Built for feed readers. If you are an agent, `/api/eip-stage-changes.json` carries the stage changes as structured fields — use that instead.

### Call planning artifacts
Each series has a `plan/` directory with upcoming agenda context:
- Pattern: `/artifacts/{series}/plan/{file}`
- Example: /artifacts/acde/plan/open_action_items.json
- Files: `agenda_suggestions.json`, `deferred_decisions.json`, `eip_threads.json`, `open_action_items.json`

### Large, optional
- `/eip-spec-index.json` (~4 MB) - Inverted word index over EIP spec text, for full-text spec search.
- `/search-corpus.json` (~19 MB) - Full transcripts and chat logs for every call. Only fetch this if you genuinely need raw transcript text; prefer `/search-light.json`.

## Still only in the source repo

A few datasets have no served equivalent. Access via the GitHub API, e.g.
`gh api repos/ethereum/forkcast/contents/src/data/events.ts`:

- `src/data/events.ts` - Timeline of devnets, testnets, and mainnet activations
- `src/data/pending-proposals.ts` - Proposals not yet assigned EIP numbers
- `src/data/eips/` - The per-EIP JSON files that `/api/eips.json` is compiled from

## Quick reference

| Want                       | How                                                             |
| -------------------------- | --------------------------------------------------------------- |
| Is EIP X in upgrade Y?     | `GET /api/eips/{id}.json` → `forkRelationships[].statusHistory` |
| What does EIP X do?        | `GET /api/eips/{id}.json` → `laymanDescription`, `benefits`     |
| Raw EIP spec               | `GET /eips/{number}.md`                                         |
| What changed recently?     | `GET /api/eip-stage-changes.json`                               |
| Subscribe to changes       | `GET /feed.xml` (RSS; agents should use the JSON above)         |
| All calls / artifact paths | `GET /api/calls.json`                                           |
| What was decided about X?  | `GET /search-light.json`                                        |
| One call's summary         | `GET /artifacts/{series}/{date}_{number}/tldr.json`             |
| One call's transcript      | `GET /artifacts/{series}/{date}_{number}/transcript.vtt`        |
| When might upgrade X ship? | `GET /api/upgrades.json` → `projectedActivation` (estimate)     |
| Upcoming agenda context    | `GET /artifacts/{series}/plan/open_action_items.json`           |
| Event timeline             | GitHub: `src/data/events.ts`                                    |
| Pending proposals          | GitHub: `src/data/pending-proposals.ts`                         |