Inbox Contract

​

Inbox Contract Design

The Inbox is responsible for fulfilling intents on the destination chain. It contains 6 primary functions:

• fulfillStorage — this function is used to fulfill requests that specified the Native Path (which uses storage proofs) during intent origination.

• fulfillHyperInstant — this function is used to fulfill requests that specified the Hyperprover Path during intent origination. It immediately dispatches a Hyperlane message to prove the intent fulfillment on the Origin chain.

• fulfillHyperInstantWithRelayer — this function is used to fulfill requests that specified the Hyperprover Path during intent origination. It immediately dispatches a Hyperlane message to prove the intent fulfillment on the Origin chain and allows for the use of any relayer for relaying the message.

• fulfillHyperBatched— this function is used to fulfill requests that specified the Hyperprover Path during intent origination. Instead of immediately dispatching, it allows intents to be queued in a batch message sent through Hyperlane later.

• fulfillHyperBatchedWithRelayer — this function is used to fulfill requests that specified the Hyperprover Path during intent origination. Instead of immediately dispatching, it allows intents to be queued in a batch message sent through Hyperlane later. It also allows for the use of any relayer for relaying the message.

• sendBatch— this function is used to send a batch of intents through Hyperlane that opted for the fulfillHyperBatchedoption when filling an intent.

All code snippets in this section reference this specific commit.

​

Intent Fulfillment

Intent fulfillment is managed through the internal _fulfill function on the Inbox contract. All of the fulfilling methods enter this internal function, so it’s best to explain it first. The function accepts as input the route information, the reward hash, the claimant, and the expected hash. The reward hash is the hash of the reward struct that was used to fund the intent — using the hash allows for efficient use of calldata and gas.

The function first checks that the destination chain is correct, then checks that the solver is authorized to fulfill the intent, and then checks that the intent hash is valid. If the intent has already been fulfilled, the function reverts. If the intent is valid, the function then transfers the tokens to the inbox, calls the downstream functions requested by the intent, and then stores the results of the calls.

    function _fulfill(
        Route memory _route,
        bytes32 _rewardHash,
        address _claimant,
        bytes32 _expectedHash
    ) internal returns (bytes[] memory) {
        if (_route.destination != block.chainid) {
            revert WrongChain(_route.destination);
        }

        if (!isSolvingPublic && !solverWhitelist[msg.sender]) {
            revert UnauthorizedSolveAttempt(msg.sender);
        }

        bytes32 routeHash = keccak256(abi.encode(_route));
        bytes32 intentHash = keccak256(
            abi.encodePacked(routeHash, _rewardHash)
        );

        if (_route.inbox != address(this)) {
            revert InvalidInbox(_route.inbox);
        }

        if (intentHash != _expectedHash) {
            revert InvalidHash(_expectedHash);
        }
        if (fulfilled[intentHash] != address(0)) {
            revert IntentAlreadyFulfilled(intentHash);
        }
        if (_claimant == address(0)) {
            revert ZeroClaimant();
        }

        fulfilled[intentHash] = _claimant;
        emit Fulfillment(_expectedHash, _route.source, _claimant);

        uint256 routeTokenCount = _route.tokens.length;
        // Transfer ERC20 tokens to the inbox
        for (uint256 i = 0; i < routeTokenCount; ++i) {
            TokenAmount memory approval = _route.tokens[i];
            IERC20(approval.token).safeTransferFrom(
                msg.sender,
                address(this),
                approval.amount
            );
        }

        // Store the results of the calls
        bytes[] memory results = new bytes[](_route.calls.length);

        for (uint256 i = 0; i < _route.calls.length; ++i) {
            Call memory call = _route.calls[i];
            if (call.target.code.length == 0 && call.data.length > 0) {
                // no code at this address
                revert CallToEOA(call.target);
            }
            if (call.target == mailbox) {
                // no executing calls on the mailbox
                revert CallToMailbox();
            }
            (bool success, bytes memory result) = call.target.call{
                value: call.value
            }(call.data);
            if (!success) {
                revert IntentCallFailed(
                    call.target,
                    call.data,
                    call.value,
                    result
                );
            }
            results[i] = result;
        }
        return results;
    }

​

Intent Fulfillment (fulfillStorage)

This function is used to fulfill requests that specified the Native Path (which uses storage proofs) during intent origination. It wraps _fulfill and then emits an event.

    function fulfillStorage(
        Route memory _route,
        bytes32 _rewardHash,
        address _claimant,
        bytes32 _expectedHash
    )
        public
        payable
        override(IInbox, Eco7683DestinationSettler)
        returns (bytes[] memory)
    {
        bytes[] memory result = _fulfill(
            _route,
            _rewardHash,
            _claimant,
            _expectedHash
        );

        emit ToBeProven(_expectedHash, _route.source, _claimant);

        return result;
    }

​

Intent Fulfillment (fulfillHyperInstant)

This function is used to fulfill requests that specified the Hyperprover Path during intent origination. It immediately dispatches a Hyperlane message to prove the intent fulfillment on the Origin chain.

    function fulfillHyperInstant(
        Route memory _route,
        bytes32 _rewardHash,
        address _claimant,
        bytes32 _expectedHash,
        address _prover
    ) external payable returns (bytes[] memory) {
        return
            fulfillHyperInstantWithRelayer(
                _route,
                _rewardHash,
                _claimant,
                _expectedHash,
                _prover,
                bytes(""),
                address(0)
            );
    }

​

Intent Fulfillment (fulfillHyperBatched)

This function is used to fulfill requests that specified the Hyperprover Path during intent origination. Instead of immediately dispatching, it allows intents to be queued in a batch message sent through Hyperlane later.

    function fulfillHyperBatched(
        Route calldata _route,
        bytes32 _rewardHash,
        address _claimant,
        bytes32 _expectedHash,
        address _prover
    ) external payable returns (bytes[] memory) {
        emit AddToBatch(_expectedHash, _route.source, _claimant, _prover);

        bytes[] memory results = _fulfill(
            _route,
            _rewardHash,
            _claimant,
            _expectedHash
        );

        return results;
    }

The sendBatch function takes a list of intent IDs, and relays them to a specific source chain via a batched Hyperlane message.

    function sendBatch(
        uint256 _sourceChainID,
        address _prover,
        bytes32[] calldata _intentHashes
    ) external payable {
        sendBatchWithRelayer(
            _sourceChainID,
            _prover,
            _intentHashes,
            bytes(""),
            address(0)
        );
    }

​

Relayer Choice

Two additional functions allow for the use of any relayer for relaying the message, which are sendBatchWithRelayer and fulfillHyperBatchedWithRelayer. This is useful for users who want to use a specific relayer for their fulfillment. For information on how to run a relayer, please refer to the Relayer Documentation.

​

Design Discussion

​

Hash Reference and Solver Race Conditions

As mentioned in the Intent Contract Design, the hash is used on all contracts in the system as a reference and to enforce uniqueness. In the Inbox contract, the hash is also used to prevent a given hash from being fulfilled more than once.

If a solver tries to solve an intent after another solver has successfully solved it, then the intent will revert with an IntentAlreadyFulfilled error. This prevents solvers from accidentally solving intents twice.

This does create a race condition if two solvers submit transactions at the same time trying to solve the same intent. Future versions of the protocol will intend to deal with this for chains where conditional execution cannot be achieved through the use of bundlers (see Future Directions on the IntentSource contract page).

​

Contract Call Execution

​

Future Directions

Future versions of the Eco Protocol will introduce significant flexibility around the solver fulfillment process. Below are some possible future improvements relevant to the Inbox contract, which are also discussed in more detail in Future Directions.

• Delegate Calls / Helper Contracts — In the Beta release, the system is dependent on solvers prefilling the Inbox contract for stablecoin transfers via multicalls. This is a more secure way to deal with arbitrary call execution, but DelegateCall and helper contracts will be added in the Mainnet launch to support more gas efficient execution.