Upgrading nodes and chains

Keeping up to date with new features and maintenance releases

Once a MultiChain network is up and running, three kinds of upgrades can be performed. The first is to upgrade the MultiChain software running on one or more nodes, to take advantage of new node-level features or the fixes in a maintenance release. The second is to upgrade the blockchain protocol, to activate new network-level features, beginning from a certain block. And the third is to upgrade certain other blockchain parameters, to scale the blockchain up or down or change its access rules.

Instructions for performing these upgrades are described below. It should be noted that a protocol upgrade will often require a prior software upgrade of the nodes in the network, because the new protocol is only supported by a new version of MultiChain.

Upgrading MultiChain software

These steps should be followed for each computer on which MultiChain is installed and needs to be upgraded:

  1. If MultiChain is currently running for a chain, you can check its version in the version field of the response to the getinfo command. There is also a nodeversion field containing a numerical version which is guaranteed to increase with each release.
  2. If MultiChain is not running, its version can be checked by running multichaind -version on the command line.
  3. To upgrade MultiChain, stop any running nodes using the stop API command ( multichain-cli [chain-name] stop from the command line). Also exit from any multichain-cli processes running in interactive mode.
  4. Verify that no MultiChain software is currently running. On Linux or Mac, use ps -x. On Windows, use the Windows Task Manager or the tasklist command.
  5. Follow the regular instructions to download and install MultiChain, overwriting the previous versions of the MultiChain executables.
  6. Restart any nodes required in the normal way: multichaind [chain-name] -daemon

Upgrading blockchain protocol and other parameters

Protocol and parameter upgrades are managed by one or more of a chain’s administrators as follows:

  1. Check the chain’s current protocol version and other parameters (as of the most recent block) using getblockchainparams. The protocol version must be at least 10008 to allow protocol upgrading, and 20007 to allow upgrading of other blockchain parameters.
  2. If upgrading the protocol version, check whether the MultiChain software being used by the other network’s participants supports the new version. Each can run multichaind -version to see the protocol versions supported by their copy of MultiChain – if necessary they should upgrade their software by following the steps in the previous section.
  3. Once the network participants are ready, create the pending (as yet unapproved) upgrade from an address which has both admin and create permissions. A node with the private key for this address should run the following, with values in [square brackets] substituted as appropriate:

    createfrom [from-address] upgrade [upgrade-name] false [new-params]

    The [new-params] structure is a JSON object containing the blockchain parameters to change, for example {"protocol-version":20010} or {"target-block-time":5, "maximum-block-size":16777216}. To apply the upgrade from a specific block number, include "startblock":[block-number] inside this JSON object.

  4. On any node, check the required field of listupgrades [upgrade-name] to see how many administrators need to approve the upgrade. This is equal to the number of addresses with admin permissions multiplied by the admin-consensus-upgrade blockchain parameter, rounded up.
  5. Each required administrator should approve the upgrade by running the following on the node holding their private key:

    approvefrom [from-address] [upgrade-name] true

  6. After each admin’s approval, check they appear in the admins field of listupgrades [upgrade-name] and that required has gone down.
  7. Once enough approvals have been given, check that the approved field of listupgrades [upgrade-name] is true.
  8. Wait for the next block (or specified block number) to appear, then check that the appliedblock field of listupgrades [upgrade-name] shows this block’s height. The appliedparams field will show changes that were made successfully. The skippedparams field will show any changes that could not be made, along with the reason why.

Some further notes about this process:

  • If a node is running an old version of MultiChain that does not support a chain’s new protocol version, a -718 (RPC_UPGRADE_REQUIRED) error will be given for most API commands sent to that node.
  • A full history of pending or approved upgrades can be viewed using listupgrades on any node.
  • If an admin’s private key is not held in a node’s wallet, upgrades can be created and approved using raw transactions.