feat(protocol, relayer): Improved Taiko Protocol and Relayer Document…

…ations (#15440)

Co-authored-by: Daniel Wang <99078276+dantaik@users.noreply.github.com>

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.

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
+HEADER_SYNC_INTERVAL_IN_SECONDS=2

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 <sub-command> --help
+./relayer <sub-command> --help
 ```
 
 ## Project structure