Search
Duplicate
Try Notion
🚧🚧
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
{"checkout": "testnet-9","git":https://github.com/KiraCore/kira","id": "kira"},
A list of resources to be used in the pipeline, such as images or external dependencies. Includes: git, checksum, checkout, 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
​