Skip to content

V21.0

Node Protocol Database Release Date Release Notes GitHub Links
21.0 18 18 2020-06-16 V21.0 Release - Milestone - Changelog
Known Issue V19+: 'Too many open files'

  • Issue: The following error, or a similar one, can be seen when attempting to run a full node on some versions of macOS, Linux and possibly other operating systems. This is most common when using the built-in Qt wallet or other GUI-based wallets: "Exception while running wallet: open: Too many open files" or other errors containing "Too many open files". This is due to some systems having a very low default file descriptor limit and V19.0+ uses more of them after the move to TCP.

  • Solution: Increasing the file limits is needed to resolve this. See this known issue for more details on resolution.

Known Issue Linux V21: 'unable to find libboost'

If you are on Linux and unable to get V21.0 to start, unable to find libboost... https://github.com/nanocurrency/nano-node/releases/download/V21.0/nano-node-V21.0.1-Linux.tar.bz2 has been added to the release artifacts with the correct lib rpath. Please use this if you do not wish to move the lib folder into the bin folder after extraction.

Known Issue Windows V21: Crash when using config node.logging.stable_log_filename

Setting node.logging.stable_log_filename configuration option to true results in a node crash on Windows in V21.0 and V21.1, after a node restart. This must be set to false.

Upgrade Notices

Upgrade notices for nodes upgrading below V21.0

These upgrade notices and other details are only for nodes upgrading from V20.0 and lower. For operators upgrading to the latest from V21.0 or higher there are no special considerations.

The following key upgrade details should be reviewed by all node operators to determine how they will impact plans for upgrading:

Database upgrades

An in-place database upgrade will occur with this release to accomodate epoch-related flags. Machines will need at least 30GB free disk space to accommodate the upgrade. During the upgrade process, which may take multiple hours to complete depending on the machine specs, the node will not participate on the network or respond to RPC calls.

As a result, the recommended approach is to upgrade the ledger in a separate environment before replacing on production. For detailed steps on this approach and other options, see the Updating the node section of the Ledger Management page.

Minor RPC breaking changes

Although breaking changes were kept to a minimum in this release, there are two RPC calls with such changes: work_validate and bootstrap_status. For integrations using them, carefully review the additional details on these changes included in the RPC Updates section below.

Upcoming v2 epoch upgrade

As outlined in the February Development Update: V21 PoW Difficulty Increases, an epoch block distribution must be done to complete the upgrade to the new work difficulty thresholds. All integrations generating work are encouraged to review the details on the Network Upgrades page under the Upcoming upgrades section ahead of the epoch V2 distribution.

Only nodes V21.0+ will be active after epoch distribution

Nodes upgrading to V21.0+ will remain peered with nodes V19.0 and V20.0 on the network until the epoch v2 block distribution begins. After the first epoch v2 block is distributed, all nodes not running V21.0+ will no longer be able to participate on the network. This distribution will occur once 90% of voting weight and key services on the network have upgraded. Communications around the progress towards this goal will be sent following the release.

More details about this network upgrade can be found on the Network Upgrades page under the Upcoming upgrades section

All network participants are encouraged to upgrade to V21.1 as soon as possible to avoid disruption.

UDP disabled by default

With all active peers capable of communicating via TCP, the UDP connections will be disabled by default in this version. To avoid disruptions, all nodes should allow traffic on 7075 TCP (see Network Ports details) and once upgraded, the peers RPC call should return at least dozens of peers and the confirmation_quorum RPC call should have a peers_stake_total value in the high tens of millions of Nano.

Although not recommended, if necessary the temporary use of UDP can be done with the new --enable_udp flag.

Major Updates

Work difficulty increase

As mentioned in the Upgrade Notices section above, work difficulty changes were implemented in V21, but will not be activated until epoch v2 blocks are distributed at a future date. Please review the Upcoming upgrades section of the Network Upgrades page for details.

Updates on the progress toward the epoch upgrade will be posted in our many social channels as well as sent through our technical updates mailing list which can be joined here: Join Mailing List.

Node Telemetry

To allow better communication between nodes about various performance and other details, telemetry was added between peers. Various version details, account and block counts, active difficulty and more can be discovered from individual peers or summarized across them.

Details of what is shared and options for receiving them can be found in the node telemetry WebSocket section and node_telemetry RPC. For protocol level details, see Node Telemetry section under Protocol Design > Networking.

Telemetry can be forged

Although the telemetry messages are signed by nodes, the data provided by other peers can be forged by malicious nodes so they cannot be guaranteed as accurate. All details in these messages should be used as rough indicators of peer and broad network situations, but not exclusively relied on for any key integration or network activities.

Continued conversation around telemetry is happening through the related forum discussion.

IPC 2.0

As a key update towards the upcoming RPC 2.0 redesign, this background upgrade will provide more performant communication to the node, allow easier integration across various languages by supporting Flatbuffers and provide the foundation for more granular authorization of specific calls.

Better election alignment and performance

Behind the scenes many improvements were made to better streamline alignment of elections across the network and allow for better performance. Resource usage by nodes, particularly network bandwidth, will be reduced even further than previous levels. No action is needed to take advantage of this increase other than upgrading your node to V21 as soon as you can!

Node Configuration and Management Updates

Support in Nano Forum

For node operators looking to upgrade their node or tune their configurations, the Node and Representative Management category of the forum is a great resource to use.

The following options are notable node configuration updates. Additional configuration changes have been included in this release and can be found when generating the config files.

  • The ability to enable a static log file name is available via the node.logging.stable_log_filename option. If update to true, a static log file of log/node.log will be written to and rotated to timestamped files once full. This option requires the node being built with Boost 1.70+ (default for Docker images and published binaries).
  • Nodes will now clear their peers lists and online weight if they are started after more than 1 week of being offline. This aims to improve re-peering in these situations, as well as provide more accurate online weight values as the node begins participating on the network again (related PR).
  • When watch_work is set to false in the process RPC, it is no longer required to have enable_control = true in the config-rpc.toml file.

Log when voting, warn multiple accounts

When the node is started there are new messages pushed to the logs which indicate when voting is enabled and how many representatives are configured to vote. A warning will be included in both the logs and stdout if multiple representatives are configured to be voting.

RPC Updates

  • BREAKING CHANGE work_validate has multiple changes to the response, one which will break most existing integrations:
    • If difficulty parameter is not explicitly passed in the request, the existing valid field will not be returned (breaking)
    • valid_all is a new return field, true if the work is valid at the current default difficulty (will go up after epoch upgrade)
    • valid_receive is a new return field, true if the work is valid at the lower epoch_2 receive difficulty (only useful after the epoch upgrade is finished)
    • To best understand how these and other epoch related changes will impact your integration, it is highly recommended that the Upcoming upgrades > Increased work difficulty section of the Network Upgrades is carefully reviewed
  • active_difficulty RPC and WebSocket will automatically begin returning the higher difficulty threshold for send/change blocks in the network_minimum field once the epoch upgrade begins, otherwise the response formats will remain the same
  • BREAKING CHANGE bootstrap_status responses now have connections field as an array of connection-related fields and adds an attempts field with an area of individual bootstrap attempt details, each including information such as a unique id, type of bootstrap (legacy, lazy) and various other granular information.
  • block_create response now contains the difficulty value of the work included in the block for easy reference by integrations. When generating work for the created block, the node ledger data is used to estimate the required difficulty threshold.
  • work_generate request now accepts optional block (and corresponding boolean json_block), which is used to estimate the required difficulty threshold by using ledger data. Two common use-cases are generating work for blocks created elsewhere, and re-generating work for a previously published block.
  • account_info responses now contain confirmation_height_frontier which is the hash of the last confirmed block.

Including subtype in process RPC calls highly recommended

In order to avoid potential incorrect sends including the optional subtype parameter on all process RPC calls is highly recommended. In the next version of the RPC this parameter will be required.

CLI Updates

WebSockets

  • Updates to WebSocket subscriptions are now allowed on the confirmation topic. With options of accounts_add and accounts_del an existing subscription can now be more easily managed to avoid resubscribing with a large list of accounts or managing multiple subscriptions.
  • NEW bootstrap topic provides notifications about the starting and exiting of bootstrap attempts.
  • NEW new_unconfirmed_block topic provides notifications about blocks which were just processed and are being seen by the node for the first time. This is useful for integrations that want to watch for blocks they didn't create themselves, but for which they want to update with new work (external work watcher).
  • WebSocket server is now enabled by default in V21+ Docker images to make it more consistent with RPC server setup and documented port mappings

Developer/Debug Options

  • confirmation_active RPC response includes new unconfirmed and confirmed fields to help with more granular election tracking and monitoring
  • When the node is started there are new messages pushed to the logs which indicate when voting is enabled and how many representatives are configured to vote. A warning will be included in both the logs and stdout if multiple representatives are configured to be voting.
  • New --debug_generate_crash_report CLI command consumes the dump files to create a helpful crash report. See What to do if the node crashes (Linux) for more details on using this command.
  • New logging.log_rpc configuration can be optionally set to false to prevent explicit logging of RPC requests made to the node

Deprecations

The following functionality is now deprecated and will be removed in a future release:

  • UDP is disabled by default in this version and will be removed in a future release. Launch flag --disable_udp is deprecated and temporary use of UDP can be done with the new --enable_udp flag.