├── .env.example ├── README.md ├── config ├── monitoring │ ├── grafana.env │ ├── influxdb.env │ └── node_exporter.sh ├── superseed-mainnet │ ├── genesis.json │ └── rollup.json └── superseed-sepolia │ ├── genesis.json │ └── rollup.json ├── docker-compose.yml ├── docker ├── grafana │ ├── dashboards │ │ └── simple_node_dashboard.json │ └── provisioning │ │ ├── dashboards │ │ └── all.yml │ │ └── datasources │ │ └── all.yml └── prometheus │ └── prometheus.yml ├── envs ├── superseed-mainnet │ ├── op-geth.env │ └── op-node.env └── superseed-sepolia │ ├── op-geth.env │ └── op-node.env ├── logo.png └── scripts ├── superseed-mainnet ├── start-geth.sh ├── start-op-geth.sh └── start-op-node.sh └── superseed-sepolia ├── start-geth.sh ├── start-op-geth.sh └── start-op-node.sh /.env.example: -------------------------------------------------------------------------------- 1 | # Network to run the node on ("superseed-mainnet" or "superseed-sepolia") 2 | NETWORK_NAME="superseed-sepolia" 3 | OP_GETH_VERSION="v1.101503.2" 4 | OP_NODE_VERSION="v1.13.0" 5 | #NETWORK_NAME="superseed-mainnet" 6 | #OP_GETH_VERSION="v1.101511.0" 7 | #OP_NODE_VERSION="v1.13.3" 8 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Superseed](logo.png) 2 | 3 | # Superseed node 4 | 5 | Superseed is an Ethereum Layer 2 that rewards those who DeFi. It's built on Optimism's open-source [OP Stack](https://stack.optimism.io/). 6 | 7 | > Forked and customized from https://github.com/smartcontracts/simple-optimism-node 8 | 9 | A simple docker compose script for launching full / archive node for the Superseed chain. 10 | 11 | ## Recommended Hardware 12 | 13 | ### Mainnet 14 | 15 | - 8GB+ RAM 16 | - 500 GB SSD (NVME Recommended) 17 | - 100mb/s+ Download 18 | 19 | ### Testnet 20 | 21 | - 8GB+ RAM 22 | - 500 GB SSD (NVME Recommended) 23 | - 100mb/s+ Download 24 | 25 | > Note: Please keep in mind if you are going to run also Ethereum node locally (EL+CL layers), these system requirements will significantly grow! 26 | 27 | ## Installation and Configuration 28 | 29 | ### Install docker and docker compose 30 | 31 | > Note: If you're not logged in as root, you'll need to log out and log in again after installation to complete the docker installation. This command installs docker and docker compose for Ubuntu. For windows and mac desktop or laptop, please use Docker Desktop. For other OS, please find instructions in Google. 32 | 33 | 34 | ```sh 35 | # Update and upgrade packages 36 | sudo apt-get update 37 | sudo apt-get upgrade -y 38 | 39 | ### Docker and docker compose prerequisites 40 | sudo apt-get install -y curl 41 | sudo apt-get install -y gnupg 42 | sudo apt-get install -y ca-certificates 43 | sudo apt-get install -y lsb-release 44 | 45 | ### Download the docker gpg file to Ubuntu 46 | sudo mkdir -p /etc/apt/keyrings 47 | curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg 48 | 49 | ### Add Docker and docker compose support to the Ubuntu's packages list 50 | echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null 51 | 52 | sudo apt-get update 53 | 54 | ### Install docker and docker compose on Ubuntu 55 | sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin 56 | 57 | sudo usermod -aG docker $(whoami) 58 | 59 | ### Verify the Docker and docker compose install on Ubuntu 60 | sudo docker run hello-world 61 | ``` 62 | 63 | (For non-root user) After logged out and logged back in, test if docker is working by running. 64 | 65 | ```sh 66 | docker ps 67 | ``` 68 | 69 | It should returns an empty container list without having any error. Otherwise, restart your machine if there are errors. 70 | 71 | ### Clone the Repository 72 | 73 | ```sh 74 | git clone https://github.com/superseed-xyz/node 75 | cd node 76 | ``` 77 | 78 | ### Copy .env.example to .env 79 | 80 | Make a copy of `.env.example` named `.env`. 81 | 82 | ```sh 83 | cp .env.example .env 84 | ``` 85 | 86 | Open `.env` with your editor of choice 87 | 88 | ### Mandatory configurations 89 | 90 | - **NETWORK_NAME** - Choose which Optimism network layer you want to operate on: 91 | - `superseed-sepolia` - Superseed Sepolia (Testnet) 92 | - `superseed-mainnet` - Superseed (Mainnet) 93 | - **NODE_TYPE** - Choose the type of node you want to run: 94 | - `full` (Full node) - A Full node contains a few recent blocks without historical states. 95 | - `archive` (Archive node) - An Archive node stores the complete history of the blockchain, including historical states. 96 | - **OP_NODE\_\_RPC_ENDPOINT** - Specify the endpoint for the RPC of Layer 1 (e.g., Ethereum mainnet). For instance, you can use the free plan of Quicknode for the Ethereum mainnet. 97 | - **OP_NODE\_\_L1_BEACON** - Specify the beacon endpoint of Layer 1. You can use [QuickNode for the beacon endpoint](https://www.quicknode.com). For example: https://xxx-xxx-xxx.quiknode.pro/db55a3908ba7e4e5756319ffd71ec270b09a7dce 98 | - **OP_NODE\_\_RPC_TYPE** - Specify the service provider for the RPC endpoint you've chosen in the previous step. The available options are: 99 | - `alchemy` - Alchemy 100 | - `quicknode` - Quicknode (ETH only) 101 | - `erigon` - Erigon 102 | - `basic` - Other providers 103 | 104 | 105 | ### Snapshots 106 | 107 | For faster synchronization you can make use of the following snapshots: 108 | 109 | 110 | **Mainnet**: https://storage.googleapis.com/conduit-networks-snapshots/superseed-mainnet-0/latest.tar 111 | 112 | **Testnet**: https://storage.googleapis.com/conduit-networks-snapshots/sepolia-superseed-826s35710w/latest.tar 113 | 114 | 115 | 116 | ### Optional configurations 117 | 118 | - **OP_GETH\_\_SYNCMODE** - Specify sync mode for the execution client 119 | - Unspecified - Use default snap sync for full node and full sync for archive node 120 | - `snap` - Snap Sync (Default) 121 | - `full` - Full Sync (For archive node, not recommended for full node) 122 | - **IMAGE_TAG\_\_[...]** - Use custom docker image for specified components. 123 | - **PORT\_\_[...]** - Use custom port for specified components. 124 | 125 | ## Operating the Node 126 | 127 | ### Start 128 | 129 | ```sh 130 | docker compose up -d --build 131 | ``` 132 | 133 | Will start the node in a detached shell (`-d`), meaning the node will continue to run in the background. We recommended to add `--build` to make sure that latest changes are being applied. 134 | 135 | > Note: If you want to start the node from scratch, you will need to first initialise the op-geth database, as described in the `start-op-geth.sh` file. This can be skipped if you use a snapshot. 136 | 137 | ```sh 138 | exec geth init --datadir="/op-data/" --state.scheme="hash" /config/${NETWORK_NAME}/genesis.json 139 | ``` 140 | 141 | ### View logs 142 | 143 | ```sh 144 | docker compose logs -f --tail 10 145 | ``` 146 | 147 | To view logs of all containers. 148 | 149 | ```sh 150 | docker compose logs -f --tail 10 151 | ``` 152 | 153 | To view logs for a specific container. Most commonly used `` are: 154 | 155 | - op-geth 156 | - op-node 157 | - geth 158 | - prysm 159 | 160 | ### Stop 161 | 162 | ```sh 163 | docker compose down 164 | ``` 165 | 166 | Will shut down the node without wiping any volumes. 167 | You can safely run this command and then restart the node again. 168 | 169 | ### Restart 170 | 171 | ```sh 172 | docker compose restart 173 | ``` 174 | 175 | Will restart the node safely with minimal downtime but without upgrading the node. 176 | 177 | ### Upgrade 178 | 179 | Pull the latest updates from GitHub, and Docker Hub and rebuild the container. 180 | 181 | ```sh 182 | git pull 183 | docker compose pull 184 | docker compose up -d --build 185 | ``` 186 | 187 | Will upgrade your node with minimal downtime. 188 | 189 | ### Wipe [DANGER] 190 | 191 | ```sh 192 | docker compose down -v 193 | ``` 194 | 195 | Will shut down the node and WIPE ALL DATA. Proceed with caution! 196 | 197 | ## Monitoring Guidelines 198 | 199 | In order to maintain a healthy node that passes the Integrity Protocol's checks, you should have a monitoring system in place. Blockchain nodes usually offer metrics regarding the node's behaviour and health - a popular way to offer these metrics is Prometheus-like metrics. The most popular monitoring stack, which is also open source, consists of: 200 | 201 | * Prometheus - scrapes and stores metrics as time series data (blockchain nodes cand send the metrics to it); 202 | * Grafana - allows querying, visualization and alerting based on metrics (can use Prometheus as a data source); 203 | * Alertmanager - handles alerting (can use Prometheus metrics as data for creating alerts); 204 | * Node Exporter - exposes hardware and kernel-related metrics (can send the metrics to Prometheus). 205 | 206 | We will assume that Prometheus/Grafana/Alertmanager are already installed (we will provide a detailed guide of how to set up monitoring and alerting with the Prometheus + Grafana stack at a later time; for now, if you do not have the stack already installed, please follow this official basic guide [here](https://grafana.com/docs/grafana/latest/getting-started/get-started-grafana-prometheus/)). 207 | 208 | We recommend installing the Node Exporter utility since it offers valuable information regarding CPU, RAM & storage. This way, you will be able to monitor possible hardware bottlenecks, or to check if your node is underutilized - you could use these valuable insights to make decisions regarding scaling up/down the allocated hardware resources. 209 | 210 | In the config folder of the repo you can find a script that installs Node Exporter as a system service. 211 | 212 | ### Estimate remaining sync time 213 | 214 | Run following `curl` to estimate remaining sync time. 215 | This will show the time until sync is completed. 216 | 217 | ``` 218 | echo "Latest synced block: $(curl -s -d '{"id":0,"jsonrpc":"2.0","method":"optimism_syncStatus"}' -H "Content-Type: application/json" http://localhost:9545 | jq -r '.result.unsafe_l2.number') , behind by: $(( ( $(date +%s) - $(curl -s -d '{ 219 | "id":0,"jsonrpc":"2.0","method":"optimism_syncStatus"}' -H "Content-Type: application/json" http://localhost:9545 | jq -r '.result.unsafe_l2.tim 220 | estamp') ) / 3600 )) hours" 221 | ``` 222 | 223 | ### Grafana dashboard 224 | 225 | Grafana is exposed at [http://localhost:3000](http://localhost:3000) and comes with one pre-loaded dashboard ("Simple Node Dashboard"). 226 | Simple Node Dashboard includes basic node information and will tell you if your node ever falls out of sync with the reference L2 node or if a state root fault is detected. 227 | 228 | Use the following login details to access the dashboard: 229 | 230 | - Username: `admin` 231 | - Password: `superseed` 232 | 233 | Navigate over to `Dashboards > Manage > Simple Node Dashboard` to see the dashboard, see the following gif if you need help: 234 | 235 | ![metrics dashboard gif](https://user-images.githubusercontent.com/14298799/171476634-0cb84efd-adbf-4732-9c1d-d737915e1fa7.gif) 236 | 237 | 238 | -------------------------------------------------------------------------------- /config/monitoring/grafana.env: -------------------------------------------------------------------------------- 1 | GF_SECURITY_ADMIN_PASSWORD=superseed 2 | -------------------------------------------------------------------------------- /config/monitoring/influxdb.env: -------------------------------------------------------------------------------- 1 | INFLUXDB_HTTP_AUTH_ENABLED=false 2 | -------------------------------------------------------------------------------- /config/monitoring/node_exporter.sh: -------------------------------------------------------------------------------- 1 | # Update packages 2 | sudo apt update -y 3 | 4 | # Create a node_exporter user (security best practice) 5 | sudo useradd -rs /bin/false node_exporter 6 | 7 | # Download latest Node Exporter release 8 | export VERSION="1.7.0" # Change this to the latest version if needed 9 | wget https://github.com/prometheus/node_exporter/releases/download/v${VERSION}/node_exporter-${VERSION}.linux-amd64.tar.gz 10 | 11 | # Extract and move the binary 12 | tar xvf node_exporter-${VERSION}.linux-amd64.tar.gz 13 | sudo mv node_exporter-${VERSION}.linux-amd64/node_exporter /usr/local/bin/ 14 | 15 | # Set correct permissions 16 | sudo chown node_exporter:node_exporter /usr/local/bin/node_exporter 17 | sudo tee /etc/systemd/system/node_exporter.service <