Skip to content

Commit

Permalink
Merge pull request #12 from lukasrosario/lukas/add-statuses
Browse files Browse the repository at this point in the history 
Add statuses
  • Loading branch information
@forshtat
forshtat authored Jan 13, 2025
2 parents b337a12 + 746cc8c commit 15e27af
Showing 1 changed file with 42 additions and 29 deletions.
71 changes: 42 additions & 29 deletions EIPS/eip-5792.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ The items in the `calls` field are simple `{to, data, value}` tuples.
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.
These fields are set inside this capability's entry in the `capabilities` object.
Each entity in the `calls` field may contain an optional `capabilities` object.
This object allows the applications to attach a capability-specific metadata to individual calls.

The wallet:
Expand Down Expand Up @@ -72,12 +72,15 @@ type SendCallsParams = {
to?: `0x${string}` | undefined;
data?: `0x${string}` | undefined;
value?: `0x${string}` | undefined; // Hex value
capabilitiesData?: Record<string, any> | undefined;
capabilities?: Record<string, any> | undefined;
}[];
capabilities?: Record<string, any> | undefined;
};

type SendCallsResult = string;
type SendCallsResult = {
id: string;
capabilities?: Record<string, any> | undefined;
};
```

##### `wallet_sendCalls` Example Parameters
Expand Down Expand Up @@ -115,11 +118,14 @@ Note that since the `paymasterService` `capability` is marked as optional, walle
##### `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.
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 `capabilities` object allows the wallets to attach a capability-specific metadata to the response.

```json
"0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
{
"id": "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
}
```

### `wallet_getCallsStatus`
Expand All @@ -128,10 +134,10 @@ 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.
The `capabilities` object allows the wallets to attach a capability-specific metadata to the response.

* The receipts in the `receipts` field MUST be in order they are included on-chain.
* The `receipts` field MUST contain receipts for all calls in a batch that were included on-chain, including reverted ones.
* 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 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 @@ -141,9 +147,9 @@ The `capabilitiesResultsData` object allows the wallets to attach a capability-s
type GetCallsParams = string;

type GetCallsResult = {
callsId: `0x${string}`;
id: `0x${string}`;
chainId?: `0x${string}`;
batchStatus: string; // See "Status Codes"
status: string; // See "Status Codes"
receipts?: {
logs: {
address: `0x${string}`;
Expand All @@ -156,26 +162,34 @@ type GetCallsResult = {
gasUsed: `0x${string}`;
transactionHash: `0x${string}`;
}[];
capabilitiesResultsData?: Record<string, any> | undefined;
capabilities?: Record<string, any> | undefined;
};
```

##### Status Codes for `batchStatus` field
##### Status Codes for `status` field

The purpose of the `batchStatus` field is to provide a short summary of the current status of the batch.
The purpose of the `status` field is to provide a short summary of the current status of the batch.
It provides some off-chain context to the array of inner transaction `receipts`.

| Name | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| PENDING | Batch has been received by the wallet but has not completed execution on-chain |
| SUCCESS | Batch has been included on-chain without reverts, receipts array contains info of all calls |
| PARTIAL | Batch has been included on-chain only partially, the rest is either reverted or invalid. Receipts array contains info of all on-chain included calls |
| FAILURE | Batch has been invalid or reverted completely and only changes related to gas charge may have been included on-chain |
| DISCARDED | Batch has not been included on-chain and wallet will not retry |
| 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`.
The `id` batch identifier is a unique 64 bytes represented as a hex encoded string returned from `wallet_sendCalls`.

```json
[
Expand All @@ -188,8 +202,8 @@ The `callsID` batch identifier is a unique 64 bytes represented as a hex encoded
```json
{
"chainId": "0x01",
"callsId": "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
"batchStatus": "SUCCESS",
"id": "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
"status": "200",
"receipts": [
{
"logs": [
Expand Down Expand Up @@ -245,7 +259,6 @@ 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)
Expand All @@ -267,15 +280,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 15e27af

Please sign in to comment.