Demo dApps for Polymer

Welcome to the official repository for Polymer demo applications! This repository serves as a centralized hub for the official (maintained by the Polymer Labs team and used in the official docs) demo apps, showcasing the capabilities and use cases of Polymer x IBC interoperability.

🦸🏼🦸🏾‍♂️ Community projects 🦸🏾‍♀️🦸🏻

We highly encourage our community to build new demos and showcase them! To help visibility of these projects, they can be added to the community demo dApps repo in the PolymerDevs GitHub org.

📚 Documentation

There's some basic information here in the README but all of the dApps found here are documented more extensively in the official Polymer documentation.

📋 Prerequisites

The demo dapps repository has been based off of the project structure found in the IBC app template for Solidity so it has the same requirements:

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

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

🧱 Repository Structure

This repository has a project structure that set it up to be compatible with the Hardhat and Foundry EVM development environments, as in the IBC app template for Solidity repo.

The main logic specific to the dApps can be found in the /contracts directory:

# Example tree structure with only one custom dApp, x-ballot-nft
contracts
├── XCounter.sol
├── XCounterUC.sol
├── base
│   ├── CustomChanIbcApp.sol
│   ├── GeneralMiddleware.sol
│   └── UniversalChanIbcApp.sol
├── x-ballot-nft
│   ├── XBallot.sol
│   └── XProofOfVoteNFT.sol
└── x-ballot-nft-UC
    ├── XBallotUC.sol
    └── XProofOfVoteNFTUC.sol

The /contracts directory always contains a /base directory where custom developed contract will inherit from to quickly get IBC compatibility. Additionally, you'll find the x-counter example from the IBC app template repo.

The additional folders are the custom developed applications.

🦮 Dependency management

This repo depends on Polymer's vibc-core-smart-contracts which are tracked as git submodules.

There are two ways to install these dependencies.

Using Foundry

If you have Foundry installed, simply run:

forge install

to install the dependencies and:

forge update

to look for and install updates.

Using git submodules directly

If you prefer not to use Foundry / Forge, you can use git submodules directly.

After cloning the repo, run this command additionally:

git submodule update --init --recursive

Find more documentation on using git submodules from the official docs or in this tutorial.

💻 Interacting with demos

To interact with any of the demos, there's a couple of things to do. (Assuming the dependencies have been installed).

1. 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).

2. Check out the configuration file; config.json. Depending on which application you'll want to interact with, update the contract type in the deploy field to the desired contract. For example, when interacting with x-ballot-nft-UC you would put 'XBallotUC' and 'XProofOfVoteNFTUC' for optimism or base (which one you pick where does not matter).

3. Once the configuration file is updated and saved, you can look at the just commands with just --list. Alternatively follow the instructions in the official Polymer documentation.

$ just --list
Available recipes:
    clean                      # Clean up the environment by removing the artifacts and cache folders and running the forge clean command
    compile COMPILER='hardhat' # Usage: just compile [compiler]
    create-channel             # Usage: just create-channel
    deploy SOURCE DESTINATION UNIVERSAL='true' # Usage: just deploy [source] [destination] [universal]
    install                    # Install dependencies
    send-packet SOURCE UNIVERSAL='true' # Usage: just send-packet [source] [universal]

🤝 Contributing

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

Option 1: Improve IBC Solidity app template

Have ideas how to improve the project environment itself, not just application logic? Feel free to drop an issue or a PR (after forking) in the IBC app template for Solidity repository.

Option 2: Contribute to Polymer official demo-dapps

Have you seen an issue with any of the demo apps listed in this repo? Feel free to drop an issue or implement the changes yourself. Also if you feel you have a great addition that could live in the official docs, drop a PR and we'll investigate (it's possible we'll ask you to add it to the community demo dApps repo instead).

Please follow these steps when you do submit code changes:

1. Fork the Repository: Start by forking this repository.
2. Add Your Demo App or make changes: Place your demo app in the /contracts directory (separate directory for your project) or update the code that can be improved.
3. Create a Pull Request: Once you've added your demo or updated the code, create a pull request to the main repository with a detailed description of your app.

💡 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!