ERC-7985 Gateway Message Control Properties (Gateway Attributes for Message Control)

Draft · Other · created 2024-07-04

Defines standard properties for ERC-7786 cross-chain message gateways, specifying cancellation, delivery time windows, retries, message ordering, and minimum gas.

Why it is needed

ERC-7786 defined an extensible property scheme for cross-chain message gateways but deferred standardization of concrete properties to a follow-up specification. As a result, each gateway has implemented its own way of canceling messages or giving them an expiry, retrying on failure, reporting failures, guaranteeing delivery order across multiple messages, and securing the gas needed for delivery. This forces applications that want the same functionality to write separate integration logic for each gateway, fragmenting the ecosystem into mutually incompatible implementations.

What to implement

In depth

cancellable(bool): message cancellation

Uses selector 0xde986d7f (the first 4 bytes of keccak256("cancellable(bool)")). The value is an ABI-encoded boolean, and if unspecified it may be treated as false. If set to true, the gateway must provide a mechanism for the application to cancel a pending message when conditions change or requirements shift.

deliverBefore/deliverAfter: delivery time window

deliverBefore(uint256) uses selector 0x3e97d7ee and the message cannot be delivered after the specified Unix timestamp. A value of 0 means no expiration. deliverAfter(uint256) uses selector 0x745910eb and the message cannot be delivered before the specified timestamp. A value of 0 means no delay. Using both attributes together creates a deliverable time window. If neither value is specified, both may be treated as 0.

retryPolicy(bytes): retry policy

Uses selector 0xf002c055 and is encoded as abi.encodePacked(uint16 maxRetries, uint32 retryDelay, uint32 backoffMultiplier). maxRetries is the maximum number of retries (0 means no retries), retryDelay is the initial delay between retries in seconds, and backoffMultiplier is the exponential backoff multiplier in basis points (10000 equals 1x). If no value is specified, it is treated as 0x, which means infinite retries, no delay, and no backoff (or equivalently maxRetries=0, retryDelay=0, backoffMultiplier=0).

revertBehavior(uint8): failure handling method

Uses selector 0x9e521a77 and the value is an ABI-encoded uint8. 0 (Revert on Failure) means the entire message send must revert on failure and SHOULD propagate the original failure reason. 1 (Emit-and-Continue) means it must emit a MessageFailed(bytes32 sendId, string reason) event on failure and continue sending subsequent messages or operations. 2 (Silent Failure) means it must neither revert the transaction nor emit any failure-related event. If no value is specified, the default is 0.

dependsOn(bytes32[]): message dependencies

Uses selector 0xa9fed7b9 and the value is specified as an ABI-encoded array of message identifiers. The gateway must not send the message until all messages specified in the dependsOn array have been sent successfully. If unspecified or an empty array, there are no dependencies, and this mechanism ensures the ordering of multiple messages is not disrupted.

minGasLimit(uint256): minimum gas requirement

Uses selector 0x39f87ba1 and specifies the minimum gas units required for the send as an ABI-encoded uint256. The gateway must verify that at least this much gas is available before attempting to send the message. If unspecified, the gateway may use its own default gas allocation strategy.

Implementation and validation rules

Gateways do not need to implement all of these attributes and may choose to implement them independently. However, for any attribute they do implement, they must validate the encoding and must revert the transaction if the encoding is invalid. Because ERC-7786's base specification requires unknown attributes to be handled safely, gateways that do not support this standard still function normally.

A proposal still under discussion

This document is in Draft status, meaning it is a proposal still undergoing community discussion and revision. The Security Considerations section has not yet been filled in, and items such as cyclic dependency detection for dependsOn are only mentioned in comments, so these may change in the future.

Original ERC · ← ERCs