Add ERC: Gateway Attributes for Message Control

ERCS/erc-7985.md

@@ -0,0 +1,130 @@
+---
+eip: 7985
+title: Gateway Attributes for Message Control
+description: Gateway attributes for cancellation, timeout, retry, dependencies, and delivery control in cross-chain messaging.
+author: Ernesto García (@ernestognw), Kalman Lajko (@LajkoKalman), Valera Grinenko (@0xValera)
+discussions-to: https://ethereum-magicians.org/t/new-erc-attributes-for-message-control-in-erc-7786-gateways/24734
+status: Draft
+type: Standards Track
+category: ERC
+created: 2024-07-04
+requires: 7786
+---
+
+## 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.
+
+[ERC-7786]: ./eip-7786.md
+
+## 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:
+
+1. **Cancellation**: Applications need to cancel pending messages due to changed conditions
+2. **Timeouts**: Automatic cancellation prevents indefinite pending states
+3. **Retry Logic**: Standardized failure handling improves reliability
+4. **Revert Behavior**: Consistent error semantics across gateways
+5. **Message Dependencies**: Ensuring correct ordering when messages must deliver in sequence
+6. **Gas Requirements**: Preventing delivery failures due to insufficient gas
+7. **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
+
+<!-- TODO: Discuss -->
+
+<!-- Maybe? -->
+<!-- - **Dependency Cycles**: Gateways should detect and reject circular dependencies in `dependsOn` arrays -->
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).