Inbox

Contract for fulfilling intents on the destination chain

Overview

The Inbox contract is the main entry point for fulfilling intents on the destination chain. It validates intent hash authenticity, executes calldata, and enables provers to claim rewards on the source chain by checking the claimants mapping.

Contract Location: contracts/Inbox.sol

Inherits: DestinationSettler, IInbox

State Variables

claimants

mapping(bytes32 => bytes32) public claimants

Mapping of intent hashes to their claimant identifiers. Stores the cross-VM compatible claimant identifier for each fulfilled intent.

executor

IExecutor public immutable executor

Reference to the Executor contract used to execute intent calls.

State-Changing Functions

fulfill

function fulfill(
    bytes32 intentHash,
    Route memory route,
    bytes32 rewardHash,
    bytes32 claimant
) external payable returns (bytes[] memory)

Fulfills an intent to be proven via storage proofs. Validates intent hash, executes calls, and marks as fulfilled.

intentHash · bytes32

The hash of the intent to fulfill

route · Route

The route of the intent containing execution instructions

rewardHash · bytes32

The hash of the reward details

claimant · bytes32

Cross-VM compatible claimant identifier

bytes[] · bytes[]

Array of execution results from each call

This function is payable and requires msg.value to be at least route.nativeAmount. Any excess ETH is automatically refunded to the caller.

---

fulfillAndProve

function fulfillAndProve(
    bytes32 intentHash,
    Route memory route,
    bytes32 rewardHash,
    bytes32 claimant,
    address prover,
    uint64 sourceChainDomainID,
    bytes memory data
) public payable returns (bytes[] memory)

Fulfills an intent and initiates proving in one transaction. Executes intent actions and sends proof message to source chain.

intentHash · bytes32

The hash of the intent to fulfill

route · Route

The route of the intent

rewardHash · bytes32

The hash of the reward details

claimant · bytes32

Cross-VM compatible claimant identifier

prover · address

Address of prover on the destination chain

sourceChainDomainID · uint64

Domain ID of the source chain where the intent was created

data · bytes

Additional data for message formatting

bytes[] · bytes[]

Array of execution results

WARNING: sourceChainDomainID is NOT necessarily the same as chain ID.

Each bridge provider uses their own domain ID mapping system:

• Hyperlane: Uses custom domain IDs that may differ from chain IDs
• LayerZero: Uses endpoint IDs that map to chains differently
• Metalayer: Uses domain IDs specific to their routing system
• Polymer: Uses chain IDs

You MUST consult the specific bridge provider’s documentation to determine the correct domain ID for the source chain.

---

prove

function prove(
    address prover,
    uint64 sourceChainDomainID,
    bytes32[] memory intentHashes,
    bytes memory data
) public payable

Initiates proving process for fulfilled intents. Sends message to source chain to verify intent execution.

prover · address

Address of prover on the destination chain

sourceChainDomainID · uint64

Domain ID of the source chain

intentHashes · bytes32[]

Array of intent hashes to prove

data · bytes

Additional data for message formatting

WARNING: sourceChainDomainID is NOT necessarily the same as chain ID.

Each bridge provider uses their own domain ID mapping system:

• Hyperlane: Uses custom domain IDs that may differ from chain IDs
• LayerZero: Uses endpoint IDs that map to chains differently
• Metalayer: Uses domain IDs specific to their routing system
• Polymer: Uses chain IDs

You MUST consult the specific bridge provider’s documentation to determine the correct domain ID for the source chain.

This function can only prove intents that have already been fulfilled. It will revert with IntentNotFulfilled if any of the provided intent hashes have not been fulfilled yet.

Events

IntentFulfilled

event IntentFulfilled(
    bytes32 indexed intentHash,
    bytes32 indexed claimant
)

Emitted when an intent is successfully fulfilled.

IntentProven

event IntentProven(
    bytes32 indexed intentHash,
    bytes32 indexed claimant
)

Emitted when an intent proof is submitted to the prover.

Errors

ChainIdTooLarge

error ChainIdTooLarge(uint256 chainId)

Thrown when the chain ID exceeds uint64 maximum value.

IntentExpired

error IntentExpired()

Thrown when attempting to fulfill an intent after its deadline.

InvalidPortal

error InvalidPortal(address portal)

Thrown when the route.portal does not match the current contract address.

InvalidHash

error InvalidHash(bytes32 intentHash)

Thrown when the computed intent hash does not match the provided intent hash.

IntentAlreadyFulfilled

error IntentAlreadyFulfilled(bytes32 intentHash)

Thrown when attempting to fulfill an intent that has already been fulfilled.

ZeroClaimant

error ZeroClaimant()

Thrown when the claimant is bytes32(0).

InsufficientNativeAmount

error InsufficientNativeAmount(uint256 provided, uint256 required)

Thrown when msg.value is less than route.nativeAmount.

IntentNotFulfilled

error IntentNotFulfilled(bytes32 intentHash)

Thrown when attempting to prove an intent that has not been fulfilled.

Usage Example

// Fulfill an intent
bytes[] memory results = inbox.fulfill{
    value: route.nativeAmount
}(
    intentHash,
    route,
    rewardHash,
    claimant
);

// Or fulfill and prove in one transaction
bytes[] memory results = inbox.fulfillAndProve{
    value: route.nativeAmount + provingFee
}(
    intentHash,
    route,
    rewardHash,
    claimant,
    proverAddress,
    sourceChainDomainID,
    proofData
);