diff --git a/README.md b/README.md index b331248b..b2ee21b1 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,15 @@ 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-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 | diff --git a/eip-0009.md b/eip-0009.md new file mode 100644 index 00000000..36585757 --- /dev/null +++ b/eip-0009.md @@ -0,0 +1,142 @@ +# 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 (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 + +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) + +## 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 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 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`. + +##### 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. + + +#### 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). + +##### 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`. + +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. + +### 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. + +##### Example: AOTC to JITC switch + +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. + +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. +