Skip to content

Commit 6fdbdb3

Browse files
pbukvapbukva
authored
Refact. downl. of input files, upgr. instr. doc, set Reconcil. admin & label (#28)
1 parent 8203c0f commit 6fdbdb3

5 files changed

+178
-38
lines changed

Diff for: ‎dorado-1/7-software-upgrade-v0.14.0.md

+169-14
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,78 @@
11

2-
# Software upgrade of testnet
3-
The upgrade procedure is exactly the same as for mainnet [here](../fetchhub-4/7-software-upgrade-v0.14.0.md) with
4-
following differences:
2+
# Software upgrade
53

6-
## CUDOS Eternal halt height
7-
The eternal halt height for CUDOS public **testnet** is `16128170`
4+
This guide is describing the procedure to upgrade to the [v0.14.0-rc10](https://github.com/fetchai/fetchd/releases/tag/v0.14.0-rc10) following the [CUDOS testnet migration (#44)](https://explore-dorado.fetch.ai/proposals/44) software upgrade governance proposal.
85

9-
## Fetch network halt height
10-
Fetch Dorado testnet halt height is `14603003`
6+
We kindly ask all the validators to read through the following document, and then wait until chain reaches upgrade block height `14603003` *before* executing the upgrade steps.
7+
8+
In case of questions or issues, feel free to reach me on Discord (`@v0id.ptr`), or Telegram [@v0idptr](https://t.me/v0idptr).
9+
10+
## About the upgrade
11+
12+
The primary feature of this release is merge of CUDOS network in to Fetch network.
13+
14+
The secondary features are:
15+
* Reconciliation,
16+
* Cleanup of `Almanac` and `AName` contracts
17+
* Setting admin for `Reconciliation` and `TokenBridge` contracts
18+
* Setting label for `Reconciliation` contract
19+
* Setting cw2 contract version for `Reconciliation` contract
20+
21+
In principle this is breaking change upgrade, since it will change state of the chain = every node must upgrade, or at least sync from block height equal or higher than the upgrade height.
22+
However, this upgrade does **not** change API whatsoever (static definition wise nor behavioural wise), since versions of underlying components (cosmos-sdk & tendermint) remains the same.
23+
24+
## Upgrade procedure
25+
26+
When blockchain reaches the target upgrade block height `14603003`, all nodes will halt - it is **\*expected\*** to have an error logged by the node, similar to:
27+
28+
```
29+
1:16PM ERR UPGRADE "v0.14.0" NEEDED at height: XXX: CUDOS mainnet migration v0.14.0 (upgrade-info)
30+
1:16PM ERR CONSENSUS FAILURE!!! err="UPGRADE \"v0.14.0\" NEEDED at height: 14603003"
31+
```
32+
33+
Once this happens, node operators can proceed with installation of the new `v0.14.0-rc10` version of the `fetchd` executable.
34+
35+
## Install new fetchd version
36+
37+
You may already have the fetchd repository on your machine from the previous installation. If not, you can:
38+
39+
```bash
40+
git clone --branch v0.14.0-rc10 https://github.com/fetchai/fetchd fetchd_v0.14.0-rc10
41+
cd fetchd_v0.14.0-rc10
42+
```
43+
44+
If you already have an existing clone, place yourself in and:
45+
46+
```bash
47+
git fetch
48+
git clean -fd
49+
git checkout v0.14.0-rc10
50+
```
51+
52+
Now you can install the new `fetchd` version:
53+
54+
```bash
55+
make install
56+
57+
# and verify you now have the correct version:
58+
fetchd -h
59+
# must print fetchd help message
60+
61+
fetchd version
62+
# MUST print v0.14.0-rc10
63+
```
64+
65+
Make sure the version is correct before proceeding further!
66+
67+
You're now ready to restart your node.
68+
69+
## Execute upgrade procedure steps
70+
71+
### Set primary environment variables
72+
First define env variables which will be used in further commands below.
73+
74+
> :exclamation: Variables set in this section determine which upgrade you are going to do.
1175
12-
## Set primary environment variables
13-
In the [Set primary environment variables](../fetchhub-4/7-software-upgrade-v0.14.0.md#set-primary-environment-variables) section,
14-
**\*INSTEAD\*** use the following commands to set values of the primary variables:
1576
> :exclamation: Please **\*VERIFY\*** value of the `FETCHD_HOME_DIR` variable below and adjust it to correct directory
1677
> of **\*your\*** node **\*IF\*** it differs from default!
1778
```shell
@@ -20,10 +81,104 @@ export FETCHD_HOME_DIR=~/.fetchd
2081
```
2182

2283
```shell
23-
export DESTINATION_CHAIN_ID="dorado-1"
24-
export GENESIS_FETCHUB_GIT_REVISION="v0.14.0"
84+
export DESTINATION_CHAIN_ID=fetchhub-4
85+
export GENESIS_FETCHUB_GIT_REVISION=v0.14.0-rc10
86+
export UPGRADE_SHA256_PARAMS="--cudos-genesis-sha256 906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e --cudos-migration-config-sha256 930dc21af917ec8f2f8820ff393c1a276297fe91d4f585757143acb2727cd6d2"
87+
```
88+
89+
### Download merge input files
90+
91+
```shell
92+
curl https://raw.githubusercontent.com/fetchai/genesis-fetchhub/refs/heads/$GENESIS_FETCHUB_GIT_REVISION/dorado-1/data/cudos_merge_config.json -o "$FETCHD_HOME_DIR/cudos_merge_config.json"
93+
curl https://raw.githubusercontent.com/fetchai/genesis-fetchhub/refs/heads/$GENESIS_FETCHUB_GIT_REVISION/dorado-1/data/genesis.cudos.json.gz -o "$FETCHD_HOME_DIR/genesis.cudos.json.gz"
94+
```
95+
96+
And finally **extract** the CUDOS genesis file:
97+
```shell
98+
gzip -d -c "$FETCHD_HOME_DIR/genesis.cudos.json.gz" > "$FETCHD_HOME_DIR/genesis.cudos.json"
99+
```
100+
101+
### Confirm fetchd version
102+
Confirm version of `fetchd` executable by executing following command:
103+
```shell
104+
fetchd version
105+
```
106+
> It **MUST** print `v0.14.0-rc10`.
107+
108+
### Execute actual upgrade command
109+
Then finally execute the upgrade - you **MUST** use the following commandline = the **VERY 1st** start of the **NEW**
110+
`v0.14.0-rc10` version of `fetchd` node executable.
111+
```shell
112+
fetchd --home "$FETCHD_HOME_DIR" start --cudos-genesis-path "$FETCHD_HOME_DIR/genesis.cudos.json" --cudos-migration-config-path "$FETCHD_HOME_DIR/cudos_merge_config.json" $UPGRADE_SHA256_PARAMS
113+
```
114+
, where the `FETCHD_HOME_DIR` variable contains path to the home directory,
115+
and all following flags of the `start` command are **MANDATORY** (= **must** be provided) for the very 1st run of
116+
the new version `v0.14.0-rc10` of the `fetchd` executable = when upgrade procedure is actually executed:
117+
* `--cudos-genesis-path <PATH_TO_CUDOS_GENESIS_JSON_FILE>`
118+
* `--cudos-migration-config-path <PATH_TO_CUDOS_MERGE_CONFIG_JSON_FILE>`
119+
* `--cudos-genesis-sha256 <HASH>`
120+
* `--cudos-migration-config-sha256 <HASH>`
121+
Once the upgrade was successfully executed, flags mentioned above will be **IGNORED** and so the `fetchd start` command
122+
can be run without providing them.
123+
124+
:exclamation: The `--cudos-genesis-sha256 <HASH>` and `--cudos-migration-config-sha256 <HASH>` flags with their
125+
respective HASH values are very **IMPORTANT** - you **MUST** use the **VERY SAME** files and hash values as provided
126+
in this documentation, especially hash values, since these will ensure, that you are using the correct input files
127+
during the upgrade.
128+
> :exclamation: :no_entry_sign: Please do **NOT** derive hash values on your own from input files, and then use these
129+
> instead of the ones we provide in this documentation, since that will allow your node to execute the upgrade using
130+
> **DIFFERENT** input files then rest of the nodes in the network, and almost certainly cause your node to end up
131+
> with different state then rest of the network after the upgrade, what effectively disqualify your node from
132+
> reconnecting with the rest of the network, when the network will resume the consensus.
133+
25134

26-
{==> CHANGE ME! (HASH value) <==}
135+
The line, like the one right below, must appear in the log, indicating that you are running the correct version of the
136+
`fetchd` node executable.
27137

28-
export UPGRADE_SHA256_PARAMS="--cudos-genesis-sha256 906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e --cudos-migration-config-sha256 2c48a252a051fb90a6401dffb718892084047a3f00dc99481d3692063cf65cce"
29138
```
139+
1:31PM INF applying upgrade "v0.14.0" at height: 14603003
140+
```
141+
142+
143+
> If there is an issue caused by using wrong input files (or hash values), the upgrade process will exit with
144+
> appropriate error describing what specifically caused the failure. The upgrade procedure will **NOT** do any changes
145+
> in node state **IF** the issue was caused by using wrong files or hash value = you can re-execute the upgrade again
146+
> with correct files and hash values should just hang and wait for more validators to complete
147+
148+
If input files and hashes are correct, your node starts executing the upgrade procedure which might take up anything
149+
from 5 to 30 seconds, during which you should see lines, like the ones below, being printed in the log, indicating
150+
progress of the upgrade procedure:
151+
152+
```log
153+
5:12AM INF cudos merge: loading merge source genesis json expected sha256=906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e file=genesis.cudos.json
154+
5:12AM INF cudos merge: loading network config expected sha256=930dc21af917ec8f2f8820ff393c1a276297fe91d4f585757143acb2727cd6d2 file=cudos_merge_config.json
155+
5:12AM INF cudos merge: remaining bonded pool balance amount=183acudos
156+
5:12AM INF cudos merge: remaining not-bonded pool balance amount=6241acudos
157+
5:12AM INF cudos merge: remaining dist balance amount=51acudos
158+
```
159+
160+
Once you see the lines like below being printed in the log, the upgrade procedure **has finished**:
161+
```log
162+
5:12AM INF minted coins from module account amount=88946755672000000000000000atestfet from=mint module=x/bank
163+
5:12AM INF minted coins from module account amount=480989277nanomobx from=mint module=x/bank
164+
5:12AM INF minted coins from module account amount=4795384342nanonomx from=mint module=x/bank
165+
5:12AM INF minted coins from module account amount=6296428529541965571atestfet from=mint module=x/bank
166+
5:12AM INF executed block height=14272900 module=consensus num_invalid_txs=0 num_valid_txs=0
167+
```
168+
169+
After this point, node is just waiting until enough validators have upgraded & joined the network (with at least 2/3
170+
of the global stake), after which the mainnet consensus will resume block generation on its own, and the mainnet
171+
upgrade procedure is finished from the conceptual standpoint.
172+
173+
### Verify upgrade completed
174+
175+
You can now query your **local** RPC endpoint to verify that the right version is running and the node properly
176+
restarted:
177+
178+
```bash
179+
curl -s http://localhost:26657/abci_info | jq -r '.result.response.version'
180+
v0.14.0-rc10
181+
```
182+
183+
> Make sure this print exactly the `v0.14.0-rc10` version. If not, double check you're on the right git tag in the `fetchd`
184+
repository, that the `make install` didn't produce errors, and that your properly restarted your node.

Diff for: ‎dorado-1/data/cudos_merge_config.json

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
"contracts" : {
88
"reconciliation" : {
99
"addr" : "fetch1g5ur2wc5xnlc7sw9wd895lw7mmxz04r5syj3s6ew8md6pvwuweqqavkgt0",
10+
"new_admin": "fetch1x77wq7m9pxyd0y3w8uk47rh8ex7q8qhdps4jut",
11+
"new_label": "reconciliation-contract",
1012
"new_contract_version" : {
1113
"cw_2_version" : {
1214
"contract" : "contract-fetch-reconciliation",

Diff for: ‎dorado-1/data/genesis.cudos.json.7z

-7.4 MB
Binary file not shown.

Diff for: ‎dorado-1/data/genesis.cudos.json.gz

29.4 MB
Binary file not shown.

Diff for: ‎fetchhub-4/7-software-upgrade-v0.14.0.md

+7-24
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11

22
# Software upgrade
3+
> :exclamation: :no_entry_sign: This guide is **NOT** finalised yet. It is subject to further changes, since some required information
4+
> will become known later (e.g. final halt block heights for chains involved, git tags, content of exported
5+
> `genesis.cudos.json` file, etc. ...).
36
47
This guide is describing the procedure to upgrade to the [{==> CHANGE ME! <==} v0.14.0-rc9](https://github.com/fetchai/fetchd/releases/tag/v0.14.0-rc9) following the [{==> CHANGE ME! <==} CUDOS mainnet migration #32](https://www.mintscan.io/fetchai/proposals/32) software upgrade governance proposal.
58

@@ -10,7 +13,6 @@ In case of questions or issues, feel free to reach me on Discord (`@v0id.ptr`),
1013
## About the upgrade
1114

1215
The primary feature of this release is merge of CUDOS network in to Fetch network (detailed description of the feature is provided in the [ {==> CHANGE ME! <==} PR #XXX @ YYY](https://github.com/fetchai/CHANGE_ME)).
13-
In this release, the Municipal Inflation is configured for the MOBX (3% APR) and NOMX (3% APR) tokens.
1416

1517
The secondary features are:
1618
* Reconciliation,
@@ -75,14 +77,6 @@ First define env variables which will be used in further commands below.
7577

7678
> :exclamation: Variables set in this section determine which upgrade you are going to do.
7779
78-
> :exclamation: **\*IMPORTANT\***: Variables set in this section are subject of **\*SUBSTITUTION\*** - they can be
79-
> replaced by values from **\*other\*** documents which refer to this document, like for example the
80-
> [upgrade procedure document for Dorado testnet](../dorado-1/7-software-upgrade-v0.14.0.md#set-primary-environment-variables).
81-
>
82-
> :point_right: So the env variables as they are defined in this section in **\*this document\***, are valid **\*only
83-
> for mainnet\*** (= for `fetchhub-4` chain-id), and will need to be replaced by values from other documents which
84-
> **\*refer\*** to this document.
85-
8680
> :exclamation: Please **\*VERIFY\*** value of the `FETCHD_HOME_DIR` variable below and adjust it to correct directory
8781
> of **\*your\*** node **\*IF\*** it differs from default!
8882
```shell
@@ -99,28 +93,17 @@ export GENESIS_FETCHUB_GIT_REVISION=v0.14.0
9993
export UPGRADE_SHA256_PARAMS="--cudos-genesis-sha256 906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e --cudos-migration-config-sha256 2c48a252a051fb90a6401dffb718892084047a3f00dc99481d3692063cf65cce"
10094
```
10195

102-
### Set derived path env variables
103-
104-
```shell
105-
export GENESIS_FETCHHUB_PATH=$FETCHD_HOME_DIR/genesis-fetchhub
106-
export UPGRADE_DATA_PATH=$GENESIS_FETCHHUB_PATH/$DESTINATION_CHAIN_ID/data
107-
```
10896

10997
### Download merge input files
11098

111-
Clone the correct version of https://github.com/fetchai/genesis-fetchhub repository in to your `$FETCHD_HOME_DIR`
112-
directory:
113-
> **\*IF\*** the $GENESIS_FETCHHUB_PATH directory **\*exists already\***, please **delete it first** (if needed, backup it before deletion).
114-
> ```shell
115-
> rm -rf "$GENESIS_FETCHHUB_PATH"
116-
> ```
11799
```shell
118-
git clone --branch $GENESIS_FETCHUB_GIT_REVISION --depth 1 https://github.com/fetchai/genesis-fetchhub "$GENESIS_FETCHHUB_PATH"
100+
curl https://raw.githubusercontent.com/fetchai/genesis-fetchhub/refs/heads/$GENESIS_FETCHUB_GIT_REVISION/dorado-1/data/cudos_merge_config.json -o "$FETCHD_HOME_DIR/cudos_merge_config.json"
101+
curl https://raw.githubusercontent.com/fetchai/genesis-fetchhub/refs/heads/$GENESIS_FETCHUB_GIT_REVISION/dorado-1/data/genesis.cudos.json.gz -o "$FETCHD_HOME_DIR/genesis.cudos.json.gz"
119102
```
120103

121104
And finally **extract** the CUDOS genesis file:
122105
```shell
123-
7z e "$UPGRADE_DATA_PATH/genesis.cudos.json.7z" -o"$UPGRADE_DATA_PATH"
106+
gzip -d -c "$FETCHD_HOME_DIR/genesis.cudos.json.gz" > "$FETCHD_HOME_DIR/genesis.cudos.json"
124107
```
125108

126109
### Confirm fetchd version
@@ -134,7 +117,7 @@ fetchd version
134117
Then finally execute the upgrade - you **MUST** use the following commandline = the **VERY 1st** start of the **NEW**
135118
`v0.14.0` version of `fetchd` node executable.
136119
```shell
137-
fetchd --home "$FETCHD_HOME_DIR" start --cudos-genesis-path "$UPGRADE_DATA_PATH/genesis.cudos.json" --cudos-migration-config-path "$UPGRADE_DATA_PATH/cudos_merge_config.json" $UPGRADE_SHA256_PARAMS
120+
fetchd --home "$FETCHD_HOME_DIR" start --cudos-genesis-path "$FETCHD_HOME_DIR/genesis.cudos.json" --cudos-migration-config-path "$FETCHD_HOME_DIR/cudos_merge_config.json" $UPGRADE_SHA256_PARAMS
138121
```
139122
, where the `FETCHD_HOME_DIR` variable contains path to the home directory,
140123
and all following flags of the `start` command are **MANDATORY** (= **must** be provided) for the very 1st run of

0 commit comments

Comments
 (0)