ERC-7786 based crosschain bridge for ERC-20 tokens

.changeset/silent-zebras-press.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC7786Recipient`: Generic ERC-7786 cross-chain message recipient contract.

contracts/crosschain/ERC7786Recipient.sol

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.27;
+
+import {IERC7786Recipient} from "../interfaces/draft-IERC7786.sol";
+import {BitMaps} from "../utils/structs/BitMaps.sol";
+
+/**
+ * @dev Base implementation of an ERC-7786 compliant cross-chain message receiver.
+ *
+ * This abstract contract exposes the `receiveMessage` function that is used for communication with (one or multiple)
+ * destination gateways. This contract leaves two functions unimplemented:
+ *
+ * * {_isAuthorizedGateway}, an internal getter used to verify whether an address is recognised by the contract as a
+ * valid ERC-7786 destination gateway. One or multiple gateway can be supported. Note that any malicious address for
+ * which this function returns true would be able to impersonate any account on any other chain sending any message.
+ *
+ * * {_processMessage}, the internal function that will be called with any message that has been validated.
+ *
+ * This contract implements replay protection, manning that if two messages are received from the same gateway with the
+ * same `receiveId`, then the second one will NOT be executed, regardless of the result of {_isAuthorizedGateway}.
+ */
+abstract contract ERC7786Recipient is IERC7786Recipient {
+    using BitMaps for BitMaps.BitMap;
+
+    mapping(address gateway => BitMaps.BitMap) private _received;
+
+    error ERC7786RecipientInvalidGateway(address gateway);
+    error ERC7786RecipientMessageAlreadyProcessed(address gateway, bytes32 receiveId);
+
+    /// @inheritdoc IERC7786Recipient
+    function receiveMessage(
+        bytes32 receiveId,
+        bytes calldata sender, // Binary Interoperable Address
+        bytes calldata payload
+    ) external payable returns (bytes4) {
+        require(_isAuthorizedGateway(msg.sender, sender), ERC7786RecipientInvalidGateway(msg.sender));
+        require(
+            !_received[msg.sender].get(uint256(receiveId)),
+            ERC7786RecipientMessageAlreadyProcessed(msg.sender, receiveId)
+        );
+        _received[msg.sender].set(uint256(receiveId));
+
+        _processMessage(msg.sender, receiveId, sender, payload);
+
+        return IERC7786Recipient.receiveMessage.selector;
+    }
+
+    /// @dev Virtual getter that returns whether an address is a valid ERC-7786 gateway for a given sender.
+    function _isAuthorizedGateway(address instance, bytes calldata sender) internal view virtual returns (bool);
+
+    /// @dev Virtual function that should contain the logic to execute when a cross-chain message is received.
+    function _processMessage(
+        address gateway,
+        bytes32 receiveId,
+        bytes calldata sender,
+        bytes calldata payload
+    ) internal virtual;
+}

contracts/crosschain/README.adoc

@@ -0,0 +1,12 @@
+= Cross chain interoperability
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/crosschain
+
+This directory contains contracts for sending and receiving cross chain messages that follows the ERC-7786 standard.
+
+- {IERC7786Recipient}: generic ERC-7786 crosschain contract that receives messages from a trusted gateway
+
+== Helpers
+
+{{IERC7786Recipient}}

contracts/crosschain/bridges/BridgeCore.sol

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {IERC7786GatewaySource} from "../../interfaces/draft-IERC7786.sol";
+import {InteroperableAddress} from "../../utils/draft-InteroperableAddress.sol";
+import {Bytes} from "../../utils/Bytes.sol";
+import {ERC7786Recipient} from "../ERC7786Recipient.sol";
+
+/**
+ * @dev Core bridging mechanism.
+ *
+ * This contract contains the logic to register and send messages to counterparts on remote chains using ERC-7786
+ * gateways. It ensure received message originate from for a counterpart. This is the code of token bridges such as
+ * {BridgeERC20}.
+ *
+ * Contract that inherit from this contract can use the internal {_senMessage} to send messages to their conterpart
+ * on a foreign chain. They must override the {_processMessage} function to handle the message that have been verified.
+ */
+abstract contract BridgeCore is ERC7786Recipient {
+    using Bytes for bytes;
+    using InteroperableAddress for bytes;
+
+    struct Link {
+        address gateway;
+        bytes remote;
+    }
+    mapping(bytes chain => Link) private _links;
+
+    event RemoteRegistered(address gateway, bytes remote);
+
+    error RemoteAlreadyRegistered(bytes chain);
+
+    constructor(Link[] memory links) {
+        for (uint256 i = 0; i < links.length; ++i) {
+            _setLink(links[0].gateway, links[0].remote, false);
+        }
+    }
+
+    /// @dev Returns the ERC-7786 gateway used for sending and receiving cross-chain messages to a given chain
+    function link(bytes memory chain) public view virtual returns (address gateway, bytes memory remote) {
+        Link storage self = _links[chain];
+        return (self.gateway, self.remote);
+    }
+
+    /// @dev Internal setter to change the ERC-7786 gateway and remote for a given chain. Called at construction.
+    function _setLink(address gateway, bytes memory remote, bool allowOverride) internal virtual {
+        // Sanity check, this should revert if gateway is not an ERC-7786 implementation. Note that since
+        // supportsAttribute returns data, an EOA would fail that test (nothing returned).
+        IERC7786GatewaySource(gateway).supportsAttribute(bytes4(0));
+
+        bytes memory chain = _extractChain(remote);
+        if (allowOverride || _links[chain].gateway == address(0)) {
+            _links[chain] = Link(gateway, remote);
+            emit RemoteRegistered(gateway, remote);
+        } else {
+            revert RemoteAlreadyRegistered(chain);
+        }
+    }
+
+    /// @dev Internal messaging function.
+    function _sendMessage(
+        bytes memory chain,
+        bytes memory payload,
+        bytes[] memory attributes
+    ) internal virtual returns (bytes32) {
+        (address gateway, bytes memory remote) = link(chain);
+        return IERC7786GatewaySource(gateway).sendMessage(remote, payload, attributes);
+    }
+
+    /// @inheritdoc ERC7786Recipient
+    function _isAuthorizedGateway(
+        address instance,
+        bytes calldata sender
+    ) internal view virtual override returns (bool) {
+        (address gateway, bytes memory router) = link(_extractChain(sender));
+        return instance == gateway && sender.equal(router);
+    }
+
+    function _extractChain(bytes memory self) private pure returns (bytes memory) {
+        (bytes2 chainType, bytes memory chainReference, ) = self.parseV1();
+        return InteroperableAddress.formatV1(chainType, chainReference, hex"");
+    }
+}

contracts/crosschain/bridges/BridgeERC20.sol

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {InteroperableAddress} from "../../utils/draft-InteroperableAddress.sol";
+import {ERC7786Recipient} from "../ERC7786Recipient.sol";
+import {BridgeCore} from "./BridgeCore.sol";
+
+/**
+ * @dev Base contract for bridging ERC-20 between chains using an ERC-7786 gateway.
+ *
+ * In order to use this contract, two function must be implemented to link it to the token:
+ * * {lock}: called when a crosschain transfer is going out. Must take the sender tokens or revert.
+ * * {unlock}: called when a crosschain transfer is coming it. Must give tokens to the receiver.
+ *
+ * This base contract is used by the {BridgeERC20Custodial}, which interfaces with legacy ERC-20 tokens, and
+ * {BrdigeERC20Bridgeable}, which interface with ERC-7802 to provide an approve-free user experience. It is also used
+ * by the {ERC20Crosschain} extension, which embeds the bridge logic directly in the token contract.
+ */
+abstract contract BridgeERC20 is BridgeCore {
+    using InteroperableAddress for bytes;
+
+    event CrossChainTransferSent(bytes32 indexed sendId, address indexed from, bytes to, uint256 amount);
+    event CrossChainTransferReceived(bytes32 indexed receiveId, bytes from, address indexed to, uint256 amount);
+
+    /// @dev Transfer `amount` tokens to a crosschain receiver.
+    function crosschainTransfer(bytes memory to, uint256 amount) public virtual returns (bytes32) {
+        return _crosschainTransfer(msg.sender, to, amount);
+    }
+
+    /// @dev Internal crosschain transfer function.
+    function _crosschainTransfer(address from, bytes memory to, uint256 amount) internal virtual returns (bytes32) {
+        _lock(from, amount);
+
+        (bytes2 chainType, bytes memory chainReference, bytes memory addr) = to.parseV1();
+        bytes memory chain = InteroperableAddress.formatV1(chainType, chainReference, hex"");
+
+        bytes32 sendId = _sendMessage(
+            chain,
+            abi.encode(InteroperableAddress.formatEvmV1(block.chainid, from), addr, amount),
+            new bytes[](0)
+        );
+
+        emit CrossChainTransferSent(sendId, from, to, amount);
+
+        return sendId;
+    }
+
+    /// @inheritdoc ERC7786Recipient
+    function _processMessage(
+        address /*gateway*/,
+        bytes32 receiveId,
+        bytes calldata /*sender*/,
+        bytes calldata payload
+    ) internal virtual override {
+        // split payload
+        (bytes memory from, bytes memory toBinary, uint256 amount) = abi.decode(payload, (bytes, bytes, uint256));
+        address to = address(bytes20(toBinary));
+
+        _unlock(to, amount);
+
+        emit CrossChainTransferReceived(receiveId, from, to, amount);
+    }
+
+    /// @dev Virtual function: implementation is required to handle token being burnt or locked on the source chain.
+    function _lock(address from, uint256 amount) internal virtual;
+
+    /// @dev Virtual function: implementation is required to handle token being minted or unlocked on the destination chain.
+    function _unlock(address to, uint256 amount) internal virtual;
+}

contracts/crosschain/bridges/BridgeERC20Bridgeable.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {IERC7802} from "../../interfaces/draft-IERC7802.sol";
+import {BridgeERC20} from "./BridgeERC20.sol";
+
+/**
+ * @dev This is a variant of {BridgeERC20} that implements the bridge logic for ERC-7802 compliant tokens.
+ */
+abstract contract BridgeERC20Bridgeable is BridgeERC20 {
+    IERC7802 private immutable _token;
+
+    constructor(IERC7802 token_) {
+        _token = token_;
+    }
+
+    /// @dev Return the address of the ERC20 token this bridge operates on.
+    function token() public view virtual returns (IERC7802) {
+        return _token;
+    }
+
+    /// @dev "Locking" tokens using an ERC-7802 crosschain burn
+    function _lock(address from, uint256 amount) internal virtual override {
+        token().crosschainBurn(from, amount);
+    }
+
+    /// @dev "Unlocking" tokens using an ERC-7802 crosschain burn
+    function _unlock(address to, uint256 amount) internal virtual override {
+        token().crosschainMint(to, amount);
+    }
+}

contracts/crosschain/bridges/BridgeERC20Custodial.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {IERC20, SafeERC20} from "../../token/ERC20/utils/SafeERC20.sol";
+import {BridgeERC20} from "./BridgeERC20.sol";
+
+/**
+ * @dev This is a variant of {BridgeERC20} that implements the bridge logic for ERC-20 tokens that do not expose mint
+ * and burn mechanism. Instead it takes custody of bridged assets.
+ */
+abstract contract BridgeERC20Custodial is BridgeERC20 {
+    using SafeERC20 for IERC20;
+
+    IERC20 private immutable _token;
+
+    constructor(IERC20 token_) {
+        _token = token_;
+    }
+
+    /// @dev Return the address of the ERC20 token this bridge operates on.
+    function token() public view virtual returns (IERC20) {
+        return _token;
+    }
+
+    /// @dev "Locking" tokens is done by taking custody
+    function _lock(address from, uint256 amount) internal virtual override {
+        token().safeTransferFrom(from, address(this), amount);
+    }
+
+    /// @dev "Unlocking" tokens is done by releasing custody
+    function _unlock(address to, uint256 amount) internal virtual override {
+        token().safeTransfer(to, amount);
+    }
+}

contracts/interfaces/draft-IERC7786.sol

@@ -15,7 +15,7 @@ interface IERC7786GatewaySource {
     event MessageSent(
         bytes32 indexed sendId,
         bytes sender, // Binary Interoperable Address
-        bytes receiver, // Binary Interoperable Address
+        bytes recipient, // Binary Interoperable Address
         bytes payload,
         uint256 value,
         bytes[] attributes
@@ -49,7 +49,7 @@ interface IERC7786GatewaySource {
  *
  * See ERC-7786 for more details
  */
-interface IERC7786Receiver {
+interface IERC7786Recipient {
     /**
      * @dev Endpoint for receiving cross-chain message.
      *

contracts/mocks/crosschain/ERC7786GatewayMock.sol

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.27;
+
+import {IERC7786GatewaySource, IERC7786Recipient} from "../../interfaces/draft-IERC7786.sol";
+import {InteroperableAddress} from "../../utils/draft-InteroperableAddress.sol";
+
+abstract contract ERC7786GatewayMock is IERC7786GatewaySource {
+    using InteroperableAddress for bytes;
+
+    error InvalidDestination();
+    error ReceiverError();
+
+    uint256 private _lastReceiveId;
+
+    /// @inheritdoc IERC7786GatewaySource
+    function supportsAttribute(bytes4 /*selector*/) public view virtual returns (bool) {
+        return false;
+    }
+
+    /// @inheritdoc IERC7786GatewaySource
+    function sendMessage(
+        bytes calldata recipient,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) public payable virtual returns (bytes32 sendId) {
+        // attributes are not supported
+        if (attributes.length > 0) {
+            revert UnsupportedAttribute(bytes4(attributes[0]));
+        }
+
+        // parse recipient
+        (bool success, uint256 chainid, address target) = recipient.tryParseEvmV1Calldata();
+        require(success && chainid == block.chainid, InvalidDestination());
+
+        // perform call
+        bytes4 magic = IERC7786Recipient(target).receiveMessage{value: msg.value}(
+            bytes32(++_lastReceiveId),
+            InteroperableAddress.formatEvmV1(block.chainid, msg.sender),
+            payload
+        );
+        require(magic == IERC7786Recipient.receiveMessage.selector, ReceiverError());
+
+        // emit standard event
+        emit MessageSent(
+            bytes32(0),
+            InteroperableAddress.formatEvmV1(block.chainid, msg.sender),
+            recipient,
+            payload,
+            msg.value,
+            attributes
+        );
+
+        return 0;
+    }
+}