EIP-1 EIP Purpose and Guidelines

No call decision · Other · EIP status Living · created 2015-10-27

A meta document that defines what an EIP is, how to write one, and the process by which it becomes a standard. It serves as the rulebook for all Ethereum Improvement Proposals.

Why it is needed

Ethereum is not a single company but a network changed collectively by developers, client teams, and the community scattered around the world. When someone wants to propose a new feature, consensus is impossible unless it is fixed where and in what format to submit it, who reviews it, and when it becomes final. EIP-1 defines this entire process. It requires proposals to be written as documents called EIPs (Ethereum Improvement Proposals) and kept as text files in a version-controlled repository, so that the edit history itself becomes the historical record of the proposal. It also divides proposals into types and sets the status flow from draft to final confirmation along with the requirements needed at each stage. Implementers can announce progress simply by disclosing the list of EIPs they have implemented, and users can track which stage a given feature is at.

What changes

Today

After EIP-1

Who is affected

In depth

The Three EIP Types

Standards Track EIPs cover changes affecting most or all Ethereum implementations and are split into four categories. Core covers improvements requiring a consensus fork and changes requiring core developer discussion; Networking covers network protocol improvements such as devp2p and the Light Ethereum Subprotocol; Interface covers language-level standards such as method names or contract ABIs; and ERC covers application-level standards such as token standards (ERC-20) and name registries (ERC-137). Meta EIPs address processes surrounding Ethereum, apply to areas outside the protocol itself, and users generally cannot ignore them. Informational EIPs merely provide design issues or general guidance, do not propose new features, and do not represent community consensus, so they need not be followed. It is recommended that a single EIP contain only one core proposal, and an EIP is needed only for changes that affect multiple clients or define a standard used by multiple apps.

Status Flow and the Meaning of Each Status

Idea is the pre-draft stage and is not tracked in the repository. Draft is the first officially tracked stage; once properly formatted, an editor merges it into the repository. Review is the state in which the author has requested peer review. Last Call is the final review period right before Final, where the author opens a PR specifying a last-call-deadline (usually 14 days out), and if normative changes become necessary it reverts to Review. Final is the final standard; only error corrections and non-normative clarifications are allowed, and the PR moving from Last Call to Final must not include changes other than the status change. If there is no activity for 6 months or more while in Draft, Review, or Last Call, the EIP moves to Stagnant, and it can be revived by the author or an editor. Withdrawn is a state the author has withdrawn from, and it cannot be revived under the same number. Living is a special status designed to keep being updated without ever reaching final confirmation, and EIP-1 itself is the representative example.

Essential Components of a Successful EIP

The preamble is an RFC 822 style header containing the EIP number, a title of at most 44 characters, a description of at most 140 characters, and author information. Abstract is a short technical summary conveying the gist of the specification. Motivation explains why the existing protocol is insufficient and can be omitted if the motivation is self-evident. Specification must be detailed enough to enable competing interoperable implementations (besu, erigon, ethereumjs, go-ethereum, nethermind, etc.). Rationale covers the reasoning behind design decisions, alternatives considered, and objections raised in discussion. Backwards Compatibility is required if backward compatibility is broken. Test Cases are required for EIPs affecting consensus changes. Security Considerations is required for every EIP; submissions lacking this section are rejected, and the EIP cannot reach Final unless reviewers judge it sufficient. Finally, every EIP must waive copyright under CC0 and be placed in the public domain.

Header Preamble Fields

The header is written in the order eip, title, description, author, discussions-to, status, last-call-deadline, type, category, created, requires, withdrawal-reason. category is required only for Standards Track EIPs. At least one person in author must include a GitHub username in order to receive change request notifications and have approval/rejection authority. discussions-to prefers an Ethereum Magicians topic; GitHub pull requests or URLs that may disappear cannot be used. requires is a dependency field used when the EIP cannot be understood or implemented without the concepts or technical elements of another EIP; merely mentioning another EIP does not create a dependency. Dates use the ISO 8601 (yyyy-mm-dd) format.

Core EIPs and the AllCoreDevs Call

A Core EIP can only reach Final if there is a client implementation, so the author must either provide the implementation directly or persuade client teams. The best way to get implementers' review is to present at an AllCoreDevs call, requested by commenting a link to the EIP on the AllCoreDevs agenda GitHub issue. This call serves three functions: discussing the EIP's technical merits, gauging other clients' willingness to implement, and coordinating implementation for a network upgrade. The outcome of the call usually leads to a rough consensus on which EIPs to implement, which rests on the assumption that the EIP is technically sound and not controversial enough to cause a network split. The source document warns that although this process is not designed to handle non-technical issues, it often ends up entangled with them anyway, and recommends that authors gather as much community discussion as possible on the Ethereum Magicians thread.

The Editors' Role and External Link Rules

Editors check that a new EIP makes technical sense and is complete, that the title accurately captures the content, and that the language, markup, and code style are correct, then assign a number and merge it. Editors do not judge the value of an EIP; they are responsible only for administration and editing. The current editors are Matt Garnett, Sam Wilson, Zainan Victor Zhou, Gajinder Singh, and Jochem Brouwer; see EIP-5069 for how to become an editor. Links to external resources are prohibited in principle because they can disappear or change, with only defined exceptions allowed, such as execution client specifications, consensus layer specifications, W3C recommendations, and IETF RFCs, on the condition that they are pinned to a specific commit or version. This approval process is governed by EIP-5757. When citing another EIP, use ERC-X if it is in the ERC category and EIP-X otherwise, and a relative-path link must be attached on first citation.

Origins of the Document and the Living Status

This document borrows heavily from Bitcoin's BIP-0001, written by Amir Taaki, which in turn was derived from Python's PEP-0001. Wording was copied and modified in many places. The authors of PEP-0001 bear no responsibility for its use in the Ethereum improvement process, so Ethereum-related questions should go to the EIP editors. EIP-1's status is Living, a document designed not to reach final confirmation but to keep being updated as needed. As a result, the process and editor list summarized here may also change going forward.

Original EIP · ← EIPs