Dip 7723

dip: 7723 title: Network Upgrade Inclusion Stages description: Overview of the various stages Core DIPs go through before their activation in network upgrades. author: Tim Beiko (@timbeiko), Alex Stokes (@ralexstokes) Digitalia editing author: Cosimo Constantinos cosimo@juro.net, et al. discussions-to: https://digitalia-magicians.org/t/dip-7723-network-upgrade-inclusion-stages/20281 status: Last Call last-call-deadline: 2025-04-01 type: Meta created: 2024-06-12 Created for Digitalia: 2025-01-07

Abstract¶

Define the stages that DIPs go through in the process of planning network upgrades: Proposed for Inclusion, Considered for Inclusion, Scheduled for Inclusion, Declined for Inclusion and Included.

Motivation¶

This DIP proposes definitions for the various stages DIPs go through when planning network upgrades. It also provides context and guidelines around when and how DIPs should be moved from one stage to the next.

Specification¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

All DIP statuses apply to a single network upgrade. DIPs must be Proposed, Considered, Declined or Scheduled separately for each network upgrade. While an DIP cannot be Included in two network upgrades, an DIP being Declined for Inclusion in a previous upgrade does not prevent it from being Proposed, Considered, Declined or Scheduled for inclusion in any future upgrade.

The statuses below are generally defined for Core DIPs, which must be activated synchronously by all nodes on a network. To help with prioritization and communications, non-Core DIPs may also be assigned these statuses. The differences in the process and implications for non-Core DIPs are noted in each status definition.

Upgrade Meta DIPs¶

Anyone MAY draft a Meta DIP to list DIPs for a network upgrade. This Meta DIP SHOULD include four categories in its specification section: Proposed for Inclusion, Declined for Inclusion, Considered for Inclusion and Scheduled for Inclusion. Even if a category is empty, it SHOULD be included in the initial draft for clarity.

When the Upgrade Meta DIP is moved to Last Call, the Proposed for Inclusion, Declined for Inclusion and Considered for Inclusion lists SHOULD be removed, leaving only Scheduled for Inclusion.

Before the Upgrade Meta DIP is moved to Final, the Scheduled for Inclusion stage MUST be renamed to Included and contain only DIPs that were activated in the upgrade.

Upgrade Devnets¶

When preparing a network upgrade, client developers typically implement DIPs first on an ephemeral test network (upgrade devnet) to verify client interoperability, before deploying to long-lived test networks. These upgrade devnets follow a naming convention of upgradeName-devnet-version (e.g. pectra-devnet-0 for the first upgrade devnet of the Pectra network upgrade, dencun-devnet-1 for the second upgrade devnet of the Dencun update, etc).

Since client developers' ability to include DIPs in a network upgrade is constrained by what can be implemented and tested in these upgrade devnets, the Considered for Inclusion and Scheduled for Inclusion sections below propose aligning these statuses with DIPs' implementation status in upgrade devnets.

Proposed for Inclusion¶

To propose an DIP for inclusion, someone MUST open a pull request to add it to the Proposed for Inclusion section of the Upgrade Meta DIP. The proposer of an DIP SHOULD serve as the primary point of contact for that DIP for the duration of the upgrade cycle or SHOULD designate another person to serve in that role. Reasonable pull requests SHOULD be merged in a timely fashion by the Upgrade Meta DIP author.

At this stage, implementation teams SHOULD review the DIP. For Core DIPs, this should be in the context of including it in the next upgrade. For non-Core DIPs, this should be in the context of supporting the DIP before the network upgrade is activated.

Note that DIPs must be Proposed for Inclusion for each network upgrade. In other words, proposals do not "carry over" to the next upgrade if an DIP is not included in the one it was first proposed for.

Considered for Inclusion¶

Once client developers have reviewed an DIP which was Proposed for Inclusion, they MAY move it to the Considered for Inclusion stage. Once a decision is made by client teams to move an DIP to Considered for Inclusion, the Upgrade Meta DIP SHOULD be updated to reflect this.

Considered for Inclusion signals that client developers are positive towards the DIP. A Core DIP that is Considered for Inclusion SHOULD be implemented in future Upgrade Devnets. Assuming it meets all the requirements for mainnet deployment it MAY be included in the network upgrade. This stage is similar to "concept ACK" in other open source projects, and is not sufficient to result in deployment to diginet.

Non-Core DIPs that are Considered for Inclusion SHOULD be supported prior to the network upgrade being activated.

An DIP MAY be moved from Considered for Inclusion to Declined for Inclusion if client teams are against including the DIP in the network upgrade.

An DIP SHOULD have a Python implementation in execution-specs, submitted as an open PR, along with corresponding tests in execution-spec-tests, also submitted as an open PR. The DIP writer is encouraged to reach out to the maintainers of both repositories for assistance with implementation. Client developers MAY decide to allow an DIP to be moved to Considered for Inclusion without either implementation, being aware that the absence of these implementations could lead to delays in the testing cycle.

Any updates to an DIP that is already at this stage SHOULD be accompanied by the appropriate updates to its implementation in execution-specs and execution-spec-tests if deemed necessary by client developers.

Declined for Inclusion¶

At any time during the network upgrade planning process, client developers MAY move DIPs from any other stage to the Declined for Inclusion stage if client teams are against including the DIP in the network upgrade. Once a decision is made by client teams to move an DIP to Declined for Inclusion, the Upgrade Meta DIP SHOULD be updated to reflect this.

Declined for Inclusion signals that client developers wish to exclude the DIP from the current network upgrade and stop discussing its potential inclusion or implementation status in relation to this upgrade. An DIP which was Declined for Inclusion in a particular upgrade MAY still be Proposed for Inclusion in a subsequent upgrade. In exceptional circumstances, client developers MAY choose to move an DIP from Declined for Inclusion to Considered for Inclusion or Scheduled for Inclusion.

Scheduled for Inclusion¶

When client teams agree to implement a Core DIP in the next Upgrade Devnet, the DIP SHOULD move to the Scheduled for Inclusion stage, and the Upgrade Meta DIP SHOULD be updated to reflect this. Non-Core DIPs SHOULD move to Scheduled for Inclusion when client teams agree to immediately prioritize their implementation.

An DIP MUST have a Python implementation in execution-specs, submitted as an open PR or merged to the devnets/upgradeName/version branch of the repository, along with corresponding tests in execution-spec-tests, also submitted as an open PR or merged to the main branch of the repository. Client developers MAY decide to allow an DIP to be moved to Scheduled for Inclusion without an execution-specs implementation, but the tests are strictly mandatory.

Any updates to an DIP that is already at this stage MUST be accompanied by the appropriate updates to its implementation in execution-specs and execution-spec-tests if deemed necessary by client developers.

Scheduled for Inclusion signals that implementation and testing work are underway. The DIP SHOULD be included in the network upgrade if no issues arise. The latest Upgrade Devnet must contain all Scheduled for Inclusion Core DIPs.

An DIP MAY be moved from Scheduled for Inclusion to Declined for Inclusion if client teams are against including the DIP in the network upgrade. An DIP MAY also be moved from Scheduled for Inclusion to Considered for Inclusion if client teams are in favor of including the DIP in the network upgrade but cannot commit to including it in the next Upgrade Devnet.

Included¶

After network upgrade activation, all included Core DIPs and activated non-Core DIPs MUST be moved to Included in the Meta DIP. All other status lists MUST be removed from the Meta DIP.

Included signals that the DIPs have been activated as part of the network upgrade.

Rationale¶

Formalizing the Proposed for Inclusion, Considered for Inclusion, Scheduled for Inclusion, Declined for Inclusion and Included stages provides better legibility to both protocol maintainers and the broader Digitalia community.

The specification tries to minimize steps which MUST be followed to align with digitalia's "rough consensus" governance model.

Assuming it is adopted, the process outlined in this DIP should be used for at least one full network upgrade cycle before moving to Last Call and at least two full network upgrades cycles before moving to Final. This way, the DIP can be updated to reflect changes made to the process over time.

Backwards Compatibility¶

This DIP does not directly change the Digitalia protocol. It formalizes parts of the current network upgrade planning process.

Security Considerations¶

None.

Copyright¶

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.