Upgrade Module

• x/upgrade에서 live-chain에서 새로운 버전으로 업그레이드 하는 모듈(v0.44~)
• BeginBlocker hook에서 state machine이 정해진 pre-defined 블록 높이에 도달하면 블록이 진행되지 않게 함
• governance가 업그레이드를 어떻게 하는지에 관해서 아무것도 결정하지 않음
• upgrade를 안전하게 하는 것이 목적임

Cosmovisor

• governance 모듈의 chain upgrade proposal을 모니터링하며 Cosmos SDK app (terrad 등) 바이너리를 관리하는 프로세스 매니저
• proposal이 승인되면 cosmovisor가 자동으로 바이너리(새 버전)로 기존 바이너리(구 버전)를 바꾸는 역할을 함

설치 방법

// go install을 통한 설치
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest

// cosmos SDK 내에 포함된 버전을 통한 다운로드
git clone git@github.com:cosmos/cosmos-sdk
cd cosmos-sdk
git checkout cosmovisor/vx.x.x
make cosmovisor

cosmovisor 실행 파일 사용을 위해 적절한 경로 설정도 추가

cp cosmovisor/cosmovisor ~/go/bin/cosmovisor

폴더 레이아웃

다음과 같은 환경 변수가 기본적으로 세팅이 되어야 함

• DAEMON_HOME : cosmovisor/ 디렉토리가 genesis binary와 upgrade binary 등을 포함하는 위치 (e.g. $HOME/.terrad)
• DAEMON_NAME : binary 파일 이름 (e.g. terrad)
• DAEMON_ALLOW_DOWNLOAD_BINARIES (optional, default=false) : true로 세팅 시 새 바이너리를 자동으로 다운로드 함. security 이유로 validator가 아닌 full node를 대상으로 함
• DAEMON_RESTART_AFTER_UPGRADE (optional, default=true) : true일 경우 업그레이드 성공 후 기존과 동일한 flag를 가진 채 새로운 버전의 바이너리를 재시작을 함. false일 경우에는 관리자가 직접 재실행 해야 함
• DAEMON_POLL_INTERVAL (optional, default=300 millisecond) : upgrade plan 파일을 투표하는 간격의 길이.
• DAEMON_BACKUP_DIR (optional, deafult=DAEMON_HOME) : 커스텀 백업 디렉토리

columbus-6 업그레이드를 포함한 폴더 레이아웃

유의 사항

• $DAEMON_HOME/cosmovisor 는 application binary만 저장하고 있음
• cosmovisor binary는 어떤 곳이든 존재할 수 있음 (e.g. /usr/local/bin)
• app은 --home flag가 설정되어 있다면 계속해서 $HOME/.terra에 데이터를 저장하고 있음
• cosmovisor 폴더 내에 genesis와 upgrades/<name> 폴더를 직접 설치해야 함

Cosmovisor를 이용한 Upgrade 방법

기본적으로 코드 상에서 Upgrade 관련 함수가 작성 되어있다고 가정 (함수 작성 방법은 추후 포스팅)

방법 1. Auto-Download

• 기본적으로 업그레이드 전에 관련 binary 파일들을 요구함
• 하지만 쉬운 업그레이드를 원하는 사용자는 DAMON_ALLOW_DOWNLOAD_BINARIES를 이용하여 binary 파일을 자동으로 다운로드하고 설치까지 하는 것을 가능하게 함
• os/architecture와 binary 파일 URL을 맵핑하여 저장하여 사용 가능
• 자세한 방법은 여기

방법 2. Manual Upgrade

Cosmos SDK 기반으로 만들어진 Terra를 통해 설명

1. 환경변수 설정

# 예시
export DAEMON_HOME=~/.terra
export DAEMON_NAME=terrad
export DAEMON_RESTART_AFTER_UPGRADE=true

export UPGRADE_NAME=columbus-6
export KEY_NAME=harvey1
export UPGRADE_HEIGHT=20
export PROPOSAL_ID=1
export CHAIN_ID=1

2. cosmovisor 실행 파일 생성 및 디렉토리 세팅

# cosmovisor 실행 파일 생성 및 실행 경로 지정
cd ~/cosmos-sdk/cosmovisor
make cosmovisor

# cosmovisor 디렉토리 생성
mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/columbus-6/bin

# columbus-5 (구버전) 설정
cd ~/core
git checkout main
make build
cp ~/core/build/terrad $DAEMON_HOME/cosmovisor/genesis/bin

# columbus-6 (신버전) 설정
cd ~/core
git checkout release/v0.6.x
make build
cp ~/core/build/terrad $DAEMON_HOME/cosmovisor/upgrades/columbus-6/bin

3. 노드 초기화 및 어카운트 셋팅

#!/bin/sh

ACCOUNT_NAME="harvey1"
TESTNET_NAME="1"
NODE_MONIKER="test"

rm $HOME/.terra/config/genesis.json
rm -r $HOME/.terra/config/gentx/*

terrad unsafe-reset-all

terrad init --chain-id=$TESTNET_NAME $NODE_MONIKER

# voting 시간 기본 값이 172800s이기 때문에 테스트를 위해 시간 조정 필요

cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s"' $HOME/.terra/config/genesis.json) > $HOME/.terra/config/genesis.json


terrad keys add $ACCOUNT_NAME
terrad add-genesis-account $(terrad keys show $ACCOUNT_NAME -a) 100000000uluna,1000usd
terrad gentx $ACCOUNT_NAME 1000000uluna --chain-id=$TESTNET_NAME
terrad collect-gentxs

4. cosmovisor 실행

cp ~/cosmos-sdk/cosmovisor/cosmovisor ~/usr/local/bin
cosmovisor start 

cosmovisor 실행 시 current/bin의 binary 파일이 genesis/bin의 binary 파일에 의해 생성됨

5. proposal 생성 및 투표

upgrade 이름과 proposal 시 이름이 반드시 동일해야 함

# 3 단계에서 설정 voting 시간 내에 투표가 완료되어야 함
terrad tx gov submit-proposal software-upgrade $UPGRADE_NAME --title upgrade --description upgrade --upgrade-height $UPGRADE_HEIGHT --from $KEY_NAME --yes --chain-id $CHAIN_ID
terrad tx gov deposit $PROPOSAL_ID 10000000uluna --from $KEY_NAME --yes --chain-id $CHAIN_ID
terrad tx gov vote 1 yes --from $KEY_NAME --yes --chain-id $CHAIN_ID

# voting 시간이 지나면 upgrade plan 확인 가능
terrad query upgrade plan

• 정해진 height에서 노드가 정지함
• governance에 의해 proposal이 통과되면 cosmovisor가 upgrades 폴더에 있는 binary 파일로 current 폴더의 binary를 변경함

• 정상적인 업그레이드가 완료되어 v0.45.1 cosmos-sdk를 사용하는 columbus-6로 업그레이드 성공

Reference

• Chain Upgrade Guid to v0.44
• Cosmovisor Quick Start