github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/cmd/bootstrap/transit/README.md (about)

     1  # Transit Bootstrap scripts
     2  
     3  The transit script is an utility used by node operators to upload and download relevant data before and after a Flow spork.
     4  It is used to download the root snapshot after a spork.
     5  Additionally, for a consensus node, it is used to upload transit keys and to submit root block votes.
     6  
     7  ## Server token
     8  
     9  The server token is needed with the `-t` flag for all commands. It authenticates the script to the server so that only trusted parties with the token may upload their node info and be included in the bootstrap data.
    10  
    11  ## Usage
    12  
    13  ```shell
    14  $ transit pull -t ${server-token} -d ${bootstrap-dir} -r ${flow-role}
    15  ```
    16  
    17  ### Pull
    18  
    19  After bootstrapping, running `transit pull` will:
    20  
    21  1. Fetch the following files:
    22  
    23     - `root-block.json` 
    24     - `node-infos.pub.json`
    25     - `root-protocol-snapshot.json`
    26     - `root-checkpoint` (only for execution nodes)
    27     - `random-beacon.priv.json.<id>.enc` (only for consensus nodes)
    28  
    29  1. Decrypt `random-beacon.priv.json.<id>.enc` using the transit keys (only for consensus nodes)
    30     - `random-beacon.priv.json`
    31  
    32  ### Wrapping Responses
    33  
    34  The transit script also has `wrap` for the other end of the connection. This function takes a private random-beacon key and wraps it with the corresponding transit key, which can then be sent back to the node.
    35  
    36  ```shell
    37  $ transit wrap -i ${ID} -r ${flow-role}
    38  ```
    39  
    40  The wrap function:
    41  
    42  1. Takes in `random-beacon.priv.json` and produces
    43     - `random-beacon.priv.json.<id>.enc`
    44  1. Uploads `random-beacon.priv.json.<id>.enc` to the server
    45  
    46  ## Consensus nodes
    47  
    48  The transit script has four commands applicable to consensus nodes:
    49  
    50  ```shell
    51  $ transit pull-root-block -t ${server-token} -d ${bootstrap-dir}
    52  $ transit generate-root-block-vote -t ${server-token} -d ${bootstrap-dir}
    53  $ transit push-root-block-vote -t ${server-token} -d ${bootstrap-dir} -v ${vote-file}
    54  $ transit push-transit-keys -t ${server-token} -d ${bootstrap-dir}
    55  ```
    56  
    57  ### Pull Root Block and Random Beacon Key
    58  
    59  Running `transit pull-root-block` will perform the following actions:
    60  
    61  1. Fetch the root block for the upcoming spork and write it to `<bootstrap-dir>/public-root-information/root-block.json`
    62  2. Fetch the random beacon key `random-beacon.priv.json.<id>.enc` and decrypt it using the transit keys
    63  
    64  ### Sign Root Block
    65  
    66  After the root block and random beacon key have been fetched, running `transit generate-root-block-vote` will:
    67  
    68  1. Create a combined signature over the root block using the node's private staking key and private random beacon key.
    69  2. Store the resulting vote to the file `<bootstrap-dir>/private-root-information/private-node-info_<node_id>/root-block-vote.json`
    70  
    71  ### Upload Vote
    72  
    73  Once a vote has been generated, running `transit push-root-block-vote` will upload the vote file to the server.
    74  
    75  ### Push Transit Key
    76  
    77  Transit key is used to encrypt the random beacon key generated for the consensus nodes.
    78  
    79  Running `transit push-transit-key` will perform the following actions:
    80  
    81  1. Create a Transit Keypair and write it to
    82     - `transit-key.pub.<id>`
    83     - `transit-key.priv.<id>`
    84  1. Upload the node's public files to the server
    85     - `transit-key.pub.<id>`