ICON2.0 Migration Guide

Important
The ICON1 node server must be maintained after STAGE3 until the migration is completed.
It should be turned off when the Foundation announces that the migration is complete.
If you are P-Rep, you must use the Keystore file used in ICON1.
If you’re not using a dual key setup, use your original registration key.
If you’re using a dual key setup, use the second key (not the registration key).
Migration Plan
Top 30 P-Reps participating in Stage2 must fill up this form before starting https://forms.gle/PvyMVDH98DBzn2op7​
Before Stage2, top 30 P-Reps must update to the latest ICON1 node version (iconloop/prep-node:20211012.0).
Other node operators can wait for further instructions to setup ICON2 - goloop node once the network migration is fully completed. Until then please keep your ICON1 node running as before.
There are three stages in the migration.
Summary of stages
[Completed] STAGE1: Migrate data from ICON1.
[Complete] STAGE2: Download the migrated data and Start an ICON2 node. [Action required - PRep]
[In Progress] STAGE3: [Action required - PRep and Exchanges ]
Send a Proposal (Foundation) → Vote a Proposal (PReps) → Complete consensus
The Foundation announces the changes. ICON1 node will be stopped.
Exchanges should stop deposits and withdrawals. [Action required - Exchanges ]
Switch to the ICON2 network
Complete migration
Timetable of migration
Stage time (KST)
Actions
10/25 10:00
Stage 1-2
Who: Foundation
10/26
Who: Foundation
Test with migrated real ICON2 data
10/26
Who: Foundation
Deploy to guide documents
10/27 11:00
Stage2
Who: P-Rep
11/03 22:00
Stage3-1
Who: Exchange / Citizen
11/03 23:00
Stage3-2
Who: Foundation
11/03 23:30
Stage3-3
Who: P-Rep
11/03 23:40
Stage 3-4
Who: P-Rep
11/03 ~23:59
Stage3-5
Who: P-Rep
11/04 00:00
Announcement
Who: Foundation
11/04 00:00
Stage3-6
Who: P-Rep
11/04 00:30
Who: Foundation
Wait for all ICON2 nodes reached stopped state
11/04 00:30
Who: Foundation
Stop Migrators
11/04 01:00
Who: Foundation
Start Migrators
11/04 01:10
Announcement
Who: Foundation
11/04 01:10
Stage3-7
Who: P-Rep
11/04 01:10
Stage 3-8
Who: P-Rep & Foundation
11/04 01:40
Who: Foundation
Start Citizen node
11/04 02:00
Announcement
Who: Foundation
11/04 02:00
Who: Foundation
Migration details
Top 30 P-Reps must update their loopchain node before starting Stage2. This update will make ICON1 stop creating blocks after Revision 13.
Please update citizen node following guideline before October 26th. Please try to update your node right after your leader turn if you're Main P-Rep.
Using docker
Check your docker image tag settings in docker-compose.yml and change the tag to below
image: iconloop/prep-node:20211012.0
Enter the following commands in order
1
docker-compose pull
2
docker-compose down
3
docker-compose up -d
Using snap
​https://snapcraft.io/loopchain​
Using citizen pack or binary
​https://github.com/icon-project/icon-release/releases/tag/20211012.0​
STAGE1
Migrate data to 5 node servers provided by the Foundation. When the current block height of ICON1 is reached, upload a backup file of migrated ICON2 data. We tested the compressed backup file and original file as follows.
Text
Using compressed database file
Using original database file
Information of migrated backup file
file size : 1.2TB over
file count: 31,000 over files
​
Download time
900GB (compress with zstd)
02 hour 08 min (1Gbps)
01 hour 04 min (2Gbps)
00 hour 32 min (4Gbps)
1.2 TB (uncompressed)
02 hour 51 min (1Gbps)
01 hour 25 min (2Gbps)
00 hour 42 min (4Gbps)
Decompress time
900GB (compress with zstd on c5.4xlarge)
02 hour 10 min
0 min
Total estimated time
04 hour 18 min (1Gbps)
03 hour 14 min (2Gbps)
02 hour 46min (4Gbps)
02 hour 51 min (1Gbps)
01 hour 25 min (2Gbps)
00 hour 42 min (4Gbps)
STAGE2
STAGE2 Each PRep prepares a new server for ICON2 and copy the Keystore file from another ICON1 server.
If you are P-Rep, you must use the Keystore file used in ICON1.
Action items of STAGE2 for P-Reps
1.Provide the new ICON2 node’s Public IP address for monitoring https://forms.gle/PvyMVDH98DBzn2op7​
2.Prepare ICON2 node (https://github.com/icon-project/icon2-docker)
1.Create a new server for ICON2
2.Copy keystore file from ICON1 node to ICON2 node
3.Download the ICON2 image or build the image. (iconloop/icon2-node)
4.Start the new ICON2 node
5.The following tasks are automatically executed as environment variables of docker
1.Download the migrated ICON2 block data
2.Start ICON2 node in container
3.Join the ICON2 Network
4.Start import (The blocks after the backup DB are additionally synchronized)
6.Monitor whether it reaches latest height of ICON1 with below command
3.Wait and keep the icon1
1
# docker exec -it icon2-node goloop chain ls
2
[
3
  {
4
    "cid": "0x1",
5
    "nid": "0x1",
6
    "channel": "icon_dex",
7
    "state": "import_icon 39314952 running",
8
    "height": 4830,
9
    "lastError": ""
10
  }
11
]
STAGE3
Switch the ICON2 Network
Action items of STAGE3
During this last stage, exchanges should stop deposits and withdrawals.
The Foundation will let you know when you can setup your ICON2 citizen nodes. Once you are ready, you can resume normal operations.
Instructions for the ICON Foundation
Stage 3-1
Block the network endpoint(ctz.solidwallet.io, wallet.icon.foundation) and prevent the creation of new Transactions.
Stop all ICON1 citizens.
STAGE3-2
Send a transaction for a new revision (ICON2 Revision).
Send a Proposal
STAGE3-3
Wait for consensus proposal to be completed.
STAGE3-4
ICON1 node and Citizen node will enter suspend state.
STAGE3-5
ICON2 node is changed to import_icon xxx finished state.
Wait for all ICON2 nodes reach to the target.
a. ICON1 consensus will stop at the target.
b. ICON2 import will stop at the target
Announcement
The Foundation notifies PReps to enter a command: chain stop
STAGE3-6
Enter the following command to confirm end of migration
$ docker exec -it icon2-node goloop chain ls
[ { "cid": "0x1", "nid": "0x1", "channel": "icon_dex", "state": "import_icon 40123455 finished", "height": 6830, "lastError": "" } ]
Stop ICON2 migration task
Stop chain
docker exec -it icon2-node goloop chain stop 0x1
Then ICON2 will fall in import_icon finished status after erasing all temporal data. To see the last block height, you need to stop again.
Stop chain
docker exec -it icon2-node goloop chain stop 0x1
Wait for all ICON2 nodes reach to the target.

Announcement
The Foundation notifies PReps to enter a command: chain start
STAGE3-7
Start chain
docker exec -it icon2-node goloop chain start 0x1
Switch the ICON2 network and Start ICON2 consenesus.
STAGE3-8
PRep Completed migrations
STAGE3-9
Foundation will make backup data with backup node(ICON2 Real data). We'll let you know If we're ready.
Announcement
Announce a successful migration
End of migration
​🚀
​
Instructions for P-Reps
Stage 3-1
If you are running a citizen node, stop it.
STAGE3-2
Vote on the proposal with preptools.
P-Reps can't vote on icon.community. Use preptools to change the endpoint to your own ICON1 node P-Reps and vote.
STAGE3-3
Wait for consensus proposal to be completed.
STAGE3-4
ICON1 node and Citizen node will enter suspend state.
STAGE3-5
ICON2 node is changed to import_icon xxx finished state.
Wait for all ICON2 nodes reach to the target.
a. ICON1 consensus will stop at the target.
b. ICON2 import will stop at the target
Announcement
The Foundation notifies PReps to enter a command: chain stop
STAGE3-6
Enter the following command to confirm end of migration

$ docker exec -it icon2-node goloop chain ls
[ { "cid": "0x1", "nid": "0x1", "channel": "icon_dex", "state": "import_icon 40123455 finished", "height": 6830, "lastError": "" } ]
Stop ICON2 migration task
Stop chain
docker exec -it icon2-node goloop chain stop 0x1
Then ICON2 will fall in “import_icon finished” status after erasing all temporal data. To see the last block height, you need to stop again.
Stop chain
docker exec -it icon2-node goloop chain stop 0x1
Wait for all ICON2 nodes reach to the target.
Announcement
The Foundation notifies PReps to enter a command: chain start
STAGE3-7
Start chain
docker exec -it icon2-node goloop chain start 0x1
Switch the ICON2 network and Start ICON2 consenesus.
STAGE3-8
PRep Completed migrations
STAGE3-9
Monitor whether consensus is reached and blocks are created.
Announcement
Shut down old ICON1 server.
End of migration
​🚀
​
Instructions for Citizen node (Exchanges)
Stage 3-1
Exchanges should stop deposits and withdrawals.
STAGE3-2
No action is required.
STAGE3-3
No action is required.
STAGE3-4
ICON1(Citizen) node will enter suspend state. ICON1 citizen node can’t generate the new block. But It is possible to query the transactions.
STAGE3-5
No action is required.
Announcement
The Foundation notifies PReps to enter a command: chain stop
STAGE3-6
Wait and keep the icon1 citizen node.
No action is required.
Announcement
The Foundation notifies PReps to enter a command: chain start
STAGE3-7
Wait and keep the icon1 citizen node.
No action is required.
STAGE3-8
Wait and keep the icon1 citizen node.
No action is required.
STAGE3-9
If we ready, let you know. Recover citizens with the backup. Start the ICON2 node.
Announcement
If you are ready, please resume deposits and withdrawals.
End of migration
​🚀
​
​