From c63e59dae8f9f06949b6de1317b9be9c4571beb3 Mon Sep 17 00:00:00 2001 From: Lukas <36800180+lukasrosario@users.noreply.github.com> Date: Wed, 8 Jan 2025 15:39:06 -0500 Subject: [PATCH] Update EIP-5792: Add status codes" Merged by EIP-Bot. --- EIPS/eip-5792.md | 81 ++++++++++++++---------------------------------- 1 file changed, 23 insertions(+), 58 deletions(-) diff --git a/EIPS/eip-5792.md b/EIPS/eip-5792.md index 5bd2d491d8a303..9d20cc9b52e106 100644 --- a/EIPS/eip-5792.md +++ b/EIPS/eip-5792.md @@ -34,20 +34,14 @@ We also define one capability expression for use with the fourth method, which f ### `wallet_sendCalls` -Requests that a wallet submits a batch of calls. `from` and `chainId` are top-level properties rather than per-call properties because all calls should be sent from the same sender and on the same chain, identified by [EIP-155](./eip-155.md) integers expressed in hexadecimal notation. -The items in the `calls` field are simple `{to, data, value}` tuples. +Requests that a wallet submits a batch of calls. `from` and `chainId` are top-level properties rather than per-call properties because all calls should be sent from the same sender and on the same chain, identified by [EIP-155](./eip-155.md) integers expressed in hexadecimal notation. The items in the `calls` field are only those that are shared by all transaction types. Any other fields that a wallet may need to submit a transaction should be handled by the wallet. The capabilities field is how an app can communicate with a wallet about capabilities a wallet supports. For example, this is where an app can specify a paymaster service URL from which an [ERC-4337](./eip-4337.md) wallet can request a `paymasterAndData` input for a user operation. -Each capability defined in the "capabilities" member can define global or call specific fields. -These fields are set inside this capability's entry in the `capabilitiesData` object. -Each entity in the `calls` field may contain an optional `capabilitiesData` object. -This object allows the applications to attach a capability-specific metadata to individual calls. - The wallet: * MUST send the calls in the order specified in the request -* MUST send the calls on the same chain identified by the request's `chainId` property +* MUST send the calls on the same chain identified by the call's `chainId` property * MUST NOT await for any calls to be finalized to complete the batch * MUST NOT send any calls from the request if the user rejects the request * MAY revert all calls if any call fails @@ -55,7 +49,6 @@ The wallet: * SHOULD stop executing the calls if any call fails * MAY reject the request if the from address does not match the enabled account * MAY reject the request if one or more calls in the batch is expected to fail, when simulated sequentially -* MUST reject the request if it contains a `capability` that is not supported by the wallet #### `wallet_sendCalls` RPC Specification @@ -63,12 +56,11 @@ The wallet: type SendCallsParams = { version: string; from: `0x${string}`; - chainId: `0x${string}` | undefined; // Hex chain id calls: { to?: `0x${string}` | undefined; data?: `0x${string}` | undefined; value?: `0x${string}` | undefined; // Hex value - capabilitiesData?: Record | undefined; + chainId?: `0x${string}` | undefined; // Hex chain id }[]; capabilities?: Record | undefined; }; @@ -83,17 +75,18 @@ type SendCallsResult = string; { "version": "1.0", "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", - "chainId": "0x01", "calls": [ { "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", "value": "0x9184e72a", - "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" + "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", + "chainId": "0x01", }, { "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", "value": "0x182183", - "data": "0xfbadbaf01" + "data": "0xfbadbaf01", + "chainId": "0x01", } ], "capabilities": { @@ -108,24 +101,17 @@ type SendCallsResult = string; ##### `wallet_sendCalls` Example Return Value -The identifier MUST be unique 64 bytes represented as a hex encoded string. -For a given session, users should be able to call `wallet_getCallsStatus` with this value and expect a call-batch status -to be returned. +The identifier can be any string. The only requirement is that for a given session, users should be able to call `wallet_getCallsStatus` with this value and expect a call-batch status to be returned. ```json -"0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" +"0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" ``` ### `wallet_getCallsStatus` -Returns the status of a call batch that was sent via `wallet_sendCalls`. -The identifier of the batch is the value returned from the `wallet_sendCalls` RPC. -Note that the `receipts` objects of this method's response is a strict subset of the object returned by `eth_getTransactionReceipt`. - -The `capabilitiesResultsData` object allows the wallets to attach a capability-specific metadata to the response. +Returns the status of a call batch that was sent via `wallet_sendCalls`. The identifier of the transaction is the value returned from the `wallet_sendCalls` RPC. Note that this method only returns a subset of the fields that `eth_getTransactionReceipt` returns, excluding any fields that may differ across wallet implementations. -* The receipts in the `receipts` field MUST be in order they are included onchain. -* The `receipts` field MUST contain receipts for all calls in a batch that were included onchain, including reverted ones. +* If a wallet does not execute multiple calls atomically (i.e. in multiple transactions), the receipts in the `receipts` field MUST be in order of the calls sent. * If a wallet executes multiple calls atomically (i.e. in a single transaction), `wallet_getCallsStatus` MUST return a single receipt, corresponding to the transaction in which the calls were included. * The `logs` in the receipt objects MUST only include logs relevant to the calls submitted using `wallet_sendCalls`. For example, in the case of a transaction submitted onchain by an [ERC-4337](./eip-4337.md) bundler, the logs must only include those relevant to the user operation constructed using the calls submitted via `wallet_sendCalls`. I.e. the logs should not include those from other unrelated user operations submitted in the same bundle. @@ -135,9 +121,7 @@ The `capabilitiesResultsData` object allows the wallets to attach a capability-s type GetCallsParams = string; type GetCallsResult = { - callsId: `0x${string}`; - chainId?: `0x${string}`; - batchStatus: string; // See "Status Codes" + status: 'PENDING' | 'CONFIRMED'; receipts?: { logs: { address: `0x${string}`; @@ -145,39 +129,22 @@ type GetCallsResult = { topics: `0x${string}`[]; }[]; status: `0x${string}`; // Hex 1 or 0 for success or failure, respectively + chainId: `0x${string}`; blockHash: `0x${string}`; blockNumber: `0x${string}`; gasUsed: `0x${string}`; transactionHash: `0x${string}`; }[]; - capabilitiesResultsData?: Record | undefined; }; ``` -##### Status Codes for `batchStatus` field - -| Code | Description | -|------|-------------| -| 100 | Batch has been received by the wallet but has not completed execution onchain (pending) | -| 200 | Batch has been included onchain without reverts, receipts array contains info of all calls (confirmed) | -| 400 | Batch reverted completely and only changes related to gas charge may have been included onchain (chain rules failure) | -| 500 | Batch has not been included onchain and wallet will not retry (offchain failure) | - -Status codes follow these categories: -* 1xx: Pending states -* 2xx: Confirmed states -* 4xx: Chain rules failures -* 5xx: Offchain failures - -More specific status codes within these categories should be proposed and agreed upon in separate ERCs. - ##### `wallet_getCallsStatus` Example Parameters -The `callsID` batch identifier is a unique 64 bytes represented as a hex encoded string returned from `wallet_sendCalls`. +As with the return value of `wallet_sendCalls`, the batch identifier may be any string. ```json [ - "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" + "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" ] ``` @@ -185,9 +152,7 @@ The `callsID` batch identifier is a unique 64 bytes represented as a hex encoded ```json { - "chainId": "0x01", - "callsId": "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", - "batchStatus": "200", + "status": "CONFIRMED", "receipts": [ { "logs": [ @@ -200,6 +165,7 @@ The `callsID` batch identifier is a unique 64 bytes represented as a hex encoded } ], "status": "0x1", + "chainId": "0x01", "blockHash": "0xf19bbafd9fd0124ec110b848e8de4ab4f62bf60c189524e54213285e7f540d4a", "blockNumber": "0xabcd", "gasUsed": "0xdef", @@ -231,7 +197,7 @@ This method accepts a call bundle identifier returned by a `wallet_sendCalls` ca ### `wallet_getCapabilities` -This RPC allows an application to request capabilities from a wallet (e.g. batch transactions, paymaster communication), without distinct discovery and permission requests. For more on the difference between requesting capabilities and discovering features, see the ["Privacy Considerations" section](#privacy-considerations). +This RPC allows an application to request capabilities from a wallet (e.g. batch transactions, paymaster communication), without distinct discovery and permission requests. For more on the difference between requesting capabilities and discoverying features, see the ["Privacy Considerations" section](#privacy-considerations). This method SHOULD return an error if the user has not already authorized a connection between the application and the requested address. @@ -245,10 +211,9 @@ If any of these supplemental expressions of capabilities are contradicted by cap Capabilities are returned in key/value pairs, with the key naming a capability and a value conforming to a shape defined for that name, in an object keyed to the relevant [EIP-155](./eip-155.md) `chainId` expressed in hexadecimal notation. Capabilities are nested in per-chain objects because wallets may support different capabilities across multiple chains authorized in a given session. -All values for the "capability" fields MUST contain Semantic Version value `version`. ```typescript -type GetCapabilitiesParams = [`0x${string}`, [`0x${string}`]]; // Wallet address, array of queried chain ids (optional) +type GetCapabilitiesParams = [`0x${string}`]; // Wallet address type GetCapabilitiesResult = Record<`0x${string}`, >; // Hex chain id ``` @@ -256,7 +221,7 @@ type GetCapabilitiesResult = Record<`0x${string}`, >; // Hex ##### `wallet_getCapabilities` Example Parameters ```json -["0xd46e8dd67c5d32be8058bb8eb970870f07244567", ["0x2105", "0x14A34"]] +["0xd46e8dd67c5d32be8058bb8eb970870f07244567"] ``` ##### `wallet_getCapabilities` Example Return Value @@ -267,15 +232,15 @@ The capabilities below are for illustrative purposes. { "0x2105": { "paymasterService": { - "version": "1.0.0" + "supported": true }, "sessionKeys": { - "version": "1.0.0" + "supported": true } }, "0x14A34": { "paymasterService": { - "version": "1.0.0" + "supported": true } } }