github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/cmd/bootstrap/README.md (about) 1 # Bootstrapping 2 3 This package contains script for generating the bootstrap files needed to initialize the Flow network. 4 The high-level bootstrapping process is described in [Notion](https://www.notion.so/dapperlabs/Flow-Bootstrapping-ce9d227f18a8410dbce74ed7d4ddee27). 5 6 WARNING: These scripts use Go's crypto/rand package to generate seeds for private keys. Make sure you are running the bootstrap scripts on a machine that does provide proper a low-level implementation. See https://golang.org/pkg/crypto/rand/ for details. 7 8 NOTE: Public and private keys are encoded in JSON files as base64 strings, not as hex, contrary to what might be expected. 9 10 Code structure: 11 * `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. 12 * `cmd/bootstrap/run` contains reusable logic that does not know about the CLI. Instead of exiting the program, functions here will return errors. 13 14 15 16 # Overview 17 18 The bootstrapping will generate the following information: 19 20 #### Per node 21 * Staking key (BLS key with curve BLS12-381) 22 * Networking key (ECDSA key) 23 * Random beacon key; _only_ for consensus nodes (BLS based on Joint-Feldman DKG for threshold signatures) 24 25 #### Node Identities 26 * List of all authorized Flow nodes 27 - node network address 28 - node ID 29 - node role 30 - public staking key 31 - public networking key 32 - weight 33 34 #### Root Block for main consensus 35 * Root Block 36 * Root QC: votes from consensus nodes for the root block (required to start consensus) 37 * Root Execution Result: execution result for the initial execution state 38 * Root Block Seal: block seal for the initial execution result 39 40 41 #### Root Blocks for Collector clusters 42 _Each cluster_ of collector nodes needs to have its own root Block and root QC 43 * Root `ClusterBlockProposal` 44 * Root QC from cluster for their respective `ClusterBlockProposal` 45 46 47 # Usage 48 49 `go run ./cmd/bootstrap` prints usage information 50 51 ## Phase 1: Generate networking and staking keys for partner nodes: 52 53 This step will generate the staking and networking keys for a _single partner node_. 54 55 #### Required Inputs 56 Values directly specified as command line parameters: 57 - node network address 58 - node role 59 60 #### Optional Inputs 61 Values can be specified as command line parameters: 62 - seed for generating staking key (min 48 bytes in hex encoding) 63 - seed for generating networking key (min 48 bytes in hex encoding) 64 If seeds are not provided, the CLI will try to use the system's pseudo-random number generator (PRNG), e. g. `dev/urandom`. Make sure you are running the CLI on a hardware that has a cryptographically secure PRNG, or provide seeds generated on such a system. 65 66 #### Example 67 ```bash 68 go run ./cmd/bootstrap key --address "example.com:1234" --role "consensus" -o ./bootstrap/partner-node-infos 69 ``` 70 71 #### Generated output files 72 * file `<NodeID>.node-info.priv.json` 73 - strictly CONFIDENTIAL (only for respective partner node with ID <NodeID>) 74 - contains node's private staking and networking keys (plus some other auxiliary information) 75 - REQUIRED at NODE START; 76 file needs to be available to respective partner node at boot up (or recovery after crash) 77 * file `<NodeID>.node-info.pub.json` 78 - public information 79 - file needs to be delivered to Dapper Labs for Phase 2 of generating root information, 80 but is not required at node start 81 82 83 ## Phase 2: Generating final root information 84 85 This step will generate the entire root information for all nodes (incl. keys for all Dapper-controlled nodes). 86 87 #### Required Inputs 88 Each input is a config file specified as a command line parameter: 89 * parameter with the ID for the chain for the root block (`root-chain`) 90 * parameter with the ID of the parent block for the root block (`root-parent`) 91 * parameter with height of the root block to bootstrap from (`root-height`) 92 * parameter with state commitment for the initial execution state (`root-commit`) 93 * `json` containing configuration for all Dapper-Controlled nodes (see `./example_files/node-config.json`) 94 * folder containing the `<NodeID>.node-info.pub.json` files for _all_ partner nodes (see `.example_files/partner-node-infos`) 95 * `json` containing the weight value for all partner nodes (see `./example_files/partner-weights.json`). 96 Format: ```<NodeID>: <weight value>``` 97 98 #### Example 99 ```bash 100 go run . genconfig \ 101 --address-format "%s%d-example.onflow.org:3569" \ 102 --access 2 \ 103 --collection 4 \ 104 --consensus 3 \ 105 --execution 2 \ 106 --verification 3 \ 107 --weight 100 \ 108 -o ./ \ 109 --config ./bootstrap-example/node-config.json 110 111 ``` 112 113 ```bash 114 go run . keygen \ 115 --machine-account \ 116 --config ./bootstrap-example/node-config.json \ 117 -o ./bootstrap-example/keys 118 119 ``` 120 121 ```bash 122 go run . rootblock \ 123 --root-chain bench \ 124 --root-height 0 \ 125 --root-parent 0000000000000000000000000000000000000000000000000000000000000000 \ 126 --epoch-counter 0 \ 127 --epoch-length 30000 \ 128 --epoch-staking-phase-length 20000 \ 129 --epoch-dkg-phase-length 2000 \ 130 --collection-clusters 1 \ 131 --protocol-version=0 \ 132 --use-default-epoch-timing \ 133 --epoch-commit-safety-threshold=1000 \ 134 --config ./bootstrap-example/node-config.json \ 135 -o ./bootstrap-example \ 136 --partner-dir ./example_files/partner-node-infos \ 137 --partner-weights ./example_files/partner-weights.json \ 138 --internal-priv-dir ./bootstrap-example/keys 139 ``` 140 141 ```bash 142 go run . finalize \ 143 --config ./bootstrap-example/node-config.json \ 144 --partner-dir ./example_files/partner-node-infos \ 145 --partner-weights ./example_files/partner-weights.json \ 146 --internal-priv-dir ./bootstrap-example/keys/private-root-information \ 147 --dkg-data ./bootstrap-example/private-root-information/root-dkg-data.priv.json \ 148 --root-block ./bootstrap-example/public-root-information/root-block.json \ 149 --intermediary-bootstrapping-data ./bootstrap-example/public-root-information/intermediary-bootstrapping-data.json \ 150 --root-block-votes-dir ./bootstrap-example/public-root-information/root-block-votes/ \ 151 --root-commit 0000000000000000000000000000000000000000000000000000000000000000 \ 152 --genesis-token-supply="1000000000.0" \ 153 --service-account-public-key-json "{\"PublicKey\":\"R7MTEDdLclRLrj2MI1hcp4ucgRTpR15PCHAWLM5nks6Y3H7+PGkfZTP2di2jbITooWO4DD1yqaBSAVK8iQ6i0A==\",\"SignAlgo\":2,\"HashAlgo\":1,\"SeqNumber\":0,\"Weight\":1000}" \ 154 -o ./bootstrap-example 155 ``` 156 157 #### Generated output files 158 * files `<NodeID>.node-info.priv.json` 159 - strictly CONFIDENTIAL (only for respective Dapper node with ID <NodeID>) 160 - contains node's private staking and networking keys (plus some other auxiliary information) 161 - REQUIRED at NODE START: 162 file needs to be available to respective Dapper node at boot up (or recovery after crash) 163 * files `<NodeID>.random-beacon.priv.json` 164 - strictly CONFIDENTIAL (only for consensus node with ID <NodeID>) 165 - CAUTION: we generate the random beacon private keys for _all_ consensus nodes, i.e. Dapper and Partner nodes alike! 166 The private random beacon keys must be delivered to the Partner Node operator securely. 167 - contains node's _private_ random beacon key 168 - REQUIRED at NODE START: 169 file needs to be available to respective consensus node at boot up (or recovery after crash) 170 * file `node-infos.pub.json` 171 - contains public Node Identities for all authorized Flow nodes (Dapper and Partner nodes) 172 - REQUIRED at NODE START for all nodes; 173 file needs to be available to all nodes at boot up (or recovery after crash) 174 175 * file `root-block.json` 176 - REQUIRED at NODE START by all nodes 177 * file `root-qc.json` 178 - REQUIRED at NODE START by all nodes 179 * file `root-result.json` 180 - REQUIRED at NODE START by all nodes 181 * file `root-seal.json` 182 - REQUIRED at NODE START by all nodes 183 * file `dkg-data.pub.json` 184 - REQUIRED at NODE START by all nodes 185 186 * file `<ClusterID>.root-cluster-block.json` 187 - root `ClusterBlockProposal` for collector cluster with ID `<ClusterID>` 188 - REQUIRED at NODE START by all collectors of the respective cluster 189 - file can be made accessible to all nodes at boot up (or recovery after crash) 190 * file `<ClusterID>.root-cluster-qc.json` 191 - root Quorum Certificate for `ClusterBlockProposal` for collector cluster with ID `<ClusterID>` 192 - REQUIRED at NODE START by all collectors of the respective cluster 193 - file can be made accessible to all nodes at boot up (or recovery after crash) 194 195 ## Generating networking key for Observer 196 197 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. 198 199 ```bash 200 go run ./cmd/bootstrap observer-network-key -f ./path/network-key 201 ``` 202 203 This key must be kept secret as it's used to encrypt and sign network requests sent by the observers.