-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* docs: localnet upgrade guide * docs: updated version to use * ci: run on larger runner * ci: different larger runner * ci: restore default runner and limit memory usage * docs: add other os download commands * docs: adding explanatory about types.go changes
- Loading branch information
1 parent
1c4f3b7
commit 2127d74
Showing
1 changed file
with
110 additions
and
43 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,75 +1,142 @@ | ||
| # How to use a testnet snapshot in localnet? | ||
| # Localnet Upgrade and Data Migration Guide for ELYS Network | ||
|
|
||
| ## High Stakes testnet snapshots | ||
| This document offers a detailed framework for upgrading the localnet used in the ELYS network, encompassing version changes, data migrations, and utilizing testnet snapshots. | ||
|
|
||
| You can find the latest High Stakes testnet snapshot [here](https://tools.highstakes.ch/files/elys.tar.gz). | ||
| ## Prerequisites | ||
|
|
||
| ``` | ||
| make install | ||
| go run ./scripts/upgrade-assure/... https://tools.highstakes.ch/files/elys.tar.gz ~/go/bin/elysd ~/go/bin/elysd --skip-proposal | ||
| ``` | ||
| Ensure the following prerequisites are met before proceeding with the upgrade and migration: | ||
|
|
||
| ## Stake Town testnet snapshots | ||
| - Git is installed on your machine. | ||
| - Go programming language is installed. | ||
| - Access to the project repository. | ||
| - `curl` and `make` utilities are installed. | ||
| - Appropriate permissions to execute the commands listed below. | ||
|
|
||
| You can find the latest Stake Town testnet snapshot [here](https://snapshots-testnet.stake-town.com/elys/elystestnet-1_latest.tar.lz4). | ||
| ## Upgrade Steps | ||
|
|
||
| ``` | ||
| make install | ||
| go run ./scripts/upgrade-assure/... https://snapshots-testnet.stake-town.com/elys/elystestnet-1_latest.tar.lz4 ~/go/bin/elysd ~/go/bin/elysd --skip-proposal | ||
| ### Step 1: Checkout the Implementation Branch | ||
|
|
||
| Switch to the branch containing the new implementation: | ||
|
|
||
| ```bash | ||
| git checkout estaking_impl | ||
| ``` | ||
|
|
||
| ## Polkachu testnet snapshots | ||
| ### Step 2: Create a New Tag and Install | ||
|
|
||
| You can find the latest Polkachu testnet snapshot [here](https://polkachu.com/testnets/elys/snapshots). | ||
| Tag the new release and install it: | ||
|
|
||
| ``` | ||
| ```bash | ||
| git tag v0.31.0 | ||
| make install | ||
| go run ./scripts/upgrade-assure/... https://snapshots.polkachu.com/testnet-snapshots/elys/elys_5724942.tar.lz4 ~/go/bin/elysd ~/go/bin/elysd --skip-proposal | ||
| ``` | ||
|
|
||
| ## AviaOne testnet snapshots | ||
| ### Step 3: Retrieve the current binary depending on your OS | ||
|
|
||
| You can find the latest AviaOne testnet snapshot [here](https://aviaone.com/blockchains-service/elystestnet-1-elys.html#8). | ||
| For MacOS/Darwin users: | ||
|
|
||
| ``` | ||
| make install | ||
| go run ./scripts/upgrade-assure/... https://services.elystestnet-1.elys.aviaone.com/elystestnet-1_2024-03-06.tar.gz ~/go/bin/elysd ~/go/bin/elysd --skip-proposal | ||
| ```bash | ||
| curl -L https://github.com/elys-network/elys/releases/download/v0.30.0/elysd-v0.30.0-darwin-arm64 -o /tmp/elysd-v0.30.0 | ||
| ``` | ||
|
|
||
| # How can I perform a test with a version upgrade that involves extensive changes to data structures? | ||
| For Linux users: | ||
|
|
||
| ``` | ||
| git checkout v0.29.30 | ||
| make install | ||
| cp -a ~/go/bin/elysd /tmp/elysd-v0.29.30 | ||
| ```bash | ||
| curl -L https://github.com/elys-network/elys/releases/download/v0.30.0/elysd-v0.30.0-linux-amd64 -o /tmp/elysd-v0.30.0 | ||
| ``` | ||
|
|
||
| ``` | ||
| go run ./scripts/upgrade-assure/... --home /tmp/elys --home2 /tmp/elysd2 https://tools.highstakes.ch/files/elys.tar.gz /tmp/elysd-v0.29.30 /tmp/elysd-v0.29.31 --skip-node-start | ||
| ``` | ||
| ### Step 4: Retrieve Testnet Snapshot | ||
|
|
||
| Fetch the latest testnet snapshot, necessary for data migration using `curl`: | ||
|
|
||
| ```bash | ||
| curl -L https://snapshots-testnet.stake-town.com/elys/elystestnet-1_latest.tar.lz4 -o /tmp/snapshot.tar.lz4 | ||
| ``` | ||
| git checkout v0.29.31 | ||
| make install | ||
| cp -a ~/go/bin/elysd /tmp/elysd-v0.29.31 | ||
| ``` | ||
|
|
||
| ### Step 5: Checkout the Previous Version | ||
|
|
||
| Switch to the previously stable version: | ||
|
|
||
| ```bash | ||
| git checkout v0.30.0 | ||
| ``` | ||
| go run ./scripts/upgrade-assure/... --home /tmp/elys --home2 /tmp/elysd2 https://tools.highstakes.ch/files/elys.tar.gz /tmp/elysd-v0.29.30 /tmp/elysd-v0.29.31 --skip-snapshot --skip-chain-init | ||
|
|
||
| ### Step 6: Run Upgrade-Assure Script | ||
|
|
||
| #### 6a: Initial Run | ||
|
|
||
| Run the upgrade-assure script without starting the node: | ||
|
|
||
| ```bash | ||
| go run ./scripts/upgrade-assure/... /tmp/snapshot.tar.lz4 /tmp/elysd-v0.30.0 ~/go/bin/elysd --skip-node-start | ||
| ``` | ||
| # Troubleshooting | ||
|
|
||
| These are some problems and its solutions when the script is executed | ||
| #### 6b: Handle Potential Errors | ||
|
|
||
| - The O.S could kill the process if you don´t have enough ram this happened in 6.6.24-1-MANJARO (64 bits) with 16gb of ram a solution was create a swapFile | ||
| Address any type errors, such as difficulties in unmarshaling strings into integer fields in Go struct fields. | ||
|
|
||
| #### 6c: Update the Script | ||
|
|
||
| Modify `scripts/upgrade-assure/types.go` to reflect data structure changes necessary to resolve type errors. | ||
|
|
||
| The `types.go` file employs the `elys` data structure types to serialize the genesis state into JSON format for initializing localnet. This file predominantly handles conversion issues where Go struggles with fields defined as integers. To address this, such fields are overridden as `json.Number`. | ||
|
|
||
| During the `read-genisis-file` step of the `upgrade-assure` process, if parsing of the genesis JSON file fails, an error is returned. This issue generally arises from integer fields that must be redefined to `json.Number`. | ||
|
|
||
| #### 6d: Retry Upgrade-Assure | ||
|
|
||
| Repeat the process after updating the script: | ||
|
|
||
| ```bash | ||
| go run ./scripts/upgrade-assure/... /tmp/snapshot.tar.lz4 /tmp/elysd-v0.30.0 ~/go/bin/elysd --skip-node-start | ||
| ``` | ||
| https://wiki.manjaro.org/index.php?title=Swap#Using_a_Swapfile | ||
|
|
||
| ### Step 7: Checkout to Latest Changes Branch | ||
|
|
||
| Switch back to the main branch to incorporate the latest changes: | ||
|
|
||
| ```bash | ||
| git checkout main | ||
| ``` | ||
| - Timeout, if you have timeout problems with the node or waiting for the next block you can use these flags: | ||
| timeout-wait-for-node is expressed in seconds | ||
| timeout-next-block is expressed in minutes | ||
|
|
||
| ### Step 8: Final Upgrade Command | ||
|
|
||
| Execute the final upgrade command to complete the upgrade process: | ||
|
|
||
| ```bash | ||
| go run ./scripts/upgrade-assure/... /tmp/snapshot.tar.lz4 /tmp/elysd-v0.30.0 ~/go/bin/elysd --skip-snapshot --skip-chain-init | ||
| ``` | ||
| --timeout-wait-for-node=600 | ||
| --timeout-next-block=15 | ||
|
|
||
| ## Testnet Snapshots Usage | ||
|
|
||
| **Snapshot Sources and Installation Procedures:** | ||
|
|
||
| ### High Stakes Testnet | ||
|
|
||
| - **Snapshot Source:** [Download the latest snapshot for High Stakes Testnet](https://tools.highstakes.ch/files/elys.tar.gz). | ||
| - **Installation Commands:** | ||
| ```bash | ||
| make install | ||
| go run ./scripts/upgrade-assure/... https://tools.highstakes.ch/files/elys.tar.gz ~/go/bin/elysd ~/go/bin/elysd --skip-proposal | ||
| ``` | ||
|
|
||
| ### Stake Town Testnet | ||
|
|
||
| - **Snapshot Source:** [Download the latest snapshot for Stake Town Testnet](https://snapshots-testnet.stake-town.com/elys/elystestnet-1_latest.tar.lz4). | ||
| - **Installation Commands:** | ||
| ```bash | ||
| make install | ||
| go run ./scripts/upgrade-assure/... https://snapshots-testnet.stake-town.com/elys/elystestnet-1_latest.tar.lz4 ~/go/bin/elysd ~/go/bin/elysd --skip-proposal | ||
| ``` | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| **Common Issues and Solutions:** | ||
|
|
||
| - **Memory Limitation:** Address processes terminated due to insufficient RAM by creating a swap file as detailed [here](https://wiki.manjaro.org/index.php?title=Swap#Using_a_Swapfile). | ||
| - **Timeout Issues:** Modify timeout settings for node responsiveness or block processing delays: | ||
|
|
||
| ```bash | ||
| --timeout-wait-for-node=600 # Time in seconds | ||
| --timeout-next-block=15 # Time in minutes | ||
| ``` |