From 6eb0638ce2b85136d9781b2b91122fb40e7d304e Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 18:46:03 +0100 Subject: [PATCH 01/11] Create Native AA JSON_RPC API A partial rewrite of the previous proposal found here: https://github.com/ethereum/ERCs/pull/625 Changes: * Some extra descriptions. * Removed the mention of the native tracing API as ERC-7562 is likely to be implemented natively regardless of this RIP. * Added a link to the Paymaster capability ERC-7677 * Made `eth_callAA` return the emitted logs array * Added example JSON requests and responses --- RIPS/rip-0000.md | 314 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 RIPS/rip-0000.md diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md new file mode 100644 index 0000000..246e5c1 --- /dev/null +++ b/RIPS/rip-0000.md @@ -0,0 +1,314 @@ +--- +rip: 0000 +title: Native Account Abstraction RPC methods +description: Native Account Abstraction specific RPC methods providing support for common user flows such as transaction gas estimation and view-only calls to smart contracts +author: Vitalik Buterin (@vbuterin), Yoav Weiss (@yoavw), Alex Forshtat (@forshtat), Dror Tirosh (@drortirosh), Shahaf Nacson (@shahafn) +discussions-to: +status: Draft +type: Standards Track +category: Core +created: 2025-01-01 +requires: 7560 +--- + +## Abstract + +With the introduction of Account Abstraction as it is defined by [RIP-7560](./rip-7560.md) +a number of existing RPC APIs are not capable of providing the necessary functionality. +The required behaviour changes are significant enough to require an introduction of completely new methods +to the Ethereum L2 clients implementing Account Abstraction. + +## Motivation + +The process of creating a transaction has been getting increasingly more complex and interactive process +with the growing complexity of on-chain protocols. +The introduction of Account Abstraction introduces a new dimension for this complexity. + +As the AA transactions are executed atomically but consist of multiple sequential frames, +it is not possible to reliably prepare parts of the AA transaction individually. + +For example, when creating an AA transaction that also performs a deployment of a `sender` smart account, +it is all but impossible to perform a gas estimation for the execution frame using the existing `eth_estimateGas` API. + +Instead, an API specifically designed with Account Abstraction in mind must be used. + +## Specification + +This document defines the API that the RIP-7560 compatible Ethereum nodes provide to the Smart Wallet applications. + +### eth_estimateGasAA + +Estimate the amount of gas needed per frame of an AA transaction. +Performs a search for gas limit values required to make each of the frames of the RIP-7560 transaction execute +successfully and without running out of gas. + +This method is an equivalent to the legacy Ethereum `eth_estimateGas` RPC API method. +This method is also a native AA equivalent to the `eth_estimateUserOperationGas` method for +[ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) UserOperations as defined in +[ERC-7769](https://eips.ethereum.org/EIPS/eip-7769). + +For validation frames, only valid calls to an appropriate `AA_ENTRY_POINT` callback, +such as `acceptAccount`, `acceptPaymaster`, `sigFailAccount` and `sigFailPaymaster`, is considered a success. + +Note that in order for `eth_esimateGasAA` to function both the wallet and the paymaster must correctly +implement signature checks as described in RIP-7560.\ +Most notably, the fields `senderValidationData` and `paymasterData` usually contain signatures for the transaction +and therefore cannot be known before the transaction preparation is complete.\ +The recommended solution to this problem is for the wallet to provide **stub data** for these contracts, +as described in the [Suggested Paymaster Flow](#suggested-paymaster-flow) section. + +Once a signature verification over the **stub data** fails, the validation code must not revert or finish execution, +but instead proceed as usual until making a `sigFailAccount` or `sigFailPaymaster` call accordingly.\ +A contract that does not implement RIP-7560 will cause `eth_esimateGasAA` to provide inconsistent results +and will risk sporadically reverting on out-of-gas errors on-chain. + +The `eth_esimateGasAA` API optionally accepts the `State Override Set` object to allow users to modify +the state during the gas estimation. +This field as well as its behavior is equivalent to the ones defined for the `eth_call` RPC method. + +If it fails to find such a value, returns an error message with the detailed description of the failure reason. + +Parameters: + +1. OBJECT - The RIP-7560 transaction object. + The `validationGasLimit`, paymasterValidationGasLimit, `paymasterGasLimit` and `callGasLimit` fields are optional. +2. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized" +3. OBJECT - `State Override Set` + The `State Override Set` option allows you to change the state of a contract before executing the call. This means you + can modify the values of variables stored in the contract, such as balances and approvals for that call without + actually modifying the contract on the blockchain. + This behavior is equivalent to the one defined for the `eth_call` RPC method. + +Example: +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "eth_estimateGasAA", + "params": [ + { + "sender": "0x783Ca0bD27E42357D6Dbc87E9Cf9eb3a8D513843", + "senderValidationData": "0xdeadbeef", + "deployer": "0xD6E4aA932147A3FE5311dA1b67D9e73da06F9cEf", + "deployerData": "0xdeadbeef", + "paymaster": "0x8410373DF6E9b20765c9599c26d585B2cd0Ef628", + "paymasterData": "0xdeadbeef", + "executionData": "0xdeadbeef", + "builderFee": "0x9184e72a000", + "maxPriorityFeePerGas": "0x9184e72a000", + "maxFeePerGas": "0x9184e72a000", + "accessList": [], + "authorizationList": [ + { + "chainId": "0x1", + "nonce": "0x15", + "yParity": "0x25", + "r": "0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea", + "s": "0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c" + } + ] + }, + "latest", + { + "0x1111111111111111111111111111111111111111": { + "balance": "0x9184e72a000", + "nonce": "0x1", + "code": "0xdeadbeef", + "state": { + "0x0000000000000000000000000000000000000000000000000000000000000001": "0x1" + }, + "stateDiff": { + "0x0000000000000000000000000000000000000000000000000000000000000001": "0x1" + } + } + } + ] +} +``` +Returns: + +| Name | Type | Comment | +|-----------------------------|----------|------------------------------------------------------------| +| validationGasLimit | QUANTITY | | +| callGasLimit | QUANTITY | | +| paymasterValidationGasLimit | QUANTITY | if `paymaster` is set, `null` otherwise | +| paymasterPostOpGasLimit | QUANTITY | if `paymaster` is set, `0` if not needed, `null` otherwise | + +Example: + +```json +{ + "validationGasLimit": "0x9184e72a000", + "paymasterValidationGasLimit":"0x9184e72a000", + "paymasterPostOpGasLimit":"0x9184e72a000", + "callGasLimit": "0x9184e72a000" +} +``` + +### eth_callAA + +Execute the AA transaction in memory without broadcasting it to the mempool or commiting it to the blockchain. +An equivalent to the legacy Ethereum `eth_call` RPC API method. + +Inputs are equivalent to the ones defined for the [eth_estimateGasAA](#eth_estimategasaa) method. + +User can also provide the gas limit for all or some of the AA transaction frames.\ +If gas limits are not provided, the RPC node provider is free to choose a default value.\ +The RPC node provider should also choose a maximum acceptable gas limit value taking into consideration the +block gas limit and other rules of the underlying L2 protocol. + +Does not require the transaction to be properly signed, meaning it continues execution after either an account +or a paymaster contract make a `sigFailAccount` or `sigFailPaymaster` call. + +Returns the data that is returned by the top-level execution frame, gas usage info, +as well as the full array of event logs emitted during the execution of the RIP-7560 transaction + +If any of the validation or execution frames reverts, returns an error object containing the revert message. + +Inputs: + +1. OBJECT - The RIP-7560 transaction object. + The `authorizationData` field is optional. +2. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized" + +Returns: + +- **returnData** - DATA - the return value of the `sender` execution frame +- **gasUsed** - QUANTITY - the total amount of gas used by the transaction +- **sigFail** - QUANTITY - whether account called "sigFailAccount" or not +- **sigFailPaymaster** - QUANTITY - whether paymaster called "sigFailPaymaster" or not +- **status** - QUANTITY - whether the execution phase including the `paymasterPostOp` completed successfully +- **logs** - ARRAY - an array of the event logs emitted during the transaction + +Example: +```json +{ + "returnData": "0xdeadbeef", + "gasUsed": "0x1a14b", + "status": "0x1", + "sigFail": "0x1", + "sigFailPaymaster": "0x1", + "logs": [ + { + "transactionHash": "0x8fc90a6c3ee3001cdcbbb685b4fbe67b1fa2bec575b15b0395fea5540d0901ae", + "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + "blockHash": "0x58a945e1558810523df00490ff28cbe111b37851c44679ce5be1eeaebb4b4907", + "blockNumber": "0xeb8822", + "data": "0x000000000000000000000000000000000000000000000000000000001debea42", + "logIndex": "0x6c", + "removed": false, + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x0000000000000000000000005067c042e35881843f2b31dfc2db1f4f272ef48c", + "0x0000000000000000000000003ee18b2214aff97000d974cf647e7c347e8fa585" + ], + "transactionIndex": "0x4e" + } + ] +} +``` + +### wallet_prepareTransactionAA + +The `wallet_prepareTransactionAA` API is meant to be implemented by the wallet application, +and not the L2 client RPC node provider. + +The method accepts a partially filled RIP-7560 transaction object and fills in all the missing fields.\ +These may include gas prices, gas limits, nonces etc.\ +All parameters are optional. If the parameter is provided with a value, calling this method will never override it. + +The method returns the full transaction object that can be serialized and sent to the `eth_sendRawTransaction` API. + +In case the wallet was not able to fill the transaction object for any reason, +the `wallet_prepareTransactionAA` method returns an appropriate error code. + +### Suggested paymaster flow + +The Paymaster service should expose the `pm_getPaymasterStubData` and `pm_getPaymasterData` APIs as defined by the +[ERC-7677](https://eips.ethereum.org/EIPS/eip-7677). + +The API defined there should be implemented by a third party paymaster service, +and not by the L2 client RPC node provider. + +This API is expected to be used internally by the wallet application as part of the `wallet_prepareTransactionAA` flow. + +### Add Account Abstraction support for all transaction-level RPC APIs + +This includes the following APIs: +`eth_sendTransaction`, +`eth_sendRawTransaction`, +`eth_getTransactionByHash`, +`eth_getTransactionReceipt`, +`eth_getTransactionByBlockHashAndIndex`, +`eth_getTransactionByBlockNumberAndIndex`. + +These methods have a very similar purpose and should support returning the new transaction type object. + +Note that the "transaction index position" is determined by the position of the transaction's **validation frame**. + +### Errors + +Error format: + +- DATA - The revert data of the first reverted frame. +- CODE - The error code indicating the type of error, which may include the entity that caused the revert on-chain. +- MESSAGE - The human-readable error that may include a decoding of the `DATA` field if possible. + +Error codes: + +* code: -32500 - transaction validation failed by `sender`. + The message field SHOULD be set to the revert message and data from the `sender`. + +* code: -32501 - transaction validation failed by `paymaster`. + The message field SHOULD be set to the revert message and data from the `paymaster`. + +* code: -32502 - transaction validation failed by `deployer` + The message field SHOULD be set to the revert message and data from the `deployer`. + +* code: -32503 - Transaction out of time range. + The message field SHOULD include the requested time range and the current block timestamp. + + +## Rationale + +### New methods instead of modification for existing ones + +While the `eth_esimateGasAA` and `eth_callAA` methods are simply RIP-7560 extensions of the existing +`eth_esimateGasAA` and `eth_call` methods accordingly, +the type of the return values for the existing methods does not match the needs of the Native Account Abstraction API. + +The approach of creating a new set of methods is cleaner in the long term as these methods may be used later in the +EOF-based Native Account Abstraction as described in [EIP-7701](https://eips.ethereum.org/EIPS/eip-7701). + +### The `eth_callAA` returned data format + +The legacy `eth_call` method returns a single DATA array representing the return data of the single top-level +call frame of a legacy transaction. + +However, this approach would not be sufficiently useful for the Native Account Abstraction solution.\ +The top-level frame of the execution phase is a call to the `sender` smart account that may consist of multiple +inner batched calls. + +Furthermore, the code in the `sender` address is frequently just +a proxy contract that does not propagate the implementation's returned data. + +In order to allow smart contract wallets to reliably expose any data to the off-chain execution we have little choice +but to rely on the existing mechanism of emitting the event logs. + +## Backwards Compatibility + +The added methods are not interfering with any existing code and should pose no backwards compatibility issues. + +## Security Considerations + +### Estimate Gas flow in smart contracts + +As mentioned in the [eth_estimateGasAA](#eth_estimategasaa) section, the `sender` and `paymaster` smart contracts +are expected to explicitly implement a special code flow to support the gas estimation. + +This code is supposed to only be executable during the `eth_estimateGasAA` and MUST never result in a valid transaction. +In case this constraint is violated the contract will be vulnerable to various potential threats. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE.md). From 8c2253f8686d9c7a193aaf12994d3c6d06e61e40 Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:02:54 +0100 Subject: [PATCH 02/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 246e5c1..30a088a 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -48,7 +48,7 @@ This method is also a native AA equivalent to the `eth_estimateUserOperationGas` [ERC-7769](https://eips.ethereum.org/EIPS/eip-7769). For validation frames, only valid calls to an appropriate `AA_ENTRY_POINT` callback, -such as `acceptAccount`, `acceptPaymaster`, `sigFailAccount` and `sigFailPaymaster`, is considered a success. +such as `acceptAccount`, `acceptPaymaster`, `sigFailAccount` and `sigFailPaymaster`, are considered a success. Note that in order for `eth_esimateGasAA` to function both the wallet and the paymaster must correctly implement signature checks as described in RIP-7560.\ From 88dcbc954480f3bfc9e516fa43b6014838d982d8 Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:03:02 +0100 Subject: [PATCH 03/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 30a088a..7c8570b 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -50,7 +50,7 @@ This method is also a native AA equivalent to the `eth_estimateUserOperationGas` For validation frames, only valid calls to an appropriate `AA_ENTRY_POINT` callback, such as `acceptAccount`, `acceptPaymaster`, `sigFailAccount` and `sigFailPaymaster`, are considered a success. -Note that in order for `eth_esimateGasAA` to function both the wallet and the paymaster must correctly +Note, that in order for `eth_esimateGasAA` to function, both the wallet and the paymaster must correctly implement signature checks as described in RIP-7560.\ Most notably, the fields `senderValidationData` and `paymasterData` usually contain signatures for the transaction and therefore cannot be known before the transaction preparation is complete.\ From 860e3a475023181116c1ff5fee64093e6b02b921 Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:03:13 +0100 Subject: [PATCH 04/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 7c8570b..e03aae2 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -59,8 +59,7 @@ as described in the [Suggested Paymaster Flow](#suggested-paymaster-flow) sectio Once a signature verification over the **stub data** fails, the validation code must not revert or finish execution, but instead proceed as usual until making a `sigFailAccount` or `sigFailPaymaster` call accordingly.\ -A contract that does not implement RIP-7560 will cause `eth_esimateGasAA` to provide inconsistent results -and will risk sporadically reverting on out-of-gas errors on-chain. +A contract that does not provide proper gas estimation capability, such as described above, may cause `eth_esimateGasAA` to provide inconsistent results and risks incorrect reverts of validation frames, thus making the transaction invalid. The `eth_esimateGasAA` API optionally accepts the `State Override Set` object to allow users to modify the state during the gas estimation. From 0151f6660856455a890ef4f6d167732f3e23e918 Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:03:42 +0100 Subject: [PATCH 05/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index e03aae2..533f98e 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -65,7 +65,7 @@ The `eth_esimateGasAA` API optionally accepts the `State Override Set` object to the state during the gas estimation. This field as well as its behavior is equivalent to the ones defined for the `eth_call` RPC method. -If it fails to find such a value, returns an error message with the detailed description of the failure reason. +If it fails to find correct gas limit values for any of the frames, returns an error message with the detailed description of the failure reason. Parameters: From 5077128b9130131f2bf8e9f92b4e20217bb8389e Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:10:29 +0100 Subject: [PATCH 06/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 533f98e..9c02c37 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -146,7 +146,7 @@ Example: ### eth_callAA -Execute the AA transaction in memory without broadcasting it to the mempool or commiting it to the blockchain. +Execute the AA transaction in memory without broadcasting it to the mempool or committing it to the blockchain. An equivalent to the legacy Ethereum `eth_call` RPC API method. Inputs are equivalent to the ones defined for the [eth_estimateGasAA](#eth_estimategasaa) method. From fbfe42e5d289512366cbe3c974963b4a4333b30e Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:10:37 +0100 Subject: [PATCH 07/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 9c02c37..d4a67a4 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -185,7 +185,7 @@ Example: "returnData": "0xdeadbeef", "gasUsed": "0x1a14b", "status": "0x1", - "sigFail": "0x1", + "sigFailAccount": "0x1", "sigFailPaymaster": "0x1", "logs": [ { From 8e080ff9e8f4c9e4dccbf7612335513fdd65b081 Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:10:43 +0100 Subject: [PATCH 08/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index d4a67a4..713ab7f 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -174,7 +174,7 @@ Returns: - **returnData** - DATA - the return value of the `sender` execution frame - **gasUsed** - QUANTITY - the total amount of gas used by the transaction -- **sigFail** - QUANTITY - whether account called "sigFailAccount" or not +- **sigFailAccount** - QUANTITY - whether account called "sigFailAccount" or not - **sigFailPaymaster** - QUANTITY - whether paymaster called "sigFailPaymaster" or not - **status** - QUANTITY - whether the execution phase including the `paymasterPostOp` completed successfully - **logs** - ARRAY - an array of the event logs emitted during the transaction From 70360ef12baf9578af2f3429f81cb54412296472 Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:12:56 +0100 Subject: [PATCH 09/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 713ab7f..01ab6bf 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -207,7 +207,8 @@ Example: } ``` -### wallet_prepareTransactionAA +### Suggested wallet flow +The wallet should expose `wallet_prepareTransactionAA` or an equivalent API, to be called by dApps communicating with the wallet. The `wallet_prepareTransactionAA` API is meant to be implemented by the wallet application, and not the L2 client RPC node provider. From 18e99c06a18ff7ab5466945ba9265f70307985bb Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:15:54 +0100 Subject: [PATCH 10/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 01ab6bf..093a3ee 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -274,7 +274,7 @@ Error codes: ### New methods instead of modification for existing ones While the `eth_esimateGasAA` and `eth_callAA` methods are simply RIP-7560 extensions of the existing -`eth_esimateGasAA` and `eth_call` methods accordingly, +`eth_esimateGas` and `eth_call` methods accordingly, the type of the return values for the existing methods does not match the needs of the Native Account Abstraction API. The approach of creating a new set of methods is cleaner in the long term as these methods may be used later in the From 31bde52266a2a7a1ec10acfc0085548ea8c950cb Mon Sep 17 00:00:00 2001 From: Alex Forshtat Date: Thu, 30 Jan 2025 20:17:23 +0100 Subject: [PATCH 11/11] Update RIPS/rip-0000.md Co-authored-by: shahafn --- RIPS/rip-0000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RIPS/rip-0000.md b/RIPS/rip-0000.md index 093a3ee..445ac4d 100644 --- a/RIPS/rip-0000.md +++ b/RIPS/rip-0000.md @@ -167,7 +167,7 @@ If any of the validation or execution frames reverts, returns an error object co Inputs: 1. OBJECT - The RIP-7560 transaction object. - The `authorizationData` field is optional. + The `senderValidationData` field is optional. 2. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized" Returns: