diff --git a/docs/the_nimbus_book/book.toml b/docs/the_nimbus_book/book.toml index 0243bbf3e..11a3389ff 100644 --- a/docs/the_nimbus_book/book.toml +++ b/docs/the_nimbus_book/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["Lee Ting Ting", "Jacek Sieka"] +authors = ["Lee Ting Ting", "Jacek Sieka", "Sacha Saint-Leger"] language = "en" multilingual = false src = "src" diff --git a/docs/the_nimbus_book/src/SUMMARY.md b/docs/the_nimbus_book/src/SUMMARY.md index 248799308..ec808cd6c 100644 --- a/docs/the_nimbus_book/src/SUMMARY.md +++ b/docs/the_nimbus_book/src/SUMMARY.md @@ -12,6 +12,7 @@ - [Setting up a systemd service](./beacon_node_systemd.md) - [Generating your keys with NBC](./create_wallet_and_deposit.md) # Misc +- [Infura guide](infura-guide.md) - [Windows users]() - [FAQ](./faq.md) - [Contribute](./contribute.md) diff --git a/docs/the_nimbus_book/src/infura-guide.md b/docs/the_nimbus_book/src/infura-guide.md new file mode 100644 index 000000000..9eee3ee53 --- /dev/null +++ b/docs/the_nimbus_book/src/infura-guide.md @@ -0,0 +1,138 @@ +# Supplying your own Infura endpoint + +In a nutshell, Infura is a hosted ethereum node cluster that lets you make requests to the eth1 blockchain without requiring you to set up your own eth1 node. + +While we do support Infura to process incoming validator deposits, we recommend running your own eth1 node to avoid relying on a third-party-service. + +> **Note:** Nimbus currently supports remote Infura nodes and [local Geth archive nodes](https://gist.github.com/onqtam/aaf883d46f4dab1311ca9c160df12fe4). However we are working on relaxing that assumption (an archive node certainly won't be required for mainnet). In the future, we plan on having our own eth1 client -- [Nimbus 1](https://github.com/status-im/nimbus) -- be the recommended default. + +## How it works + +When you join an eth2 testnet by running `make spadina` or `make medalla`, the beacon node actually launches with an Infura endpoint supplied by us. + +This endpoint is passed through the `web3-url` option (which takes as input the url of the web3 server from which you'd like to observe the eth1 chain). + +If you look at the initial logs you should see something similar to the following: + + +``` +DBG 2020-09-29 12:15:41.969+02:00 Launching beacon node +topics="beacnde" tid=8941404 file=beacon_node.nim:1190 version="0.5.0 (78ceeed8)" bls_backend=BLST +cmdParams="@[ +\"--network=spadina\", +\"--log-level=DEBUG\", +\"--log-file=build/data/shared_spadina_0/nbc_bn_20200929121541.log\", +\"--data-dir=build/data/shared_spadina_0\", +\"--web3-url=wss://goerli.infura.io/ws/v3/809a18497dd74102b5f37d25aae3c85a\", +\"--tcp-port=9000\", +\"--udp-port=9000\", +\"--metrics\", +\"--metrics-port=8008\", +\"--rpc\", +\"--rpc-port=9190\" +]" +... +``` + +This allows us to deduce that the default endpoint is given by: + +``` +--web3-url=wss://goerli.infura.io/ws/v3/809a18497dd74102b5f37d25aae3c85a\" +``` + +## Potential problems + +Because Infura caps the requests per endpoint per day to 100k, and all Nimbus nodes use the same Infura endpoint by default, it can happen that our Infura endpoint is overloaded (i.e the requests on a given day reach the 100k limit). If this happens, all requests to Infura using the default endpoint will fail, which means your node will stop processing new deposits. + +To know if our endpoint has reached its limit for the day, keep your eye out for error messages that look like the following: + +``` +ERR 2020-09-29 14:04:33.313+02:00 Mainchain monitor failure, restarting tid=8941404 +file=mainchain_monitor.nim:812 err="{\"code\":-32005, +\"data\":{\"rate\":{\"allowed_rps\":1, +\"backoff_seconds\":24, +\"current_rps\":22.5}, +\"see\":\"https://infura.io/dashboard\"}, +\"message\":\"daily request count exceeded, request rate limited\"}" +``` + +To get around this problem, we recommend launching the beacon node with your own endpoint. + +## Supplying your own endpoint + + + +> **Note:** In a previous version of the software it wasn't possible to manually override the web3 endpoint when running `make spadina` or `make medalla`. For the instructions below to work, make sure you've updated to the latest version of the software (run `git pull && make update` from the `master` branch of the `nim-beacon-chain` repository). + +### 1. Visit Infura.io + +Go to: + +[https://infura.io/](https://infura.io/) + +and click on `Get Started For Free` + +![](https://i.imgur.com/BtStgup.png) + +### 2. Sign up + +Enter your email address and create a password + +![](https://i.imgur.com/al1OsdR.png) + +### 3. Verify email address +You should have received an email from Infura in your inbox. Open up it up and click on `Confirm Email Address` + +![](https://i.imgur.com/EAD8ZhV.png) + +### 4. Go to dashboard +This will take you to your Infura dashboard (https://infura.io/dashboard/) + +![](https://i.imgur.com/LuNcoYr.png) + +### 5. Create your first project + +Click on the first option (`create your first project`) under `Let's Get Started` + +![](https://i.imgur.com/wBAGhcs.png) + +Choose a name for your project + +![](https://i.imgur.com/yr5vnSo.png) + +You'll be directed to the settings page of your newly created project + +![](https://i.imgur.com/kx3R8XS.png) + +### 6. View Görli endpoints + +In the `KEYS` section, click on the dropdown menu to the right of `ENDPOINTS`, and select `GÖRLI` + +![](https://i.imgur.com/D9186kv.png) + +### 7. Copy the websocket endpoint + +Copy the address that starts with `wss://` + +![](https://i.imgur.com/fZ6Bcjy.png) + +> ⚠️ **Warning:** make sure you've copied the endpoint that starts with`wss` (websocket), and not the `https` endpoint. + + +### 8. Run the beacon node + +Run the beacon node on your favourite testnet, pasting in your websocket endpoint as the input to the `web3-url` option. + +``` +make NODE_PARAMS="--web3-url=wss://goerli.infura.io/ws/v3/83b9d67f81ca401b8f9651441b43f29e" + +``` +> Remember to replace with either `medalla` or `spadina`. + +### 9. Check stats + +Visit your project's stats page to see a summary of your eth1 related activity and method calls + +![](https://i.imgur.com/MZVTHHV.png) + +That's all there is to it :) diff --git a/docs/the_nimbus_book/src/intro.md b/docs/the_nimbus_book/src/intro.md index dc33f09f1..53ae83f18 100644 --- a/docs/the_nimbus_book/src/intro.md +++ b/docs/the_nimbus_book/src/intro.md @@ -31,9 +31,10 @@ In this book, we will cover: 9. [Advanced usage](./advanced.md) for developers 10. How to [setup up a systemd service](./beacon_node_systemd.md) 11. How to [use Nimbus to generate your validator keys](./create_wallet_and_deposit.md) -12. Tips and tricks for windows users (WIP) -13. Common [questions and answers](./faq.md) to satisfy your curiosity -14. How to [contribute](./contribute.md) to this book +12. How to [supply your own Infura endpoint](./infura-guide) +13. Tips and tricks for windows users (WIP) +14. Common [questions and answers](./faq.md) to satisfy your curiosity +15. How to [contribute](./contribute.md) to this book ## Introduction diff --git a/docs/the_nimbus_book/src/medalla-troubleshooting.md b/docs/the_nimbus_book/src/medalla-troubleshooting.md index ea5e4a311..04d8b73b8 100644 --- a/docs/the_nimbus_book/src/medalla-troubleshooting.md +++ b/docs/the_nimbus_book/src/medalla-troubleshooting.md @@ -17,6 +17,7 @@ If you find that `make update` causes the console to hang for too long, try runn >**Note:** rest assured that when you restart the beacon node, the software will resume from where it left off, using the validator keys you have already imported. + ### Starting over The directory that stores the blockchain data of the testnet is `build/data/shared_medalla_0` (if you're connecting to another testnet, replace `medalla` with that testnet's name). Delete this folder to start over (for example, if you started building medalla with the wrong private keys). @@ -78,3 +79,39 @@ make BASE_PORT=9100 medalla (You can replace `9100` with a port of your choosing) +### Mainchain monitor failure + +If you're seeing one or more error messages that look like the following: + +``` +ERR 2020-09-29 14:04:33.313+02:00 Mainchain monitor failure, restarting tid=8941404 +file=mainchain_monitor.nim:812 err="{\"code\":-32005, +\"data\":{\"rate\":{\"allowed_rps\":1, +\"backoff_seconds\":24, +\"current_rps\":22.5}, +\"see\":\"https://infura.io/dashboard\"}, +\"message\":\"daily request count exceeded, request rate limited\"}" +``` + +This means that our Infura endpoint is overloaded (in other words, the requests on a given day have reached the 100k free tier limit). + +You can fix this by passing in your own Infura endpoint. + +To do so, run: + +``` +make NODE_PARAMS="--web3-url=" medalla +``` + +Importantly, make sure you pass in a websocket (`wss`) endpoint, not `https`. If you're not familiar with Infura, we recommend reading through our [Infura guide](./infura-guide) first. + +### Running multiple nodes on the same computer + +If you're running different testnets on the same computer, you'll need to specify a different `NODE_ID` to avoid port conflicts (the default is `NODE_ID=0`). + +For example, to run `medalla` and `spadina` at the same time: + +``` +make medalla NODE_ID=0 # the default +make spadina NODE_ID=1 +``` diff --git a/docs/the_nimbus_book/src/medalla.md b/docs/the_nimbus_book/src/medalla.md index c2370390e..69d9d3c1b 100644 --- a/docs/the_nimbus_book/src/medalla.md +++ b/docs/the_nimbus_book/src/medalla.md @@ -8,7 +8,6 @@ If you generated your signing key using the [eth2 launchpad](https://medalla.lau > If you're an advanced user running Ubuntu, we recommend you check out this [excellent and complementary guide](https://medium.com/@SomerEsat/guide-to-staking-on-ethereum-2-0-ubuntu-medalla-nimbus-5f4b2b0f2d7c). - ## Prerequisites > ⚠️ If this is your first time playing with Nimbus, please make sure you [install our external dependencies](./install.md) first. @@ -63,9 +62,20 @@ INF 2020-08-03 16:24:17.951+02:00 Local validators attached top INF 2020-08-03 16:24:17.958+02:00 Starting beacon node topics="beacnde" tid=11677993 file=beacon_node.nim:875 version="0.5.0 (31b33907)" nim="Nim Compiler Version 1.2.6 [MacOSX: amd64] (bf320ed1)" timeSinceFinalization=81350 head=ebe49843:0 finalizedHead=ebe49843:0 SLOTS_PER_EPOCH=32 SECONDS_PER_SLOT=12 SPEC_VERSION=0.12.2 dataDir=build/data/shared_medalla_0 pcs=start_beacon_node ``` + > **Note:** when you run `make medalla`, the beacon node launches with an Infura endpoint supplied by us. This endpoint is passed through the `web3-url` option (which takes as input the url of the web3 server from which you'd like to observe the eth1 chain). +> +> Because Infura caps the requests per endpoint per day to 100k, and all Nimbus nodes use the same Infura endpoint by default, it can happen that our Infura endpoint is overloaded (i.e the requests on a given day reach the 100k limit). If this happens, all requests to Infura using the default endpoint will fail, which means your node will stop processing new deposits. +> +> To pass in your own Infura endpoint, you'll need to run: +>``` +> make NODE_PARAMS="--web3-url=" medalla +>``` +> Importantly, the endpoint must be a websocket (`wss`) endpoint, not `https`. If you're not familiar with Infura, we recommend reading through our [Infura guide](./infura-guide), first. +> +> P.S. We are well aware that Infura is less than ideal from a decentralisation perspective. As such we are in the process of changing our default to [Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth) (with Infura as a fallback). For some rough notes on how to use Geth with Nimbus, see [here](https://gist.github.com/onqtam/aaf883d46f4dab1311ca9c160df12fe4) (we will be adding more complete instructions very soon). + - -> Tip: to 🎨 on the [graffitwall](https://medalla.beaconcha.in/graffitiwall), pass the graffiti parameter like this: +> **Tip:** to 🎨 on the [graffitwall](https://medalla.beaconcha.in/graffitiwall), pass the graffiti parameter like this: >``` >make NODE_PARAMS="--graffiti=''" medalla diff --git a/docs/the_nimbus_book/src/spadina.md b/docs/the_nimbus_book/src/spadina.md index 495875663..ae43a7d4d 100644 --- a/docs/the_nimbus_book/src/spadina.md +++ b/docs/the_nimbus_book/src/spadina.md @@ -88,7 +88,18 @@ This tutorial assumes basic knowledge of the [command line](https://www.learneno INF 2020-09-27 17:33:56.912+02:00 Eth1 block processed tid=8490483 file=mainchain_monitor.nim:717 block=3423176:0ac7969b totalDeposits=1 ``` - > **Note:** as it stands, Nimbus defaults to using Infura to keep track of eth1 deposits. However we are well aware that Infura is less than ideal from a decentralisation perspective. As such we are in the process of changing the default to [Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth) (with Infura as a fallback). For some rough notes on how to use Geth with Nimbus, see [here](https://gist.github.com/onqtam/aaf883d46f4dab1311ca9c160df12fe4) (we will be adding more complete instructions to this book very soon). + > **Note:** when you run `make spadina`, the beacon node launches with an Infura endpoint supplied by us. This endpoint is passed through the `web3-url` option (which takes as input the url of the web3 server from which you'd like to observe the eth1 chain). +> +> Because Infura caps the requests per endpoint per day to 100k, and all Nimbus nodes use the same Infura endpoint by default, it can happen that our Infura endpoint is overloaded (i.e the requests on a given day reach the 100k limit). If this happens, all requests to Infura using the default endpoint will fail, which means your node will stop processing new deposits. +> +> To pass in your own Infura endpoint, you'll need to run: +>``` +> make NODE_PARAMS="--web3-url=" medalla +>``` +> Importantly, the endpoint must be a websocket (`wss`) endpoint, not `https`. If you're not familiar with Infura, we recommend reading through our [Infura guide](./infura-guide), first. +> +> P.S. We are well aware that Infura is less than ideal from a decentralisation perspective. As such we are in the process of changing our default to [Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth) (with Infura as a fallback). For some rough notes on how to use Geth with Nimbus, see [here](https://gist.github.com/onqtam/aaf883d46f4dab1311ca9c160df12fe4) (we will be adding more complete instructions very soon). + ## 4. Keep an eye on your validator