Upgrade Module

Upgrade Module is responsible for ensuring smooth transition between various iterations of the KIRA Network while preserving current chain state. The upgrade process is managed by the KIRA governance set with permissions to propose and vote on the "Upgrade Plan". The upgrade plan is a set of instruction in the JSON format hosted on-chain. Upgrade Plan contains informations how and when validators should proceed with the upgrade. One of the extra features of the Upgrade Module is informing new network participants what are the software resources necessary to join the network, thus making the process of acquiring essential references and checksums fully trustless.

Upgrades can take place as either Hard Forks or Soft Forks. In case of Hard Forks its expected that new blockchain application is incompatible with current chain state storage and thus requires to launch from a new genesis with new chain-id to prevent double signing. In case of Soft Forks is expected that there is no impact on the chain-state thus network can continue with the same chain-id without need for exporting & generating new genesis file.

If we want to update parts of the infrastructure other than sekaid such as interex, infrastructure manager etc, then we should set a skip_handler property. If skip handler is set to true then check if sekaid version changes will be omitted and network will be able to continue running. If set to false the network will halt at the time defined by upgrade_time property and remain stopped until sekaid binary is upgraded.

If the new version of the sekaid application is completely incompatible with the old database state, or if the state of database is so large that validators can’t continue running we can reset entire chain by utilising instate_upgrade property.  If instate_upgrade is set to true then a Hard Fork will be executed and the new_chain_id and old_chain_id MUST be different. If instate_upgrade is set to false then a Soft Fork will be executed and the database does NOT have to be erased.

Upgrade Configurations

Hard Fork with NO changes made in sekaid binary - used to upgrade other binaries and wiping old database state (e.g. to save disk space)

instate_upgrade - false

skip_hangler - true

new_chain_id - MUST be different then old_chain_id

Hard Fork with changes in sekaid binary - used to upgrade network in the case where old database state is incompatible with new release

instate_upgrade - false

skip_hangler - false

new_chain_id - MUST be different then old_chain_id

Soft Fork without changes in sekaid binary  - used to upgrade other binaries, but preserve old database state

instate_upgrade - TBD

skip_hangler - TBD

new_chain_id - MUST be the same as old_chain_id

Plan Example

{
  "plan": {
    "max_enrolment_duration": "<integer>", // expected duration od upgrade in seconds
    "name": "<string>", // name of the plan
    "new_chain_id": "<string>", // identifier of the new chain
    "old_chain_id": "<string>", // identifier of the current chain
    "reboot_required": <boolean>, // defines if nodes require OS reboot
    "resources": [
      {
        "checkout": "<string>", // git branch or commit checkout
        "checksum": "<string>", // expected SHA256 hash of the resource
        "git": "<string>", // URL to resource or git branch
        "id": "<string>" // unique identifier of the resource
      }, { ... }, ...
    ],
    "rollback_checksum": "<string>", // checksum to use when rolling back the chain
    "skip_handler": <boolean>, // defines if on-chain handlers of the upgrade process should be skipped (skip check if version of binary changed)
    "instate_upgrade": <boolean>, // defines if database state should be deleted or persisted
    "upgrade_time": "<integer>" // unix timestamp of the exact time the update should be executed
  }
}

JSON

Plan Types

Upgrade process is an off-chain mechanism executed by the daemon service of the KIRA Manager (KM). Using KM is not mandatory thus any validator can setup their own dedicated CD/CI pipeline tools such as Jenkins or Teamcity. Informations about upcoming upgrades from the following two INTERX endpoints:

<ip>:11000/api/kira/upgrade/next_plan

<ip>:11000/api/kira/upgrade/current_plan

The “current” plan contains informations & resources regarding current release while the “next” plan contains informations & resources regarding upcoming release. It is further possible to resource references (github links & branches) specified in the “current” plan endpoint of a trusted node while joining the the network for the very first time. 

Manual Upgrades

If KM is not used and new genesis file is required (hard fork), node operator must create it by first exporting genesis at the height where network stopped (node daemon should be shut down) and then passing the  it through a dedicated new-genesis-from-exported command. It should be noted that the sekaid application must be upgraded prior to executing  new-genesis-from-exported command, otherwise application might not be aware how to interpret and convert old genesis to the new 

SEKAI="/home/go/src/github.com/kiracore/sekai"
EXPORTED_GENESIS="/tmp/exported-genesis.json"
NEW_GENESIS="/tmp/new-genesis.json"

# cleanup old files
rm -fv $EXPORTED_GENESIS $NEW_GENESIS

#ensure sekaid process is killed gracefully
pkill -15 sekaid || echoWarn "WARNING: Failed to kill sekaid, process might already be dead"

# export current genesis
sekaid export --home=$SEKAID_HOME > $EXPORTED_GENESIS

# update repository
cd $SEKAI
git fetch --all
git checkout $BRANCH_TO_CHECKOUT
make install

# convert exported genesis to a new compatible version
sekaid new-genesis-from-exported $EXPORTED_GENESIS $NEW_GENESIS

Bash

NOTE: Proposals can be raised using via CLI sekaid tx customgov proposals command. The --help flag can be used to discover further options. To raise a certain proposal a dedicated permission is required. For example to submit SoftwareUpgrade message a PermCreateSoftwareUpgradeProposal (28) permission must be assigned to the account creating said proposal. For example to vote on the SoftwareUpgrade a PermVoteSoftwareUpgradeProposal (29) is needed. To find available proposal types and corresponding to them permissions required to submit or vote see Proposals documentation.

Commands Examples

Proposing Upgrade Plan

# CLI - Demo Hard Fork, NO changes in binaries (instate-upgrade: false, skip-handler: true)
HASH="bafybeigx2qmj26n3q7ueqizjqwcorokzwmvodsnfx4gcljpthpqsqgl3zu" && \
RES1="{\"id\":\"kira\",\"git\":\"https://ipfs.kira.network/ipfs/$HASH/kira.zip\"}" && \
sekaid tx upgrade proposal-set-plan \
 --name="Hard Fork - Test Upgrade - $(date)" \
 --instate-upgrade=false \
 --skip-handler=true \
 --resources="[${RES1}]" \
 --min-upgrade-time=$(($(date -d "$(date)" +"%s") + 900)) \
 --old-chain-id="$NETWORK_NAME" \
 --new-chain-id="$(echo $NETWORK_NAME | cut -d '-' -f 1)-$(($(echo $NETWORK_NAME | cut -d '-' -f 2) + 1))" \
 --max-enrollment-duration=60 \
 --upgrade-memo="This is a hard fork test upgrade with no changes in sekaid binary" \
 --from=validator --keyring-backend=test --home=$SEKAID_HOME --chain-id=$NETWORK_NAME --fees=100ukex --log_format=json --yes --output=json | txAwait 180

# CLI - Demo Hard Fork, changes in binaries (instate-upgrade: false, skip-handler: false)
HASH="bafybeicm4r5ny2fysxmnvv6wxxkrkevrwle2j2jqc5ymv2oodg3yxms7wq" && \
RES1="{\"id\":\"kira\",\"git\":\"https://ipfs.kira.network/ipfs/$HASH/kira.zip\"}" && \
sekaid tx upgrade proposal-set-plan \
 --name="Hard Fork - Test Upgrade - $(date)" \
 --instate-upgrade=false \
 --skip-handler=false \
 --resources="[${RES1}]" \
 --min-upgrade-time=$(($(date -d "$(date)" +"%s") + 900)) \
 --old-chain-id="$NETWORK_NAME" \
 --new-chain-id="$(echo $NETWORK_NAME | cut -d '-' -f 1)-$(($(echo $NETWORK_NAME | cut -d '-' -f 2) + 1))" \
 --rollback-memo="roll" \
 --max-enrollment-duration=60 \
 --upgrade-memo="This is a hard fork test upgrade with changes made to the sekaid binary" \
 --from=validator --keyring-backend=test --home=$SEKAID_HOME --chain-id=$NETWORK_NAME --fees=100ukex --log_format=json --yes --output=json | txAwait 180

# Vote on the proposal (e.g. voting on the last proposal)
voteYes $(lastProposal) validator

Bash

Query Upgrade Plans

# Current Upgrade Plan
# CLI
sekaid query upgrade current-plan --output=json --chain-id=$NETWORK_NAME --home=$SEKAID_HOME | jq
# INTERX
curl "<ip>:11000/api/kira/upgrade/current_plan" | jq
# KM
showCurrentPlan

# Next Upgrade Plan
# CLI
sekaid query upgrade next-plan --output=json --chain-id=$NETWORK_NAME --home=$SEKAID_HOME | jq
# INTERX
curl "<ip>:11000/api/kira/upgrade/next_plan" | jq
# KM
showNextPlan

Bash