Genesis Bootstrapping
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.
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.
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.
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."
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
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.
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.
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.
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.
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:
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!