Add EIP: Flow Control Wallet Call Capability by SamWilsn · Pull Request #9259 · ethereum/EIPs

SamWilsn · 2025-01-22T19:10:39Z

No description provided.

eth-bot · 2025-01-22T19:11:04Z

✅ All reviewers have approved.

Marchhill

A few nitpicks

Marchhill · 2025-01-23T11:24:40Z

+
+#### Rollback
+
+A rollback is informally defined as "causing no meaningful changes on chain." A


Is there any reason to break up lines like this? A paragraph could be on one line and use line wrapping, not sure what the standard is here

I like a narrow line width, but we accept both wrapped and unwrapped lines.

Marchhill · 2025-01-23T11:40:47Z

+| `207`  | Partial Success       |
+
+An "included" call, in this section, is defined as having either been
+successfully or unsuccessfully executed. A call that has been recorded on chain,


Suggested change

successfully or unsuccessfully executed. A call that has been recorded on chain,

executed, even if execution was unsuccessful. A call that has been recorded on chain,

Marchhill · 2025-01-23T11:41:43Z

+
+Status `102` SHALL be returned only when all of the following are true:
+
+ * At least one call in the batch has been included on chain; and


Suggested change

* At least one call in the batch has been included on chain; and

* At least one call in the batch has been included on chain.

Marchhill · 2025-01-23T11:42:39Z

+
+Status `207` SHALL be returned only when all of the following are true:
+
+* At least one call in the batch has been included and succeeded;


Suggested change

* At least one call in the batch has been included and succeeded;

* At least one call in the batch has been included and succeeded.

Same for rest of list, for consistency with other lists

Marchhill · 2025-01-23T11:44:32Z

+
+## Backwards Compatibility
+
+<!--


can be removed

github-actions · 2025-01-27T16:05:02Z

The commit a269e9d (as a parent of d421328) contains errors.
Please inspect the Run Summary for details.

g11tech · 2025-01-29T19:10:01Z

+
+The following subsections are modifications to the API endpoints from EIP-5792.
+
+If a request does not match the schema defined below, the wallet MUST reject the request with an error code of 0 <!-- TODO -->.


i would prefer to create a params/constants table and refer them by their param/constant name here. brings it out as well as confine the TODO to a particualr section.

similarly with other TODOS

g11tech · 2025-01-29T19:10:32Z

small nit and linter/markup fixes required

lukasrosario · 2025-02-04T09:30:39Z

any particular reason this isn't an ERC @SamWilsn ? other capabilities are ERCs and 5792 technically does specify capabilities should be ERCs

lukasrosario · 2025-02-04T09:33:45Z

+Strict atomicity is simply naming the default behaviour of EIP-5792: calls
+within a single batch MUST be contiguous and applied atomically (or the batch
+rolled back.)


this is effectively atomicBatch right?

Can I pitch a more explicit naming for atomicity
strict -> transaction
loose -> bundle
none -> none
I think this more clearly states what the app is requesting

I'm not sure I find those more clear? What is a bundle? They also seem tied to particular implementations. I can imagine a multisig where each signature is a single transaction and only the last one executes the calls. You'd have multiple transactions, applied atomically.

I think in that example I would only expect the last transaction to show up in the result (the signature transactions aren't really relevant to the app's request).

Fair that it's still not super clear. I guess I prefer these as it's more explicit about how the calls take place, i.e.
transaction = all in one transaction
bundle = in a bundle of transactions (Flashbots bundles as a reference), implying that transactions will be executed as a group, unless there's a reorg
none = no constraints

jakubuid · 2025-02-09T16:43:25Z

+
+## Motivation
+
+While the base EIP-5792 specification works extremely well for smart contract wallets, it does not allow the expression of the full range of flow control options that wallets can implement. For example, a dapp may only be submitting a batch for gas savings and not care about whether all calls are reverted on failure. A wallet may only be able to offer a limited form of atomicity through block builder backchannels, but that may be sufficient for a trading platform.


a dapp may only be submitting a batch for gas savings and not care about whether all calls are reverted on failure

Why wouldn't dapp care? What's the user flow in this case?

Something like a token dispersement or several unrelated swaps. For example, I could be swapping several ERC-20 tokens into ETH. I just want as much of that ETH as possible, and I'll resubmit any failed swaps.

jakubuid · 2025-02-09T16:55:49Z

+        "data": "0xfbadbaf01",
+        "capabilities": {
+            "flow-control": {
+                "on-failure": "continue"


what exactly is a wallet supposed to do in this case when the flow fails? what does continue mean? like to continue with the execution of the next calls? what if there's only one call in the array?

Hopefully that's defined well enough later in the document (and let me know if it isn't), but a failed call with "on-failure": "continue" is just skipped, and the next call is executed.

jakubuid · 2025-02-09T17:08:42Z

+* MUST reject (with error code 0<!-- TODO -->) batches containing unsupported
+  `on-failure` modes.


We should rather set some default mode instead of forcing a wallet to reject such a batch. The reasoning is that on mobile devices MUST reject indicates that the wallet should reject such request immediately which is bad UX. Imagine a mobile wallet in the background that is triggered by a dapp aka it receives the batch request, a wallet is put to the foreground and immediately redirects back to a dapp without any information to the user. It should rather default to some mode and continue the flow.

We should rather set some default mode instead of forcing a wallet to reject such a batch.

This is unacceptable behaviour. If the dapp requests a mode, it has to get that mode. Imagine asking for "rollback" and getting "continue". That could be catastrophic.

Imagine a mobile wallet in the background that is triggered by a dapp aka it receives the batch request, a wallet is put to the foreground

Does the wallet need to be in the foreground to reject the request? If so, how does the UX flow work for unsupported RPC endpoints, like for example eth_signTransaction on MetaMask? This doesn't seem unique to just this proposal.

immediately redirects back to a dapp without any information to the user

The standard doesn't say anything about not displaying information to the user. The wallet is free to display a message to the user before redirecting back to the dapp.

I meant more like the scenario where the dapp requests the mode, but the wallet doesn't support that mode. The proposal suggests the rejection, which is a bad UX on mobile, hence reasoning for some default behaviour that mitigates that.

Yes, on mobile, a wallet must be foregrounded to receive the request. So, in the MetaMask case (and not only), they support the CAIP-25 handshake, which defines the methods, chains, and events supported by a wallet, so dapp knows before sending the request if a given method is supported by a wallet or not. Hence, there's no problem with automatic rejection on mobile.

Now, when I'm writing this, I realized that the wallet could use the CAIP-25 handshake (sessionProperties) to define what modes are supported, so the dapp could only request those that the wallet supports.

@SamWilsn
I think it might be useful to add a section explaining how wallets can define flow-control capabilities via CAIP-25 that would mitigate the above. Something similar to the section in 7811

jakubuid · 2025-02-09T17:10:46Z

+#### `wallet_sendCalls`
+
+The wallet MUST reject `wallet_sendCalls` requests with error code 0
+<!-- TODO --> where both:


As mentioned below, this creates a bad UX on mobile devices. We should rather default to one agreed behaviour to keep the user flow consistent instead of letting a wallet auto-reject such requests:
https://github.com/ethereum/EIPs/pull/9259/files#r1948151108

jakubuid · 2025-02-09T17:17:52Z

+The returned `receipts` array:
+
+* MUST NOT contain more than one receipt for the same transaction.
+* SHOULD NOT contain receipts for transactions without a call from the requested


Why not MUST NOT? Is it allowed to add a receipt for a call that was not icluded in the batch? If yes, why, and what is the use case?

I went with "MUST NOT" for things that would break/be unsafe, and SHOULD NOT for things that would be weird but not dangerous.

jakubuid · 2025-02-18T08:58:46Z

+        "flow-control": {
+            "loose": ["halt", "continue"],
+            "strict": ["continue"]


Shouldn't this define on-failure flow control for call-scope and atomicity flow control for batch-scope?

Not sure how to interpret this part:

"loose": ["halt", "continue"], "strict": ["continue"]

This snippet is saying the wallet supports on-failure modes of halt and continue when using loose atomicity, but only continue when using strict.

Co-authored-by: Marc <Marchhill@users.noreply.github.com>

azf20

A couple of comments / questions.

azf20 · 2025-02-28T20:55:43Z

+
+## Motivation
+
+While the base EIP-5792 specification works extremely well for smart contract wallets, it does not allow the expression of the full range of flow control options that wallets can implement. For example, a dapp may only be submitting a batch for gas savings and not care about whether all calls are reverted on failure. A wallet may only be able to offer a limited form of atomicity through block builder backchannels, but that may be sufficient for a trading platform.


I think it is worth mentioning the EOA use case (for 7702 laggards, whether chains or wallets).
I think it is also worth mentioning that while atomicity might be a hard requirement for some use cases (particularly Defi), for others it is not important, and this allows those apps to benefit from 5792 as well. Also notably approve-transfer is currently non-atomic, and improving that UX is generally a priority.

azf20 · 2025-02-28T20:56:25Z

+      "atomicity": {
+        "enum": ["strict", "loose", "none"]
+      }
+    }


why not allow setting onFailure at the top level to set the default?

azf20 · 2025-02-28T20:57:14Z

+Strict atomicity is simply naming the default behaviour of EIP-5792: calls
+within a single batch MUST be contiguous and applied atomically (or the batch
+rolled back.)


Can I pitch a more explicit naming for atomicity
strict -> transaction
loose -> bundle
none -> none
I think this more clearly states what the app is requesting

azf20 · 2025-02-28T20:59:57Z

+
+A rollback is informally defined as "causing no meaningful changes on chain." A
+rolled back batch only makes gas accounting and bookkeeping (eg. nonce)
+changes. In other words, a rollback is the default behaviour of EIP-5792 when


I think it's worth calling out that with this EIP the default is strict / rollback (maybe not in this spot, but mentioning because it's alluded to here)

azf20 · 2025-02-28T21:01:05Z

+changes. In other words, a rollback is the default behaviour of EIP-5792 when
+a call fails.
+
+#### Critical Calls


I don't see critical defined in the JSON schema?

I'm defining critical here so I can use:

"critical call" as short-form for call with "onFailure": "rollback" and;

"non-critical call" as short-form for the other modes.

azf20 · 2025-02-28T23:26:42Z

+
+* MUST treat a missing call-scope `flowControl` capability as equivalent to
+  setting `onFailure` to `rollback`.
+* MUST treat a missing call-scope `onFailure` mode as equivalent to `rollback`.


I think this is another argument for request-level onFailure settings - as an example I don't think loose and none are necessarily capable of rollback?

azf20 · 2025-02-28T23:32:52Z

+  provide for any reason other than user rejection.
+  * Wallets supporting `strict` but not `loose` SHOULD NOT reject `loose`
+    batches and SHOULD instead upgrade the request to strict atomicity.
+  * Note that a batch with exactly one call _always_ satisfies the requirements


For such calls any specification of flow control capabilities is effectively ignored, as it's necessarily strict / rollback?

azf20 · 2025-02-28T23:36:24Z

+  batch.
+* MUST contain exactly one receipt capturing each successful call.
+    * Multiple calls MAY be captured in one receipt, but the successful
+      execution of one call MUST NOT be captured by multiple receipts.


is it even possible for a successful call to be captured by multiple receipts?

azf20 · 2025-02-28T23:39:19Z

+            * `[(successful A, successful B)]`
+            * `[(successful A), (successful B)]`
+            * `[(successful A, unsuccessful B), (successful B)]`
+            * `[(unsuccessful A), (successful A), (successful B)]`


how are unsuccessful calls represented? obviously the receipt as a whole has a status, but you can have failed calls in a successful receipt (requiring tracing to track down what actually happened) - and I don't see where in the call result it's identified one way or the other

azf20 · 2025-02-28T23:44:43Z

+{
+    "0x1": {
+        "flowControl": {
+            "none": [ "rollback", "continue" ]


how do you rollback in none?

I believe the options should be halt and continue. Right @SamWilsn?

It would be quite weird to have none + rollback...

eth-bot

All Reviewers Have Approved; Performing Automatic Merge...

KristijanSajenko

Gg

SamWilsn requested a review from eth-bot as a code owner January 22, 2025 19:10

github-actions Bot added c-new Creates a brand new proposal s-draft This EIP is a Draft t-interface labels Jan 22, 2025

eth-bot added e-consensus Waiting on editor consensus e-review Waiting on editor to review labels Jan 22, 2025

eth-bot changed the title ~~Add EIP: EIP-5792 flow control~~ Add EIP: Flow Control Wallet Call Capability Jan 22, 2025

github-actions Bot added the w-ci Waiting on CI to pass label Jan 22, 2025

SamWilsn force-pushed the eip-call-flow-control branch from 64b1893 to 114bb1c Compare January 22, 2025 19:15

Marchhill approved these changes Jan 23, 2025

View reviewed changes

SamWilsn force-pushed the eip-call-flow-control branch from 114bb1c to 9968288 Compare January 24, 2025 00:23

Remaong89 approved these changes Jan 24, 2025

View reviewed changes

poojaranjan mentioned this pull request Jan 28, 2025

EIP Editing Office Hour Meeting 50 ethcatherders/EIPIP#377

Closed

31 tasks

g11tech reviewed Jan 29, 2025

View reviewed changes

lukasrosario reviewed Feb 4, 2025

View reviewed changes

jakubuid reviewed Feb 9, 2025

View reviewed changes

jakubuid reviewed Feb 18, 2025

View reviewed changes

g11tech reviewed Feb 25, 2025

View reviewed changes

Comment thread EIPS/eip-7867.md

SamWilsn and others added 4 commits February 27, 2025 11:43

Add EIP: flow control

3cd628e

Apply suggestions from code review

c1d4c90

Co-authored-by: Marc <Marchhill@users.noreply.github.com>

Update and rename eip-draft_wallet-call-flow-control.md to eip-7867.md

7fc7072

EIP-7867: Rename flow-control to flowControl

3fb0b54

SamWilsn added 3 commits February 27, 2025 11:50

Move error codes into table

c912870

Fix markdownlint

ac46d68

Rename on-failure to onFailure

ca6955a

SamWilsn force-pushed the eip-call-flow-control branch from a269e9d to ca6955a Compare February 27, 2025 16:54

github-actions Bot removed the w-ci Waiting on CI to pass label Feb 27, 2025

azf20 reviewed Feb 28, 2025

View reviewed changes

SamWilsn added 2 commits March 6, 2025 12:41

Update eip-7867.md

e57fc81

Update eip-7867.md

f19a8f5

g11tech approved these changes Mar 12, 2025

View reviewed changes

eth-bot enabled auto-merge (squash) March 12, 2025 08:33

eth-bot approved these changes Mar 12, 2025

View reviewed changes

eth-bot merged commit c1e8ebe into ethereum:master Mar 12, 2025
1 check passed

KristijanSajenko approved these changes Mar 1, 2026

View reviewed changes


		#### Rollback

		A rollback is informally defined as "causing no meaningful changes on chain." A

	successfully or unsuccessfully executed. A call that has been recorded on chain,
	executed, even if execution was unsuccessful. A call that has been recorded on chain,


		Status `102` SHALL be returned only when all of the following are true:

		* At least one call in the batch has been included on chain; and


		Status `207` SHALL be returned only when all of the following are true:

		* At least one call in the batch has been included and succeeded;


		The following subsections are modifications to the API endpoints from EIP-5792.

		If a request does not match the schema defined below, the wallet MUST reject the request with an error code of 0 <!-- TODO -->.


		## Motivation

		While the base EIP-5792 specification works extremely well for smart contract wallets, it does not allow the expression of the full range of flow control options that wallets can implement. For example, a dapp may only be submitting a batch for gas savings and not care about whether all calls are reverted on failure. A wallet may only be able to offer a limited form of atomicity through block builder backchannels, but that may be sufficient for a trading platform.

		* MUST reject (with error code 0<!-- TODO -->) batches containing unsupported
		`on-failure` modes.

Conversation

SamWilsn commented Jan 22, 2025

Uh oh!

eth-bot commented Jan 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Marchhill left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jan 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

g11tech commented Jan 29, 2025

Uh oh!

lukasrosario commented Feb 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakubuid Feb 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SamWilsn Feb 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakubuid Feb 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

azf20 left a comment

Choose a reason for hiding this comment

Uh oh!

eth-bot commented Jan 22, 2025 •

edited

Loading

jakubuid Feb 9, 2025 •

edited

Loading

SamWilsn Feb 9, 2025 •

edited

Loading

jakubuid Feb 9, 2025 •

edited

Loading