EIP-7723 Network upgrade inclusion stages
No call decision · Other · EIP status Last Call · created 2024-06-12
A meta EIP that formally defines the five stages (Proposed for Inclusion, Considered for Inclusion, Scheduled for Inclusion, Declined for Inclusion, Included) that a core EIP goes through to be included in a network upgrade.
Why it is needed
Ethereum changes through network upgrades (hard forks) prepared jointly by several client teams. Which EIPs go into an upgrade has been discussed on the core developer calls, but the exact meaning of stages such as "under consideration" or "scheduled" and the criteria for moving between them were not set out in an official document. As a result, both the developers who maintain the protocol and the community watching from outside found it hard to tell how far a given proposal had progressed. This EIP defines five stages from Proposed for Inclusion to Included and provides guidance on when and how to move between them. In keeping with Ethereum's rough consensus governance, the procedures that must be followed are kept to a minimum. It is not a proposal that changes the protocol itself, but one that formalizes the upgrade planning process currently in use.
What changes
Today
- The stage terms used in upgrade planning are used by convention, without official definitions
- It is hard to tell which stage an EIP is in and what it needs to move to the next one
- There is no set way to write and maintain the meta EIPs that hold the list of EIPs for each upgrade
After EIP-7723
- Five stages, from Proposed for Inclusion (PFI) to Included, are formally defined
- Each stage specifies its transition conditions and the required implementation and testing
- The upgrade meta EIP holds a list for each stage, and rules are added for cleaning up the lists as progress is made
Who is affected
- Client teams: There is a common basis for prioritizing which EIPs to implement and test on devnets.
- EIP authors: It becomes clear what must be prepared at each stage from proposal to inclusion (designating a point of contact, execution-specs implementation and tests, and so on).
- Community and users: Stage labels alone show which proposals are likely to go into the next upgrade.
In depth
Five stages and their scope
Every stage applies to only one network upgrade. An EIP must receive its own Proposed, Considered, Declined or Scheduled determination for each upgrade, and one EIP cannot be Included in two upgrades. Even if it was Declined for Inclusion in a previous upgrade, it can be proposed, considered and scheduled again in a later one. The stages are defined primarily for Standards Track Core EIPs, which all nodes must activate at the same time, but they may also be assigned to non-core EIPs to help with prioritization and communication. Differences when applying them to non-core EIPs are noted in each stage definition.
Upgrade meta EIP operating rules
Anyone can write a draft of a meta EIP that holds the list of EIPs for a specific upgrade. The specification section must have four categories: Proposed for Inclusion, Declined for Inclusion, Considered for Inclusion and Scheduled for Inclusion. Even if they are empty and read TBD, it is good to include them from the draft for clarity. When the meta EIP moves to Review, the Proposed and Declined lists are cleared. When it moves to Last Call, the Considered list is cleared as well, leaving only the Scheduled list. Before it becomes Final, the Scheduled for Inclusion category must be renamed Included and keep only the EIPs actually activated in that upgrade.
How upgrade devnets and stages connect
Before putting an EIP on a long-lived testnet, client developers first implement it on an upgrade devnet, a temporary test network, to verify interoperability between clients. Devnet names follow the format upgradeName-devnet-version. For example, the first devnet of the Pectra upgrade is pectra-devnet-0, and the second devnet of the Dencun upgrade is dencun-devnet-1. Which EIPs can go into an upgrade ultimately depends on what can be implemented and tested on devnets, so this EIP proposes aligning the Considered and Scheduled statuses with devnet implementation status.
Requirements for Proposed for Inclusion (PFI) and Considered for Inclusion (CFI)
To propose inclusion, one must open a pull request that adds the EIP to the Proposed for Inclusion section of the meta EIP, and the meta EIP authors must merge reasonable pull requests in a timely manner. The proposer must act as the point of contact during the upgrade cycle or designate someone else, and a proposal does not carry over automatically to the next upgrade. When client developers finish their review and signal that they intend to try it on a devnet, the EIP is raised to Considered for Inclusion. The ACDE and ACDC call facilitators work with the testing team to draft a priority list of CFI EIPs and reflect it in the meta EIP. This priority serves as a reference for the next devnet's composition. CFI EIPs are recommended to have a public PR in execution-specs containing a Python implementation and tests. Becoming CFI without an implementation is allowed, but the testing cycle may then be delayed.
Maturity criteria for Scheduled for Inclusion (SFI)
Scheduled for Inclusion is assigned when core developers agree on a strong commitment to include the EIP in the next upgrade and judge that the specification and implementation have reached a certain level of maturity. There are four maturity criteria: the EIP must be included in a stable devnet with high participation and no critical bugs for at least one week; the specification must be close to final, with no placeholder values or open design questions; interaction with other CFI EIPs must be small or already validated on the same devnet; and test coverage must be sufficient that clients pass consensus tests and there are no known divergences. SFI eligibility is reviewed on the ACDT call, and status changes are ratified on ACDE or ACDC. The latest devnet must include all SFI core EIPs. An SFI EIP must have a Python implementation and tests in execution-specs, either as a public PR or merged into a devnets/upgradeName/version branch. The implementation may be waived in exceptional cases, but tests are mandatory. If circumstances change, an EIP can be moved down from SFI to DFI, and if there is intent to include it but it is hard to fit into the immediate next devnet, it can be moved back to CFI.
Declined for Inclusion (DFI) and Included
If client teams oppose inclusion, an EIP can be moved to Declined for Inclusion at any point and at any stage of upgrade planning. DFI signals that the EIP is excluded from this upgrade and that discussion of its inclusion or implementation status should stop. In exceptional circumstances, however, an EIP can be moved from DFI back to CFI or SFI, and it is not barred from being proposed again for the next upgrade. After the upgrade is activated, all included core EIPs and activated non-core EIPs must be moved to Included in the meta EIP, and all other status lists must be cleared.
No Protocol Changes and Current Status
This EIP does not change the protocol directly. It formalizes part of the upgrade planning process currently in use. As a result, there are no backwards compatibility concerns and no security considerations. In keeping with Ethereum's rough consensus governance, it keeps the number of required (MUST) steps to a minimum. The source proposes moving the process to Last Call after it has been used for at least one upgrade cycle, and to Final after it has been used at least twice. The current status is Last Call, with a deadline of 2025-04-01. In the call records, it was discussed on 07.09 ACDC #182 and 07.20 ACDT #88, but no decision was made. The content may be refined further before it becomes Final.