ERC-7677 Paymaster web service integration standard (Paymaster Web Service Capability)
Review · Accounts & wallets · created 2024-04-03
Lets an app hand a wallet the web address of a paymaster (a fee-sponsoring service) and have the wallet communicate with that service in a standardized way, enabling the creation of transactions where the app pays the user's transaction fees on their behalf.
Why it is needed
In account abstraction (ERC-4337) wallets, a separate entity called a paymaster can pay transaction fees on a user's behalf, and paymasters are usually run as web services. Before this standard, however, there was no way for an app to tell a wallet which specific paymaster web service to talk to, and no fixed format for how the wallet and that service should exchange data. The loosely used pm_sponsorUserOperation method that existed before this had gas estimation that varied by service, and estimates were sometimes inconsistent or insufficient. As a result, even when app developers wanted to cover users' fees, there was no common channel linking the wallet and the paymaster service, making sponsored transactions hard to implement.
What to implement
pm_getPaymasterStubData: Takes an unsigned user operation, entry point address, chain ID, and context, and returns paymaster-related stub values to use for gas estimation. It can also return sponsor information and an isFinal flag.pm_getPaymasterData: Takes the same parameters and returns the final paymaster field values actually used when submitting to the bundler.
In depth
Two-stage RPC: stub values and final values
The paymaster web service implements two JSON-RPC methods. pm_getPaymasterStubData takes an unsigned user operation, entry point address, chain ID, and a context object, and returns stub values for gas estimation. With entry point v0.7, it MAY return paymaster-specific gas values such as paymasterVerificationGasLimit, and MUST return paymasterPostOpGasLimit. This is because postOp gas is a cost borne by the paymaster, so the wallet's own estimate cannot be trusted. The wallet SHOULD use these values when having the bundler estimate gas. The service SHOULD validate the user operation it receives at this stage and reject it here if it will not be sponsored. pm_getPaymasterData takes parameters of the same shape and returns the final values to be used for actual submission. Neither method includes a signature in the user operation parameter, because the user signs only after all other fields have been filled in.
Entry point version detection and isFinal
The service MUST detect which entry point version the account uses and return the matching fields: a single paymasterAndData for v0.6, or separate paymaster and paymasterData for v0.7. There are cases, such as when paymasterData contains no signature, where the pm_getPaymasterStubData call alone produces valid paymaster fields; in that case the service MAY return isFinal: true so the second call, pm_getPaymasterData, can be skipped.
The sponsor object and icon display rules
pm_getPaymasterStubData MAY return a sponsor object identifying who is sponsoring the transaction. name is the sponsor's name, and icon is an optional URI pointing to an image. The wallet MAY display this information to the user. The icon string MUST be a data URI as defined in RFC-2397, and the image SHOULD ideally be a square with at least 96x96px resolution. Lossless or vector formats such as PNG, WebP, or SVG are recommended so wallets can render them easily. Because SVG can execute JavaScript, wallets MUST render it via an img tag to prevent untrusted code from running.
App-side and wallet-side implementation of the paymasterService capability
The app places paymasterService in the capabilities field of an EIP-5792 wallet_sendCalls call, passing a url and context. context is a free-form object defined by the service provider, for example containing a value like policyId. The wallet MUST indicate support by returning supported: true for paymasterService per chain in the wallet_getCapabilities response, and SHOULD call the provided service and use its values. There can be exceptions, however, such as a wallet that lets the user choose a different paymaster the wallet itself offers. Because a service outage or a different user choice may mean the paymaster the app specified ends up not being used, the app MUST NOT assume that the paymaster it passed is the entity that ultimately pays the fee.
Why gas estimation was left to the wallet
The previous loosely used standard, pm_sponsorUserOperation, returned updated gas values along with the paymaster-related fields. However, gas estimation methods vary by service provider, so the resulting estimates differed and were sometimes insufficient. This standard therefore leaves gas estimation to the wallet, since the wallet has more context, such as which bundler the user operation will be submitted through. The structure is for the wallet to request sponsorship from the service based on its own estimate. However, because bundlers tend to underestimate paymaster-specific gas values, this standard lets the paymaster service, which knows its own costs best, return that value directly in pm_getPaymasterStubData.
Why a chain ID parameter was included
Paymaster service providers have so far generally issued a separate URL per chain, and multichain URLs have not been common. Even so, the wallet needs some way to convey which chain a request is for. The two options were to standardize the existing practice of one URL per chain, or to require a chain ID parameter in the request, and this standard judged the latter to be the better abstraction. This way, providers who want to can offer a multichain URL, while providers using per-chain URLs can simply ignore the extra parameter, at little cost either way. App developers using a provider with per-chain URLs only need to change the URL when sending to a different chain.
Constraints the stub data must satisfy
preVerificationGas depends heavily on the user operation's size and the ratio of zero bytes to non-zero bytes. If the preVerificationGas estimated from stub values is lower than what the final values actually require, the bundler returns a preVerificationGas too low error from eth_sendUserOperation. To prevent this, the service MUST return a stub that matches the final data in length and whose number of zero bytes (0x00) does not exceed that of the final data. There is also a pitfall in code paths. A naive stub that repeats 0x01 can fail simulation, and even a valid stub can cause an underestimated gas limit and a post-submission out of gas error if validatePaymasterUserOp or postOp takes a different code path than the final values, for example by returning early. The stub MUST therefore produce a simulation that follows the same code path as the final user operation.
Prerequisite standards and proposal status
This standard rests on two foundations. The fee-sponsorship structure called the paymaster is itself defined by ERC-4337, and the framework by which apps and wallets exchange support for advanced capabilities is defined by EIP-5792. ERC-7677 adds one new wallet capability (paymasterService) on top of these, along with the standard web service interface for paymasters that underlies it. The source status is Review, meaning it is a proposal that has not yet been finalized and whose specification may still change.
Things to watch out for
- API key exposure in paymaster URLs: URLs that paymaster service providers give to app developers commonly contain an API key. Passing this URL directly to the wallet would leak the key, so the recommended approach is to give the wallet the app's backend URL and have the backend proxy calls to the paymaster service. This way the key can be kept secret, and the backend can also perform additional simulation and verification to sponsor only the transactions it wants to sponsor.