From 67ca2e1e0bfe5301efa854048cc5cb0f0dafe921 Mon Sep 17 00:00:00 2001 From: joao <22820692+joaolago1113@users.noreply.github.com> Date: Wed, 24 Jan 2024 01:58:39 +0000 Subject: [PATCH] feat(protocol, relayer): Improved Taiko Protocol and Relayer Documentations (#15440) Co-authored-by: Daniel Wang <99078276+dantaik@users.noreply.github.com> --- packages/protocol/README.md | 105 ++++++++++++++++------ packages/relayer/.l1processor.example.env | 4 +- packages/relayer/README.md | 81 +++++++++++++---- 3 files changed, 144 insertions(+), 46 deletions(-) diff --git a/packages/protocol/README.md b/packages/protocol/README.md index 7836e0b7c35..2037a682d10 100644 --- a/packages/protocol/README.md +++ b/packages/protocol/README.md @@ -1,42 +1,26 @@ -# Taiko protocol +# Taiko Protocol This package contains rollup contracts on both L1 and L2, along with other assisting code. Taiko L2's chain ID is [167](https://github.com/ethereum-lists/chains/pull/1611). -## Compile +## Getting Started -To compile smart contracts, run: +Before compiling smart contracts, ensure all necessary dependencies are installed: ```sh -pnpm compile +pnpm install ``` -If you run into `Error: Unknown version provided`, you should upgrade your foundry installation by running `curl -L https://foundry.paradigm.xyz | bash`. - -## Deploy - -Deploy TaikoL1 on foundry network: +Then, compile the smart contracts: ```sh -pnpm deploy:foundry -``` - -## Test - -Run test cases on foundry network: - -```sh -pnpm test +pnpm compile ``` -Run test cases that require a running go-ethereum node: - -```sh -pnpm test:integration -``` +If you run into `Error: Unknown version provided`, you should upgrade your foundry installation by running `curl -L https://foundry.paradigm.xyz | bash`. -## Generate L2 genesis JSON's `alloc` field +## Generate L2 Genesis JSON's `alloc` Field -Start by creating a `config.js`, for example: +Create a `config.js` with the following structure: ```javascript module.exports = { @@ -49,6 +33,10 @@ module.exports = { { "0xDf08F82De32B8d460adbE8D72043E3a7e25A3B39": 1024 }, { "0x79fcdef22feed20eddacbb2587640e45491b757f": 1024 }, ], + // Owner Chain ID, Security Council, and Timelock Controller + ownerChainId: 31337, + ownerSecurityCouncil: "0xDf08F82De32B8d460adbE8D72043E3a7e25A3B39", + ownerTimelockController: "0xDf08F82De32B8d460adbE8D72043E3a7e25A3B39", // L2 EIP-1559 baseFee calculation related fields. param1559: { gasExcess: 1, @@ -58,7 +46,7 @@ module.exports = { }; ``` -Next, run the generation script: +Then, execute the generation script: ```sh pnpm compile && pnpm generate:genesis config.js @@ -77,3 +65,68 @@ This project also integrates with Foundry for building and testing contracts. - To run foundry tests: `forge test --gas-report -vvv` or `pnpm test:foundry` Note that compiling with foundry uses dependencies inside the `lib` dir (instead of `node_modules`). + +## Generating and Running the L2 Genesis Block + +The generation of the L2 genesis block and obtaining its hash involves a series of steps, including constructing the genesis JSON, followed by the actual generation and retrieval of the genesis block hash. A test can be executed to comprehend this process. + +### Testing Genesis Block Creation + +To understand how the `genesis.json` is built from deployment files and how to generate the genesis block and its hash, you can use the `test:genesis` command. This test serves as a learning tool: + +```sh +pnpm test:genesis +``` + +This test, defined in `./genesis/generate_genesis.test.sh`, compiles the contracts, generates the genesis JSON, and initiates a Geth node using Docker to simulate the deployment of the genesis block. Reviewing this script and its output can help you grasp the steps required to create and initiate a genesis block for the Taiko Protocol. + +### Generating the Actual Genesis Block + +After understanding the process from the test, proceed to generate the actual `genesis.json` and the genesis block: + +1. **Build the Genesis JSON:** Use the information learned from the `test:genesis` to build the `genesis.json` file from the files in the `/deployments/` directory. The `generate_genesis.test.sh` script contains the necessary commands to create this file. + +2. **Run Geth to Generate the Genesis Block:** You can use Geth to initialize and run a private network with the genesis block. You can start Geth with the following commands: + + ```sh + geth --datadir ~/taiko-l2-network/node init /deployments/genesis.json + geth --datadir ~/taiko-l2-network/node --networkid 167 --http --http.addr 127.0.0.1 --http.port 8552 --http.corsdomain "*" + ``` + + For details refer to the Geth documentation on [creating a genesis block](https://geth.ethereum.org/docs/fundamentals/private-network#creating-genesis-block). + +3. **Retrieve the Genesis Block Hash:** Connect to the Geth node using the command: + + ```sh + geth attach ~/taiko-l2-network/node/geth.ipc + ``` + + In the Geth console, use `eth.getBlock(0)` to obtain the hash of the genesis block. + +4. **Update `test_deploy_on_l1.sh` File:** Update the `L2_GENESIS_HASH` variable in the `test_deploy_on_l1.sh` script with the obtained genesis block hash. + +By following these steps, you will successfully generate the L2 genesis block for the Taiko Protocol, retrieve its hash, and prepare for the L1 contract deployment. + +## Deploying the L1 Contracts + +To deploy L1 contracts for Taiko Protocol, you can use any Ethereum network. This guide illustrates the process using a Hardhat local network, but it's adaptable to others. The deployment relies on `script/test_deploy_on_l1.sh`, which targets a node at `http://localhost:8545` by default. + +Here’s how you can proceed: + +1. **Ensure Sufficient ETH:** Check that the address associated with the private key in `script/test_deploy_on_l1.sh` has enough ETH for deploying contracts on the Hardhat network. + +2. **Update Contract Addresses:** After running the genesis block generation script (`pnpm test:genesis`), you will receive a list of pre-computed contract addresses. These addresses need to be added to the `test_deploy_on_l1.sh` file. Make sure to update this file with the correct contract addresses before proceeding with the deployment. + +3. **Start a Local Development Network:** While this guide uses Hardhat as an example, you can use any Ethereum network. If you choose to use Hardhat, start a local Ethereum network for development and testing: + +```sh +pnpm hardhat node +``` + +4. **Deploy Contracts Using Foundry:** Once your network is running, open a new terminal window and execute the deployment scripts using Foundry: + +```sh +pnpm deploy:foundry +``` + +This command will deploy the L1 contracts using the settings and addresses you’ve provided in the `test_deploy_on_l1.sh` script. diff --git a/packages/relayer/.l1processor.example.env b/packages/relayer/.l1processor.example.env index d4be45f7659..6b8c1c05cbe 100644 --- a/packages/relayer/.l1processor.example.env +++ b/packages/relayer/.l1processor.example.env @@ -1,6 +1,6 @@ PROMETHEUS_HTTP_PORT=6062 DATABASE_USER=root -DATABASE_PASSWORD=root +DATABASE_PASSWORD=passw00d DATABASE_NAME=relayer DATABASE_HOST=localhost:3306 DATABASE_MAX_IDLE_CONNS=50 @@ -27,4 +27,4 @@ CONFIRMATIONS_BEFORE_PROCESSING=2 CORS_ORIGINS=* NUM_GOROUTINES=50 BLOCK_BATCH_SIZE=100 -HEADER_SYNC_INTERVAL_IN_SECONDS=2 \ No newline at end of file +HEADER_SYNC_INTERVAL_IN_SECONDS=2 diff --git a/packages/relayer/README.md b/packages/relayer/README.md index 4dda06eefc5..c52d8b1207c 100644 --- a/packages/relayer/README.md +++ b/packages/relayer/README.md @@ -5,54 +5,99 @@ A relayer for the Bridge to watch and sync event between Layer 1 and Taiko Layer 2. -## Build the source +## Build the Source -Building the `taiko-client` binary requires a Go compiler. Once installed, run: +To build the source, ensure you have an updated Go compiler installed. Run the following command to compile the executable: ```sh -make build +go build -o relayer ./cmd/ ``` ## Configuration -### Configure environment variables +### Configure MySQL and RabbitMQ -To run an indexer: -run `cp .l1processor.example.env .l1processor.env`, and replace the variables as needed in `.l1processor.env`. +Before configuring environment variables, ensure that you have MySQL and RabbitMQ instances running. Replace the `MYSQL_` environment variables with your specific configurations. -### Confgiure MySQL and RabbitMQ +RabbitMQ can be installed using the provided script: -You need to be running a MySQL instance and a RabbitMQ instance, and replace all the `MYSQL_` env vars with yours. - -RabbitMQ can be installed with `./scripts/install-rabbitmq.sh`. +```sh +./scripts/install-rabbitmq.sh +``` -You can also use docker-compose to bring up MySQL and RabbitMQ in your local setup. +Alternatively, use Docker Compose to set up MySQL and RabbitMQ in your local environment: -``` +```sh cd ./docker-compose docker-compose up ``` -To migrate database schema in MySQL +To migrate the database schema in MySQL: -``` +```sh cd ./migrations goose mysql "root:passw00d@tcp(localhost:3306)/relayer" status goose mysql "root:passw00d@tcp(localhost:3306)/relayer" up ``` +### Configure Environment Variables + +Environment variables are crucial for the configuration of the Relayer’s processor and indexer. These variables are set in environment files, which are then loaded by the Relayer at runtime. + +#### Setting up the Processor: + +1. **Create the Environment File for the Processor**: + Copy the example processor environment file to a new file: + + ```sh + cp .l1processor.example.env .l1processor.env + ``` + + Modify `.l1processor.env` as necessary to suit your environment settings. + +2. **Run the Processor**: + Before running the processor, specify which environment file it should use by setting the `RELAYER_ENV_FILE` environment variable: + ```sh + export RELAYER_ENV_FILE=./.l1processor.env + ``` + Now, you can run the processor: + ```sh + ./relayer processor + ``` + +#### Setting up the Indexer: + +1. **Create the Environment File for the Indexer**: + Copy the example indexer environment file to a new file: + + ```sh + cp .l1indexer.example.env .l1indexer.env + ``` + + Edit `.l1indexer.env` to reflect your specific configurations. + +2. **Run the Indexer**: + Set the `RELAYER_ENV_FILE` to point to the indexer's environment file: + ```sh + export RELAYER_ENV_FILE=./.l1indexer.env + ``` + Execute the indexer: + ```sh + ./relayer indexer + ``` + ## Usage -Review all available sub-commands: +To review all available sub-commands, use: ```sh -bin/relayer --help +./relayer --help ``` -Review each sub-command's command line flags: +To review each sub-command's command line flags, use: ```sh -bin/relayer --help +./relayer --help ``` ## Project structure