bootstrap

Bootstrapping

This package contains script for generating the bootstrap files needed to initialize the Flow network. The high-level bootstrapping process is described in Notion.

WARNING: These scripts use Go's crypto/rand package to generate seeds for private keys, whenever seeds are not provided to the commands. Make sure you are running the bootstrap scripts on a machine that does provide a low-level cryptographically secure RNG. See https://golang.org/pkg/crypto/rand/ for details.

NOTE: Public and private keys are encoded in JSON files as hex strings.

Code structure:

• cmd/bootstrap/cmd contains CLI logic that can exit the program and read/write files. It also uses structures and data types that are purely relevant for CLI purposes, such as encoding, decoding, etc.
• cmd/bootstrap/run contains reusable logic that does not know about the CLI. Instead of exiting the program, functions here will return errors.

Overview

The bootstrapping will generate the following information:

Per node

• Staking private key (BLS key on curve BLS12-381)
• Networking private key (ECDSA key on curve P-256)
• Random beacon private key; only for consensus nodes (BLS key on curve BLS12-381, used for a BLS-based threshold signatures)

Node Identities

• List of all authorized Flow nodes
  • node network address
  • node ID
  • node role
  • public staking key
  • proof of possession of the staking private key
  • public networking key
  • weight

Collector clusters

Each cluster of collector nodes needs to have its own root Block and root QC

• Root clustering: assignment of collector nodes to clusters
• For each cluster:
  • Root cluster.Block
  • Root QC: votes from collector nodes for the respective root cluster.Block

Root Block for main consensus

• Root Block
• Root QC: votes from consensus nodes for the root block (required to start consensus)
• Root Execution Result: execution result for the initial execution state
• Root Block Seal: block seal for the initial execution result

Usage

go run ./cmd/bootstrap prints usage information

Phase 1: Generate networking and staking keys for partner nodes:

This step will generate the staking and networking keys for a single partner node.

Required Inputs

Values directly specified as command line parameters:

• node network address
• node role

Optional Inputs

Values can be specified as command line parameters:

• seed for generating staking key (min 48 bytes in hex encoding)
• seed for generating networking key (min 48 bytes in hex encoding) Provided seeds must be of high entropy, ideally generated by a crypto secure RNG. If seeds are not provided, the CLI will try to use the system's random number generator (RNG), e. g. dev/urandom. Make sure you are running the CLI on a hardware that has a cryptographically secure RNG.

Example

go run ./cmd/bootstrap key --address "example.com:1234" --role "consensus" -o ./bootstrap/partner-node-infos

Generated output files

• file <NodeID>.node-info.priv.json
  • strictly CONFIDENTIAL (only for respective partner node with ID )
  • contains node's private staking and networking keys (plus some other auxiliary information)
  • REQUIRED at NODE START; file needs to be available to respective partner node at boot up (or recovery after crash)
• file <NodeID>.node-info.pub.json
  • public information
  • file needs to be delivered to the Flow Foundation team for Phase 2 of generating root information, but is not required at node start

Phase 2: Generating final root information

This step will generate the entire root information for all nodes (incl. keys for all Dapper-controlled nodes).

Required Inputs

Each input is a config file specified as a command line parameter:

• parameter with the ID for the chain for the root block (root-chain)
• parameter with the ID of the parent block for the root block (root-parent)
• parameter with height of the root block to bootstrap from (root-height)
• parameter with view of the root block to bootstrap from (root-view)
• parameter with state commitment for the initial execution state (root-commit)
• json containing configuration for all Dapper-Controlled nodes (see ./example_files/node-config.json)
• folder containing the <NodeID>.node-info.pub.json files for all partner nodes (see .example_files/partner-node-infos)
• json containing the weight value for all partner nodes (see ./example_files/partner-weights.json). Format: <NodeID>: <weight value>
• random seed for the new collector node clustering and epoch RandomSource (min 32 bytes in hex encoding) Provided seeds should be derived from a verifiable random source, such as the previous epoch's RandomSource.

Example

go run . genconfig \
    --address-format "%s%d-example.onflow.org:3569" \
    --access 2 \
    --collection 4 \
    --consensus 3 \
    --execution 2 \
    --verification 3 \
    --weight 100 \
    -o ./ \
    --config ./bootstrap-example/node-config.json

go run . keygen \
    --machine-account \
    --config ./bootstrap-example/node-config.json \
    -o ./bootstrap-example/keys

go run . cluster-assignment \
    --epoch-counter 0 \
    --collection-clusters 1 \
    --clustering-random-seed 00000000000000000000000000000000000000000000000000000000deadbeef \
    --config ./bootstrap-example/node-config.json \
    -o ./bootstrap-example \
    --partner-dir ./example_files/partner-node-infos \
    --partner-weights ./example_files/partner-weights.json \
    --internal-priv-dir ./bootstrap-example/keys

go run . rootblock  \
    --root-chain bench \
    --root-height 0 \
    --root-parent 0000000000000000000000000000000000000000000000000000000000000000 \
    --root-view 0 \
    --epoch-counter 0 \
    --epoch-length 30000 \
    --epoch-staking-phase-length 20000 \
    --epoch-dkg-phase-length 2000 \
    --random-seed 00000000000000000000000000000000000000000000000000000000deadbeef \
    --collection-clusters 1 \
    --protocol-version=0 \
    --use-default-epoch-timing \
    --kvstore-finalization-safety-threshold=1000 \
    --kvstore-epoch-extension-view-count=2000 \
    --config ./bootstrap-example/node-config.json \
    -o ./bootstrap-example \
    --partner-dir ./example_files/partner-node-infos \
    --partner-weights ./example_files/partner-weights.json \
    --internal-priv-dir ./bootstrap-example/keys \
    --intermediary-clustering-data ./bootstrap-example/public-root-information/root-clustering.json \
    --cluster-votes-dir ./bootstrap-example/public-root-information/root-block-votes/

go run . finalize \
    --config ./bootstrap-example/node-config.json \
    --partner-dir ./example_files/partner-node-infos \
    --partner-weights ./example_files/partner-weights.json \
    --internal-priv-dir ./bootstrap-example/keys/private-root-information \
    --dkg-data ./bootstrap-example/private-root-information/root-dkg-data.priv.json \
    --root-block ./bootstrap-example/public-root-information/root-block.json \
    --intermediary-bootstrapping-data ./bootstrap-example/public-root-information/intermediary-bootstrapping-data.json \
    --root-block-votes-dir ./bootstrap-example/public-root-information/root-block-votes/ \
    --root-commit 0000000000000000000000000000000000000000000000000000000000000000 \
    --genesis-token-supply="1000000000.0" \
    --service-account-public-key-json "{\"PublicKey\":\"R7MTEDdLclRLrj2MI1hcp4ucgRTpR15PCHAWLM5nks6Y3H7+PGkfZTP2di2jbITooWO4DD1yqaBSAVK8iQ6i0A==\",\"SignAlgo\":2,\"HashAlgo\":1,\"SeqNumber\":0,\"Weight\":1000}" \
    -o ./bootstrap-example

Generated output files

• files <NodeID>.node-info.priv.json

  • strictly CONFIDENTIAL (only for respective Dapper node with ID )
  • contains node's private staking and networking keys (plus some other auxiliary information)
  • REQUIRED at NODE START: file needs to be available to respective Dapper node at boot up (or recovery after crash)

• files <NodeID>.random-beacon.priv.json

  • strictly CONFIDENTIAL (only for consensus node with ID )
  • CAUTION: we generate the random beacon private keys for all consensus nodes, i.e. Dapper and Partner nodes alike! The private random beacon keys must be delivered to the Partner Node operator securely.
  • contains node's private random beacon key
  • REQUIRED at NODE START: file needs to be available to respective consensus node at boot up (or recovery after crash)

• file node-infos.pub.json

  • contains public Node Identities for all authorized Flow nodes (Dapper and Partner nodes)
  • REQUIRED at NODE START for all nodes; file needs to be available to all nodes at boot up (or recovery after crash)

• file root-block.json

  • REQUIRED at NODE START by all nodes

• file root-qc.json

  • REQUIRED at NODE START by all nodes

• file root-result.json

  • REQUIRED at NODE START by all nodes

• file root-seal.json

  • REQUIRED at NODE START by all nodes

• file dkg-data.pub.json

  • REQUIRED at NODE START by all nodes

Generating networking key for Observer

This generates the networking key used by observers to connect to the public libp2p network. It is a different key format than staked nodes and should only be used for Observers.

go run ./cmd/bootstrap observer-network-key  -f ./path/network-key

This key must be kept secret as it's used to encrypt and sign network requests sent by the observers.