Skip to content

Remove deprecated bundle stats API methods #638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
odysseus0 merged 1 commit into from
Nov 12, 2025
+16 −318
Merged

Remove deprecated bundle stats API methods #638

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions docs/flashbots-auction/advanced/gas-fee-refunds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,6 @@ Searchers can also use `mev_sendBundle` to multiplex bundles if they prefer. Thi

_Note: Smart multiplexing has a 1% rate of false positives, meaning that in 1% of MEV-Boost blocks there is a risk that searcher bundles will not be landed._

### Bundle stats for multiplexed bundles

To view bundle stats on multiplexed `eth_sendBundle` requests, use the `flashbots_getSbundleStats` API. You will see a new "smart" field in the response to multiplexed `eth_sendBundle` which indicates that the sbundle stats endpoint should be used.

## How are refunds calculated

BuilderNet uses a refund rule to retroactively calculate refunds for all bundles landed in its blocks. For more information, see the [BuilderNet docs](https://buildernet.org/docs/refunds).
Expand Down
2 changes: 0 additions & 2 deletions docs/flashbots-auction/advanced/reputation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,6 @@ $\Delta_{coinbase_T}$: coinbase difference from direct payment in transaction $T

Flashbots uses a dynamic threshold to classify users between the high reputation and low reputation queue. The dynamic variables are: 1) the historical time period considered to calculate reputation, 2) the cutoff reputation score which classifies a searcher as "high reputation". Using a dynamic threshold allows the builder to adapt in periods of high demand and maintain high reliability for top searchers.

A searcher can query their current reputation status using the [`flashbots_getUserStatsV2` RPC method](/flashbots-auction/advanced/rpc-endpoint#flashbots_getuserstatsv2).

## Building reputation

Searcher reputation is associated with the signing key used to authenticate with Flashbots. That is, the ethereum address associated with the `X-Flashbots-Signature` field of your bundle submission.
Expand Down
301 changes: 1 addition & 300 deletions docs/flashbots-auction/advanced/rpc-endpoint.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ example response:
}
```

If `builders` are specified, the response will include an additional `smart` field. Use the `flashbots_getSbundleStats` API to look up stats for smart bundles.
If `builders` are specified, the response will include an additional `smart` field.

example with `builders`:

Expand Down Expand Up @@ -536,305 +536,6 @@ example response:
}
```

### flashbots_getUserStats

:::caution

flashbots_getUserStats will be deprecated soon, use [flashbots_getUserStatsV2](/flashbots-auction/advanced/rpc-endpoint#flashbots_getuserstatsv2)

:::

The `flashbots_getUserStats` JSON-RPC method returns a quick summary of how a searcher is performing in the Flashbots ecosystem, including their [reputation-based priority](/flashbots-auction/advanced/reputation). It is currently updated once every hour and has the following payload format:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "flashbots_getUserStats",
"params": [
blockNumber, // String, a hex encoded recent block number, in order to prevent replay attacks. Must be within 20 blocks of the current chain tip.
]
}
```

example response:

```json
{
"is_high_priority": true,
"all_time_miner_payments": "1280749594841588639",
"all_time_gas_simulated": "30049470846",
"last_7d_miner_payments": "1280749594841588639",
"last_7d_gas_simulated": "30049470846",
"last_1d_miner_payments": "142305510537954293",
"last_1d_gas_simulated": "2731770076"
}
```

where

- `is_high_priority`: boolean representing if this searcher has a high enough reputation to be in the high priority queue
- `all_time_miner_payments`: the total amount paid to validators over all time
- `all_time_gas_simulated`: the total amount of gas simulated across all bundles submitted to Flashbots. This is the actual gas used in simulations, not gas limit

:::note

Parameters with `miner` in the name are retrofitted with Flashbots block builder data to maintain backwards compatibility. This nomenclature will be changed in a future release to accurately reflect PoS Ethereum architecture.

:::

### flashbots_getBundleStats

:::caution

flashbots_getBundleStats will be deprecated soon, use [flashbots_getBundleStatsV2](/flashbots-auction/advanced/rpc-endpoint#flashbots_getbundlestatsv2)

:::

The `flashbots_getBundleStats` JSON-RPC method returns stats for a single bundle. You must provide a blockNumber and the bundleHash, and the signing address must be the same as the one who submitted the bundle.

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "flashbots_getBundleStats",
"params": [
{
bundleHash, // String, returned by the flashbots api when calling eth_sendBundle
blockNumber, // String, the block number the bundle was targeting (hex encoded)
}
]
}
```

example response:

```json
{
"isSimulated": true,
"isSentToMiners": true,
"isHighPriority": true,
"simulatedAt": "2021-08-06T21:36:06.317Z",
"submittedAt": "2021-08-06T21:36:06.250Z",
"sentToMinersAt": "2021-08-06T21:36:06.343Z",
"receivedAt": "2022-10-06T21:36:06.250Z", // Added for POS, will be included as part of V2
"consideredByBuildersAt": [
{
"pubkey": "0x81babeec8c9f2bb9c329fd8a3b176032fe0ab5f3b92a3f44d4575a231c7bd9c31d10b6328ef68ed1e8c02a3dbc8e80f9",
"timestamp": "2022-10-06T21:36:06.343Z"
},
{
"pubkey": "0x81beef03aafd3dd33ffd7deb337407142c80fea2690e5b3190cfc01bde5753f28982a7857c96172a75a234cb7bcb994f",
"timestamp": "2022-10-06T21:36:06.394Z"
},
{
"pubkey": "0xa1dead1e65f0a0eee7b5170223f20c8f0cbf122eac3324d61afbdb33a8885ff8cab2ef514ac2c7698ae0d6289ef27fc",
"timestamp": "2022-10-06T21:36:06.322Z"
}
], // Added for POS, will be included as part of V2
"sealedByBuildersAt": [
{
"pubkey": "0x81beef03aafd3dd33ffd7deb337407142c80fea2690e5b3190cfc01bde5753f28982a7857c96172a75a234cb7bcb994f",
"timestamp": "2022-10-06T21:36:07.742Z"
}
] // Added for POS, will be included as part of V2
}
```

### flashbots_getUserStatsV2

The `flashbots_getUserStatsV2` JSON-RPC method returns a quick summary of how a searcher is performing in the Flashbots ecosystem, including their [reputation-based priority](/flashbots-auction/advanced/reputation). It is currently updated once every hour and has the following payload format:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "flashbots_getUserStatsV2",
"params": [
{
blockNumber // String, a hex encoded recent block number, in order to prevent replay attacks. Must be within 20 blocks of the current chain tip.
}
]
}
```

example response:

```json
{
"isHighPriority": true,
"allTimeValidatorPayments": "1280749594841588639",
"allTimeGasSimulated": "30049470846",
"last7dValidatorPayments": "1280749594841588639",
"last7dGasSimulated": "30049470846",
"last1dValidatorPayments": "142305510537954293",
"last1dGasSimulated": "2731770076"
}
```

where

- `isHighPriority`: boolean representing if this searcher has a high enough reputation to be in the high priority queue
- `allTimeValidatorPayments`: the total amount paid to validators over all time
- `allTimeGasSimulated`: the total amount of gas simulated across all bundles submitted to Flashbots. This is the actual gas used in simulations, not gas limit

### flashbots_getBundleStatsV2

The `flashbots_getBundleStatsV2` JSON-RPC method returns stats for a single bundle. You must provide a blockNumber and the bundleHash, and the signing address must be the same as the one who submitted the bundle.

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "flashbots_getBundleStatsV2",
"params": [
{
bundleHash, // String, returned by the flashbots api when calling eth_sendBundle
blockNumber, // String, the block number the bundle was targeting (hex encoded)
}
]
}
```

example response when bundle relay has simulated the bundle and the target block has been reached:

```json
{
"isHighPriority": true,
"isSimulated": true,
"simulatedAt": "2022-10-06T21:36:06.317Z",
"receivedAt": "2022-10-06T21:36:06.250Z",
"consideredByBuildersAt": [
{
"pubkey": "0x81babeec8c9f2bb9c329fd8a3b176032fe0ab5f3b92a3f44d4575a231c7bd9c31d10b6328ef68ed1e8c02a3dbc8e80f9",
"timestamp": "2022-10-06T21:36:06.343Z"
},
{
"pubkey": "0x81beef03aafd3dd33ffd7deb337407142c80fea2690e5b3190cfc01bde5753f28982a7857c96172a75a234cb7bcb994f",
"timestamp": "2022-10-06T21:36:06.394Z"
},
{
"pubkey": "0xa1dead1e65f0a0eee7b5170223f20c8f0cbf122eac3324d61afbdb33a8885ff8cab2ef514ac2c7698ae0d6289ef27fc",
"timestamp": "2022-10-06T21:36:06.322Z"
}
],
"sealedByBuildersAt": [
{
"pubkey": "0x81beef03aafd3dd33ffd7deb337407142c80fea2690e5b3190cfc01bde5753f28982a7857c96172a75a234cb7bcb994f",
"timestamp": "2022-10-06T21:36:07.742Z"
}
]
}
```

when relay has not seen the bundle yet:

```json
{
"isSimulated": false,
}
```

when relay has seen the bundle but has yet to simulate it:

```json
{
"isSimulated": false,
"isHighPriority": true,
"receivedAt": "2022-10-06T21:36:06.250Z",
}
```

when relay has simulated the bundle but the target block has not been reached:

```json
{
"isSimulated": true,
"isHighPriority": true,
"simulatedAt": "2022-10-06T21:36:06.317Z",
"receivedAt": "2022-10-06T21:36:06.250Z"
}
```

where

- `isHighPriority`: boolean representing if this searcher has a high enough reputation to be in the high priority queue
- `isSimulated`: boolean representing whether the bundle gets simulated. All other fields will be omitted except simulated field if API didn't receive bundle
- `simulatedAt`: time at which the bundle gets simulated
- `receivedAt`: time at which the bundle API received the bundle
- `consideredByBuildersAt`: indicates time at which each builder selected the bundle to be included in the target block
- `sealedByBuildersAt`: indicates time at which each builder sealed a block containing the bundle

### flashbots_getSbundleStats

The `flashbots_getSbundleStats` JSON-RPC method returns stats for a single [sbundle](/flashbots-mev-share/searchers/understanding-bundles). You must provide `bundleHash`, and the signing address must be the same as the one who submitted the bundle.
Only bundles that do not contain user's private transactions are supported (so no backrun bundles)

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "flashbots_getSbundleStats",
"params": [
{
bundleHash, // String, returned by the flashbots api when calling eth_sendBundle with builders field or mev_sendBundle
}
]
}
```

example response when bundle relay has simulated the bundle and the target block has been reached:

```json
{
"isHighPriority": true,
"isSimulated": true,
"simulatedAt": "2022-10-06T21:36:06.317Z",
"receivedAt": "2022-10-06T21:36:06.250Z",
"consideredByBuildersAt": [
{
"pubkey": "0x81babeec8c9f2bb9c329fd8a3b176032fe0ab5f3b92a3f44d4575a231c7bd9c31d10b6328ef68ed1e8c02a3dbc8e80f9",
"timestamp": "2022-10-06T21:36:06.343Z"
},
{
"pubkey": "0x81beef03aafd3dd33ffd7deb337407142c80fea2690e5b3190cfc01bde5753f28982a7857c96172a75a234cb7bcb994f",
"timestamp": "2022-10-06T21:36:06.394Z"
},
{
"pubkey": "0xa1dead1e65f0a0eee7b5170223f20c8f0cbf122eac3324d61afbdb33a8885ff8cab2ef514ac2c7698ae0d6289ef27fc",
"timestamp": "2022-10-06T21:36:06.322Z"
}
],
"sealedByBuildersAt": [
{
"pubkey": "0x81beef03aafd3dd33ffd7deb337407142c80fea2690e5b3190cfc01bde5753f28982a7857c96172a75a234cb7bcb994f",
"timestamp": "2022-10-06T21:36:07.742Z"
}
]
}
```

Only responds with success when sbundle is already simulated.

When bundle-relay has simulated the bundle but the target block (or maxBlock) has not been reached:

```json
{
"isSimulated": true,
"isHighPriority": true,
"simulatedAt": "2022-10-06T21:36:06.317Z",
"receivedAt": "2022-10-06T21:36:06.250Z"
}
```

where

- `isSimulated`: boolean representing whether the bundle gets simulated. All other fields will be omitted except simulated field if API didn't receive bundle
- `simulatedAt`: time at which the bundle gets simulated
- `receivedAt`: time at which the bundle API received the bundle
- `consideredByBuildersAt`: indicates time at which each builder selected the bundle to be included in the target block
- `sealedByBuildersAt`: indicates time at which each builder sealed a block containing the bundle

### flashbots_getFeeRefundTotalsByRecipient

The `flashbots_getFeeRefundTotalsByRecipient` JSON-RPC method returns the total amount of fee refunds that have been earned by a specific address. Our refund process calculates these values weekly.
Expand Down
Loading