#v2.0

This is an archived guide. v2.0.X has been deprecated.

Initially, you might have created your BridgeChain using ARK Node , the official v1 implementation. Now that ARK Core (v2) has reached a stable, production-ready release, you will want to upgrade your network.

Depending on the size of your BridgeChain network, upgrading to ARK Core may need more or less preparation. Upgrading is a breaking change, and all v1 nodes will become incompatible with your new network. You should ensure that your users are aware of the upgrade, and node operators have time to adequately prepare for the migration, as they will need to update their tools and code bases.

#Initial Preparation

Ensure you have correctly mapped all participants in your network. You should be able to answer the following questions:

• How many node operators are there, and am I able to contact all of them?
• Are services dependent on my network, such as exchanges or third party apps?

During the migrations, third-party providers and exchanges should ensure they stop accepting transactions, as there is a gap where the blockchain is possibly rolled back a few hundred blocks. Once the migration is completed, these services must ensure they are not on a forked network; it is best to wait a few hours to a day until everyone is sure a network consensus has been reached.

All node operators must cooperate in the migration. (Technically http://0.0.0.0:8080y only > 50% of the delegates need to migrate. However, you should avoid a community split). We recommend establishing a dedicated communication channel, monitored by your team during the entire migration process, so that you may provide assistance.

Together with your node operators, it would be best if you decided on a cutoff block height, after this height, v1 will no longer be supported in your BridgeChain, and services relying on v1 nodes may break and should be considered unreliable.

#Setting the BridgeChain Configuring

The new v2 implementation is backward compatible with v1; thus we can deploy our new nodes without forcing a migration. Your BridgeChain configuration is defined by the following files, which are needed by v2 as well.

• config.mainnet.json
• genesisBlock.json

Clone ARK Core so that we can configure our network. Make sure to verify that you have the latest tag.

1git clone [email protected]:arkecosystem/core
2git checkout tags/<2.0.X> -b <branch_name>
3cd core

Create a new directory in packages/core/lib/config for your BridgeChain configurations.

1cd packages/core/lib/config
2mkdir MyNet

The following files are required to make v2 compatible with your custom network.

• genesisBlock.json: defines the very first block of your network, and from it your networkHash is derived, as it is the header of the first block.
• peers.json: used by the node to find other existing nodes. The file resembles something like this:

 1{
 2"minimumVersion": ">=0",
 3"minimumNetworkReach": 20,
 4"globalTimeout": 5000,
 5"coldStart": 30,
 6"whiteList": [],
 7"blackList": [],
 8"list": [
 9{
10    "ip": "5.196.105.32",
11    "port": 4001
12},

minimumVersion is of special interest to use, as we will use it later to evict all v1 nodes from our network. Ensure it is not set to >=2.X.X, as your new node will not be able to sync due to it banning existing v1 nodes.

• plugins.js: contains default configurations for your node. You can copy the below file for sane defaults and edit them later. These are not very relevant to the migration.

 1module.exports = {
 2    "@arkecosystem/core-event-emitter": {},
 3    "@arkecosystem/core-logger-winston": {
 4        transports: {
 5            console: {
 6                options: {
 7                    level: process.env.ARK_LOG_LEVEL || "debug"
 8                }
 9            },
10            dailyRotate: {
11                options: {
12                    level: process.env.ARK_LOG_LEVEL || "debug"
13                }
14            }
15        }
16    },
17    "@arkecosystem/core-database-postgres": {
18        connection: {
19            host: process.env.ARK_DB_HOST || "localhost",
20            port: process.env.ARK_DB_PORT || 5432,
21            database: process.env.ARK_DB_DATABASE || `ark_${process.env.ARK_NETWORK_NAME}`,
22            user: process.env.ARK_DB_USERNAME || "ark",
23            password: process.env.ARK_DB_PASSWORD || "password"
24        }
25    },
26    "@arkecosystem/core-transaction-pool-mem": {
27        enabled: !process.env.ARK_TRANSACTION_POOL_DISABLED,
28        maxTransactionsPerSender: process.env.ARK_TRANSACTION_POOL_MAX_PER_SENDER || 300,
29        allowedSenders: []
30    },
31    "@arkecosystem/core-p2p": {
32        host: process.env.ARK_P2P_HOST || "0.0.0.0",
33        port: process.env.ARK_P2P_PORT || 4001,
34        whitelist: ["127.0.0.1", "::ffff:127.0.0.1"]
35    },
36    "@arkecosystem/core-blockchain": {
37        fastRebuild: false
38    },
39    "@arkecosystem/core-api": {
40        enabled: !process.env.ARK_API_DISABLED,
41        host: process.env.ARK_API_HOST || "0.0.0.0",
42        port: process.env.ARK_API_PORT || 4003,
43        whitelist: ["*"]
44    },
45    "@arkecosystem/core-webhooks": {
46        enabled: process.env.ARK_WEBHOOKS_ENABLED,
47        server: {
48            enabled: process.env.ARK_WEBHOOKS_API_ENABLED,
49            host: process.env.ARK_WEBHOOKS_HOST || "0.0.0.0",
50            port: process.env.ARK_WEBHOOKS_PORT || 4004,
51            whitelist: ["127.0.0.1", "::ffff:127.0.0.1"]
52        }
53    },
54    "@arkecosystem/core-graphql": {
55        enabled: process.env.ARK_GRAPHQL_ENABLED,
56        host: process.env.ARK_GRAPHQL_HOST || "0.0.0.0",
57        port: process.env.ARK_GRAPHQL_PORT || 4005
58    },
59    "@arkecosystem/core-forger": {
60        hosts: [`http://127.0.0.1:${process.env.ARK_P2P_PORT || 4001}`]
61    },
62    "@arkecosystem/core-json-rpc": {
63        enabled: process.env.ARK_JSON_RPC_ENABLED,
64        host: process.env.ARK_JSON_RPC_HOST || "0.0.0.0",
65        port: process.env.ARK_JSON_RPC_PORT || 8080,
66        allowRemote: false,
67        whitelist: ["127.0.0.1", "::ffff:127.0.0.1"]
68    },
69    "@arkecosystem/core-snapshots": {}
70};

Your directory MyNet should now contain genesisBlock.json, peers.json, and a plugins.js. If you use the terms mainnet, devnet and testnet in your BridgeChain, you should create configuration directories for each of these networks, overriding the existing directories.

Next, we need to edit our scripts to use the new configurations. From your git root, open packages/core/bin/ark. Edit the file, removing references of ark and replacing it with your BridgeChain name. These changes are for cosmetic purposes only.

Open packages/core/package.json. Here the common startup scripts are defined. You can read more on how these work in the node lifecycle section. We are interested in the scripts key.

 1"scripts": {
 2    "debug:start": "node --inspect-brk ./bin/ark start",
 3    "debug:relay": "node --inspect-brk ./bin/ark relay",
 4    "debug:forger": "node --inspect-brk ./bin/ark forger",
 5    "debug:snapshot": "node --inspect-brk ./bin/ark snapshot",
 6    "start": "./bin/ark start",
 7    "start:mainnet": "./bin/ark start --config ./lib/config/mainnet --network mainnet",
 8    "start:devnet": "./bin/ark start --config ./lib/config/devnet --network devnet",
 9    "start:testnet": "cross-env ARK_ENV=test ./bin/ark start --config ./lib/config/testnet --network testnet",
10    "start:testnet:live": "./bin/ark start --config ./lib/config/testnet.live --network testnet",
11    "relay": "./bin/ark relay",
12    "relay:mainnet": "./bin/ark relay --config ./lib/config/mainnet --network mainnet",
13    "relay:devnet": "./bin/ark relay --config ./lib/config/devnet --network devnet",
14    "relay:testnet": "cross-env ARK_ENV=test ./bin/ark relay --config ./lib/config/testnet --network testnet",
15    "relay:testnet:live": "./bin/ark relay --config ./lib/config/testnet.live --network testnet",
16    "forger": "./bin/ark forger",
17    "forger:mainnet": "./bin/ark forger --config ./lib/config/mainnet --network mainnet",
18    "forger:devnet": "./bin/ark forger --config ./lib/config/devnet --network devnet",
19    "forger:testnet": "cross-env ARK_ENV=test ./bin/ark forger --config ./lib/config/testnet --network testnet",
20    "forger:testnet:live": "./bin/ark forger --config ./lib/config/testnet.live --network testnet",
21    "snapshot": "./bin/ark snapshot",
22    "snapshot:mainnet": "./bin/ark snapshot --config ./lib/config/mainnet --network mainnet",
23    "snapshot:devnet": "./bin/ark snapshot --config ./lib/config/devnet --network devnet",
24    "snapshot:testnet": "./bin/ark snapshot --config ./lib/config/testnet --network testnet",
25    "snapshot:testnet:live": "./bin/ark snapshot --config ./lib/config/testnet.live --network testnet",
26    "full:testnet": "cross-env ARK_ENV=test ./bin/ark start --config ./lib/config/testnet --network testnet --network-start",
27    "full:testnet:live": "./bin/ark start --config ./lib/config/testnet.live --network testnet --network-start",
28    "full:testnet:2tier:2": "cross-env ARK_ENV=test ./bin/ark start --config ./lib/config/testnet.2 --network testnet --network-start",
29    "full:testnet:2tier:1": "cross-env ARK_ENV=test ./bin/ark start --config ./lib/config/testnet.1 --network testnet --network-start",
30    "full:testnet:2tier": "cross-env ARK_ENV=test ./bin/ark start --config ./lib/config/testnet.1 --network testnet --network-start && ./bin/ark start --config ./lib/config/testnet.2 --network testnet --network-start",
31    "lint": "eslint ./ --fix"
32},

Some of these commands use the --config option. This accepts a relative directory as its parameter, pointing to our pre-created configuration directories. If you altered the existing mainnet, devnet and testnet directories, these commands will now work with your configurations.

We will continue this guide using the name MyNet, as that means we cover all options and places to edit. Add the following lines to scripts:

1"start:MyNet": "./bin/ark start --config ./lib/config/MyNet --network MyNet",
2"relay:MyNet": "./bin/ark relay --config ./lib/config/MyNet --network MyNet",
3"forger:MyNet": "./bin/ark forger --config ./lib/config/MyNet --network MyNet",
4"snapshot:MyNet": "./bin/ark snapshot --config ./lib/config/MyNet --network MyNet",

These shortcut commands will use your custom configurations.

We will also need to edit our snapshot commands, which we will use later on to jump-start our v2 network. Go to core/packages/core-snapshot-cli and open package.json. Once again we are interested in the scripts section.

 1"scripts": {
 2    "start": "./bin/snapshot",
 3    "debug": "node --inspect-brk ./bin/snapshot",
 4    "create:mainnet": "./bin/snapshot create --config ../core/lib/config/mainnet --network mainnet",
 5    "create:devnet": "./bin/snapshot create --config ../core/lib/config/devnet --network devnet",
 6    "create:testnet": "./bin/snapshot create --config ../core/lib/config/testnet --network testnet",
 7    "import:mainnet": "./bin/snapshot import --config ../core/lib/config/mainnet --network mainnet",
 8    "import:devnet": "./bin/snapshot import --config ../core/lib/config/devnet --network devnet",
 9    "import:testnet": "./bin/snapshot import --config ../core/lib/config/testnet --network testnet",
10    "verify:mainnet": "./bin/snapshot verify --config ../core/lib/config/mainnet --network mainnet",
11    "verify:devnet": "./bin/snapshot verify --config ../core/lib/config/devnet --network devnet",
12    "verify:testnet": "./bin/snapshot verify --config ../core/lib/config/testnet --network testnet",
13    "rollback:mainnet": "./bin/snapshot rollback --config ../core/lib/config/mainnet --network mainnet",
14    "rollback:devnet": "./bin/snapshot rollback --config ../core/lib/config/devnet --network devnet",
15    "rollback:testnet": "./bin/snapshot rollback --config ../core/lib/config/testnet --network testnet",
16    "truncate:mainnet": "./bin/snapshot truncate --config ../core/lib/config/mainnet --network mainnet",
17    "truncate:devnet": "./bin/snapshot truncate --config ../core/lib/config/devnet --network devnet",
18    "truncate:testnet": "./bin/snapshot truncate --config ../core/lib/config/testnet --network testnet",
19    "test": "cross-env ARK_ENV=test jest --runInBand --detectOpenHandles",
20    "test:coverage": "cross-env ARK_ENV=test jest --coverage --runInBand --detectOpenHandles",
21    "test:debug": "cross-env ARK_ENV=test node --inspect-brk ../../node_modules/.bin/jest --runInBand --watch",
22    "test:watch": "cross-env ARK_ENV=test jest --runInBand --watch",
23    "test:watch:all": "cross-env ARK_ENV=test jest --runInBand --watchAll",
24    "lint": "eslint ./ --fix"
25},

Add the following keys to the scripts section:

1"create:MyNet": "./bin/snapshot create --config ../core/lib/config/MyNet --network MyNet",
2"import:MyNet": "./bin/snapshot import --config ../core/lib/config/MyNet --network MyNet",
3"verify:MyNet": "./bin/snapshot verify --config ../core/lib/config/MyNet --network MyNet",
4"rollback:MyNet": "./bin/snapshot rollback --config ../core/lib/config/MyNet --network MyNet",
5"truncate:MyNet": "./bin/snapshot truncate --config ../core/lib/config/MyNet --network MyNet",

If you chose to override the existing mainnet, testnet and devnet configurations, you should omit this step.

Commit your changes and push them to your organizations’ repository; your node operators may make these changes themselves, or clone the new configurations from this repository.

1git remote set-url origin https://github.com/myorganization/mynet-v2.git
2git push

#Syncing With the Existing Network

We are going to start a relay node, which is the equivalent of a standard v1 node without entering your delegate’s passphrase. First bootstrap all dependencies.

1lerna bootstrap

This might take a while, as lerna obtains all dependencies required for ARK Core. Once the process is done, run the following command to start the synchronization process:

1(cd packages/core && yarn start:MyNet)

Your node should now start and connect with the peers we set in our peers.json. It will take a few hours to a couple of days for the entire synchronization process to finalize, depending on the size of your blockchain.

All node operators, delegates and third-party services should do the same and create a v2 node. Once enough participants are in sync, we can move to the next step.

#Migrating

Once you proceed with the following steps, v1 nodes will not be able to join your network, nor will you be able to downgrade the network.

Ensure that during this phase, all delegates and node operators are communicating with you. First, we need to collect all peers running v2 nodes, and create an updated peers.json. Remove all v1 nodes from your peers list, and add the v2 nodes. (Only add reliable nodes, for example, the ones curated by your team).

Once we are passed the cutoff block, all node operators should create a snapshot of their blockchain:

1(cd packages/core-snapshot-cli && yarn create:MyNet)

Stop the running node process, and proceed to truncate the existing database:

1(cd packages/core-snapshot-cli && yarn truncate:MyNet)

Now we must ban all v1 nodes, by editing our peers.json file. Set the minimumVersion key to ">=2.0.15". We recommend committing this change to your repository after the migration is complete. Your peers.json should now only contain IP addresses of v2 nodes and have the minimumVersion key set to something greater than 1.X.X.

Import the snapshot up to the cutoff block:

1(cd packages/core-snapshot-cli && yarn import:devnet -b 0-$CUTOFF_BLOCK_HEIGHT)

Your blockchain will now be up to the cutoff point. Restart the nodes, either using start:MyNet or relay:MyNet. The forging process should restart, and your network has been upgraded to v2. Pop a bottle of champagne and wipe the sweat of your brow.

#Considerations

The upgrading process is a vulnerable stage in your blockchain’s lifecycle. Ensure the following:

• genesisBlock.json must be exactly the same as the v1 genesis block. Have each node operator verify this themselves.
• Snapshots should not be shared during the upgrade process. If you do this, use this command instead to decrease the risk of a malicious participant corrupting the chain:

1(cd packages/core-snapshot-cli && \
2    yarn import:devnet -b 0-$CUTOFF_BLOCK_HEIGHT --signature-verify)
3    # --signature-verify forces our node to check each block.