Skip to main content

⛓ī¸đŸ”—⛓ī¸ Template for IBC enabled Solidity contracts

This IBC app in Solidity template repo provides a starter project that serves as a starting point for building multichain smart contracts that leverage Polymer Hub to connect across rollups through our vIBC core contracts.

The repository is a GitHub template repository so you can click "Use this template" to create your own project repository without having the entire commit history of the template.

GitHub template

📋 Prerequisites​

The repo is compatible with both Hardhat and Foundry development environments.

  • Have git installed
  • Have node installed (v18+)
  • Have Foundry installed (Hardhat will be installed when running npm install)
  • Have just installed (recommended but not strictly necessary)

You'll need some API keys from third party's:

Some basic knowledge of all of these tools is also required, although the details are abstracted away for basic usage.

🧰 Install dependencies​

To compile your contracts and start testing, make sure that you have all dependencies installed.

From the root directory run:

just install

to install the vIBC core smart contracts and the Polymer registry as a dependency.

Additionally Hardhat will be installed as a dev dependency with some useful plugins. Check package.json for an exhaustive list.

Note: In case you're experiencing issues with dependencies using the just install recipe, check that all prerequisites are correctly installed. If issues persist with forge, try to do the individual dependency installations...

📁 Repository structure​

Video walkthrough: repository structure

⚙ī¸ Set up your environment variables​

Convert the .env.example file into an .env file. This will ignore the file for future git commits as well as expose the environment variables. Add your private keys and update the other values if you want to customize (advanced usage feature).

cp .env.example .env

This will enable you to sign transactions with your private key(s). If not added, the scripts from the justfile will fail.

Configuration file​

The configuration file is where all important data is stored for the just commands and automation. We strive to make direct interaction with the config file as little as possible.

By default the configuration file is stored at root as config.json.

However, it is recommended to split up different contracts/projects in the same repo into different config file in case you want to switch between them.

Store alternate config files in the /config directory and set

# .env file
CONFIG_PATH='config/alt-config.json'

to use a different config file.

Obtaining testnet ETH​

The account associated with your private key must have both Base Sepolia and Optimism Sepolia ETH. To obtain the testnet ETH visit:

🏃đŸŊ🏃đŸģ‍♀ī¸ Quickstart​

The project comes with a built-in dummy application called x-counter (which syncrhonizes a counter across two contracts on remote chains). You can find the contracts in the /contracts directory as XCounterUC.sol and XCounter.sol (the former when using the universal channel, the latter when creating a custom/private channel).

Universal channels​

Video walkthrough: Sending a packet over a universal channel

The easiest way to get onboarded is to use Universal channels. Universal channel is like an open port already deployed by Polymer to allow anyone to call a remote contracts. Universal channels utilize a contract which is known as Universal channel handler (UCH).

Users can utilize universal channels through deploying a Universal channel compatible contract. This can be done either from deploying a contract which inherits the UniversalChanIbcApp base contract) or implements the IbcUniversalPacketReceiver and IbcUniversalPacketSender interfaces. Once deployed, the dapp will be able to connect to the Universal Channel handler, define Universal packets which will then be wrapped into a regular IBC packet by the Universal Channel Handler and unwrapped by its counterparty on the destination chain. The Universal channel handler on the destination will then unwrap the the packet and send the data to defined address.

The configuration file that comes as default in the template repository, allows to quickly send a packet by running:

just send-packet base

To send a packet between the XCounterUC contract on Base Sepolia to OP Sepolia and vice versa.

Custom IBC channel​

There is a quick guide available that helps you send packets over a custom/private IBC channel. The channel is established through a session setup process, known as a handshake, which typically takes less than five minutes to complete. Once established, the private channel provides fault isolation from other applications, ensuring that only your contracts can communicate with each other, unlike universal channels.

To have your application be compatible with custom IBC channels, have it inherit the CustomChanIbcApp base contract.

Run the following command to go through a full E2E sweep of the project, using the default XCounter.sol contract:

# Usage: just do-it
just do-it

It does the following under the hood:

# Run the full E2E flow by setting the contracts, deploying them, creating a channel, and sending a packet
# Usage: just do-it
do-it:
    echo "Running the full E2E flow..."
    just set-contracts optimism XCounter false && just set-contracts base XCounter false
    just deploy optimism base
    just create-channel
    just send-packet optimism
    echo "You've done it!"

It makes sure you've got the correct contracts set, deploys new instances, creates a channel and sends a packet over the channel once created.

đŸ’ģ Develop your custom application​

The main work for you as a developer is to develop the contracts that make up your cross-chain logic.

You can use the contracts in the "/contracts/base" directory as base contracts for creating IBC enabled contracts that can either send packets over the universal channel or create their own channel to send packets over.

A complete walkthrough on how to develop these contracts is provided in the Developer Launchpad.

🕹ī¸ Interaction with the contracts​

When the contracts are ready, you can go ahead and interact with the contracts through scripts. There is a Justfile to for the most common commands, with the underlying scripts in the /scripts folder.

The /private folder within the scripts folder has scripts that you're unlikely to need to touch. The only scripts you'll (potentially) be interacting with are:

There's three types of default scripts in the project:

  • The deploy.js allows you to deploy your application contract. You may want to add additional deployment logic to the Hardhat script.
  • In the /contracts folder you'll find arguments.js to add your custom constructor arguments for automated deployment with the deploy.js script.
  • The send-packet.js script sends packets over an existing custom channel, and send-universal-packet.js is specifically for sending packets over a universal channel. You might want to add additional logic before or after sending the packet to customize your application.

For most of the actions above and more, there are just recipes that combine related logic and update the configuration file in an automated way.

Note: These are the default scripts provided. They provide the most generic interactions with the contracts to deploy, create channels and send packets. For more complicated use cases you will want to customize the scripts to your use case.

Deploy​

Video walkthrough: Setting and deploying contracts

Before deploying, make sure to update the config.json with your contract type to deploy for each of the chains you wish to deploy to.

Set contracts to config​

Do this by running:

# Usage: just set-contracts [chain] [contract_type] [universal]
just set-contracts optimism MyContract true

to deploy MyContract artefact to the Optimism (Sepolia) chain.

IMPORTANT: This is where you set if your contract uses universal or custom channels. Make sure this corresponds to the base contract you've inherited from when developing your application (UniversalChanIbcApp or CustomChanIbcApp).

Constructor arguments​

By default any application inheriting a base IBC application contract will need a dispatcher or universal channel handler address passed into the constructor. Obviously you might have other constructor arguments you may want to add. To still make use of the just deploy source destination recipe, add your arguments to the arguments.js file

/contracts/arguments.js
module.exports = {
    "XCounter": [],
    "XCounterUC": [],
    // Add your contract types here, along with the list of custom constructor arguments
    // DO NOT ADD THE DISPATCHER OR UNIVERSAL CHANNEL HANDLER ADDRESSES HERE!!!
    // These will be added in the deploy script at $ROOT/scripts/deploy.js
};

Finally: deploy​

Then run:

# Usage: just deploy [source] [destination]
just deploy optimism base

where the script will automatically detect whether you are using custom or universal IBC channels.

The script will take the output of the deployment and update the config file with all the relevant information.

Before moving on, you'll want to check if the variables in your .env and config files line up with what is stored in the actual deployed contracts... especially when you're actively playing around with different configuration files and contracts.

To do a sanity check, run:

# Usage: just sanity-check
just sanity-check

Create a channel​

If you're using universal channels, channel creation is not required. Your contract will send and receive packet data from the Universal channel handler contract which already has a universal channel to send packets over. You can directly proceed to sending (universal) packets in that case.

Video walkthrough: Creating a custom IBC channel

To create a custom channel, run:

just create-channel

This creates a channel between base and optimism. Note that the ORDER MATTERS; if you picked optimism as the source chain (first argument) above, by default it will create the channel from optimism and vice versa.

The script will take the output of the channel creation and update the config file with all the relevant information.

Send packets​

Finally Run:

# Usage: just send-packet
just send-packet optimism

to send a packet over a channel (script looks at the config's isUniversal flag to know if it should use the custom or universal packet). You can pick either optimism or base to send the packet from.