Skip to content

Commit

Permalink
Update EIP_AUTHORS_MANUAL.md
Browse files Browse the repository at this point in the history
Co-authored-by: Sam Wilson <[email protected]>
  • Loading branch information
gurukamath and SamWilsn committed Sep 24, 2024
1 parent 324bed6 commit 045e74c
Showing 1 changed file with 15 additions and 11 deletions.
26 changes: 15 additions & 11 deletions EIP_AUTHORS_MANUAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,18 @@

This document outlines the process of specifying and testing EIPs for the Ethereum execution layer. It is intended for EIP authors, researchers and implementers. An EIP will typically go through the following stages:

1. **Research**: The EIP author concieves and refines an idea for an improvement to Ethereum.
2. **Plain English Specification**: The EIP author writes a document describing the EIP. This is done in the eips repository. [EIPS](https://github.com/ethereum/EIPs/tree/master/EIPS)
3. **Executable Specifications**: The EIP is implemented in the `execution-specs`. This is intended to make the EIP executable, identify any immediate and obvious implementation issues with the EIP (For example, the eip may not be compatible with some minor detail of the current Ethereum Virtual Machine).
4. **Writing Tests**: The EIP author writes test schemes for the EIP in the `execution-spec-tests` repository. Having the reference implementation should help identify the various logical flows to test and thus, feed into more robust testing. Once the test schemes are written, the reference implementation can then be used to fill the tests and generate the test vectors.
5. **Community Discussion**: The EIP is now ready for discussion with the broader Ethereum community. Although the feedback from the community can be sought at all stages of the EIP lifecycle, we feel that having a reference implementation and tests act as a good bridge between research and client implemtation. It also helps core developers (who have limited time and resources) to understand the EIP better and provide more informed feedback.
6. **Inclusion in a Fork**: Contigent on the community agreeing to the merits of the EIP, it can be included for implementation in a future fork. The test vectors can then be generated using the reference implementation and made available to the client teams.
7. **Client Implementation**: The EIP is implemented by the various client teams with the test vectors as the guide.
8. **Mainnet Deployment**: The EIP is deployed on the Ethereum mainnet.
| Stage | Activities | Outputs |
| ------------------ | ----------- | ------- |
| _Pre‑Draft_ | Prospective EIP author conceives of an idea for an improvement to Ethereum, and discusses with the community. | <ul><li>Vague Consensus on [Ethereum Magicians][0]</li></ul> |
| **Draft** | <p>EIP author writes a technical human-language document describing the improvement, initially in broad strokes and becoming more specific over time.</p><p>Concurrently, they develop a Python reference implementation to make the EIP executable and identify any immediate/obvious implementation issues. For example, the EIP may not be compatible with some detail of the current Ethereum Virtual Machine.</p><p>Finally for this stage, the author begins to write test schemes for the EIP. Having the reference implementation should help identify the various logical flows to test and thus feed into more robust testing. Once the test schemes are written, the reference implementation can then be used to fill the tests and generate the test vectors.</p> | <ul><li>Complete (but not final) document in [EIPs Repository][1]</li><li>Reference Implementation in [EELS][2]</li><li>Initial Tests in [EEST][3]</li></ul> |
| **Review** | <p>The broader Ethereum community discusses and provides input on the proposal.</p><p>Although the feedback from the community can be sought at all lifecycle stages, having a reference implementation and tests act as a good bridge between research and client implemtation. It also helps core developers (who have limited time and resources) to understand the EIP better and provide more informed feedback.</p> | <ul><li>Complete &amp; final document in the [EIPs Repository][1]</li><li>Comprehensive tests in [EEST][3]</li></ul>
| **Last&nbsp;Call** | Usually after being nominated for inclusion in a fork, the EIP author signals that the proposal is effectively done and begins the last period for comments/discussion. | <ul><li>Complete reference implementation in [EELS][2]</li><li>Complete tests in [EEST][3]</li><li>Immutable proposal in [EIPs Repository][1]</li></ul> |
| **Final** | The proposal is now immutable (cannot be changed) and exists for reference. | <ul><li>Mainnet client implementations</li></ul> |

[0]: https://ethereum-magicians.org/
[1]: https://github.com/ethereum/EIPs/
[2]: https://github.com/ethereum/execution-specs
[3]: https://github.com/ethereum/execution-spec-tests

This document will focus on stages 3 and 4 of the above lifecycle.

Expand All @@ -24,11 +28,11 @@ This repository contains the executable specifications for the Ethereum executio

The folder `src/ethereum` contains the specifications for the different execution layer forks. Each fork has its own folder. For example, the folder `src/ethereum/frontier` contains the specifications for the Frontier hardfork. The `state_transition` function which is available in the `src/ethereum/<FORK NAME>/fork.py` is the transition function for each fork.

# Forks under development
# Fork under development

At the time of writing, the Prague Fork is still under development and the previous fork is Cancun, which is live on Mainnet.
At any given time, there is a single fork under development. Any new EIP has to be implemented in the folder that is meant for that fork (`src/ethereum/<FORK_NAME>` folder).

So the prague folder under `src/ethereum` is essentially just the Cancun fork with the values of variables updated to reflect Prague and its under-development status. This folder (`src/ethereum/prague`) serves as the baseline for further Prague development and all the EIPs for Prague are to be implemented in this folder.
For example, at the time of writing, the Prague Fork is still under development and the previous fork is Cancun, which is live on Mainnet. So the prague folder under `src/ethereum` is essentially just the Cancun fork with the values of variables updated to reflect Prague and its under-development status. This folder (`src/ethereum/prague`) serves as the baseline for further development and all new EIPs are to be implemented in this folder.

## Branch Structure

Expand Down

0 comments on commit 045e74c

Please sign in to comment.