contracts

API Documentation

Type references can be found in the (types directory)[/types].

IntentSource

The IntentSource is where intent publishing and reward claiming functionality live. Users (or actors on their behalf) can publish intents here, as well as fund intents' rewards. After an intent is fulfilled and proven, a solver can fetch their rewards here as well. This contract is not expected to hold any funds between transactions.

Events

IntentPartiallyFunded

Signals partial funding of an intent with native tokens

Parameters:

• intentHash (bytes32) The hash of the partially funded intent
• funder (address) The address providing the partial funding

IntentFunded

Signals complete funding of an intent with native tokens

Parameters:

• intentHash (bytes32) The hash of the partially funded intent
• funder (address) The address providing the partial funding

IntentCreated

Signals the creation of a new cross-chain intent

Parameters:

• hash (bytes32) Unique identifier of the intent
• salt (bytes32) Creator-provided uniqueness factor
• source (uint256) Source chain identifier
• destination (uint256) Destination chain identifier
• inbox (address) Address of the receiving contract on the destination chain
• routeTokens (TokenAmount[]) Required tokens for executing destination chain calls
• calls (Call[]) Instructions to execute on the destination chain
• creator (address) Intent originator address
• prover (address) Prover contract address
• deadline (address) Timestamp for reward claim eligibility
• nativeValue (uint256) Native token reward amount
• rewardTokens (TokenAmount[]) ERC20 token rewards with amounts

Withdrawal

Signals successful reward withdrawal

Parameters:

• hash (bytes32) The hash of the claimed intent
• recipient (address) The address receiving the rewards

Refund

Signals successful reward refund

Parameters:

• hash (bytes32) The hash of the refunded intent
• recipient (address) The address receiving the refund

Methods

getRewardStatus

Retrieves the current reward claim status for an intent

Parameters:

• intentHash (bytes32) The hash of the intent

getVaultState

Retrieves the current state of an intent's vault

Parameters:

• intentHash (bytes32) The hash of the intent

getPermitContract

Retrieves the permit contract for the token transfers

Parameters:

• intentHash (bytes32) The hash of the intent

getIntentHash

Computes the hash components of an intent

Parameters:

• intent (Intent) The intent to hash

intentVaultAddress

Computes the deterministic vault address for an intent

Parameters:

• intent (Intent) The intent to calculate the vault address for

publish

Creates a new cross-chain intent with associated rewards

Parameters:

• intent (Intent) The complete intent specification

Security: This method can be called to create an intent on anyone's behalf. It does not transfer any funds. It emits an event that would give a solver all the information required to fulfill the intent, but the solver is expected to check that the intent is funded before fulfilling.

publishAndFund

Creates and funds an intent in a single transaction

Parameters:

• intent (Intent) The complete intent specification

Security: This method is called by the user to create and completely fund an intent. It will fail if the funder does not have sufficient balance or has not given the IntentSource authority to move all the reward funds.

fund

Funds an existing intent

Parameters:

• intent (Intent) The complete intent specification
• reward (Reward) Reward structure containing distribution details

Security: This method is called by the user to completely fund an intent. It will fail if the funder does not have sufficient balance or has not given the IntentSource authority to move all the reward funds.

fundFor

Funds an intent for a user with permit/allowance

Parameters:

• routeHash (bytes32) The hash of the intent's route component
• reward (Reward) Reward structure containing distribution details
• funder (address) Address to fund the intent from
• permitContract (address) Address of the permitContract instance
• allowPartial (bool) Whether to allow partial funding

Security: This method will fail if allowPartial is false but incomplete funding is provided. Additionally, this method cannot be called for intents with nonzero native rewards.

publishAndFundFor

Creates and funds an intent using permit/allowance

Parameters:

• intent (Intent) The complete intent specification
• funder (address) Address to fund the intent from
• permitContract (address) Address of the permitContract instance
• allowPartial (bool) Whether to allow partial funding

Security: This method is called by the user to create and completely fund an intent. It will fail if the funder does not have sufficient balance or has not given the IntentSource authority to move all the reward funds.

isIntentFunded

Checks if an intent is completely funded

Parameters:

• intent (Intent) Intent to validate

Security: This method can be called by anyone, but the caller has no specific rights. Whether or not this method succeeds and who receives the funds if it does depend solely on the intent's proven status and expiry time, as well as the claimant address specified by the solver on the Inbox contract on fulfillment.

withdrawRewards

Claims rewards for a successfully fulfilled and proven intent

Parameters:

• routeHash (bytes32) The hash of the intent's route component
• reward (Reward) Reward structure containing distribution details

Security: Can withdraw anyone's intent, but only to the claimant predetermined by its solver. Withdraws to solver only if intent is proven.

batchWithdraw

Claims rewards for multiple fulfilled and proven intents

Parameters:

• routeHashes (bytes32[]) Array of route component hashes
• reward (Reward[]) Array of corresponding reward specifications

Security: Can withdraw anyone's intent, but only to the claimant predetermined by its solver. Withdraws to solver only if intent is proven.

refund

Returns rewards to the intent creator

Parameters:

• routeHashes (bytes32[]) Array of route component hashes
• reward (Reward[]) Array of corresponding reward specifications

Security: Will fail if intent not expired.

recoverToken

Recover tokens that were sent to the intent vault by mistake

Parameters:

• routeHashes (bytes32[]) Array of route component hashes
• reward (Reward[]) Array of corresponding reward specifications
• token (address) Token address for handling incorrect vault transfers

Security: Will fail if token is the zero address or the address of any of the reward tokens. Will also fail if intent has nonzero native token rewards and has not yet been claimed or refunded.

Inbox (Inbox.sol)

The Inbox is where intent fulfillment lives. Solvers fulfill intents on the Inbox via one of the contract's fulfill methods, which pulls in solver resources and executes the intent's calls on the destination chain. Once an intent has been fulfilled, any subsequent attempts to fulfill it will be reverted. The Inbox also contains some post-fulfillment proving-related logic.

Events

Fulfillment

Emitted when an intent is successfully fulfilled

Parameters:

• _hash (bytes32) the hash of the intent
• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _claimant (address) the address (on the source chain) that will receive the fulfilled intent's reward

ToBeProven

Emitted when an intent is ready to be proven via a storage prover

Parameters:

• _hash (bytes32) the hash of the intent
• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _claimant (address) the address (on the source chain) that will receive the fulfilled intent's reward

HyperInstantFulfillment

Emitted when an intent is fulfilled with the instant hyperprover path

Parameters:

• _hash (bytes32) the hash of the intent
• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _claimant (address) the address (on the source chain) that will receive the fulfilled intent's reward

AddToBatch

Emitted when an intent is added to a batch to be proven with the hyperprover

Parameters:

• _hash (bytes32) the hash of the intent
• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _claimant (address) the address (on the source chain) that will receive the fulfilled intent's reward
• _prover (address) the address of the HyperProver these intents will be proven on

AddToBatch

Emitted when an intent is added to a Hyperlane batch

Parameters:

• _hash (bytes32) the hash of the intent
• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _claimant (address) the address (on the source chain) that will receive the fulfilled intent's reward
• _prover (address) the address of the Hyperlane prover

SolvingIsPublic

Emitted when solving is made public

MailboxSet

Emitted when Hyperlane mailbox address is set

Parameters:

• _mailbox (address) address of the mailbox contract

SolverWhitelistChanged

Emitted when the solver whitelist permissions are changed

Parameters:

• _solver (address) the address of the solver whose permissions are being changed
• _canSolve(bool) whether or not _solver will be able to solve after this method is called

Methods

fulfillStorage

Allows a filler to fulfill an intent on its destination chain to be proven by the StorageProver specified in the intent. The filler also gets to predetermine the address on the destination chain that will receive the reward tokens.

Parameters:

• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _targets (address[]) the address on the destination chain at which the instruction sets need to be executed
• _data (bytes[]) the instructions to be executed on _targets
• _expiryTime (uint256) the timestamp at which the intent expires
• _nonce (bytes32) the nonce of the calldata. Composed of the hash on the source chain of the global nonce and chainID
• _claimant (address) the address that can claim the fulfilled intent's fee on the source chain
• _expectedHash (bytes32) the hash of the intent. Used to verify that the correct data is being input

Security: This method can be called by anyone, but cannot be called again for the same intent, thus preventing a double fulfillment. This method executes arbitrary calls written by the intent creator on behalf of the Inbox contract - it is important that the caller be aware of what they are executing. The Inbox will be the msg.sender for these calls. _sourceChainID, the destination's chainID, the inbox address, _targets, _data, _expiryTime, and _nonce are hashed together to form the intent's hash on the IntentSource - any incorrect inputs will result in a hash that differs from the original, and will prevent the intent's reward from being withdrawn (as this means the intent fulfilled differed from the one created). The _expectedHash input exists only to help prevent this before fulfillment.

fulfillHyperInstant

Allows a filler to fulfill an intent on its destination chain to be proven by the HyperProver specified in the intent. After fulfilling the intent, this method packs the intentHash and claimant into a message and sends it over the Hyperlane bridge to the HyperProver on the source chain. The filler also gets to predetermine the address on the destination chain that will receive the reward tokens.

Parameters:

• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _targets (address[]) the address on the destination chain at which the instruction sets need to be executed
• _data (bytes[]) the instructions to be executed on _targets
• _expiryTime (uint256) the timestamp at which the intent expires
• _nonce (bytes32) the nonce of the calldata. Composed of the hash on the source chain of the global nonce and chainID
• _claimant (address) the address that can claim the fulfilled intent's fee on the source chain
• _expectedHash (bytes32) the hash of the intent. Used to verify that the correct data is being input
• _prover (address) the address of the hyperProver on the source chain

Security: This method inherits all of the security features in fulfillstorage. This method is also payable, as funds are required to use the hyperlane bridge.

fulfillHyperInstantWithRelayer

Performs the same functionality as fulfillHyperInstant, but allows the user to use a custom HyperLane relayer and pass in the corresponding metadata

Parameters:

• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _targets (address[]) the address on the destination chain at which the instruction sets need to be executed
• _data (bytes[]) the instructions to be executed on _targets
• _expiryTime (uint256) the timestamp at which the intent expires
• _nonce (bytes32) the nonce of the calldata. Composed of the hash on the source chain of the global nonce and chainID
• _claimant (address) the address that can claim the fulfilled intent's fee on the source chain
• _expectedHash (bytes32) the hash of the intent. Used to verify that the correct data is being input
• _prover (address) the address of the hyperProver on the source chain
• _metadata (bytes) Metadata for postDispatchHook (empty bytes if not applicable)
• _postDispatchHook (address) Address of postDispatchHook (zero address if not applicable)

Security: This method inherits all of the security features in fulfillstorage. This method is also payable, as funds are required to use the hyperlane bridge. Additionally, the user is charged with the responsibility of ensuring that the passed in metadata and relayer perform according to their expectations

fulfillHyperBatched

`

Allows a filler to fulfill an intent on its destination chain to be proven by the HyperProver specified in the intent. After fulfilling the intent, this method emits an event that indicates which intent was fulfilled. Fillers of hyperprover-destined intents will listen to these events and batch process them later on. The filler also gets to predetermine the address on the destination chain that will receive the reward tokens. Note: this method is currently not supported by Eco's solver services, but has been included for completeness. Work on services for this method is ongoing.

Parameters:

• _sourceChainID (uint256) the ID of the chain where the fulfilled intent originated
• _targets (address[]) the address on the destination chain at which the instruction sets need to be executed
• _data (bytes[]) the instructions to be executed on _targets
• _expiryTime (uint256) the timestamp at which the intent expires
• _nonce (bytes32) the nonce of the calldata. Composed of the hash on the source chain of the global nonce and chainID
• _claimant (address) the address that can claim the fulfilled intent's fee on the source chain
• _expectedHash (bytes32) the hash of the intent. Used to verify that the correct data is being input
• _prover (address) the address of the hyperProver on the source chain

Security: This method inherits all of the security features in fulfillstorage.

sendBatch

Allows a filler to send a batch of HyperProver-destined intents over the HyperLane bridge. This reduces the cost per intent proven, as intents that would have had to be sent in separate messages are now consolidated into one.

Parameters:

• _sourceChainID (uint256) the chainID of the source chain
• _prover (address) the address of the hyperprover on the source chain
• _intentHashes (bytes32[]) the hashes of the intents to be proven

Security: This method ensures that all passed-in hashes correspond to intents that have been fulfilled according to the inbox. It contains a low-level call to send native tokens, but will only do this in the event that the call to this method has a nonzero msg.value. The method is payable because the HyperLane relayer requires fees in native token in order to function.

sendBatchWithRelayer

Performs the same functionality as sendBatch, but allows the user to use a custom HyperLane relayer and pass in the corresponding metadata.

Parameters:

• _sourceChainID (uint256) the chainID of the source chain
• _prover (address) the address of the hyperprover on the source chain
• _intentHashes (bytes32[]) the hashes of the intents to be proven
• _metadata (bytes) Metadata for postDispatchHook (empty bytes if not applicable)
• _postDispatchHook (address) Address of postDispatchHook (zero address if not applicable)

Security: This method inherits all of the security features in sendBatch. Additionally, the user is charged with the responsibility of ensuring that the passed in metadata and relayer perform according to their expectations.

fetchFee

A passthrough method that calls the HyperLane Mailbox and fetches the cost of sending a given message. This method is used inside both the fulfillHyperInstant and sendBatch methods to ensure that the user has enough gas to send the message over HyperLane's bridge.

Parameters:

• _sourceChainID (uint256) the chainID of the source chain
• _messageBody (bytes) the message body being sent over the bridge
• _prover (address) the address of the hyperprover on the source chain

Security: This method inherits all of the security features in fulfillstorage. This method is also payable, as funds are required to use the hyperlane bridge.

setMailbox

Sets the HyperLane Mailbox address to be used for all HyperProving fulfills.

Parameters:

• _mailbox (address) the address of the mailbox.

Security: This method can only be called by the owner of the Inbox, and can only be called if the current mailbox address is the zero address. It is intended to be called at time of construction.

makeSolvingPublic

Opens up solving functionality to all addresses if it is currently restricted to a whitelist.

Security: This method can only be called by the owner of the Inbox, and can only be called if solving is not currently public. There is no function to re-restrict solving - once it is public it cannot become private again.

changeSolverWhitelist

Changes the solving permissions for a given address.

Parameters:

• _solver (address) the address of the solver whose permissions are being changed
• _canSolve(bool) whether or not _solver will be able to solve after this method is called

Security: This method can only be called by the owner of the Inbox. This method has no tangible effect if isSolvingPublic is true.

drain

Transfers excess gas token out of the contract.

Parameters:

• _destination (address) the destination of the transferred funds

Security: This method can only be called by the owner of the Inbox. This method is primarily for testing purposes.

HyperProver (HyperProver.sol)

A message-based implementation of BaseProver that consumes data coming from HyperLane's message bridge sent by the Inbox on the destination chain. intentHash - claimant address pairs sent across the chain are written to the HyperProver's provenIntents mapping and are later read by the IntentSource when reward withdrawals are attempted.

Events

IntentProven

emitted when an intent has been successfully proven

Parameters:

• _hash (bytes32) the hash of the intent
• _claimant (address) the address that can claim this intent's rewards

IntentAlreadyProven

emitted when an attempt is made to re-prove an already-proven intent

Parameters:

• _hash (bytes32) the hash of the intent

Methods

handle

Called by the HyperLane Mailbox contract to finish the HyperProving process. This method parses the message sent via HyperLane into intent hashes and their corresponding claimant addresses, then writes them to the provenIntents mapping so that the IntentSource can read from them when a reward withdrawal is attempted.

Parameters:

• (uint32) this variable is not used, but is required by the interface. it is the chain ID of the intent's origin chain.
• _sender (bytes32) the address that called dispatch() on the HyperLane Mailbox on the destination chain
• _messageBody (bytes) the message body containing intent hashes and their corresponding claimants

Security: This method is public but there are checks in place to ensure that it reverts unless msg.sender is the local hyperlane mailbox and _sender is the destination chain's inbox. This method has direct write access to the provenIntents mapping and, therefore, gates access to the rewards for hyperproven intents.

Storage Prover (Prover.sol)

A storage-based implementation of BaseProver that utilizes the digests posted between rollups and mainnet to verify fulfilled status of intents on the destination chain.

Events

L1WorldStateProven

emitted when L1 world state is proven

Parameters:

• _blocknumber (uint256) the block number corresponding to this L1 world state
• _L1WorldStateRoot (bytes32) the world state root at _blockNumber

L2WorldStateProven

emitted when L2 world state is proven

Parameters:

• _destinationChainID (uint256) the chainID of the destination chain
• _blocknumber (uint256) the block number corresponding to this L2 world state
• _L2WorldStateRoot (bytes32) the world state root at _blockNumber

IntentProven

emitted when an intent has been successfully proven

Parameters:

• _hash (bytes32) the hash of the intent
• _claimant (address) the address that can claim this intent's rewards

Methods

proveSettlementLayerState

validates input L1 block state against the L1 oracle contract. This method does not need to be called per intent, but the L2 batch containing the intent must have been settled to L1 on or before this block.

Parameters:

• rlpEncodedBlockData (bytes) properly encoded L1 block data

Security: This method can be called by anyone. Inputting the correct block's data encoded as expected will result in its hash matching the blockhash found on the L1 oracle contract. This means that the world state root found in that block corresponds to the block on the oracle contract, and that it represents a valid state. Notably, only one block's data is present on the oracle contract at a time, so the input data must match that block specifically, or the method will revert.

proveWorldStateBedrock

Validates World state by ensuring that the passed in world state root corresponds to value in the L2 output oracle on the Settlement Layer. We submit a `StorageProof` proving that the L2 Block is included in a batch that has been settled to L1 and an `AccountProof` proving that the `StorageProof` submitted is linked to a `WorldState` for the contract that the `StorageProof` is for.

For Optimisms BedRock release we submit an outputRoot storage proof created by concatenating

output_root = kecakk256( version_byte || state_root || withdrawal_storage_root || latest_block_hash)

ERC-7683

Eco Protocol also allows the creation and solving of intents via the ERC-7683 interface.

Eco7683OriginSettler

An implementation of the ERC-7683 OriginSettler designed to work with Eco protocol. This contract is where intents are created and funded. Reward withdrawal has not yet been implemented within Eco's ERC7683 implementation, but it can be accomplished via the IntentSource contract.

Events

Open

Signals that an order has been opened

Parameters:

• orderId (bytes32) a unique order identifier within this settlement system
• resolvedOrder (ResolvedCrossChainOrder) resolved order that would be returned by resolve if called instead of Open

Methods

open

Opens an Eco intent directly on chain

Parameters:

• _order (OnchainCrossChainOrder) the onchain order containing all relevant intent data. The orderData of the order is of type OnchainCrosschainOrderData.

Security: This method will fail if the orderDataType does not match the typehash of OnchainCrosschainOrderData. This method is payable to account for users who wish to create intents that reward solvers with native tokens. A user should have approved the Eco7683OriginSettler to transfer reward tokens. This method will also fail if a user attempts to use it to open an intent that has already been funded.

openFor

Opens an Eco intent on behalf of a user

Parameters:

• _order (GaslessCrossChainOrder) the gasless order containing all relevant intent data. The orderData of the order is of type GaslessCrosschainOrderData.
• _signature (bytes32) the intent user's signature over _order _ _originFillerData (bytes) filler data for the origin chain (this is vestigial, not used and included only to maintain compatibility)

Security: This method will fail if the orderDataType does not match the typehash of GaslessCrosschainOrderData. This method is made payable in the event that the caller of this method (a solver) is opening an intent that has native token as a reward. How that solver receives the native token from the user is not within the scope of this method. This method also demands that the intent is funded in its entirety and will fail if the requisite funds have not been approved by the user. Lastly, this method will fail if the same intent has already been funded.

resolve

resolves an OnchainCrossChainOrder to a ResolvedCrossChainOrder

Parameters:

• _order (OnchainCrossChainOrder) the OnchainCrossChainOrder to be resolved

resolveFor

resolves a GaslessCrossChainOrder to a ResolvedCrossChainOrder

Parameters:

• _order (OnchainCrossChainOrder) the GaslessCrossChainOrder to be resolved

Eco7683DestinationSettler

An implementation of the ERC-7683 DestinationSettler designed to work with Eco protocol. This is an abstract contract whose functionality is present on Eco's Inbox contract. This is where intent fulfillment lives within the ERC-7683 system.

Events

OrderFilled

Emitted when an intent is fulfilled via the Eco7683DestinationSettler using Hyperlane instant proving

Parameters:

• _orderId (bytes32) Hash of the fulfilled intent
• _solver (address) Address that fulfilled the intent

Methods

fill

Fills an order on the destination chain

Parameters:

• _orderId (bytes32) Unique identifier for the order being filled
• _originData (bytes) Data emitted on the origin chain to parameterize the fill, equivalent to the originData field from the fillInstruction of the ResolvedCrossChainOrder. An encoded Intent struct.
• _fillerData (bytes) Data provided by the filler to inform the fill or express their preferences. an encoding of the ProofType (enum), claimant (address), and optionally postDispatchHook (address) and metadata (bytes) in the event that the intent is to be proven against a HyperProver.

Security: This method fails if the intent's fillDeadline has passed. It also inherits all of the security features in fulfillStorage / fulfillHyperInstantWithRelayer.