Skip to content

Commit

Permalink
Update EIP-5792: Add status codes"
Browse files Browse the repository at this point in the history 
Merged by EIP-Bot.
  • Loading branch information
@lukasrosario
lukasrosario authored Jan 8, 2025
1 parent 3c4dc08 commit c63e59d
Showing 1 changed file with 23 additions and 58 deletions.
81 changes: 23 additions & 58 deletions EIPS/eip-5792.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,41 +34,33 @@ 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
* MAY send all calls as part of one or more transactions, depending on wallet capability
* 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

```typescript
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<string, any> | undefined;
chainId?: `0x${string}` | undefined; // Hex chain id
}[];
capabilities?: Record<string, any> | undefined;
};
Expand All @@ -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": {
Expand All @@ -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.

Expand All @@ -135,59 +121,38 @@ 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}`;
data: `0x${string}`;
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<string, any> | 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"
]
```

##### `wallet_getCallsStatus` Example Return Value

```json
{
"chainId": "0x01",
"callsId": "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
"batchStatus": "200",
"status": "CONFIRMED",
"receipts": [
{
"logs": [
Expand All @@ -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",
Expand Down Expand Up @@ -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.

Expand All @@ -245,18 +211,17 @@ 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}`, <Record<string, any>>; // Hex chain id
```
##### `wallet_getCapabilities` Example Parameters
```json
["0xd46e8dd67c5d32be8058bb8eb970870f07244567", ["0x2105", "0x14A34"]]
["0xd46e8dd67c5d32be8058bb8eb970870f07244567"]
```
##### `wallet_getCapabilities` Example Return Value
Expand All @@ -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
}
}
}
Expand Down

0 comments on commit c63e59d

Please sign in to comment.