-
Notifications
You must be signed in to change notification settings - Fork 42
feat: incentivized cross domain message delivery #272
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
hamdiallam
wants to merge
1
commit into
l2tol2cdm-gasreceipt-only
Choose a base branch
from
incentivized_relays
base: l2tol2cdm-gasreceipt-only
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+182
−0
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,182 @@ | ||
# [Incentivized Relays MVP]: Design Doc | ||
|
||
| | | | ||
| ------------------ | -------------------------------------------------- | | ||
| Author | _Hamdi Allam_ | | ||
| Created at | _2025-04-21_ | | ||
| Initial Reviewers | _Reviewer Name 1, Reviewer Name 2_ | | ||
| Need Approval From | _Reviewer Name_ | | ||
| Status | _Draft / In Review / Implementing Actions / Final_ | | ||
|
||
## Purpose | ||
|
||
<!-- This section is also sometimes called “Motivations” or “Goals”. --> | ||
|
||
<!-- It is fine to remove this section from the final document, | ||
but understanding the purpose of the doc when writing is very helpful. --> | ||
|
||
We want to preserve a single transaction experience in the Superchain event when a transaction spawns asynchronous cross chain invocations. | ||
|
||
## Summary | ||
|
||
<!-- Most (if not all) documents should have a summary. | ||
While the length will likely be proportional to the length of the full document, | ||
the summary should be as succinct as possible. --> | ||
|
||
With an incentivation framework, we can ensure permissionless delivery of cross domain messages by any relayer. Very similar to solvers fulfilling cross chain [intents](https://www.erc7683.org/) that are retroactively paid by the settlement system. | ||
|
||
This settlement system is built outside of the core protocol contracts, with this iteration serving as a functional MVP to start from. Any cut scope significantly simplifies implementation and can be re-added as improvements in further versions. | ||
|
||
## Problem Statement + Context | ||
|
||
<!-- Describe the specific problem that the document is seeking to address as well | ||
as information needed to understand the problem and design space. | ||
If more information is needed on the costs of the problem, | ||
this is a good place to that information. --> | ||
|
||
In order to pay relayers for delivering cross chain messages, relayers need to reimburse themselves for gas used during delivery. Since cross domain messages can span many hops, i.e A->B->C or A->B->A, this settlement system must ensure all costs are paid by the same fee payer. Thus all callbacks and transitive messages are implicitly incentivized by the originating transaction. | ||
|
||
## Proposed Solution | ||
|
||
<!-- A high level overview of the proposed solution. | ||
When there are multiple alternatives there should be an explanation | ||
of why one solution was picked over other solutions. | ||
As a rule of thumb, including code snippets (except for defining an external API) | ||
is likely too low level. --> | ||
|
||
An initial invariant that works well in establishing the fee payer is the `tx.origin` of the originating transaction. This is the same invariant that holds for 4337 and 7702 sponsored transaction. | ||
|
||
The changes proposed in [#266](https://github.com/ethereum-optimism/design-docs/pull/266) & [#282](https://github.com/ethereum-optimism/design-docs/pull/282) provide the foundation for creating the first iteration of this settlement system -- without enshrinment in the core protocol contracts. The `RelayedMessageGasReceipt` includes contextual information on the gas consumed, and the propogated (`tx.origin`, `rootMessageHash`) upon nested cross domain messages that can be used to appropriately charge `tx.origin`. | ||
|
||
This settlement system is a permissionless CREATE2 deployment, `L2ToL2CrossDomainGasTank`, where tx senders can hold an ETH deposit, used to asynchronously pay relayers for delivered messages. | ||
|
||
```solidity | ||
contract L2ToL2CrossDomainGasTank { | ||
uint256 constant MAX_DEPOSIT = 0.01 ether; | ||
|
||
event Deposit(address depositor, uint256 amount); | ||
|
||
mapping(address => uint256) public balanceOf; | ||
|
||
function deposit() nonReentrant external payable { | ||
uint256 amount = msg.value; | ||
require(amount > 0); | ||
|
||
uint256 newBalance = balanceOf[msg.sender] + amount; | ||
require(newBalance < MAX_DEPOSIT); | ||
|
||
balanceOf[msg.sender] = newBalance; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it would be good to emit a deposit event |
||
emit Deposit(msg.sender, amount) | ||
} | ||
} | ||
``` | ||
|
||
We cap the deposits in order to cut scope in supporting withdrawals. This makes our first iteration super simple since as withdrawal support introduces a race between deposited funds and a relayer compensating themselves for message delivery. With a relatively low max deposit, we eliminate the risk of a large amount of stuck funds for a given account whilst the amount being sufficient enough to cover hundreds of sub-cent transactions. | ||
|
||
Relayers that deliver messages can compensate themselves by pushing through the `RelayedMessageGasReceipt` event, validated with Superchain interop. A tx sender with no deposit makes this feature a no-op as incentive exists. The user must either relay messages themselves or rely on a 3rdparty provider. | ||
|
||
```solidity | ||
contract L2ToL2CrossDomainGasTank { | ||
|
||
event Claimed(bytes32 msgHash, address relayer, uint256 amount); | ||
|
||
mapping(bytes32 => bool) claimed; | ||
|
||
function claim(Identifier calldata id, bytes calldata payload) nonReentrant external { | ||
require(id.origin == address(messenger)); | ||
ICrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(id, keccak256(payload)); | ||
|
||
// parse the receipt | ||
require(payload[:32] == RelayedMessageGasReceipt.selector); | ||
(bytes32 msgHash, bytes32 rootMsgHash, address relayer, address txOrigin, uint256 relayCost) = _decode(payload); | ||
|
||
// ensure the original outbound message was sent from this chain | ||
require(messenger.sentMessages[rootMsgHash]); | ||
|
||
// ensure unclaimed, and mark the claim | ||
require(!claimed[msgHash]); | ||
claimed[msgHash] = true | ||
|
||
// compute total cost (adding the overhead of this claim) | ||
uint256 claimCost = CLAIM_OVERHEAD * block.basefee; | ||
uint256 cost = relayCost + claimCost; | ||
require(balanceOf[txOrigin] >= cost); | ||
hamdiallam marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
// compensate the relayer (whatever is left if there is not enough) | ||
uint256 amount = SafeMath.min(balanceOf[txOrigin], cost) | ||
balanceOf[txOrigin] -= amount; | ||
|
||
new SafeSend{ value: amount }(payable(relayer)); | ||
|
||
emit Claimed(msgHash, relayer, cost) | ||
} | ||
} | ||
``` | ||
|
||
As relayers deliver messages, they can claim the cost against the original tx sender's deposit. This design introduces some off-chain complexity for the relayer. | ||
|
||
1. The relayer must simulate the call and ensure the emitted tx origin has a deposit that will cover the cost on the originating chain. | ||
2. The relayer should also track the pending claimable `RelayedMessageGasReceipt` of the `rootMsgHash` callstack to maximize the likelihood that the held deposit is sufficient. | ||
3. The relayer should claim the receipt within a reasonable time frame to ensure they are compensated. | ||
- An unrelated relayer not checking (2) might claim newer transitive message that depletes the funds. A version of the gas tank where claims are ordered would fix this. | ||
- There are restrictions for the max age of any event pulled in with interop -- applying to claim flow with `RelayedMessageGasReceipt` | ||
|
||
### Resource Usage | ||
|
||
<!-- What is the resource usage of the proposed solution? | ||
Does it consume a large amount of computational resources or time? --> | ||
|
||
As a CREATE2 deployment, this settlement framework does not affect the core protocol contracts. All contract operations are on fixed-sized fields bounding the gas consumption of this contract. | ||
|
||
### Single Point of Failure and Multi Client Considerations | ||
|
||
<!-- Details on how this change will impact multiple clients. Do we need to plan for changes to both op-geth and op-reth? --> | ||
|
||
No external contract calls are made during the deposit and claim pathways, with the `nonReentrant` modifier also applied to protect against re-entrancy attacks as ETH is transferred between the gas tank and the caller. | ||
|
||
## Failure Mode Analysis | ||
|
||
<!-- Link to the failure mode analysis document, created from the fma-template.md file. --> | ||
|
||
_pending_. | ||
|
||
Important to note that holding no deposit is makes this feature a no-op. Users leveraging 3rdparty relayers or different infrastructure can continue to do so without affect. The failure mode here is simply an unused gas tank. The `RelayedMessageGasReceipt` emmitted by the messenger can be ignored or consumed by a different party for their own purposes. | ||
|
||
## Impact on Developer Experience | ||
|
||
<!-- Does this proposed design change the way application developers interact with the protocol? | ||
Will any Superchain developer tools (like Supersim, templates, etc.) break as a result of this change? --> | ||
|
||
When sending a transaction that involves cross chain interactions, the frontend should simulate these interactions and ensure the gas tank has appropriate funds to pay. With `multicall`, a single transaction can bundle together the funding operation with the transaction if neededed. | ||
|
||
The infrastructure required for make cross chain tx simulation as simple as possible must also be taken into consideration. Since a cross chain tx requires a valid `CrossL2Inbox.Identifier`, there's already added complexity here in simulating side effects where dependencies have not yet been executed. However, frontends can liberally make deposits without full simulation as the settlement system only charges what was used. | ||
|
||
## Alternatives Considered | ||
|
||
<!-- List out a short summary of each possible solution that was considered. | ||
Comparing the effort of each solution --> | ||
|
||
1. Rely on 3rdparty Bridge/Relay providers. See the problem statement in [#266](https://github.com/ethereum-optimism/design-docs/pull/266). | ||
2. Offchain attribution. Schemes can be derived with web2-esque approaches such as API keys. With a special tx-submission endpoint, being able to tag cross chain messages with off-chain accounts to thus charge for gas used. This might a good fallback mechanism to have in place. | ||
|
||
### Permissioned Gas Tank | ||
|
||
We can create an intermediate version of the gas tank to build the entire flow end to end. The deployment of this gas tank is scoped to specific relayers which can unliterally charge depositors without needing a validated receipt. By having the same user-facing deposit api, we can get to a faster implementation to test any UX flows ahead of time. | ||
|
||
```solidity | ||
contract PermissionedL2ToL2CrossDomainGasTank { | ||
constructor(address[] relayers) {} | ||
|
||
function deposit() payable; | ||
function claim(address txSender, uint256 amount) onlyRelayers {} | ||
} | ||
``` | ||
|
||
## Risks & Uncertainties | ||
|
||
<!-- An overview of what could go wrong. | ||
Also any open questions that need more work to resolve. --> | ||
|
||
1. This incentive framework is insufficient and unused. This is not a problem as this settlement framework is not enshrined in the protocol and is a simple CREATE2 deployment. Entirely new frameworks can be derived to replace this, leaving this unused. | ||
|
||
2. Also important to note that holding no deposit is makes this feature a no-op. Users leveraging 3rdparty relayers or different infrastructure can continue to do so without affect. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What are your thoughts on having a second mapping keying balance by root message hash?
This could still enforce a
MAX_DEPOSIT
to mitigate risk of a large amount of stuck funds for a given account. The deposit flow would looks like this:Then in claim you would have to deduct cost from both balance mappings:
The main benefit of
messageBalanceOf
is that it removes complexity from the relayer around determining whetherL2ToL2CrossDomainGasTank
contains enough funds for the gas required to relay a message because relayer can check the balance per message hash instead of having to check for other pending messages that might be associated with that tx.origin. Another benefit, is down the line when we support withdrawals, we could add timeouts per message hash on withdrawals, which would guarantee that the balance for the message hash would exist up until a given block timestamp.However, a potential downside I see of the
messageBalanceOf
approach is that it would require a new deposit for every new root message hash. And a potential risk of this approach is that someone could assign a balance ofMAX_DEPOSIT
to a single message hash (or across multiple message hahes), that ends up not being relayable, and then that account ends up "stuck" and cannot fund any additional messages because the account balance cannot exceedMAX_DEPOSIT
. However, this risk becomes mitigated if we assumeL2ToL2CrossDomainGasTank
is not "production-ready" until there is withdrawal support.wdyt?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yea this is a great point! I was actually thinking of having support for this not in replacement but for 3rdparty integrator that wants a different fee payer than
tx.origin
.The reason it can't replace is that this requires native integration with someone using the L2ToL2CrossDomainMessenger. You'd have to wrap every
sendMessage
call with a call todeposit
. Instead of a replacement, this would be an additive API.One easy usecase. Lets say Layerzero wants to integrate this feature. Someone sends a message from Solana -> OPM that then spawns a bunch of operations. You dont want the LZ relayer from Sol->OPM to be the fee payer. However, the LZ DVN that integrates the L2ToL2CDM can use this api to specifically just push whatever gas was provided from the original tx as the deposit for the given root msg hash. Then everything just works. And if the provided gas wasn't enough, the person can top up the given root msg hash with more funds
Does this make sense?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
100% agree that this first version should actually include this, i'll add it today
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
when you say additive API, are you saying that the gas tank will support balance tracking and claiming by tx.origin and by msg hash?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
by default claiming by tx.origin unless the
rootMsgHash
has an explicit balance set.If the rootMsgHash has a balance set, i think it should not claim by tx.origin. Is there a scenario where you think it should fallback to tx.origin after depleting the funds associated with the msg hash?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, if we are going to support balances by tx.origin and by msgHash then we should fallback to tx.origin. Otherwise, a bad actor could potentially try to make it more difficult for a msg to relay by setting a very small balance to any msg hash they want to prevent from being relayed, and then the user would have to intervene and increase the balance on that msg hash in order to get it to relay.
The other option here is to just simplify things and only support msgHash balances. Even though it will always require an extra deposit, can't that be simplified by something like 7702?