Software Updates

The Algorand node software is upgraded from time to time, and some of these updates may contain a consensus protocol upgrade. When there is no protocol upgrade, it is not be necessary to upgrade the node software, but it may be desirable to do so to take advantage of new features and/or bug fixes.

However, when a new version of algod contains a protocol upgrade, an important process is kicked off in which online accounts effectively vote for or against a new protocol with the blocks they propose. These protocol upgrade voting periods last 10,000 rounds, and each block produced counts as one vote.

When the network is in a voting period, additional details can be seen in the output of running goal node status:

Last committed block: 46248141
Time since last block: 2.3s
Sync Time: 0.0s
Last consensus protocol: https://github.com/algorandfoundation/specs/tree/925a46433742afb0b51bb939354bd907fa88bf95
Next consensus protocol: https://github.com/algorandfoundation/specs/tree/925a46433742afb0b51bb939354bd907fa88bf95
Round for next consensus protocol: 46248142
Next consensus protocol supported: true
Last Catchpoint:
Consensus upgrade state: Voting
Yes votes: 3
No votes: 2097
Votes remaining: 7900
Yes votes required: 9000
Vote window close round: 46256042
Genesis ID: mainnet-v1.0
Genesis hash: wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=

The new protocol is activated if 90% of the votes—9000 blocks within the 10,000 block range—are in favor of the new protocol. If the new protocol is not activated, the voting period ends and the network continues to run on the current protocol. If a new protocol is approved, it will be activated after a cooldown period that may range from 10,000-150,000 rounds (or more, in special circumstances). At this point, all nodes must be running the new protocol. If a node is not running the new protocol, it will be kicked offline and unable to participate in consensus until it is upgraded.

Note

Although the next protocol to be activated following a voting period is generally the next version with a higher version number, this may not always be the case. In extenuating circumstances, it may be necessary or node operators to downgrade their software to approve falling back to a previous protocol version in order to resolve an issue.

Updating Node Software

Node software updates can be automated, but node runners are encouraged to read release notes to be aware of changes included in new versions of algod and decide if and when updating is appropriate for their situation.

Caution

Node runners should avoid scheduling updates to run automatically at a common time, such as 00:00 UTC or at the top of any hour, especially if they have significant online stake. If a large enough amount of stake went offline because nodes were simultaneously running an automated update, it is possible that the network could briefly halt while waiting for enough stake to certify blocks.

NodeKit Install

If you installed your node with NodeKit, NodeKit updates it too. When a newer version of algod is available, the terminal user interface (TUI) shows [UPDATE AVAILABLE] next to the node version in the Protocol panel, or an Upgrade Available: true row in terminals narrower than 90 columns. NodeKit also checks for new releases of itself every time it starts, and prints a warning if one is available.

To upgrade, run this from the directory that holds the nodekit binary:

./nodekit upgrade

This does two things, in order:

1. If the latest NodeKit release differs from the one you are running, it downloads it and replaces the nodekit binary in place.
2. It upgrades the algorand package through your package manager (apt-get or dnf on Linux, Homebrew on macOS) and restarts the node service.

If algod was not installed through one of those package managers, upgrade stops with an error and exit status 1. Upgrade such installs the same way they were installed.

Expect a short interruption while algod restarts. If your account is online, see Going Offline Gracefully before you upgrade.

Linux - Package Manager Install

The RPM or Debian packages in the package repository are updated automatically, but this does not mean that the node installation on your local machine is updated automatically. Depending on your Linux distribution and version, you may have or need to install unattended-upgrades to handle automatic updates.

Linux or MacOS - Update Script Install

If your node was installed using the updater script, follow this approach. You can check for and install the latest updates by running the following at any time from within your node directory:

./update.sh -d ~/node/data

Note that the -d argument has to be specified when updating. It will query S3 for available builds and see if there are newer builds than the currently installed version. To force an update, run:

./update.sh -i -c stable -d ~/node/data

If there is a newer version, it will be downloaded and unpacked. The node will shutdown, the binaries and data files will be archived, and the new binaries will be installed. If any part of the process fails, the node will restore the previous version (bin and data) and restart the node. If it succeeds, the new version is started. The automatic start can be disabled by adding the -n option.

Setting up a schedule to automatically check for and install updates can be done with CRON.

crontab -e

Add a line that looks like this (run update.sh every hour, on the half-hour, of every day), where user is the name of the account used to install / run the node:

30 * * * * /home/user/node/update.sh -d /home/user/node/data >/home/user/node/update.log 2>&1

Removing a NodeKit-Installed Node

If your account is online, register it offline first and wait 320 rounds. See Going Offline Gracefully. Then:

./nodekit stop
./nodekit uninstall

uninstall removes the algorand package and the service definition. It leaves the data directory in place (~/.algorand on macOS, /var/lib/algorand on Linux) because it holds the ledger and any participation keys. On macOS the launchd plist at /Library/LaunchDaemons/com.algorand.algod.plist is also left behind. uninstall fails if algod was not installed through a package manager: always on Linux, and on macOS unless you pass --force.

On macOS, to remove everything, including the data directory, use --force:

./nodekit uninstall --force

On macOS, --force stops algod, deletes whichever of /var/lib/algorand, ~/node/data and ~/.algorand holds an Algorand data directory, and deletes the plist. On Linux, --force does not stop algod or delete the data directory; delete /var/lib/algorand yourself after uninstalling. Your participation keys go with the data directory, so only do this once your accounts are offline.

Neither form removes the nodekit binary itself. Delete it from wherever you ran the installer.