Document Infura Bundler support (MetaMask#2183)

* Document bundler methods.

Signed-off-by: bgravenorst <[email protected]>

* Add costing to lib file.

Signed-off-by: bgravenorst <[email protected]>

* Remove redundent files.

Signed-off-by: bgravenorst <[email protected]>

* Fix incorrect method name.

Signed-off-by: bgravenorst <[email protected]>

* Add error codes.

Signed-off-by: bgravenorst <[email protected]>

* Added v6 methods.

Signed-off-by: bgravenorst <[email protected]>

* Fix tip.

Signed-off-by: bgravenorst <[email protected]>

* Add calldata.

Signed-off-by: bgravenorst <[email protected]>

* Apply suggestions from code review

Co-authored-by: Alexandra Carrillo <[email protected]>

* Add additional methods and update pricing.

Signed-off-by: bgravenorst <[email protected]>

* Add additional methods.

Signed-off-by: bgravenorst <[email protected]>

* Remove pm methods added earlier.

Signed-off-by: bgravenorst <[email protected]>

* Add bundler support to multiple networks.

Signed-off-by: bgravenorst <[email protected]>

* Update services/concepts/bundler.md

Co-authored-by: Alexandra Carrillo <[email protected]>

---------

Signed-off-by: bgravenorst <[email protected]>
Co-authored-by: Alexandra Carrillo <[email protected]>
Co-authored-by: Yashovardhan Agrawal <[email protected]>

Author: 3 people

services/concepts/bundler.md

@@ -0,0 +1,96 @@
+---
+description: Infura supports ERC-4337 bundler methods.
+sidebar_label: Bundler methods
+---
+
+# Bundler methods (ERC-4337)
+
+Infura supports [ERC-4337](https://docs.erc4337.io/) bundler JSON-RPC methods that enable you to build
+account abstraction (AA) experiences like gas sponsorship (paymasters), ERC-20 gas payment, session keys, or
+batched actions using smart accounts.
+
+If your dapp or wallet uses smart accounts, use the bundler JSON-RPC methods. If you use externally
+owned accounts (EOAs) only, use standard Ethereum JSON-RPC methods.
+
+:::info
+AA moves validation and fee-payment logic into smart contracts. Instead of sending raw transactions
+from an EOA, clients submit [user operations (UserOps)](#user-operations) to a bundler. The
+bundler collects and simulates these operations, then executes them through a
+[shared coordination contract (EntryPoint)](#entrypoint-contracts) on the network.
+
+Smart accounts are smart contract-based wallets that serve as the foundation of AA. They embed custom
+logic for authentication, authorization, network fee payment, nonce management and execution.
+:::
+
+:::info
+Refer to the [official Pimlico documentation](https://docs.pimlico.io/references/bundler)
+for more about the bundler methods and
+[EntryPoint errors](https://docs.pimlico.io/references/bundler/entrypoint-errors#entrypoint-errors).
+:::
+
+## User operations
+
+A user operation (UserOp) is an is an off-chain request that a bundler later includes onchain by
+calling the EntryPoint. UserOps go to a dedicated mempool watched by bundlers instead of being broadcast
+as raw L1/L2 transactions.
+
+## EntryPoint contract
+
+The EntryPoint contract is the shared coordination contract defined by ERC-4337. Bundlers call them to
+validate and execute user operations (UserOps) from smart accounts. At a high level, an EntryPoint:
+
+- Runs the ERC-4337 validation and execution.
+- Enforces nonce and signature checks exposed by each smart account.
+- Coordinates fee payment (including paymasters).
+- Executes the requested calls onchain.
+
+The bundler supports calling multiple EntryPoint versions (v0.6 and v0.7/v0.8) through the same set
+of RPC methods, allowing it to handle both older and modern smart account schemes.
+
+Use the [`eth_supportedEntryPoints`](../reference/ethereum/json-rpc-methods/bundler/eth_supportedentrypoints)
+method to fetch the EntryPoint addresses supported by the bundler.
+
+## Supported methods
+
+The following bundler methods are available on the [supported networks](#supported-networks):
+
+- [`eth_sendUserOperation`](../reference/ethereum/json-rpc-methods/bundler/eth_senduseroperation.mdx):
+    Submits a user operation to be included onchain.
+- [`eth_estimateUserOperationGas`](../reference/ethereum/json-rpc-methods/bundler/eth_estimateuseroperationgas):
+    Simulates the user operation and estimates the appropriate gas limits.
+- [`eth_getUserOperationReceipt`](../reference/ethereum/json-rpc-methods/bundler/eth_getuseroperationreceipt):
+    Fetches the receipt of a user operation.
+- [`eth_getUserOperationByHash`](../reference/ethereum/json-rpc-methods/bundler/eth_getuseroperationbyhash):
+    Fetches the user operation by hash.
+- [`eth_supportedEntryPoints`](../reference/ethereum/json-rpc-methods/bundler/eth_supportedentrypoints):
+    Fetches the EntryPoint addresses supported by the bundler.
+- [`pimlico_getUserOperationGasPrice`](../reference/ethereum/json-rpc-methods/bundler/pimlico_getuseroperationgasprice):
+    Returns the gas prices that must be used for the user operation.
+- [`pimlico_getUserOperationStatus`](../reference/ethereum/json-rpc-methods/bundler/pimlico_getuseroperationstatus):
+    Returns the user operation status.
+- [`pimlico_simulateAssetChanges`](../reference/ethereum/json-rpc-methods/bundler/pimlico_simulateassetchanges):
+    Simulates a user operation to predict the asset changes it will cause.
+
+## Supported networks
+
+Bundler methods are active on the following networks:
+
+- [Arbitrum](../reference/arbitrum/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [Avalanche](../reference/avalanche-c-chain/json-rpc-methods/bundler/index.md) (mainnet and Fuji)
+- [Base](../reference/base/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [Blast](../reference/blast/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [BNB Smart Chain](../reference/bnb-smart-chain/json-rpc-methods/bundler/index.md) (mainnet and testnet)
+- [Celo](../reference/celo/json-rpc-methods/bundler/index.md) (mainnet and Alfajores)
+- [Ethereum](../reference/ethereum/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [Linea](../reference/linea/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [Mantle](../reference/mantle/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [opBNB](../reference/opbnb/json-rpc-methods/bundler/index.md) (mainnet)
+- [Optimism](../reference/optimism/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [Polygon](../reference/polygon-pos/json-rpc-methods/bundler/index.md) (mainnet and Amoy)
+- [Scroll](../reference/scroll/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+- [Sei](../reference/sei/json-rpc-methods/bundler/index.md) (mainnet and testnet)
+- [Unichain](../reference/unichain/json-rpc-methods/bundler/index.md) (mainnet and Sepolia)
+
+:::info
+[Contact support](https://support.infura.io/) if you require bundler method activation on a network not listed here that’s currently supported by Pimlico.
+:::

services/get-started/pricing/credit-cost.mdx

@@ -46,22 +46,18 @@ a specific network, then use the default Ethereum method's credit cost.
 
 <CreditCostTable methods="evm" />
 
-
 ### Trace methods
 
 <CreditCostTable methods="evm_trace" />
 
-
 ### Filter methods
 
 <CreditCostTable methods="evm_filter" />
 
 ### Debug methods
 
-
 <CreditCostTable methods="evm_debug" />
 
-
 ### Subscription events
 
 You can subscribe and unsubscribe to events using [`eth_subscribe`](../../reference/ethereum/json-rpc-methods/subscription-methods/eth_subscribe.mdx) and [`eth_unsubscribe`](../../reference/ethereum/json-rpc-methods/subscription-methods/eth_unsubscribe.mdx).
@@ -75,7 +71,6 @@ are charged at approximately one second intervals.
 
 <CreditCostTable methods="linea" />
 
-
 ## Polygon
 
 <CreditCostTable methods="polygon" />
@@ -95,3 +90,11 @@ All Solana methods are charged at 160 credits per request.
 ## Gas API
 
 <CreditCostTable methods="gasApi" />
+
+## Bundler API
+
+:::info
+The Bundler API methods are currently only available on Ethereum Mainnet and Sepolia.
+:::
+
+<CreditCostTable methods="bundler" />

services/reference/_partials/bundler/_eth_estimateuseroperationgas-description.mdx

@@ -0,0 +1,13 @@
+import CreditCost from '@site/src/components/CreditCost/CreditCostPrice.js'
+
+Simulates the user operation and estimates the appropriate gas limits. Returns an error if the operation
+is unsuccessful. <CreditCost network="bundler" method="eth_estimateUserOperationGas" />
+
+:::tip
+- You can use `stateOverrides` to estimate the gas cost even if the sender has no funds.
+    However, if the operation is sent onchain when the sender has no balance, it will revert during
+    the call phase due to lack of funds.
+
+- You can include a dummy signature for the `signature` field to estimate the gas cost. For example:
+    `0xfffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c`
+:::

services/reference/_partials/bundler/_eth_estimateuseroperationgas-example.mdx

@@ -0,0 +1 @@
+Replace `<YOUR-API-KEY>` with an API key from your [MetaMask Developer dashboard](https://developer.metamask.io/). 

services/reference/_partials/bundler/_eth_estimateuseroperationgas-parameters.mdx

@@ -0,0 +1,79 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+<Tabs>
+<TabItem value="v0.7" label="v0.7 and v0.8 user operation">
+
+- `userOperation`: The user operation object containing the following fields:
+
+  - `sender`: (string) - The address of the account making the operation.
+  - `nonce`: (string) - Unique identifier for the request from this sender. This includes the key and sequence number.
+  - `factory`: (string) [_optional_] - The factory contract address that will deploy the smart account if it doesn't exist yet.
+  - `factoryData`: (string) [_optional_] - The data passed to the factory contract to deploy the smart account.
+  - `callData`: (string) [_optional_] - The data to pass to the sender during the main execution call.
+  - `callGasLimit`: (string) - The amount of gas to allocate the main execution call.
+  - `verificationGasLimit`: (string) - The amount of gas to allocate for the verification step.
+  - `preVerificationGas`: (string) - The amount of gas to pay for to compensate the bundler for pre-verification execution and `calldata`.
+  - `maxFeePerGas`: (string) - Maximum fee per gas, in wei, the sender is willing to pay per gas.
+  - `maxPriorityFeePerGas`: (string) - Maximum fee, in wei, the sender is willing to pay per gas above the base fee.
+  - `paymaster`: (string) [_optional_] - Address of paymaster sponsoring the transaction, or `null` if none.
+  - `paymasterVerificationGasLimit`: (string) [_optional_] - The amount of gas to allocate for the verification step of the paymaster, or `null` if no paymaster.
+  - `paymasterPostOpGasLimit`: (string) [_optional_] - The amount of gas to allocate for the post-operation step of the paymaster, or `null` if no paymaster.
+  - `paymasterData`: (string) [_optional_] - The data to pass to the paymaster during the verification step, or `null` if no paymaster.
+  - `signature`: (string) - The signature data. For gas estimation, this can be a dummy signature.
+  - `eip7702Auth`: (object) [_optional_] - The EIP-7702 authorization data. This can be a dummy authorization
+      for estimations:
+    - `address`: (string) - The contract address for the authorization.
+    - `chainId`: (string) - The chain ID.
+    - `nonce`: (string) - The nonce.
+    - `r`: (string) - The r component of the signature.
+    - `s`: (string) - The s component of the signature.
+    - `v`: (string) - The v component of the signature.
+    - `yParity`: (string) - The y-parity value.
+
+- `entryPoint`: (string) - The EntryPoint contract address (`0x0000000071727De22E5E9d8BAf0edAc6f37da032`).
+
+- `stateOverrides`: (object) [_optional_] - State overrides to apply for the simulation. Each key is an address, and each value is an object that can contain:
+  - `balance`: (string) [_optional_] - The balance to set for the address.
+  - `nonce`: (string) [_optional_] - The nonce to set for the address.
+  - `code`: (string) [_optional_] - The code to set for the address.
+  - `state`: (object) [_optional_] - Complete state to set, where each key is a 32-byte hex storage slot and each value is a 32-byte hex value.
+  - `stateDiff`: (object) [_optional_] - State differences to apply, where each key is a 32-byte hex storage slot and each value is a 32-byte hex value.
+
+</TabItem>
+<TabItem value="v0.6" label="v0.6 user operation">
+
+- `userOperation`: The user operation object containing the following fields:
+
+  - `sender`: (string) - The address of the account making the operation.
+  - `nonce`: (string) - Unique identifier for the request from this sender.
+  - `initCode`: (string) - The initialization code for the smart account if it doesn't exist yet.
+  - `callData`: (string) [_optional_] - The data to pass to the sender during the main execution call.
+  - `callGasLimit`: (string) - The amount of gas to allocate the main execution call.
+  - `verificationGasLimit`: (string) - The amount of gas to allocate for the verification step.
+  - `preVerificationGas`: (string) - The amount of gas to pay for to compensate the bundler for pre-verification execution and `calldata`.
+  - `maxFeePerGas`: (string) - Maximum fee per gas, in wei, the sender is willing to pay per gas.
+  - `maxPriorityFeePerGas`: (string) - Maximum fee, in wei, the sender is willing to pay per gas above the base fee.
+  - `paymasterAndData`: (string) - The address of the paymaster contract and the data that will be passed to it.
+  - `signature`: (string) - The signature data. For gas estimation, this can be a dummy signature.
+  - `eip7702Auth`: (object) [_optional_] - The EIP-7702 authorization data. This can be a dummy authorization
+      for estimations:
+    - `address`: (string) - The contract address for the authorization.
+    - `chainId`: (string) - The chain ID.
+    - `nonce`: (string) - The nonce.
+    - `r`: (string) - The r component of the signature.
+    - `s`: (string) - The s component of the signature.
+    - `v`: (string) - The v component of the signature.
+    - `yParity`: (string) - The y-parity value.
+
+- `entryPoint`: (string) - The EntryPoint contract address (`0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789`).
+
+- `stateOverrides`: (object) [_optional_] - State overrides to apply for the simulation. Each key is an address, and each value is an object that can contain:
+  - `balance`: (string) [_optional_] - The balance to set for the address.
+  - `nonce`: (string) [_optional_] - The nonce to set for the address.
+  - `code`: (string) [_optional_] - The code to set for the address.
+  - `state`: (object) [_optional_] - Complete state to set, where each key is a 32-byte hex storage slot and each value is a 32-byte hex value.
+  - `stateDiff`: (object) [_optional_] - State differences to apply, where each key is a 32-byte hex storage slot and each value is a 32-byte hex value.
+
+</TabItem>
+</Tabs>

services/reference/_partials/bundler/_eth_estimateuseroperationgas-request.mdx

@@ -0,0 +1,82 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+<Tabs>
+  <TabItem value="curl without an override">
+
+  ```bash
+  curl https://mainnet.infura.io/v3/<YOUR-API-KEY> \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d '{
+      "jsonrpc": "2.0",
+      "method": "eth_estimateUserOperationGas",
+      "params": [
+        {
+          "sender": "0x5a6b47F4131bf1feAFA56A05573314BcF44C9149",
+          "nonce": "0x845adb2c711129d4f3966735ed98a9f09fc4ce5700000000000000000000",
+          "factory": "0xd703aaE79538628d27099B8c4f621bE4CCd142d5",
+          "factoryData": "0xc5265d5d000000000000000000000000aac5d4240af87249b3f71bc8e4a2cae074a3e419",
+          "callData": "0xe9ae5c5300000000000000000000000000000000000000000000000000000000000000000000000000",
+          "callGasLimit": "0x0",
+          "verificationGasLimit": "0x0",
+          "preVerificationGas": "0x0",
+          "maxFeePerGas": "0x7a5cf70d5",
+          "maxPriorityFeePerGas": "0x3b9aca00",
+          "paymaster": null,
+          "paymasterVerificationGasLimit": null,
+          "paymasterPostOpGasLimit": null,
+          "paymasterData": null,
+          "signature": "0xfffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c"
+        },
+        "0x0000000071727De22E5E9d8BAf0edAc6f37da032"
+      ],
+      "id": 1
+    }'
+  ```
+
+  </TabItem>
+  <TabItem value="curl with an override">
+
+  ```bash
+  curl https://mainnet.infura.io/v3/<YOUR-API-KEY> \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d '{
+      "jsonrpc": "2.0",
+      "method": "eth_estimateUserOperationGas",
+      "params": [
+        {
+          "sender": "0xa203fDb8bC335F86016F635b85389B62B189E417",
+          "nonce": "0x35bf2a054f92f3730b87582ef223c8d663f9eb01158154750000000000000000",
+          "factory": "0xd703aaE79538628d27099B8c4f621bE4CCd142d5",
+          "callData": "0xb61d27f6000000000000000000000000530fff22987e137e7c8d2adcc4c15eb45b4fa752",
+          "callGasLimit": "0x0",
+          "verificationGasLimit": "0x0",
+          "preVerificationGas": "0x0",
+          "maxPriorityFeePerGas": "0x12a05f200",
+          "maxFeePerGas": "0x5b08082fa",
+          "paymaster": null,
+          "paymasterVerificationGasLimit": null,
+          "paymasterPostOpGasLimit": null,
+          "paymasterData": null,
+          "signature": "0xa6cc6589c8bd561cfd68d7b6b0757ef6f208e7438782939938498eee7d703260137856c840c491b3d415956265e81bf5c2184a725be2abfc365f7536b6af525e1c"
+        },
+        "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
+        {
+          "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": {
+            "balance": "0xde0b6b3a7640000"
+          },
+          "0xebe8efa441b9302a0d7eaecc277c09d20d684540": {
+            "stateDiff": {
+              "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80": "0x21"
+            }
+          }
+        }
+      ],
+      "id": 1
+    }'
+  ```
+
+  </TabItem>
+</Tabs> 

services/reference/_partials/bundler/_eth_estimateuseroperationgas-response.mdx

@@ -0,0 +1,22 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```JSON
+  {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {
+      "preVerificationGas": "0xd3e3",
+      "verificationGasLimit": "0x60b01",
+      "callGasLimit": "0x13880",
+      "paymasterVerificationGasLimit": "0x0",
+      "paymasterPostOpGasLimit": "0x0"
+    }
+  }
+  ```
+
+  </TabItem>
+</Tabs> 

services/reference/_partials/bundler/_eth_estimateuseroperationgas-returns.mdx

@@ -0,0 +1,30 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+**Type:** `Object`
+
+An object containing the estimated gas values for the user operation.
+
+<Tabs>
+<TabItem value="v0.7" label="v0.7 and v0.8">
+
+- `preVerificationGas`: (string) - The amount of gas to pay for to compensate the bundler for
+    pre-verification execution and `calldata`.
+- `verificationGasLimit`: (string) - The amount of gas to allocate for the verification step.
+- `callGasLimit`: (string) - The amount of gas to allocate the main execution call.
+- `paymasterVerificationGasLimit`: (string) - The amount of gas to allocate for the verification step
+    of the paymaster, or `null` if no paymaster.
+- `paymasterPostOpGasLimit`: (string) - The amount of gas to allocate for the post-operation step of
+    the paymaster, or `null` if no paymaster.
+
+</TabItem>
+<TabItem value="v0.6" label="v0.6">
+
+- `preVerificationGas`: (string) - The amount of gas to pay for to compensate the bundler for
+    pre-verification execution and `calldata`.
+- `verificationGas`: (string) - The amount of gas used for verification (legacy field from v0.6).
+- `verificationGasLimit`: (string) - The amount of gas to allocate for the verification step.
+- `callGasLimit`: (string) - The amount of gas to allocate the main execution call.
+
+</TabItem>
+</Tabs>

services/reference/_partials/bundler/_eth_getuseroperationbyhash-description.mdx

@@ -0,0 +1,4 @@
+import CreditCost from '@site/src/components/CreditCost/CreditCostPrice.js'
+
+Fetches user operation details by providing its hash. If the user operation is not available, it
+will return `null`. <CreditCost network="bundler" method="eth_getUserOperationByHash" />

services/reference/_partials/bundler/_eth_getuseroperationbyhash-example.mdx

@@ -0,0 +1 @@
+Replace `<YOUR-API-KEY>` with an API key from your [MetaMask Developer dashboard](https://developer.metamask.io/).