alagbe003 / polyverse

⛓️🔗⛓️ IBC-Enabled Solidity Contracts Template

Welcome to a starter project designed to kickstart your journey into building Inter-Blockchain Communication (IBC) enabled Solidity contracts. This template is tailored for projects aiming to interconnect rollups or other blockchain architectures via the Polymer Hub, leveraging the power of vIBC core contracts.

As a GitHub template repository, you're only a click away from beginning your own project. Simply select "Use this template" to start a new repository for your project, free from the baggage of the template's commit history.

📚 Extensive Documentation

While this README provides a foundational overview, for an in-depth guide on building IBC-enabled DApps with Solidity, refer to the official Polymer documentation. Here, you will find everything from basic concepts to advanced contract interactions explained.

📋 Prerequisites

This template offers flexibility by ensuring compatibility with both Hardhat and Foundry, two of the leading development environments for Ethereum smart contract development. This allows you to choose the environment that best suits your workflow and preferences.

---

Before diving into the development, make sure to set up your development environment according to the chosen tool (Hardhat or Foundry). Each has its own setup process, and being familiar with the basics of Solidity and smart contract development is highly recommended.

Happy building! May your journey into the IBC-enabled ecosystem be both exciting and fruitful.

• 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:

• Optimism Sepolia and Base Sepolia Blockscout Explorer API keys
• Have an Alchemy API key for OP and Base Sepolia

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 as a dependency.

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

⚙️ 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.

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:

• Optimism Sepolia Faucet
• Base Sepolia Faucet

🏃🏽🏃🏻‍♀️ Quickstart

The project comes with a built-in dummy application called x-counter. 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 IBC channel).

Custom IBC channel

The default setup (.env, config.json) are preconfigured to try to send packets over a custom channel.

Run the following command to go through a full E2E sweep of the project:

# 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 && just set-contracts base XCounter
    just deploy optimism base false
    just create-channel
    just send-packet optimism false
    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.

Note: by default the sim-client is used to improve latency. This is useful for iterative development and testing BUT also insecure as it involves no proofs. Make sure to move to the client with proofs by running another just command...

# Usage: just switch-client [universal=true]
just switch-client false

Check if the packet got through on the Polymer IBC explorer.

Universal channels

Soon...

💻 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 official Polymer documentation.

🕹️ 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.

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

• _deploy.js and deploy-config.js allow you to deploy your application contract
• _create-channel.js and create-channel-config.js creates a channel
• send-packet.js sends packets over an existing custom channel, and send-universal-packet.js is specifically for sending packets over a universal channel

For every script you'll find a field in the configuration file!!

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. See advanced usage for more info.

Deploy

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

Do this by running:

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

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

Then run:

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

for an application that will use a universal channel, or:

# or
just deploy optimism base false

for an application that uses custom 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 [universal=true]
just sanity-check false

Pick false for custom channels and true (or leave empty) for universal channels.

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.

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.

Check out the channel tab in the explorer to find out if the correct channel-id's related to your contracts were updated in the config.

Send packets

Finally Run:

# Usage: just send-packet [source] [universal]
just send-packet optimism true

to send a packet over a universal channel. You can pick either optimism or base to send the packet from.

Or run:

just send-packet optimism false

to send a packet over a custom channel. You can pick either optimism or base to send the packet from.

Verify, don't trust

Note: by default the sim-client is used to improve latency. This is useful for iterative development and testing BUT also insecure as it involves no proofs. Make sure to move to the client with proofs by running another just command...

# Usage: just switch-client [universal=true]
just switch-client false
This command will switch to using the op-stack client with proofs, ensuring that the relayer is proving what is being submitted every step along the way, thereby eliminating any trust assumptions on the relayer.

🦾 Advanced Usage
For advanced users, there are multiple customizations to follow. These include configuring the config.json manually and/or running the scripts without using just.

For example, to execute the last action to send a packet on a universal channel, you can use the following command:
npx hardhat run scripts/send-universal-packet.js --network base
This command sends a universal packet from the contract specified in the config.sendUniversalPacket field in the config.

🤝 Contributing
We welcome and encourage contributions from our community! Here’s how you can contribute:

Fork the Repository: Start by forking this repository.
Apply the Improvements: Optimize something or add support for additional developer tooling? Add your changes!
Create a Pull Request: Once you're ready and have tested your added code, submit a PR to the repo, and we'll review it as soon as possible.
If there's an issue that has the help wanted label or good first issue, those are up for grabs. Assign yourself to the issue so people know you're working on it. Alternatively, you can open an issue for a new idea or piece of feedback.

💡 Questions or Suggestions?
Feel free to open an issue for questions, suggestions, or discussions related to this repository. For further discussion as well as a showcase of some community projects, check out the Polymer developer forum.

Thank you for being a part of our community!


I made some grammatical improvements and formatting adjustments for clarity and consistency.