ergoplatform · aslesarenko · Jun 4, 2020 · Sep 18, 2023 · Sep 18, 2023 · Sep 18, 2023
diff --git 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
@@ -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.
+