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).
This upgrade is sometimes referenced as the epoch v2 upgrade and the relate events to complete are as follows:
|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_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:
difficultyparameter is not explicitly passed in the request, the existing
validfield will not be returned (breaking)
valid_allis a new return field,
trueif the work is valid at the current default difficulty (will go up after epoch upgrade)
valid_receiveis a new return field,
trueif 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
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
- 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.
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.
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.
New PoW algorithm¶
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.
|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.
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.
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.
|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.|
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.
|2018-08-22||Node release||Nano node V15.2 release with support for vote-by-hash but not yet activated.|
|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.|
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.
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.
|Multiple node upgrades||No||
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.
|Node upgrade + specific date||No||
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.
|Node upgrade + distribution of one block per transition phase||Yes||
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.
|Node upgrade + distribution of epoch blocks||Yes||
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|
||Undistributed as of June 2020, see Increased work difficulty details above|