Skip to content

Network Upgrades

For details on why and how network upgrades happen, along with explanations of the various types, please see the Upgrades overview and Upgrade methods sections further down.

Join our Technical Update Mailing List

Follow this link to sign up for email updates on the latest protocol/node releases and other technical details. This will include network upgrades such as the upcoming epoch distribution: http://eepurl.com/gZucL1
Join Technical Updates Mailing List


Upcoming upgrades

Increased work difficulty

To help ensure Quality of Service on the network by increasing the difficulty required for send and change blocks to be considered valid by the network (8x compared to current). To help offset the difficulty increase and add incentive to receive blocks so ledger pruning can be done more broadly in the future, the difficulty for receive blocks will simultaneously be reduced (⅛ compared to current).

Transition details

This upgrade is sometimes referenced as the epoch v2 upgrade and the relate events to complete are as follows:

Date Type Description
2020-06-16 Node release Nano node V21.0 released which includes changes necessary for supporting new difficulty validation and generation
TBD v2 epoch blocks distribution start Distribution of v2 epoch blocks to all accounts to mark in the ledger the point at which the new work difficulty levels will be required. The start of this distribution process will occur once key services and over 90% of voting weight on the network has upraded.
TBD v2 epoch blocks distribution end Distribution of epoch blocks ends after all accounts are upgraded.

Nodes de-peered with epoch blocks

Due to the nature of the work difficulty changes, any nodes not updated to V21.0+ at the time of epoch block distribution will be de-peered from the network.

In order to best prepare for the transition to new thresholds, the following items should be considered:

Work generation guide
The new Work Generation guide was written to help users and integrations leverage their work generation at all times.

Work validation
The work_validate RPC has multiple changes to the response, one which will break most existing integrations when upgrading to V21, two others that will become useful after upgrade:

  • 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)
  • If possible, it is best to avoid using this RPC until the epoch upgrade is completed

External work generation
nano-work-server has been updated to use the higher threshold (fffffff800000000) by default when not given an explicit difficulty. The work_validate response has the same breaking changes as above.

  • Prefer directly using the server as a work peer as outlined in the guide. The node always requests the appropriate difficulty threshold when using RPC block_create, or work_generate with the optional block.
  • In cases where requesting directly from a node is not possible, avoid using the lower threshold for receive blocks (fffffe0000000000) until the epoch upgrade is fully complete.

Work generation performance
Testing out work generation capabilities on a machine is recommended. Details for how to accomplish this can be found in the Benchmark section of the Work Generation guide.

Active difficulty changes
The active difficulty RPC command and WebSocket topic allow programatically retrieving the current difficulty from the network_minimum field in the response. When this field changes from ffffffc000000000 (pre-epoch v2 difficulty) to fffffff800000000 (8x higher epoch v2 difficulty), it indicates the epoch upgrade has begun.

Post-distribution changes

Accounts that have already been upgraded can optionally use fffffe0000000000 as the lower threshold for receive blocks going forward.
The current epoch version of an opened account can be obtained using the account_info RPC, field account_version. Once that field has the value "2", the lower threshold may be used.

Other integration considerations
Although it is already recommended as best practice, any integrations not already calling for the frontier block when constructing a transaction should do so. If hashes are being internally tracked and frontier is not requested, the integration could unintentionally cause a fork on the account with distribution of epoch blocks.

See Step 1: Get Account Info for the account_info RPC recommendation when creating transactions.

Transition Explanation

When changing the work difficulty requirements it is necessary to mark a point in each account where the difficulty requirements change so bootstrapping and other behaviors can accurately validate historical blocks. For this reason the epoch blocks are being distributed to act as the marker in the ledger.

Once epoch block distribution is started the ability to validate the new work difficulty levels is required. Since node versions before V21.0 do not have the ability to do this, they will be immediately de-peered from the network and cannot participate with the current network until upgraded.

To mitigate the impacts of this approach the Nano Foundation will be communicating regularly about progress and monitoring closely the activity on the network. Once acceptable conditions exist to finalize the transition, the distribution will begin. The current plan is to start once over 90% of voting weight has been upgraded, along with all the key services on the network.


Future upgrades

New PoW algorithm

Purpose

To help ensure Quality of Service on the network by providing the ability to generate and validate PoW using a new algorithm. This algorithm will be more memory-hard causing the resources required for generating transactions to shift accordingly.

Transition details

Date Type Description
TBD Node release Nano node V20.0 released to include a new PoW server and epoch block support. These are only foundational updates and will not be configured for activation in this release.
TBD Node release Nano node VXX.X released to include new PoW algorithm in PoW server, addition of a new state block version (v2) with support for the new work values and final changes allowing transition via epoch blocks.
TBD Epoch blocks start Distribution of epoch blocks to each account which upgrades them to use the new state block version (v2). Once an account is upgraded nodes will only validate work made using the new PoW algorithm for that account.
TBD Epoch blocks end Distribution of epoch blocks ends after all accounts are upgraded.

Nodes de-peered with epoch blocks

Due to the nature of the state block changes to be included in the 2nd node release of this transition, any nodes not updated to the latest version at the time of epoch block distribution will be de-peered as part of this process.

Transition Explanation

In the above transition plan a phased node upgrade was used to provide support for some foundational elements of the new PoW algorithm while further details of the design are worked out. The epoch block distribution in this transition represents a clean switch from one PoW algorithm to the other - no block in the ledger is allowed to have work generated by either PoW, instead older block versions must use the existing PoW and new block versions must use the newer PoW.

This clean switch comes with benefits including reduction in code complexity related to handling two types of PoW generation and validation for the same block versions, and the setting of a clear point in the ledger for each account where work values changed - potentially useful for future snapshoting.

To mitigate the impacts of this approach the Nano Foundation will be communicating regularly about progress and monitoring closely the activity on the network to ensure proper conditions exist to finalize the transition.


Past upgrades

State blocks

Purpose

The upgrade to state blocks involved multiple node releases and three different actions on the network including distribution of two canary blocks and the first epoch blocks.

Transition Details

Date Type Description
2018-03-23 Node release Nano node V11.0 released with support for state blocks built-in but not yet activated.
2018-04-11 Canary block Parse canary block distributed which enabled parsing of state blocks by nodes so manual generation of that block type would be accepted on the network going forward. This action was performed after a majority of the network upgraded to the required V11.0 to allow confirmations to occur on this new block type.
2018-05-20 Canary block Generation canary block distributed which forced the generation of state blocks by nodes going forward. At this point both state and legacy type (open, send, receive, change) blocks remain valid on the network.
2018-08-20 Node release Nano node V15.0 released with support for epoch blocks built-in and away distribution.
2018-10-25 Epoch v1 block distribution start Distribution of epoch v1 blocks begins.
2019-05-24 Epoch v1 block distribution end Distribution of epoch v1 blocks is finished. All accounts, opened and unopened, are now capped and can no longer attempt inserting legacy style blocks.

Vote-by-Hash

Purpose

The upgrade to include the vote-by-hash feature was based on a hardcoded timestamp in the node. After this time nodes began voting using this new feature.

Transition Details

Date Type Description
2018-08-22 Node release Nano node V15.2 release with support for vote-by-hash but not yet activated.
2018-09-01
00:00:00 UTC
Hardcoded date Nodes upgraded to V15.2 began voting using the vote-by-hash method. Nodes not yet upgraded would fail to properly interpret votes so were no longer compatible with the network.

Upgrades overview

Nano is a protocol, an agreed upon standard that allows computers to communicate with each other and agree on data. Because of these communication standards, having mechanisms that force all nodes to upgrade certain behaviors at the same time is critical to the consensus and consistency in the network.

In most blockchain networks these upgrades can be scheduled to take effect once a particular block height is hit because all nodes operate off a single, synchronous chain. Due to the Nano network being asynchronous this method doesn’t work, so instead we need methods for upgrading accounts asynchronously.

There are a couple different options for handling these upgrades and the process is currently managed primarily by the Nano Foundation. The upgrades are tested on the beta network to ensure all components are behaving as expecting before being considered for updating on the main network. If the behavior being changed involves consensus, any manual upgrade actions are triggered once a large majority of nodes and major services have upgraded.

Of course many features, including protocol changes, can be activated immediately with a new node release, so these network upgrade scenarios are only reserved for certain cases. Options for providing better agreement on capabilities between nodes has been discussed in this GitHub issue. There is also a discussion around how to potentially automate network upgrade processes in this forum topic: https://forum.nano.org/t/automated-network-upgrades/113.


Upgrade methods

There are various methods used to upgrade and a brief overview of each, along with benefits and drawbacks, are included below. Upgrades for behaviors contained and activated with a single node release are not included as they are the foundation on top of which these other methods are made capable.

Phased node upgrades

A feature is introduced in a node release but not activated for use across the network until a subsequent node release. See State block upgrade details for an example.

Trigger Uses blocks Benefits Drawbacks
Multiple node upgrades No
  • No manual intervention or automated process needed
  • Uses already established upgrade process node operators are used to
  • Longer time period to get feature activated
  • Cannot be used to perform upgrades needed simultaneously across the network

Hardcoded date

A date is hardcoded into the node release to activate a feature or behavior at a specific time in the future. See Vote-by-Hash upgrade details for an example.

Trigger Uses blocks Benefits Drawbacks
Node upgrade + specific date No
  • Simple to implement
  • No manual activity required
  • Inability to adjust timing without rushing new release out

Canary block(s)

The hash of a block is hardcoded in the node such that once that hash is seen by the node, it will activate a feature or behavior. Multiple block hashes can be used to perform different phases of a transition. See State blocks upgrade details for an example.

Trigger Uses blocks Benefits Drawbacks
Node upgrade + distribution of one block per transition phase Yes
  • Can be used for multi-phase upgrades, including in combination with other options
  • Timing flexible
  • Requires manual intervention
  • Adds additional code complexity
  • Can cause unchecked table to fill during transition

Epoch blocks

A special block type that can only be generated using a pre-determined private key. These will be accepted by nodes and be attached as the frontier blocks on each account-chain on the network. This feature was built to allow very limited controls using these blocks: they cannot change account balances or representatives, only upgrade the account versions to allow new block structures. See State block upgrade details for an example.

Trigger Uses blocks Benefits Drawbacks
Node upgrade + distribution of epoch blocks Yes
  • Provides clean upgrade markers directly within the ledger on every account-chain
  • Timing flexible
  • Ability to asynchronously upgrade block versions even for inactive/unopened account chains
  • Requires manual intervention
  • Introduces ability for non-account owner to write to account chain in a highly restricted way
  • Adds additional code complexity
  • Requires large volume of blocks

The following are the epoch versions and the related accounts which are used to distribute them to the network. For certain protocol implementations these epoch signers need to be included to efficiently determine whether incoming blocks are epoch blocks.

Version Epoch signer account Notes
1 xrb_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3 Genesis account
2 nano_3qb6o6i1tkzr6jwr5s7eehfxwg9x6eemitdinbpi7u8bjjwsgqfj4wzser3x Undistributed as of June 2020, see Increased work difficulty details above