Feature - Support GMP Token Bridge (#12)

* forge install: analog-gmp

* Integrate with GMP

* update docs

* remove typo

* fix anothe typo

* gmp bridge-related fixes (#13)

* fixes to make it compile

* deployment script update

* rm REMOTE_ADDRESS

* make AnlogTokenV1Test work

---------

Co-authored-by: Alexander Gryaznov <[email protected]>

Author: Lohann

.env.anvil

@@ -9,3 +9,7 @@ export UPGRADER=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC
 export PAUSER=0x90F79bf6EB2c4f870365E785982E1f101E93b906
 # well-known (thus key compromised) Anvil default account(4)
 export UNPAUSER=0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65
+# Teleport-specific
+export GATEWAY=0x49877F1e26d523e716d941a424af46B86EcaF09E
+export TIMECHAIN_ROUTE_ID=1000
+export MINIMAL_TELEPORT_VALUE=1000000000000

.gitmodules

@@ -7,3 +7,6 @@
 [submodule "lib/openzeppelin-contracts-upgradeable"]
 	path = lib/openzeppelin-contracts-upgradeable
 	url = https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable
+[submodule "lib/analog-gmp"]
+	path = lib/analog-gmp
+	url = https://github.com/Analog-Labs/analog-gmp

lib/analog-gmp

@@ -1,2 +1,3 @@
 @openzeppelin/contracts/=lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts
 @openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts
+@analog-gmp/=lib/analog-gmp/src

remappings.txt

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.13;
 
 import {Script, console} from "forge-std/Script.sol";
-import {Upgrades} from "openzeppelin-foundry-upgrades/Upgrades.sol";
+import {Upgrades, Options} from "openzeppelin-foundry-upgrades/Upgrades.sol";
 import {AnlogTokenV1} from "../src/AnlogTokenV1.sol";
 
 contract AnlogTokenScript is Script {
@@ -18,10 +18,18 @@ contract AnlogTokenScript is Script {
         address pauser = vm.envAddress("PAUSER");
         address unpauser = vm.envAddress("UNPAUSER");
 
+        // Teleport-related
+        address gateway = vm.envAddress("GATEWAY");
+        uint16 timechainId = uint16(vm.envUint("TIMECHAIN_ROUTE_ID"));
+        uint256 minimalTeleport = vm.envUint("MINIMAL_TELEPORT_VALUE");
+
         vm.startBroadcast(deployer);
 
+        Options memory opts;
+        opts.constructorData = abi.encode(gateway, timechainId, minimalTeleport);
+
         address proxyAddress = Upgrades.deployUUPSProxy(
-            "AnlogTokenV1.sol", abi.encodeCall(AnlogTokenV1.initialize, (minter, upgrader, pauser, unpauser))
+            "AnlogTokenV1.sol", abi.encodeCall(AnlogTokenV1.initialize, (minter, upgrader, pauser, unpauser)), opts
         );
 
         vm.stopBroadcast();

script/00_Deploy.s.sol

@@ -10,6 +10,9 @@ import {ERC20PausableUpgradeable} from
     "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC20PausableUpgradeable.sol";
 import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {IGmpReceiver} from "@analog-gmp/interfaces/IGmpReceiver.sol";
+import {IGateway} from "@analog-gmp/interfaces/IGateway.sol";
 
 /// @notice V1: Roles Model implementation of upgradable ERC20 token.
 /// This to be used as the initial implementation of UUPS proxy.
@@ -21,15 +24,99 @@ contract AnlogTokenV1 is
     ERC20BurnableUpgradeable,
     ERC20PausableUpgradeable,
     AccessControlUpgradeable,
-    UUPSUpgradeable
+    UUPSUpgradeable,
+    IGmpReceiver
 {
     bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
     bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
     bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
     bytes32 public constant UNPAUSER_ROLE = keccak256("UNPAUSER_ROLE");
 
+    /**
+     * @dev Length of `OutboundTeleportCommand` struct encoded in bytes.
+     * ```
+     * uint256 messageLength = abi.encode(OutboundTeleportCommand({from: address(0), to: bytes32(0), amount: 0})).length;
+     * ```
+     */
+    uint256 public constant TELEPORT_COMMAND_ENCODED_LEN = 96;
+
+    /**
+     * @dev Minimun gas limit necessary to execute the `onGmpReceived` method defined in this contract.
+     */
+    uint256 public constant INBOUND_TRANSFER_GAS_LIMIT = 100_000;
+
+    /**
+     * @dev Address of Analog Gateway deployed in the local network, work as "broker" to exchange messages,
+     *      between this contract and the Timechain.
+     *
+     * References:
+     * - Protocol Overview: https://docs.analog.one/documentation/developers/analog-gmp
+     * - Gateway source-code: https://github.com/Analog-Labs/analog-gmp
+     */
+    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
+    IGateway public immutable GATEWAY;
+
+    /**
+     * @dev Timechain's Route ID, this is the unique identifier of Timechain's network.
+     */
+    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
+    uint16 public immutable TIMECHAIN_ROUTE_ID;
+
+    /**
+     * @dev Minimal quantity of tokens allowed per teleport.
+     *
+     * IMPORTANT: This value MUST be equal or greater than the timechain's existential deposit.
+     * see: https://github.com/paritytech/polkadot-sdk/blob/polkadot-v1.17.1/substrate/frame/balances/README.md?plain=1#L24-L29
+     */
+    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
+    uint256 public immutable MINIMAL_TELEPORT_VALUE;
+
+    /**
+     * @dev Emitted when `amount` tokens are teleported from `source` account in the local network to `recipient` in Timechain.
+     */
+    event OutboundTransfer(bytes32 indexed id, address indexed source, bytes32 indexed recipient, uint256 amount);
+
+    /**
+     * @dev @dev Emitted when `amount` tokens are teleported from `source` in Timechain to `recipient` in the local network.
+     */
+    event InboundTransfer(bytes32 indexed id, bytes32 indexed source, address indexed recipient, uint256 amount);
+
+    /**
+     * @dev One or more preconditions of `onGmpReceived` method failed.
+     */
+    error Unauthorized();
+
+    /**
+     * @dev Command encoded in the `data` field on the `onGmpReceived` method, representing a teleport from Timechain to the local network.
+     * @param from Timechain's account teleporting the tokens.
+     * @param to Local account receing the tokens.
+     * @param amount The amount of tokens teleported.
+     */
+    struct InboundTeleportCommand {
+        bytes32 from;
+        address to;
+        uint256 amount;
+    }
+
+    /**
+     * @dev Command that that teleports tokens from the local network to the Timechain.
+     * @param from Account in the local network teleporting the tokens.
+     * @param to Account in Timechain receing the tokens.
+     * @param amount The amount of tokens to teleport.
+     */
+    struct OutboundTeleportCommand {
+        address from;
+        bytes32 to;
+        uint256 amount;
+    }
+
     /// @custom:oz-upgrades-unsafe-allow constructor
-    constructor() {
+    constructor(address gateway, uint16 timechainId, uint256 minimalTeleport) {
+        require(gateway.code.length > 0, "Gateway address is not a contract");
+        require(IGateway(gateway).networkId() != timechainId, "local network and Timechain must be different networks");
+        GATEWAY = IGateway(gateway);
+        TIMECHAIN_ROUTE_ID = timechainId;
+        MINIMAL_TELEPORT_VALUE = minimalTeleport;
         _disableInitializers();
     }
 
@@ -63,14 +150,142 @@ contract AnlogTokenV1 is
         _mint(to, amount);
     }
 
+    /**
+     * @dev The following functions are overrides required by Solidity.
+     */
     function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) {}
 
-    // The following functions are overrides required by Solidity.
-
     function _update(address from, address to, uint256 value)
         internal
         override(ERC20Upgradeable, ERC20PausableUpgradeable)
     {
         super._update(from, to, value);
     }
+
+    /**
+     * @dev Workaround for EVM compatibility, in some chains like `Astar` where `address(this).balance` can
+     *      be less than `msg.value` if this contract has no previous existential deposit.
+     * Reference:
+     * - https://github.com/polkadot-evm/frontier/blob/polkadot-v1.11.0/ts-tests/tests/test-balance.ts#L41
+     */
+    function _msgValue() private view returns (uint256) {
+        return Math.min(msg.value, address(this).balance);
+    }
+
+    /**
+     * @dev Teleport a `value` amount of tokens from the caller's account in the local chain to `to`
+     * account in the Timechain.
+     *
+     * Returns the GMP message identifier.
+     *
+     * Requirements:
+     * - `to` cannot be the zero address.
+     * - `value` must be equal or greater than `MINIMAL_TELEPORT_VALUE`.
+     * - the caller must have a balance of at least `value`.
+     *
+     * Emits a {OutboundTransfer} event.
+     */
+    function teleport(bytes32 to, uint256 value) external payable returns (bytes32 messageID) {
+        return _teleportFrom(_msgSender(), to, value);
+    }
+
+    /**
+     * @dev Teleports a `value` amount of tokens from `from` account in the local chain to `to` account
+     * in the Timechain using the allowance mechanism. `value` is then deducted from the caller's
+     * allowance.
+     *
+     * Returns the GMP message identifier.
+     *
+     * NOTE: Does not update the allowance if the current allowance
+     * is the maximum `uint256`.
+     *
+     * Requirements:
+     * - `from` and `to` cannot be the zero address.
+     * - `from` must have a balance of at least `value`.
+     * - `value` must be equal or greater than `MINIMAL_TELEPORT_VALUE`.
+     * - the caller must have allowance for ``from``'s tokens of at least
+     * `value`.
+     *
+     * Emits a {OutboundTransfer} event.
+     */
+    function teleportFrom(address from, bytes32 to, uint256 value) external payable returns (bytes32 messageID) {
+        address spender = _msgSender();
+        _spendAllowance(from, spender, value);
+        return _teleportFrom(from, to, value);
+    }
+
+    /**
+     * @dev Teleports a `value` amount of tokens from `from` account in the local chain to `to` account
+     * in the Timechain.
+     *
+     * Requirements:
+     * - `from` and `to` cannot be the zero address.
+     * - `from` must have a balance of at least `value`.
+     * - `value` must be equal or greater than `MINIMAL_TELEPORT_VALUE`.
+     *
+     * Emits a {OutboundTransfer} event.
+     */
+    function _teleportFrom(address from, bytes32 to, uint256 value) private returns (bytes32 messageID) {
+        if (from == address(0)) {
+            revert ERC20InvalidSender(address(0));
+        }
+        if (to == bytes32(bytes20(address(0)))) {
+            revert ERC20InvalidReceiver(address(0));
+        }
+        require(value >= MINIMAL_TELEPORT_VALUE, "value below minimum required");
+        _burn(from, value);
+        bytes memory message = abi.encode(OutboundTeleportCommand({from: from, to: to, amount: value}));
+        messageID = GATEWAY.submitMessage{value: _msgValue()}(
+            address(0), TIMECHAIN_ROUTE_ID, INBOUND_TRANSFER_GAS_LIMIT, message
+        );
+        emit OutboundTransfer(messageID, from, to, value);
+    }
+
+    /**
+     * @dev Estimate the teleport cost in native tokens, the returned is the amount of ether to send to `teleport` method.
+     */
+    function estimateTeleportCost() public view returns (uint256) {
+        return GATEWAY.estimateMessageCost(TIMECHAIN_ROUTE_ID, TELEPORT_COMMAND_ENCODED_LEN, INBOUND_TRANSFER_GAS_LIMIT);
+    }
+
+    /**
+     * @dev Handles the receipt of a single GMP message.
+     * The contract must verify the msg.sender, it must be the Gateway Contract address.
+     *
+     * @param id The global unique identifier of the message.
+     * @param network The unique identifier of the source chain who send the message
+     * @param payload The message payload with no specified format
+     * @return 32 byte result which will be stored together with GMP message
+     *
+     * * Requirements:
+     * - the caller must be the `GATEWAY` contract.
+     * - `network` must be the `TIMECHAIN_ROUTE_ID`.
+     * - `source` must be the `REMOTE_ADDRESS`.
+     * - `payload` must be the struct `InboundTeleportCommand` encoded.
+     *
+     * Emits a {InboundTransfer} event.
+     */
+    function onGmpReceived(bytes32 id, uint128 network, bytes32, bytes calldata payload)
+        external
+        payable
+        returns (bytes32)
+    {
+        // Check preconditions
+        require(msg.sender == address(GATEWAY), Unauthorized());
+        require(network == TIMECHAIN_ROUTE_ID, Unauthorized());
+
+        // Decode the command
+        InboundTeleportCommand memory command = abi.decode(payload, (InboundTeleportCommand));
+
+        // Mint the tokens to the recipient account
+        if (command.to != address(0) && command.amount > 0) {
+            _mint(command.to, command.amount);
+        }
+        emit InboundTransfer(id, command.from, command.to, command.amount);
+
+        // Returns the current total supply as result, the result is included in the `GmpExecuted` event
+        // emitted by the gateway. It allows the Timechain to verify if the amount of tokens locked matches
+        // the total supply of this contract.
+        return bytes32(totalSupply());
+    }
 }

src/AnlogTokenV1.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.22;
 
 import {Test, console} from "forge-std/Test.sol";
-import {Upgrades} from "openzeppelin-foundry-upgrades/Upgrades.sol";
+import {Upgrades, Options} from "openzeppelin-foundry-upgrades/Upgrades.sol";
 import {PausableUpgradeable} from "@openzeppelin/contracts-upgradeable/utils/PausableUpgradeable.sol";
 import {IAccessControl} from "@openzeppelin/contracts/access/IAccessControl.sol";
 import {AnlogTokenV1} from "../src/AnlogTokenV1.sol";
@@ -19,13 +19,29 @@ contract AnlogTokenV1Test is Test {
     address constant UNPAUSER = address(3);
     address constant NEW_MINTER = address(4);
 
+    // Teleport-related
+    address constant GATEWAY = 0xEb73D0D236DE8F8D09dc6A52916e5849ff1E8dfA;
+    uint16 constant TIMECHAIN_ID = 1000;
+    uint256 constant MIN_TELEPORT_VAL = 1000000000000;
+
+    // fork testing
+    string SEPOLIA_RPC_URL = vm.envString("SEPOLIA_RPC_URL");
+    uint256 sepoliaFork;
+
     /// @notice deploys an UUPS proxy.
     /// Here we start with the V1 implementation right away.
     /// For V0->V1 upgrade see another test.
     function setUp() public {
+        sepoliaFork = vm.createFork(SEPOLIA_RPC_URL);
+        vm.selectFork(sepoliaFork);
+        assertEq(vm.activeFork(), sepoliaFork);
+
+        Options memory opts;
+        opts.constructorData = abi.encode(GATEWAY, TIMECHAIN_ID, MIN_TELEPORT_VAL);
+
         // deploy proxy with a distinct address assigned to each role
         address proxy = Upgrades.deployUUPSProxy(
-            "AnlogTokenV1.sol", abi.encodeCall(AnlogTokenV1.initialize, (MINTER, UPGRADER, PAUSER, UNPAUSER))
+            "AnlogTokenV1.sol", abi.encodeCall(AnlogTokenV1.initialize, (MINTER, UPGRADER, PAUSER, UNPAUSER)), opts
         );
         token = AnlogTokenV1(proxy);
     }