From 7d731322b2ebfadfc6c8755c9e9955f094faaf58 Mon Sep 17 00:00:00 2001 From: sacha Date: Tue, 1 Feb 2022 12:02:04 +0100 Subject: [PATCH] Book: trusted sync (edits and clarifications) (#3329) * edits * more edits and clarifications * edit * add clarification on --trusted-node-url * address feedback * remove repetition --- docs/the_nimbus_book/src/SUMMARY.md | 4 +- docs/the_nimbus_book/src/rest-api.md | 2 +- docs/the_nimbus_book/src/start-syncing.md | 3 +- docs/the_nimbus_book/src/trusted-node-sync.md | 75 ++++++++++++------- 4 files changed, 52 insertions(+), 32 deletions(-) diff --git a/docs/the_nimbus_book/src/SUMMARY.md b/docs/the_nimbus_book/src/SUMMARY.md index 4efc1377a..e8b1ed447 100644 --- a/docs/the_nimbus_book/src/SUMMARY.md +++ b/docs/the_nimbus_book/src/SUMMARY.md @@ -11,8 +11,8 @@ # How-to (beacon node) - [Install dependencies](./install.md) - [Build the beacon node](./build.md) -- [Sync the beacon node](./start-syncing.md) - - [Trusted node sync](./trusted-node-sync.md) +- [Sync from scratch](./start-syncing.md) +- [Sync from a trusted node (checkpoint sync)](./trusted-node-sync.md) - [Add a backup web3 provider](./web3-backup.md) # How-to (validator) diff --git a/docs/the_nimbus_book/src/rest-api.md b/docs/the_nimbus_book/src/rest-api.md index 47614037c..fe65bd692 100644 --- a/docs/the_nimbus_book/src/rest-api.md +++ b/docs/the_nimbus_book/src/rest-api.md @@ -1,6 +1,6 @@ # REST API -Nimbus exposes an **extremely fast** and high-performance implementation of the standard [Beacon Node API](https://ethereum.github.io/beacon-APIs/). The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers as well as your own monitoring infrastructure. +Nimbus exposes an **extremely fast** implementation of the standard [Beacon Node API](https://ethereum.github.io/beacon-APIs/). The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers as well as your own monitoring infrastructure. The API is a `REST` interface accessed via `HTTP`. **The API should not be exposed to the public Internet** unless protected by additional security: it includes multiple endpoints which could open your node to denial-of-service (DoS) attacks. diff --git a/docs/the_nimbus_book/src/start-syncing.md b/docs/the_nimbus_book/src/start-syncing.md index dd64fa7a1..d7bf81fe3 100644 --- a/docs/the_nimbus_book/src/start-syncing.md +++ b/docs/the_nimbus_book/src/start-syncing.md @@ -1,5 +1,4 @@ - -# Start syncing +# Sync from scratch To minimize the amount of downtime, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit. If it's not fully synced you will miss attestations and proposals until it has finished syncing. diff --git a/docs/the_nimbus_book/src/trusted-node-sync.md b/docs/the_nimbus_book/src/trusted-node-sync.md index 14c2aef81..7e04fed70 100644 --- a/docs/the_nimbus_book/src/trusted-node-sync.md +++ b/docs/the_nimbus_book/src/trusted-node-sync.md @@ -1,72 +1,93 @@ -# Trusted node sync +# Sync from a trusted node -When you start the beacon node for the first time, it will connect to the beacon chain network and start syncing automatically, a process that can take several days. +When you [start the beacon node](./quick-start.md) for the first time, it will connect to the beacon chain network and start syncing automatically, a process that can take several days. -Trusted node sync allows you to get started more quickly with Nimbus by fetching a recent checkpoint from a trusted node. +Trusted node sync allows you to get started more quickly with Nimbus by fetching a recent checkpoint from a trusted node (we will expect it will save you 1 to 2 days). -To use trusted node sync, you must have access to a node that you trust that exposes the REST HTTP API, for example a locally running backup node. +To use trusted node sync, you must have access to a node that you trust that exposes the Ethereum [Beacon API](./rest-api.md) (for example a locally running backup node). -Should this node or your connection to it be compromised, your node will not be able to detect that it's being served false information. +Should this node, or your connection to it, be compromised, your node will not be able to detect whether or not it is being served false information. -It is possibly to use trusted node sync with a third-party API provider - follow the steps below to verify that the chain you were given corresponds to the canonical chain at the time. +It is possibly to use trusted node sync with a third-party API provider -- see [here](trusted-node-sync.md#verify-you-synced-the-correct-chain) for how to verify that the chain you are given corresponds to the canonical chain at the time. -## Performing a trusted node sync +## Perform a trusted node sync -**Prater (testnet)** - -```bash -build/nimbus_beacon_node trustedNodeSync --network:prater \ - --data-dir=build/data/shared_prater_0 \ - --trusted-node-url=http://localhost:5052 -``` +> **Tip:** Make sure to replace `http://localhost:5052` in the commands below with the appropriate endpoint for you. `http://localhost:5052` is the endpoint exposed by Nimbus but this is not consistent across all clients. For example, if your trusted node is a [Prysm node](https://docs.prylabs.network/docs/how-prysm-works/ethereum-public-api#performing-requests-against-a-local-prysm-node), it exposes `127.0.0.1:3500` by default. Which means you would run the commands below with +> +> `--trusted-node-url=http://127.0.0.1:3500` **Mainnet** +To sync Mainnet, from the `nimbus-eth2` directory run: + ```bash build/nimbus_beacon_node trustedNodeSync --network:mainnet \ --data-dir=build/data/shared_mainnet_0 \ --trusted-node-url=http://localhost:5052 ``` -**NOTE** +**Prater (testnet)** -Because trusted node sync by default copies all blocks via REST, if you use a third-party service to sync from, you may hit API limits - see the `--backfill` option. +To sync Prater, from the `nimbus-eth2` directory run: -## Verifying that you synced the correct chain +```bash +build/nimbus_beacon_node trustedNodeSync --network:prater \ + --data-dir=build/data/shared_prater_0 \ + --trusted-node-url=http://localhost:5052 +``` -When performing a trusted node sync, you can manually verify that the correct chain was synced by comparing the head hash with other sources, such as friends, forums, chats and web sites. You can retrieve the current head from the node using: + + +> **Note:** +> Because trusted node sync by default copies all blocks via REST, if you use a third-party service to sync from, you may hit API limits. If this happens to you, you may need to use the `--backfill` option to [delay the backfill of the block history](./trusted-node-sync.md#delay-block-history-backfill). + +## Verify you synced the correct chain + +When performing a trusted node sync, you can manually verify that the correct chain was synced by comparing the head hash with other sources (e.g. your friends, forums, chats and web sites). If you're syncing using your own backup node you can retrieve the current head from the node using: ``` -# Make sure to enabled the `--rest` option when running your node: +# Make sure to enable the `--rest` option when running your node: curl http://localhost:5052/eth/v1/beacon/blocks/head/root ``` The `head` root is also printed in the log output at regular intervals. -## Block history +> **Note:** this same [Beacon API](./rest-api.md) request should work with any third-party provider. +> +> For example, to test it out with our mainnet [testing server](rest-api.md#test-your-tooling-against-our-servers), you could run: +> +> ``` +> curl -X GET http://testing.mainnet.beacon-api.nimbus.team/eth/v1/beacon/blocks/head/root +> ``` + + + +## Advanced + +### Delay block history backfill By default, both the state and the full block history will be downloaded from the trusted node. It is possible to get started more quickly by delaying the backfill of the block history using the `--backfill=false` parameter. In this case, the beacon node will first sync to the current head so that it can start performing its duties, then backfill the blocks from the network. -While it's backfilling blocks from the network, the node will be violating the beacon chain protocol and may be disconnected or lose reputation with other nodes. +> **Warning:** While backfilling blocks, your node will not be able to answer historical requests or sync requests. This might lead to you being de-scored, and eventually disconnected, by your peers. -## Sync point +### Modify sync point -By default, the node will sync up to the latest finalized checkpoint of the node that you're syncing with. You can choose a different sync point using a block hash or a slot number - this block must fall on an epoch boundary: +By default, the node will sync up to the latest finalized checkpoint of the node that you're syncing with. While you can choose a different sync point using a block hash or a slot number, this block must fall on an epoch boundary: ``` build/nimbus_beacon_node trustedNodeSync --blockId:0x239940f2537f5bbee1a3829f9058f4c04f49897e4d325145153ca89838dfc9e2 ... ``` -## Sync from checkpoint files +### Sync from checkpoint files -If you have a state and a block file available, you can instead start the node using the finalized checkpoint options: +If you have a state and a block file available, you can start the node using the finalized checkpoint options: ``` -# Obtain a state and a block from a REST API - these must be in SSZ format: +# Obtain a state and a block from a Beacon API - these must be in SSZ format: curl -o state.32000.ssz -H 'Accept: application/octet-stream' http://localhost:5052/eth/v2/debug/beacon/states/32000 curl -o block.32000.ssz -H 'Accept: application/octet-stream' http://localhost:5052/eth/v2/beacon/blocks/32000 @@ -76,4 +97,4 @@ build/nimbus_beacon_node --data-dir:trusted --finalized-checkpoint-block=block.3 ## Caveats -A node synced using trusted node sync will not be able to serve historical requests via the REST API from before the checkpoint. Future versions will resolve this issue. +A node synced using trusted node sync will not be able to serve historical requests via the Beacon API from before the checkpoint. Future versions will resolve this issue.