From bb0a086be31f67b293e557bb84d2626da8645478 Mon Sep 17 00:00:00 2001 From: 0xmiel Date: Wed, 14 Jul 2021 13:14:39 +0200 Subject: [PATCH] book updates (#2721) * cp * rename API to JSON-RPC API * rename api to json-rpc api, add rest api page * remove extra emacs generated file * remove extra emacs generated file --- docs/the_nimbus_book/src/SUMMARY.md | 3 ++- docs/the_nimbus_book/src/api.md | 6 ++--- docs/the_nimbus_book/src/keep-an-eye.md | 2 +- docs/the_nimbus_book/src/preparation.md | 8 ++----- docs/the_nimbus_book/src/rest-api.md | 6 +++++ docs/the_nimbus_book/src/troubleshooting.md | 25 +++++++++++++++++---- 6 files changed, 35 insertions(+), 15 deletions(-) create mode 100644 docs/the_nimbus_book/src/rest-api.md diff --git a/docs/the_nimbus_book/src/SUMMARY.md b/docs/the_nimbus_book/src/SUMMARY.md index cb30aaa45..850d6e842 100644 --- a/docs/the_nimbus_book/src/SUMMARY.md +++ b/docs/the_nimbus_book/src/SUMMARY.md @@ -51,7 +51,8 @@ - [Download Docker images](./docker.md) # Reference -- [API](./api.md) +- [JSON-RPC API](./api.md) +- [REST API](./rest-api.md) - [Help / Command line options](./options.md) - [Advanced migration options](./migration-options.md) - [Troubleshooting](./troubleshooting.md) diff --git a/docs/the_nimbus_book/src/api.md b/docs/the_nimbus_book/src/api.md index 56c3749e5..1043a2162 100644 --- a/docs/the_nimbus_book/src/api.md +++ b/docs/the_nimbus_book/src/api.md @@ -1,8 +1,8 @@ -# APIs +# JSON-RPC API -`nimbus-eth2` exposes a collection of APIs for querying the state of the application at runtime. +`nimbus-eth2` exposes a collection of APIs for querying the state of the application at runtime. -> **Note:** Where applicable, these APIs mimic the [eth2 APIs](https://github.com/ethereum/eth2.0-APIs) with the exception that JSON-RPC is used instead of http rest (the method names, parameters and results are all the same except for the encoding / access method). +Where applicable, these APIs mimic the [eth2 APIs](https://github.com/ethereum/eth2.0-APIs) with the exception that `JSON-RPC` is used instead of [http `REST`](./rest-api.md) (the method names, parameters and results are all the same except for the encoding / access method). ## Introduction diff --git a/docs/the_nimbus_book/src/keep-an-eye.md b/docs/the_nimbus_book/src/keep-an-eye.md index 275176754..a5702c8ab 100644 --- a/docs/the_nimbus_book/src/keep-an-eye.md +++ b/docs/the_nimbus_book/src/keep-an-eye.md @@ -31,7 +31,7 @@ Note that the port number is displayed directly after the IP -- in the above cas ## Keep track of your syncing progress -To keep track of your sync progress, pay attention to the `Slot start` messages in you logs: +To keep track of your sync progress, pay attention to the `Slot start` messages in your logs: ``` INF 2021-05-24 14:53:59.067+02:00 Slot start diff --git a/docs/the_nimbus_book/src/preparation.md b/docs/the_nimbus_book/src/preparation.md index bbc9a35b3..a20d27c8d 100644 --- a/docs/the_nimbus_book/src/preparation.md +++ b/docs/the_nimbus_book/src/preparation.md @@ -7,9 +7,9 @@ Please check that you are running the latest stable [Nimbus software release](ht > **Note:** If you are setting up your client before launch, it is your responsibility to check for any new software releases in the run up to launch. At the minimum you should check the [release page](https://github.com/status-im/nimbus-eth2/releases) weekly. -## More than 20 peers +## More than 50 peers -Please check that your node has at least 15 peers. See [the footer](keep-an-eye.md#keep-track-of-your-syncing-progress) at the bottom of the terminal window for your peer count. +Please check that your node has at least 50 peers. To monitor your peer count, pay attention to the [`Slot start` messages in your logs](keep-an-eye.md#keep-track-of-your-syncing-progress). ## Validator attached @@ -25,10 +25,6 @@ Systemd will also ensure your validator keeps running when you exit your ssh ses For the details on how to do this, see [this page](./beacon-node-systemd.md). -## VPN - -To avoid exposing your validator identity (IP address) to the network, we recommend using a trustworthy VPN such as [protonmail](https://protonmail.com/). While it may result in the occasional missed attestation, we believe the [tradeoff](https://our.status.im/validator-privacy-call-to-action/) is worth it. - ## Ethereum Foundation's Checklist Ad a final check, we recommend you also go through the EF'S [staker checklist](https://launchpad.ethereum.org/checklist). diff --git a/docs/the_nimbus_book/src/rest-api.md b/docs/the_nimbus_book/src/rest-api.md new file mode 100644 index 000000000..317cb9ac6 --- /dev/null +++ b/docs/the_nimbus_book/src/rest-api.md @@ -0,0 +1,6 @@ +# REST API + + +The community has settled on REST as a common interface, as [documented here](https://ethereum.github.io/eth2.0-APIs/#/) -- the `REST` API is an updated version of the [`JSON-RPC` api](./api.md). + +If you're looking to use this more standard API, you can enable it by running the Beacon Node with the `--rest` parameter (note this is currently in Beta). diff --git a/docs/the_nimbus_book/src/troubleshooting.md b/docs/the_nimbus_book/src/troubleshooting.md index ea2b469f1..477d8fe79 100644 --- a/docs/the_nimbus_book/src/troubleshooting.md +++ b/docs/the_nimbus_book/src/troubleshooting.md @@ -7,6 +7,8 @@ As it stands, we are continuously making improvements to both stability and memo > **Note:** While the `stable` branch of the `nimbus-eth2` repository is more stable, the latest updates happen in the `unstable` branch which is (usually) merged into master every week on Tuesday. If you choose to run Nimbus directly from the `unstable` branch, be prepared for instabilities! +### Console hanging for too long on update + To update and restart, run `git pull`, `make update`, followed by `make nimbus_beacon_node`: ``` @@ -21,15 +23,15 @@ 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 +### Starting over after importing wrong keys The directory that stores the blockchain data of the testnet is `build/data/prater_shared_0` (if you're connecting to another testnet, replace `prater` with that testnet's name). If you've imported the wrong keys, and wish to start over, delete this repository. -### Syncing +### Sync problems If you’re experiencing sync problems, we recommend running `make clean-prater` to delete the database and restart your sync (make sure you’ve updated to the latest `master` first though). > **Warning**: `make clean-prater` will erase all of your syncing progress so far, so it should only be used as a last resort -- if your client gets stuck for a long time (because it's unable to find the right chain and/or stay with the same head value) and a normal restart doesn't improve things. -### Pruning the database +### Running out of storage If you're running out of storage, you can [prune](https://blog.ethereum.org/2015/06/26/state-tree-pruning/) the database of unnecessary blocks and states by running: ``` @@ -43,13 +45,28 @@ Options: - `--keepOldStates` (boolean): Keep pre-finalisation states; defaults to `true`. - `--verbose` (boolean): Print a more verbose output to the console; defaults to `false`. -### Low peer counts +### Low peer count If you're experiencing a low peer count, you may be behind a firewall. Try restarting your client and passing `--nat:extip:$EXT_IP_ADDRESS` as an option to `./run-prater-beacon-node.sh`, where `$EXT_IP_ADDRESS` is your real IP. For example, if your real IP address is `35.124.65.104`, you'd run: ``` ./run-prater-beacon-node.sh --nat:extip:35.124.65.104 ``` + +### No peers for topic, skipping publish (logs) + +If you see a message that looks like the following in your logs: + +``` +NOT 2021-07-11 17:17:00.928+00:00 No peers for topic, skipping publish topics="libp2p gossipsub" tid=284547 file=gossipsub.nim:457 peersOnTopic=0 connectedPeers=0 topic=/eth2/b5303f2a/beacon_attestation_0/ssz_snappy +``` + +It could be that your max peer count (`--max-peers`) has been set too low. In order to ensure your attestations are published correctly, we recommend setting `--max-peers` to 60, at the *very least*. + +> Note that Nimbus manages peers slightly differently to other clients (we automatically connect to more peers than we actually use, in order not to have to do costly reconnects). As such, `--max-peers` is set to 160 by default. + +If this doesn't fix the problem, please double check your node is able to [receive incoming connections](./health.md). + ### noCommand does not accept arguments If, on start, you see `The command 'noCommand' does not accept arguments`