Skip to main content

Network Upgrade (Spork) Process

Overview​

A spork is a coordinated network upgrade process where node operators upgrade their node software and re-initialize with a consolidated representation of the previous spork's state. This enables rapid development on the Flow Protocol and minimizes the impact of breaking changes.

The Flow network sporks approximately once every year. Upcoming sporks are announced in advance on the #flow-validators-announcements Discord channel and in Upcoming Sporks. The #flow-validators-announcements channel is also used to coordinate during the spork process.

This guide is for existing operators participating in a spork. See Node Bootstrap for a guide to joining the network for the first time.

Step 1 - Cleaning Up Previous Spork State​

Once the spork start has been announced on, stop your node and clear your database. The node should stay stopped for the duration of the spork.

warning

You can skip this step if it is your first time running a node on Flow.

  1. Stop your Flow node
  2. Clear the contents of your data directory that you have previously created. The default location is /var/flow/data. The data directory contains the Flow chain state.

Step 2 - Start Your Node​

Once you receive an announcement that the spork process is complete (via Discord), you will need to fetch the genesis info, update your runtime configuration and then boot your Flow node up!

warning

If you had set the dynamic bootstrap arguments command line arguments (--dynamic-startup-access-address, --dynamic-startup-access-publickey, --dynamic-startup-epoch-phase) please remove them.

  1. Run the transit script to fetch the new genesis info: ./boot-tools/transit pull -b ./bootstrap -t ${PULL_TOKEN} -r ${YOUR_NODE_TYPE} --concurrency 10 --timeout 15m

  • PULL_TOKEN will be provided by the Flow team.

    • For collection, consensus, verification node type it will generally be testnet-x or mainnet-x where x is the latest number of respective network upgrade. e.g. testnet-52, mainnet-26.
    • For execution node type it will generally be testnet-x-execution or mainnet-x-execution.
    • For access node:
      • It will generally be testnet-x or mainnet-x if execution data indexing is not enabled.
      • It will generally be testnet-x-execution or mainnet-x-execution if execution data indexing is enabled.

  • YOUR_NODE_TYPE should be one of collection, consensus, execution, verification, access based on the node(s) that you are running.

Example

_19
$ ./boot-tools/transit pull -b ./bootstrap -t mainnet-16 -r consensus
_19
Transit script Commit: a9f6522855e119ad832a97f8b7bce555a163e490
_19
2020/11/25 01:02:53 Running pull
_19
2020/11/25 01:02:53 Downloading bootstrap/public-root-information/node-infos.pub.json
_19
2020/11/25 01:02:54 Downloading bootstrap/public-root-information/root-protocol-snapshot.json
_19
2020/11/25 01:02:54 Downloading bootstrap/random-beacon.priv.json.39fa54984b8eaa463e129919464f61c8cec3a4389478df79c44eb9bfbf30799a.enc
_19
2020/11/25 01:02:54 SHA256 of the root block is: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
_19
_19
$ tree ./bootstrap/
_19
./bootstrap/
_19
├── private-root-information
_19
│ └── private-node-info_39fa54984b8eaa463e129919464f61c8cec3a4389478df79c44eb9bfbf30799a
_19
│ └── node-info.priv.json
_19
├── public-root-information
_19
│ ├── node-id
_19
│ ├── node-info.pub.39fa54984b8eaa463e129919464f61c8cec3a4389478df79c44eb9bfbf30799a.json
_19
│ ├── node-infos.pub.json
_19
│ └── root-protocol-snapshot.json
_19
└── random-beacon.priv.json.39fa54984b8eaa463e129919464f61c8cec3a4389478df79c44eb9bfbf30799a

  1. Pull the latest changes from flow-go repository
  2. Get your node-id, you can find it at /path/to/bootstrap/public-genesis-information/node-id
  3. Update the FLOW_GO_NODE_ID inside runtime-conf.env to the node-id that you got from the previous step
  4. Start your Flow node via docker or systemd

See Node Bootstrap for detailed information on Docker/Systemd configuration.

Common Issues​

Error: cannot create connection​


_10
20T18:34:21Z","message":"could not create connection"}
_10
{"level":"error","node_role":"consensus","node_id":"6d3fac8675a1df96f4bb7a27305ae531b6f4d0d2bc13a233e37bb07ab6b852dc","target":"QmVcSQaCdhmk1CMeMN7HTgGiUY1i2KqgVE2vvEmQXK4gAA","error":"failed to dial : all dials failed
_10
* [/ip4/155.138.151.101/tcp/3569] dial tcp4 155.138.151.101:3569: connect: connection refused","retry_attempt":2,"time":"2020-05-20T18:34:21Z","message":"could not create connection"}

This error is OK. Your fellow node operators have not turned on/joined the network yet. So no need to worry about it!