With the introduction of Account Abstraction as it is defined by RIP-7560 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.
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.
This document defines the API that the RIP-7560 compatible Ethereum nodes provide to the Smart Wallet applications.
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 UserOperations as defined in
ERC-7769.
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
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 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 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.
This field as well as its behavior is equivalent to the ones defined for the eth_call RPC method.
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:
validationGasLimit, paymasterValidationGasLimit, paymasterGasLimit and callGasLimit fields are optional.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:
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:
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 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:
senderValidationData field is optional.Returns:
sender execution framepaymasterPostOp completed successfullyExample:
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.
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.
The Paymaster service should expose the pm_getPaymasterStubData and pm_getPaymasterData APIs as defined by the
ERC-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.
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.
Error format:
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.
While the eth_esimateGasAA and eth_callAA methods are simply RIP-7560 extensions of the existing
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 EOF-based Native Account Abstraction as described in EIP-7701.
eth_callAA returned data formatThe 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.
The added methods are not interfering with any existing code and should pose no backwards compatibility issues.
As mentioned in the 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 and related rights waived via CC0.