# JSON-RPC API for verifying paymasters

This document proposes a standard interface for ERC-4337 paymasters that require an off-chain service to recieve and approve UserOperations from any source.

## Background

The ERC-4337 standard for account abstraction introduces the concept of a paymaster. This is any entity that is able to sponsor the gas cost of a UserOperation if it meets certain conditions.

One interesting use case this enables is the concept of a [verifying paymaster](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/samples/VerifyingPaymaster.sol). In this case, the on-chain paymaster will sponsor all UserOperations that have been externally signed by a trusted private key.

In practice this allows for systems where gas can be abstracted to other forms of off-chain payment methods such as credit card and subscription services.

In an ecosystem of smart contract accounts, we could also expect a diversity of paymaster services that any ERC-4337 account can interact with. To promote maximum composibility, we propose all verifying paymasters to expose a standard interface for recieving and sponsoring UserOperations.

## RPC methods

`pm` is the paymaster namespace. The implementation of each RPC method is left up to individual paymasters.

### `pm_sponsorUserOperation`

This methods sends a UserOperation to a paymaster for off-chain verification. If approved, it will return the `paymasterAndData` and updated gas values which can be appended to the UserOperation before signing.

If the paymaster rejects the UserOperation it should not return a result but a standard JSON-RPC error with the reason.

**Parameters (in order):**

- **partial UserOperation**: This is a UserOperation with a dummy `signature`.
- **entryPoint**: The EntryPoint address that the UserOperation is intended for.
- **context (optional)**: This argument is saved for arbitrary data that may be required for specific paymaster implementations.

#### Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "pm_sponsorUserOperation",
  "params": [
    {
      sender, // address
      nonce, // uint256
      initCode, // bytes
      callData, // bytes
      callGasLimit, // uint256
      verificationGasLimit, // uint256
      preVerificationGas, // uint256
      maxFeePerGas, // uint256
      maxPriorityFeePerGas, // uint256
      paymasterAndData, // bytes
      signature, // Can be a valid dummy value
    },
    "0x0576a174D229E3cFA37253523E645A78A0C91B57",
    { /* PM specific data here... */ }
  ]
}

#### Response (success)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
      "paymasterAndData": "0x1234...5678",
      "preVerificationGas": "0x...",
      "verificationGasLimit": "0x...",
      "callGasLimit": "0x...",
  }
}

#### Response (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "message": "Error reason here.",
    "code": -32601
  }
}

### `pm_accounts`

This method allows clients to get all the paymaster addresses associated with an EntryPoint that's owned by this service. The first address in the returned array is the preferred paymaster contract.

This is useful for usecases where a client application is required to know the paymaster address to create certain transactions like an ERC-20 approve.

#### Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "pm_accounts",
  "params": [
      entryPoint // string
  ]
}

#### Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "0x..."
  ]
}