Skip to main content

Genesis Bootstrapping

Genesis Only

All nodes joining the network in May are required to go through this process as part of the Genesis Bootstrapping.

Overview

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.

Understanding Keys

The bootstrapping process deals with a number of different keys. Make sure you understand their usage and terminology by reviewing the Node Keys Guide.

Download the Bootstrapping Toolkit

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

Pull-boot-tools

_10
~ $ curl -sL -O storage.googleapis.com/flow-genesis-bootstrap/boot-tools.tar
_10
~ $ 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.

Node Address
Your Node Address must be a publicly routable IPv4 address or valid DNS name that points to your node. This is how other nodes in the network will communicate with you.
Generate-bootstrap-keys"

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

BYO Entropy

By default, the bootstrap script uses the kernel entropy source, either via a getrandom syscall or /dev/urandom. If you have a more secure source of entropy, like a hardware device, you can specify --staking-seed and --networking-seed, to provide your own seeds.

Run the bootstrap command with no flags to print usage information."

Protect your keys!

The key pairs generated in the bootstrapping process are extremely sensitive and must be managed securely. This guide does not deal with storing the keys in a secure backup or controlling access, as the right approach to this will vary from user to user, but it is something you must consider.

Private keys are suffixed with .priv.json, their public counterparts are not sensitive and can be shared freely.

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

bootstrap-directory

_10
~
_10
└──bootstrap
_10
├──{id}.node-info.priv.json
_10
└──{id}.node-info.pub.json",

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.

Token Needed

The transit script here need a -t token parameter flag. This token will have been provided to you by the Flow team out of band. Reach out to your contact if you don't have your token.

Upload-public-keys

_10
# If you joined our network previously, make sure to take a backup!
_10
cp /path/to/bootstrap /path/to/bootstrap.bak
_10
$ ./boot-tools/transit push -d ./bootstrap -t ${TOKEN} -role ${YOUR_NODE_ROLE}
_10
Running push
_10
Generating keypair
_10
Uploading ...
_10
Uploaded 400 bytes

One and Done!

Once you've run the bootstrap and are confident in your setup, run the transit push command only once. If you bootstrap again and transit push again with a new node ID, it will count against your quota of Nodes. Exceeding your quota will result in a long back and forth with the Flow team to see which node is the extra one.

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

Wait

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.

A Note on Staking

For the Genesis Block, your nodes will start pre-staked, which means no action on your part is needed to get your nodes staked.

For more details on staking check the guide on Staking and Rewards.

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.

Pull-beacon-keys

_10
~ $ ./boot-tools/transit pull -d ./bootstrap -t ${TOKEN} -role ${YOUR_NODE_ROLE}
_10
Fetching keys for node ID FEF5CCFD-DC66-4EF6-8ADB-C93D9B6AE5A4
_10
Decrypting Keys
_10
Keys available

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:

bootstrap-directory

_19
~
_19
bootstrap/
_19
├── private-genesis-information
_19
│ └── private-node-info_{node id}
_19
│ ├── node-info.priv.json
_19
│ └── random-beacon.priv.json
_19
├── public-genesis-information
_19
│ ├── dkg-data.pub.json
_19
│ ├── genesis-block.json
_19
│ ├── genesis-cluster-block.{cid}.json
_19
│ ├── genesis-cluster-block.{cid}.json
_19
│ ├── genesis-cluster-qc.{cid}.json
_19
│ ├── genesis-cluster-qc.{cid}.json
_19
│ ├── genesis-commit.json
_19
│ ├── genesis-qc.json
_19
│ ├── node-id
_19
│ ├── node-info.pub.{node id}.json
_19
│ └── node-infos.pub.json
_19
├── <additional files...>

Why are we generating the beacon keys for you?

Unlike staking and account keys, the beacon keys are not randomly generated, and depend on inputs from all consensus nodes on the network. In typical Flow network operation, these keys will be dynamically generated on demand by the consensus nodes communicating. However for genesis, as the consensus nodes aren't communicating yet, the Flow team will generate and distribute them to kickstart the process.

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!