Please note that the current Data Availability (DA) configuration in Polygon CDK is using a Data Availability Committee (DAC) node with a local Geth client as the L1. However, the integration with Layer 1 testnets, including Sepoilla, is actively being pursued.
The CDK Validium is actively being developed, with ongoing feature enhancements and issue resolutions. For the latest updates, follow our official GitHub repositories.
New features and refinements are designed to enhance user experience without disrupting ongoing activities.
What You'll Learn
In this tutorial, you'll quickly dive into the world of Polygon CDK. You'll learn to set up and run a local CDK-based chain, enabling you to:
- Gain a rapid understanding of Polygon CDK.
- Test smart contracts.
- Execute web3 transactions.
- Investigate network capabilities.
What You'll Need
This tutorial requires Docker and Docker Compose. They allow you to run multiple services in separate environments. If you haven't installed these tools yet, you can do so by following the guides at the following links:
Recommended System Requirements
Ensure that your system meets the following recommended specifications before starting this tutorial:
- A Linux-based OS (e.g., Ubuntu Server 22.04 LTS)
- At least 16GB RAM with a 4-core CPU
- An AMD64 architecture system
What You'll Do
In this tutorial, you'll go through the following steps. Make sure to follow each section in order if this is your first time setting up a zkValidium.
- : You'll start by downloading necessary configuration files from our repository.
- : After setting up your workspace, you'll launch the zkValidium on your local machine and ensure all services are running properly.
- : With your local CDK Validium running, you'll verify its functionalities, including testing block explorers and making transactions.
- : In this section, you will test using the native bridges to transfer assets between the L1 and L2.
Step 1: Download Configuration Files
The first step involves downloading the necessary configuration files from our repository. Run the following commands in your terminal to clone the repository and navigate into it:
git clone https://github.com/Snapchain/zkValidium-quickstart.git
.env file by copying from the example:
cp .env.example .env
The repository includes these key files:
Docker-compose.yml: This Docker Compose file defines all the necessary containers to set up the CDK Validium.
Makefile: This file includes a series of commands that will help you manage your CDK Validium node.
config: This folder contains configuration files required for the CDK Validium.
Step 2: Launch the Validium Locally
With the repository cloned and your working directory set, let's start up the CDK Validium. First, you'll need to pull the necessary Docker images from Docker Hub:
After pulling the images, you can start your local CDK Validium:
To ensure all services are running properly, check the status of each container:
You will see results similar to the following:
Container status details ↓
Name Command State Ports
cdk-validium-aggregator /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:50081->50081/tcp,:::50081->50081/tcp, 8123/tcp,
cdk-validium-approve /bin/sh -c /app/cdk-validi ... Exit 0
cdk-validium-data-availability /bin/sh -c /app/cdk-data-a ... Up 0.0.0.0:8444->8444/tcp,:::8444->8444/tcp
cdk-validium-data-node-db docker-entrypoint.sh postg ... Up (healthy) 0.0.0.0:5444->5432/tcp,:::5444->5432/tcp
cdk-validium-eth-tx-manager /bin/sh -c /app/cdk-validi ... Up 8123/tcp, 0.0.0.0:9094->9091/tcp,:::9094->9091/tcp
cdk-validium-event-db docker-entrypoint.sh postg ... Up 0.0.0.0:5435->5432/tcp,:::5435->5432/tcp
cdk-validium-explorer-json-rpc /bin/sh -c /app/cdk-validi ... Up 8123/tcp, 0.0.0.0:8124->8124/tcp,:::8124->8124/tcp,
cdk-validium-explorer-l1 /bin/sh -c mix do ecto.cre ... Up 0.0.0.0:4000->4000/tcp,:::4000->4000/tcp
cdk-validium-explorer-l1-db docker-entrypoint.sh postg ... Up 0.0.0.0:5436->5432/tcp,:::5436->5432/tcp
cdk-validium-explorer-l2 /bin/sh -c mix do ecto.cre ... Up 0.0.0.0:4001->4000/tcp,:::4001->4000/tcp
cdk-validium-explorer-l2-db docker-entrypoint.sh postg ... Up 0.0.0.0:5437->5432/tcp,:::5437->5432/tcp
cdk-validium-json-rpc /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:8123->8123/tcp,:::8123->8123/tcp,
cdk-validium-l2gaspricer /bin/sh -c /app/cdk-validi ... Up 8123/tcp
cdk-validium-mock-l1-network geth --http --http.api adm ... Up 30303/tcp, 30303/udp,
cdk-validium-pool-db docker-entrypoint.sh postg ... Up 0.0.0.0:5433->5432/tcp,:::5433->5432/tcp
cdk-validium-prover zkProver -c /usr/src/app/c ... Up 0.0.0.0:50052->50052/tcp,:::50052->50052/tcp,
cdk-validium-sequence-sender /bin/sh -c /app/cdk-validi ... Up 8123/tcp
cdk-validium-sequencer /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:6060->6060/tcp,:::6060->6060/tcp, 8123/tcp,
cdk-validium-state-db docker-entrypoint.sh postg ... Up 0.0.0.0:5432->5432/tcp,:::5432->5432/tcp
cdk-validium-sync /bin/sh -c /app/cdk-validi ... Up 8123/tcp
dac-setup-committee docker-entrypoint.sh npm r ... Exit 0
zkevm-bridge-db docker-entrypoint.sh postg ... Up 0.0.0.0:5438->5432/tcp,:::5438->5432/tcp
zkevm-bridge-service /bin/sh -c /app/zkevm-brid ... Up 0.0.0.0:8080->8080/tcp,:::8080->8080/tcp,
zkevm-bridge-ui /bin/sh /app/scripts/deploy.sh Up 0.0.0.0:8088->80/tcp,:::8088->80/tcp
If any service isn't running (i.e., in Exit 1 state), you can investigate further using the logs:
docker-compose logs <container_name>
<container_name> can be found in results above.
To stop the zkValidium, use:
And to restart all the services:
Step 3: Test the Validium
Congratulations! Your local zkValidium is now up and running. Let's test its functionalities.
First, verify the block explorer by navigating to localhost:4001. You should see a page similar to this:
Now, let's add the network to your Web3 wallet by populating the necessary fields.
We'll use MetaMask for our example.
- Set the chain ID to be 1001.
- The currency symbol can be anything but we will use POL by default.
- The RPC node and block explorer containers can be found at ports 8123 and 4001, respectively.
Next, switch to the new network:
By default, an account with private key
0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 has been preloaded with tokens.
Import this account and you will see the balance shown up as 100000 POL:
You can now try a transaction by transferring some tokens to another account:
After confirming the transaction, check the updated balances:
You can also view the transaction details in the block explorer by clicking on the transaction details in MetaMask:
Step 4: Test the Bridge
The CDK stack comes with a native bridge with UI to allow you to transfer fund between the L1 and the L2 validium.
In this section, you will learn how to bridge fund from the L1 to the validium L2 and then bridge it back from the validium to the L1.
Before you can bridge any fund from the L1 to the validium L2, you also need to add the L1 RPC to MetaMask similar to what you have done in previous steps:
Switch to the L1 network and you will see the previously imported account already with ~999 POL on the L1 chain.
First, verify the bridge UI by navigating to localhost:8088. You should see a page similar to this and click on "Connect a wallet > MetaMask":
Select the previously imported account (0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266) to connect and once you are connected, you should see a page like this:
Enter the amount (e.g. 5) to bridge and click "Continue", you will see the "Confirm Bridge" page. Click "Bridge" and approve the transaction on the MetaMask pop-up:
Once the bridging is completed, you should see the "Activity" page like this:
Now let's bridge back the fund from the validium L2 to the L1 chain. Switch network on MetaMask to your validium chain and navigate back to localhost:8088. You should see both the updated L1 and L2 balances:
Enter an amount (e.g. 1) and follow the same process to bridge the fund back to the L1.
You cannot bridge back fund more than what you have previously bridged from L1 to the L2.
The L2->L1 bridging is slightly different than L1->L2 and you will see the "Activity" page like this after the transaction is executed:
Click "Finalise" and approve the transaction (Note: MetaMask will pop up a window to ask you to switch to the L1 network first). Then you will see this once the bridging is completed: