Mainnet support (#57)

Closes:
https://linear.app/thesis-co/issue/TET-607/mainnet-support-in-v-kit

Here we adjust all V-Kit components and documentation to support the
incoming Mezo Mainnet. I recommend reviewing commit-by-commit to better
understand all the changes.

Author: dimpar

README.md

@@ -6,7 +6,10 @@
 ## Overview
 
 This repository contains the Validator Kit for Mezo chain. The Validator Kit is
-a collection of tools and documentation to help you run a validator node on Mezo chain.
+a collection of tools and documentation to help you run a Mezo chain node.
+
+Although the Validator Kit is primarily designed for validator nodes, it can be
+used to run [non-validator nodes](#non-validator-nodes) as well.
 
 ### Main components
 
@@ -27,13 +30,10 @@ As a validator you can choose between the above options to run your validator no
 
 ### Auxiliary components
 
-Moreover, there are several auxiliary components of the Validator Kit that
-can help you with various operational tasks:
+Moreover, there are auxiliary components of the Validator Kit that can help you with various 
+operational tasks:
 
-1. [`tools`](./tools): provides a collection of Hardhat tasks designed to simplify
-   interactions with the blockchain’s Proof-of-Authority (PoA) based network.
-   For example, you can submit your application to become one of the PoA validators.
-2. [`docker-monitoring`](./docker-monitoring): contains files to run a monitoring
+1. [`docker-monitoring`](./docker-monitoring): contains files to run a monitoring
    stack for your validator node using Docker. This is an optional way to monitor
    your validator node. The monitoring stack is dedicated to the `docker` setup.
    You can use it for the `native` variant after some adjustments (not covered in this repo).
@@ -42,15 +42,30 @@ can help you with various operational tasks:
 
 Regardless of the chosen way to run a validator node, you may want to use 
 pre-built artifacts provided by the Mezo team. These include Docker images and
-binary files for the `mezod` node software.
+binary files for the `mezod` node software. Alternatively, you can build the
+necessary artifacts yourself.
+
+### Stable releases (Mainnet)
+
+Stable releases are ready to be rolled out on Mainnet nodes. You can find relevant
+artifacts in the following locations (substitute `VERSION` with the desired 
+stable version, e.g. `v1.0.0`):
+
+- Docker image (DockerHub): `mezo/mezod:VERSION`
+- Binary (amd64): `https://github.com/mezo-org/mezod/releases/download/VERSION/linux-amd64.tar.gz`
+
+### Candidate releases (Testnet)
+
+>[!WARNING]
+> Candidate releases are **NOT READY** for Mainnet use.
+
+Candidate releases are intended to be rolled out on Testnet nodes. You can find
+relevant artifacts in the following locations (substitute `VERSION` with the 
+desired candidate version, e.g. `v1.0.0-rc0`):
 
-You can find the mentioned artifacts in the following locations (substitute 
-`VERSION` with the desired version, e.g. `v0.5.0-rc0`):
 - Docker image: `us-central1-docker.pkg.dev/mezo-test-420708/mezo-staging-docker-public/mezod:VERSION`
 - Binary (amd64): `https://artifactregistry.googleapis.com/download/v1/projects/mezo-test-420708/locations/us-central1/repositories/mezo-staging-binary-public/files/mezod:VERSION:linux-amd64.tar.gz:download?alt=media`
 
-Alternatively, you can build the necessary artifacts yourself.
-
 ## Node synchronization
 
 There are two ways to synchronize your node with the Mezo blockchain.
@@ -67,15 +82,20 @@ a long time depending on your network connection and the number of blocks in
 the network. Moreover, you need to start with the initial version
 of `mezod` and upgrade along the way to handle on-chain upgrades properly.
 
-Version ordering for Mezo Matsnet testnet:
+#### Version ordering for Mezo Matsnet testnet
+
 - `v0.2.0-rc3`: initial version from genesis to block 1093500
 - `v0.3.0-rc3`: from block 1093500 to block 1745000
 - `v0.4.0-rc1`: from block 1745000 to block 2213000
 - `v0.5.0-rc1`: from block 2213000 to block 2563000
 - `v0.6.0-rc2`: from block 2563000 to block 3078794
 - `v0.7.0-rc0`: from block 3078794 to block 3569000
 - `v1.0.0-rc0`: from block 3569000 to block 3712500
-- `v1.0.0-rc*`: from block 3712500 to the current chain tip (pick the latest `-rc*`)
+- `v1.0.0-rc1`: from block 3712500 to the current chain tip
+
+#### Version ordering for Mezo Mainnet
+
+- `v1.*.*`: from genesis to the current chain tip (pick the latest minor/patch version)
 
 ### State sync from snapshot
 
@@ -90,32 +110,70 @@ apply the snapshot to get the latest state of the chain. The downside here
 is the fact that your node won't have the chain history prior to the snapshot.
 Moreover, you need to trust the source of the snapshot.
 
-Mezo team provides snapshots for Mezo Matsnet testnet. Please refer to
-[this runbook](./manual/README.md#State-sync-from-snapshot)
-for details. Alternatively, you can ask trusted community members for a snapshot.
+Mezo team provides snapshots only for Mezo Matsnet testnet. Mezo team **DOES NOT** 
+provide snapshots for Mezo Mainnet. In any case, you can ask trusted community members
+for a snapshot.
+
+Please refer to [this runbook](./manual/README.md#State-sync-from-snapshot)
+to learn how to sync your node from a snapshot in practice.
 
 ## PoA application submission
 
 The final step to becoming a PoA validator is submitting your application to the Mezo
-team. Before you proceed, ensure you have sufficient funds in your validator's node
-address. You have several ways to submit your application:
-
-1. Using a CLI command exposed by `mezod` (recommended):
-   ```bash
-   mezod --home=<mezod_home_path> poa submit-application <key_name>
-   ```
-   where `key_name` denotes the private key from your node's keyring that
-   corresponds to the aforementioned validator's node address.
-   
-2. Alternatively, you can run the `submit-application.sh` script from the
-   [tools/hardhat](tools/hardhat/README.md#how-to-submit-an-application-to-validator-pool) toolbox.
-
-Both options are valid, and you can choose either. Once you submit your application,
-the Mezo team will verify your node status and approve your application if everything
-is in order. Please provide your public IP, your node address, and any custom port
-settings. If you wish to close the CometBFT RPC port (note that the CometBFT 
-P2P port must remain open), please whitelist the following IP 
-address: `34.57.120.151` so that we can verify your status.
+team. Before you proceed, ensure you have sufficient funds on your validator's node
+address. You can submit your application using a CLI command exposed by `mezod`:
+
+```bash
+mezod --home=<mezod_home_path> poa submit-application <key_name>
+```
+where `key_name` denotes the private key from your node's keyring that corresponds to 
+the aforementioned validator's node address.
+
+Once you submit your application, the Mezo team will verify your node status and approve 
+your application if everything is in order. Please provide your public IP, your node address, 
+and any custom port settings. If you wish to close the CometBFT RPC port (note that the 
+CometBFT P2P port must remain open), please whitelist the following IP address: `34.57.120.151` 
+so that we can verify your status.
+
+## Non-validator nodes
+
+### Network seed nodes
+
+If you want to run a seed node to help network peer discovery, follow the configuration
+process as for a validator node but:
+- Do not submit an application to PoA.
+- Set the `p2p.seed_mode` parameter in your node's `config.toml` file to `true`.
+
+Ensure your CometBFT P2P port is open and accessible from the outside.
+This is `26656` by default, but can be changed using the `p2p.laddr` or 
+`p2p.external_address` parameters in the `config.toml` file.
+
+### RPC node
+
+To run an RPC node (serving both EVM JSON-RPC and CometBFT RPC), follow the configuration
+process as for a validator node but:
+- Do not submit an application to PoA.
+- If you want to run an archiving node (i.e. with full history of the chain),
+  set the `pruning` parameter in your node's `app.toml` file to `nothing`.
+
+Ensure the following ports are open and accessible from the outside:
+- EVM JSON-RPC HTTP port: `8545` by default. Can be changed using the 
+  `json-rpc.address` parameter in the `app.toml` file.
+- EVM JSON-RPC WebSocket port: `8546` by default. Can be changed using the 
+  `json-rpc.ws-address` parameter in the `app.toml` file.
+- CometBFT RPC port: `26657` by default. Can be changed using the `rpc.laddr`
+  parameter in the `config.toml` file.
+
+## Hardware requirements
+
+Here are the minimum recommended hardware requirements for running different 
+types of Mezo chain nodes:
+
+| Node Type | vCPU | RAM   | Disk    |
+|-----------|------|-------|---------|
+| Validator | 4    | 16 GB | 256 GB  |
+| RPC       | 8    | 32 GB | 512 GB  |
+| Seed      | 2    | 8 GB  | 128 GB  |
 
 ## Acknowledgements
 

docker/README.md

@@ -4,8 +4,14 @@
 
 The following instruction will guide you through the process of configuring
 and running a validator node. Before continuing, decide which network you want
-to join. There are two options: `testnet` and `mainnet`. The following
-instruction will use `testnet` as an example.
+to join. There are two options: `testnet` and `mainnet`. 
+
+> [!IMPORTANT]
+> The following instruction uses `mainnet` environment as an example. 
+> For `testnet`, follow the same steps but use `testnet.env` 
+> (from the `testnet.env.example` template) as your configuration file and
+> explicitly set the `NETWORK=testnet` environment variable while running 
+> the `v-kit.sh` script.
 
 > [!NOTE]
 > Run `./v-kit.sh` (without arguments) to see the list of available commands.
@@ -14,7 +20,7 @@ instruction will use `testnet` as an example.
 
 ```mermaid
 sequenceDiagram
-  participant testnet.env
+  participant mainnet.env
   participant v-kit.sh
   box Docker Compose
     participant compose.yaml
@@ -23,8 +29,8 @@ sequenceDiagram
     participant mezod-and-sidecars as Service 'mezod' with sidecars
   end
 
-  Note over testnet.env: (USER) Adjust the configuration
-  v-kit.sh -->> testnet.env: load
+  Note over mainnet.env: (USER) Adjust the configuration
+  v-kit.sh -->> mainnet.env: load
 
   critical One-time setup
     v-kit.sh ->> compose.yaml: v-kit.sh init-keyring
@@ -46,13 +52,13 @@ sequenceDiagram
 
 ### 1. Prepare configuration file
 
-1. Copy the `testnet.env.example` to `testnet.env`:
-
+#### Copy the `mainnet.env.example` to `mainnet.env`
+   
 ```shell
-cp testnet.env.example testnet.env
+cp mainnet.env.example mainnet.env
 ```
 
-2. Edit the `testnet.env` file:
+#### Edit the `mainnet.env` file
 
 * `NETWORK` - the network you want to join (`testnet` or `mainnet`)
 * `DOCKER_IMAGE` - the latest version of mezod image
@@ -107,11 +113,11 @@ The URL must be WebSocket, i.e. start with `wss://` (recommended) or `ws://`.
 ./v-kit.sh init-genval
 ```
 
-### 3. Submit joining request
+### 3. Submit PoA application
 
-TBD
+See [PoA application submission](../README.md#poa-application-submission) in the root README for details.
 
-### 5. Run the validator
+### 4. Run the validator
 
 ```shell
 ./v-kit.sh start
@@ -133,7 +139,8 @@ TBD
 
 ### Edit the configuration manually
 
-Keep in mind that some parts of the configuration are managed by the [entrypoint.sh](./entrypoint.sh) script
+Keep in mind that some parts of the configuration are managed by the 
+[entrypoint.sh](https://github.com/mezo-org/mezod/blob/main/entrypoint.sh) script
 within the container. These parts will be overwritten when the container is started.
 
 ```shell

docker/compose.yaml

@@ -49,6 +49,7 @@ services:
       - ethereum-sidecar
       - --log_format=json
       - --ethereum-sidecar.server.ethereum-node-address=${MEZOD_ETHEREUM_SIDECAR_SERVER_ETHEREUM_NODE_ADDRESS}
+      - --ethereum-sidecar.server.network=${MEZOD_ETHEREUM_SIDECAR_SERVER_NETWORK}
     restart: always
     expose:
       - 7500

docker/mainnet.env.example

@@ -0,0 +1,43 @@
+#
+# Docker
+#
+NETWORK=mainnet
+DOCKER_IMAGE="<change me>" # mezo/mezod:VERSION
+#DOCKER_LOG_DRIVER="json-file" # uncomment when running on MacOS
+
+#
+# Network
+#
+PUBLIC_IP="<change me>"
+
+#
+# Storage
+#
+LOCAL_BIND_PATH=/var/mezod
+
+#
+# Keyring
+#
+KEYRING_NAME="localkey"
+KEYRING_PASSWORD="<change me>" # Can be generated. Check out README.md
+KEYRING_MNEMONIC="<change me>" # Can be generated. Check out README.md
+
+#
+# Mezod
+#
+MEZOD_CHAIN_ID="mezo_31612-1"
+MEZOD_HOME="/var/mezod"
+MEZOD_MONIKER="<change me>"
+MEZOD_ETHEREUM_SIDECAR_SERVER_ETHEREUM_NODE_ADDRESS="<change me>" # Ethereum Mainnet WS RPC
+MEZOD_ETHEREUM_SIDECAR_SERVER_NETWORK="mainnet"
+MEZOD_LOG_LEVEL=info
+MEZOD_LOG_FORMAT=json # json|plain
+MEZOD_PORT_P2P=26656 # Default. It should be changed in case of a custom setup
+
+# Custom configuration
+#LOCAL_CUSTOM_CONF_APP_TOML="file/path"
+#MEZOD_CUSTOM_CONF_APP_TOML=/config/app.toml.txt
+#LOCAL_CUSTOM_CONF_CLIENT_TOML="file/path"
+#MEZOD_CUSTOM_CONF_CLIENT_TOML=/config/client.toml.txt
+#LOCAL_CUSTOM_CONF_CONFIG_TOML="file/path"
+#MEZOD_CUSTOM_CONF_CONFIG_TOML=/config/config.toml.txt

docker/testnet.env.example

@@ -29,6 +29,7 @@ MEZOD_CHAIN_ID="mezo_31611-1"
 MEZOD_HOME="/var/mezod"
 MEZOD_MONIKER="<change me>"
 MEZOD_ETHEREUM_SIDECAR_SERVER_ETHEREUM_NODE_ADDRESS="<change me>"
+MEZOD_ETHEREUM_SIDECAR_SERVER_NETWORK="sepolia"
 MEZOD_LOG_LEVEL=info
 MEZOD_LOG_FORMAT=json # json|plain
 MEZOD_PORT_P2P=26656 # Default. It should be changed in case of a custom setup

docker/v-kit.sh

@@ -8,7 +8,7 @@ set -o pipefail # Exit on pipe error
 ################################################################################
 # Variables
 ################################################################################
-NETWORK="${NETWORK:-testnet}"
+NETWORK="${NETWORK:-mainnet}"
 DOCKER_COMPOSE_CMD="docker compose --env-file ${NETWORK}.env"
 
 # Load NETWORK.env

helm-chart/mezod/Chart.yaml

@@ -1,4 +1,4 @@
 apiVersion: v2
 name: mezod
-version: 1.6.0
-appVersion: v1.0.0-rc1
+version: 2.0.0
+appVersion: v1.0.0

helm-chart/mezod/README.md

@@ -1,7 +1,6 @@
 # Helm chart for Mezod
 
-The chart contains configuration for testnet on Sepolia so far.
-Eventually, it will be updated to support mainnet by default.
+The chart is configured for mainnet by default.
 
 ## Pre-requisites
 
@@ -37,18 +36,18 @@ kubectl -n <NAMESPACE> create secret generic <SECRET_NAME> \
 
 # mezod
 
-![Version: 1.6.0](https://img.shields.io/badge/Version-1.6.0-informational?style=flat-square) ![AppVersion: v1.0.0-rc1](https://img.shields.io/badge/AppVersion-v1.0.0--rc1-informational?style=flat-square)
+![Version: 2.0.0](https://img.shields.io/badge/Version-2.0.0-informational?style=flat-square) ![AppVersion: v1.0.0](https://img.shields.io/badge/AppVersion-v1.0.0-informational?style=flat-square)
 
 ## Values
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| image | string | `"us-central1-docker.pkg.dev/mezo-test-420708/mezo-staging-docker-public/mezod"` |  |
-| tag | string | `"v1.0.0-rc1"` |  |
+| image | string | `"mezo/mezod"` |  |
+| tag | string | `"v1.0.0"` |  |
 | imagePullPolicy | string | `"Always"` |  |
-| env.NETWORK | string | `"testnet"` | Select the network to connect to |
+| env.NETWORK | string | `"mainnet"` | Select the network to connect to (mainnet or testnet) |
 | env.PUBLIC_IP | string | `"CHANGE_ME"` | Set public IP address of the validator |
-| env.MEZOD_CHAIN_ID | string | `"mezo_31611-1"` | Set the chain ID (mezo_31611-1 is the testnet) |
+| env.MEZOD_CHAIN_ID | string | `"mezo_31612-1"` | Set the chain ID (mezo_31612-1 is mainnet, mezo_31611-1 is testnet) |
 | env.MEZOD_HOME | string | `"/var/mezod"` |  |
 | env.MEZOD_MONIKER | string | `"CHANGE_ME"` | Set the moniker (name of the validator) |
 | env.MEZOD_ETHEREUM_SIDECAR_SERVER | string | `"localhost:7500"` |  |

helm-chart/mezod/README.md.gotmpl

@@ -1,7 +1,6 @@
 # Helm chart for Mezod
 
-The chart contains configuration for testnet on Sepolia so far.
-Eventually, it will be updated to support mainnet by default.
+The chart is configured for mainnet by default.
 
 ## Pre-requisites
 

helm-chart/mezod/templates/statefulset.yaml

@@ -136,6 +136,11 @@ spec:
             - --home=/tmp/dummy-data
             - --log_format=json
             - --ethereum-sidecar.server.ethereum-node-address=$(ETHEREUM_ENDPOINT)
+            {{- if eq .Values.env.NETWORK "mainnet" }}
+            - --ethereum-sidecar.server.network=mainnet
+            {{- else if eq .Values.env.NETWORK "testnet" }}
+            - --ethereum-sidecar.server.network=sepolia
+            {{- end }}
           env:
             - name: ETHEREUM_ENDPOINT
               valueFrom: