powerdlz23 1.1.5 → 1.1.7

package/polymer/polymer-template/README.md

@@ -0,0 +1,312 @@
+# ⛓️🔗⛓️ Template for IBC enabled Solidity contracts
+
+This repo provides a starter project to build [IBC](https://github.com/cosmos/ibc) enabled Solidity contracts that connect rollups to one another Polymer Hub, through the [vIBC core contracts](https://github.com/open-ibc/vibc-core-smart-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](./img/gh_template.png)
+
+## 📚 Documentation
+
+There's some basic information here in the README but a more comprehensive documentation can be found in [the official Polymer documentation](https://docs.polymerlabs.org/docs/category/build-ibc-dapps-1).
+
+## 📋 Prerequisites
+
+The repo is **compatible with both Hardhat and Foundry** development environments.
+
+- Have [git](https://git-scm.com/downloads) installed
+- Have [node](https://nodejs.org) installed (v18+)
+- Have [Foundry](https://book.getfoundry.sh/getting-started/installation) installed (Hardhat will be installed when running `npm install`)
+- Have [just](https://just.systems/man/en/chapter_1.html) installed (recommended but not strictly necessary)
+
+You'll need some API keys from third party's:
+- [Optimism Sepolia](https://optimism-sepolia.blockscout.com/account/api-key) and [Base Sepolia](https://base-sepolia.blockscout.com/account/api-key) Blockscout Explorer API keys
+- Have an [Alchemy API key](https://docs.alchemy.com/docs/alchemy-quickstart-guide) 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:
+
+```bash
+just install
+```
+
+to install the [vIBC core smart contracts](https://github.com/open-ibc/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.
+
+> 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...
+
+## ⚙️ 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).
+
+```bash
+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
+```sh
+# .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:
+
+- [Optimism Sepolia Faucet](https://www.alchemy.com/faucets/optimism-sepolia)
+- [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia)
+
+## 🏃🏽🏃🏻‍♀️ 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 IBC channel).
+
+### Universal channels
+
+The easiest way to get onboarded is to use Universal channels. A universal channel is an IBC channel where the port is owned by Polymer's Universal channel middleware contracts on each chain.
+
+When a user deploys a Universal channel compatible contract (this means inheriting the [UniversalChanIbcApp](./contracts/base/UniversalChanIbcApp.sol) base contract), it will be able to connect to the Universal Channel middleware, define Universal packets which will then be wrapped into an IBC packet by the Universal Channel Handler and unwrapped by its counterpart on the destination chain (rollup). The Universal channel middleware on the destination will then unwrap the IBC packet and send the data through to you application on the destination.
+
+Find out more about uinversal channels in the [documenation](https://docs.polymerlabs.org/docs/build/ibc-solidity/universal-channel).
+
+The configuration file that comes as default in the template repository, allows to quickly send a packet by running:
+
+```sh
+just send-packet base
+```
+
+To send a packet between the XCounterUC contract on Base Sepolia to OP Sepolia and vice versa.
+
+You can find the universal channel middleware details [in the documentation](https://docs.polymerlabs.org/docs/build/supp-networks).
+
+Check if the packet got through on the [Polymer IBC explorer](https://sepolia.polymer.zone/packets).
+
+### Custom IBC channel
+
+There's also a just recipe that quickly enables to try to send packets over a custom IBC channel. Custom IBC channel require a channel hanshake to open a private IBC channel (which can take a while depending on the client latency) but then give complete control over a private IBC channel that enables fault isolation from other applications, compared to unviersal channels.
+
+To have your application be compatible with custom IBC channels, have it inherit the [CustomChanIbcApp](./contracts/base/CustomChanIbcApp.sol) base contract.
+
+Run the following command to go through a full E2E sweep of the project, using the default XCounter.sol contract:
+
+```bash
+# Usage: just do-it
+just do-it
+```
+
+It does the following under the hood:
+```bash
+# 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.
+
+> 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...
+
+```bash
+# Usage: just switch-client
+just switch-client
+```
+
+Check if the packet got through on the [Polymer IBC explorer](https://sepolia.polymer.zone/packets).
+
+
+## 💻 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](https://docs.polymerlabs.org/docs/build/ibc-solidity/).
+
+## 🕹️ 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 cusotmize your application.
+
+For most of the actions above and more, there are just recipes that combine related logic and update the configuation 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. See [advanced usage](#🦾-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.
+
+#### Set contracts to config
+
+Do this by running:
+
+```bash
+# 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
+
+```javascript title="/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:
+
+```bash
+# 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:
+```bash
+# 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.
+
+To create a custom channel, run:
+
+```bash
+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](https://sepolia.polymer.zone/channels) to find out if the correct channel-id's related to your contracts were updated in the config.
+
+### Send packets
+
+Finally Run:
+
+```bash
+# 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.
+
+## Verify, don't trust
+
+As a starter value, the sim-client is used to improve latency. **The sim-client 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...
+
+```bash
+# Usage: just switch-client
+just switch-client
+```
+
+This will use the op-stack client with proofs, making sure that the relayer is proving what is being submitted every step along the way, ensuring there's no trust assumption on the relayer.
+
+An overview of the different clients can be found in `ibc.json`:
+```json
+{
+    "optimism": {
+        "sim-client": {
+            "canonConnFrom": "connection-0",
+            "canonConnTo": "connection-1",
+            "universalChannel": "channel-10"
+        },
+        "op-client": {
+            "canonConnFrom": "connection-8",
+            "canonConnTo": "connection-9",
+            "universalChannel": "channel-16"
+        }
+    },
+    "base": {
+        "sim-client" : {
+            "canonConnFrom": "connection-4",
+            "canonConnTo": "connection-5",
+            "universalChannel": "channel-11"
+        },
+        "op-client": {
+            "canonConnFrom": "connection-10",
+            "canonConnTo": "connection-11",
+            "universalChannel": "channel-17"
+        }
+    }
+}
+```
+
+## 🦾 Advanced usage
+
+For advanced users, there's multiple custimizations to follow. These includes configuring the config.json manually and/or running the scripts without using just.
+
+For example, the last action to send a packet on a universal channel could be executed with this command:
+
+```bash
+npx hardhat run scripts/send-universal-packet.js --network base
+```
+
+To send 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.
+
+Take a look at the open issues. 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.
+
+When you want to contribute code, please follow these steps:
+
+1. **Fork the Repository:** Start by forking this repository.
+2. **Apply the improvements:** Want to optimize something or add support for additional developer tooling? Add your changes!
+3. **Create a Pull Request:** Once you're ready and have tested your added code, submit a PR to the repo and we'll review as soon as possible.
+
+## 💡 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](https://forum.polymerlabs.org).
+
+Thank you for being a part of our community!

package/polymer/polymer-template/config/alt-config.json

@@ -0,0 +1,42 @@
+{
+  "proofsEnabled": false,
+  "deploy": {
+    "optimism": "XCounterUC",
+    "base": "XCounterUC"
+  },
+  "isUniversal": true,
+  "createChannel": {
+    "srcChain": "optimism",
+    "srcAddr": "0x1234567890AbCdEf1234567890aBcDeF12345678",
+    "dstChain": "base",
+    "dstAddr": "0x1234567890AbCdEf1234567890aBcDeF12345678",
+    "version": "1.0",
+    "ordering": 0,
+    "fees": false
+  },
+  "sendPacket": {
+    "optimism": {
+      "portAddr": "0x1234567890abcdef1234567890abcdef12345678",
+      "channelId": "channel-n",
+      "timeout": 36000
+    },
+    "base": {
+      "portAddr": "0x1234567890abcdef1234567890abcdef12345678",
+      "channelId": "channel-n",
+      "timeout": 36000
+    }
+  },
+  "sendUniversalPacket": {
+    "optimism": {
+      "portAddr": "0x1234567890abcdef1234567890abcdef12345678",
+      "channelId": "channel-x",
+      "timeout": 36000
+    },
+    "base": {
+      "portAddr": "0x1234567890abcdef1234567890abcdef12345678",
+      "channelId": "channel-y",
+      "timeout": 36000
+    }
+  },
+  "backup": {}
+}

package/polymer/polymer-template/config.json

@@ -0,0 +1,42 @@
+{
+  "proofsEnabled": false,
+  "deploy": {
+    "optimism": "XCounter",
+    "base": "XCounter"
+  },
+  "isUniversal": false,
+  "createChannel": {
+    "srcChain": "optimism",
+    "srcAddr": "0x9a5fDA8E49bcd1Ada645c06273A496D9A2397C9e",
+    "dstChain": "base",
+    "dstAddr": "0x9a5fDA8E49bcd1Ada645c06273A496D9A2397C9e",
+    "version": "1.0",
+    "ordering": 0,
+    "fees": false
+  },
+  "sendPacket": {
+    "optimism": {
+      "portAddr": "0x9a5fDA8E49bcd1Ada645c06273A496D9A2397C9e",
+      "channelId": "channel-19292",
+      "timeout": 36000
+    },
+    "base": {
+      "portAddr": "0x9a5fDA8E49bcd1Ada645c06273A496D9A2397C9e",
+      "channelId": "channel-19293",
+      "timeout": 36000
+    }
+  },
+  "sendUniversalPacket": {
+    "optimism": {
+      "portAddr": "0x1234567890abcdef1234567890abcdef12345678",
+      "channelId": "channel-x",
+      "timeout": 36000
+    },
+    "base": {
+      "portAddr": "0x1234567890abcdef1234567890abcdef12345678",
+      "channelId": "channel-y",
+      "timeout": 36000
+    }
+  },
+  "backup": {}
+}

package/polymer/polymer-template/contracts/XCounter.sol

@@ -0,0 +1,89 @@
+//SPDX-License-Identifier: UNLICENSED
+
+pragma solidity ^0.8.9;
+
+import './base/CustomChanIbcApp.sol';
+
+contract XCounter is CustomChanIbcApp {
+    // app specific state
+    uint64 public counter;
+    mapping (uint64 => address) public counterMap;
+
+
+    constructor(IbcDispatcher _dispatcher) CustomChanIbcApp(_dispatcher) {}
+
+    // app specific logic
+    function resetCounter() internal {
+        counter = 0;
+    }
+
+    function increment() internal {
+        counter++;
+    }
+
+    // IBC logic
+
+    /**
+     * @dev Sends a packet with the caller address over a specified channel.
+     * @param channelId The ID of the channel (locally) to send the packet to.
+     * @param timeoutSeconds The timeout in seconds (relative).
+     */
+
+    function sendPacket( bytes32 channelId, uint64 timeoutSeconds) external {
+        // incrementing counter on source chain
+        increment();
+
+        // encoding the caller address to update counterMap on destination chain
+        bytes memory payload = abi.encode(msg.sender);
+
+        // setting the timeout timestamp at 10h from now
+        uint64 timeoutTimestamp = uint64((block.timestamp + timeoutSeconds) * 1000000000);
+
+        // calling the Dispatcher to send the packet
+        dispatcher.sendPacket(channelId, payload, timeoutTimestamp);
+    }
+
+    /**
+     * @dev Packet lifecycle callback that implements packet receipt logic and returns and acknowledgement packet.
+     *      MUST be overriden by the inheriting contract.
+     * 
+     * @param packet the IBC packet encoded by the source and relayed by the relayer.
+     */
+    function onRecvPacket(IbcPacket memory packet) external override onlyIbcDispatcher returns (AckPacket memory ackPacket) {
+        recvedPackets.push(packet);
+        address _caller = abi.decode(packet.data, (address));
+        counterMap[packet.sequence] = _caller;
+
+        increment();
+
+        return AckPacket(true, abi.encode(counter));
+    }
+
+    /**
+     * @dev Packet lifecycle callback that implements packet acknowledgment logic.
+     *      MUST be overriden by the inheriting contract.
+     * 
+     * @param ack the acknowledgment packet encoded by the destination and relayed by the relayer.
+     */
+    function onAcknowledgementPacket(IbcPacket calldata, AckPacket calldata ack) external override onlyIbcDispatcher {
+        ackPackets.push(ack);
+        
+        (uint64 _counter) = abi.decode(ack.data, (uint64));
+        
+       if (_counter != counter) {
+        resetCounter();
+       }
+    }
+
+    /**
+     * @dev Packet lifecycle callback that implements packet receipt logic and return and acknowledgement packet.
+     *      MUST be overriden by the inheriting contract.
+     *      NOT SUPPORTED YET
+     * 
+     * @param packet the IBC packet encoded by the counterparty and relayed by the relayer
+     */
+    function onTimeoutPacket(IbcPacket calldata packet) external override onlyIbcDispatcher {
+        timeoutPackets.push(packet);
+        // do logic
+    }
+}

package/polymer/polymer-template/contracts/XCounterUC.sol

@@ -0,0 +1,100 @@
+//SPDX-License-Identifier: UNLICENSED
+
+pragma solidity ^0.8.9;
+
+import "./base/UniversalChanIbcApp.sol";
+
+contract XCounterUC is UniversalChanIbcApp {
+    // application specific state
+    uint64 public counter;
+    mapping(uint64 => address) public counterMap;
+
+    constructor(address _middleware) UniversalChanIbcApp(_middleware) {}
+
+    // application specific logic
+    function resetCounter() internal {
+        counter = 0;
+    }
+
+    function increment() internal {
+        counter++;
+    }
+
+    // IBC logic
+
+    /**
+     * @dev Sends a packet with the caller's address over the universal channel.
+     * @param destPortAddr The address of the destination application.
+     * @param channelId The ID of the channel to send the packet to.
+     * @param timeoutSeconds The timeout in seconds (relative).
+     */
+    function sendUniversalPacket(address destPortAddr, bytes32 channelId, uint64 timeoutSeconds) external {
+        increment();
+        bytes memory payload = abi.encode(msg.sender, counter);
+
+        uint64 timeoutTimestamp = uint64((block.timestamp + timeoutSeconds) * 1000000000);
+
+        IbcUniversalPacketSender(mw).sendUniversalPacket(
+            channelId, IbcUtils.toBytes32(destPortAddr), payload, timeoutTimestamp
+        );
+    }
+
+    /**
+     * @dev Packet lifecycle callback that implements packet receipt logic and returns and acknowledgement packet.
+     *      MUST be overriden by the inheriting contract.
+     *
+     * @param channelId the ID of the channel (locally) the packet was received on.
+     * @param packet the Universal packet encoded by the source and relayed by the relayer.
+     */
+    function onRecvUniversalPacket(bytes32 channelId, UniversalPacket calldata packet)
+        external
+        override
+        onlyIbcMw
+        returns (AckPacket memory ackPacket)
+    {
+        recvedPackets.push(UcPacketWithChannel(channelId, packet));
+
+        (address payload, uint64 c) = abi.decode(packet.appData, (address, uint64));
+        counterMap[c] = payload;
+
+        increment();
+
+        return AckPacket(true, abi.encode(counter));
+    }
+
+    /**
+     * @dev Packet lifecycle callback that implements packet acknowledgment logic.
+     *      MUST be overriden by the inheriting contract.
+     *
+     * @param channelId the ID of the channel (locally) the ack was received on.
+     * @param packet the Universal packet encoded by the source and relayed by the relayer.
+     * @param ack the acknowledgment packet encoded by the destination and relayed by the relayer.
+     */
+    function onUniversalAcknowledgement(bytes32 channelId, UniversalPacket memory packet, AckPacket calldata ack)
+        external
+        override
+        onlyIbcMw
+    {
+        ackPackets.push(UcAckWithChannel(channelId, packet, ack));
+
+        // decode the counter from the ack packet
+        (uint64 _counter) = abi.decode(ack.data, (uint64));
+
+        if (_counter != counter) {
+            resetCounter();
+        }
+    }
+
+    /**
+     * @dev Packet lifecycle callback that implements packet receipt logic and return and acknowledgement packet.
+     *      MUST be overriden by the inheriting contract.
+     *      NOT SUPPORTED YET
+     *
+     * @param channelId the ID of the channel (locally) the timeout was submitted on.
+     * @param packet the Universal packet encoded by the counterparty and relayed by the relayer
+     */
+    function onTimeoutUniversalPacket(bytes32 channelId, UniversalPacket calldata packet) external override onlyIbcMw {
+        timeoutPackets.push(UcPacketWithChannel(channelId, packet));
+        // do logic
+    }
+}

package/polymer/polymer-template/contracts/arguments.js

@@ -0,0 +1,7 @@
+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
+};