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.
Technical Update Mailing List
Planned upgrades¶
No planned network upgrades
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 |
|---|---|---|
| 2019-11-21 | 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. |
| 2020-08-29 | Epoch blocks | Following the postponing of the Nano PoW algorithm in favor or research towards other options, the original epoch v2 blocks intended for the PoW algorithm update were modified for increasing work difficulty using the existing algorithm in V21.0 and subsequently distributed in August 2020. Any future PoW algorithm updates will require a different epoch block version. |
| TBD | Node release | Nano node VXX.X released to include new PoW algorithm in PoW server 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 PoW algorithm. 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. |
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¶
Final votes¶
Purpose
To enable the final votes feature which will add a second round of voting to the consensus process as follows: once initial voting weight for an unconfirmed block has reached quorum, nodes will issue final votes by setting the timestamp to the maximum integer possible for that field (18446744073709551615). These final votes will then be required to confirm the block and increase the related accounts confirmation height in the ledger.
Because this is a consensus change, a network upgrade is required to activate. As noted above, this will be done using a canary block once at least 80% of voting weight on the network has been upgraded. After the canary block is distributed by the Nano Foundation, the final votes will be used for confirmation going forward.
Transition details
| Date | Type | Description |
|---|---|---|
| 2021-05-14 | Node release | Nano node V22.0 released with final votes functionality and hardcoded with the block hash for the canary to activate the behavior. |
| 2021-06-03 | Canary block | Canary block hash B0AA9D2D10837ABD6E96DD9ECD9409F5D6F5B982D26D0E395FF3ECFBC2D139A0 distributed to the network which forced nodes upgraded to V22.0+ to only confirm blocks using final votes. Non-final votes reaching quorum are used to trigger when final votes are generated, not used for confirmation. |
Increased work difficulty¶
Purpose
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 |
| 2020-08-18 | 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. |
| 2020-08-29 | 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.
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.
Recommended preparations
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
difficultyparameter is not explicitly passed in the request, the existingvalidfield 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 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.
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 | Purpose |
|---|---|---|
| 1 | xrb_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3 (Genesis account) |
See State blocks |
| 2 | nano_3qb6o6i1tkzr6jwr5s7eehfxwg9x6eemitdinbpi7u8bjjwsgqfj4wzser3x (Used for epoch 2 only) |
See Increased work difficulty |