How to Use Polygon zkEVM with Avail

Introduction

Embark on setting up your own Polygon zkEVM network, leveraging Avail as the data availability layer. This guide is tailored for deploying on Ethereum's Sepolia testnet and integrating with the Avail Goldberg testnet. To gain a comprehensive understanding of Polygon zkEVM, review the Polygon zkEVM documentation (opens in a new tab).

In this guide, you will conduct the following:

• Introduction
• Prerequisites
  • Hardware Requirements
  • Network Details
• Launch an Avail-Powered zkEVM
  • Deploy the Contracts
  • Deploy the Node
  • Setup the Prover
  • Configure the Bridge

Prerequisites

Ensure you have installed the following software.

Installation commands are based on Ubuntu 20.04 LTS:

# Install Git
sudo apt install -y git
 
# Install Node.js (using NVM)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
nvm install --lts
 
# Install Golang
wget https://go.dev/dl/go1.19.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.19.linux-amd64.tar.gz
echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc
source ~/.bashrc
 
# Install Docker and Docker Compose
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Hardware Requirements

Both the real and mock provers are compatible exclusively with x86 architectures. They are not designed to operate on ARM architecture machines, including Apple Silicon devices, even within Dockerized environments.

Running the Polygon zkEVM solution suite may lead to storage issues, primarily due to excessive Docker logs. To mitigate this, you can customize the Docker daemon's behavior by referring to the first answer here (opens in a new tab). Choose a configuration that best suits your needs.

• For a devnet setup with limited state growth and Docker logs, we recommend a minimum disk size of approximately 50GB.
• If you plan to run a real prover, it's advisable to allocate a minimum disk size of around 120GB for your devnet setup.
• Keep in mind that these recommendations may vary based on your specific use case and requirements.

Network Details

Before diving into the setup, ensure you have the following network details:

Launch an Avail-Powered zkEVM

Please be aware that some aspects of this guide may differ from the original source due to the unique nature of the Avail validium implementation. For zkEVM node-specific configurations and troubleshooting, refer to the official Polygon documentation (opens in a new tab).

Deploy the Contracts

1. Clone the validium-contracts repository and install dependencies:

   git clone git@github.com:availproject/validium-contracts.git
   cd validium-contracts
    
   npm i

2. Set up the environment and deployment parameters:

   • Update .env as per .env.example.

     .env.example

   • Fill in deploy_parameters.json following deploy_parameters.json.example:

     • Specify the trustedSequencer address. This address represents the Sequencer that is responsible for sequencing batches.

     • Define the trustedAggregator address. This address represents the Aggregator that handles the submission of proofs.

     • Fill in the following fields with the respective addresses that will control the contracts: admin, zkEVMOwner, timelockAddress, and initialZkEVMDeployerOwner.

     • Enter the private key for the deployer in the deployerPvtKey field.

       deployment/deploy_parameters.json

3. Execute deployment scripts on the Sepolia network:

   npx hardhat run --network sepolia deployment/2_deployPolygonZKEVMDeployer.js
   npx hardhat run --network sepolia deployment/3_deployContracts.js

   You should generate a deploy_output.json file.

4. Verify the deployed contracts:

   npx hardhat run --network sepolia deployment/verifyzkEVMDeployer.js
   npx hardhat run --network sepolia deployment/verifyContracts.js

Deploy the Node

1. Clone the validium-node repository for node setup:

   git clone git@github.com:availproject/validium-node.git
   cd validium-node

2. Generate a secure account keystore file for Ethereum L1 transactions:

   docker run --rm hermeznetwork/zkevm-node:latest sh -c "/app/zkevm-node encryptKey --pk=[your private key] --pw=[password to encrypt file] --output=./keystore; cat ./keystore/*" > account.keystore
   • Replace [your private key] with your Ethereum L1 account private key.
   • Replace [password to encrypt file] with a password used for file encryption. This password must be passed to the Node later via the env variable ZKEVM_NODE_ETHERMAN_PRIVATEKEYPASSWORD.

3. Update configuration files for the node:

   • Modify test.avail.config.json, test.node.config.toml, and test.genesis.config.json based on the provided example files.

     Click to view the avail configuration example

     test/config/test.avail.example.config.json
     Click to view the node configuration example

     test/config/test.node.config.example.toml
     Click to view the genesis configuration example

     test/config/test.genesis.config.example.json

4. Build the Docker image and launch the node:

   make build-docker
   cd test
   make run

Setup the Prover

1. To switch to the real verifier mode, modify the deploy_parameters.json file:

   "realVerifier": true

2. Utilize the following commands to download and unpack the configuration file:

wget https://de012a78750e59b808d922b39535e862.s3.eu-west-1.amazonaws.com/v2.0.0-RC4-fork.5.tgz
tar -xzvf v2.0.0-RC4-fork.5.tgz
rm -rf config
mv v2.0.0-RC4-fork.5.tgz validium-node/test/config/prover

3. Ensure the docker-compose.yml includes proper file mappings for the prover configuration.

4. Modify the test.prover.config.json to enable actual prover functionality:

   test.prover.config.json

Configure the Bridge

The zkEVM bridge service is a microservice that simplifies bridging between L1 and L2 by auto-claiming L1 transactions on L2 and generating necessary Merkle proofs. While optional for running a Validium, it enhances the ease of bridging transactions.

The Nomad DA bridge is only operational on Sepolia, limiting validium's data attestation to this chain. Alternatively, you can simulate data attestation and deploy on your preferred blockchain

1. Clone the bridge repository:

   git clone git@github.com:availproject/validium-bridge-service.git
   cd bridge

2. Fill in config/config.local.toml following config.local.example.toml:

   Unless you changed the genesis file, the L2 bridge address should remain the same.

   The address provided by default in the configuration is allocated ETH in the validium test setup for autoclaiming on L2. If a different address is used, it might require ETH. Similarly, in a production setup where ETH is not arbitrarily minted, you will need to manually fund the zkevm-bridge-service autoclaiming account.

   Parameter	Example Value
   L1URL	"http://zkevm-mock-l1-network:8545"
   GenBlockNumber	1
   PolygonBridgeAddress	"0xff0EE8ea08cEf5cb4322777F5CC3E8A584B8A4A0"
   PolygonZkEVMGlobalExitRootAddress	"0x2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6"
   L2PolygonBridgeAddresses	"0xff0EE8ea08cEf5cb4322777F5CC3E8A584B8A4A0"

   Click to view the bridge configuration example

   config/config.local.example.toml

3. Build and run the Docker image using the following commands:

   make build-docker
   make run

4. Once the Docker image is running, it serves as a microservice to detect L1 and L2 bridge transactions. You can check if the API is active by accessing the /api endpoint.

   • Generate Merkle Proofs: Use the /merkle-proof endpoint to generate the necessary Merkle proofs for bridging transactions.
   • Additional Endpoints: The microservice provides other endpoints for various functionalities, such as detecting bridge transactions for specific accounts.
   • Updating Code: If you need to modify any part of the code, remember that each change necessitates a new build. To update and rerun the service, execute the make build-docker && make run commands.