Skip to main content

Network Upgrade (Spork) Process

Overview​

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

Network upgrade are also referred to as Spork.

Network Upgrades are approximately once every year. Upcoming network upgrades are announced in advance on the #flow-validators-announcements Discord channel and on the status page. The #flow-validators-announcements channel is also used to coordinate during the upgrade process with all the node operators.

📢 Forte Upgrade on Wednesday, Oct 22nd, 2025 at 15:00 UTC

This guide is for existing operators participating in a network upgrade. 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 Discord, 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 server), 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:


    _10
    ./boot-tools/transit pull -b ./bootstrap -t ${PULL_TOKEN} -r ${YOUR_NODE_TYPE} --concurrency 10 --timeout 50m

  • 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-53, mainnet-27.
    • 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. See here to enable execution date indexing.

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

    • For access nodes however, if you have execution data index enabled use the role execution to ensure the execution state files (root.checkpoint*) are also downloaded. If you do not have execution data indexing enabled, specify the role as access.
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. Update command line arguments

For the Forte upgrade, remove the pebble-dir argument as it has been deprecated. This applies to all node types. The node will continue to use the datadir argument which points to the location of the node database.

  1. Start your Flow node via docker or systemd

The FlowFoundation team will share the new docker tag at the completion of the upgrade. Please use that docker tag to bring up the node.

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!

Rate this page