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
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
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 sectionGovernance
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