Skip to content

Commit

Permalink
Refact. downl. of input files, upgr. instr. doc, set Reconcil. admin …
Browse files Browse the repository at this point in the history 
…& label (#29)
  • Loading branch information
@pbukva
pbukva authored Oct 21, 2024
1 parent 6514d0b commit b382ab0
Show file tree
Hide file tree
Showing 5 changed files with 184 additions and 71 deletions.
183 changes: 169 additions & 14 deletions dorado-1/7-software-upgrade-v0.14.0.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,78 @@

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

## CUDOS Eternal halt height
The eternal halt height for CUDOS public **testnet** is `16128170`
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.

## Fetch network halt height
Fetch Dorado testnet halt height is `14603003`
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.

In case of questions or issues, feel free to reach me on Discord (`@v0id.ptr`), or Telegram [@v0idptr](https://t.me/v0idptr).

## About the upgrade

The primary feature of this release is merge of CUDOS network in to Fetch network.

The secondary features are:
* Reconciliation,
* Cleanup of `Almanac` and `AName` contracts
* Setting admin for `Reconciliation` and `TokenBridge` contracts
* Setting label for `Reconciliation` contract
* Setting cw2 contract version for `Reconciliation` contract

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.
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.

## Upgrade procedure

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:

```
1:16PM ERR UPGRADE "v0.14.0" NEEDED at height: XXX: CUDOS mainnet migration v0.14.0 (upgrade-info)
1:16PM ERR CONSENSUS FAILURE!!! err="UPGRADE \"v0.14.0\" NEEDED at height: 14603003"
```

Once this happens, node operators can proceed with installation of the new `v0.14.0-rc10` version of the `fetchd` executable.

## Install new fetchd version

You may already have the fetchd repository on your machine from the previous installation. If not, you can:

```bash
git clone --branch v0.14.0-rc10 https://github.com/fetchai/fetchd fetchd_v0.14.0-rc10
cd fetchd_v0.14.0-rc10
```

If you already have an existing clone, place yourself in and:

```bash
git fetch
git clean -fd
git checkout v0.14.0-rc10
```

Now you can install the new `fetchd` version:

```bash
make install

# and verify you now have the correct version:
fetchd -h
# must print fetchd help message

fetchd version
# MUST print v0.14.0-rc10
```

Make sure the version is correct before proceeding further!

You're now ready to restart your node.

## Execute upgrade procedure steps

### Set primary environment variables
First define env variables which will be used in further commands below.

> :exclamation: Variables set in this section determine which upgrade you are going to do.
## Set primary environment variables
In the [Set primary environment variables](../fetchhub-4/7-software-upgrade-v0.14.0.md#set-primary-environment-variables) section,
**\*INSTEAD\*** use the following commands to set values of the primary variables:
> :exclamation: Please **\*VERIFY\*** value of the `FETCHD_HOME_DIR` variable below and adjust it to correct directory
> of **\*your\*** node **\*IF\*** it differs from default!
```shell
Expand All @@ -20,10 +81,104 @@ export FETCHD_HOME_DIR=~/.fetchd
```

```shell
export DESTINATION_CHAIN_ID="dorado-1"
export GENESIS_FETCHUB_GIT_REVISION="v0.14.0"
export DESTINATION_CHAIN_ID=fetchhub-4
export GENESIS_FETCHUB_GIT_REVISION=v0.14.0-rc10
export UPGRADE_SHA256_PARAMS="--cudos-genesis-sha256 906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e --cudos-migration-config-sha256 930dc21af917ec8f2f8820ff393c1a276297fe91d4f585757143acb2727cd6d2"
```

### Download merge input files

```shell
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"
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"
```

And finally **extract** the CUDOS genesis file:
```shell
gzip -d -c "$FETCHD_HOME_DIR/genesis.cudos.json.gz" > "$FETCHD_HOME_DIR/genesis.cudos.json"
```

### Confirm fetchd version
Confirm version of `fetchd` executable by executing following command:
```shell
fetchd version
```
> It **MUST** print `v0.14.0-rc10`.
### Execute actual upgrade command
Then finally execute the upgrade - you **MUST** use the following commandline = the **VERY 1st** start of the **NEW**
`v0.14.0-rc10` version of `fetchd` node executable.
```shell
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
```
, where the `FETCHD_HOME_DIR` variable contains path to the home directory,
and all following flags of the `start` command are **MANDATORY** (= **must** be provided) for the very 1st run of
the new version `v0.14.0-rc10` of the `fetchd` executable = when upgrade procedure is actually executed:
* `--cudos-genesis-path <PATH_TO_CUDOS_GENESIS_JSON_FILE>`
* `--cudos-migration-config-path <PATH_TO_CUDOS_MERGE_CONFIG_JSON_FILE>`
* `--cudos-genesis-sha256 <HASH>`
* `--cudos-migration-config-sha256 <HASH>`
Once the upgrade was successfully executed, flags mentioned above will be **IGNORED** and so the `fetchd start` command
can be run without providing them.

:exclamation: The `--cudos-genesis-sha256 <HASH>` and `--cudos-migration-config-sha256 <HASH>` flags with their
respective HASH values are very **IMPORTANT** - you **MUST** use the **VERY SAME** files and hash values as provided
in this documentation, especially hash values, since these will ensure, that you are using the correct input files
during the upgrade.
> :exclamation: :no_entry_sign: Please do **NOT** derive hash values on your own from input files, and then use these
> instead of the ones we provide in this documentation, since that will allow your node to execute the upgrade using
> **DIFFERENT** input files then rest of the nodes in the network, and almost certainly cause your node to end up
> with different state then rest of the network after the upgrade, what effectively disqualify your node from
> reconnecting with the rest of the network, when the network will resume the consensus.

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

export UPGRADE_SHA256_PARAMS="--cudos-genesis-sha256 906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e --cudos-migration-config-sha256 2c48a252a051fb90a6401dffb718892084047a3f00dc99481d3692063cf65cce"
```
1:31PM INF applying upgrade "v0.14.0" at height: 14603003
```


> If there is an issue caused by using wrong input files (or hash values), the upgrade process will exit with
> appropriate error describing what specifically caused the failure. The upgrade procedure will **NOT** do any changes
> in node state **IF** the issue was caused by using wrong files or hash value = you can re-execute the upgrade again
> with correct files and hash values should just hang and wait for more validators to complete
If input files and hashes are correct, your node starts executing the upgrade procedure which might take up anything
from 5 to 30 seconds, during which you should see lines, like the ones below, being printed in the log, indicating
progress of the upgrade procedure:

```log
5:12AM INF cudos merge: loading merge source genesis json expected sha256=906ea6ea5b1ab5936bb9a5f350d11084eb92cba249e65e11c460ab251b27fb0e file=genesis.cudos.json
5:12AM INF cudos merge: loading network config expected sha256=930dc21af917ec8f2f8820ff393c1a276297fe91d4f585757143acb2727cd6d2 file=cudos_merge_config.json
5:12AM INF cudos merge: remaining bonded pool balance amount=183acudos
5:12AM INF cudos merge: remaining not-bonded pool balance amount=6241acudos
5:12AM INF cudos merge: remaining dist balance amount=51acudos
```

Once you see the lines like below being printed in the log, the upgrade procedure **has finished**:
```log
5:12AM INF minted coins from module account amount=88946755672000000000000000atestfet from=mint module=x/bank
5:12AM INF minted coins from module account amount=480989277nanomobx from=mint module=x/bank
5:12AM INF minted coins from module account amount=4795384342nanonomx from=mint module=x/bank
5:12AM INF minted coins from module account amount=6296428529541965571atestfet from=mint module=x/bank
5:12AM INF executed block height=14272900 module=consensus num_invalid_txs=0 num_valid_txs=0
```

After this point, node is just waiting until enough validators have upgraded & joined the network (with at least 2/3
of the global stake), after which the mainnet consensus will resume block generation on its own, and the mainnet
upgrade procedure is finished from the conceptual standpoint.

### Verify upgrade completed

You can now query your **local** RPC endpoint to verify that the right version is running and the node properly
restarted:

```bash
curl -s http://localhost:26657/abci_info | jq -r '.result.response.version'
v0.14.0-rc10
```

> 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`
repository, that the `make install` didn't produce errors, and that your properly restarted your node.
41 changes: 8 additions & 33 deletions dorado-1/data/cudos_merge_config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@
"merge_source_chain_id" : "cudos-testnet-public-4",
"destination_chain_id" : "dorado-1",
"reconciliation_info" : {
"target_address" : "fetch1g5ur2wc5xnlc7sw9wd895lw7mmxz04r5syj3s6ew8md6pvwuweqqavkgt0",
"input_csv_records" : [ [ "0x0b3777b5Dbea0C579c05898E7160351F114B9E08", "0490657da13c62de6495a39958aa864d0a1beff1f4cf65ad1a86c67362b94eb1f35eff0eb1f9ccba919d909707adda21531d286fdff74f9a94f2d63e7979ce26c5", "fetch1uvye96zkp86egcwrnsff22ama3c0m8h2aemmsd", "", "", "" ], [ "0x6ACBEDc7616dA8AB5Cf0bB04fC3aA8CbB2629675", "04b049b9a4e0745990f1dd2f95c0940f6ef6e34e6a61735de007faef914698ccdc9d0503cf00558819f744554bfd33895aeada4357b2a6bfb44332b08da8a52c14", "fetch1kydzrk0ylc60zt34m00qttev5h3dgz72scl79d", "", "", "" ], [ "0x3Ffa3598647e93136cf02434629b500E5a40473A", "04f40cc694aa1f42b5eaa97ba9500001573f5aa4ef06114837bc972538bf0a67a93d9507472d4562532d9344767bffa20db3034653f34f20958aef135d97afc622", "fetch1753h55um54pnskd77x0pfpv3le2e4cdhf3dhqc", "", "", "" ] ]
"target_address" : "fetch1g5ur2wc5xnlc7sw9wd895lw7mmxz04r5syj3s6ew8md6pvwuweqqavkgt0"
},
"contracts" : {
"reconciliation" : {
"addr" : "fetch1g5ur2wc5xnlc7sw9wd895lw7mmxz04r5syj3s6ew8md6pvwuweqqavkgt0",
"new_admin": "fetch1x77wq7m9pxyd0y3w8uk47rh8ex7q8qhdps4jut",
"new_label": "reconciliation-contract",
"new_contract_version" : {
"cw_2_version" : {
"contract" : "contract-fetch-reconciliation",
Expand All @@ -25,7 +26,7 @@
}
},
"cudos_merge" : {
"ibc_target_addr" : "cudos1c3qgr4df6u3awsz6rqwkxcpsef7aau7p23pew5",
"ibc_target_addr" : "cudos15p3rl5aavw9rtu86tna5lgxfkz67zzr6tp4ltv",
"remaining_staking_balance_addr" : "cudos1k9jqjvjm2jcn67jkp2tude23d0egerv5nzps0x",
"remaining_gravity_balance_addr" : "cudos10zdec748q8qx0vrt276sj9xau8qnff7r63ct0v",
"remaining_distribution_balance_addr" : "cudos1eyxaeuuu4c70zsga5lqxzm224jy49ncxkqfyvs",
Expand All @@ -42,13 +43,12 @@
"total_cudos_supply" : "22530000000000000000000000000",
"total_fetch_supply_to_mint" : "88946755672000000000000000",
"not_vested_accounts" : [
"cudos15p3rl5aavw9rtu86tna5lgxfkz67zzr6tp4ltv",
"cudos1nj49l56x7sss5hqyvfmctxr3mq64whg273g3x5",
"cudos15jpukx39rtkt8w3u3gzwwvyptdeyejcjade6he",
"cudos15p3rl5aavw9rtu86tna5lgxfkz67zzr6tp4ltv" ],
"cudos10zdec748q8qx0vrt276sj9xau8qnff7r63ct0v" ],
"not_delegated_accounts" : [
"cudos1dslwarknhfsw3pfjzxxf5mn28q3ewfectw0gta",
"cudos1nj49l56x7sss5hqyvfmctxr3mq64whg273g3x5",
"cudos15jpukx39rtkt8w3u3gzwwvyptdeyejcjade6he" ],
"cudos1nj49l56x7sss5hqyvfmctxr3mq64whg273g3x5" ],
"moved_accounts" : [ {
"from" : "cudos196nrmandtwz67d8h4h0ux7amlcluecglx00wlw",
"to" : "cudos1nj49l56x7sss5hqyvfmctxr3mq64whg273g3x5"
Expand All @@ -60,31 +60,6 @@
"to" : "cudos1tfmkdzx9hm8g28vpgc3xhhxjjn460wzkwtayxr",
"amount" : "2000000000000000000000000",
"memo" : "moving all self-delegation"
}, {
"from" : "cudos1ejmf96efvjp6pmsaj8djv3gpmnsvmpnctger4v",
"to" : "cudos15p3rl5aavw9rtu86tna5lgxfkz67zzr6tp4ltv",
"amount": "81029720903928698660",
"memo": "from: Delegation is 3000000000000000000acudos + liquid balance 78550269365994074314acudos(balance+rewards+unboding) = 81550269365994074314acudos. All numbers before commission. To: brand new account - it does not exist on CUDOS testnet nor Fetch Dorado testnet."
}, {
"from" : "cudos1tjr8jjztvwgapj8f9pmjpdqy2v68z9jtvmecyq",
"to" : "cudos1tjrdq53ksrtqres8asrpx0t2t9c337jyvyvhfj",
"amount": "5000000000000010000",
"memo": "Both from & to accnts do not have any delegations on either chain. From acc has liquid alance 5005000000000000010000acudos, To acc has liquid balance 1000000000000acudos."
}, {
"from" : "cudos1tjr8jjztvwgapj8f9pmjpdqy2v68z9jtvmecyq",
"to" : "cudos1tjy0sra0aj35t4cuq5xzrcfn0ujpaql0tx809p",
"amount": "5005000000000000010000",
"memo": "From acc do not have any delegations on either chain. At this point the From acc should have liquid alance 5000000000000000000000acudos, what means the the everything from acc From will be moved to acc To. The To acc has delegations."
}, {
"from" : "cudos1skj8uwra89tjqwdasnne4kzdw3hse9puddjlps",
"to" : "cudos1yfa92hlkxmzxxqkwd84drjp7ne4ddzd4jhyvul",
"amount": "5000000000000000000",
"memo": "The From acc has liquid balance e (356386412522750462acudos + presumably also rewards + perhaps UNbonding delegations) + approx. 10163446788420516312acudos worth of delegations. We are going to move here amount worth about half of what the delegations are worth."
}, {
"from" : "cudos1skj8uwra89tjqwdasnne4kzdw3hse9puddjlps",
"to" : "cudos1tjy0sra0aj35t4cuq5xzrcfn0ujpaql0tx809p",
"amount": "5000000000000000000",
"memo": "The From acc has liquid balance (356386412522750462acudos + presumably also rewards + perhaps UNbonding delegations) + approx. 4807060375897765850acudos worth of delegations. We are going to move here amount which is lightly *HIGHER** than what the reminig the delegations are worth. Expected end result here is that *ALL* delegations on From account *AND* part of its liquid balance is supposed to be moved over to the To acc."
} ],
"validators_map" : [ {
"key" : "cudosvaloper198qaeg4wkf9tn7y345dhk2wyjmm0krdm68jp09",
Expand All @@ -108,6 +83,6 @@
"key" : "cudosvaloper1n738v30yvnge2cc3lq773d8vyvqj3rejnspa3r",
"value" : "fetchvaloper1edqmkwy4rh87020rvf9xn7kktyu7x894led46w"
} ],
"backup_validators" : [ "fetchvaloper1je7r8yuqgaf5f2tx4z2f9008wp4jx0ct6msnzg" ]
"backup_validators" : [ "fetchvaloper1je7r8yuqgaf5f2tx4z2f9008wp4jx0ct6msnzg", "fetchvaloper1rsane988vksrgp2mlqzclmt8wucxv0ej4hrn2k", "fetchvaloper1edqmkwy4rh87020rvf9xn7kktyu7x894led46w" ]
}
}
Binary file removed dorado-1/data/genesis.cudos.json.7z
View file
Binary file not shown.
Binary file added dorado-1/data/genesis.cudos.json.gz
View file
Binary file not shown.
31 changes: 7 additions & 24 deletions fetchhub-4/7-software-upgrade-v0.14.0.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@

# Software upgrade
> :exclamation: :no_entry_sign: This guide is **NOT** finalised yet. It is subject to further changes, since some required information
> will become known later (e.g. final halt block heights for chains involved, git tags, content of exported
> `genesis.cudos.json` file, etc. ...).
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.

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

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)).
In this release, the Municipal Inflation is configured for the MOBX (3% APR) and NOMX (3% APR) tokens.

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

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

### Set derived path env variables

```shell
export GENESIS_FETCHHUB_PATH=$FETCHD_HOME_DIR/genesis-fetchhub
export UPGRADE_DATA_PATH=$GENESIS_FETCHHUB_PATH/$DESTINATION_CHAIN_ID/data
```

### Download merge input files

Clone the correct version of https://github.com/fetchai/genesis-fetchhub repository in to your `$FETCHD_HOME_DIR`
directory:
> **\*IF\*** the $GENESIS_FETCHHUB_PATH directory **\*exists already\***, please **delete it first** (if needed, backup it before deletion).
> ```shell
> rm -rf "$GENESIS_FETCHHUB_PATH"
> ```
```shell
git clone --branch $GENESIS_FETCHUB_GIT_REVISION --depth 1 https://github.com/fetchai/genesis-fetchhub "$GENESIS_FETCHHUB_PATH"
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"
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"
```

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

### Confirm fetchd version
Expand All @@ -134,7 +117,7 @@ fetchd version
Then finally execute the upgrade - you **MUST** use the following commandline = the **VERY 1st** start of the **NEW**
`v0.14.0` version of `fetchd` node executable.
```shell
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
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
```
, where the `FETCHD_HOME_DIR` variable contains path to the home directory,
and all following flags of the `start` command are **MANDATORY** (= **must** be provided) for the very 1st run of
Expand Down

0 comments on commit b382ab0

Please sign in to comment.