# Previous Release Notes

## V21.1¶

Node Protocol Database Release Date Release Notes GitHub Links
21.1 18 18 2020-07-14 V21.1 Release - Milestone - Changelog
Known Issue V19+: macOS 'Too many open files'
• Issue: The following error can be seen when attempting to run a full node on macOS using the built-in Qt wallet or other GUI-based wallets: "Exception while running wallet: open: Too many open files". This is due to macOS having a very low default file descriptor limit and V19.0 uses more of them after the move to TCP.

• Solution: For now a workaround is needed to increase the limit. The method depends on the specific macOS version, but some people had success with the recipe in https://superuser.com/a/1171028.

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.

V21.1 is a service release which doesn't require any special upgrade considerations when upgrading from V21.0.

## 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+: macOS 'Too many open files'
• Issue: The following error can be seen when attempting to run a full node on macOS using the built-in Qt wallet or other GUI-based wallets: "Exception while running wallet: open: Too many open files". This is due to macOS having a very low default file descriptor limit and V19.0 uses more of them after the move to TCP.

• Solution: For now a workaround is needed to increase the limit. The method depends on the specific macOS version, but some people had success with the recipe in https://superuser.com/a/1171028.

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.

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.

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.

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: .

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.

• 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.

### 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:

## V20.0¶

Node Protocol Database Release Date Release Notes GitHub Links
20.0 17 15 2019-11-12 V20.0 Release - Milestone - Changelog
Known Issue V19+: macOS 'Too many open files'
• Issue: The following error can be seen when attempting to run a full node on macOS using the built-in Qt wallet or other GUI-based wallets: "Exception while running wallet: open: Too many open files". This is due to macOS having a very low default file descriptor limit and V19.0 uses more of them after the move to TCP.

• Solution: For now a workaround is needed to increase the limit. The method depends on the specific macOS version, but some people had success with the recipe in https://superuser.com/a/1171028.

Known Issue V20: Peers stake reporting inaccurate (Windows only)
• Issue: For Windows builds only, when calling confirmation_quorum RPC the peers_stake_total amount returned may be inaccurate, returning a range from the correct full peer stake amount down to 0.

• Solution: A solution to the issue has been found and as this is a reporting issue only, the fix will be included in the next released version. For those manually building the node, patching the fix pull request onto the V20.0 tag can resolve the issue now. Or alternatively, building on the V20.0 tag with RelWithDebInfo option, see Build Instructions for Windows.

Only node V18.0 and higher supported

With V20.0 only nodes V18.0 and higher will be peered with on the network (see Active Releases above). This means any nodes running versions earlier than 18.0 will begin to lose peers and fall out of sync over time once upgrades to V20.0 begin.

If you are running a node version earlier than V18.0, please update as soon as possible to avoid disruption.

Please review the following details carefully as the automatic database upgrade process will cause downtime for the node.

This version brings some new optimizations to the ledger which require database upgrades to be performed. Due to the nature of upgrades, the following impacts will occur:

• Upgrade times depend on specs of the node host but are expected to be between 5 and 15 minutes for most cases.
• Upgrade activities are synchronous which means the node will not be participating on the network and RPC requests won’t be available during the upgrade process - services requiring uptime should plan to swap out their ledger for one upgraded by a separate node or download from a trusted source.
• Ledger size will grow by up to 50% during this process - please ensure you have free disk space of 3x the current ledger before starting the upgrade (currently ~16GB on the main network).
• A database vacuum will be automatically performed after the upgrade to reclaim disk space, which can be verified complete in the logs.
• Doing proper ledger backups is recommended before starting this process. Ensure you have enough disk space to allow for any ledger backups plus the additional disk space required for the database upgrade mentioned above. A new config option in V20, node.backup_before_upgrade, will allow for automated ledger backups between future versions.

New .toml config files
A new setup in V20.0 uses internal default config values, so config files are only needed for non-default settings. During upgrade new .toml format files will be created for the config.json and rpc_config.json files if they contain non-default values. Before migration config_backup_toml_migration.json and rpc_config_backup_toml_migration.json files will be created for backup.

The following commands can be used to generated commented out, complete config files for review:

Only set non-default values in .toml files

It is not recommended to uncomment all values in the .toml file output from commands below. Instead, only uncomment or insert non-default values to ensure any default value changes in future release are only overridden when needed.

Name Description Generated with
config-node.toml Node configuration nano_node --generate_config node
config-rpc.toml RPC configuration nano_node --generate_config rpc
config-nano-pow-server.toml Proof of work server configuration nano_pow_server --generate_config
config-qtwallet.toml Qt developer wallet configuration This file is maintained by the Qt wallet

More details on the new configuration setup can be found in the node Configuration documentation.

Networking changes
Improvements to default network setup in this version requires less setup from node operators, specifically around port forwarding. Although new setups will immediately benefit, any existing systems that have already setup port forwarding may be impacted by these changes. For those systems, we recommend validating your network setup allows proper peering with a test V20.0 node prior to upgrading. If you run into issues, review the Troubleshooting UPnP documentation for assistance. Additional help can be sought in the Node and Representative Management forum category.

Proof-of-Work management
A couple changes to PoW management that services should be aware of:

• With OpenCL enabled, nodes will still use the local CPU for work generation by default. Setting node.work_threads to 0 will turn this off if required.
• Regenerating PoW for delayed transactions during high network load will now happen by default through the process RPC. If you wish to turn this off, setting watch_work to false is required.

Improvements to the External Management and Block Confirmation and Tracking documentation should help clarify the recommended approaches to building integrations.

Migration to .toml config files
Better legibility, support for comments, and no more having the node write to your config files are some of the benefits of this upgrade. Any non-default values captured in your existing .json files will be migrated and you can export a full list of configuration options for use with simple commands. See additional callouts in Upgrade Notices above and in the node Configuration documentation.

Proof-of-Work regeneration outside development wallet
Any requests to the process RPC will have the new watch_work option turned on by default, allowing the node to regenerate Proof-of-Work for blocks even if they are outside of the node’s development wallet. This makes Dynamic PoW and prioritization function more consistently across the network. If you have an external integration utilizing this RPC call, you will automatically start taking advantage of rework during confirmation delays on the network.

RocksDB experimental support
With better disk IO usage, RocksDB is being introduced in this version with experimental support. It is not recommended for use in production, but those interested in testing out a more performant database for the ledger should checkout how to install RocksDB and try it out on development and test systems. We also have a related discussion in our forum for those interested.

Active elections and other optimizations
Thanks to our excellent community testers putting effort into collecting and analyzing block, voting and confirmation data from the beta network, we’ve found various optimizations with the active elections process, confirmation request attempts and bootstrapping behaviors. Various changes have been implemented to help reduce resource usage on nodes in various areas and increase the available throughput on the network. This feature also enhances the effectiveness of prioritization and rework of PoW. No action is needed to take advantage of these great updates.

Infrastructure for PoW transition
Back in September we announced a new PoW algorithm design we had been working on which aimed to be memory hard. After open sourcing an implementation of the algorithm, an efficient low-memory solution was found and we subsequently removed the algorithm implementation from V20.

As part of the original implementation work we were able to setup infrastructure for moving PoW out of the node process in the future, and also added support for version 2 of epoch blocks, which will allow the network upgrade later when a new PoW algorithm is ready. These updates will be included in Lydia but not be utilized until a future version. To follow along with node releases going forward, check out the Upcoming Features page.

Support in Nano Forum

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

Generate .toml config to see options

As noted in the Upgrade Notices above, this version will migrate your existing .json files over to .toml files. Only non-default values for these fields will be added to the new .toml file. If you wish to adjust other options, use the config generation commands to see all available options.

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.

• backup_before_upgrade (default false) enables automatic backup of the ledger and wallet databases when updating to a new node version
• work_watcher_period (default 5 seconds) controls how frequently the node should check the confirmation status of block in the work watcher, and re-generate higher difficulty work if unconfirmed
• max_work_generate_multiplier (default 64.0) previously max_work_generate_difficulty, now a multiplier for easier management, specifies the absolute maximum difficulty multiplier to be used for work generation

### Developer/Debug Options¶

• New RPC epoch_upgrade allowing easier epoch distribution (Note - this epoch requires a special private key to be used, see the Network Upgrades page for information)
• RPC bootstrap has a new optional "bypass_frontier_confirmation"
• RPC bootstrap_status now displays more data about the current bootstrap attempt
• New CLI debug_stacktrace displays an example stacktrace, simulating an unexpected program crash
• New CLI debug_account_versions displays the total number of accounts separated by version and opened/unopened
• CLI debug_validate_blocks updated to cover more cases
• CLI debug_profile_verify renamed to debug_profile_validate and now provides simplified work validation profiling
• New CMake build options:
• NANO_ROCKSDB enables use of the RocksDB database backend, experimental
• NANO_WARN_TO_ERR turns compiler warnings into errors on Linux/Mac
• NANO_TIMED_LOCKS provides information on mutexes held for a long time
• NANO_STACKTRACE_BACKTRACE uses libbacktrace to provide stacktraces
• CI_BUILD if set, uses the TRAVIS_TAG environment variable to modify the locally reported node version, to help with support tickets

### Deprecations¶

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

• Addresses containing a dash (ex. nano- or xrb-) are being deprecated and will not longer be compatible with the node in a future release. Addresses using underscores will only be supported.

## V19.0¶

Node Protocol Database Release Date Release Notes GitHub Links
19.0 17 14 2019-07-11 V19.0 Release - Milestone - Changelog
Known Issue V19+: macOS 'Too many open files'
• Issue: The following error can be seen when attempting to run a full node on macOS using the built-in Qt wallet or other GUI-based wallets: "Exception while running wallet: open: Too many open files". This is due to macOS having a very low default file descriptor limit and V19.0 uses more of them after the move to TCP.

• Solution: For now a workaround is needed to increase the limit. The method depends on the specific macOS version, but some people had success with the recipe in https://superuser.com/a/1171028.

Version Limits
Upgrades from versions V17.1 and to V19 will involve a sequential database upgrade and impact participation of the node on the network. RPC calls will be unavailable for a long period of time amongst other impacts.

Upgrading from V17.1 and earlier to V19.0 not recommended

It is highly recommended that nodes are upgraded to V18.0 first or a V18.0 ledger is acquired and used when upgrading to V19.0.

Confirmation tracking considerations
The addition of confirmation height to the database requires the node to validate that blocks are confirmed before the cementing can occur. This process can take up to 24 hours or longer to complete and will cause an increase in some resource usage, particularly CPU and network bandwidth increases, but won’t impact participation on the network. For integrations watching confirmations, the existing HTTP callback, block_confirm RPC and confirmation_history RPC methods will continue to function as before.

Tracking confirmed block hashes required

It is required that tracking of confirmed block hashes outside the node is done to avoid potential duplicate notifications from causing issues. This was a requirement in previous versions and remains the same with V19.

For those looking to utilize the new WebSocket confirmation subscription or new confirmed field in block_info RPC responses, special considerations should be taken if implementing before confirmation height updates are complete:

• If the websocket confirmation subscription is hooked up to receive all confirmations (default) then notifications for confirmations will come through during the cementing process on a new or upgrading ledger as the confirmation process will occur (it also fires for dependent confirmations)
• Calls to block_info for blocks in the ledger before the confirmation height upgrade process began may indicate confirmed as false despite their having been confirmed on the network before. This is expected behavior.
• To validate that confirmation height upgrade is complete, note the count value from the block_count RPC when the upgrade is started and once the cemented amount returned by this call (include the include_cemented option) is higher than that previous count, cementing is in sync.

In this and future versions, all addresses emitted from the node will use the nano_ prefix. It will continue to support input for xrb_ prefixed addresses, but all services must verify they are properly set up to handle the node outputting nano_ prefixed addresses.

Live network over TCP
Live network traffic over TCP is now available and operates on the same port (7075 for main network, 54000 for beta network) as the bootstrapping network that was already available over TCP. Because of this, existing network setups that are open inbound and outbound on port 7075 for TCP should function as expected with V19.0. For those running production services, it is still recommended to verify network ports setup and consider setting up a new node on internal networks to ensure it can connect and participate on the main network before production nodes are upgraded.

• To check for proper connection via TCP, call the peers RPC with peer_details option and look for peers with type = tcp. This command can be used to search for these instances:
curl -sd '{"action": "peers", "peer_details":"true"}' [::1]:7076 | grep "\"type\": \"tcp\"" | wc -l


Confirmation Height
This provides cementing of blocks by marking on an account the highest block height that has been confirmed for the account. A more detailed look at this feature can be found in the relatd Medium article: https://medium.com/nanocurrency/looking-up-to-confirmation-height-69f0cd2a85bc

TCP Network
Blocks being published and voted on live are now supported via TCP, with UDP remaining as a fallback. See the TCP callouts in Upgrade Notices above for information about verifying your network setup is ready for the upgrade.

Dynamic Proof-of-Work and Prioritization
With the ability to track work difficulty seen on the network and have the node wallet produce more difficult work for local blocks, this feature allows users to get their transactions prioritized for processing. More details about this feature can be found in the Medium article: https://medium.com/nanocurrency/dynamic-proof-of-work-prioritization-4618b78c5be9

RPC Process Options
By default the RPC server will run in the node process, but can be configured to run as a child process or completely out of process (currently limited to running on the same computer), depending on your needs. See Running Nano as a service for more details.

No Breaking Changes

There were no breaking changes made in V19 for any RPC or CLI commands. It is recommended any integrations run tests against V19 before upgrading production nodes, and also explore the various changes below to improve their setups.

• New active_elections_size will limit the number of active elections allowed before dropping occurs. Default is 50,000 but higher settings are recommended for nodes provisioned with 8GB RAM or more
• New bandwidth_limit will limit the outbound voting traffic to 5MB/s by default
• New confirmation_history_size provides an adjustable limit on the batching of confirmations return in the confirmation_history RPC. Default 2048 which will support up to ~56 confirmations/sec before confirmations may be missed. The new websocket setup with confirmation subscription is recommended over use of the confirmation_history RPC.

New vote_generator_delay allows for tuning performance of bundling votes by hash before sending.

Rpc_config.json
This new file was split out from the config.json file as the RPC server can now be run in its own process. Entries previously existing in config.json were migrated over and new values added. One setting to note: the max_request_size parameter is defaulted to 32MB - if your service is submitting data amounts larger than this you will need to adjust accordingly.

Automated config backups
Backups of config files will be made prior to upgrades. During upgrades from V18 to V19 you will see a backup created even for the new rpc_config.json - this is expected behavior given the upgrade process.

### Deprecations¶

The following RPC calls are being deprecated and will be removed in a future release:

### Other Notices¶

New nanorep QR code standard
A new nanorep QR code standard for easier management of representative changes was added for wallets and other services to consider supporting.

New recommended block explorer
The Nano Foundation supports a new recommended block explorer - NanoCrawler. We encourage services and exchanges linking out to block explorers to consider using NanoCrawler going forward as it provides solid design and performance for referencing blocks, accounts and more.