From 1aa535c0e275564da44b846e2eb313c1775b1e9c Mon Sep 17 00:00:00 2001 From: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Thu, 1 Aug 2024 12:09:53 -0600 Subject: [PATCH] docs: cleanup zk chain tutorial --- content/tutorials/custom-zk-chain/10.index.md | 67 ++++++++++--------- .../20.customizing-your-chain.md | 55 ++++++++------- content/tutorials/custom-zk-chain/_dir.yml | 7 +- 3 files changed, 68 insertions(+), 61 deletions(-) diff --git a/content/tutorials/custom-zk-chain/10.index.md b/content/tutorials/custom-zk-chain/10.index.md index e1512568..dd56dfc4 100644 --- a/content/tutorials/custom-zk-chain/10.index.md +++ b/content/tutorials/custom-zk-chain/10.index.md @@ -3,11 +3,11 @@ title: Getting Started with ZK Chains description: Create and run your first ZK chain. --- -This tutorial shows you how to use the `zk_inception` CLI to run an Elastic chain ecosystem and custom zk chain locally: +This tutorial shows you how to use the `zk_inception` CLI to run an Elastic Chain ecosystem and custom ZK chain locally: -- You'll set up a local **Elastic chain ecosystem** +- You'll set up a local **Elastic Chain ecosystem** - You'll create a standard **ZK chain** and deploy a smart contract to it -- You'll create a second ZK chain that uses a **custom base token** +- You'll create a second ZK chain that uses a **custom ERC20 base token** ## Prerequisites @@ -23,11 +23,11 @@ If you previously have `foundry-zksync` installed, reinstall the normal version of [foundry](https://book.getfoundry.sh/getting-started/installation) for this tutorial. :: -## Setting up the Elastic chain ecosystem +## Setting up the Elastic Chain ecosystem There are two components needed for running a ZK chain locally: -1. An Elastic chain ecosystem to manage different chains +1. An Elastic Chain ecosystem to manage different chains 2. A chain deployed within the ecosystem To setup both of these components, can use the `zk_inception` CLI. @@ -37,7 +37,7 @@ You can use `cargo` to install the CLI with the command below: cargo install --git https://github.com/matter-labs/zksync-era/ --locked zk_inception --force ``` -Once you have that installed, the first step is to create a new ecosystem with the `zk_inception` command: +Once you have that installed, the first step is to create a new ecosystem with the `ecosystem create` command: ```bash zk_inception ecosystem create @@ -88,28 +88,28 @@ $ zk_inception ecosystem create By running this command and selecting these options, you just: -- Created a new ecosystem called `my-elastic-chain`, which can contain many chains. +- Created a new ecosystem called `my_elastic_chain`, which can contain many chains. - Cloned the `zksync-era` repository inside the `my_elastic_chain` folder. - Chose to use a local network to act as the L1. -This means we'll have to run a local reth docker container as well (don't worry, we've setup everything you need for this too!). +This means we'll have to run a local reth node as well (don't worry, we've setup everything you need for this too!). - Created a new chain called `zk_chain_1` and set it as your default chain. - Set the chain id to `271`. - Chose the default wallet configuration. - Selected to not use proofs, which makes testing more lightweight. - Chose a standard rollup for the data availability. - Selected ETH to use as the base token. -- Started the containers for the ecosystem and `zk_chain_1` in Docker. +- Started the containers for the ecosystem in Docker. Inside the generated `my_elastic_chain` folder, you should now have the following contents: -- `ZkStack.yaml`: a config file for the ecosystem. -- `chains`: a folder with configurations for each chain created -- `configs`: configuration for the deployments and wallets -- `volumes`: dependencies for running local nodes -- `zksync-era`: a clone of the `zksync-era` repository -- `docker-compose.yml`: a docker compose file to start up a local environment +- `ZkStack.yaml`: a configuration file for the ecosystem. +- `chains`: a folder with configurations for each chain created. +- `configs`: configuration for the deployments and wallets. +- `volumes`: dependencies for running local nodes. +- `zksync-era`: a clone of the `zksync-era` repository. +- `docker-compose.yml`: a Docker compose file to start up a local environment. -### Deploying the ecosystem +## Deploying the ecosystem You've just set up your ecosystem and chain, and have two Docker containers running: a postgres database for your chain, and a reth node for the local L1 chain. @@ -117,7 +117,7 @@ a postgres database for your chain, and a reth node for the local L1 chain. The L1 chain is already running, but your ecosystem and chain aren't deployed yet. The next step is to deploy your ecosystem contracts to the L1 and register your chain to the ecosystem. -Move into the elastic chain folder: +Move into the ecosystem folder: ```bash cd my_elastic_chain @@ -156,7 +156,7 @@ To summarize, the `init` command: - Checks to see if your environment has the necessary dependencies. - Compiles and deploys all of necessary contracts for the ecosystem. -- Deploys the `zk_chain_1` to the ecosystem. +- Deploys `zk_chain_1` to the ecosystem. - Sets up a database for the default chain (in this case `zk_chain_1`). - Deploys a paymaster contract and some test ERC20 contracts (if selected) to use for development. @@ -177,9 +177,9 @@ Inside `my_elastic_chain/chains/zk_chain_1/configs`, you can find six more confi 1. `contracts.yaml`: configurations for all the L1 & L2 contracts. 1. `external_node.yaml`: configurations for the chain's node server. 1. `general.yaml`: general configurations. -1. `wallets.yaml`: all wallets that you are using for this chain. -1. `secrets.yaml`: secrets that are individual for every chain. 1. `genesis.yaml`: chain specific configurations with parameters that were used during genesis. +1. `secrets.yaml`: secrets that are individual for every chain. +1. `wallets.yaml`: all wallets that you are using for this chain. ::callout{icon="i-heroicons-light-bulb"} Never commit your private keys or sensitive secrets to a public repository! @@ -193,20 +193,20 @@ The last step here is to start a server for `zk_chain_1`: zk_inception server ``` -With this, your L1 chain should be running at port `8545`, and the `zk_chain_1` should be running at port `3050`. +With this, your L1 chain should be running at port `8545`, and the `zk_chain_1` node should be running at port `3050`. -### Funding a wallet on your chain +## Funding a wallet on your chain Because you chose to use a local reth node for your L1 and selected ETH as the base asset, you have access to several rich wallets on the L1 that you can use to bridge ETH to `zk_chain_1`. -You can do this by running the command below using the `zksync-cli`: +Open a new terminal and run the command below to bridge some ETH to `zk_chain_1` using the `zksync-cli`: ```bash npx zksync-cli bridge deposit --rpc=http://localhost:3050 --l1-rpc=http://localhost:8545 ``` -For testing purposes, use the first rich wallet as both the sender and recipient: +For testing purposes, we'll use one of the rich wallets as both the sender and recipient: ```shell ? Amount to deposit 10 @@ -214,7 +214,7 @@ For testing purposes, use the first rich wallet as both the sender and recipient ? Recipient address on L2 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049 ``` -To see that it's worked, let's check the balance of that address on the `zk_chain_1`: +To see that it worked, let's check the balance of that address on `zk_chain_1`: ```bash zksync-cli wallet balance --address 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049 --rpc http://localhost:3050 @@ -224,7 +224,7 @@ Now this address has ETH available on `zk_chain_1` to use for testing. ## Deploying a contract to chain 1 -Now that your chain is deployed and your wallet is funded, let's create a template contract and deploy it to chain `zk_chain_1`: +Now that your chain is deployed and your wallet is funded, let's create a template contract and deploy it to `zk_chain_1`: Move out of your ecosystem folder and initialize a new hardhat project using the `zksync-cli`: @@ -233,19 +233,20 @@ npx zksync-cli@latest create --template qs-hello-zksync zk-chain-test cd zk-chain-test ``` -In the `hardhat.config.ts` file, change the default network on line 6 to `dockerizedNode`: +Use the same private key for the rich wallet: -```bash -defaultNetwork: "dockerizedNode", +```shell +? Private key of the wallet responsible for deploying contracts (optional) +0x7726827caac94a7f9e1b160f7ea819f172f7b6f9d2a97f992c38edeab82d4110 ``` -In the `.env` file, add the private key of the wallet you just funded on your chain: +In the `hardhat.config.ts` file, change the default network on line 6 to `dockerizedNode`: -```env -WALLET_PRIVATE_KEY=0x7726827caac94a7f9e1b160f7ea819f172f7b6f9d2a97f992c38edeab82d4110 +```bash +defaultNetwork: "dockerizedNode", ``` -Finally, compile the contract and deploy to `zk_chain_1` +Finally, compile the contract and run the deploy script: ```bash yarn compile && yarn deploy diff --git a/content/tutorials/custom-zk-chain/20.customizing-your-chain.md b/content/tutorials/custom-zk-chain/20.customizing-your-chain.md index 5e4664c4..72a95ebb 100644 --- a/content/tutorials/custom-zk-chain/20.customizing-your-chain.md +++ b/content/tutorials/custom-zk-chain/20.customizing-your-chain.md @@ -1,6 +1,6 @@ --- title: Customizing your ZK chain -description: Customizing your ZK chain's base token. +description: Create a ZK chain with a custom ERC20 base token. --- @@ -15,13 +15,13 @@ For now, you have the ability to whitelist tokens in your local ecosystem. The overall flow for setting up a local chain with a custom ERC20 base token looks like this: -1. Deploy an ERC20 token to the L1 -1. Send ERC20 tokens to the governor address on L1 -1. Create your new chain that uses the ERC20 token and set it as the default -1. Initialize the new chain in the ecosystem -1. Bridge tokens from L1 to L2 +1. Deploy an ERC20 token to the L1. +1. Send ERC20 tokens to the governor address on the L1. +1. Create your new chain that uses the ERC20 token and set it as the default. +1. Initialize the new chain in the ecosystem. +1. Bridge tokens from the L1 to your new chain. -### Deploying an ERC20 token +## Deploying an ERC20 token For the first step of this flow, let's make a new hardhat project. @@ -123,7 +123,7 @@ Rename the module file with the command below: mv ignition/modules/Lock.ts ignition/modules/CustomBaseToken.ts ``` -Replace the module file with the code below: +Then, replace the module file with the code below: ```ts import { buildModule } from "@nomicfoundation/hardhat-ignition/modules"; @@ -146,7 +146,10 @@ To deploy the token contract, run: npx hardhat ignition deploy ./ignition/modules/CustomBaseToken.ts --network localRethNode ``` -Let's verify that the tokens were minted to the owner using the `cast` CLI: +Select `y` to confirm to deploy the contract to the `localRethNode`. +After deploying, the token contract address should be logged in your console. + +Let's verify that the tokens were minted to the deployer address using the `cast` CLI: ```bash cast balance --erc20 0xYOUR_TOKEN_ADDRESS 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049 --rpc-url http://localhost:8545 @@ -167,9 +170,13 @@ To verify that this worked, check the balance of the governor's address: cast balance --erc20 0xYOUR_TOKEN_ADDRESS 0x_YOUR_GOVERNOR_ADDRESS --rpc-url http://localhost:8545 ``` -### Creating a new chain +## Creating a new chain + +Now that your ERC20 token is deployed and the governor's address is funded with that token, you can create a new chain. + +First, shut down the node server running for `zk_chain_1`. -Now that your ERC20 token is deployed and the governor's address is funded with that token, you can create a new chain: +Move back into the `my_elastic_chain` ecosystem folder and run the `chain create` command: ```bash zk_inception chain create @@ -233,12 +240,12 @@ Now that the chain is initialized, you can start the chain server: zk_inception server ``` -### Bridging the base token to your chain +## Bridging the base token to your chain The last step is to bridge some ERC20 tokens from the L1 to the new chain. -Base tokens can not be minted on L2 without being backed by the corresponding L1 amount. In the future, there will be more flexibility for this. +Base tokens can not be minted on the L2 without being backed by the corresponding L1 amount. In the future, there will be more flexibility for this. -You can use the `zksync-cli` to bridge the tokens with the command below: +Open a new terminal and use the `zksync-cli` to bridge the tokens with the command below: ```bash npx zksync-cli bridge deposit --token 0x_YOUR_TOKEN_ADDRESS --rpc=http://localhost:3050 --l1-rpc=http://localhost:8545 @@ -262,7 +269,7 @@ The CLI will display the amount as ETH, but in reality, it's our bridged ERC20 t And that's it! You are now running a local ZK chain that uses a custom ERC20 base token. You can follow the steps in the previous section to deploy a contract to the new chain. -### Bridging ETH to your chain +## Bridging ETH to your chain If your ERC20 token bridged to the L2 "looks" like ETH, then what happens if you bridge ETH to your custom chain? @@ -280,19 +287,19 @@ npx zksync-cli bridge deposit --rpc=http://localhost:3050 --l1-rpc=http://localh ? Recipient address on L2 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049 ``` -If you run the previous command to check the balance again, note how the balance is the same. +If you run the previous command to check the base token balance again, note how the balance is still `5`. This is because you have to look at the L2 token balance for ETH. To find the L2 token address for ETH, you can use the `l2TokenAddress` method available through `zksync-ethers`. To try this out, open the `zk-chain-test` folder from the previous section, -and run the command below to create a new script file: +and run the commands below to create a new script file: ```bash mkdir scripts touch scripts/checkBalance.ts ``` -Next, copy and paste the script below to the `checkBalance.ts` file: +Next, copy and paste the script below to into the `checkBalance.ts` file: ```ts import { ETH_ADDRESS_IN_CONTRACTS } from "zksync-ethers/build/utils.js"; @@ -310,20 +317,20 @@ async function main(){ main(); ``` -Run the script with the command below: +Run the script with the `hardhat run` command: ```bash npx hardhat run scripts/checkBalance.ts ``` -You should see the output below: +You should see the output below showing the same amount of ETH you bridged: ```shell L2 ETH Address: 0x_YOUR_ETH_TOKEN_ADDRESS L2 ETH Balance 🎉: 20000000000000000000n ``` -### Switching between chains and shutting down the ecosystem +## Switching between chains and shutting down the ecosystem You can switch in between different chains without losing any state by shutting down the chain server and running the command below: @@ -344,10 +351,10 @@ To restart the ecosystem and run your custom ZK chain again, follow the steps be 1. In the ecosystem folder, run `zk_inception containers`. 1. Redeploy your ERC20 contract to the L1. -1. Update the base token address in `chains/custom_zk_chain/configs/contracts.yaml` under `l1.base_token_addr` and in - `chains/custom_zk_chain/ZkStack.yaml` under `base_token.address`. +1. Update the base token address in `my_elastic_chain/chains/custom_zk_chain/configs/contracts.yaml` under `l1.base_token_addr` and in + `my_elastic_chain/chains/custom_zk_chain/ZkStack.yaml` under `base_token.address`. 1. Send ERC20 tokens to the governor address. -1. Initialize the ecosystem with `zk_inception ecosystem init` and choose to not deploy the Paymaster or ERC20 addresses +1. Initialize the ecosystem with `zk_inception ecosystem init` and choose to not deploy the Paymaster or ERC20 test tokens (this requires funding another address). 1. Start the chain server with `zk_inception server`. 1. Bridge ERC20 tokens from the L1 to L2. diff --git a/content/tutorials/custom-zk-chain/_dir.yml b/content/tutorials/custom-zk-chain/_dir.yml index e103e092..fe9779c9 100644 --- a/content/tutorials/custom-zk-chain/_dir.yml +++ b/content/tutorials/custom-zk-chain/_dir.yml @@ -11,11 +11,10 @@ tags: - tutorial summary: Create, customize, and run your first ZK chain locally. description: - In this tutorial, you will get familiar with the ZK Inception CLI by creating a local elastic chain ecosystem, - creating a default local ZK chain, and deploying a contract to that chain. Next, you will create a new ZK chain that - uses a custom ERC20 base token. + In this tutorial, you will get familiar with the ZK Inception CLI. You will create a local Elastic Chain ecosystem and + deploy a contract to a ZK chain. Next, you will create a new ZK chain that uses a custom ERC20 base token. what_you_will_learn: - - How to create and locally run an elastic chain ecosystem. + - How to create and locally run an Elastic Chain ecosystem. - How to create a ZK chain and deploy a contract to it. - How to setup a ZK chain with a custom base token. updated: 2024-08-01