@hyperlane-xyz/core 0.5.0-beta0

package/README.md

@@ -0,0 +1,14 @@
+## Hyperlane Solidity
+
+On-chain implementations of Hyperlane in Solidity.
+
+### Setup
+
+- `npm install --dev`
+- `brew install jq`   OR   `sudo apt-get install jq`
+- `npm install -g solhint`, check it is installed using `solhint --version`
+
+### Build
+
+- `npm run compile`
+- `npm run test`

package/contracts/AbacusConnectionManager.sol

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+// ============ Internal Imports ============
+import {IOutbox} from "../interfaces/IOutbox.sol";
+import {IInbox} from "../interfaces/IInbox.sol";
+import {IAbacusConnectionManager} from "../interfaces/IAbacusConnectionManager.sol";
+import {IMultisigValidatorManager} from "../interfaces/IMultisigValidatorManager.sol";
+
+// ============ External Imports ============
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {Address} from "@openzeppelin/contracts/utils/Address.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+/**
+ * @title AbacusConnectionManager
+ * @author Celo Labs Inc.
+ * @notice Manages a registry of local Inbox contracts for remote Outbox
+ * domains.
+ */
+contract AbacusConnectionManager is IAbacusConnectionManager, Ownable {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+
+    // ============ Public Storage ============
+
+    // Outbox contract
+    IOutbox public override outbox;
+    // local Inbox address => remote Outbox domain
+    mapping(address => uint32) public inboxToDomain;
+    // remote Outbox domain => local Inbox addresses
+    mapping(uint32 => EnumerableSet.AddressSet) internal domainToInboxes;
+    // complete history of enrolled inbox domain hashes, even if unenrolled
+    EnumerableSet.Bytes32Set domainHashes;
+
+    // ============ Events ============
+
+    /**
+     * @notice Emitted when a new Outbox is set.
+     * @param outbox the address of the Outbox
+     */
+    event OutboxSet(address indexed outbox);
+
+    /**
+     * @notice Emitted when a new Inbox is enrolled / added
+     * @param domain the remote domain of the Outbox contract for the Inbox
+     * @param inbox the address of the Inbox
+     */
+    event InboxEnrolled(uint32 indexed domain, address inbox);
+
+    /**
+     * @notice Emitted when a new Inbox is un-enrolled / removed
+     * @param domain the remote domain of the Outbox contract for the Inbox
+     * @param inbox the address of the Inbox
+     */
+    event InboxUnenrolled(uint32 indexed domain, address inbox);
+
+    // ============ Constructor ============
+
+    // solhint-disable-next-line no-empty-blocks
+    constructor() Ownable() {}
+
+    // ============ External Functions ============
+
+    /**
+     * @notice Sets the address of the local Outbox contract.
+     * @param _outbox The address of the new local Outbox contract.
+     */
+    function setOutbox(address _outbox) external onlyOwner {
+        require(Address.isContract(_outbox), "outbox !contract");
+        outbox = IOutbox(_outbox);
+        emit OutboxSet(_outbox);
+    }
+
+    /**
+     * @notice Allow Owner to enroll Inbox contract
+     * @param _domain the remote domain of the Outbox contract for the Inbox
+     * @param _inbox the address of the Inbox
+     */
+    function enrollInbox(uint32 _domain, address _inbox) external onlyOwner {
+        require(Address.isContract(_inbox), "inbox !contract");
+        require(!isInbox(_inbox), "already inbox");
+
+        // prevent enrolling an inbox that matches any previously enrolled domain hash
+        bytes32 domainHash = getDomainHash(_inbox);
+        require(
+            !domainHashes.contains(domainHash),
+            "domain hash previously enrolled"
+        );
+        domainHashes.add(domainHash);
+
+        // add inbox and domain to two-way mapping
+        inboxToDomain[_inbox] = _domain;
+        require(domainToInboxes[_domain].add(_inbox), "already enrolled");
+        emit InboxEnrolled(_domain, _inbox);
+    }
+
+    /**
+     * @notice Allow Owner to un-enroll Inbox contract
+     * @param _inbox the address of the Inbox
+     */
+    function unenrollInbox(address _inbox) external onlyOwner {
+        _unenrollInbox(_inbox);
+    }
+
+    /**
+     * @notice Query local domain from Outbox
+     * @return local domain
+     */
+    function localDomain() external view override returns (uint32) {
+        return outbox.localDomain();
+    }
+
+    /**
+     * @notice Returns the Inbox addresses for a given remote domain
+     * @return inboxes An array of addresses of the Inboxes
+     */
+    function getInboxes(uint32 remoteDomain)
+        external
+        view
+        returns (address[] memory)
+    {
+        EnumerableSet.AddressSet storage _inboxes = domainToInboxes[
+            remoteDomain
+        ];
+        uint256 length = _inboxes.length();
+        address[] memory ret = new address[](length);
+        for (uint256 i = 0; i < length; i += 1) {
+            ret[i] = _inboxes.at(i);
+        }
+        return ret;
+    }
+
+    // ============ Public Functions ============
+
+    /**
+     * @notice Check whether _inbox is enrolled
+     * @param _inbox the inbox to check for enrollment
+     * @return TRUE iff _inbox is enrolled
+     */
+    function isInbox(address _inbox) public view override returns (bool) {
+        return inboxToDomain[_inbox] != 0;
+    }
+
+    /**
+     * @notice Check whether _inbox is enrolled
+     * @param _inbox the inbox to check for enrollment
+     * @return TRUE iff _inbox is enrolled
+     */
+    function getDomainHash(address _inbox) public view returns (bytes32) {
+        IInbox inbox = IInbox(_inbox);
+        address vm = inbox.validatorManager();
+        return IMultisigValidatorManager(vm).domainHash();
+    }
+
+    // ============ Internal Functions ============
+
+    /**
+     * @notice Remove the inbox from the two-way mappings
+     * @param _inbox inbox to un-enroll
+     */
+    function _unenrollInbox(address _inbox) internal {
+        uint32 _currentDomain = inboxToDomain[_inbox];
+        require(domainToInboxes[_currentDomain].remove(_inbox), "not enrolled");
+        inboxToDomain[_inbox] = 0;
+        emit InboxUnenrolled(_currentDomain, _inbox);
+    }
+}

package/contracts/Inbox.sol

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+// ============ Internal Imports ============
+import {Versioned} from "./upgrade/Versioned.sol";
+import {Mailbox} from "./Mailbox.sol";
+import {MerkleLib} from "./libs/Merkle.sol";
+import {Message} from "./libs/Message.sol";
+import {TypeCasts} from "./libs/TypeCasts.sol";
+import {IMessageRecipient} from "../interfaces/IMessageRecipient.sol";
+import {IInbox} from "../interfaces/IInbox.sol";
+
+// ============ External Imports ============
+import {ReentrancyGuardUpgradeable} from "@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol";
+
+/**
+ * @title Inbox
+ * @author Celo Labs Inc.
+ * @notice Track root updates on Outbox, prove and dispatch messages to end
+ * recipients.
+ */
+contract Inbox is IInbox, ReentrancyGuardUpgradeable, Versioned, Mailbox {
+    // ============ Libraries ============
+
+    using MerkleLib for MerkleLib.Tree;
+    using Message for bytes;
+    using TypeCasts for bytes32;
+
+    // ============ Enums ============
+
+    // Status of Message:
+    //   0 - None - message has not been processed
+    //   1 - Processed - message has been dispatched to recipient
+    enum MessageStatus {
+        None,
+        Processed
+    }
+
+    // ============ Public Storage ============
+
+    // Domain of outbox chain
+    uint32 public override remoteDomain;
+    // Mapping of message leaves to MessageStatus
+    mapping(bytes32 => MessageStatus) public messages;
+
+    // ============ Upgrade Gap ============
+
+    // gap for upgrade safety
+    uint256[48] private __GAP;
+
+    // ============ Events ============
+
+    /**
+     * @notice Emitted when message is processed
+     * @dev This event allows watchers to observe the merkle proof they need
+     * to prove fraud on the Outbox.
+     * @param messageHash Hash of message that was processed.
+     */
+    event Process(bytes32 indexed messageHash);
+
+    // ============ Constructor ============
+
+    // solhint-disable-next-line no-empty-blocks
+    constructor(uint32 _localDomain) Mailbox(_localDomain) {}
+
+    // ============ Initializer ============
+
+    function initialize(uint32 _remoteDomain, address _validatorManager)
+        external
+        initializer
+    {
+        __ReentrancyGuard_init();
+        __Mailbox_initialize(_validatorManager);
+        remoteDomain = _remoteDomain;
+    }
+
+    // ============ External Functions ============
+
+    /**
+     * @notice Attempts to process the provided formatted `message`. Performs
+     * verification against root of the proof
+     * @dev Called by the validator manager, which is responsible for verifying a
+     * quorum of validator signatures on the checkpoint.
+     * @dev Reverts if verification of the message fails.
+     * @param _root The merkle root of the checkpoint used to prove message inclusion.
+     * @param _index The index of the checkpoint used to prove message inclusion.
+     * @param _message Formatted message (refer to Mailbox.sol Message library)
+     * @param _proof Merkle proof of inclusion for message's leaf
+     * @param _leafIndex Index of leaf in outbox's merkle tree
+     */
+    function process(
+        bytes32 _root,
+        uint256 _index,
+        bytes calldata _message,
+        bytes32[32] calldata _proof,
+        uint256 _leafIndex
+    ) external override nonReentrant onlyValidatorManager {
+        require(_index >= _leafIndex, "!index");
+        bytes32 _messageHash = _message.leaf(_leafIndex);
+        // ensure that message has not been processed
+        require(
+            messages[_messageHash] == MessageStatus.None,
+            "!MessageStatus.None"
+        );
+        // calculate the expected root based on the proof
+        bytes32 _calculatedRoot = MerkleLib.branchRoot(
+            _messageHash,
+            _proof,
+            _leafIndex
+        );
+        // verify the merkle proof
+        require(_calculatedRoot == _root, "!proof");
+        _process(_message, _messageHash);
+    }
+
+    // ============ Internal Functions ============
+
+    /**
+     * @notice Marks a message as processed and calls handle on the recipient
+     * @dev Internal function that can be called by contracts like TestInbox
+     * @param _message Formatted message (refer to Mailbox.sol Message library)
+     * @param _messageHash keccak256 hash of the message
+     */
+    function _process(bytes calldata _message, bytes32 _messageHash) internal {
+        (
+            uint32 origin,
+            bytes32 sender,
+            uint32 destination,
+            bytes32 recipient,
+            bytes calldata body
+        ) = _message.destructure();
+
+        // ensure message came from the correct domain
+        require(origin == remoteDomain, "!origin");
+        // ensure message was meant for this domain
+        require(destination == localDomain, "!destination");
+
+        // update message status as processed
+        messages[_messageHash] = MessageStatus.Processed;
+
+        IMessageRecipient(recipient.bytes32ToAddress()).handle(
+            origin,
+            sender,
+            body
+        );
+        emit Process(_messageHash);
+    }
+}

package/contracts/InterchainGasPaymaster.sol

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+// ============ Internal Imports ============
+import {IInterchainGasPaymaster} from "../interfaces/IInterchainGasPaymaster.sol";
+// ============ External Imports ============
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+
+/**
+ * @title InterchainGasPaymaster
+ * @notice Manages payments on a source chain to cover gas costs of relaying
+ * messages to destination chains.
+ */
+contract InterchainGasPaymaster is IInterchainGasPaymaster, OwnableUpgradeable {
+    // ============ Events ============
+
+    /**
+     * @notice Emitted when a payment is made for a message's gas costs.
+     * @param outbox The address of the Outbox contract.
+     * @param leafIndex The index of the message in the Outbox merkle tree.
+     * @param amount The amount of native tokens paid.
+     */
+    event GasPayment(address indexed outbox, uint256 leafIndex, uint256 amount);
+
+    // ============ Constructor ============
+
+    // solhint-disable-next-line no-empty-blocks
+    constructor() {
+        initialize(); // allows contract to be used without proxying
+    }
+
+    // ============ External Functions ============
+
+    function initialize() public initializer {
+        __Ownable_init();
+    }
+
+    /**
+     * @notice Deposits msg.value as a payment for the relaying of a message
+     * to its destination chain.
+     * @param _outbox The address of the Outbox contract.
+     * @param _leafIndex The index of the message in the Outbox merkle tree.
+     * @param _destinationDomain The domain of the message's destination chain.
+     */
+    function payGasFor(
+        address _outbox,
+        uint256 _leafIndex,
+        uint32 _destinationDomain
+    ) external payable override {
+        // Silence compiler warning. The NatSpec @param requires the parameter to be named.
+        // While not used at the moment, future versions of the paymaster may conditionally
+        // forward payments depending on the destination domain.
+        _destinationDomain;
+
+        emit GasPayment(_outbox, _leafIndex, msg.value);
+    }
+
+    /**
+     * @notice Transfers the entire native token balance to the owner of the contract.
+     * @dev The owner must be able to receive native tokens.
+     */
+    function claim() external {
+        // Transfer the entire balance to owner.
+        (bool success, ) = owner().call{value: address(this).balance}("");
+        require(success, "!transfer");
+    }
+}

package/contracts/Mailbox.sol

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+// ============ Internal Imports ============
+import {IMailbox} from "../interfaces/IMailbox.sol";
+// ============ External Imports ============
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+import {Address} from "@openzeppelin/contracts/utils/Address.sol";
+
+/**
+ * @title Mailbox
+ * @author Celo Labs Inc.
+ * @notice Shared utilities between Outbox and Inbox.
+ */
+abstract contract Mailbox is IMailbox, OwnableUpgradeable {
+    // ============ Immutable Variables ============
+
+    // Domain of chain on which the contract is deployed
+    uint32 public immutable override localDomain;
+
+    // ============ Public Variables ============
+
+    // Address of the validator manager contract.
+    address public validatorManager;
+
+    // ============ Upgrade Gap ============
+
+    // gap for upgrade safety
+    uint256[49] private __GAP;
+
+    // ============ Events ============
+
+    /**
+     * @notice Emitted when the validator manager contract is changed
+     * @param validatorManager The address of the new validatorManager
+     */
+    event ValidatorManagerSet(address validatorManager);
+
+    // ============ Modifiers ============
+
+    /**
+     * @notice Ensures that a function is called by the validator manager contract.
+     */
+    modifier onlyValidatorManager() {
+        require(msg.sender == validatorManager, "!validatorManager");
+        _;
+    }
+
+    // ============ Constructor ============
+
+    constructor(uint32 _localDomain) {
+        localDomain = _localDomain;
+    }
+
+    // ============ Initializer ============
+
+    function __Mailbox_initialize(address _validatorManager)
+        internal
+        onlyInitializing
+    {
+        // initialize owner
+        __Ownable_init();
+        _setValidatorManager(_validatorManager);
+    }
+
+    // ============ External Functions ============
+
+    /**
+     * @notice Set a new validator manager contract
+     * @dev Mailbox(es) will initially be initialized using a trusted validator manager contract;
+     * we will progressively decentralize by swapping the trusted contract with a new implementation
+     * that implements Validator bonding & slashing, and rules for Validator selection & rotation
+     * @param _validatorManager the new validator manager contract
+     */
+    function setValidatorManager(address _validatorManager) external onlyOwner {
+        _setValidatorManager(_validatorManager);
+    }
+
+    // ============ Internal Functions ============
+
+    /**
+     * @notice Set the validator manager
+     * @param _validatorManager Address of the validator manager
+     */
+    function _setValidatorManager(address _validatorManager) internal {
+        require(
+            Address.isContract(_validatorManager),
+            "!contract validatorManager"
+        );
+        validatorManager = _validatorManager;
+        emit ValidatorManagerSet(_validatorManager);
+    }
+}

package/contracts/MerkleTreeManager.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+// ============ Internal Imports ============
+import {MerkleLib} from "./libs/Merkle.sol";
+
+/**
+ * @title MerkleTreeManager
+ * @author Celo Labs Inc.
+ * @notice Contains a Merkle tree instance and
+ * exposes view functions for the tree.
+ */
+contract MerkleTreeManager {
+    // ============ Libraries ============
+
+    using MerkleLib for MerkleLib.Tree;
+    MerkleLib.Tree public tree;
+
+    // ============ Upgrade Gap ============
+
+    // gap for upgrade safety
+    uint256[49] private __GAP;
+
+    // ============ Public Functions ============
+
+    /**
+     * @notice Calculates and returns tree's current root
+     */
+    function root() public view returns (bytes32) {
+        return tree.root();
+    }
+}