Inbox Contract

An overview of the Inbox contract, responsible for managing intent fulfillment, preventing double fills, and filler whitelisting (for the Alpha).

Each destination chain supported by the Eco Protocol has one Inbox contract.

Intent Contract Design

The Inbox contract contains one primary functions: fulfill, which is explained below. All code snippets in this section reference this specific commit.

Intent Fulfillment

Intent fulfillment is managed through the fulfill function on the Inbox contract. When a filler goes to fulfill a transfer request on chain, they call this function and supply data specifying the:

• Source Chain

• Array of Contracts to Call

• Array of Calldata for those Functions

• Expiration Time

• Nonce

• Claimant for Reward

• Expected Hash

function fulfill(
    uint256 _sourceChainID,
    address[] calldata _targets,
    bytes[] calldata _data,
    uint256 _expiryTime,
    bytes32 _nonce,
    address _claimant,
    bytes32 _expectedHash
) external validated(_expiryTime, msg.sender) returns (bytes[] memory) {
    bytes32 intentHash =
        encodeHash(_sourceChainID, block.chainid, address(this), _targets, _data, _expiryTime, _nonce);

    // revert if locally calculated hash does not match expected hash
    if (intentHash != _expectedHash) {
        revert InvalidHash(_expectedHash);
    }

    // revert if intent has already been fulfilled
    if (fulfilled[intentHash] != address(0)) {
        revert IntentAlreadyFulfilled(intentHash);
    }

After running a few sanity checks (like making sure the intent has already been fulfilled), the contract takes the inputs, and calls the downstream functions requested by the intent. If any of the calls are unsuccessful, the fulfill call reverts and the intent remains unfulfilled. If all the calls are successful, the intent is marked as fulfilled and the claimant is designated as the eligible recipient for the rewards.

// Store the results of the calls
bytes[] memory results = new bytes[](_data.length);
// Call the addresses with the calldata
for (uint256 i = 0; i < _data.length; i++) {
    (bool success, bytes memory result) = _targets[i].call(_data[i]);
    if (!success) {
        revert IntentCallFailed(_targets[i], _data[i], result);
    }
    results[i] = result;
}
// Mark the intent as fulfilled
fulfilled[intentHash] = _claimant;

// Emit an event
emit Fulfillment(intentHash, _sourceChainID, _claimant);

// Return the results
return results;

Design Discussion

Fulfill Parameters

The fulfill function requires the filler to specify many parameters as part of intent fulfillment.

• Source Chain — This specifies the ID of the origin chain where the the requested intent was submitted to the IntentSource contract.

• Array of Contracts to Call — This specifies the list of contracts that the filler is calling on the destination chain.

• Array of Calldata for those Functions — This specifies the list of corresponding function signatures and calldata that pair with the contracts to call.

• Expiration Time — This specifies the expiration blocktime after which the intent will be considered expired. If the intent fulfillment is not proven by this time, the intent originator can claw back their funds. This expiration time must be appropriately set to the proving method chosen by the intent creator.

• Nonce — This represents the unique nonce generated in the IntentSource contract as part of intent origination.

• Claimant for Reward — This specifies the eligible claimant for the rewards on the source chain.

• Expected Hash — This specifies the expected hash the filler anticipated, to protect the filler in case there is some issue during construction of the fulfill transaction.

Hash Reference and Filler 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 filler tries to solve an intent after another filler has successfully solved it, then the intent will revert with an IntentAlreadyFulfilled error. This prevents filler from accidentally solving intents twice.

This does create a race condition if two fillers 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

Intent creators will need to be careful when creating intents for contracts that may not produce deterministic outcomes. Some contracts may successfully complete calls without obtaining the desired outcome that intent creators wanted.

Likewise, fillers will need to be careful not to fill intents that contain function calls. If not careful, they could be quickly drained of funds.