ERC-7786 interfaces and receiver

.changeset/khaki-keys-burn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC-7786`: Add interfaces for the ERC-7786 gateways and receiver, and a receiver base contract.

contracts/crosschain/draft-ERC7786Receiver.sol

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import {IERC7786GatewayDestinationPassive, IERC7786Receiver} from "../interfaces/draft-IERC7786.sol";
+
+/**
+ * @dev Base implementation of an ERC-7786 compliant cross-chain message receiver.
+ *
+ * This abstract contract exposes the `receiveMessage` function that is used in both active and passive mode for
+ * communication with (one or multiple) destination gateways. This contract leaves two function unimplemented:
+ *
+ * `_isKnownGateway(address)`, 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.
+ */
+abstract contract ERC7786Receiver is IERC7786Receiver {
+    error ERC7786ReceiverInvalidGateway(address gateway);
+
+    /// @inheritdoc IERC7786Receiver
+    function receiveMessage(
+        address gateway,
+        bytes calldata gatewayMessageKey,
+        string calldata source,
+        string calldata sender,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) public payable virtual {
+        if (_isKnownGateway(msg.sender)) {
+            // Active mode
+            // no extra check
+        } else if (_isKnownGateway(gateway)) {
+            // Passive mode
+            IERC7786GatewayDestinationPassive(gateway).validateReceivedMessage(
+                gatewayMessageKey,
+                source,
+                sender,
+                payload,
+                attributes
+            );
+        } else {
+            revert ERC7786ReceiverInvalidGateway(gateway);
+        }
+        _processMessage(gateway, source, sender, payload, attributes);
+    }
+
+    /// @dev Virtual getter that returns weither an address in a valid ERC-7786 gateway.
+    function _isKnownGateway(address instance) internal view virtual returns (bool);
+
+    /// @dev Virtual function that should contain the logic to execute when a crosschain message is received.
+    function _processMessage(
+        address gateway,
+        string calldata source,
+        string calldata sender,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) internal virtual;
+}

contracts/interfaces/README.adoc

@@ -41,6 +41,7 @@ are useful to interact with third party contracts that implement them.
 - {IERC5805}
 - {IERC6372}
 - {IERC7674}
+- {IERC7786}
 
 == Detailed ABI
 
@@ -83,3 +84,5 @@ are useful to interact with third party contracts that implement them.
 {{IERC6372}}
 
 {{IERC7674}}
+
+{{IERC7786}}

contracts/interfaces/draft-IERC7786.sol

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+/**
+ * @dev Interface for ERC-7786 source gateways.
+ *
+ * See ERC-7786 for more details
+ */
+interface IERC7786GatewaySource {
+    /**
+     * @dev Event emitted when a message is created. If `outboxId` is zero, no further processing is necessary, and
+     * not {MessageSent} event SHOULD be expected. If `outboxId` is not zero, then further (gateway specific, and non
+     * standardized) action is required.
+     */
+    event MessageCreated(
+        bytes32 outboxId,
+        string sender, // CAIP-10 account ID
+        string receiver, // CAIP-10 account ID
+        bytes payload,
+        bytes[] attributes
+    );
+
+    /**
+     * @dev This event is emitted when a message, for which the {MessageCreated} event contains an non zero `outboxId`,
+     * received the required post processing actions, and was thus sent to the destination chain.
+     */
+    event MessageSent(bytes32 indexed outboxId);
+
+    /// @dev This error is thrown when a message creation fails because of an unsupported attribute being specified.
+    error UnsuportedAttribute(bytes4 selector);
+
+    /// @dev Getter to check weither an attribute is supported.
+    function supportsAttribute(bytes4 selector) external view returns (bool);
+
+    /**
+     * @dev Endpoint for creating a new message. If the message requires further (gateway specific) processing before
+     * it can be sent to the destination chain, then a non-zero `outboxId` must be returned. Otherwise, this the
+     * message MUST be sent and this function must return 0.
+     *
+     * * MUST emit a {MessageCreated} event.
+     * * SHOULD NOT emit a {MessageSent} event.
+     *
+     * If any of the `attributes` is not supported, this function SHOULD revert with an {UnsuportedAttribute} error.
+     * Other errors SHOULD revert with errors not specified in ERC-7786.
+     */
+    function sendMessage(
+        string calldata destination, // CAIP-2 chain ID
+        string calldata receiver, // CAIP-10 account ID
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) external payable returns (bytes32 outboxId);
+}
+
+/**
+ * @dev Interface for ERC-7786 destination gateways operating in passive mode.
+ *
+ * See ERC-7786 for more details
+ */
+interface IERC7786GatewayDestinationPassive {
+    error InvalidMessageKey(bytes messageKey);
+
+    /**
+     * @dev Endpoint for checking the validity of a message that is being relayed in passive mode. The message
+     * receiver is implicitelly the caller of this method, which guarantees that no-one but the receiver can
+     * "consume" the message. This function MUST implement replay protection, meaning that if called multiple time
+     * for same message, all but the first calls MUST revert.
+     *
+     * NOTE: implementing this interface is OPTIONAL. Some destination gateway MAY only support active mode.
+     */
+    function validateReceivedMessage(
+        bytes calldata messageKey,
+        string calldata source,
+        string calldata sender,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) external;
+}
+
+/**
+ * @dev Interface for the ERC-7786 client contracts (receiver).
+ *
+ * See ERC-7786 for more details
+ */
+interface IERC7786Receiver {
+    /**
+     * @dev Endpoint for receiving cross-chain message.
+     *
+     * This function may be called directly by the gateway (active mode) or by a third party (passive mode).
+     */
+    function receiveMessage(
+        address gateway,
+        bytes calldata gatewayMessageKey,
+        string calldata source,
+        string calldata sender,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) external payable;
+}

contracts/mocks/Stateless.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.20;
+pragma solidity ^0.8.25;
 
 // We keep these imports and a dummy contract just to we can run the test suite after transpilation.
 

contracts/mocks/crosschain/ERC7786GatewayMock.sol

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.25;
+
+import {IERC7786GatewaySource, IERC7786GatewayDestinationPassive, IERC7786Receiver} from "../../interfaces/draft-IERC7786.sol";
+import {BitMaps} from "../../utils/structs/BitMaps.sol";
+import {Strings} from "../../utils/Strings.sol";
+import {CAIP2} from "../../utils/CAIP2.sol";
+import {CAIP10} from "../../utils/CAIP10.sol";
+
+contract ERC7786GatewayMock is IERC7786GatewaySource, IERC7786GatewayDestinationPassive {
+    using BitMaps for BitMaps.BitMap;
+    using Strings for *;
+
+    BitMaps.BitMap private _outbox;
+    bool private _activeMode;
+
+    function _setActive(bool newActiveMode) internal {
+        _activeMode = newActiveMode;
+    }
+
+    function supportsAttribute(bytes4 /*selector*/) public pure returns (bool) {
+        return false;
+    }
+
+    function sendMessage(
+        string calldata destination, // CAIP-2 chain ID
+        string calldata receiver, // CAIP-10 account ID
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) public payable returns (bytes32) {
+        string memory source = CAIP2.local();
+        string memory sender = msg.sender.toChecksumHexString();
+
+        require(destination.equal(source), "This mock only supports local messages");
+        for (uint256 i = 0; i < attributes.length; ++i) {
+            bytes4 selector = bytes4(attributes[i][0:4]);
+            if (!supportsAttribute(selector)) revert UnsuportedAttribute(selector);
+        }
+
+        if (_activeMode) {
+            address target = Strings.parseAddress(receiver);
+            IERC7786Receiver(target).receiveMessage(address(this), new bytes(0), source, sender, payload, attributes);
+        } else {
+            _outbox.set(uint256(keccak256(abi.encode(source, sender, receiver, payload, attributes))));
+        }
+
+        emit MessageCreated(0, CAIP10.format(source, sender), CAIP10.format(source, receiver), payload, attributes);
+        return 0;
+    }
+
+    function validateReceivedMessage(
+        bytes calldata /*messageKey*/, // this mock doesn't use a messageKey
+        string calldata source,
+        string calldata sender,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) public {
+        uint256 digest = uint256(
+            keccak256(abi.encode(source, sender, msg.sender.toChecksumHexString(), payload, attributes))
+        );
+        require(_outbox.get(digest), "invalid message");
+        _outbox.unset(digest);
+    }
+}

contracts/mocks/crosschain/ERC7786ReceiverMock.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import {ERC7786Receiver} from "../../crosschain/draft-ERC7786Receiver.sol";
+
+contract ERC7786ReceiverMock is ERC7786Receiver {
+    address private immutable _gateway;
+
+    event MessageReceived(address gateway, string source, string sender, bytes payload, bytes[] attributes);
+
+    constructor(address gateway_) {
+        _gateway = gateway_;
+    }
+
+    function _isKnownGateway(address instance) internal view virtual override returns (bool) {
+        return instance == _gateway;
+    }
+
+    function _processMessage(
+        address gateway,
+        string calldata source,
+        string calldata sender,
+        bytes calldata payload,
+        bytes[] calldata attributes
+    ) internal virtual override {
+        emit MessageReceived(gateway, source, sender, payload, attributes);
+    }
+}

contracts/utils/Bytes.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.20;
+pragma solidity ^0.8.25;
 
 import {Math} from "./math/Math.sol";
 

contracts/utils/CAIP10.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.20;
+pragma solidity ^0.8.25;
 
 import {SafeCast} from "./math/SafeCast.sol";
 import {Bytes} from "./Bytes.sol";

contracts/utils/CAIP2.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.20;
+pragma solidity ^0.8.25;
 
 import {SafeCast} from "./math/SafeCast.sol";
 import {Bytes} from "./Bytes.sol";

foundry.toml

@@ -1,5 +1,5 @@
 [profile.default]
-solc_version = '0.8.24'
+solc_version = '0.8.25'
 evm_version = 'cancun'
 optimizer = true
 optimizer-runs = 200

hardhat.config.js

@@ -1,5 +1,5 @@
 /// ENVVAR
-// - COMPILER:      compiler version (default: 0.8.24)
+// - COMPILER:      compiler version (default: 0.8.25)
 // - SRC:           contracts folder to compile (default: contracts)
 // - RUNS:          number of optimization runs (default: 200)
 // - IR:            enable IR compilation (default: false)
@@ -18,7 +18,7 @@ const { argv } = require('yargs/yargs')()
     compiler: {
       alias: 'compileVersion',
       type: 'string',
-      default: '0.8.24',
+      default: '0.8.25',
     },
     src: {
       alias: 'source',