-
Notifications
You must be signed in to change notification settings - Fork 558
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1 from AstroAxolotl/AstroAxolotl-patch-1
Update eip-1.md
- Loading branch information
Showing
1 changed file
with
44 additions
and
59 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,101 +1,90 @@ | ||
| --- | ||
| eip: 1 | ||
| title: EIP Purpose and Guidelines | ||
| title: ERC Purpose and Guidelines | ||
| status: Living | ||
| type: Meta | ||
| author: Martin Becze <[email protected]>, Hudson Jameson <[email protected]>, et al. | ||
| created: 2015-10-27 | ||
| --- | ||
|
|
||
| ## What is an EIP? | ||
| ### What is an ERC? | ||
|
|
||
| EIP stands for Ethereum Improvement Proposal. An EIP is a design document providing information to the Ethereum community, or describing a new feature for Ethereum or its processes or environment. The EIP should provide a concise technical specification of the feature and a rationale for the feature. The EIP author is responsible for building consensus within the community and documenting dissenting opinions. | ||
| ERC stands for Ethereum Request for Comment. An ERC is a design document providing information to the Ethereum community or proposing a new standard for application-level protocols, interfaces, or conventions within the Ethereum ecosystem. The ERC should include a concise technical specification of the standard and a rationale for its adoption. | ||
|
|
||
| ## EIP Rationale | ||
| ERCs are: | ||
|
|
||
| We intend EIPs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Ethereum. Because the EIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. | ||
| - **Independent of Ethereum Core Protocol Changes**: ERCs do not require consensus from Ethereum Core Developers or execution via hard forks. | ||
| - **Consensus-Driven Among Stakeholders**: ERCs achieve finality based on broad consensus among authors, implementers, and the community. | ||
| - **Application-Focused**: ERCs address the needs of developers, dapps, and infrastructure providers. | ||
|
|
||
| For Ethereum implementers, EIPs are a convenient way to track the progress of their implementation. Ideally each implementation maintainer would list the EIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library. | ||
| Unlike Ethereum Improvement Proposals (EIPs), ERCs focus on standards for applications and infrastructure surrounding Ethereum, independent of core protocol changes or hard forks. This process aims to foster community-driven innovation and ensure the adoption of robust and interoperable standards. | ||
|
|
||
| ## EIP Types | ||
| ## ERC Rationale | ||
|
|
||
| There are three types of EIP: | ||
| We intend ERCs to be the primary mechanisms for proposing new standards, collecting community technical input, and documenting the design decisions that shape Ethereum’s ecosystem. Because ERCs are maintained as text files in a versioned repository, their revision history serves as the historical record of the proposal. | ||
|
|
||
| - A **Standards Track EIP** describes any change that affects most or all Ethereum implementations, such as—a change to the network protocol, a change in block or transaction validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Ethereum. Standards Track EIPs consist of three parts—a design document, an implementation, and (if warranted) an update to the [formal specification](https://github.com/ethereum/yellowpaper). Furthermore, Standards Track EIPs can be broken down into the following categories: | ||
| - **Core**: improvements requiring a consensus fork (e.g. [EIP-5](./eip-5.md), [EIP-101](./eip-101.md)), as well as changes that are not necessarily consensus critical but may be relevant to [“core dev” discussions](https://github.com/ethereum/pm) (for example, [EIP-90], and the miner/node strategy changes 2, 3, and 4 of [EIP-86](./eip-86.md)). | ||
| - **Networking**: includes improvements around [devp2p](https://github.com/ethereum/devp2p/blob/readme-spec-links/rlpx.md) ([EIP-8](./eip-8.md)) and [Light Ethereum Subprotocol](https://ethereum.org/en/developers/docs/nodes-and-clients/#light-node), as well as proposed improvements to network protocol specifications of [whisper](https://github.com/ethereum/go-ethereum/issues/16013#issuecomment-364639309) and [swarm](https://github.com/ethereum/go-ethereum/pull/2959). | ||
| - **Interface**: includes improvements around language-level standards like method names ([EIP-6](./eip-6.md)) and [contract ABIs](https://docs.soliditylang.org/en/develop/abi-spec.html). | ||
| - **ERC**: application-level standards and conventions, including contract standards such as token standards ([ERC-20](./eip-20.md)), name registries ([ERC-137](./eip-137.md)), URI schemes, library/package formats, and wallet formats. | ||
| For Ethereum implementers, ERCs provide a convenient way to track the progress of standard adoption. Ideally, each implementation maintainer would list the ERCs they have implemented, offering end users a clear understanding of the current status of a given implementation or library. | ||
|
|
||
| - A **Meta EIP** describes a process surrounding Ethereum or proposes a change to (or an event in) a process. Process EIPs are like Standards Track EIPs but apply to areas other than the Ethereum protocol itself. They may propose an implementation, but not to Ethereum's codebase; they often require community consensus; unlike Informational EIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Ethereum development. Any meta-EIP is also considered a Process EIP. | ||
| ## ERC Types | ||
|
|
||
| - An **Informational EIP** describes an Ethereum design issue, or provides general guidelines or information to the Ethereum community, but does not propose a new feature. Informational EIPs do not necessarily represent Ethereum community consensus or a recommendation, so users and implementers are free to ignore Informational EIPs or follow their advice. | ||
| There are three types of ERC: | ||
|
|
||
| It is highly recommended that a single EIP contain a single key proposal or new idea. The more focused the EIP, the more successful it tends to be. A change to one client doesn't require an EIP; a change that affects multiple clients, or defines a standard for multiple apps to use, does. | ||
| - A **Standards Track ERC** outlines any technical standard that impacts the broader Ethereum ecosystem, including proposed conventions or specifications for decentralized applications, wallets, smart contracts, or their interoperability. These ERCs often include detailed design documents, implementation guidelines, and, if applicable, updates to formal specifications. Standards Track ERCs serve as the foundation for creating cohesive and interoperable tools and protocols within the Ethereum ecosystem. | ||
| Standards Track ERCs are further divided into the following subcategories: | ||
|
|
||
| An EIP must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly. | ||
| - **Apps**: These ERCs define standards for decentralized applications. They cover APIs, conventions, and data formats to ensure dapp interoperability and smooth intercommunication with wallets. | ||
|
|
||
| ### Special requirements for Core EIPs | ||
| - **Wallets**: These ERCs focus on standards specific to wallet implementations. This includes features like transaction signing protocols, account management, and interoperability with other Ethereum ecosystem tools. | ||
|
|
||
| If a **Core** EIP mentions or proposes changes to the EVM (Ethereum Virtual Machine), it should refer to the instructions by their mnemonics and define the opcodes of those mnemonics at least once. A preferred way is the following: | ||
| - **Smart Contracts**: These ERCs specify standards for smart contract design, such as reusable templates, interaction patterns, or security practices. They aim to improve code reliability, compatibility, and efficiency in smart contract development. | ||
|
|
||
| ``` | ||
| REVERT (0xfe) | ||
| ``` | ||
|
|
||
| ## EIP Work Flow | ||
|
|
||
| ### Shepherding an EIP | ||
|
|
||
| Parties involved in the process are you, the champion or *EIP author*, the [*EIP editors*](#eip-editors), and the [*Ethereum Core Developers*](https://github.com/ethereum/pm). | ||
| - A **Meta ERC** describes a process surrounding the Ethereum ecosystem or proposes a change to a process. Meta ERCs are procedural and do not propose changes to Ethereum's core protocol or applications themselves. They often require community consensus and may include guidelines, decision-making processes, or changes to development tools and environments. Meta ERCs are crucial for maintaining and improving Ethereum’s ecosystem-wide workflows. | ||
|
|
||
| Before you begin writing a formal EIP, you should vet your idea. Ask the Ethereum community first if an idea is original to avoid wasting time on something that will be rejected based on prior research. It is thus recommended to open a discussion thread on [the Ethereum Magicians forum](https://ethereum-magicians.org/) to do this. | ||
| - **Informational ERC** provides general guidance or information to the Ethereum community. Unlike Standards Track ERCs, they do not define new standards or require implementation but serve as references for best practices or clarifications. | ||
| follow their advice. | ||
|
|
||
| Once the idea has been vetted, your next responsibility will be to present (by means of an EIP) the idea to the reviewers and all interested parties, invite editors, developers, and the community to give feedback on the aforementioned channels. You should try and gauge whether the interest in your EIP is commensurate with both the work involved in implementing it and how many parties will have to conform to it. For example, the work required for implementing a Core EIP will be much greater than for an ERC and the EIP will need sufficient interest from the Ethereum client teams. Negative community feedback will be taken into consideration and may prevent your EIP from moving past the Draft stage. | ||
| It is highly recommended that a single ERC contain a single key proposal or new idea. The more focused the ERC, the more successful it tends to be. A change to one client doesn't require an ERC; a change that affects multiple clients, or defines a standard for multiple apps to use, does. | ||
|
|
||
| ### Core EIPs | ||
| An ERC must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly. | ||
| ## ERC Work Flow | ||
|
|
||
| For Core EIPs, given that they require client implementations to be considered **Final** (see "EIPs Process" below), you will need to either provide an implementation for clients or convince clients to implement your EIP. | ||
| ### Shepherding an ERC | ||
|
|
||
| The best way to get client implementers to review your EIP is to present it on an AllCoreDevs call. You can request to do so by posting a comment linking your EIP on an [AllCoreDevs agenda GitHub Issue](https://github.com/ethereum/pm/issues). | ||
| Parties involved in the process are you, the champion or *ERC author*, the [*ERC editors*](#eip-editors), and the [*Ethereum Core Developers*](https://github.com/ethereum/pm). | ||
|
|
||
| The AllCoreDevs call serves as a way for client implementers to do three things. First, to discuss the technical merits of EIPs. Second, to gauge what other clients will be implementing. Third, to coordinate EIP implementation for network upgrades. | ||
| Before you begin writing a formal ERC, you should vet your idea. Ask the Ethereum community first if an idea is original to avoid wasting time on something that will be rejected based on prior research. It is thus recommended to open a discussion thread on [the Ethereum Magicians forum](https://ethereum-magicians.org/) to do this. | ||
|
|
||
| These calls generally result in a "rough consensus" around what EIPs should be implemented. This "rough consensus" rests on the assumptions that EIPs are not contentious enough to cause a network split and that they are technically sound. | ||
| Once the idea has been vetted, your next responsibility will be to present (by means of an ERC) the idea to the reviewers and all interested parties, invite editors, developers, and the community to give feedback on the aforementioned channels. You should try and gauge whether the interest in your ERC is commensurate with both the work involved in implementing it and how many parties will have to conform to it. Negative community feedback will be taken into consideration and may prevent your ERC from moving past the Draft stage. | ||
|
|
||
| :warning: The EIPs process and AllCoreDevs call were not designed to address contentious non-technical issues, but, due to the lack of other ways to address these, often end up entangled in them. This puts the burden on client implementers to try and gauge community sentiment, which hinders the technical coordination function of EIPs and AllCoreDevs calls. If you are shepherding an EIP, you can make the process of building community consensus easier by making sure that [the Ethereum Magicians forum](https://ethereum-magicians.org/) thread for your EIP includes or links to as much of the community discussion as possible and that various stakeholders are well-represented. | ||
| ### ERC Process | ||
|
|
||
| *In short, your role as the champion is to write the EIP using the style and format described below, shepherd the discussions in the appropriate forums, and build community consensus around the idea.* | ||
|
|
||
| ### EIP Process | ||
|
|
||
| The following is the standardization process for all EIPs in all tracks: | ||
| The following is the standardization process for all ERCs in all tracks: | ||
|
|
||
|  | ||
|
|
||
| **Idea** - An idea that is pre-draft. This is not tracked within the EIP Repository. | ||
| **Idea** - An idea that is pre-draft. This is not tracked within the ERC Repository. | ||
|
|
||
| **Draft** - The first formally tracked stage of an EIP in development. An EIP is merged by an EIP Editor into the EIP repository when properly formatted. | ||
| **Draft** - The first formally tracked stage of an ERC in development. An ERC is merged by an ERC Editor into the ERC repository when properly formatted. | ||
|
|
||
| **Review** - An EIP Author marks an EIP as ready for and requesting Peer Review. | ||
| **Review** - An ERC Author marks an ERC as ready for and requesting Peer Review. | ||
|
|
||
| **Last Call** - This is the final review window for an EIP before moving to `Final`. An EIP editor will assign `Last Call` status and set a review end date (`last-call-deadline`), typically 14 days later. | ||
| **Last Call** - This is the final review window for an ERC before moving to `Final`. An ERC editor will assign `Last Call` status and set a review end date (`last-call-deadline`), typically 14 days later. | ||
|
|
||
| If this period results in necessary normative changes it will revert the EIP to `Review`. | ||
| If this period results in necessary normative changes it will revert the ERC to `Review`. | ||
|
|
||
| **Final** - This EIP represents the final standard. A Final EIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. | ||
| **Final** - This ERC represents the final standard. A Final ERC exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. | ||
|
|
||
| A PR moving an EIP from Last Call to Final SHOULD contain no changes other than the status update. Any content or editorial proposed change SHOULD be separate from this status-updating PR and committed prior to it. | ||
| A PR moving an ERC from Last Call to Final SHOULD contain no changes other than the status update. Any content or editorial proposed change SHOULD be separate from this status-updating PR and committed prior to it. | ||
|
|
||
| **Stagnant** - Any EIP in `Draft` or `Review` or `Last Call` if inactive for a period of 6 months or greater is moved to `Stagnant`. An EIP may be resurrected from this state by Authors or EIP Editors through moving it back to `Draft` or it's earlier status. If not resurrected, a proposal may stay forever in this status. | ||
| **Stagnant** - Any ERC in `Draft` or `Review` or `Last Call` if inactive for a period of 6 months or greater is moved to `Stagnant`. An ERC may be resurrected from this state by Authors or ERC Editors through moving it back to `Draft` or it's earlier status. If not resurrected, a proposal may stay forever in this status. | ||
|
|
||
| >*EIP Authors are notified of any algorithmic change to the status of their EIP* | ||
| >*ERC Authors are notified of any algorithmic change to the status of their ERC* | ||
| **Withdrawn** - The EIP Author(s) have withdrawn the proposed EIP. This state has finality and can no longer be resurrected using this EIP number. If the idea is pursued at a later date it is considered a new proposal. | ||
| **Withdrawn** - The ERC Author(s) have withdrawn the proposed ERC. This state has finality and can no longer be resurrected using this ERC number. If the idea is pursued at a later date it is considered a new proposal. | ||
|
|
||
| **Living** - A special status for EIPs that are designed to be continually updated and not reach a state of finality. This includes most notably EIP-1. | ||
| **Living** - A special status for ERCs that are designed to be continually updated and not reach a state of finality. This includes most notably ERC-1. | ||
|
|
||
| ## What belongs in a successful EIP? | ||
| ## What belongs in a successful ERC? | ||
|
|
||
| Each EIP should have the following parts: | ||
|
|
||
|
|
@@ -134,7 +123,7 @@ Each EIP must begin with an [RFC 822](https://www.ietf.org/rfc/rfc822.txt) style | |
|
|
||
| `type`: *One of `Standards Track`, `Meta`, or `Informational`* | ||
|
|
||
| `category`: *One of `Core`, `Networking`, `Interface`, or `ERC`* (Optional field, only needed for `Standards Track` EIPs) | ||
| `category`: *One or more of `Apps`, `Wallets`, `Smart Contracts`* | ||
|
|
||
| `created`: *Date the EIP was created on* | ||
|
|
||
|
|
@@ -176,11 +165,7 @@ The preferred discussion URL is a topic on [Ethereum Magicians](https://ethereum | |
|
|
||
| ### `type` header | ||
|
|
||
| The `type` header specifies the type of EIP: Standards Track, Meta, or Informational. If the track is Standards please include the subcategory (core, networking, interface, or ERC). | ||
|
|
||
| ### `category` header | ||
|
|
||
| The `category` header specifies the EIP's category. This is required for standards-track EIPs only. | ||
| The `type` header specifies the type of EIP: Standards Track, Meta, or Informational. If the track is Standards please include the subcategories (Wallet, Application, Smart Contract). | ||
|
|
||
| ### `created` header | ||
|
|
||
|
|
||