Skip to main content

Upgrade Module

Upgrades can occur as either Hard Forks or Soft Forks. Hard Forks are executed when the new SEKAI version is incompatible with the current 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 SEKAI 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.

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

Example of Upgrade Proposal Plan​

{
  "proposal_id": "1",
  "title": "HARD UPGRADE to ver v0.12.24",
  "description": "Upgrade the network",
  "content": {
    "@type": "/kira.upgrade.ProposalSoftwareUpgrade",
    "name": "to-chaosnet-2",
    "resources": [
      {
        "id": "kira",
        "url": "https://github.com/KiraCore/kira/releases/download/v0.12.25/kira.zip",
        "version": "v0.12.25",
        "checksum": "6c021d91c53b1ee611715aaeeccdf22229e721d6532233db11f15dc45a3b325a"
      }
    ],
    "upgrade_time": "1714400646",
    "old_chain_id": "chaosnet-1",
    "new_chain_id": "chaosnet-2",
    "rollback_checksum": "1",
    "max_enrolment_duration": "1",
    "memo": "Upgrade to chaosnet-2",
    "instate_upgrade": false,
    "reboot_required": true,
    "skip_handler": false
  },
  "submit_time": "2024-04-29T13:52:25.605037930Z",
  "voting_end_time": "2024-04-29T13:57:25.605037930Z",
  "enactment_end_time": "2024-04-29T14:02:25.605037930Z",
  "min_voting_end_block_height": "1602",
  "min_enactment_end_block_height": "1603",
  "result": "VOTE_PENDING",
  "exec_result": ""
}

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

Parameters​

ParameterTypeExampleDescription
namestringto-chaosnet-2Name of the plan
max_enrolment_durationinteger1Expected duration of upgrade in seconds
new_chain_idstringchaosnet-1Identifier of the new chain
old_chain_idstringchaosnet-2Identifier of the current chain
proposalIDstring668ID of the update proposal. It is set automatically.
reboot_requiredbooleantrueDefines if nodes require OS reboot
resourcesresources[]List of resources related to each stack to be upgrade in this proposal.
rollback_checksumstringupgrade-118-rollChecksum to use when rolling back the chain
skip_handlerbooleanfalseDefines 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_upgradebooleanfalseDefines 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

Resources​

ParameterTypeExampleDescription
idstringsekaiIdentify the stack to be updated, for instance, SEKAI, MIRO, INTERX, etc.
urlstringhttps://github.com/KiraCore/kira/releases/download/v0.12.25/kira.zipUrl source of the upgrade archive
versionstringv0.12.25Version to be upgraded to.
checksumstring6c021d91c53b1ee611715aaeeccdf22229Checksum of the archive of the upgrade binaries

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.

Building the future of trustless computing by enabling scalable solutions for resource-intensive applications
2024 KIRA Network, All rights reserved.
Ecosystem
HomeToken & EconomicsBuild on KIRARun a node
Resources
GithubCareersBlogContact us
Community
XTelegramDiscord
2024 KIRA Network, All rights reserved.