feat(website): refactor prover and node running guides and add warning (

#13414)
taikoxyz · Mar 22, 2023 · 72d3d4e · 72d3d4e
1 parent 0d588b1
commit 72d3d4e
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 51 deletions.
diff --git a/packages/website/pages/docs/guides.mdx b/packages/website/pages/docs/guides.mdx
@@ -3,7 +3,8 @@ Here are the testnet guides:
 - 💦 [Receive tokens](/docs/guides/receive-tokens)
 - 🌉 [Use the bridge](/docs/guides/use-the-bridge)
 - 🔀 [Swap tokens](/docs/guides/swap-tokens)
-- 🌐 [Run a node (and prover)](/docs/guides/run-a-node)
+- 🌐 [Run a node](/docs/guides/run-a-node)
+- 🔐 [Enable a prover](/docs/guides/enable-a-prover)
 - 🧙 [Deploy a contract](/docs/guides/deploy-a-contract)
 - 🛠️ [Build a dapp](/docs/guides/build-a-dapp)
 

diff --git a/packages/website/pages/docs/guides/_meta.json b/packages/website/pages/docs/guides/_meta.json
@@ -12,7 +12,10 @@
     "title": "🔀 Swap tokens"
   },
   "run-a-node": {
-    "title": "🌐 Run a node (and prover)"
+    "title": "🌐 Run a node"
+  },
+  "enable-a-prover": {
+    "title": "🔐 Enable a prover"
   },
   "deploy-a-contract": {
     "title": "🧙 Deploy a contract"

diff --git a/packages/website/pages/docs/guides/enable-a-prover.mdx b/packages/website/pages/docs/guides/enable-a-prover.mdx
@@ -0,0 +1,28 @@
+import { Callout, Steps } from "nextra-theme-docs";
+
+<Callout>
+ Only the first prover can get the reward, and others will be rejected by the protocol smart contract. This means the fastest prover will be able to prove the block and earn the reward, **if you have just the minimum hardware outlined in the prerequisited below, it's unlikely you will be able to prove any blocks if there are many other high-performance provers**.
+</Callout>
+
+
+## Prerequisites
+- Must have some ETH on Sepolia (see [receive tokens](/docs/guides/receive-tokens)).
+- Should have at least 8/16 core CPU and 32GB of RAM. (**note: see warning above**)
+
+
+## Steps
+
+<Steps>
+### Set environment variables to enable prover
+Set the following environment variables to enable your node as a prover: 
+    - Set `ENABLE_PROVER` to `true` (replacing the default `false` with `true`). 
+    - Set `L1_PROVER_PRIVATE_KEY` to that of your wallet's private key; it will need some balance on Sepolia to prove blocks (if using MetaMask, follow these directions to [retrieve the private key](https://metamask.zendesk.com/hc/en-us/articles/360015289632-How-to-export-an-account-s-private-key)).
+
+### Verify prover logs
+Verify you have some prover logs:
+    - `💰 Your block proof was accepted` means you are the first prover and receive the reward.
+    - `✅ Valid block proven` just means a proposed block was successfully proved on TaikoL1 (by anyone).
+</Steps>
+
+## Troubleshooting
+Consult [Run a node - Troubleshooting](/docs/guides/run-a-node#troubleshooting) for common issues.
diff --git a/packages/website/pages/docs/guides/run-a-node.mdx b/packages/website/pages/docs/guides/run-a-node.mdx
@@ -11,9 +11,6 @@ This guide will walk you through the process of operating a Taiko node via [simp
 - [Docker](https://docs.docker.com/engine/install/) is installed and **running**.
 - [Git](https://github.com/git-guides/install-git/) is installed.
 - Consult the [Geth minimum hardware requirements](https://github.com/ethereum/go-ethereum#hardware-requirements), with the exception of 1TB of free space (you won't need much, even ~50GB should suffice).
-- If running a prover:
-  - Must have some ETH on Sepolia (see [receive tokens](/docs/guides/receive-tokens)).
-  - Should have 8/16 core CPU and 32GB of RAM.
 
 ## Steps
 
@@ -32,7 +29,7 @@ First, copy the `.env.sample` to a new file `.env`:
 cp .env.sample .env
 ```
 
-And open the `.env` file in your preferred text editor:
+Next, open the `.env` file in your preferred text editor:
 
 {" "}
 
@@ -53,27 +50,12 @@ Finally, set the following environment variables:
 
 ### Enable your node as a prover (optional)
 
-<Callout>
- Only the first prover can get the reward, and others will be rejected by the protocol smart contract (with a custom error: L1_ID() or L1_ALREADY_PROVEN()). `💰 Your block proof was accepted` means you are the first prover and receive the reward. `✅ Valid block proven` means a proposed block was successfully proved on TaikoL1.
-</Callout>
-<Callout>
-  Keep in mind the additional prover requirements laid out in the prerequisites.
-</Callout>
-
-Set the following environment variables to enable your node as a prover: 
-  - Set `ENABLE_PROVER` to `true` (replacing the default `false` with `true`). 
-  - Set `L1_PROVER_PRIVATE_KEY` to that of your wallet's private key; it will need some balance on Sepolia to prove blocks (if using MetaMask, follow these directions to [retrieve the private key](https://metamask.zendesk.com/hc/en-us/articles/360015289632-How-to-export-an-account-s-private-key)).
+See [enable a prover](/docs/guide/enable-a-prover) for more information.
 
 ### Start a node
 
 <Callout>
-  If this is the first time starting the node, it may take some time to
-  synchronize from the genesis block. You can monitor this progress through
-  logs, or in the local grafana dashboard and see the latest L2 chain status in
-  the [Taiko alpha-2 block explorer](https://explorer.a2.taiko.xyz/).
-</Callout>
-<Callout>
-  If you ran an alpha-1 testnet node make sure to first run a `docker compose down -v` to remove the old volumes.
+  If you ran an alpha-1 testnet node make sure to first run a `docker compose down -v` to remove the old volumes. Also, it may take some time to synchronize from the genesis block. You can monitor this progress through logs, or in the local grafana dashboard and see the latest L2 chain status in the [Taiko alpha-2 block explorer](https://explorer.a2.taiko.xyz/).
 </Callout>
 
 Make sure Docker is running and then run the following command to start the node. If you want to run it in the background, please add the `-d` flag (`docker compose up -d`).
@@ -96,6 +78,23 @@ This command shuts down the node, but will keep all volumes, so next time you re
 docker compose down
 ```
 
+### Remove a node
+
+These commands will completely remove the node by removing all volumes used by each container:
+
+```sh
+docker compose down -v
+rm -f .env
+```
+
+### Update a node
+
+Update the `simple-taiko-node` Docker images:
+
+```sh
+docker compose pull
+```
+
 ### View the node's logs
 
 To view the Docker logs, the following commands can be ran:
@@ -140,40 +139,31 @@ A [Grafana](https://grafana.com/) dashboard with a [Prometheus](https://promethe
 
 ## Troubleshooting
 
-**Remove a node**
+### Node warning logs
+You can ignore any WARN logs.
 
-```sh
-docker compose down -v
-rm -f .env
-```
-
-These commands completely remove the node by removing all volumes used by each container. You should try this first.
+### Node error logs 
+#### `Fatal: Failed to register the Ethereum service: database contains incompatible genesis`
+Try to remove the node with `docker compose down -v` and then try again. 
 
-**Error Messages**
+#### `Unhandled trie error: missing trie node`
+You can ignore this error, it doesn't affect you and goes away after a while.
 
-When running a node it's normal for the node to run into errors. This doesn't mean that your node isn't working correctly, as most of the time the node resolves the errors. Some errors are there for the developers to easily debug if something goes wrong, but can be ignored by users. The following table explains some error messages a bit more.
+#### `Block batch iterator callback error; error="failed to fetch L2 parent block: not found`
+You can ignore this error.
 
-| Error message                                                                                                                 | Explanation                                                                                                                                                 |
-| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Fatal: Failed to register the Ethereum service: database contains incompatible genesis`                                      | Try to remove the node with `docker compose down -v` and then try again.                                                                                    |
-| `Unhandled trie error: missing trie node`                                                                                     | You can ignore this error, it doesn't affect you and goes away after a while.                                                                               |
-| `Block batch iterator callback error` <br></br> `error="failed to fetch L2 parent block: not found`                           | You can ignore this error.                                                                                                                                  |
-| `Error starting ...: listen tcp4 0.0.0.0:{port} bind: address already in use`                                                 | The port is already in use by another service. You can either shut down the other program or change the port in the .env file.                              |
-| `error parsing HTTP 403 response body: invalid character '<' looking for beginning of value`                                  | Your IP address is being geo-blocked due to sanctions lists. If you're affected, try changing hosting locations or utilize a VPN to change your IP address. |
-| `ERROR: The Compose file './docker-compose.yml' is invalid because: Unsupported config option for some_serivce 'pull_policy'` | Your docker installation is out of date. You need to update your docker compose installation: https://docs.docker.com/compose/install/.                     |
-| `daemon docker is not running` <br></br> `Cannot connect to the Docker daemon`                                                | Need to start the Docker before running the commands.                                                                                                       |
+#### `Error starting ...: listen tcp4 0.0.0.0:{port} bind: address already in use`
+The port is already in use by another service. You can either shut down the other program or change the port in the .env file.
 
-**Unclean Shutdown**
+#### `error parsing HTTP 403 response body: invalid character '<' looking for beginning of value`
+Your IP address is being geo-blocked due to sanctions lists. If you're affected, try changing hosting locations or utilize a VPN to change your IP address.
 
-When running a Node, you will need to ensure a clean shutdown by running the command `docker compose down`
+#### `ERROR: The Compose file './docker-compose.yml' is invalid because: Unsupported config option for some_serivce 'pull_policy'`
+Your docker installation is out of date. You need to update your docker compose installation: https://docs.docker.com/compose/install/. 
 
-If the node is being ran with `docker compose up` (without the `-d` flag) and the logs are displaying in the terminal, then Press CTRL+C to allow Docker to clean up the resources.
+#### `daemon docker is not running` <br></br> `Cannot connect to the Docker daemon` 
+Need to start the Docker before running the commands. 
 
-Please try running the following:
+#### `database contains incompatible genesis`
+If you ran an alpha-1 testnet node make sure to first run a docker compose down -v to remove the old volumes.
 
-```sh
-docker compose down -v
-git pull
-docker compose pull
-docker compose up -d
-```