Skip to content

Commit

Permalink
add forking tool
Browse files Browse the repository at this point in the history
  • Loading branch information
@dasanchez
dasanchez committed May 26, 2024
1 parent d17ef04 commit 344de95
Show file tree
Hide file tree
Showing 11 changed files with 453 additions and 299 deletions.
311 changes: 14 additions & 297 deletions local/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,157 +1,26 @@
# v15 Local Testnet Upgrade
# Local Testnet Upgrade

These instructions will help you simulate the `v15` upgrade on a single validator node testnet as follows:
The [script](./simulate_mainnet_upgrade.sh) in this folder will help you simulate a Cosmos Hub `v17` upgrade with a single-validator fork.

- Start with gaia version: `v14.1.0`
- After the upgrade: Gaia release `v15.0.0-rc0`
- Starting Gaia version: `v16.0.0`
- Post-upgrade Gaia version: `v17.0.0-rc0`

We will use a modified genesis file during this upgrade. This modified genesis file is similar to the one we are running on the public testnet, and has been modified in part to replace an existing validator (Coinbase Custody) with a new validator account that we control. The account's mnemonic, validator key, and node key are provided in this repo.
For a full list of modifications to the genesis file, please [see below](#genesis-modifications).
The script uses a special build of Gaia to fork the chain with a single validator using a recent snapshot. The upgrade is performed by the one validator running the chain.
* The forked chain will contain the existing state from the chain we are simulating the upgrade on, but the voting period will be set to 20 seconds (this can be modified with further param change proposals).
* We set the validator keys and allocate funds to an account we control. The account's mnemonic and validator keys are provided in this repo.
* **Validator key:** [priv_validator_key](priv_validator_key.json)
* **Validator mnemonic:** [mnemonic.txt](mnemonic.txt)

If you are interested in running v15 without going through the upgrade, you can download one of the binaries in the Gaia [releases](https://github.com/cosmos/gaia/releases) page and follow the rest of the instructions up until the node is running and producing blocks.
If you are interested in running a forked node without going through the upgrade, you can edit the script to stop before the upgrade section.

* **Chain ID**: `local-testnet`
* **Gaia version:** `v14.1.0`
* **Modified genesis file:** [here](https://files.polypore.xyz/genesis/mainnet-genesis-tinkered/latest_v14.json.gz)
* **Original genesis file:** [here](https://files.polypore.xyz/genesis/mainnet-genesis-export/latest_v14.json.gz)
* **Validator key:** [priv_validator_key](priv_validator_key.json)
* **Node key:** [node_key](node_key.json)
* **Validator mnemonic:** [mnemonic.txt](mnemonic.txt)
## Cosmovisor: Manual binary setup

## Set up with Ansible Playbook
The script uses the auto-download feature of Cosmovisor for convenience. Node runners can manually build the new binary and put it into the relevant `upgrades` folder as shown below. Cosmovisor will switch to the new binary when the upgrade height is reached.

Use the example inventory file from the [cosmos-ansible](https://github.com/hyphacoop/cosmos-ansible) repo to set up a local testnet node:

```
git clone https://github.com/hyphacoop/cosmos-ansible.git
cd cosmos-ansible
ansible-playbook node.yml -i examples/inventory-local-genesis.yml -e 'target=SERVER_IP_OR_DOMAIN'
```

The playbook will set up Cosmovisor with auto-download enabled.

For additional information, visit the [examples page](https://github.com/hyphacoop/cosmos-ansible/tree/main/examples#start-a-local-testnet-using-a-modified-genesis-file).

### Upgrade proposal requirements

Log into the target machine and switch to the `gaia` user with `su gaia`.

```
export CHAIN_ID=local-testnet
export NODE_HOME=$HOME/.gaia
export USER_MNEMONIC="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art"
export USER_KEY_NAME=my-validator-account
echo $USER_MNEMONIC | gaiad --home $NODE_HOME keys add $USER_KEY_NAME --recover --keyring-backend=test
```

## Manual setup

### Requirements

Follow the [installation instructions](https://hub.cosmos.network/main/getting-started/installation.html) to understand build requirements. You'll need to install Go 1.20.

```
sudo apt update
sudo apt upgrade
sudo apt install git build-essential
curl -OL https://golang.org/dl/go1.20.linux-amd64.tar.gz
sudo tar -C /usr/local -xvf go1.20.linux-amd64.tar.gz
```

### Modify your paths
```
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> ~/.profile
source ~/.profile
```

### Build gaia

```
cd $HOME
git clone https://github.com/cosmos/gaia.git
cd gaia
git checkout v14.1.0
make install
```

### Configure the chain

First initialize your chain.

```
export CHAIN_ID=local-testnet
export NODE_MONIKER=my-local-validator # whatever you like
export BINARY=gaiad
export NODE_HOME=$HOME/.gaia
$BINARY config chain-id $CHAIN_ID --home $NODE_HOME
$BINARY config keyring-backend test --home $NODE_HOME
$BINARY config broadcast-mode block --home $NODE_HOME
$BINARY init $NODE_MONIKER --home $NODE_HOME --chain-id=$CHAIN_ID
```

Then replace the genesis file with our modified genesis file.

```
wget https://files.polypore.xyz/genesis/mainnet-genesis-tinkered/latest_v14.json.gz
gunzip latest_v14.json.gz
mv latest_v14.json $NODE_HOME/config/genesis.json
```

Replace the validator and node keys.

```
wget https://raw.githubusercontent.com/cosmos/testnets/master/local/priv_validator_key.json
mv priv_validator_key.json $NODE_HOME/config/priv_validator_key.json
wget https://raw.githubusercontent.com/cosmos/testnets/master/local/node_key.json
mv node_key.json $NODE_HOME/config/node_key.json
```

Now add your user account. This account has over 75% tokens bonded to your validator.

```
export USER_MNEMONIC="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art"
export USER_KEY_NAME=my-validator-account
echo $USER_MNEMONIC | $BINARY --home $NODE_HOME keys add $USER_KEY_NAME --recover --keyring-backend=test
```

Set minimum gas prices.

```
sed -i -e 's/minimum-gas-prices = ""/minimum-gas-prices = "0.0025uatom"/g' $NODE_HOME/config/app.toml
```

Set block sync to be false. This allows us to achieve liveness without additional peers. See this [issue](https://github.com/osmosis-labs/osmosis/issues/735) for details.

```
sed -i -e '/fast_sync =/ s/= .*/= false/' $NODE_HOME/config/config.toml
```

Add the following line under the `fast_sync` one in config.toml:
```
block_sync = false
$NODE_HOME/cosmovisor/upgrades/v17/bin/gaiad
```

### Cosmovisor

First download Cosmovisor.

```
export GO111MODULE=on
go install cosmossdk.io/tools/cosmovisor/cmd/[email protected]
```

Setup the Cosmovisor directory structure. There are two methods to use Cosmovisor:

1. **Manual:** Node runners can manually build the old and new binary and put them into the `cosmovisor` folder (as shown below). Cosmovisor will then switch to the new binary upon upgrade height.

```
cosmovisor/upgrades/v15/bin/gaiad
```

1. **Auto-download:** Allowing Cosmovisor to [auto-download](https://github.com/cosmos/cosmos-sdk/tree/main/tools/cosmovisor#auto-download) the new binary at the upgrade height automatically.

**Cosmovisor directory structure**

```shell
Expand All @@ -161,160 +30,8 @@ cosmovisor/upgrades/v15/bin/gaiad
│ └── bin
│ └── gaiad
└── upgrades
└── v15
└── v17
├── bin
│ └── gaiad
└── upgrade-info.json
```

For both methods, you should first start by creating the genesis directory as well as copying over the starting binary.

```
mkdir -p $NODE_HOME/cosmovisor/genesis/bin
cp $(which gaiad) $NODE_HOME/cosmovisor/genesis/bin
export BINARY=$NODE_HOME/cosmovisor/genesis/bin/gaiad
```

We recommend running Cosmovisor as a systemd service. Here's how to create the service:

```
touch /etc/systemd/system/$NODE_MONIKER.service
echo "[Unit]" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Description=cosmovisor-$NODE_MONIKER" >> /etc/systemd/system/$NODE_MONIKER.service
echo "After=network-online.target" >> /etc/systemd/system/$NODE_MONIKER.service
echo "" >> /etc/systemd/system/$NODE_MONIKER.service
echo "[Service]" >> /etc/systemd/system/$NODE_MONIKER.service
echo "User=root" >> /etc/systemd/system/$NODE_MONIKER.service
echo "ExecStart=/root/go/bin/cosmovisor run start --x-crisis-skip-assert-invariants" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Restart=no" >> /etc/systemd/system/$NODE_MONIKER.service
echo "LimitNOFILE=4096" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Environment='DAEMON_NAME=gaiad'" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Environment='DAEMON_HOME=$NODE_HOME'" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Environment='DAEMON_ALLOW_DOWNLOAD_BINARIES=true'" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Environment='DAEMON_RESTART_AFTER_UPGRADE=true'" >> /etc/systemd/system/$NODE_MONIKER.service
echo "Environment='DAEMON_LOG_BUFFER_SIZE=512'" >> /etc/systemd/system/$NODE_MONIKER.service
echo "" >> /etc/systemd/system/$NODE_MONIKER.service
echo "[Install]" >> /etc/systemd/system/$NODE_MONIKER.service
echo "WantedBy=multi-user.target" >> /etc/systemd/system/$NODE_MONIKER.service
```

Set the following environment variables for the Cosmovisor service:

```
export DAEMON_NAME=gaiad
export DAEMON_HOME=$NODE_HOME
```

Before running the service, we recommend reloading the systemctl daemon and restarting the journald service.

```
sudo systemctl daemon-reload
sudo systemctl restart systemd-journald
```

### Run your node

You are now ready to start your node like this:

```
sudo systemctl enable --now $NODE_MONIKER.service
```

And view the logs like this:

```
sudo journalctl -fu $NODE_MONIKER.service
```

**Please make sure your node is running and producing blocks before you proceed further!** It can take up to 10 minutes for your node to start up. Once it's producing blocks you'll start seeing log messages like the following:

```
INF committed state app_hash=99D509C03FDDFEACAD90608008942C0B4C801151BDC1B8998EEC69A1772B22DF height=16188740 module=state num_txs=0
```

## Manually prepare the upgrade binary (if you do not have auto-download enabled on Cosmovisor)

Build the upgrade binary: v15 requires GO v1.20.
```
wget -q https://go.dev/dl/go1.20.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.linux-amd64.tar.gz
cd $HOME/gaia
git checkout v15.0.0-rc0
git pull
make install
```

Copy over the v15 binary into the correct directory.
```
mkdir -p $NODE_HOME/cosmovisor/upgrades/v15/bin
cp $(which gaiad) $NODE_HOME/cosmovisor/upgrades/v15/bin
export BINARY=$NODE_HOME/cosmovisor/upgrades/v15/bin/gaiad
```

## Submit and vote on a software upgrade proposal

You can submit a software upgrade proposal without specifying a binary, but this only works for those nodes who are manually preparing the upgrade binary.

```
gaiad tx gov submit-proposal software-upgrade v15 \
--title "v15 Upgrade" \
--deposit 100uatom \
--upgrade-height TBD \
--upgrade-info '{"binaries": {"darwin/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0-rc0/gaiad-v15.0.0-rc0-darwin-amd64?checksum=sha256:22e704a35300eb1aa70d437414d54e2ff303afa7d4ce09ef620b7e60d15cff99", "darwin/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0-rc0/gaiad-v15.0.0-rc0-darwin-arm64?checksum=sha256:ca58d7d0f5081ce8b1fbfb59275d8eb274620aab67b59cd97cdb2d33ab93c44c", "linux/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0-rc0/gaiad-v15.0.0-rc0-linux-amd64?checksum=sha256:30e9f0042196126e199ca97c1f03ff5a733e4528b226f820777cf43dfbe143e7", "linux/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0-rc0/gaiad-v15.0.0-rc0-linux-arm64?checksum=sha256:4f3101d842f41dfb5055314eeb8f3d6900e310a0c7ff947f7621430a028ef677", "windows/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0-rc0/gaiad-v15.0.0-rc0-windows-amd64.exe?checksum=sha256:45a1d76de1c57f889a29bae9f0d65eb7baad65de83dee87d4f87455b25a32980", "windows/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0-rc0/gaiad-v15.0.0-rc0-windows-arm64.exe?checksum=sha256:820f6a5b414595964ea855364e09ba07aab4fb4ec84173ea543000c013d2a8c9"}}' \
--description "Upgrade Gaia to v15" \
--gas auto \
--fees 1000uatom \
--from $USER_KEY_NAME \
--keyring-backend test \
--chain-id $CHAIN_ID \
--home $NODE_HOME \
--node tcp://localhost:26657 \
--yes
```

Get the proposal ID from the TX hash (you will get a different hash):
`$NODE_HOME/cosmovisor/current/bin/gaiad q tx DB297FDA1DAE700B0155388220703A4074E0C48595635C6A91BBEAF2FF266412`

Vote on it.

```
gaiad tx gov vote <proposal ID> yes \
--from $USER_KEY_NAME \
--keyring-backend test \
--chain-id $CHAIN_ID \
--home $NODE_HOME \
--gas auto \
--fees 500uatom \
--node tcp://localhost:26657 \
--yes
```

After the voting period ends, you should be able to query the proposal to see if it has passed. Like this:

```
gaiad query gov proposal <proposal ID> --home $NODE_HOME
```

After `PROPOSAL_STATUS_PASSED`, wait until the upgrade height is reached Cosmovisor will now auto-download the new binary specific to your platform and apply the upgrade.

## Genesis Modifications

Full list of modifications are as follows:

* Swapping chain id to local-testnet
* Increasing balance of cosmos1r5v5srda7xfth3hn2s26txvrcrntldjumt8mhl by 175000000000000 uatom
* Increasing supply of uatom by 175000000000000
* Increasing balance of cosmos1r5v5srda7xfth3hn2s26txvrcrntldjumt8mhl by 550000000000000 uatom
* Increasing supply of uatom by 550000000000000
* Increasing delegator stake of cosmos1wvvhhfm387xvfnqshmdaunnpujjrdxznr5d5x9 by 550000000000000
* Increasing validator stake of cosmosvaloper1r5v5srda7xfth3hn2s26txvrcrntldju7lnwmv by 550000000000000
* Increasing validator power of 973C48DF8B3356C45E44494723A6E0D45DEB8131 by 550000000
* Swapping min governance deposit amount to 1uatom
* Swapping tally parameter quorum to 0.000000000000000001
* Swapping tally parameter threshold to 0.000000000000000001
* Swapping governance voting period to 60s
* Swapping staking unbonding_time to 1s

Please note that you will need to set `fast-sync` to false in your `config.toml` file and wait for approximately 10mins for a single node testnet to start. This is due to an [issue](https://github.com/osmosis-labs/osmosis/issues/735) with state export based testnets that can't get to consensus without multiple peered nodes.
1 change: 0 additions & 1 deletion local/mnemonic.txt
View file

This file was deleted.

1 change: 0 additions & 1 deletion local/node_key.json
View file

This file was deleted.

0 local/previous-local-testnets/v10/README.md → ...vious-local-testnets/v10-local-testnet.md
View file
File renamed without changes.
0 local/previous-local-testnets/v11/README.md → ...vious-local-testnets/v11-local-testnet.md
View file
File renamed without changes.
0 local/previous-local-testnets/v12/README.md → ...vious-local-testnets/v12-local-testnet.md
View file
File renamed without changes.
0 local/previous-local-testnets/v13/README.md → ...vious-local-testnets/v13-local-testnet.md
View file
File renamed without changes.
0 local/previous-local-testnets/v14/README.md → ...vious-local-testnets/v14-local-testnet.md
View file
File renamed without changes.
Loading

0 comments on commit 344de95

Please sign in to comment.