Flow Playground

Genesis Bootstrapping


To kickstart the Flow network and build the first block, all the nodes that will participate in the first round of consensus need to be known and have exchanged some metadata in advance.

This guide will take you through setting up your nodes, running the initial metadata and key generation, exchanging data back and forth with the Flow team, and then finally starting your nodes to join the network.

Before You Begin

The Flow consensus algorithm depends on there always being a previous block, which means your nodes cannot start until after the Genesis block has been signed. The process of signing that block will be done by the Flow team, and can only be done after every node has completed the first half of the bootstrapping process, which assures that all the identities are included. Since the Flow team needs to wait for metadata from all participants, it will take hours to even days until the Flow network can start.

The bootstrapping process will be in 2 phases, with the Flow team signing the Genesis block between the two.

Download the Bootstrapping Toolkit

Both phases of the bootstrapping are automated with scripts. Pull a copy onto each of your nodes and extract it.

~ $ curl -sL -O\n~ $ tar -xvf boot-tools.tar

Generate Your Node Keys

Start the bootstrapping process by generating your Staking Key and Networking Key. Use your Node Address that you generated in Setting Up a Node in the --address flag, and the node role.

~ $ mkdir ./bootstrap\n~ $ ./boot-tools/bootstrap key --address \"${YOUR_NODE_ADDRESS}:3569\" --role ${YOUR_NODE_ROLE} -o ./bootstrap

This command generates two keys, a Staking Key and a Network Key, and stores them both in a .node-info file. Both these keys are needed during runtime and must be present as a file to start your flow node.

For more details around all the keys that are needed to run nodes and their usage, see the Node Keys overview.

The bootstrapping process will create a file structure similar to the following

Upload Public Keys

To mint the Genesis Block, the Flow team will need the public Staking and Network keys from all your nodes.

If you have previously joined our networks, and you are generating your keys again. Ensure that you take a backup of your keys before generating it again

To facilitate this, the boot-tools directory comes with a script push-keys that will bundle your *.pub.json files and send it to the flow team. You can inspect this script to make sure no private key material is being bundled or uploaded. The data not encrypted before being sent as the public keys involved are not sensitive.

In phase 2 of the bootstrapping process, the Flow team will need to securely issue each node a Random Beacon key. This key is again sensitive and unique to your node. To enable this, the push-keys script also generates another key pair called the Transit Key. The public key of this pair will be uploaded along with the Staking and Network keys, and your Random Beacon key will be encrypted with it before being sent to you. You must keep your Transit Key until you have received and decrypted your Random Beacon key from the Flow team.

Update Node Config

As flow node requires a --nodeid flag to start. You will need to pass in the contents of the node-id into either your container, runtime-config.env file, or hard coded into the systemd unit file which the flow team provides.

You can get the node-id from the metadata that you pulled. It will be at: /path/to/bootstrap/public-genesis-information/node-id


Now the ball is in the Flow team's court. As soon as all nodes have completed the above steps, the Genesis block will be created and distributed to you.

Join the Flow discord server if you haven't already and stay tuned for updates. Your nodes need not be online during this waiting period if you want to suspend them to reduce cost, but you must not lose your key material.

Receive Your Random Beacon Keys

When the Flow team gives the go-ahead, your Random Beacon keys will be available for retrieval. Each Node will need to pull their own keys down individually.

Pulling your keys will also pull a bunch of additional metadata needed for the bootstrapping process. In the end, your bootstrap directory should look like this:

Move Genesis Data

This bootstrapping data is needed by your node at each startup, so it must be present on disk.

Where in the filesystem you store this data is up to you, but you may not change the folder structure generated by the bootstrapping process. By default, flow stores this data under /var/flow/bootstrap.

New Images

Once the Genesis block has been minted, it will be included into the official container images so that it's available to all nodes. Pull the new images, which should now be version v1.0.0.

Start Your Nodes

Once every node has puled its keys and fetched the new images, the network is ready to start.

Make sure you're part of the Discord Chat. Once all nodes are ready, updates will be provided to everyone.

Start your systems, let's make some blocks!