ERC-7985: Gateway Attributes for Message Control
Gateway attributes for cancellation, timeout, retry, dependencies, and delivery control in cross-chain messaging.
| Authors | Ernesto García (@ernestognw), Kalman Lajko (@LajkoKalman), Valera Grinenko (@0xValera) |
|---|---|
| Created | 2024-07-04 |
| Discussion Link | https://ethereum-magicians.org/t/new-erc-attributes-for-message-control-in-erc-7786-gateways/24734 |
| Requires | EIP-7786 |
Table of Contents
Abstract
This ERC defines standard attributes for ERC-7786 cross-chain messaging gateways to enable consistent cancellation, timeout, retry, dependency, and delivery control mechanisms across implementations. These attributes provide applications with predictable control over message lifecycle, ordering, and delivery requirements.
Motivation
ERC-7786 introduces an extensible attribute system for cross-chain messaging, but leaves attribute standardization to follow-up specifications. As cross-chain applications mature, consistent patterns for message control have emerged as essential requirements:
- Cancellation: Applications need to cancel pending messages due to changed conditions
- Timeouts: Automatic cancellation prevents indefinite pending states
- Retry Logic: Standardized failure handling improves reliability
- Revert Behavior: Consistent error semantics across gateways
- Message Dependencies: Ensuring correct ordering when messages must deliver in sequence
- Gas Requirements: Preventing delivery failures due to insufficient gas
- Delivery Timing: Controlling when messages can be delivered for scheduling and coordination
Without standardized attributes, each gateway implements these features differently, fragmenting the ecosystem and requiring application-specific integration logic.
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.
Standard Attributes
This specification defines standard attributes for ERC-7786 cross-chain messaging gateways. The word “delivery” (or “deliver”) is used to refer to the process of delivering a message to the destination chain, similar to its usage in ERC-7786.
Gateways MAY implement attributes independently. Gateways MUST validate the attribute’s encoding for each attribute they implement and revert the transaction if the encoding is invalid.
cancellable(bool)
Indicates whether a message can be cancelled after submission. This attribute uses selector 0xde986d7f, which represents the first 4 bytes of keccak256("cancellable(bool)").
The attribute value is encoded as an ABI-encoded boolean, and MAY default to false when not specified. When set to true, gateways MUST provide a cancellation mechanism to allow applications to cancel pending messages due to changed conditions or requirements.
deliverBefore(uint256)
Specifies a timestamp after which the message cannot be delivered. This attribute uses selector 0x3e97d7ee, derived from the first 4 bytes of keccak256("deliverBefore(uint256)").
The value is encoded as an ABI-encoded Unix timestamp, and MAY default to 0 when not specified. Gateways MUST NOT deliver messages after the expiration timestamp unless 0 is specified, which MUST be interpreted as no expiration.
deliverAfter(uint256)
Specifies the earliest timestamp at which the message can be delivered. This attribute uses selector 0x745910eb, derived from the first 4 bytes of keccak256("deliverAfter(uint256)").
The value is encoded as an ABI-encoded Unix timestamp, and MAY default to 0 when not specified. Gateways MUST NOT deliver messages before the delivery timestamp unless 0 is specified, which MUST be interpreted as no delay. When combined with deliverBefore(uint256), this creates a delivery time window.
retryPolicy(bytes)
Defines retry behavior for failed message delivery. Using selector 0xf002c055 from the first 4 bytes of keccak256("retryPolicy(bytes)"), this attribute encodes retry parameters as ABI-encoded bytes.
The format follows abi.encodePacked(uint16(maxRetries), uint32(retryDelay), uint32(backoffMultiplier)), where maxRetries specifies the maximum number of retry attempts (with 0 indicating no retries), retryDelay defines the initial delay between retries in seconds, and backoffMultiplier provides the multiplier for exponential backoff in basis points (with 10000 representing 1x multiplier).
The attribute value MAY default to 0x when not specified, equivalent to infinite retries, no delay, and no backoff (or maxRetries = 0, retryDelay = 0, and backoffMultiplier = 0).
revertBehavior(uint8)
Specifies how delivery failures MUST be handled. This attribute uses selector 0x9e521a77, representing the first 4 bytes of keccak256("revertBehavior(uint8)").
The value is encoded as an ABI-encoded uint8 with the following possible values:
0 – Revert on Failure
- Gateways MUST revert the entire message delivery when any failure occurs.
- Gateways SHOULD propagate the original failure reason when reverting.
1 – Emit-and-Continue
- Gateways MUST emit a
MessageFailed(bytes32 sendId, string reason)event upon failure. - Gateways MUST continue delivery of subsequent messages or operations.
2 – Silent Failure
- Gateways MUST NOT revert the transaction
- Gateways MUST NOT emit any failure-related events.
When not specified, the attribute MUST default to 0.
dependsOn(bytes32[])
Specifies message dependencies that must be delivered before this message. This attribute uses selector 0xa9fed7b9, derived from the first 4 bytes of keccak256("dependsOn(bytes32[])").
The value is encoded as an ABI-encoded array of message identifiers. Gateways MUST NOT deliver a message until all messages specified in the dependsOn array have been successfully delivered. When not specified or empty, the message has no dependencies. This ensures correct ordering and prevents out-of-order delivery issues.
minGasLimit(uint256)
Specifies the minimum gas limit required for message delivery. This attribute uses selector 0x39f87ba1, derived from the first 4 bytes of keccak256("minGasLimit(uint256)").
The value is encoded as an ABI-encoded uint256 representing the minimum gas units required. Gateways MUST ensure at least this amount of gas is available before attempting message delivery. When not specified, gateways MAY use their default gas allocation strategies.
Rationale
These attributes address the most common cross-chain message control requirements:
- Lifecycle control via cancellation and timeout mechanisms
- Delivery timing through delivery time windows
- Failure handling via retry policies and revert behavior
- Message ordering through dependency chains
- Delivery guarantees via minimum gas requirements
The byte-encoded retry policy allows for extensible parameters without requiring additional attributes. The dependency mechanism enables complex multi-message workflows while maintaining simplicity for single-message scenarios.
Backwards Compatibility
This specification extends ERC-7786 without breaking changes. Gateways not supporting these attributes will operate normally per the base specification’s requirement to handle unknown attributes gracefully.
Security Considerations
Copyright
Copyright and related rights waived via CC0.
Citation
Please cite this document as:
Ernesto García (@ernestognw), Kalman Lajko (@LajkoKalman), Valera Grinenko (@0xValera), "ERC-7985: Gateway Attributes for Message Control [DRAFT]," Ethereum Improvement Proposals, no. 7985, July 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7985.