Upgrade Module

Concept

The Upgrade Module plays a crucial role in ensuring seamless transitions between different versions of the KIRA Network while preserving the current chain state. KIRA's governance is responsible for managing the upgrade process with permissions to propose and vote on the "Upgrade Plan". The Upgrade Plan is a set of JSON-formatted instructions hosted on-chain that details how and when validators should proceed with the upgrade. Additionally, the Upgrade Module offers a unique feature that informs new network participants about the necessary software resources to join the network, thereby ensuring the process of acquiring essential references and checksums is entirely trustless.

Upgrades can occur as either Hard Forks or Soft Forks. Hard Forks are executed when the new blockchain application is incompatible with the current chain state storage, requiring launching from a new genesis with a new chain ID to prevent double signing. On the other hand, Soft Forks are executed when no impact on the chain-state is expected, allowing the network to continue with the same chain ID without exporting and generating a new genesis file.

If a consensus node casts a negative vote on an upgrade proposal that is later approved, it will automatically be paused at the beginning of the upgrade.

Parameters

Parameter	Type	Example	Description
name	string	upgrade-118	Name of the plan
max_enrolment_duration	integer	90	Expected duration of upgrade in seconds
new_chain_id	string	testnet-9	Identifier of the new chain
old_chain_id	string	testnet-8	Identifier of the current chain
proposalID	string	668	ID of the update proposal. It is set automatically.
reboot_required	boolean	true	Defines if nodes require OS reboot
resources	array	{"version": "testnet-9","url":https://github.com/KiraCore/kira","id": "kira"},	A list of resources to be used in the pipeline, such as images or external dependencies. Includes: url, checksum, version, id.
rollback_checksum	string	upgrade-118-roll	Checksum to use when rolling back the chain
skip_handler	boolean	true	Defines if sekaid on-chain handlers of the upgrade process should be skipped. If true, sekaid version changes will be omitted and the network will continue running. If false, the network will halt at the upgrade_time and remain stopped until sekaid binary is upgraded
instate_upgrade	boolean	true	Defines if database state should be deleted or persisted. If set to true then a Hard Fork will be executed and the new_chain_id and old_chain_id must be different. If set to false , a Soft Fork will be executed and the database does not have to be erased.
upgrade_time	integer	1641573000	Unix timestamp of the exact time the update should be executed

Upgrade configuration examples

Hard Fork with no change made in sekaid binary - used to upgrade other binaries such as INTERX or infrastructure manager, and wiping old database state (e.g. to save disk space)

instate_upgrade - false

skip_handler - 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_handler - 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_handler - TBD

new_chain_id - MUST be the same as old_chain_id

Upgrade plan example

JSON

Copy

{
	"plan": {
		"max_enrolment_duration": "90",
		"name": "upgrade-118",
		"new_chain_id": "testnet-9",
		"old_chain_id": "testnet-8",
		"proposalID": "668",
		"reboot_required": true,
		"resources": [
			{
			"checkout": "testnet-9",
			"git": "https://github.com/KiraCore/kira",
			"id": "kira"
			},
			{
			"checkout": "testnet-9",
			"git": "https://github.com/KiraCore/sekai",
			"id": "sekai"
			},
			{
			"checkout": "testnet-9",
			"git": "https://github.com/KiraCore/sekai",
			"id": "interx"
			}
		],
		"rollback_checksum": "upgrade-118-roll",
		"skip_handler": true,
		"upgrade_time": "1641573000"
		}
}

Upgrade process

The KIRA network can be upgraded through an off-chain mechanism executed by the daemon service of the KIRA Manager (KM). However, it is not mandatory to use KM to upgrade the network, and node operators can set up their own dedicated CD/CI pipeline tools, such as Jenkins or Teamcity.

To keep up-to-date with upcoming upgrades, operators can obtain information from two INTERX endpoints:

/<ip>:11000/api/kira/upgrade/current_plan: The “current” plan contains information and resources regarding the current release.

/<ip>:11000/api/kira/upgrade/next_plan: The “next” plan contains information and resources regarding the upcoming release. Nodes can also obtain resource references, such as GitHub links and branches, specified in the “current” plan endpoint of a trusted node while joining the network for the very first time.

Manual hard fork

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

Node operators can execute the following steps to manually hard fork the network:

Bash

Copy

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

CLI syntax & examples

Each CLI command and proposal process in KIRA requires specific permissions. These permissions must be added to the account's whitelist or obtained as sudo permissions for direct changes. Refer to the Roles & Permissions documentation for more details. $SIGNER represents the transaction signer's account name or address. For instructions on setting common flags as environment variables, such as $FLAGS_TX and $FLAGS_QR, see the CLI flags configuration section

Governance

If a consensus node casts a negative vote on an upgrade proposal that is later approved, it will automatically be paused at the beginning of the upgrade.

Transactions

N/A

Queries

query upgrade

current-plan - Query the current plan

next-plan - Query the nexy plan

Display the current plan

Bash

Copy

sekaid query upgrade current-plan $FLAGS_QR | jq 

Display the next plan

Bash

Copy

sekaid query upgrade next-plan $FLAGS_QR | jq 