# Executable Spec instead of Core EIPs

## Discussion link
https://ethereum-magicians.org/t/core-eips-in-an-executable-spec-world/8640

---

## Contents

[toc]

## Context

Today, [Core EIPs](https://eips.ethereum.org/core) are used to specify changes affecting the execution layer (EL) which need to be activated through coordinated network upgrades (a.k.a. soft/hard forks).

Core EIPs currently serve two purposes: explaining the motivation/rationale/security implications of the change and formally specifying it. While the former is very useful, and helps the Ethereum community understand and debate changes, the latter isn't ideal for a few reasons:
1. The EIP format is very different than the "full specification" for the EL, the Yellow Paper. The YP often lags behind network upgrades for several months before reflecting the current state of the network. This means the actual specification is often "Yellow Paper + EIPs A, B, C"
2. Complex EIPs which touch several parts of Ethereum, e.g. [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), can require authors re-write a "skeleton spec" for Ethereum to highlight the changes they introduce.
3. The consensus layer (CL) uses a different process: an [executable specification](https://github.com/ethereum/consensus-specs/) on which changes are directly proposed as a diff. Changes' motivation/rationale/security implications are not generally detailled in EIPs.

We now (almost!) have an executable specification for the EL as well ([link](https://github.com/ethereum/execution-specs/#consensus-specification-work-in-progress)). Here is a proposal for how we could harmonize the process across EL + CL.

## Constraints

A few things we are trying to optimize for here:

1. **EIP Editors bandwidth**: EIP Editors are part time volunteers with incredibly high opportunity cost. We already have less than we would like, and we need to make sure we don't burn out or drive away the ones we do have.
* **Links**: One particularly challenging topic for EIP editors is external links. Currently, they aren't allowed. Because links vary in quality and degrade over time, making a judgement call about them is something that adds a ton of overhead to EIP editors.
3. **Coherent process across EL + CL:** while it's OK if there are small differences between the EL & CL processes, post-merge, there is just one Ethereum. We need to make sure that the overall process is coherent across both the EL + CL layers, and legible to the broader Ethereum community.
4. **Varying Quality of EIPs**: EIPs are open for anyone to submit, which, while good, leads to a lot of stale, poor quality, duplicate, etc. proposals. We need to make sure that these can be easily triaged from potential proposals for an upgrade and from EIPs which have been included in an upgrade.
5. **EIP Champions bandwidth**: It's hard to get an EIP implemented in a network update, we want to make sure we're not creating unnecessary work for the people who endeavour to try.

## High Level Proposal

Separate Core EIPs from other EIP categories, and store them directly in the executable and consensus spec repositories. The technical "Specification" section would instead be represented by the accompanying changes to the specification itself, while the other text-based sections would remain as they exist currently.

## Implementation Details

### EIP Location & Format

Currently all EIPs live in the [`ethereum/EIPs`](https://github.com/ethereum/EIPs) repository.

Under this proposal, Core EIPs would instead live in [`ethereum/execution-specs`](https://github.com/ethereum/execution-specs) and [`ethereum/consensus-specs`](https://github.com/ethereum/consensus-specs) under a subdirectory.

Core EIPs would now be formatted with reStructuredText for consistency with the inline documentation.

### Core EIPs Template

Make the following changes to the [template](https://github.com/ethereum/EIPs/blob/master/eip-template.md):

> #### Specification

Remove the section entirely.

> #### Test Cases

TBD.

> #### Reference Implementation

Remove this section.

#### Notes:

* This will require maintaining two templates: one for Core EIPs and one for everything else. While this isn't the end of the world, we should be mindful of it.

### Executable Specifications

Use branches to highlight EIPs in various stages, specifically:

* `master`: what is currently live on the Ethereum mainnet
* `forks/$FORK_NAME`: PR target branch for EIPs slated for inclusion in `$FORK_NAME`
* `eips/$EIP_NUMBER/$FORK_NAME`: a specific EIP's specification, targeting a specific fork

When an EIP goes from being proposed for a specific fork to being [Considered for Inclusion](https://github.com/ethereum/execution-specs/tree/master/network-upgrades#definitions) for it, merge `eips/$EIP_NUMBER/$FORK_NAME` into `forks/$FORK_NAME`. When `$FORK_NAME` is deployed on mainnet, merge it into `master`.

This means that specifications for historical EIPs will forever live as branches in the executable spec repository. If the EIP wants to be proposed for another fork, an author must update its branch by rebasing it off `master` and creating a new `eips/$EIP_NUMBER/$FORK_NAME` branch.

### EIP Process

Currently, Core EIPs roughly follow this process:

| Stage | Name | EIP Location | Description |
| ----- | -------- | -------- | -------- |
| 0 | Pre-Draft | _any git repository_ | Open PR in `ethereum/EIPs`, no requirements |
| 1 | Draft | _`ethereum/EIPs master`_ | Meets minimum requirements in EIP-1 |
| 2 | Review | _`ethereum/EIPs master`_ | EIP is fully specified, but changes are expected. |
| 3 | Last Call | _`ethereum/EIPs master`_ | Changes are no longer expected to the EIP. Required before testnet deployements. |
| 4 | Final | _`ethereum/EIPs master`_ | EIP is live on mainnet. Material changes are no longer possible. |

Instead if we, as an example, combine this with the Executable Specifications flow, we get:

| Stage | Name | EIP Location | Description |
| ----- | -------- | -------- | -------- |
| 0 | Pre-Draft | _any git repository_ | Open PR in `ethereum/execution-specs`, no requirements. |
| 1 | Draft | _`ethereum/execution-specs eips/4444/london`_ | Meets minimum requirements in EIP-1 |
| 2 | Review | _`ethereum/execution-specs eips/4444/london`_ | EIP is fully specified, but changes are expected. |
| 3 | Last Call | _`ethereum/execution-specs eips/4444/london`_ | Changes are no longer expected to the EIP. Required before testnet deployements. |
| 4 | Final | _`ethereum/execution-specs forks/london`_ | Material changes are no longer possible. |

Note: this would apply across both the EL **and CL**, implying that CL changes would also require an EIP for specification.

### Automation

What parts can we get a bot to do here?
* Verifying that EIPs meet the template
* Need to handle Core vs. Non-Core EIPs
* Need to allow links to specs, and nothing else
* Merging specs PRs when EIPs are merged
* Requires monitoring two repositories. Is this possible?