Keeping up to date with new features and maintenance releases

Once a MultiChain network is up and running, two 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 as a whole, to activate new network-level features that change the chain’s consensus rules, beginning from a certain block.

Instructions for performing these two types of upgrades are described in separate sections 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

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

  1. Check the chain’s current protocol version (as of the most recent block) in the protocol-version field of getblockchainparams. This version must be at least 10008 to allow protocol upgrading.
  2. Decide on the new protocol version, e.g. 10009. The participants in the network should be informed of this, and check whether their MultiChain software 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 '{"protocol-version":[new-version]}'

    To apply the upgrade from a specific block number, substitute '{"protocol-version":[new-version],"startblock":[block-number]}' for the last parameter above.

  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.
  9. On every node in the network, confirm the new protocol version is displayed in the output of getblockchainparams.

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.