3⃣
Node: Staying Up-To-Date
This is a step-by-step guide on how to stay up to date with hardforks of the core repository, as well as instructions for core team members on how to execute updates that could cause a hard fork on the network.
This doc should help node operators and the core team release new code in an organized way, particularly so that the developer community has sufficient time and resources to upgrade their nodes.
- 1.Subscribe to release notifications on GitHub
- Which repos?
- How to subscribe
- 1.Click “Watch” at the top
- 2.Select “Custom”
- 3.Check “Releases”
- 2.Whenever a major version update occurs, e.g. moving from 2.9.9 to 3.0.0, be sure to read the release notes and reboot your node within the next week to avoid issues
- Note that occasionally a resync will be required, which could cause ~20 minutes of downtime unless done in parallel with a second running node. Be sure to read the release instructions to avoid any interruptions.
- 3.
- 4.
- 1.Gate all the forking changes by a ForkHeight which initially should be set to
math.MaxUint32for both mainnet and testnet, and 0 for regtest. - 2.Verify that the code passes all basic tests:
- 1.core unit tests
- 2.core integration tests
- 3.node syncs with hypersync + txindex on testnet and mainnet
- 4.node syncs with blocksync + txindex on testnet and mainnet
- 5.rosetta can sync mainnet
- 6.repeat steps c. and d. for postgres
- 7.test that all of the changes work in the reference frontend
- 8.make sure to run more comprehensive tests when deploying a complex change
- 3.Assuming you’re ready with all the content for the steps in the next sections, you should announce everything at 12:00 PM PT and set the testnet fork height to 1 day from the announcement, and the mainnet fork height to a minimum of 7 days from the announcement.
- We will strive to give as much time for node operators to upgrade as possible, erring on the side of two weeks. However, in the interest of moving quickly, it will sometimes be necessary to make updates with less warning, though generally with no less than one week of warning.
- 1.Come up with a description of what happens in the fork. Make it a couple sentences, or a couple paragraphs depending on the scope of the change. See what fits based on next steps.
- 2.Draft a Fork Preparation Checklist document which is a step-by-step checklist/walkthrough of what node operators need to do in order to upgrade their nodes (inspired by prism’s merge preparation checklist)
- 3.(Optionally) Write a before and after table which describes what happens in the fork. The left column should describe different aspects of the “before” tech and the right shows how they updated / changed “after” the fork. (also prism’s merge preparation docs)
- 4.Put all of the above in a new draft release on github, similar to how consensys does it with teku, or how ethereum does it
- 5.Assuming the release number is XX.YY.ZZ (major.minor.patch):
- You should increment the major XX
- -> if the node operators will be required to upgrade their software within a fixed amount of time, otherwise risking ending up on a stale fork.
- You should increment the minor YY
- -> if the node operators can do nothing and still properly participate in the network. The code augments the node in a backwards-compatible fashion.
- You should increment the patch ZZ
- -> If the update fixes a bug in a backwards-compatible fashion.
- 6.Cut the new release
- 1.Create twitter announcement for the fork
- 2.Create diamond announcement for the fork
- 3.Create discord announcement for the fork
Last modified 3mo ago