From 20e99a6f0c252a1f618bb9afa127ddefa3c4180f Mon Sep 17 00:00:00 2001 From: Alexander Slesarenko Date: Thu, 4 Jun 2020 13:17:31 +0300 Subject: [PATCH 1/2] eip-0009.md: Hard-fork Activation protocol (v1 to v2) --- eip-0009.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 eip-0009.md diff --git a/eip-0009.md b/eip-0009.md new file mode 100644 index 00000000..c6e60fe9 --- /dev/null +++ b/eip-0009.md @@ -0,0 +1,151 @@ +# EIP-0009: Hard-fork Activation protocol (v1 to v2) + +* Author: aslesarenko +* Status: Proposed +* Created: 04-Jun-2020 +* License: CC0 +* Forking: hard-fork needed + +## Contents +- [Description](#description) +- [Background And Motivation](#background-and-motivation) +- [Changes in EP2](#changes-in-ep2) +- [Activation of the Hard-Fork on Ergo network](#implementation-of-the-hard-fork-on-ergo-network) + - [Phase 1: Release v4.0.0](#phase-1-release-v400) + - [Phase 2: Release v4.0.1 (removing AOTC)](#phase-2-release-v401-removing-aotc) + +## Description +This EIP specifies a hard-fork activation protocol and the necessary implementation +details. For the sake of presentation the description is formulated in terms for switching +from Ergo Protocol v1 to Ergo Protocol v2 (EP1 to EP2). However, the protocol and +activation process are general enough to be repeated in future if the need arises. + +## Background And Motivation + +Ergo is designed to support consensus protocol evolution via soft-fork. Soft-forkability +is already implemented in EP1. However, some protocol changes require hard-fork, which is +a significant event is the network lifecycle. Therefore, it is especially important to +have clear, transparent, predictable, safe and well understood hard-fork activation +process. +The following sections describe the process using switch from EP1 to EP2 as an example. + +## Changes in EP2 + +### Change from AOTC to JITC +JIT costing (JITC pronounced "jitsy") can only be activated via hard-fork. It is not +possible to ensure that JITC always produces the same costs as AOTC by changing CostTable +parameters. This is because JITC is accurately accumulates the actual operations' cost and +AOTC is approximating both data sizes and speculating on potential costs in case of +branching logic. Please see detailed description of the changes in related [EIP8](eip-0008.md) + +### PoW Changes + TODO + +## Implementation of the Hard-Fork on Ergo network + +The activation is performed in two phases. The goal of the first phase is to collect +votes, select starting block for a hard-fork and perform safe switch. The second phase is +dedicated to code cleanup and optimizations enabled by the hard-fork. This is optional +and some verifiers may opt to not do this, however this is part of the whole transition. + +### Phase 1: Release v4.0.0. +This phase consists of the following steps, which are described in subsections: +1) voting until consensus on `HFVoted` status is achieved and `HFBlock` is defined, +waiting for `HFBlock` while following EP1 +3) switching to EP2 starting from `HFBlock` + +#### Selection of hard-forking block + +In this first HF release both EP1 and EP2 code will be available. EP1 will be +operational until HF voting is finished and HF switch is performed. The full nodes vote +for HF by running v4.0.0 release (which imply voting). Every node can check the voting +status using Block Extension section. Once the necessary voting threshold is achieved +(`HFVoted` status) in an epoch, the first block of the next epoch is the first hard-forked +block, we will refer to it as `HFBlock`. + +##### JITC Specific Part + It is important to ensure that JITC is functionally equivalent to AOTC for all the + blocks in `[1 .. HFBlock-1]` range. Here functional equivalence means that for each script + both AOTC and JITC should evaluate to the same result. + This property is necessary to remove the old v3.x ErgoTree interpreter and perform the + validation of historical blocks using the JITC interpreter alone. Since the history is + immutable, it is enough to check the equivalence by running both v3.x interpreter and + JITC on all the blocks up until `HFBlock`. + + Thus, all v4.0.0 nodes will run JITC interpreter in parallel with AOTC and compare the + results. If at any time the script results are different, then AOTC result is used in + the consensus and the problematic transaction is logged. In addition the _voting + is blocked_, by the node. If AOTC validates the problematic transaction it still should + be added to the blockchain to support current consensus among v4.0.0 and older nodes. + This will lead to all v4.0.0 nodes stop voting, thus preventing the HF switch. + + If voting is blocked (which is exceptional case), then a fix in JITC is required, so new + v4.0.1 release should be create and the HF process should start from scratch. + + If voting is not blocked and `HFVoted` network status is achieved, then majority of + nodes are running v4.0.0 version. In this case the validation of the first block after + `HFVoted` (let's call it `HFVotedBlock`) require both AOTC and JITC have strictly the + same result. Transactions which invalidate this property should be rejected by all + v4.0.0 nodes (which are now the majority). This will ensure that in the block range + `[HFVotedBlock .. HFBlock]` AOTC and JITC are functionally equivalent. + + + +##### PoW Specific Part + TODO + +#### Switching EP1 to EP2 + +When voting is not blocked, `HFVoted` status is achieved and `HFBlock` is selected then +all the v4.0.0 nodes need to switch from EP1 to EP2 starting from `HFBlock`. +This switch is implemented as `if` statements in the block validation code of v4.0.0 +release. + +Thus, starting from `HFBlock`, EP2 is used for all new block validation and EP1 is +turned-off (the code is not executed) and the network is operating according to a new +consensus (Ergo Protocol v2). + +##### JITC Specific Part +Now, because the v2 consensus is based on JITC there is an opportunity to fix bugs and +add new features to ErgoTree, which are all enabled starting from `HFBlock`. + +NOTE, both fixes and new features should keep backward compatibility of applications in +mind. + +The fixes in JITC for v2 protocol, however, may be not compatible with v1 protocol. +This will require JITC interpreter to have an internal branching logic having both +versions of the protocol. Thus JITC v4.0.0 will process historical blocks according to +Ergo Protocol v1 and starting from `HFBlock` as Ergo Protocol v2. This will ensure, that +each v4.x release will successfully validate all historical blocks. + +##### PoW Specific Part + +### Phase 2: Release v4.0.1 (removing AOTC) + +##### JITC Specific Part + +This version can be released after `HFBlock` and should include JITC supporting +ErgoProtocol v1 and v2. The main goal of this release is to remove v3.x AOTC ErgoTree +interpreter from the code to simplify reference implementation. + +Update of the node to v4.0.1 shouldn't require node re-sync. For new nodes joining the +network, v4.0.1 will use JITC to validate both historical and new blocks. This is +possible since AOTC is conservative/pessimistic in estimating actual script costs. Thus, +JITC can relax script costs 2-3x so that all the historical blocks which are valid under +AOTC can also be valid under JITC. Thus, JITC will never invalidate historical blocks +due to costing and other invalidation reasons were prevented on the Phase 1 (by checking +functional equivalence). + +Together with removed AOTC code, the HF switching condition can be simplified. Starting +from v4.0.1 release it can be based on using the known `HFBlock` constant in the code. +Switching based on hard-fork voting and `HFVoted` status is no-longer necessary and can +be disabled. The HF activation code itself, however, can be reused in the next HF voting +and activation. + +##### PoW Specific Part + TODO + +### Hard-Fork Voting Implementation + TODO + + From 5ebb46776b704ced2f8cdf7ac19f36c89efb7d1e Mon Sep 17 00:00:00 2001 From: Alexander Slesarenko Date: Mon, 18 Sep 2023 18:17:12 +0200 Subject: [PATCH 2/2] eip9: refreshed description --- README.md | 37 ++++++++++----------- eip-0009.md | 93 ++++++++++++++++++++++++----------------------------- 2 files changed, 61 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 977b8891..55162a9e 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,23 @@ Ergo Improvement Proposals (EIPs) specify and/or describe standards for the Ergo Please check out existing EIPs, such as [EIP-1](eip-0001.md), to understand the general expectation of how EIPs are supposed to be formatted. -| Number | Title | -| --- | --- | -| [EIP-0001](eip-0001.md) | Application-Friendly Wallet API | -| [EIP-0002](eip-0002.md) | Ergo grant program | -| [EIP-0003](eip-0003.md) | Deterministic Wallet Standard | -| [EIP-0004](eip-0004.md) | Assets standard | -| [EIP-0005](eip-0005.md) | Contract Template | +| Number | Title | +|-------------------------|-------------------------------------------------------| +| [EIP-0001](eip-0001.md) | Application-Friendly Wallet API | +| [EIP-0002](eip-0002.md) | Ergo grant program | +| [EIP-0003](eip-0003.md) | Deterministic Wallet Standard | +| [EIP-0004](eip-0004.md) | Assets standard | +| [EIP-0005](eip-0005.md) | Contract Template | | [EIP-0006](eip-0006.md) | Informal Smart Contract Protocol Specification Format | -| [EIP-0017](eip-0017.md) | Proxy Contracts | -| [EIP-0019](eip-0019.md) | Cold Wallet Protocol | -| [EIP-0020](eip-0020.md) | ErgoPay Protocol | -| [EIP-0021](eip-0021.md) | Genuine tokens verification | -| [EIP-0022](eip-0022.md) | Auction Contract | -| [EIP-0024](eip-0024.md) | Artwork Standard | -| [EIP-0025](eip-0025.md) | Payment Request URI | -| [EIP-0027](eip-0027.md) | Emission Retargeting Soft-Fork | -| [EIP-0031](eip-0031.md) | Babel Fees | -| [EIP-0034](eip-0034.md) | NFT Collection Standard | -| [EIP-0039](eip-0039.md) | Monotonic box creation height rule | \ No newline at end of file +| [EIP-0009](eip-0009.md) | Hard-fork Activation protocol | +| [EIP-0017](eip-0017.md) | Proxy Contracts | +| [EIP-0019](eip-0019.md) | Cold Wallet Protocol | +| [EIP-0020](eip-0020.md) | ErgoPay Protocol | +| [EIP-0021](eip-0021.md) | Genuine tokens verification | +| [EIP-0022](eip-0022.md) | Auction Contract | +| [EIP-0024](eip-0024.md) | Artwork Standard | +| [EIP-0025](eip-0025.md) | Payment Request URI | +| [EIP-0027](eip-0027.md) | Emission Retargeting Soft-Fork | +| [EIP-0031](eip-0031.md) | Babel Fees | +| [EIP-0034](eip-0034.md) | NFT Collection Standard | +| [EIP-0039](eip-0039.md) | Monotonic box creation height rule | \ No newline at end of file diff --git a/eip-0009.md b/eip-0009.md index c6e60fe9..36585757 100644 --- a/eip-0009.md +++ b/eip-0009.md @@ -17,8 +17,9 @@ ## Description This EIP specifies a hard-fork activation protocol and the necessary implementation details. For the sake of presentation the description is formulated in terms for switching -from Ergo Protocol v1 to Ergo Protocol v2 (EP1 to EP2). However, the protocol and -activation process are general enough to be repeated in future if the need arises. +from Ergo Protocol v1 (v3.x releases) to Ergo Protocol v2 (v4.x releases), hereinafter +called EP1 to EP2. However, the protocol and activation process are general enough to be +repeated in future if the need arises. ## Background And Motivation @@ -38,9 +39,6 @@ parameters. This is because JITC is accurately accumulates the actual operations AOTC is approximating both data sizes and speculating on potential costs in case of branching logic. Please see detailed description of the changes in related [EIP8](eip-0008.md) -### PoW Changes - TODO - ## Implementation of the Hard-Fork on Ergo network The activation is performed in two phases. The goal of the first phase is to collect @@ -58,42 +56,40 @@ waiting for `HFBlock` while following EP1 In this first HF release both EP1 and EP2 code will be available. EP1 will be operational until HF voting is finished and HF switch is performed. The full nodes vote -for HF by running v4.0.0 release (which imply voting). Every node can check the voting +for HF by running v4.0.0 release, which behaves as v3.x, but imply voting. Every node can check the voting status using Block Extension section. Once the necessary voting threshold is achieved -(`HFVoted` status) in an epoch, the first block of the next epoch is the first hard-forked -block, we will refer to it as `HFBlock`. - -##### JITC Specific Part - It is important to ensure that JITC is functionally equivalent to AOTC for all the - blocks in `[1 .. HFBlock-1]` range. Here functional equivalence means that for each script - both AOTC and JITC should evaluate to the same result. - This property is necessary to remove the old v3.x ErgoTree interpreter and perform the - validation of historical blocks using the JITC interpreter alone. Since the history is - immutable, it is enough to check the equivalence by running both v3.x interpreter and - JITC on all the blocks up until `HFBlock`. - - Thus, all v4.0.0 nodes will run JITC interpreter in parallel with AOTC and compare the - results. If at any time the script results are different, then AOTC result is used in - the consensus and the problematic transaction is logged. In addition the _voting - is blocked_, by the node. If AOTC validates the problematic transaction it still should - be added to the blockchain to support current consensus among v4.0.0 and older nodes. - This will lead to all v4.0.0 nodes stop voting, thus preventing the HF switch. +(`HFVoted` status is reached) in an epoch we know enough mining nodes upgraded and are running v4.0.0 release. +We therefore can define the first block of the next epoch as the first hard-forked +block. We will refer to it as `HFBlock`. - If voting is blocked (which is exceptional case), then a fix in JITC is required, so new - v4.0.1 release should be create and the HF process should start from scratch. - - If voting is not blocked and `HFVoted` network status is achieved, then majority of - nodes are running v4.0.0 version. In this case the validation of the first block after - `HFVoted` (let's call it `HFVotedBlock`) require both AOTC and JITC have strictly the - same result. Transactions which invalidate this property should be rejected by all - v4.0.0 nodes (which are now the majority). This will ensure that in the block range - `[HFVotedBlock .. HFBlock]` AOTC and JITC are functionally equivalent. +##### Example: AOTC to JITC switch + +It is important to ensure that JITC is functionally equivalent to AOTC for all the +blocks in `[1 .. HFBlock-1]` range. Here functional equivalence means that for each script +both AOTC and JITC should evaluate to the same result. +This property is necessary to remove the old v3.x ErgoTree interpreter and perform the +validation of historical blocks using the JITC interpreter alone. Since the history is +immutable, it is enough to check the equivalence by running both v3.x interpreter and +JITC on all the blocks up until `HFBlock`. + +Thus, all v4.0.0 nodes will run JITC interpreter in parallel with AOTC and compare the +results. If at any time the script results are different, then AOTC result is used in +the consensus and the problematic transaction is logged. In addition the _voting +is blocked_, by the node. If AOTC validates the problematic transaction it still should +be added to the blockchain to support current consensus among v4.0.0 and older nodes. +This will lead to all v4.0.0 nodes stop voting, thus preventing the HF switch. + +If voting is blocked (which is exceptional case), then a fix in JITC is required, so new +v4.0.1 release should be create and the HF process should start from scratch. + +If voting is not blocked and `HFVoted` network status is achieved, then majority of +nodes are running the latest v4.x version. In this case the validation of the first block after +`HFVoted` (let's call it `HFVotedBlock`) require both AOTC and JITC have strictly the +same result. Transactions which invalidate this property should be rejected by all +v4.0.0 nodes (which are now the majority). This will ensure that in the block range +`[HFVotedBlock .. HFBlock]` AOTC and JITC are functionally equivalent. - -##### PoW Specific Part - TODO - #### Switching EP1 to EP2 When voting is not blocked, `HFVoted` status is achieved and `HFBlock` is selected then @@ -105,7 +101,7 @@ Thus, starting from `HFBlock`, EP2 is used for all new block validation and EP1 turned-off (the code is not executed) and the network is operating according to a new consensus (Ergo Protocol v2). -##### JITC Specific Part +##### Example: AOTC to JITC switch Now, because the v2 consensus is based on JITC there is an opportunity to fix bugs and add new features to ErgoTree, which are all enabled starting from `HFBlock`. @@ -114,17 +110,19 @@ mind. The fixes in JITC for v2 protocol, however, may be not compatible with v1 protocol. This will require JITC interpreter to have an internal branching logic having both -versions of the protocol. Thus JITC v4.0.0 will process historical blocks according to +versions of the protocol. Thus, JITC v4.0.0 will process historical blocks according to Ergo Protocol v1 and starting from `HFBlock` as Ergo Protocol v2. This will ensure, that each v4.x release will successfully validate all historical blocks. -##### PoW Specific Part - -### Phase 2: Release v4.0.1 (removing AOTC) +### Phase 2: Release v4.0.x (removing AOTC) + +This version can be released after `HFBlock` and should include code supporting +ErgoProtocol v1 and v2. The main goal of this release is to remove unnecessary code to +simplify reference implementation. -##### JITC Specific Part +##### Example: AOTC to JITC switch -This version can be released after `HFBlock` and should include JITC supporting +v4.0.x version can be released after `HFBlock` and should include JITC supporting ErgoProtocol v1 and v2. The main goal of this release is to remove v3.x AOTC ErgoTree interpreter from the code to simplify reference implementation. @@ -142,10 +140,3 @@ Switching based on hard-fork voting and `HFVoted` status is no-longer necessary be disabled. The HF activation code itself, however, can be reused in the next HF voting and activation. -##### PoW Specific Part - TODO - -### Hard-Fork Voting Implementation - TODO - -