Node Bootstrap
This guide is for getting a new node staked and running on Flow other than a permissionless Access node. For running a permissionless Access node see Access node setup. For sporking documentation for existing node operators, see Spork Process.
Timing​
New nodes are able to join the network each time a new epoch begins.
In order to join the network at epoch N+1, the node must be registered with sufficient stake and
authorized by the service account prior to the end of epoch N's Staking Auction Phase.
Confirmation of a new node's inclusion in epoch N+1 is included in the EpochSetup
event.
Nodes registered for epoch N+1 are able to participate in network communication on a limited basis starting in the Epoch Setup Phase
of epoch N.
Once registered and confirmed to join the network at epoch N+1, the node must start up before epoch N+1 begins.
- Verification & Access nodes may start up any time during the
Epoch Setup Phase
. - Consensus & Collection nodes must start up within the first 1000 views (~30mins)
of the
Epoch Setup Phase
to participate in the Epoch Preparation Protocol.
Step 1 - Run Genesis Bootstrap​
You will need to run this process for each node that you are operating
Download the Bootstrapping Kit​
If you have downloaded the bootstrapping kit previously, ensure you check the hash below still matches. If not, re-download to ensure you are using the most up-to-date version.
_10curl -sL -O storage.googleapis.com/flow-genesis-bootstrap/boot-tools.tar_10tar -xvf boot-tools.tar_10chmod +x ./boot-tools/bootstrap_10chmod +x ./boot-tools/transit
Generate Your Node Keys​
Network Address​
Use a fully qualified domain name for the network address. Please also include the port number in the network address e.g. example.com:3569
Do not include in http://
format.
If you are running multiple nodes, please ensure you have different addresses for each node.
All your current keys and Flow genesis files should be in the bootstrap
folder created earlier. Please take a back up of the entire folder.
_10## Skip this section if this is your first time ##_10# If you joined our network previously, make sure to take a backup of your previously generated keys!_10cp -r /path/to/bootstrap /path/to/bootstrap.bak_10#########################################################_10# Generate Keys_10$ mkdir ./bootstrap_10# YOUR_NODE_ADDRESS: FQDN associated to your instance (do NOT use an IP address, use a hostname)_10# YOUR_NODE_ROLE: The Flow nodes that you wish to run, it should be ONE of the following - [ access, collection, consensus, execution, verification ]_10$ ./boot-tools/bootstrap key --address \"YOUR_NODE_ADDRESS_GOES_HERE:3569\" --role YOUR_NODE_ROLE_GOES_HERE -o ./bootstrap
For consensus
and collection
node types an additional key will be created for the Machine Account.
For all other node types this will not be needed.
Machine Account Creation​
If you are running a collection and consensus node, you will have an additional private key file (node-machine-account-key.priv.json
)
which contains the private key for your node's machine account. You can learn more about machine
accounts here.
In Step 2 of this guide, when you submit a transaction to stake your node, you will need to provide the
machine account public key, which can be found in the output of the previous bootstrap key
command.
Copy the machine account public key somewhere safe. You will need it in a later step.
Step 2 - Stake Your Node​
Stake your node via Flow Port
The node details
(Node ID
, Network Address
, Networking Key
and Staking Key
) that need to be submitted when staking the node on Flow Port, can be found in the file: ./bootstrap/public-root-information/node-info.pub.<node-id>.json
.
If you are running a collection or consensus node, you will need to provide an additional field Machine Account Public Key
.
This value is found in the output of the bootstrap key
command from Step 1.
Please let us know your node id via discord or email.
Finalize Machine Account Setup​
If you are not running a collection or consensus node, you can skip this step.
You will now need to use the bootstrap
utility to run machine-account
with the created address to finalize the set up of your Machine account.
_10$ ./boot-tools/bootstrap machine-account --address YOUR_MACHINE_ACCOUNT_ADDRESS_GOES_HERE -o ./bootstrap
After running this step, you should see the node-machine-account-info.priv.json
file in your bootstrap
directory as shown above.
Verify Machine Account Setup​
After finalizing your machine account setup, you should verify its correctness with the check-machine-account
command:
This command will detect and provide information about common misconfigurations, or confirm that the machine account is configured correctly.
Push transit keys (consensus node only)​
If you are running a consensus node, run the following command to generate the transit keys.
This will generate the public and private transit keys under the bootstrap folder. The transit keys are used to transfer the DKG keys after a network upgrade.
Please share the public transit key with the Flow Foundation via discord or email.
Step 3 - Start Your Flow Node​
Ensure you have configured your node using the Node Setup guide.
Confirming authorization​
You can confirm your node's successful registration and authorization by executing a Cadence script to query the Staking Contract.
At the end of the Staking Auction Phase
, the members of the Proposed Identity Table are confirmed as authorized participants in the next epoch.
Therefore, if your node ID appears in the Proposed Identity Table during the Staking Auction Phase
, your node will be a participant in the next epoch.
You can read the current Proposed Identity Table using the getProposedTable script.
You can read the current epoch phase using the getEpochPhase script. (A return value of 0
indicates the Staking Auction Phase
.)
Trusted Root Snapshot​
Once your node has been registered and authorized by the service account, it will be able to participate in the next epoch.
A new node must bootstrap with a trusted root snapshot of the protocol state, where the node is a confirmed participant.
Since new nodes are confirmed at the end of the Staking Auction Phase
, this means that, if the node is registered to join at epoch N+1
, it must use a root snapshot from within the Epoch Setup Phase
of epoch N
.
Dynamic Startup​
Flow provides a mechanism called Dynamic Startup to simplify the process of obtaining the root snapshot.
When using Dynamic Startup, the node can be started at any time during the Staking Auction Phase
.
The node will wait for the Epoch Setup Phase
to begin, retrieve a valid root snapshot from a trusted Access Node, then bootstrap its state and join the network.
This is the recommended way to start your node for the first time.
- Remove any
root-protocol-state-snapshot.json
file from yourbootstrap
folder. (If this file is present the node will attempt to bootstrap with it rather than Dynamic Startup.) - Select a trusted Access Node to provide the root snapshot. You will need this node's secure GRPC server address and Networking Public Key.
- Configure Dynamic Startup by adding flags:
- Start your node (see guide)
Once the node has bootstrapped, these flags may be removed.
Manually Provisioned Root Snapshot​
You can also provision the root snapshot file manually, then start the node without configuring Dynamic Startup. A snapshot can be obtained from any Access Node using Flow CLI.
The snapshot must be within the Epoch Setup Phase
.
Since Collection and Consensus Nodes must start up in the first ~30mins of the Epoch Setup Phase
(see Timing),
the snapshot must be provisioned within this time window.
Once a valid root snapshot file is downloaded to the node's bootstrap folder, it can be started (see guide)