Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@zjg555543
zjg555543 committed Nov 21, 2023
1 parent 34eab3b commit 7371a7b
Show file tree
Hide file tree
Showing 4 changed files with 100 additions and 73 deletions.
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ X1 Node is a Go implementation of a node that operates the X1 Network.

## About the X1 network

Since this is an implementation of a protocol it's fundamental to understand it, [here]() you can find the specification of the protocol.
Since this is an implementation of a protocol it's fundamental to understand it, [here](https://www.okx.com/x1/docs/technology/overview/x1-architecture) you can find the specification of the protocol.

Glossary:

- L1: Base blockchain where the rollup smart contracts are deployed. It's Ethereum or a testnet of Ethereum, but it could be any EVM compatible blockchain.
- L2: the rollup network aka the X1 network.
- Batch: a group of transactions that are executed/proved, using the [X1 prover]() and sent to / synchronized from L1
- Batch: a group of transactions that are executed/proved, using the [X1 prover](https://github.com/okx/x1-prover) and sent to / synchronized from L1
- Sequencer: the actor that is responsible for selecting transactions, putting them in a specific order, and sending them in batches to L1
- Trusted sequencer: sequencer that has special privileges, there can only be one trusted sequencer. The privileges granted to the trusted sequencer allow it to forecast the batches that will be applied to L1. This way it can commit to a specific sequence before interacting with L1. This is done to achieve fast finality and reduce costs associated with using the network (lower gas fees)
- Permissionless sequencer: sequencer role that can be performed by anyone. It has competitive disadvantages compared to the trusted sequencer (slow finality, MEV attacks). Its main purpose is to provide censorship resistance and unstoppability features to the network.
Expand Down
4 changes: 2 additions & 2 deletions docs/networks.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# X1 testnet networks
# X1 networks

| Network Name | ChainID | RPC URL | Explorer | Bridge Info |
|--------------|---------|---------|----------|------------------|
| Public Testnet | `1402` | https://rpc.public.x1-test.net | https://explorer.public.x1-test.net | https://public.x1-test.net/
| Public Testnet | `195` | https://x1testrpc.okx.com/ <br> https://testrpc.x1.tech | https://www.oklink.com/x1-test | https://www.okx.com/x1/bridge-test
156 changes: 90 additions & 66 deletions docs/production-setup.md
View file
Original file line number Diff line number Diff line change
@@ -1,82 +1,106 @@
# Production Setup

This guide describes how to run a node that:

- Synchronizes the network
- Expose a JSON RPC interface, acting as an archive node

Note that sequencing and proving functionalities are not covered in this document **yet**.

## Requirements

- A machine to run the X1 node with the following requirements:
- Hardware: 32G RAM, 4 cores, 128G Disk with high IOPS (as the network is super young the current disk requirements are quite low, but they will increase overtime. Also note that this requirement is true if the DBs run on the same machine, but it's recommended to run Postgres on dedicated infra). Currently ARM-based CPUs are not supported
- Software: Ubuntu 22.04, Docker
- A L1 node: we recommend using geth, but what it's actually needed is access to a JSON RPC interface for the L1 network (Goerli for X1 testnet, Ethereum mainnet for X1 mainnet)

## Setup

This is the most straightforward path to run a X1 node, and it's perfectly fine for most use cases, however if you are interested in providing service to many users it's recommended to do some tweaking over the default configuration. Furthermore, this is quite opinionated, feel free to run this software in a different way, for instance it's not needed to use Docker, you could use the Go and C++ binaries directly.

tl;dr:

```bash
# DOWNLOAD ARTIFACTS
ZKEVM_NET=mainnet
ZKEVM_DIR=./path/to/install # CHANGE THIS
ZKEVM_CONFIG_DIR=./path/to/config # CHANGE THIS
curl -L https://github.com/okx/x1-node/releases/latest/download/$ZKEVM_NET.zip > $ZKEVM_NET.zip && unzip -o $ZKEVM_DIR.zip -d $ZKEVM_DIR && rm $ZKEVM_DIR.zip
mkdir -p $ZKEVM_CONFIG_DIR && cp $ZKEVM_DIR/$ZKEVM_NET/example.env $ZKEVM_CONFIG_DIR/.env
# Setup Production zkNode
X1 is now available on the Testnet for developers to launch smart contracts, execute transactions, and experiment with the network. This tutorial extends the exploration by allowing developers to launch their own node on the Public Testnet.
Before we begin, this document is fairly technical and requires prior exposure to Docker and CLI. Post spinning up your zkNode instance, you will be able to run the Synchronizer and utilize the JSON-RPC interface.

## Prerequisites
This tutorial assumes that you have docker-compose already installed. If you need any help with the installation, please check the [official docker-compose installation guide](https://docs.docker.com/compose/install/).

### Minimum System Requirements
<Tip title="CAUTION">zkProver does not work on ARM-based Macs yet, and using WSL/WSL2 on Windows is not advisable. Currently, zkProver optimizations require CPUs that support the AVX2 instruction, which means some non-M1 computers, such as AMD, won't work with the software regardless of the OS.</Tip>

- 16GB RAM
- 4-core CPU
- 20GB Storage (This will increase over time)

### Network Components
Here is a list of crucial network components that are required before you can run the zkNode:
- Ethereum Node - Use geth or any service providing a JSON RPC interface for accessing the L1 network
- X1-Node (or zkNode) - L2 Network
- Synchronizer - Responsible for synchronizing data between L1 and L2
- JSON RPC Server - Interface to L2 network
- State DB - Save the L2 account, block and tx data.

Let's set up each of the above components!

## Ethereum Node Setup
The Ethereum RPC Node is the first component to be deployed because zkNode needs to synchronize blocks and transactions on L1. You can invoke the ETH RPC (Testnet: Sepolia) service through any of the following methods:
- Third-party RPC services, such as [Infura](https://www.infura.io/) or [Ankr](https://www.ankr.com/).
- Set up your own Ethereum node. Follow the instructions provided in this [guide to set up and install Geth](https://geth.ethereum.org/docs/getting-started/installing-geth).

## Installing
Once the L1 RPC component is complete, we can start the zkNode setup. This is the most straightforward way to run a zkNode and it's fine for most use cases.
Furthermore, this method is purely subjective and feel free to run this software in a different manner. For example, Docker is not required, you could simply use the Go binaries directly.
Let's start setting up our zkNode:

1. Download the installation scrip
``` bash
mkdir -p ./x1-node && cd ./x1-node

wget https://static.okex.org/cdn/chain/x1/snapshot/run_x1_testnet.sh && chmod +x run_x1_testnet.sh && ./run_x1_testnet.sh init && cp ./testnet/example.env ./testnet/.env
```
2. The example.env file must be modified according to your configurations. Edit the .env file with your favourite editor (we'll use vim in this guide): ```vim ./testnet/.env.```
``` bash
# URL of a JSON RPC for Sepolia
X1_NODE_ETHERMAN_URL = "http://your.L1node.url"

# EDIT THIS env file:
nano $ZKEVM_CONFIG_DIR/.env
# PATH WHERE THE STATEDB POSTGRES CONTAINER WILL STORE PERSISTENT DATA
X1_NODE_STATEDB_DATA_DIR = "./x1_testnet_data/statedb"

# RUN:
docker compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml up -d
# PATH WHERE THE POOLDB POSTGRES CONTAINER WILL STORE PERSISTENT DATA
X1_NODE_POOLDB_DATA_DIR = "/x1_testnet_data/pooldb"
```
3. Restore the latest L2 snapshot locally database for synchronizing L2 data quickly.
``` bash
./run_x1_testnet.sh restore
```

### Explained step by step:

1. Define network: `ZKEVM_NET=testnet` or `ZKEVM_NET=mainnet`
2. Define installation path: `ZKEVM_DIR=./path/to/install`
3. Define a config directory: `ZKEVM_CONFIG_DIR=./path/to/config`
4. It's recommended to source this env vars in your `~/.bashrc`, `~/.zshrc` or whatever you're using
5. Download and extract the artifacts: `curl -L https://github.com/okx/x1-node/releases/latest/download/$X1_NET.zip > $X1_NET.zip && unzip -o $X1_NET.zip -d $X1_DIR && rm $X1_NET.zip`. Note you may need to install `unzip` for this command to work.
## Starting
Use the below command to start the zkNode instance:
``` bash
./run_x1_testnet.sh start

> **NOTE:** Take into account this works for the latest release (mainnet), in case you want to deploy a pre-release (testnet) you should get the artifacts directly for that release and not using the "latest" link depicted here. [Here](https://github.com/okx) you can check the node release deployed for each network.
docker ps -a
```

6. Copy the file with the env parameters into config directory: `mkdir -p $ZKEVM_CONFIG_DIR && cp $ZKEVM_DIR/$ZKEVM_NET/example.env $ZKEVM_CONFIG_DIR/.env`
7. Edit the env file, with your favourite editor. The example will use nano: `nano $ZKEVM_CONFIG_DIR/.env`. This file contains the configuration that anyone should modify. For advanced configuration:
1. Copy the config files into the config directory `cp $ZKEVM_DIR/$ZKEVM_NET/config/environments/testnet/* $ZKEVM_CONFIG_DIR/`
2. Make sure the modify the `ZKEVM_ADVANCED_CONFIG_DIR` from `$ZKEVM_CONFIG_DIR/.env` with the correct path
3. Edit the different configuration files in the $ZKEVM_CONFIG_DIR directory and make the necessary changes
8. Run the node: `docker compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml up -d`. You may need to run this command using `sudo` depending on your Docker setup.
9. Make sure that all components are running: `docker compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml ps`. You should see the following containers:
1. x1-rpc
2. x1-sync
3. x1-state-db
4. x1-pool-db
5. x1-prover
You will see a list of the following containers :
- x1-rpc
- x1-sync
- x1-state-db
- x1-pool-db
- x1-prover

You should now be able to run queries to the JSON-RPC endpoint at http://localhost:8545.
Run the following query to get the most recently synchronized L2 block; if you call it every few seconds, you should see the number grow:
``` bash
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":83}' http://localhost:8545
```

If everything has gone as expected you should be able to run queries to the JSON RPC at `http://localhost:8545`. For instance you can run the following query that fetches the latest synchronized L2 block, if you call this every few seconds, you should see the number increasing:
## Stopping
Use the below command to stop the zkNode instance:
``` bash
./run_x1_testnet.sh stop
```

`curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":83}' http://localhost:8545`
## Restarting
Use the below command to stop the zkNode instance:
``` bash
./run_x1_testnet.sh restart
```
## Updating
To update the zkNode software, run the below command, and the file ```./testnet/.env``` will be retained, the other config will be deleted.
``` bash
./run_x1_testnet.sh update
```

## Troubleshooting
- It's possible that the machine you're using already uses some of the necessary ports. In this case, you can change them directly ```./testnet/docker-compose.yml```.
- If one or more containers are crashing, please check the logs using the command below:
``` bash
docker ps -a

- It's possible that the machine you're using already uses some of the necessary ports. In this case you can change them directly at `$ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml`
- If one or more containers are crashing please check the logs using `docker compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs <cointainer_name>`

## Stop

```bash
docker compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml down
docker logs <cointainer_name>
```

## Updating

In order to update the software, you have to repeat the steps of the setup, but taking care of not overriding the config that you have modified. Basically, instead of running `cp $ZKEVM_DIR/$ZKEVM_NET/example.env $ZKEVM_CONFIG_DIR/.env`, check if the variables of `$ZKEVM_DIR/$ZKEVM_NET/example.env` have been renamed or there are new ones, and update `$ZKEVM_CONFIG_DIR/.env` accordingly.

## Advanced setup

> DISCLAIMER: right now this part of the documentation attempts to give ideas on how to improve the setup for better performance, but is far from being a detailed guide on how to achieve this. Please open issues requesting more details if you don't understand how to achieve something. We will keep improving this doc for sure!
Expand Down
9 changes: 6 additions & 3 deletions docs/running_local.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,9 @@ This documentation will help you running the following components:

## Requirements

The current version of the environment requires `go`, `docker` and `docker-compose` to be previously installed, check the links below to understand how to install them:
The current version of the environment requires `Foundryup`, `go`, `docker` and `docker-compose` to be previously installed, check the links below to understand how to install them:

- <https://book.getfoundry.sh/getting-started/installation>
- <https://go.dev/doc/install>
- <https://www.docker.com/get-started>
- <https://docs.docker.com/compose/install/>
Expand Down Expand Up @@ -75,6 +76,8 @@ If you need sample data already deployed to the network, we have the following s
**To add some examples of transactions and smart contracts:**

```bash
cast send --legacy --from 0x2ECF31eCe36ccaC2d3222A303b1409233ECBB225 --private-key 0xde3ca643a52f5543e84ba984c4419ff40dbabd0e483c31c1d09fee8168d68e38 --rpc-url http://127.0.0.1:8123 0xC949254d682D8c9ad5682521675b8F43b102aec4 --value 10ether

make deploy-sc
```

Expand Down Expand Up @@ -191,11 +194,11 @@ To configure your Metamask to use your local environment, follow these steps:

| Address | Description |
|---|---|
| 0x82109a709138A2953C720D3d775168717b668ba6 | L1 OKB token |
| 0x82109a709138A2953C720D3d775168717b668ba6 | L2 WETH token |
| 0x0D9088C72Cd4F08e9dDe474D8F5394147f64b22C | Proof of Efficiency |
| 0x10B65c586f795aF3eCCEe594fE4E38E1F059F780 | Bridge |
| 0xcFE6D77a653b988203BfAc9C6a69eA9D583bdC2b | Matic token |
| 0x82109a709138A2953C720D3d775168717b668ba6 | L1 OKB token |
| 0x82109a709138A2953C720D3d775168717b668ba6 | L2 WETH token |
| 0xEd236da21Ff62bC7B62608AdB818da49E8549fa7 | GlobalExitRootManager |

## Admin Account
Expand Down

0 comments on commit 7371a7b

Please sign in to comment.