4 - Balancer-v2

L1X-EVM is a robust and reliable system that is ready for production use in the DeFi market. Our demo highlights the practical Host and Runtime functions of the L1X L1 layer and showcases its capabilities using a complex use case, the balancer-v2 protocol.

Step 1: Setting Up Your Environment

• 1.1. Create an empty folder for this demonstration:

   $ mkdir -p $HOME/l1x-home/l1x-demo-home/

• 1.2. Change your current directory to the newly created folder:

  $ cd $HOME/l1x-home/l1x-demo-home/

Step 2: Download the Demo Template

• 2.1. Make sure you can access the l1x-forge tool from your command line. If you don't have l1x-forge installed, follow the instructions in Step 2: Checking the L1X Tool before proceeding.

• 2.2. Use the l1x-forge command to create a new project workspace. We'll name it l1x_demo04_balancer_v2 and use the template l1x-balancer-v2:

  $ l1x-forge new --name l1x_demo04_balancer_v2 --template l1x-balancer-v2

• 2.3. After running the command, you'll receive a confirmation message indicating the successful creation of the "l1x_demo04_balancer_v2" contract:

  Created contract l1x_demo04_balancer_v2

• 2.4. Your workspace will now be populated with content from the template.

   	$ exa -T -L 1 ./l1x_demo04_balancer_v2
   		./l1x_demo04_balancer_v2
   		├── Cargo.toml
   		├── devbox.json
   		├── devbox.lock
   		├── devnet-services-dc.yml
   		├── l1x-artifacts
   		├── l1x-conf
   		├── l1x-eth-contracts
   		├── l1x-evm-artifacts
   		├── l1x-traces
   		├── l1x-utils
   		├── process-compose-devnode.yaml
   		├── README.md
   		├── rust-toolchain.toml
   		└── rustfmt.toml

Step 3: Starting with Workspace Workflow Script Commands

• 3.1. Introduction to Devbox Shell and Workflow Commands

  If you're new to the l1x-sde template workspace, it's a good idea to familiarize yourself with the basics of the devbox shell and workflow commands. This will help you get started more smoothly. You can review the following links for an overview:

  • Step 4: Understanding Configuration Files and Default Settings

  • Step 5: Getting Started with the Devbox Shell

• 3.2. Default Commands to Begin With

  To start using the workspace, there are some default commands you can use:

  • Activate the Shell: To access the devbox shell, simply enter the following command in your terminal:

  $ devbox shell

  • List Default Commands: To see a list of the built-in default commands available in the devbox shell, you can use the following command:

    (devbox)$ devbox run -l | sort
    * 01_init_setup
    * 01_start_hardhat
    * 01_teardown_setup
    * 02_check_chain_state
    * 02_check_devnet_db_state
    * 02_prune_devnode
    * 02_start_devnode
    * 02_stop_devnode
    * 11_clean_logs
    * 11_clean_objs
    * 20_01_compile_evm_erc20
    * 20_02_compile_evm_erc201
    * 20_03_compile_evm_weth
    * 20_04_compile_evm_rateprovider
    * 20_05_compile_evm_rateProvider1
    * 20_06_compile_evm_authorizer
    * 20_07_compile_evm_vault
    * 20_08_compile_evm_protocolfee
    * 20_09_compile_evm_pool
    * 20_compile_evm_cmd
    * 42_deploy_cli_evm_bpool
    * 42_deploy_cli_evm_cmd
    * 42_init_cli_evm_bpool
    * 42_init_cli_evm_cmd
    * 43_01_test_cli_evm_getpoolid
    * 43_02_gettokenlist_calldata
    * 43_03_test_cli_evm_gettokenlist
    * 43_04_approve_tokens_calldata
    * 43_05_test_cli_evm_approve_tokens
    * 62_install_forge_evm_cmd_force_deploy
    * 63_install_forge_evm_cmd_reuse_deploy
    * 81_01_install_forge_evm_erc20
    * 81_02_install_forge_evm_erc201
    * 81_03_install_forge_evm_weth
    * 81_04_install_forge_evm_rateprovider
    * 81_05_install_forge_evm_rateprovider1
    * 81_06_install_forge_evm_authorizer
    * 81_07_install_forge_evm_vault
    * 81_08_install_forge_evm_protocolfee
    * 81_09_install_forge_evm_pool
    * 82_01_install_forge_evm_bpool
    Available scripts:

• Initialize the Workspace: To prepare your workspace for building and testing, run:

   (devbox)$ devbox run 01_init_setup

Now you have all the necessary tools and packages to work with the demo template workspace.

Step 4: Building Balancer-v2 Smart Contracts for l1x-evm

In this section, we'll walk you through the process of building and deploying the BalancerPool smart contracts.

4.1 For this demonstration, we'll use the super key from the predefined wallet in l1x-conf/l1x_dev_wallets.yaml.

• This same key serves as the owner for the pool, as specified in the l1x-eth-contracts/Balancer-v2/pkg/pool-stable/deploy/input.json file.

4.2 Start the hardhat local node

Open your workspace devbox shell terminal and run this command:

(devbox)$ devbox run 01_start_hardhat

4.3 Compiling and Deploying the Contract for l1x-evm

To compile and deploy the contracts located at l1x-eth-contracts/Balancer-v2/pkg/pool-stable, execute this command:

(devbox)$ devbox run 82_01_install_forge_evm_bpool

When you run this command, it will:

• Generate EVM bytecode object files in the ./l1x-evm-artifacts folder, as shown below:

  exa -T -L 1 ./l1x-evm-artifacts
  ./l1x-evm-artifacts
  ├── creationAuthorizer.txt
  ├── creationCode20.txt
  ├── creationCode202.txt
  ├── creationCodePool.txt
  ├── creationProtocolFee.txt
  ├── creationRateProvider.txt
  ├── creationRateProvider2.txt
  ├── creationVault.txt
  └── creationWeth.txt

• Automatically update the contract address registry at l1x-conf/config-contract-address-registry.yaml.

• This updated address from the contract address registry will be used in the transaction JSON payload files located in l1x-conf/scripts to interact with the deployed contracts, as shown below:

    exa -T -L 1 ./l1x-conf/scripts
    ./l1x-conf/scripts
    ├── 043-01-test-evm-pool-getpoolid.json
    ├── 043-02-test-evm-pool-gettokenlist.json
    ├── 043-03-test-evm-approve-erc20.json
    ├── 043-04-test-evm-approve-erc201.json
    ├── 043-05-test-evm-init-pool.json

That's it! You've successfully completed the steps for building and deploying the smart contracts.

Step 5: Setting Up Local Development Network Services

In this step, we will walk you through the process of configuring local development l1x-chain network.

• 5.1 Choose the Chain Type: To begin, select the "L1X_CFG_CHAIN_TYPE": "local_devnet" option. Next, open a new terminal and activate the devbox shell:

  $ devbox shell

• 5.2 Start the Devnode Services: While in the devbox shell, run the following command:

  (devbox)$ devbox run 02_start_devnode

• 5.3 Wait for Services to Initialize: After executing the previous command, please wait for approximately 160 seconds. During this time, the services will start up and become operational. You will also observe the L1X node beginning to produce blocks.

• 5.4 Verify DevNet Service Status: To ensure that everything is running smoothly, use the following command to check the service status:

  (devbox)$ devbox run 02_check_chain_state

  

  (devbox)$ devbox run 02_check_devnet_db_state

  

• 5.5 Troubleshooting: Occasionally, we might encounter a problem where the l1x-node-client server and the cassandra DB service do not sync properly, as indicated by the state shown in the image below.

• To fix this issue and get your setup back on track, follow these simple steps:

  (devbox)$ devbox run 02_stop_devnode
  (devbox)$ devbox run 02_prune_devnode
  (devbox)$ devbox run 02_start_devnode

These commands will help reset and restart the necessary components. Your setup should work smoothly after completing these steps.

Step 6: Initializing the Deployed Pool

6.1 Obtain the PoolID

• To retrieve the PoolID from the deployed pool instance, refer to the tag key creationCodePool.txt in the l1x-conf/config-contract-address-registry.yaml address registry file. In this case, use the address 09796da51ef92af5ccb4965d3fe10b9cae61db0c. And update the file l1x-conf/scripts/043-01-test-evm-pool-getpoolid.json with noted info

• In your devbox shell terminal, execute the following command:

(devbox)$ devbox run 43_01_test_cli_evm_getpoolid

• Take note of the poolID, which is highlighted within the "data:" field. In this context, it is 0x8c9f70606ca7d0ba5639a002e1889a1c4a92bd54000000000000000000000000.

6.2 Obtain the TokenList

• Update input.json in l1x-eth-contracts/Balancer-v2/pkg/pool-stable/deploy/ with the PoolID you obtained.

• Generate ABI encoded calldata to retrieve the tokenlist from creationVault.txt.

(devbox)$ devbox run 43_02_gettokenlist_calldata

• Take note of the highlighted calldata, which you can find in the "data:" field. In this case, it is 0xf94d46688c9f70606ca7d0ba5639a002e1889a1c4a92bd54000000000000000000000000.

• To obtain the TokenList from the deployed vault instance, refer to the tag key creationVault.txt in the l1x-conf/config-contract-address-registry.yaml address registry file. Use the address 199202a07fd7bd18e6f0cf252d694ec84f37f40b for this context, and update 043-02-test-evm-pool-gettokenlist.json in l1x-conf/scripts/ with the information you noted.

• In your devbox shell terminal, run the following command:

(devbox)$ devbox run 43_03_test_cli_evm_gettokenlist

• Take note of the highlighted "data:" field, and then decode the ABI encoded raw data to get the following token address information:

  • ERC202: 0x25c77f9c598ecc4bc3eaeb58188c07d80605a9ea

  • Pool: 0x8c9f70606ca7d0ba5639a002e1889a1c4a92bd54

  • ERC20: 0xe088b9ad19e5766ecdab0a2e1ccdc7f061ffe155

6.3 Approving ERC20 and ERC202 Tokens for the Vault

• Open input.json located at l1x-eth-contracts/Balancer-v2/pkg/pool-stable/deploy/. Update the token balance to be approved for the Vault. For this demo, we'll approve a balance of One hundred million tokens.

• Generate ABI encoded calldata to approve the tokens for the Vault using the following command:

(devbox)$ devbox run 43_04_approve_tokens_calldata

Take note of the highlighted calldata and update the l1x-conf/scripts/043-03-test-evm-approve-erc20.json and l1x-conf/scripts/043-04-test-evm-approve-erc201.json files with the calldata and the appropriate token contract addresses.

• Execute the following command:

(devbox)$ devbox run 43_05_test_cli_evm_approve_tokens

This process approves ERC20 and ERC202 tokens for the Vault.

6.4 Initializing the Pool

To kickstart your deployed pool, follow these simple steps:

• Open the input.json file found in l1x-eth-contracts/Balancer-v2/pkg/pool-stable/deploy/. Update it with the information you collected during Step 6.2: Obtaining the TokenList. The image below highlights the fields that need updating:

• Now, let's generate ABI encoded calldata to initialize your pool. In your devbox shell terminal, use the following command:

  (devbox)$ devbox run 43_06_init_pool_calldata

• You'll see the generated calldata, which is highlighted in the "data:" field.

• Find the creationVault.txt tag key in the l1x-conf/config-contract-address-registry.yaml address registry file. Depending on your situation, choose the appropriate address. For our example, we'll assume the address is 00578931a9d5b5ca359c5b9bcd0a4efb6cef1a7d. Update the 043-05-test-evm-init-pool.json file in l1x-conf/scripts/ with this information:

• Finally, to complete the initialization of your pool, run this command in your devbox shell terminal:

(devbox)$ devbox run 43_07_test_cli_evm_init_pool

Step 7: Joining the Deployed Pool

Now, let's join the pool using the Ava key from the default wallet.

• Open the input.json file in l1x-eth-contracts/Balancer-v2/pkg/pool-stable/deploy/. Update it with the joinPoolCall::tokenlist information from Step 6.2: Obtaining the TokenList. Just like before, the image below shows the fields that need your attention:

• To generate the ABI encoded calldata for joining the pool, run this command in your devbox shell terminal:

(devbox)$ devbox run 43_08_join_pool_calldata

• Make a note of the highlighted calldata, located in the "data:" field.

• Find the creationVault.txt tag key in the l1x-conf/config-contract-address-registry.yaml address registry file, and, based on your context, select the appropriate address. For our example, let's stick with 00578931a9d5b5ca359c5b9bcd0a4efb6cef1a7d. Update the 043-05-test-evm-init-pool.json file in l1x-conf/scripts/ with this information:

• To finish the process of joining the pool, execute this command in your devbox shell terminal:

(devbox)$ devbox run 43_09_test_cli_evm_join_pool

now user Ava is part of the pool!

By following these steps, you can successfully initialise and join the deployed pool.