Add docs for gas fee refunds (#555)

* Add docs for gas fee refunds

* Add multiplexing and bundle stats instructions

* Explain smart bundles

* Correct prefix from eth to flashbots

* Add refund rule

* Specify API users and update description of refund API

* Fix build errors caused by link issues

---------

Co-authored-by: George Zhang <georgezhangtj97@gmail.com>

Author: sketsdever

docs/flashbots-auction/advanced/gas-fee-refunds.md

@@ -0,0 +1,104 @@
+---
+title: Gas Fee Refunds
+---
+
+## Introduction
+
+Searchers and private transaction API users are automatically eligible to receive gas fee refunds. If Flashbots can include a bundle on chain for a lower price, you are eligible to receive a refund.
+
+Gas fee refunds do not change how bundles are executed and searchers do not need to make any changes to be eligible for them.
+
+## Where do refunds come from
+
+Gas fee refunds include both priority fees and coinbase transfers.
+
+In an optimal case, searchers are refunded the difference between their bid and the bid of the next-best bundle or transaction targeting the same state. Ie. the refund effectively results in the searcher paying the second price. In practice, searchers will receive some fraction of this amount depending on how much profit the Flashbots builder makes.
+
+## Which bundles receive refunds
+
+Flashbots provides refunds for bundles in blocks landed by the Flashbots block builder. Whether a bundle receives a refund depends on a few factors that vary from block to block:
+* How much network congestion and competition there was
+* Whether the Flashbots builder made a profit and how much
+* How much the specific bundle contributed to the value of the block
+* If the bundle was sent directly to Flashbots, or shared with other block builders by the searcher
+
+## How to maximize both refunds and speed
+
+Transactions which are sent directly to the Flashbots Builder via the Bundle Relay, and not multiplexed _by the searcher_ to other block builders, are likely to receive higher refunds. This is because they increase the profit of the Flashbots builder which is used to provide refunds.
+
+The Flashbots block builder does not land 100% of blocks. In order to land bundles in all blocks, searchers can ask Flashbots to share their bundles with other block builders in cases where the Flashbots builder does not win a block. Flashbots will automatically share with all specified builders on the searcher's behalf.
+
+### Smart multiplexing
+
+To share bundles with other builders, add the `builders` field to your `eth_sendBundle` request. The `builders` field accepts a list of strings which correspond to the "name" tags of [registered builders](https://github.com/flashbots/dowg/blob/main/builder-registrations.json).
+
+All `eth_sendBundle` requests are shared with the Flashbots builder. They are multiplexed to other block builders at the end of the slot if the Flashbots builder determines it will not win that block.
+
+For example:
+
+```
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "eth_sendBundle",
+  "params": [
+    {
+      "txs": ["0x123abc...", "0x456def..."],
+      "blockNumber": "0xb63dcd",
+      "minTimestamp": 0,
+      "maxTimestamp": 1615920932
+      "builders": ["builder0x69", "beaverbuild.org"]
+    }
+  ]
+}
+```
+
+Searchers can also use `mev_sendBundle` to multiplex bundles if they prefer. Though this method is more complex and not necessary for gas fee refunds.
+
+_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
+
+The Flashbots builder uses a refund rule to retroactively calculate refunds for all bundles landed in its blocks.
+
+The refund rule aims to have bundles make the minimum net payment so that bidding optimally is as straight forward as possible. We do this by measuring the contribution of bundles above the other bundles the builder has received, and refunding as much of that as possible. 
+
+Bundles sent by the same signer will be treated as non-competitive.
+
+### The Flat Tax Rule
+
+<div className="med caption-img">
+
+![Flat tax rule](/img/flat-tax-rule.png)
+
+Definition of the flat tax rule
+
+</div>
+
+Notice that if the block generates enough value after paying the proposer, everyone should be refunded their contribution, meaning everyone pays the minimum they need to pay to beat competition. 
+
+### Identity constraint
+
+To avoid the rule being gamed by submitting bundles from multiple identities, we impose an additional constraint that no set of identities can receive in total more refunds than they contribute to the block.
+
+<div className="med caption-img">
+
+![Identity constraint](/img/identity-constraint.png)
+
+Definition of the identity constraint
+
+</div>
+
+## Who receives refunds
+
+The refund recipient is the signer used on the `eth_sendBundle`, `mev_sendBundle`, or `eth_sendPrivateTransaction` request.
+
+## How to track refunds
+
+Refunds are tracked from a start date of July 8, 2024. Via an upcoming API, users will be able to:
+* View unclaimed refund amounts
+* Delegate refunds to an Ethereum account other than their signing key address.

docs/flashbots-auction/advanced/multiplexing.mdx

@@ -6,7 +6,9 @@ import Builders from '../../specs/mev-share/_builders.mdx';
 
 Some users might want to send their transactions or bundles to multiple builders for various reasons. The ability to multiplex is supported by our APIs.
 
-When you are using [`mev_sendBundle`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#mev_sendbundle) to send bundle, or [`eth_sendPrivateTransaction`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendprivatetransaction) to send transaction, simply specify the builders you want to multiplex to in the `privacy.builders` parameter.
+If you are using [`mev_sendBundle`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#mev_sendbundle) to send bundles, or [`eth_sendPrivateTransaction`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendprivatetransaction) to send transactions, specify the builders you want to multiplex to in the `privacy.builders` parameter.
+
+If you are using [`eth_sendBundle`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendbundle) to send bundles, specify the builders you want to multiplex to in the `builders` parameter.
 
 Below is the list of builders that you can multiplex to:
 

docs/flashbots-auction/advanced/rpc-endpoint.mdx

@@ -46,6 +46,7 @@ Each method is documented below.
       maxTimestamp,      // (Optional) Number, the maximum timestamp for which this bundle is valid, in seconds since the unix epoch
       revertingTxHashes, // (Optional) Array[String], A list of tx hashes that are allowed to revert
       replacementUuid,   // (Optional) String, UUID that can be used to cancel/replace this bundle
+      builders,          // (Optional) Array[String], A list of [registered](https://github.com/flashbots/dowg/blob/main/builder-registrations.json) block builder names to share the bundle with
     }
   ]
 }
@@ -81,9 +82,43 @@ 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.
+
+example with `builders`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "eth_sendBundle",
+  "params": [
+    {
+      "txs": ["0x123abc...", "0x456def..."],
+      "blockNumber": "0xb63dcd",
+      "minTimestamp": 0,
+      "maxTimestamp": 1615920932,
+      "builders": ["builder0x69"]
+    }
+  ]
+}
+```
+
+example response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "123",
+  "result": {
+    "bundleHash": "0x2228f5d8954ce31dc1601a8ba264dbd401bf1428388ce88238932815c5d6f23f",
+    "smart": "true"
+  }
+}
+```
+
 ### mev_sendBundle
 
-`mev_sendBundle` uses a new bundle format to send bundles to MEV-Share. See the [Sending Bundles](/flashbots-mev-share/searchers/sending-bundles#simulating_bundles) page for more information, or check out the [Sending Bundles](/flashbots-mev-share/searchers/sending-bundles) page for a short guide.
+`mev_sendBundle` uses a new bundle format to send bundles to MEV-Share. See the [Understanding Bundles](/flashbots-mev-share/searchers/understanding-bundles) page for more information, or check out the [Sending Bundles](/flashbots-mev-share/searchers/sending-bundles) page for a short guide.
 
 <SendBundleSpec />
 

docs/flashbots-protect/additional-documentation/eth-sendPrivateTransaction.mdx

@@ -220,7 +220,7 @@ and 70% of the backrun value is left to the builder.
 
 ### eth_sendPrivateRawTransaction
 
-`eth_sendPrivateRawTransaction` behaves like [eth_sendPrivateTransaction](#eth_sendprivatetransaction) but its format
+`eth_sendPrivateRawTransaction` behaves like [eth_sendPrivateTransaction](#) but its format
 is similar to that of [`eth_sendRawTransaction`](https://docs.alchemy.com/reference/eth-sendrawtransaction)
 
 This method has the following JSON-RPC format:

docs/flashbots-protect/gas-fee-refunds.md

@@ -0,0 +1,47 @@
+---
+title: Gas Fee Refunds
+---
+
+## Introduction
+
+Flashbots Protect users are automatically eligible to receive gas fee refunds. If Flashbots can include your transaction on chain for a lower price, you are eligible to receive a refund. This applies to both the RPC and the private transaction API.
+
+Gas fee refunds do not change how transactions are executed and users do not need to make any changes to be eligible for them.
+
+Gas fee refunds are calculated separately, and applied in addition to, refunds from [MEV-Share](/flashbots-protect/mev-share).
+
+## Where do refunds come from
+
+Users and orderflow providers (like wallets) often pay high priority fees to land transactions on chain. Many of these transactions could be executed just as quickly for a fraction of the gas cost.
+
+It can be difficult to estimate gas correctly when sending a transaction. The Flashbots block builder calculates this on behalf of users and automatically refunds transactions that overpay.
+
+Gas fee refunds include both priority fees (more common in user transactions) and coinbase transfers (less common).
+
+## Which transactions receive refunds
+
+Flashbots provides refunds for transactions in blocks landed by the Flashbots block builder. Whether a transaction receives a refund depends on a few factors that vary from block to block:
+* How much network congestion and competition there was
+* Whether the Flashbots builder made a profit and how much
+* How much the specific transaction contributed to the value of the block
+* If the transaction was sent directly to Flashbots, or shared with other RPCs and block builders
+
+## How to maximize both refunds and speed
+
+Transactions which are sent directly to the Flashbots RPC or API, and not multiplexed _by the user_ to other RPCs or block builders, are likely to receive higher refunds. This is because they increase the profit of the Flashbots builder which is used to provide refunds.
+
+The Flashbots block builder does not land 100% of blocks. In order to improve inclusion speed, users can ask Flashbots to share their transactions with other block builders in cases where the Flashbots builder does not win a block. Flashbots will automatically share with all specified builders on the user's behalf.
+
+There are two ways to share with other builders:
+* Use [fast mode](/flashbots-protect/quick-start#faster-transactions) to share with all registered builders
+* Choose [specific builders](/flashbots-protect/mev-share#builders) to share transactions with
+
+## Who receives refunds
+
+For the RPC: The refund recipient is the address specified in the first [refund parameter](/flashbots-protect/mev-share#refunds) on an RPC request, if one is provided. Otherwise, refunds are sent to the transaction originator (`tx.origin`) by default.
+
+For the private transaction API: The refund recipient is the signer used on the `eth_sendPrivateTransaction` request.
+
+## How to track refunds
+
+Refunds are tracked from a start date of July 8, 2024. Users wil be able to view unclaimed refund amounts via an upcoming API.

docs/flashbots-protect/overview.mdx

@@ -20,7 +20,7 @@ It has the following key benefits:
 
 - **Configurable:** You can choose which builders to send to and your mev-share settings.
 - **Frontrunning protection:** Transactions are sent to a private Flashbots mempool where they will be hidden from front-running and sandwich bots.
-- **Receive backrunning MEV refunds**: If your transaction creates MEV via backrunning, you will receive an MEV refund through [MEV-Share](/flashbots-mev-share/introduction).
+- **Receive refunds**: If your transaction creates MEV via backrunning, you will receive an MEV refund through [MEV-Share](/flashbots-mev-share/introduction). If your transaction pays a higher priority fee than required for inclusion on chain, you will receive a [gas fee refund](/flashbots-protect/gas-fee-refunds).
 - **Revert protection:** Users do not pay for failed transactions since transactions that would revert are excluded.
 
 You can use Flashbots Protect by clicking the button below or by sending transactions using `eth_sendRawTransaction` to `rpc.flashbots.net/fast` or the custom URL based on your advanced configuration below.

docs/flashbots-protect/quick-start.mdx

@@ -10,7 +10,7 @@ Flashbots Protect has the following key benefits:
 
 - **Highly Configurable:** Customize your preference level for privacy, latency, and rebate returns.
 - **No frontrunning:** Transactions are hidden from the public mempool away from front-running and sandwich bots.
-- **Earn MEV refunds**: If your transaction creates MEV, earn refunds through [MEV-Share](/flashbots-mev-share/introduction).
+- **Earn refunds**: If your transaction creates MEV, earn MEV refunds through [MEV-Share](/flashbots-mev-share/introduction). If your transaction pays high priority fees, earn [gas fee refunds](/flashbots-protect/gas-fee-refunds).
 - **No failed transactions:** Transactions are only included in the block if they will not revert. Users do not pay fees for failed transactions.
 
 ### Faster Transactions
@@ -49,10 +49,10 @@ You can also add Flashbots Protect RPC manually in MetaMask by following these s
 3. Click “Add a network manually” and fill in the following information:
 
 - **Network Name:** Flashbots Protect
-- **New RPC URL:** <https://rpc.flashbots.net/fast> or the URL provided above based on your configuration
+- **New RPC URL:** [https://rpc.flashbots.net/fast](https://rpc.flashbots.net/fast) or the URL provided above based on your configuration
 - **Chain ID:** 1
 - **Currency Symbol:** ETH
-- **Block Explorer URL:** <https://etherscan.io/>
+- **Block Explorer URL:** [https://etherscan.io/](https://etherscan.io/)
 
 4. Click “Save.”
 5. Click “Switch to Flashbots Protect”
@@ -62,10 +62,10 @@ You can also add Flashbots Protect RPC manually in MetaMask by following these s
 Flashbots Protect RPC for Goerli testnet can be added with these details:
 
 - **Network Name:** Goerli Flashbots Protect
-- **New RPC URL:** <https://rpc-goerli.flashbots.net/>
+- **New RPC URL:** [https://rpc-goerli.flashbots.net/](https://rpc-goerli.flashbots.net/)
 - **Chain ID:** 5
 - **Currency Symbol:** ETH
-- **Block Explorer URL**: <https://goerli.etherscan.io/>
+- **Block Explorer URL**: [https://goerli.etherscan.io/](https://goerli.etherscan.io/)
 
 Below is the list of Flashbots Protect RPCs we currently support across Ethereum mainnet and testnets:
 

docs/guide-send-tx-bundle.mdx

@@ -27,5 +27,6 @@ With `relay.flashbots.net` identified as the go-to for advanced operations, the
 
 - **For Single Transactions**: Use `eth_sendPrivateTransaction`.
 - **For Bundles of Transactions**:
-  - **Use**: `mev_sendBundle` for more flexibility and power, like leveraging the [new bundle format](flashbots-mev-share/searchers/understanding-bundles), [MEV-Share](flashbots-mev-share/introduction), and [multiplexing to multiple builders](flashbots-auction/advanced/multiplexing).
+  - **Use**: `mev_sendBundle` for more flexibility and power, like leveraging the [new bundle format](flashbots-mev-share/searchers/understanding-bundles) and [MEV-Share](flashbots-mev-share/introduction).
   - **Use**: `eth_sendBundle` if you want something simple and quick! The OG way of sending bundles.
+  - Both bundle APIs support [multiplexing to multiple builders](flashbots-auction/advanced/multiplexing).

docs/sidebars.js

@@ -34,6 +34,7 @@ module.exports = {
           "Advanced Concepts": [
             'flashbots-auction/advanced/understanding-bundles',
             'flashbots-auction/advanced/multiplexing',
+            'flashbots-auction/advanced/gas-fee-refunds',
             'flashbots-auction/advanced/coinbase-payment',
             'flashbots-auction/advanced/bundle-pricing',
             'flashbots-auction/advanced/reputation',
@@ -53,6 +54,7 @@ module.exports = {
         'flashbots-protect/overview',
         'flashbots-protect/quick-start',
         'flashbots-protect/mev-share',
+        'flashbots-protect/gas-fee-refunds',
         'flashbots-protect/cancellations',
         'flashbots-protect/stuck_transactions',
         'flashbots-protect/large-transactions',