Add EIP: Versioning Scheme for EIPs

This EIP suggests a semantic versioning scheme for Standard Track EIPs based on their Specifications section to help remove ambiguity when discussing changes and tracking implementations.

An extended rationale that demonstrates how this can be used within the EVM Testing Toolchain can be found here.


@danceratopz & Ahmad Bitar thanks for sharing about this proposal in EIPIP Meeting 96.

This obviously will help in testing Standard Track - Core proposals. However, I can imagine a few other use cases of this proposal across EIP types/categories.

The EIP versioning scheme MUST follow a semantic versioning scheme of MAJOR.MINOR.PATCH, which is applied as follows:

  1. MAJOR: A breaking change to the specifications that requires an implementation change and a change to the reference tests.
  2. MINOR: An addition to the specifications that does not require changing an existing implementation, but requires additional implementation and additional test coverage to be added to the reference tests.
  3. PATCH: Any cosmetic change to, or a reformulation of, the EIP without specification change.

In my mind, with slight changes, we can perhaps increase use cases. Instead of MAJOR.MINOR.PATCH may we consider STATUS.SPECS.PATCH (x.y.z)?

  1. STATUS: When a proposal is being proposed/merged in a new status.

Acceptable values (for x)

  • 0 - Living
  • 1 - Draft
  • 2 - Review
  • 3 - Last Call
  • 4 - Final
  • 5 - Stanant
  • 6 - Withdrawn
  1. SPECS: Any update to the “Specification” field of the “EIP-template” that requires changing an existing implementation, requires additional implementation and additional test coverage to be added to the reference tests.

Acceptable values (for y)

  • Default value = 0
  • Max can be any number

Change of value to default

  • The value will go to default (y=0) every time with the change of the value of “x”
  1. PATCH: Any other changes including but not limited to fixing typos, non-significant specs changes, and updates on the EIP authors list. (This list can be increased as we see PRs with different update suggestions.)

Acceptable values (for z)

  • Default value = 0
  • Max can be any number

Change of value to default

  • The value will go to default (z=0) every time with the change of the value of “x”

I wonder what are the thoughts on

  • Adding “Version” to EIP-Preamble: This will help read the proposal status by just checking the version. It can be checked and automatically/manually allocated to a proposal by an EIP editor and be super helpful for toolings around EIPs.
  • Implementing retroactively to all EIPs: When implemented retroactively (with a script) to all existing EIPs (715+) let’s say from March 01, 2024, it will help to keep track of the number of merged changes to a Final EIPs among other changes.

Recommendation on the default value for retroactive implementations will be STATUS.0.0
eg. For proposals in Final status, the Version = 4.0.0.

Advancing EIP-7577 using the versioning feature as described can be a good example. However, I understand it may not be doable instantaneously without updating bots.


In the current architecture of the EIP repository, once an EIP reaches a “final” status there is no way to modify it, not even if a security consideration is found.

My suggestion: add a mechanism that is available in the IETF’s RFC repository: an “Updated-by” or “Replaced-by” tag.
This way, a reader of an EIP can clearly see there is further discussion after the current ERC was finalized.

Updated-by should be marked even if the updating EIP is in “draft” (its an “FYI” notice)
Replaced-by should only be marked once the referencing EIP is finalized, and thus the current one becomes completely obsolete.
(both tags are added to existing EIPs once a new document with “Updates” or “Replaces” header tags, respectively, is added to the repository)


Thanks @dror for adding feedback.

It is correct that the Final EIP represents the final standard and is not open to accept modification.

However, there is a small room for non-normative changes. As per EIP-1

“A Final EIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications.”

So, if there is a general agreement of moving forward with the version scheme for EIPs, perhaps Final EIPs can also be updated to 4.0.1 where

  • 4 will indicate status = Final
  • 0 will indicate there is no significant specs change that may require additional implementation (any change is anyway not allowed for Final EIP) and
  • 1 will indicate the correction after the status change by adding the preamble header.

If not, then moving EIP versioning ahead with non-Final EIPs should be okay as well.

I am aware of the interest in discussing the process for updating Final Ethereum Standards under exceptional circumstances like security considerations. It was mentioned in the last meeting and is in active discussion in EIPIP meetings and we hope to get to talk about specific conditions under which Final EIPs can be updated. We encourage people to join the meeting or leave comments to participate in discussing edits to Final standards.

Just to be clear that this is more or less exactly the proposal in a parallel discussion, motivated especially by finding new security considerations.

The idea that a standard will be final is really appealing, but seems to push hard against reality. My 25-odd years working with W3C suggest that the goal of making a final complete standard (as opposed to the next version of something that needs to be tweaked at least from time to time) causes a lot of problems.

Over time it gets harder to fix things (update to EIP-1 anyone?) but they can still be fixed - or get completely replaced by something people believe will be easier to manage into the future. So I would like to see this discussion continue, until it reaches the point where we have a working visible concept of “this EIP is obsolete, go look at that one that replaces it”, without simply allowing anyone to claim their new thing obsoletes what the world is using.

I’m not a fan of “living” as a status - that is the status of anything that is still used.

I have an approach that is a bit like @poojaranjan backwards: Version, then status (I have “draft” and “done”). I think it’s critical to have a mechanism for a specific spec (or version) to point forward to its replacement, and this is not hard. I’m not that keen on patching old versions - if they are hanging around long enough that it is really important, then it means the next version didn’t reach the status people thought, and some more work needs to be done on re-doing the transition.

But I think people in this community understand “semantic versioning” and are used to it. It’s probably more useful to question whether we’re prepared to accept that “Final” is not real and that we should version things or not, and expect that the answer if we do versioning will be that.

1 Like

Philosophically, it comes down to are you optimising for stability or innovation? In particular what is the meaning of a standard?

Using the above as a mental map:

  1. technical discussions (technical control along bottome) in the rough consensus, working code stage need more precise versioning so details can be thrashed and matters that have been settled, can pinhole cite in case later participants raise variations of the same objective.

  2. on the other hand businesses that are looking to invest significant resources into an DLT, would like to see certainty in the timescale of decades (middle left)… which means distrust of anything too new so finality is welcome … even with known bugs (cough browser feature sets), they can be worked around because cross-chain consistency is more important.

  3. the gap between where new knowledge (eg of vulnerabilities) arises and the standards are slow to update are where attacks have the biggest detrimental impact. You can have different “standards” (eg tech and legal) moving at different speeds, so long as there is a clear coupling / stapling between the two. For example, the tech standard might say every 5-7 years have a review which then gets compiled in the market accepted practices which can be ratified at the legislative/regulative level (middle right of centre).

However, there should be some way of clustering closely related topics … at the moment, variations of treating NFTs are numbers across quite unrelated pull requests. An complementary proposal would be

For easy human memonics, EIPeditors should have the discretionary power to alias ERC-??? [alpha] to a future EIP …

eg ERC-20A might be aliased to that EIP which calls a recipient function upon transfer if commonly used). That way you’d only need to recall the shortened form.