How EIP Versioning could help Ethereum Development

# How EIP Versioning could help Ethereum Development This document provides examples of how a [Versioning Scheme for EIPs](https://github.com/danceratopz/EIPs/blob/versioning-scheme-for-eips/EIPS/eip-7577.md) could help Ethereum protocol development. - [ethereum/EIPs#8034](https://github.com/ethereum/EIPs/pull/8034). - [eth magicians discussion link](https://ethereum-magicians.org/t/add-eip-versioning-scheme-for-eips/17295). ## Background Defining specifications for all but extremely simple EIPs is typically an iterative process; EIP specifications are often changed many times during the different stages of an EIP's life-cycle. As core developers start implementing an EIP's specifications, discussions often ensue to clarify them, resulting in often important changes to specifications. Subsequently, broader discussion within the community and testing can also lead to specification changes. There may be many different implementations of the different versions of an EIP's specifications during its development life-cycle and tracking whether a client is up-to-date with the current definition of an EIP can be difficult. This ambiguity also hinders the testing process which also has to keep up-to-date with the specs. In the case of EVM testing, the problem is exacerbated due to the two-step process of generating fixtures that involves four sources of truth for an EIP specification (details below). ## Example 1: Client Core Dev - As a client core developer, - I want a versioning scheme and a CHANGELOG for EIP specifications, - So that I can easily determine if any changes have been made to an EIP since my last implementation update, enabling me to quickly incorporate any new changes into my work. ## Example 2: ACD Meeting Participant - As a participant in ACD status update discussions, - I want to reference specific versions of EIPs, - So that we can reduce ambiguity in our conversations and arrive at resolutions more efficiently. ## Example 3: EVM Testing Toolchain Testing an implementation of the EVM is currently a two-step process: 1. Generate "test fixtures" using a `t8n` (transition) Tool from a reference client implementation: The framework _"Fills the test fixtures"_, see Figure 1. 2. Execute the "test fixtures" against the client implementation under test: The client _"consumes the test fixtures"_, see Figure 2. During this process there are 4 sources of truth for an EIP's specification: 1. The EIP definition itself ([ethereum/EIPs](https://github.com/ethereum/EIPs)). 2. The test source code ([ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests)). 3. The reference client implementation (historically, this is typically [go-ethereum](https://github.com/ethereum/go-ethereum), planned in the future: [EELS](https://github.com/ethereum/execution-specs)). 4. The client implementation under test. ### Versioning in the Toolchain The EVM testing toolchain is currently being improved to make this 2-step process more tightly coupled. In particular, the new family of `consume` commands, which help clients "consume" test fixtures, share a common codebase that could utilize the EIP versions reported from these 4 sources. The framework could mark tests to expectedly fail (xfail), to be skipped, or issue warnings, as appropriate. This would require client teams to add an option to all executables used in the testing toolchain that returns a list of implemented EIPS and versions. ### Versioning in Test Fixture Releases [Test fixture releases](https://github.com/ethereum/execution-spec-tests/releases/), which client teams use in their internal CI/CD flows, could cite which version of an EIP they implement to reduce ambiguity. Moreover, dedicated releases of fixtures could be made on a per-EIP basis for EIPs under active development; client teams can directly choose the test fixture release that matches the current state of their implementation the closest. _**For readability, please use the links to open svg in a new tab.**_   <figure> <img src="https://mermaid.ink/svg/pako:eNqlVm1P5DYQ_iuj3CE4SrLsG6UROmkL7Gmre0EF9UtTrUwyy7okduQ4y26B_37jxHnZlwLt5VMyM348eeYZjx-dUEbo-M7e3iMXXPvwuK_nmOC-vx8xdb___Ly3F4hZLB_COVMaPv8eCIBMr2IEfSroTcl79N-Nfxmd9oZH5af7wCM993vpsgnmIs31VKqpzDW9QeuxGPCuezo6v-gfwRrKoI0y40udK8xg-_kPKJeTK7fb68OPo_R73R9E0ZjpzN2Z0f9C2croDSjrOFMuZopNcYm7cYajX4cn45erFMew-3kDSoNDKUxzEaGamrx244zHl-fDixe5IZm-ls2_o2xwk8lchbiNZH6ZcPqD_mhwvI0DYJHy2zvF0jkgdZnCPOlQzbKgSNBq4ODMtORH-rruWJOXRGedwhoEonQvUGVcCh96Xs8bWO-HBohksAlEppeABt7Q67aBUERl0lXTWUCvUxk6h4edQ-_vTIoG9bfrb1_hxpRrXPVqyhRLUCv-D0aQooKZVPcUOhFhnEdc3BXUAoWwiGnmk8uFci-qnQ-4SKRA19Tx2Ot2vWM3wsVPoUwSrr2T_iD6-fjktMmgXkugblkvwuCpYdJftPl6KZjY8hcbnKxVMHDqGpJOw1wTi26WYugWzRg4ZTFa8W1q4ph4GBteHgwZNnhtQUtvfwZOsc6qz-QTOH8FLV2vHSN1oQprpaKyWunqTVIi79VKz6UoEz5nGWYfdm_YSK29IVlf3bBN7ysbFmJsN5vd8n152FQ7b4EFAaQr42vVejljPO5k9zwtv4HPTM-AkMRwnqZSaRLq7QrCmKNor3xgSpBe7S6-WbjWyMBEVIrZVsr-agYJzxKmw_kOsAbLKPxVBEuKJaRu0pbOLv_4AjeKiYwbTcKNlHElMNrBEkdNZb4awnCpUQkWQ6lmdhtjXbFqPK1JpbtZ12r81FFfqW13nih1sp_xrq7sxg3hIHAmxgJSwbfCEjj239en1IFtjokxwGWTfRW-PkYovImBwl5IzobXOW6MjTPP_VhorfBtDm13p9PO4rZzY9Cfud6GszW_S-eTMkcnLhBiVgqDzpiKY-J-wRl84nqe38LoavJUg20NYZPGU8ntU32mO0dOgiphPKJL4KNZFzjFBTBwfHqNcMbyWBv5PFMoy7W8XonQ8WcszvDIyVM6sfGCMypnUlsx4lqqL-XNsrhgPn8HRAdFVw"> <figcaption>Figure 1: EVM Testing Toolchain - Using EIP Versioning Metadata during Test Fixture Generation (<a href="https://mermaid.ink/svg/pako:eNqlVm1P5DYQ_iuj3CE4SrLsG6UROmkL7Gmre0EF9UtTrUwyy7okduQ4y26B_37jxHnZlwLt5VMyM348eeYZjx-dUEbo-M7e3iMXXPvwuK_nmOC-vx8xdb___Ly3F4hZLB_COVMaPv8eCIBMr2IEfSroTcl79N-Nfxmd9oZH5af7wCM993vpsgnmIs31VKqpzDW9QeuxGPCuezo6v-gfwRrKoI0y40udK8xg-_kPKJeTK7fb68OPo_R73R9E0ZjpzN2Z0f9C2croDSjrOFMuZopNcYm7cYajX4cn45erFMew-3kDSoNDKUxzEaGamrx244zHl-fDixe5IZm-ls2_o2xwk8lchbiNZH6ZcPqD_mhwvI0DYJHy2zvF0jkgdZnCPOlQzbKgSNBq4ODMtORH-rruWJOXRGedwhoEonQvUGVcCh96Xs8bWO-HBohksAlEppeABt7Q67aBUERl0lXTWUCvUxk6h4edQ-_vTIoG9bfrb1_hxpRrXPVqyhRLUCv-D0aQooKZVPcUOhFhnEdc3BXUAoWwiGnmk8uFci-qnQ-4SKRA19Tx2Ot2vWM3wsVPoUwSrr2T_iD6-fjktMmgXkugblkvwuCpYdJftPl6KZjY8hcbnKxVMHDqGpJOw1wTi26WYugWzRg4ZTFa8W1q4ph4GBteHgwZNnhtQUtvfwZOsc6qz-QTOH8FLV2vHSN1oQprpaKyWunqTVIi79VKz6UoEz5nGWYfdm_YSK29IVlf3bBN7ysbFmJsN5vd8n152FQ7b4EFAaQr42vVejljPO5k9zwtv4HPTM-AkMRwnqZSaRLq7QrCmKNor3xgSpBe7S6-WbjWyMBEVIrZVsr-agYJzxKmw_kOsAbLKPxVBEuKJaRu0pbOLv_4AjeKiYwbTcKNlHElMNrBEkdNZb4awnCpUQkWQ6lmdhtjXbFqPK1JpbtZ12r81FFfqW13nih1sp_xrq7sxg3hIHAmxgJSwbfCEjj239en1IFtjokxwGWTfRW-PkYovImBwl5IzobXOW6MjTPP_VhorfBtDm13p9PO4rZzY9Cfud6GszW_S-eTMkcnLhBiVgqDzpiKY-J-wRl84nqe38LoavJUg20NYZPGU8ntU32mO0dOgiphPKJL4KNZFzjFBTBwfHqNcMbyWBv5PFMoy7W8XonQ8WcszvDIyVM6sfGCMypnUlsx4lqqL-XNsrhgPn8HRAdFVw"/>view image as SVG</a>).</figcaption> </figure> <figure> <img src="https://mermaid.ink/svg/pako:eNqlWAtP40YQ_isjt4hHsUMgOe4sehLHo03F9RBcpUq4ijb2hmyx19Z6HZIS_ntnvfZm7QQUjiCEGY8_z-Pbb2fz5IRpRB3f2dp6YpxJH5625YQmdNvfjoh42H5-3toK-DhOH8MJERKubgIOkMt5TIHxrJDDVAzTQuIVWJ9civSB-vBT9-Pp2fnRfmVwH1kkJ34vmy1RxmwmC0FzWP28AUXSXA4FzVIh34FyMbh2u4dH8L5YFMrRYfeHUVpZMT4WZEhndD1S__RL_8Pla_GEKc-LhA4jJmgo34si4uzFrDZHofye8R_OaMKmFNZ_NkJZImFZhwWPqBiqWq9Hury8OOufvxbPKE7DhxWAt6KEMaNcDvN5LmnSjGcjlCVSzpIiJjIV61bVmMUxIvU-9Q_6x1YlcN0LWiTDdcV94Rkd8QudqJ456h2d9g5aER9mMzveJkOHSRoVMd0QZy1DV4v4ZhTN0BbQxiiqiMOciikVb66Mzc4sJpxIlvL1KIA9Oe596n1qoRwoFPUDRl93TpTUf_Y6taGzt9fZ8_7NU37SKW8FAf_j9tuf8F3lelnLckYESagU7D8aQYbpjFPxgK4DHsZFxPh9qVKALiQikvh4ywX9LvmR-0CnScqpi9dw4HW73oEb0ekvYZokTHofjnrR8cGHj8sIzLMI6uZpIUKkPWWZ0mV_eugder0NnFF-_WnP63vdynlXFyMvRveCZBPD9g6KdR6U1a3Ev6oT_nfbqUxeEi3fqW9jX3Psig92RLtLIAygDYSm14Ba0QJQHrWCDhwTNupWWCheuHlGQ1cVIA8c_X7jX1H5LnCWfT3TNgGXqq2PqpfOP0FFL4tvO4Fzhj1C4oX1E6pnhEcwLnioXEjM5Lzst05lNiYs7uQPLNuHRyI4cqPKx4fBWJUFeCoxvExt08im0bxSEKuVax5s9ApUBCXjKh5DVcEcEpYnRIaT19EqzdoAxtmt69KuaFOo7lSpSjtMGYGIRiwkKr8z_aoBl1SMSUhh56tWNtWJXavu0AKuqPNzbQao9m7XxeXkjhj_1Ww5S0Jdz-UE-xUEkM1l-Ya6rYpJrUyWWwSG_7uS_FtjaUS2kntLXlvZ31xdw85teXtNmmCjrGSJtg2yaeSzJr5V4W6FeKFnj9PrwUaRaryVYLX5rfGaRW2s65a5Js52DueGS83FayhVr3lDhypOpAmsoQid4XO4cEHrBxnF1ChRPfxa0oZq3dareri1dKtnvF7QrWYrzjEqqrcTq_rYlSkTKU-UHNSNWJHrcji5s3RQ_W_1TS8TtV1-_wLq5NLiiLUt32nSl9eNvisf0-1yGHLdSjTuU7d-8_6I5oXnecv6aCjIRDpl5b6o0lJ_rcxeXZL6JZjdZRHHc-xxLgmXrGz_Ra33lai0uboyOlYZ3GO8Kv4JweNdBF074DeS4dBsT6-Rod8kQyPXFxl_Re-NU-tUifvQQFkgFfCttBhdbp6O0LHk0UAZqnqVKdXuzVEf3Zc-UNrLhlXuVTjq1zpamhnKsnmzJLYGqL_wFA1_f73abU5fplOu-xlgUSa5sMVwc2ctPJv76zWh_M1uYvsvdJ0Xdp7KuT3BnngKvEm4somts0btt7i5Pls0F64VgzmMNmGNZCnX9mm8FYEGqh3tA3fpuBBqaKW4fDE6RQw1KNVMxU6pneA3JifFSO0EplzOvoMCmxAWOb7zVHLAKb8RCRwfLyM6JkUslew-oyspZHo756Hjj0mc032nyHAIpueMILETY0UVxwJ91V-1lN-4PP8PnbKj8g"> <figcaption>Figure 2: EVM Testing Toolchain - Using EIP Versioning Metadata during Test Fixture Consumption (<a href="https://mermaid.ink/svg/pako:eNqlWAtP40YQ_isjt4hHsUMgOe4sehLHo03F9RBcpUq4ijb2hmyx19Z6HZIS_ntnvfZm7QQUjiCEGY8_z-Pbb2fz5IRpRB3f2dp6YpxJH5625YQmdNvfjoh42H5-3toK-DhOH8MJERKubgIOkMt5TIHxrJDDVAzTQuIVWJ9civSB-vBT9-Pp2fnRfmVwH1kkJ34vmy1RxmwmC0FzWP28AUXSXA4FzVIh34FyMbh2u4dH8L5YFMrRYfeHUVpZMT4WZEhndD1S__RL_8Pla_GEKc-LhA4jJmgo34si4uzFrDZHofye8R_OaMKmFNZ_NkJZImFZhwWPqBiqWq9Hury8OOufvxbPKE7DhxWAt6KEMaNcDvN5LmnSjGcjlCVSzpIiJjIV61bVmMUxIvU-9Q_6x1YlcN0LWiTDdcV94Rkd8QudqJ456h2d9g5aER9mMzveJkOHSRoVMd0QZy1DV4v4ZhTN0BbQxiiqiMOciikVb66Mzc4sJpxIlvL1KIA9Oe596n1qoRwoFPUDRl93TpTUf_Y6taGzt9fZ8_7NU37SKW8FAf_j9tuf8F3lelnLckYESagU7D8aQYbpjFPxgK4DHsZFxPh9qVKALiQikvh4ywX9LvmR-0CnScqpi9dw4HW73oEb0ekvYZokTHofjnrR8cGHj8sIzLMI6uZpIUKkPWWZ0mV_eugder0NnFF-_WnP63vdynlXFyMvRveCZBPD9g6KdR6U1a3Ev6oT_nfbqUxeEi3fqW9jX3Psig92RLtLIAygDYSm14Ba0QJQHrWCDhwTNupWWCheuHlGQ1cVIA8c_X7jX1H5LnCWfT3TNgGXqq2PqpfOP0FFL4tvO4Fzhj1C4oX1E6pnhEcwLnioXEjM5Lzst05lNiYs7uQPLNuHRyI4cqPKx4fBWJUFeCoxvExt08im0bxSEKuVax5s9ApUBCXjKh5DVcEcEpYnRIaT19EqzdoAxtmt69KuaFOo7lSpSjtMGYGIRiwkKr8z_aoBl1SMSUhh56tWNtWJXavu0AKuqPNzbQao9m7XxeXkjhj_1Ww5S0Jdz-UE-xUEkM1l-Ya6rYpJrUyWWwSG_7uS_FtjaUS2kntLXlvZ31xdw85teXtNmmCjrGSJtg2yaeSzJr5V4W6FeKFnj9PrwUaRaryVYLX5rfGaRW2s65a5Js52DueGS83FayhVr3lDhypOpAmsoQid4XO4cEHrBxnF1ChRPfxa0oZq3dareri1dKtnvF7QrWYrzjEqqrcTq_rYlSkTKU-UHNSNWJHrcji5s3RQ_W_1TS8TtV1-_wLq5NLiiLUt32nSl9eNvisf0-1yGHLdSjTuU7d-8_6I5oXnecv6aCjIRDpl5b6o0lJ_rcxeXZL6JZjdZRHHc-xxLgmXrGz_Ra33lai0uboyOlYZ3GO8Kv4JweNdBF074DeS4dBsT6-Rod8kQyPXFxl_Re-NU-tUifvQQFkgFfCttBhdbp6O0LHk0UAZqnqVKdXuzVEf3Zc-UNrLhlXuVTjq1zpamhnKsnmzJLYGqL_wFA1_f73abU5fplOu-xlgUSa5sMVwc2ctPJv76zWh_M1uYvsvdJ0Xdp7KuT3BnngKvEm4somts0btt7i5Pls0F64VgzmMNmGNZCnX9mm8FYEGqh3tA3fpuBBqaKW4fDE6RQw1KNVMxU6pneA3JifFSO0EplzOvoMCmxAWOb7zVHLAKb8RCRwfLyM6JkUslew-oyspZHo756Hjj0mc032nyHAIpueMILETY0UVxwJ91V-1lN-4PP8PnbKj8g"/>view image as SVG</a>).</figcaption> </figure> ### EIP-4788 Case Study (as from the EIP, but with links to Github PRs) This section explores how the versioning scheme would be applied to an existing EIPs recently under active development at the time of writing as an example. The history of [EIP-4788](./eip-4788.md) contains many changes to its specification. EIP-4788 was updated to status "Review" on 2023-11-28, [#7992](https://github.com/ethereum/EIPs/pull/7992). This case study assumes, however, that the EIP moved to status "Review" on 2023-04-11, [#6859](https://github.com/ethereum/EIPs/pull/6859) and updated to version 1.0.0 due to the start of a client team implementation. #### Changelog - 9.0.1 - 2023-09-26: Update ring buffer size rationale for new ring buffer size [#7786](https://github.com/ethereum/EIPs/pull/7786). - 9.0.0 - 2023-09-26: Post audit tweaks [#7672](https://github.com/ethereum/EIPs/pull/7672). - Verify timestamp is non-zero. - Make `HISTORY_BUFFER_LENGTH` prime (8191). - Load calldata once. - Update `BEACON_ROOTS_ADDRESS`. - 8.0.1 - 2023-08-28: 4788 cleanups [#7532](https://github.com/ethereum/EIPs/pull/7532). - 8.0.0 - 2023-08-24: Initial stab at v2 [#7456](https://github.com/ethereum/EIPs/pull/7456). - Require timestamp input to be exactly 32 bytes. - Revert if timestamp input does not match stored value (instead of returning zeroed word). - Remove precompile concept, use regular smart contract with provided bytecode. - 7.0.3 - 2023-08-01: Mention genesis block with no existing beacon block root case [#7445](https://github.com/ethereum/EIPs/pull/7445). - 7.0.2 - 2023-07-07: Explicitly specify header schema [#7297](https://github.com/ethereum/EIPs/pull/7297). - 7.0.1 - 2023-07-07: Fix typo [#7293](https://github.com/ethereum/EIPs/pull/7293). - 7.0.0 - 2023-07-05: Bound precompile storage [#7178](https://github.com/ethereum/EIPs/pull/7178). - 6.0.1 - 2023-06-13: Clarify header and validity sections [#7179](https://github.com/ethereum/EIPs/pull/7179). - 6.0.0 - 2023-06-12: Update precompile address. [#7173](https://github.com/ethereum/EIPs/pull/7173). - 5.0.0 - 2023-05-31: Key beacon roots by root [#7107](https://github.com/ethereum/EIPs/pull/7107). - 4.0.0 - 2023-05-24: Favor stateful precompile over opcode [#7065](https://github.com/ethereum/EIPs/pull/7065). - 3.0.0 - 2023-05-17: Send current slot from CL to avoid timestamp conversions [#7037](https://github.com/ethereum/EIPs/pull/7037). - 2.0.1 - 2023-05-15: Fix typo [#7005](https://github.com/ethereum/EIPs/pull/7005). - 2.0.0 - 2023-05-03: Update opcode to avoid clash [#6980](https://github.com/ethereum/EIPs/pull/6980). - 1.0.1 - 2023-04-13: Minor nits [#6870](https://github.com/ethereum/EIPs/pull/6870). - 1.0.0 - 2023-04-11: Use block roots; update to status "Draft" [#6859](https://github.com/ethereum/EIPs/pull/6859). - Update to "Draft" due to client implementation ([NethermindEth/nethermind#5476](https://github.com/NethermindEth/nethermind/pull/5476)). - Use block roots instead of state roots. - Roots are stored keyed by slot. - Use of ring buffer in state. - Use header timestamps to derive slot numbers, rather than consume additional header space. - 0.2.1 - 2023-02-04: Update to status "Stagnant" [#6432](https://github.com/ethereum/EIPs/pull/6432). - 0.2.0 - 2022-06-29: Rename "beacon block root" to "beacon state root" [#5090](https://github.com/ethereum/EIPs/pull/5090). - 0.1.1 - 2022-05-06: Force usage of included LICENSE file [#5055](https://github.com/ethereum/EIPs/pull/5055). - 0.1.0 - 2022-02-17: Add EIP-4788: Beacon state root in EVM [#4788](https://github.com/ethereum/EIPs/pull/4788).