Skip to main content

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.

note

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​

ParameterTypeExampleDescription
namestringupgrade-118Name of the plan
max_enrolment_durationinteger90Expected duration of upgrade in seconds
new_chain_idstringtestnet-9Identifier of the new chain
old_chain_idstringtestnet-8Identifier of the current chain
proposalIDstring668ID of the update proposal. It is set automatically.
reboot_requiredbooleantrueDefines if nodes require OS reboot
resourcesarray{"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_checksumstringupgrade-118-rollChecksum to use when rolling back the chain
skip_handlerbooleantrueDefines 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_upgradebooleantrueDefines 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_timeinteger1641573000Unix 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​

{
	"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:

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​

note

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 section

Transactions​

There is no transactions other than the governance proposals for this sub-module.