Add XCM Escrow Input Settler for Polkadot Cross-Chain Intent Settlement (#7)

* contracts, mocks and tests

* Added reentrancy guards, added XCM hand brake, minor optimizations

* Fixes suggested by MCP

* Added docs to the contract functions
Added docs to the XCM message building library
Fixed review comments

* More review fixes

* applied more comments

---------

Co-authored-by: Daniel Bigos <daniel.bigos96@gmail.com>

Author: KitHat

contracts/InputSettlerXCMEscrow.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+/**
+ * @title ILibrary
+ * @notice Interface for libraries that build XCM messages.
+ *         Implemented in ink! and deployed in PolkaVM, this library currently supports constructing Teleport messages only.
+ *         XCM messages are returned as SCALE-encoded bytes for use with XCM precompiles.
+ *
+ * @dev Example:
+ *   bytes memory xcmMsg = ILibrary(inkLibrary).teleport(paraId, beneficiary, amount);
+ */
+interface ILibrary {
+    function teleport(
+        uint32 paraId,
+        bytes32 beneficiary,
+        uint128 amount
+    ) external returns (bytes memory);
+}

contracts/interfaces/ILibrary.sol

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+/// @dev The on-chain address of the XCM (Cross-Consensus Messaging) precompile.
+address constant XCM_PRECOMPILE_ADDRESS = address(0xA0000);
+
+/// @title XCM Precompile Interface
+/// @notice A low-level interface for interacting with `pallet_xcm`.
+/// It forwards calls directly to the corresponding dispatchable functions,
+/// providing access to XCM execution and message passing.
+/// @dev Documentation:
+/// @dev - XCM: https://docs.polkadot.com/develop/interoperability
+/// @dev - SCALE codec: https://docs.polkadot.com/polkadot-protocol/parachain-basics/data-encoding
+/// @dev - Weights: https://docs.polkadot.com/polkadot-protocol/parachain-basics/blocks-transactions-fees/fees/#transactions-weights-and-fees
+interface IXcm {
+    /// @notice Weight v2 used for measurement for an XCM execution
+    struct Weight {
+        /// @custom:property The computational time used to execute some logic based on reference hardware.
+        uint64 refTime;
+        /// @custom:property The size of the proof needed to execute some logic.
+        uint64 proofSize;
+    }
+
+    /// @notice Executes an XCM message locally on the current chain with the caller's origin.
+    /// @dev Internally calls `pallet_xcm::execute`.
+    /// @param message A SCALE-encoded Versioned XCM message.
+    /// @param weight The maximum allowed `Weight` for execution.
+    /// @dev Call @custom:function weighMessage(message) to ensure sufficient weight allocation.
+    function execute(bytes calldata message, Weight calldata weight) external;
+
+    /// @notice Sends an XCM message to another parachain or consensus system.
+    /// @dev Internally calls `pallet_xcm::send`.
+    /// @param destination SCALE-encoded destination MultiLocation.
+    /// @param message SCALE-encoded Versioned XCM message.
+    function send(bytes calldata destination, bytes calldata message) external;
+
+    /// @notice Estimates the `Weight` required to execute a given XCM message.
+    /// @param message SCALE-encoded Versioned XCM message to analyze.
+    /// @return weight Struct containing estimated `refTime` and `proofSize`.
+    function weighMessage(bytes calldata message) external view returns (Weight memory weight);
+}

contracts/interfaces/IXcm.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+import {ERC20} from "openzeppelin/token/ERC20/ERC20.sol";
+
+contract MockERC20 is ERC20 {
+    constructor(string memory name, string memory symbol) ERC20(name, symbol) {}
+
+    function mint(address to, uint256 amount) public {
+        _mint(to, amount);
+    }
+
+    function burn(address from, uint256 amount) public {
+        _burn(from, amount);
+    }
+}

contracts/test/MockERC20.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+import "../interfaces/ILibrary.sol";
+import {SafeERC20} from "openzeppelin/token/ERC20/utils/SafeERC20.sol"; 
+import {IERC20} from "openzeppelin/token/ERC20/IERC20.sol";
+
+contract MockLibrary is ILibrary {
+    event TeleportCalled(uint32 paraId, bytes32 beneficiary, uint128 amount);
+
+    bytes private teleportMessage = "0x";
+    address private tokenAddress;
+
+    function setTeleportMessage(bytes memory message) external {
+        teleportMessage = message;
+    }
+
+    function setToken(address _token) external {
+        tokenAddress = _token;
+    }
+
+    function teleport(
+        uint32 paraId,
+        bytes32 beneficiary,
+        uint128 amount
+    ) external returns (bytes memory) {
+        // Simulate burning tokens by transferring from caller to this contract
+        if (tokenAddress != address(0)) {
+            SafeERC20.safeTransferFrom(IERC20(tokenAddress), msg.sender, address(this), amount);
+        }
+        emit TeleportCalled(paraId, beneficiary, amount);
+        return teleportMessage;
+    }
+}

contracts/test/MockLibrary.sol

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+import "../interfaces/IXcm.sol";
+
+contract MockXcm is IXcm {
+    event Executed(bytes message);
+    event Sent(bytes destination, bytes message);
+    event WeighMessageCalled(bytes message);
+
+    bool private executionSuccess = true;
+    Weight private mockWeight = Weight({refTime: 1000000, proofSize: 1000});
+
+    function setExecutionSuccess(bool success) external {
+        executionSuccess = success;
+    }
+
+    function setMockWeight(uint64 refTime, uint64 proofSize) external {
+        mockWeight = Weight({refTime: refTime, proofSize: proofSize});
+    }
+
+    function execute(
+        bytes calldata message,
+        Weight calldata weight
+    ) external override {
+        require(executionSuccess, "MockXcm: execution failed");
+        emit Executed(message);
+    }
+
+    function send(
+        bytes calldata destination,
+        bytes calldata message
+    ) external override {
+        emit Sent(destination, message);
+    }
+
+    function weighMessage(
+        bytes calldata message
+    ) external view override returns (Weight memory weight) {
+        return mockWeight;
+    }
+}

contracts/test/MockXcm.sol

@@ -0,0 +1,27 @@
+import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";
+
+const InputSettlerXCMEscrowModule = buildModule("InputSettlerXCMEscrowModule", (m) => {
+    // Parameters with defaults
+    // Default XCM precompile address on many Polkadot parachains is 0xA0000 or similar precompiles
+    const xcmPrecompile = m.getParameter("xcmPrecompile", "0x00000000000000000000000000000000000A0000");
+
+    // For inkLibrary, we might need a real address. Defaulting to zero address for now if not provided.
+    // User should provide this when deploying to a real network.
+    const inkLibrary = m.getParameter("inkLibrary", "0x0000000000000000000000000000000000000000");
+
+    // Deploy the base settler contract
+    // Note: InputSettlerEscrow is imported from oif-contracts
+    const baseSettler = m.contract("InputSettlerEscrow", []);
+
+    // Deploy the XCM settler
+    const inputSettlerXCMEscrow = m.contract("InputSettlerXCMEscrow", [
+        inkLibrary,
+        xcmPrecompile,
+        baseSettler
+    ]);
+
+    return { baseSettler, inputSettlerXCMEscrow };
+});
+
+export default InputSettlerXCMEscrowModule;
+

ignition/modules/InputSettlerXCMEscrow.ts

@@ -0,0 +1,125 @@
+const { expect } = require("chai");
+const { ethers } = require("hardhat");
+const {
+    setupInputSettlerXCMEscrow,
+    createOrderFactory,
+    DESTINATION_CHAIN_ID,
+    STANDARD_AMOUNT,
+    DOUBLE_AMOUNT,
+    MOCK_XCM_MESSAGE_1
+} = require("./helpers/inputSettlerXCMEscrowHelper");
+
+describe("InputSettlerXCMEscrow - Admin Functions", function () {
+    let inputSettlerXCMEscrow;
+    let token;
+    let owner;
+    let user;
+    let mockXcm;
+    let mockLibrary;
+    let baseSettler;
+    let chainId;
+    let createOrder;
+
+    beforeEach(async function () {
+        const setup = await setupInputSettlerXCMEscrow();
+        owner = setup.owner;
+        user = setup.user;
+        mockXcm = setup.mockXcm;
+        mockLibrary = setup.mockLibrary;
+        baseSettler = setup.baseSettler;
+        inputSettlerXCMEscrow = setup.inputSettlerXCMEscrow;
+        token = setup.token;
+        chainId = setup.chainId;
+        createOrder = createOrderFactory(user, token, chainId);
+    });
+
+    describe("Deployment", function () {
+        it("Should set the right owner", async function () {
+            expect(await inputSettlerXCMEscrow.owner()).to.equal(owner.address);
+        });
+    });
+
+    describe("allowTeleport", function () {
+        it("Should allow teleport for a destination and token", async function () {
+            const tokenAddress = await token.getAddress();
+
+            await expect(inputSettlerXCMEscrow.allowTeleport(DESTINATION_CHAIN_ID, tokenAddress))
+                .to.emit(inputSettlerXCMEscrow, "TeleportAllowed")
+                .withArgs(DESTINATION_CHAIN_ID, tokenAddress);
+        });
+
+        it("Should revert if not called by owner", async function () {
+            const tokenAddress = await token.getAddress();
+
+            await expect(
+                inputSettlerXCMEscrow.connect(user).allowTeleport(DESTINATION_CHAIN_ID, tokenAddress)
+            ).to.be.revertedWithCustomError(inputSettlerXCMEscrow, "OwnableUnauthorizedAccount")
+                .withArgs(user.address);
+        });
+    });
+
+    describe("forbidTeleport", function () {
+        it("Should forbid teleport for a destination and token", async function () {
+            const tokenAddress = await token.getAddress();
+
+            await inputSettlerXCMEscrow.allowTeleport(DESTINATION_CHAIN_ID, tokenAddress);
+
+            await expect(inputSettlerXCMEscrow.forbidTeleport(DESTINATION_CHAIN_ID, tokenAddress))
+                .to.emit(inputSettlerXCMEscrow, "TeleportForbidden")
+                .withArgs(DESTINATION_CHAIN_ID, tokenAddress);
+        });
+    });
+
+    describe("setXCMEnabled", function () {
+        it("Should fall back to baseSettler when XCM is disabled for valid XCM order", async function () {
+            await inputSettlerXCMEscrow.allowTeleport(DESTINATION_CHAIN_ID, await token.getAddress());
+
+            const order = createOrder();
+
+            // Verify XCM path would work normally
+            await token.connect(user).approve(await inputSettlerXCMEscrow.getAddress(), ethers.parseEther(DOUBLE_AMOUNT));
+            await mockLibrary.setTeleportMessage(MOCK_XCM_MESSAGE_1);
+            await mockXcm.setExecutionSuccess(true);
+
+            // Disable XCM globally
+            await inputSettlerXCMEscrow.setXCMEnabled(false);
+
+            // Should fall back to baseSettler despite valid XCM configuration
+            await expect(inputSettlerXCMEscrow.connect(user).open(order))
+                .to.emit(baseSettler, "Open");
+
+            // Verify XCM was not called
+            const xcmAllowance = await token.allowance(
+                await inputSettlerXCMEscrow.getAddress(),
+                await mockXcm.getAddress()
+            );
+            expect(xcmAllowance).to.equal(0);
+        });
+
+        it("Should resume XCM path when re-enabled", async function () {
+            await inputSettlerXCMEscrow.allowTeleport(DESTINATION_CHAIN_ID, await token.getAddress());
+
+            const order = createOrder();
+
+            await token.connect(user).approve(await inputSettlerXCMEscrow.getAddress(), ethers.parseEther(STANDARD_AMOUNT));
+            await mockLibrary.setTeleportMessage(MOCK_XCM_MESSAGE_1);
+            await mockXcm.setExecutionSuccess(true);
+
+            // Disable then re-enable XCM
+            await inputSettlerXCMEscrow.setXCMEnabled(false);
+            await inputSettlerXCMEscrow.setXCMEnabled(true);
+
+            // Should use XCM path again
+            await expect(inputSettlerXCMEscrow.connect(user).open(order))
+                .to.emit(mockXcm, "Executed")
+                .withArgs(MOCK_XCM_MESSAGE_1);
+        });
+
+        it("Should revert if not called by owner", async function () {
+            await expect(
+                inputSettlerXCMEscrow.connect(user).setXCMEnabled(false)
+            ).to.be.revertedWithCustomError(inputSettlerXCMEscrow, "OwnableUnauthorizedAccount")
+                .withArgs(user.address);
+        });
+    });
+});