The following standard allows for the implementation of a standard API for cross-chain value-transfer systems. This standard provides generic order structs, as well as a standard set of settlement smart contract interfaces.
Motivation
Intent-based systems have become the preeminent solution for end-user cross-chain interaction by abstracting away the complexity and time constraints of traditional bridges. One of the key difficulties for cross-chain intents systems is accessing sufficient liquidity and a network of active fillers across chains. This challenge may be exacerbated as the number of distinct chains increases over time. The end result of this is a poor experience for users including higher costs, longer wait times and higher failure rates than necessary.
By implementing a standard, cross-chain intents systems can interoperate and share infrastructure such as order dissemination services and filler networks, thereby improving end-user experience by increasing competition for fulfilling user intents.
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
Glossary of Terms
Destination Chain: the chain where the intent is executed and the user receives funds. Note: intents can involve multiple destination chains.
Filler: a participant who fulfils a user intent on the destination chain(s) and receives payment as a reward.
Leg: a portion of the user intent that can be executed independently from others. All legs must be executed for an intent to be considered fulfilled.
Origin chain: the chain where the user sends funds.
Settlement System: a system that custodies user deposits, verifies fills, and pays fillers for the purpose of faciliating intents.
Settler: a contract that implements part of the settlement system on a particular chain.
User: for the purposes of this document, the user is the end-user who is sending the order.
Order structs
A compliant cross-chain order type MUST be ABI decodable into either GaslessCrossChainOrder or OnchainCrossChainOrder type.
/// @title GaslessCrossChainOrder CrossChainOrder type
/// @notice Standard order struct to be signed by users, disseminated to fillers, and submitted to origin settler contracts
structGaslessCrossChainOrder{/// @dev The contract address that the order is meant to be settled by.
/// Fillers send this order to this contract address on the origin chain
addressoriginSettler;/// @dev The address of the user who is initiating the swap,
/// whose input tokens will be taken and escrowed
addressuser;/// @dev Nonce to be used as replay protection for the order
uint256nonce;/// @dev The chainId of the origin chain
uint256originChainId;/// @dev The timestamp by which the order must be opened
uint32openDeadline;/// @dev The timestamp by which the order must be filled on the destination chain
uint32fillDeadline;/// @dev Type identifier for the order data. This is an EIP-712 typehash.
bytes32orderDataType;/// @dev Arbitrary implementation-specific data
/// Can be used to define tokens, amounts, destination chains, fees, settlement parameters,
/// or any other order-type specific information
bytesorderData;}/// @title OnchainCrossChainOrder CrossChainOrder type
/// @notice Standard order struct for user-opened orders, where the user is the msg.sender.
structOnchainCrossChainOrder{/// @dev The timestamp by which the order must be filled on the destination chain
uint32fillDeadline;/// @dev Type identifier for the order data. This is an EIP-712 typehash.
bytes32orderDataType;/// @dev Arbitrary implementation-specific data
/// Can be used to define tokens, amounts, destination chains, fees, settlement parameters,
/// or any other order-type specific information
bytesorderData;}
Cross-chain execution systems implementing this standard SHOULD use a sub-type that can be parsed from the arbitrary orderData field. This may include information such as the tokens involved in the transfer, the destination chain IDs, fulfillment constraints or settlement oracles.
All sub-types SHOULD be registered in a subtypes repository to encourage sharing of sub-types based on their functionality. See the examples section for an example of how sub-types can be used to support behavior like executing calldata on a target contract of the user’s choice on the destination chain.
ResolvedCrossChainOrder struct
A compliant cross-chain order type MUST be convertible into the ResolvedCrossChainOrder struct. This means that the orderData must be decoded into the information needed to populate the ResolvedCrossChainOrder struct. Additionally, orderData SHOULD be decodable into a sub-type, which can be used for further functionality such as cross-chain calldata execution (see the examples section for an example of this). It is the responsibility of the user and the filler to ensure that the originSettler supports their order’s contained sub-type.
/// @title ResolvedCrossChainOrder type
/// @notice An implementation-generic representation of an order intended for filler consumption
/// @dev Defines all requirements for filling an order by unbundling the implementation-specific orderData.
/// @dev Intended to improve integration generalization by allowing fillers to compute the exact input and output information of any order
structResolvedCrossChainOrder{/// @dev The address of the user who is initiating the transfer
addressuser;/// @dev The chainId of the origin chain
uint256originChainId;/// @dev The timestamp by which the order must be opened
uint32openDeadline;/// @dev The timestamp by which the order must be filled on the destination chain(s)
uint32fillDeadline;/// @dev The unique identifier for this order within this settlement system
bytes32orderId;/// @dev The max outputs that the filler will send. It's possible the actual amount depends on the state of the destination
/// chain (destination dutch auction, for instance), so these outputs should be considered a cap on filler liabilities.
Output[]maxSpent;/// @dev The minimum outputs that must to be given to the filler as part of order settlement. Similar to maxSpent, it's possible
/// that special order types may not be able to guarantee the exact amount at open time, so this should be considered
/// a floor on filler receipts.
Output[]minReceived;/// @dev Each instruction in this array is parameterizes a single leg of the fill. This provides the filler with the information
/// necessary to perform the fill on the destination(s).
FillInstruction[]fillInstructions;}/// @notice Tokens that must be receive for a valid order fulfillment
structOutput{/// @dev The address of the ERC20 token on the destination chain
/// @dev address(0) used as a sentinel for the native token
bytes32token;/// @dev The amount of the token to be sent
uint256amount;/// @dev The address to receive the output tokens
bytes32recipient;/// @dev The destination chain for this output
uint256chainId;}/// @title FillInstruction type
/// @notice Instructions to parameterize each leg of the fill
/// @dev Provides all the origin-generated information required to produce a valid fill leg
structFillInstruction{/// @dev The contract address that the order is meant to be settled by
uint64destinationChainId;/// @dev The contract address that the order is meant to be filled on
bytes32destinationSettler;/// @dev The data generated on the origin chain needed by the destinationSettler to process the fill
bytesoriginData;}
Open event
A compliant Open event MUST adhere to the following abi:
/// @notice Signals that an order has been opened
/// @param orderId a unique order identifier within this settlement system
/// @param resolvedOrder resolved order that would be returned by resolve if called instead of Open
eventOpen(bytes32indexedorderId,ResolvedCrossChainOrderresolvedOrder);
Settlement interfaces
A compliant origin settler contract implementation MUST implement the IOriginSettler interface:
/// @title IOriginSettler
/// @notice Standard interface for settlement contracts on the origin chain
interfaceIOriginSettler{/// @notice Opens a gasless cross-chain order on behalf of a user.
/// @dev To be called by the filler.
/// @dev This method must emit the Open event
/// @param order The GaslessCrossChainOrder definition
/// @param signature The user's signature over the order
/// @param originFillerData Any filler-defined data required by the settler
functionopenFor(GaslessCrossChainOrdercalldataorder,bytescalldatasignature,bytescalldataoriginFillerData)external;/// @notice Opens a cross-chain order
/// @dev To be called by the user
/// @dev This method must emit the Open event
/// @param order The OnchainCrossChainOrder definition
functionopen(OnchainCrossChainOrdercalldataorder)external;/// @notice Resolves a specific GaslessCrossChainOrder into a generic ResolvedCrossChainOrder
/// @dev Intended to improve standardized integration of various order types and settlement contracts
/// @param order The GaslessCrossChainOrder definition
/// @param originFillerData Any filler-defined data required by the settler
/// @return ResolvedCrossChainOrder hydrated order data including the inputs and outputs of the order
functionresolveFor(GaslessCrossChainOrdercalldataorder,bytescalldataoriginFillerData)externalviewreturns(ResolvedCrossChainOrdermemory);/// @notice Resolves a specific OnchainCrossChainOrder into a generic ResolvedCrossChainOrder
/// @dev Intended to improve standardized integration of various order types and settlement contracts
/// @param order The OnchainCrossChainOrder definition
/// @return ResolvedCrossChainOrder hydrated order data including the inputs and outputs of the order
functionresolve(OnchainCrossChainOrdercalldataorder)externalviewreturns(ResolvedCrossChainOrdermemory);}
A compliant destination settlement contract implementation MUST implement the IDestinationSettler interface:
/// @title IDestinationSettler
/// @notice Standard interface for settlement contracts on the destination chain
interfaceIDestinationSettler{/// @notice Fills a single leg of a particular order on the destination chain
/// @param orderId Unique order identifier for this order
/// @param originData Data emitted on the origin to parameterize the fill
/// @param fillerData Data provided by the filler to inform the fill or express their preferences
functionfill(bytes32orderId,bytescalldataoriginData,bytescalldatafillerData)external;}
fillerData
Cross-chain execution systems implementing this standard SHOULD use a sub-type that can be parsed from the arbitrary fillerData field. This may include information such as the desired timing or form of payment for the filler
All sub-types SHOULD be registered in a subtypes repository to encourage sharing of sub-types based on their functionality.
Rationale
Generic OrderData
A key consideration is to ensure that a broad range of cross-chain intent designs can work within the same standard. To enable this, the specification is designed around a cross-chain intents flow, with two variations: gasless and onchain.
Gasless cross-chain intents flow
Origin Chain:
The user signs an off-chain message defining the parameters of their order
The order is disseminated to fillers
The filler calls resolve to unpack the order’s requirements
The filler opens the order on the origin chain
Destination Chain(s):
The filler fills each leg of the order on the destination chain(s)
Settlement:
A cross-chain settlement process takes place to settle the order
Onchain cross-chain intents flow
Origin Chain:
The caller signs a transaction calling open with their order
The filler retrieves the emitted event to determine requirements
Destination Chain(s):
The filler fills each leg of the order on the destination chain(s)
Settlement:
A cross-chain settlement process takes place to settle the order
Customization
Within this flow, implementers of the standard have design flexibility to customize behavior such as:
Price resolution, e.g. dutch auctions (on origin or destination) or oracle-based pricing
Fulfillment constraints
Settlement procedures
Ordering of the origin and destination chain actions, e.g. the fill could happen before open in some settlement systems
The orderData field allows implementations to take arbitrary specifications for these behaviors while still enabling integrators to parse the primary fields of the order.
This functionality also motivated the resolve view function and ResolvedCrossChainOrder type. Resolution enables integrating fillers to validate and assess orders without specific knowledge of the orderData field at hand.
Emission of Fill Instructions
An important component of the standard is creating a flexible and robust mechanism for fillers to ensure their fills are valid. For a fill to be valid,
it typically must satisfy the following constraints:
It must be filled on the correct destination chain(s)
It must be filled on the correct destination contract
It must include some (not necessarily all) information from the order that the user provided on the origin chain
It may require some execution information from the open call on the origin chain (ex. dutch auctions based on open timing)
The FillInstruction array in ResolvedCrossChainOrder is intended to ensure it’s simple for the filler to meet all of these requirements by either
listening for the Open or by calling resolve.
One may notice that the originData field within FillInstruction is completely opaque. This opaqueness allows the settler implementations to
freely customize the data they transmit. Because fillers do not need to interpret this information, the opaqueness does not result in any
additional implementation costs on fillers.
This functionality also makes it feasible for a user, filler, or order distribution system to perform an end-to-end simulation of the order initiation
and fill to evaluate all resulting state transitions without understanding the nuances of a particular execution system.
Cross-compatibility
Since this standard is intended to reduce friction for users moving value across chains, non-EVM ecosystems should not be excluded. However, attempting
to pull each non-EVM ecosystem in would dramatically increase the size and complexity of this standard, while ommitting any that come in the future.
Instead, this standard is intended to be cross-compatible with other ecosystems. It standardizes interfaces and data types on EVM chains, but allows
for the creation of sibling standards that define compatible interfaces, data types, and flows within other ecosystems. Intents created within these
sibling standards should be able to be filled on an EVM chain and vice versa.
To ensure this cross-compatibility, all foreign addresses use bytes32 rather than address to allow for larger address identifiers.
Usage of Permit2
Permit2 is not specifically required by this standard, but does provide an efficient and straightforward approach to building standard-adherent protocols. Specifically, the witness functions of permit2 allow users to both approve the token transfer and the order itself with a single signature. This also nicely couples the transfer of tokens with a successful initiation of the order.
In contrast, a standard approval model would require two separate signatures - a token approval (either ERC-2612 or on-chain) and a signature to approve the terms of the order. It also decouples the token approval from the order, meaning approved tokens could potentially be taken at any time due to a buggy or untrusted settler contract.
When building a standard-compliant settler system around Permit2, the following considerations should be made
nonce in the order struct should be a permit2 nonce
openDeadline in the order struct should be the permit2 deadline
A full order struct including the parsed orderData should be used as the witness type during the permit2 call. This ensures maximum transparency to the user as they sign their order permit.
Examples
This is an example of how a 7683 cross-chain value transfer order can include instructions to the filler to execute arbitrary calldata on behalf of the recipient on the destination chain. This calldata execution is performed by the settlement contract atomically within the filler’s fill() execution, so the arbitrary contract execution can take advantage of the destination chain recipient’s newly transferred value. A hypothetical user in this example would select a originSettler that is known to support the Message sub-type.
Let there be a sub-type called Message, which is defined by the following structs:
// The Message subtype allows ERC7683 intents to carry calldata that is executed on a target contract on the destination chain. The settlement contract that the filler interacts with on the destination chain will decode the message into smart contract calls and execute the calls within the filler's `fill()` transaction.
// The Message contains calls that the user wants executed on the destination chain.
// The target is a contract on the destination chain that the settlement contract will attempt to send callData and value to.
structCalls{addresstarget;bytescallData;uint256value;}structMessage{Calls[]calls;}
The Message sub-type is designed to be used by a 7683 user to incentivize a filler to to execute arbitrary calldata on a target destination chain contracton the user’s behalf. For example, the settlement contract might decode the orderData containing the message information as follows:
functionfill(bytes32orderId,bytescalldataoriginData,bytescalldatafillerData)public{(addressuser,uint32fillDeadline,OutputmemoryfillerOutput,Messagememorymessage)=abi.decode(originData);// ...Do some preprocessing on the parameters here to validate the order...
// ...Execute the fill logic of the ResolvedCrossChainOrder...
// Handle the Message subtype:
// Revert if any of the message calls fail.
uint256length=message.calls.length;for(uint256i=0;i<length;++i){Callmemorycall=message.calls[i];// If we are calling an EOA with calldata, assume target was incorrectly specified and revert.
if(call.callData.length>0&&call.target.code.length==0){revertInvalidCall(i,calls);}(boolsuccess,)=call.target.call{value:call.value}(call.callData);if(!success)revertCallReverted(i,message.calls);}}
In this example, the Message sub-type allows the user to delegate destination chain contract execution to fillers. However, because transactions are executed via filler, the msg.sender would be the DestinationSettler, making this Message sub-type limited if the target contract authenticates based on the msg.sender. Ideally, 7683 orders containing Messages can be combined with smart contract wallets like implementations of ERC-4337 or EIP-7702 to allow complete cross-chain delegated execution.
Security Considerations
Evaluating settlement contract security
This ERC is agnostic of how the settlement system validates a 7683 order fulfillment and refunds the filler. In fact, this ERC is designed to delegate the responsibility of evaluating the settlement contract’s security to the filler and the application that creates the user’s 7683 order.
This design decision is motivated by the existence of many viable cross-chain messaging systems today offering settlement contracts a variety of tradeoffs. We hope that this standard can eventually support an ERC dedicated to standardizing a safe, trustless, cross-chain verification system.
Mark Toda (@marktoda), Matt Rice (@mrice32), Nick Pai (@nicholaspai), "ERC-7683: Cross Chain Intents [DRAFT]," Ethereum Improvement Proposals, no. 7683, April 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7683.