@hyperlane-xyz/core 1.5.8 → 3.0.0-beta0

package/contracts/token/HypNative.sol

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0;
+
+import {TokenRouter} from "./libs/TokenRouter.sol";
+import {TokenMessage} from "./libs/TokenMessage.sol";
+import {Address} from "@openzeppelin/contracts/utils/Address.sol";
+
+/**
+ * @title Hyperlane Native Token Router that extends ERC20 with remote transfer functionality.
+ * @author Abacus Works
+ * @dev Supply on each chain is not constant but the aggregate supply across all chains is.
+ */
+contract HypNative is TokenRouter {
+    /**
+     * @dev Emitted when native tokens are donated to the contract.
+     * @param sender The address of the sender.
+     * @param amount The amount of native tokens donated.
+     */
+    event Donation(address indexed sender, uint256 amount);
+
+    constructor(address _mailbox) TokenRouter(_mailbox) {}
+
+    /**
+     * @inheritdoc TokenRouter
+     * @dev uses (`msg.value` - `_amount`) as interchain gas payment and `msg.sender` as refund address.
+     */
+    function transferRemote(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) public payable virtual override returns (bytes32 messageId) {
+        require(msg.value >= _amount, "Native: amount exceeds msg.value");
+        uint256 gasPayment = msg.value - _amount;
+        return _transferRemote(_destination, _recipient, _amount, gasPayment);
+    }
+
+    function balanceOf(address _account)
+        external
+        view
+        override
+        returns (uint256)
+    {
+        return _account.balance;
+    }
+
+    /**
+     * @inheritdoc TokenRouter
+     * @dev No-op because native amount is transferred in `msg.value`
+     * @dev Compiler will not include this in the bytecode.
+     */
+    function _transferFromSender(uint256)
+        internal
+        pure
+        override
+        returns (bytes memory)
+    {
+        return bytes(""); // no metadata
+    }
+
+    /**
+     * @dev Sends `_amount` of native token to `_recipient` balance.
+     * @inheritdoc TokenRouter
+     */
+    function _transferTo(
+        address _recipient,
+        uint256 _amount,
+        bytes calldata // no metadata
+    ) internal virtual override {
+        Address.sendValue(payable(_recipient), _amount);
+    }
+
+    receive() external payable {
+        emit Donation(msg.sender, msg.value);
+    }
+}

package/contracts/token/README.md

@@ -0,0 +1,253 @@
+# Hyperlane Tokens and Warp Routes
+
+This repo contains contracts and SDK tooling for Hyperlane-connected ERC20 and ERC721 tokens. The contracts herein can be used to create [Hyperlane Warp Routes](https://docs.hyperlane.xyz/docs/deploy/deploy-warp-route) across different chains.
+
+For instructions on deploying Warp Routes, see [the deployment documentation](https://docs.hyperlane.xyz/docs/deploy/deploy-warp-route/deploy-a-warp-route) and the [Hyperlane-Deploy repository](https://github.com/hyperlane-xyz/hyperlane-deploy).
+
+## Warp Route Architecture
+
+A Warp Route is a collection of [`TokenRouter`](./contracts/libs/TokenRouter.sol) contracts deployed across a set of Hyperlane chains. These contracts leverage the `Router` pattern to implement access control and routing logic for remote token transfers. These contracts send and receive [`Messages`](./contracts/libs/Message.sol) which encode payloads containing a transfer `amount` and `recipient` address.
+
+```mermaid
+%%{ init: {
+  "theme": "neutral",
+  "themeVariables": {
+    "mainBkg": "#025AA1",
+    "textColor": "white",
+    "clusterBkg": "white"
+  },
+  "themeCSS": ".edgeLabel { color: black }"
+}}%%
+
+graph LR
+    subgraph "Ethereum"
+        HYP_E[TokenRouter]
+        style HYP_E fill:orange
+        Mailbox_E[(Mailbox)]
+    end
+
+    subgraph "Polygon"
+        HYP_P[TokenRouter]
+        style HYP_P fill:orange
+        Mailbox_P[(Mailbox)]
+    end
+
+
+    subgraph "Gnosis"
+        HYP_G[TokenRouter]
+        style HYP_G fill:orange
+        Mailbox_G[(Mailbox)]
+    end
+
+    HYP_E -. "router" .- HYP_P -. "router" .- HYP_G
+
+```
+
+The Token Router contract comes in several flavors and a warp route can be composed of a combination of these flavors.
+
+- [`Native`](./contracts/HypNative.sol) - for warping native assets (e.g. ETH) from the canonical chain
+- [`Collateral`](./contracts/HypERC20Collateral.sol) - for warping tokens, ERC20 or ERC721, from the canonical chain
+- [`Synthetic`](./contracts/HypERC20.sol) - for representing tokens, Native/ERC20 or ERC721, on a non-canonical chain
+
+## Interchain Security Models
+
+Warp routes are unique amongst token bridging solutions because they provide modular security. Because the `TokenRouter` implements the `IMessageRecipient` interface, it can be configured with a custom interchain security module. Please refer to the relevant guide to specifying interchain security modules on the [Messaging API receive docs](https://docs.hyperlane.xyz/docs/apis/messaging-api/receive#interchain-security-modules).
+
+## Remote Transfer Lifecycle Diagrams
+
+To initiate a remote transfer, users call the `TokenRouter.transferRemote` function with the `destination` chain ID, `recipient` address, and transfer `amount`.
+
+```solidity
+interface TokenRouter {
+  function transferRemote(
+    uint32 destination,
+    bytes32 recipient,
+    uint256 amount
+  ) public returns (bytes32 messageId);
+}
+
+```
+
+**NOTE:** The [Relayer](https://docs.hyperlane.xyz/docs/protocol/agents/relayer) shown below must be compensated. Please refer to the relevant guide on [paying for interchain gas](https://docs.hyperlane.xyz/docs/build-with-hyperlane/guides/paying-for-interchain-gas) on the `messageID` returned from the `transferRemote` call.
+
+Depending on the flavor of TokenRouter on the source and destination chain, this flow looks slightly different. The following diagrams illustrate these differences.
+
+### Transfer Alice's `amount` native ETH from Ethereum to Bob on Polygon
+
+```mermaid
+%%{ init: {
+  "theme": "neutral",
+  "themeVariables": {
+    "mainBkg": "#025AA1",
+    "textColor": "white",
+    "clusterBkg": "white"
+  },
+  "themeCSS": ".edgeLabel { color: black }"
+}}%%
+
+graph TB
+    Bob((Bob))
+    style Bob fill:black
+    Alice((Alice))
+    style Alice fill:black
+
+    Relayer([Relayer])
+
+    subgraph "Ethereum"
+        HYP_E[NativeTokenRouter]
+        style HYP_E fill:orange
+        Mailbox_E[(Mailbox)]
+    end
+
+    Alice == "transferRemote(Polygon, Bob, amount)\n{value: amount}" ==> HYP_E
+    linkStyle 0 color:green;
+    HYP_E -- "dispatch(Polygon, (Bob, amount))" --> Mailbox_E
+
+    subgraph "Polygon"
+        HYP_P[SyntheticTokenRouter]
+        style HYP_P fill:orange
+        Mailbox_P[(Mailbox)]
+    end
+
+    Mailbox_E -. "indexing" .-> Relayer
+
+    Relayer == "process(Ethereum, (Bob, amount))" ==> Mailbox_P
+    Mailbox_P -- "handle(Ethereum, (Bob, amount))" --> HYP_P
+
+    HYP_E -. "router" .- HYP_P
+
+    HYP_P -- "mint(Bob, amount)" --> Bob
+    linkStyle 6 color:green;
+```
+
+### Transfer Alice's ERC20 `amount` from Ethereum to Bob on Polygon
+
+```mermaid
+%%{ init: {
+  "theme": "neutral",
+  "themeVariables": {
+    "mainBkg": "#025AA1",
+    "textColor": "white",
+    "clusterBkg": "white"
+  },
+  "themeCSS": ".edgeLabel { color: black }"
+}}%%
+
+graph TB
+    Alice((Alice))
+    Bob((Bob))
+    style Alice fill:black
+    style Bob fill:black
+
+    Relayer([Relayer])
+
+    subgraph "Ethereum"
+        Token_E[ERC20]
+        style Token_E fill:green
+        HYP_E[CollateralTokenRouter]
+        style HYP_E fill:orange
+        Mailbox_E[(Mailbox)]
+    end
+
+    Alice == "approve(CollateralTokenRouter, infinity)" ==> Token_E
+    Alice == "transferRemote(Polygon, Bob, amount)" ==> HYP_E
+    Token_E -- "transferFrom(Alice, amount)" --> HYP_E
+    linkStyle 2 color:green;
+    HYP_E -- "dispatch(Polygon, (Bob, amount))" --> Mailbox_E
+
+    subgraph "Polygon"
+        HYP_P[SyntheticRouter]
+        style HYP_P fill:orange
+        Mailbox_P[(Mailbox)]
+    end
+
+    Mailbox_E -. "indexing" .-> Relayer
+
+    Relayer == "process(Ethereum, (Bob, amount))" ==> Mailbox_P
+    Mailbox_P -- "handle(Ethereum, (Bob, amount))" --> HYP_P
+
+    HYP_E -. "router" .- HYP_P
+    HYP_P -- "mint(Bob, amount)" --> Bob
+    linkStyle 8 color:green;
+```
+
+### Transfer Alice's `amount` synthetic MATIC from Ethereum back to Bob as native MATIC on Polygon
+
+```mermaid
+%%{ init: {
+  "theme": "neutral",
+  "themeVariables": {
+    "mainBkg": "#025AA1",
+    "textColor": "white",
+    "clusterBkg": "white"
+  },
+  "themeCSS": ".edgeLabel { color: black }"
+}}%%
+
+graph TB
+    Bob((Bob))
+    style Bob fill:black
+    Alice((Alice))
+    style Alice fill:black
+
+    Relayer([Relayer])
+
+    subgraph "Ethereum"
+        HYP_E[SyntheticTokenRouter]
+        style HYP_E fill:orange
+        Mailbox_E[(Mailbox)]
+    end
+
+    Alice == "transferRemote(Polygon, Bob, amount)" ==> HYP_E
+    Alice -- "burn(Alice, amount)" --> HYP_E
+    linkStyle 1 color:green;
+    HYP_E -- "dispatch(Polygon, (Bob, amount))" --> Mailbox_E
+
+    subgraph "Polygon"
+        HYP_P[NativeTokenRouter]
+        style HYP_P fill:orange
+        Mailbox_P[(Mailbox)]
+    end
+
+    Mailbox_E -. "indexing" .-> Relayer
+
+    Relayer == "process(Ethereum, (Bob, amount))" ==> Mailbox_P
+    Mailbox_P -- "handle(Ethereum, (Bob, amount))" --> HYP_P
+
+    HYP_E -. "router" .- HYP_P
+    HYP_P -- "transfer(){value: amount}" --> Bob
+    linkStyle 7 color:green;
+```
+
+**NOTE:** ERC721 collateral variants are assumed to [enumerable](https://docs.openzeppelin.com/contracts/4.x/api/token/erc721#IERC721Enumerable) and [metadata](https://docs.openzeppelin.com/contracts/4.x/api/token/erc721#IERC721Metadata) compliant.
+
+## Versions
+
+| Git Ref                  | Release Date | Notes                          |
+| ------------------------ | ------------ | ------------------------------ |
+| [audit-v2-remediation]() | 2023-02-15   | Hyperlane V2 Audit remediation |
+| [main]()                 | ~            | Bleeding edge                  |
+
+## Setup for local development
+
+```sh
+# Install dependencies
+yarn
+
+# Build source and generate types
+yarn build:dev
+```
+
+## Unit testing
+
+```sh
+# Run all unit tests
+yarn test
+
+# Lint check code
+yarn lint
+```
+
+## Learn more
+
+For more information, see the [Hyperlane introduction documentation](https://docs.hyperlane.xyz/docs/introduction/readme) or the [details about Warp Routes](https://docs.hyperlane.xyz/docs/deploy/deploy-warp-route).

package/contracts/token/extensions/FastHypERC20.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0;
+
+import {HypERC20} from "../HypERC20.sol";
+import {FastTokenRouter} from "../libs/FastTokenRouter.sol";
+import {TokenRouter} from "../libs/TokenRouter.sol";
+
+import {ERC20Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
+
+/**
+ * @title Hyperlane ERC20 Token Router that extends ERC20 with remote transfer functionality.
+ * @author Abacus Works
+ * @dev Supply on each chain is not constant but the aggregate supply across all chains is.
+ */
+contract FastHypERC20 is FastTokenRouter, HypERC20 {
+    constructor(uint8 __decimals, address _mailbox)
+        HypERC20(__decimals, _mailbox)
+    {}
+
+    /**
+     * @dev delegates transfer logic to `_transferTo`.
+     * @inheritdoc TokenRouter
+     */
+    function _handle(
+        uint32 _origin,
+        bytes32 _sender,
+        bytes calldata _message
+    ) internal virtual override(FastTokenRouter, TokenRouter) {
+        FastTokenRouter._handle(_origin, _sender, _message);
+    }
+
+    /**
+     * @dev Mints `_amount` of tokens to `_recipient`.
+     * @inheritdoc FastTokenRouter
+     */
+    function _fastTransferTo(address _recipient, uint256 _amount)
+        internal
+        override
+    {
+        _mint(_recipient, _amount);
+    }
+
+    /**
+     * @dev Burns `_amount` of tokens from `_recipient`.
+     * @inheritdoc FastTokenRouter
+     */
+    function _fastRecieveFrom(address _sender, uint256 _amount)
+        internal
+        override
+    {
+        _burn(_sender, _amount);
+    }
+
+    function balanceOf(address _account)
+        public
+        view
+        virtual
+        override(HypERC20, TokenRouter)
+        returns (uint256)
+    {
+        return ERC20Upgradeable.balanceOf(_account);
+    }
+}

package/contracts/token/extensions/FastHypERC20Collateral.sol

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0;
+
+import {HypERC20Collateral} from "../HypERC20Collateral.sol";
+import {FastTokenRouter} from "../libs/FastTokenRouter.sol";
+import {TokenRouter} from "../libs/TokenRouter.sol";
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+/**
+ * @title Hyperlane ERC20 Token Collateral that wraps an existing ERC20 with remote transfer functionality.
+ * @author Abacus Works
+ */
+contract FastHypERC20Collateral is FastTokenRouter, HypERC20Collateral {
+    using SafeERC20 for IERC20;
+
+    /**
+     * @notice Constructor
+     * @param erc20 Address of the token to keep as collateral
+     */
+    constructor(address erc20, address _mailbox)
+        HypERC20Collateral(erc20, _mailbox)
+    {}
+
+    /**
+     * @dev delegates transfer logic to `_transferTo`.
+     * @inheritdoc FastTokenRouter
+     */
+    function _handle(
+        uint32 _origin,
+        bytes32 _sender,
+        bytes calldata _message
+    ) internal virtual override(FastTokenRouter, TokenRouter) {
+        FastTokenRouter._handle(_origin, _sender, _message);
+    }
+
+    /**
+     * @dev Transfers `_amount` of `wrappedToken` to `_recipient`.
+     * @inheritdoc FastTokenRouter
+     */
+    function _fastTransferTo(address _recipient, uint256 _amount)
+        internal
+        override
+    {
+        wrappedToken.safeTransfer(_recipient, _amount);
+    }
+
+    /**
+     * @dev Transfers in `_amount` of `wrappedToken` from `_recipient`.
+     * @inheritdoc FastTokenRouter
+     */
+    function _fastRecieveFrom(address _sender, uint256 _amount)
+        internal
+        override
+    {
+        wrappedToken.safeTransferFrom(_sender, address(this), _amount);
+    }
+}

package/contracts/token/extensions/HypERC721URICollateral.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0;
+
+import {HypERC721Collateral} from "../HypERC721Collateral.sol";
+
+import {IERC721MetadataUpgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/extensions/IERC721MetadataUpgradeable.sol";
+
+/**
+ * @title Hyperlane ERC721 Token Collateral that wraps an existing ERC721 with remote transfer and URI relay functionality.
+ * @author Abacus Works
+ */
+contract HypERC721URICollateral is HypERC721Collateral {
+    // solhint-disable-next-line no-empty-blocks
+    constructor(address erc721, address _mailbox)
+        HypERC721Collateral(erc721, _mailbox)
+    {}
+
+    /**
+     * @dev Transfers `_tokenId` of `wrappedToken` from `msg.sender` to this contract.
+     * @return The URI of `_tokenId` on `wrappedToken`.
+     * @inheritdoc HypERC721Collateral
+     */
+    function _transferFromSender(uint256 _tokenId)
+        internal
+        override
+        returns (bytes memory)
+    {
+        HypERC721Collateral._transferFromSender(_tokenId);
+        return
+            bytes(
+                IERC721MetadataUpgradeable(address(wrappedToken)).tokenURI(
+                    _tokenId
+                )
+            );
+    }
+}

package/contracts/token/extensions/HypERC721URIStorage.sol

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0;
+
+import {HypERC721} from "../HypERC721.sol";
+
+import {ERC721URIStorageUpgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/extensions/ERC721URIStorageUpgradeable.sol";
+import {ERC721EnumerableUpgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/extensions/ERC721EnumerableUpgradeable.sol";
+import {ERC721Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol";
+
+/**
+ * @title Hyperlane ERC721 Token that extends ERC721URIStorage with remote transfer and URI relay functionality.
+ * @author Abacus Works
+ */
+contract HypERC721URIStorage is HypERC721, ERC721URIStorageUpgradeable {
+    constructor(address _mailbox) HypERC721(_mailbox) {}
+
+    function balanceOf(address account)
+        public
+        view
+        override(HypERC721, ERC721Upgradeable)
+        returns (uint256)
+    {
+        return HypERC721.balanceOf(account);
+    }
+
+    /**
+     * @return _tokenURI The URI of `_tokenId`.
+     * @inheritdoc HypERC721
+     */
+    function _transferFromSender(uint256 _tokenId)
+        internal
+        override
+        returns (bytes memory _tokenURI)
+    {
+        _tokenURI = bytes(tokenURI(_tokenId)); // requires minted
+        HypERC721._transferFromSender(_tokenId);
+    }
+
+    /**
+     * @dev Sets the URI for `_tokenId` to `_tokenURI`.
+     * @inheritdoc HypERC721
+     */
+    function _transferTo(
+        address _recipient,
+        uint256 _tokenId,
+        bytes calldata _tokenURI
+    ) internal override {
+        HypERC721._transferTo(_recipient, _tokenId, _tokenURI);
+        _setTokenURI(_tokenId, string(_tokenURI)); // requires minted
+    }
+
+    function tokenURI(uint256 tokenId)
+        public
+        view
+        override(ERC721Upgradeable, ERC721URIStorageUpgradeable)
+        returns (string memory)
+    {
+        return ERC721URIStorageUpgradeable.tokenURI(tokenId);
+    }
+
+    function _beforeTokenTransfer(
+        address from,
+        address to,
+        uint256 tokenId,
+        uint256 batchSize
+    ) internal override(ERC721EnumerableUpgradeable, ERC721Upgradeable) {
+        ERC721EnumerableUpgradeable._beforeTokenTransfer(
+            from,
+            to,
+            tokenId,
+            batchSize
+        );
+    }
+
+    function supportsInterface(bytes4 interfaceId)
+        public
+        view
+        override(ERC721EnumerableUpgradeable, ERC721Upgradeable)
+        returns (bool)
+    {
+        return ERC721EnumerableUpgradeable.supportsInterface(interfaceId);
+    }
+
+    function _burn(uint256 tokenId)
+        internal
+        override(ERC721URIStorageUpgradeable, ERC721Upgradeable)
+    {
+        ERC721URIStorageUpgradeable._burn(tokenId);
+    }
+}

package/contracts/token/extensions/HypNativeScaled.sol

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0;
+
+import {HypNative} from "../HypNative.sol";
+import {TokenRouter} from "../libs/TokenRouter.sol";
+
+/**
+ * @title Hyperlane Native Token that scales native value by a fixed factor for consistency with other tokens.
+ * @dev The scale factor multiplies the `message.amount` to the local native token amount.
+ *      Conversely, it divides the local native `msg.value` amount by `scale` to encode the `message.amount`.
+ * @author Abacus Works
+ */
+contract HypNativeScaled is HypNative {
+    uint256 public immutable scale;
+
+    constructor(uint256 _scale, address _mailbox) HypNative(_mailbox) {
+        scale = _scale;
+    }
+
+    /**
+     * @inheritdoc HypNative
+     * @dev Sends scaled `msg.value` (divided by `scale`) to `_recipient`.
+     */
+    function transferRemote(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) public payable override returns (bytes32 messageId) {
+        require(msg.value >= _amount, "Native: amount exceeds msg.value");
+        uint256 gasPayment = msg.value - _amount;
+        uint256 scaledAmount = _amount / scale;
+        return
+            _transferRemote(_destination, _recipient, scaledAmount, gasPayment);
+    }
+
+    /**
+     * @dev Sends scaled `_amount` (multipled by `scale`) to `_recipient`.
+     * @inheritdoc TokenRouter
+     */
+    function _transferTo(
+        address _recipient,
+        uint256 _amount,
+        bytes calldata metadata // no metadata
+    ) internal override {
+        uint256 scaledAmount = _amount * scale;
+        HypNative._transferTo(_recipient, scaledAmount, metadata);
+    }
+}