|
| 1 | +# Pool Upgrade How To |
| 2 | + |
| 3 | +Below there are steps which need to be done to upgrade a pool to a new DCL |
| 4 | +application version: |
| 5 | + |
| 6 | +1. **[Dev Team] New Release and Upgrade Name**: A new release of |
| 7 | + [distributed-compliance-ledger](https://github.com/zigbee-alliance/distributed-compliance-ledger) |
| 8 | + project is issued. The code of the new released application version must be |
| 9 | + augmented by a new upgrade handler which will handle an upgrade to this new |
| 10 | + version. This upgrade handler must have a unique name which will serve as the |
| 11 | + name of the upgrade to this new version. |
| 12 | + |
| 13 | +2. **[Trustees] Upgrade Height**: A ledger height not reached yet at which all |
| 14 | + the nodes in the pool must be upgraded to the new application version is |
| 15 | + chosen. |
| 16 | + |
| 17 | +3. **[A Trustee] ProposeUpgrade**: One of trustees proposes the upgrade using |
| 18 | + the following steps: |
| 19 | + |
| 20 | + 1. Calculates SHA-256 or SHA-512 checksums of the new application version |
| 21 | + binaries (for the supported platforms) taken from the project release. |
| 22 | + This can be done using `sha256sum` or `sha512sum` tool. For example: |
| 23 | + ``` |
| 24 | + sha256sum ./dcld |
| 25 | + ``` |
| 26 | +
|
| 27 | + 2. Sends [`ProposeUpgrade`](./transactions.md#propose_upgrade) transaction |
| 28 | + with the name of the new upgrade handler, the chosen ledger height and the |
| 29 | + info containing URLs of the new application version binaries for supported |
| 30 | + platforms with the calculated checksums. For example: |
| 31 | + ``` |
| 32 | + dcld tx dclupgrade propose-upgrade --name=v0.7.0 --upgrade-height=10000 --upgrade-info="{\"binaries\":{\"linux/amd64\":\"https://github.com/zigbee-alliance/distributed-compliance-ledger/releases/download/v0.7.0/dcld?checksum=sha256:50708d4f7e00da347d4e678bf26780cd424232461c4bb414f72391c75e39545a\"}}" --from=alice |
| 33 | + ``` |
| 34 | +
|
| 35 | +4. **[Trustees] ApproveUpgrade**: Other trustees approve the proposed upgrade |
| 36 | + until it turns into the approved state and is scheduled (this happens when |
| 37 | + the count of approvals including the proposal reaches 2/3 of the total count |
| 38 | + of trustees). Each of them uses the following steps to accomplish this: |
| 39 | +
|
| 40 | + 1. Re-calculates checksums of the new application version binaries (for the |
| 41 | + supported platforms) taken from the project release. This can be done |
| 42 | + using `sha256sum` / `sha512sum` tool. For example: |
| 43 | + ``` |
| 44 | + sha256sum ./dcld |
| 45 | + ``` |
| 46 | +
|
| 47 | + 2. Ensures that the re-calculated values are equal to the checksums specified |
| 48 | + in the proposed upgrade plan `Info` field. Example how to view the |
| 49 | + proposed upgrade plan: |
| 50 | + ``` |
| 51 | + dcld query dclupgrade proposed-upgrade --name=v0.7.0 |
| 52 | + ``` |
| 53 | +
|
| 54 | + 3. Verifies that the application binaries URLs provided in the proposed |
| 55 | + upgrade plan `Info` field are valid and that the files referenced by them |
| 56 | + match the provided checksums. |
| 57 | +
|
| 58 | + 4. Verifies that `Height` field of the proposed upgrade plan has the proper |
| 59 | + value. |
| 60 | +
|
| 61 | + 5. Sends [`ApproveUpgrade`](./transactions.md#approve_upgrade) transaction |
| 62 | + with the name of the proposed upgrade. For example: |
| 63 | + ``` |
| 64 | + dcld tx dclupgrade approve-upgrade --name=v0.7.0 --from=bob |
| 65 | + ``` |
| 66 | +
|
| 67 | +5. **[Anyone] Ensure That Upgrade Has Been Scheduled**: It makes sense to ensure |
| 68 | + that the upgrade has been approved and scheduled. Example how to view the |
| 69 | + approved upgrade plan: |
| 70 | + ``` |
| 71 | + dcld query dclupgrade approved-upgrade --name=v0.7.0 |
| 72 | + ``` |
| 73 | + Command to view the current scheduled upgrade plan: |
| 74 | + ``` |
| 75 | + dcld query upgrade plan |
| 76 | + ``` |
| 77 | +
|
| 78 | +6. **[All Node Admins] Download New Binary**: Before the ledger reaches the |
| 79 | + height specified in the upgrade plan, each node admin does the following |
| 80 | + steps: |
| 81 | +
|
| 82 | + 1. Downloads the application binary from the URL specified in the upgrade |
| 83 | + plan `Info` field and corresponding to the node platform. Command to view |
| 84 | + the current scheduled upgrade plan: |
| 85 | + ``` |
| 86 | + dcld query upgrade plan |
| 87 | + ``` |
| 88 | +
|
| 89 | + 2. Verifies that the downloaded application binary matches the checksum |
| 90 | + specified in the URL. This can be done automatically together with the |
| 91 | + previous step by [`go-getter`](https://github.com/hashicorp/go-getter) |
| 92 | + download tool (its executable binaries for various platforms can be |
| 93 | + downloaded from https://github.com/hashicorp/go-getter/releases). For |
| 94 | + example: |
| 95 | + ``` |
| 96 | + go-getter https://github.com/zigbee-alliance/distributed-compliance-ledger/releases/download/v0.7.0/dcld?checksum=sha256:50708d4f7e00da347d4e678bf26780cd424232461c4bb414f72391c75e39545a ~/Downloads |
| 97 | + ``` |
| 98 | + `go-getter` verifies that the downloaded file matches the checksum when |
| 99 | + the URL is provided in the specified format. If the downloaded file |
| 100 | + checksum does not equal to the checksum provided in the URL, `go-getter` |
| 101 | + reports that checksums did not match. |
| 102 | +
|
| 103 | + 3. Creates a directory with the name of the upgrade within |
| 104 | + `/var/lib/<USERNAME>/.dcl/cosmovisor/` (where <USERNAME> is the name of |
| 105 | + the user on behalf of whom `cosmovisor` service is running), creates |
| 106 | + `bin` sub-directory within the created directory, and puts the new |
| 107 | + application binary within `bin` sub-directory. |
| 108 | + |
| 109 | + Example (for the user `ubuntu`): |
| 110 | + ``` |
| 111 | + cd /var/lib/ubuntu/.dcl/cosmovisor |
| 112 | + mkdir -p upgrades |
| 113 | + cd upgrades |
| 114 | + mkdir v0.7.0 |
| 115 | + cd v0.7.0 |
| 116 | + mkdir bin |
| 117 | + cd ~/Downloads |
| 118 | + cp ./dcld /var/lib/ubuntu/.dcl/cosmovisor/upgrades/v0.7.0/bin/ |
| 119 | + ``` |
| 120 | + Ensure that `dcld` file has been copied to the new application version |
| 121 | + binary directory: |
| 122 | + ``` |
| 123 | + ls -l /var/lib/ubuntu/.dcl/cosmovisor/upgrades/v0.7.0/bin/dcld |
| 124 | + ``` |
| 125 | + The command output must contatain information about `dcld` file like |
| 126 | + following: |
| 127 | + ``` |
| 128 | + -rw-r--r-- 1 ubuntu ubuntu 55816720 Mar 11 08:23 /var/lib/ubuntu/.dcl/cosmovisor/upgrades/v0.7.0/bin/dcld |
| 129 | + ``` |
| 130 | +
|
| 131 | +7. **Upgrade Is Applied**: The upgrade is applied on all the nodes in the pool |
| 132 | + when the ledger reaches the height specified in the upgrade plan. |
| 133 | + |
| 134 | + Command to view the current pool status: |
| 135 | + ``` |
| 136 | + dcld status |
| 137 | + ``` |
| 138 | + The current ledger height is reported in `SyncInfo` -> `latest_block_height` |
| 139 | + field. |
| 140 | + |
| 141 | + Example of command to check whether the upgrade was applied: |
| 142 | + ``` |
| 143 | + dcld query upgrade applied v0.7.0 |
| 144 | + ``` |
| 145 | + If the upgrade with the passed name was applied, this command output will |
| 146 | + contain information about it. |
0 commit comments