diff --git a/docs/flashbots-auction/advanced/rpc-endpoint.mdx b/docs/flashbots-auction/advanced/rpc-endpoint.mdx index 09f15a1c..119c0d0a 100644 --- a/docs/flashbots-auction/advanced/rpc-endpoint.mdx +++ b/docs/flashbots-auction/advanced/rpc-endpoint.mdx @@ -402,7 +402,7 @@ example response: #### `privacy` -By default, transactions are sent to the Flashbots MEV-Share Node with the default [Stable](/flashbots-protect/mev-share#stable-configuration) configuration. The `privacy` parameter allows you to specify your own privacy parameters. +By default, transactions are sent to the Flashbots MEV-Share Node with the default [Stable](/flashbots-protect/mev-refunds#stable-configuration) configuration. The `privacy` parameter allows you to specify your own privacy parameters. | Param | Type Info | Description | | --- | --- | --- | diff --git a/docs/flashbots-mev-share/introduction.mdx b/docs/flashbots-mev-share/introduction.mdx index 93e32003..f53731fc 100644 --- a/docs/flashbots-mev-share/introduction.mdx +++ b/docs/flashbots-mev-share/introduction.mdx @@ -20,7 +20,7 @@ Users send their transactions to a specialized actor called a MEV-Share Node. Th At the moment, MEV-Share Nodes ony accept backruns. ## How do I use MEV-Share? -The most simple way to use MEV-Share is by sending transactions to [Flashbots Protect](/flashbots-protect/quick-start), which leverages the [Flashbots MEV-Share Node](/flashbots-protect/mev-share). Wallet and application developers should check out the [Flashbots Protect MEV-Share section](/flashbots-protect/mev-share) for information about integrating and configuring the Flashbots MEV-Share Node. +The most simple way to use MEV-Share is by sending transactions to [Flashbots Protect](/flashbots-protect/quick-start), which leverages the [Flashbots MEV-Share Node](/flashbots-protect/mev-refunds). Wallet and application developers should check out the [Flashbots Protect MEV-Share section](/flashbots-protect/mev-refunds) for information about integrating and configuring the Flashbots MEV-Share Node. ## How do I search on MEV-Share? Searchers should see the [Getting Started](/flashbots-mev-share/searchers/getting-started) guide for a walkthrough of MEV-Share and how it differs from traditional searching. \ No newline at end of file diff --git a/docs/flashbots-mev-share/orderflow-providers.mdx b/docs/flashbots-mev-share/orderflow-providers.mdx index 54612946..391a02b8 100644 --- a/docs/flashbots-mev-share/orderflow-providers.mdx +++ b/docs/flashbots-mev-share/orderflow-providers.mdx @@ -2,4 +2,4 @@ title: For Orderflow Providers --- -Flashbots runs a MEV-Share Node that can be used by sending transactions to [Flashbots Protect](/flashbots-protect/quick-start). Wallets and application developers should see the [Protect MEV-Share Node guide](/flashbots-protect/mev-share) to configure your integration. \ No newline at end of file +Flashbots runs a MEV-Share Node that can be used by sending transactions to [Flashbots Protect](/flashbots-protect/quick-start). Wallets and application developers should see the [Protect MEV-Share Node guide](/flashbots-protect/mev-refunds) to configure your integration. \ No newline at end of file diff --git a/docs/flashbots-mev-share/release-notes/2023-07.mdx b/docs/flashbots-mev-share/release-notes/2023-07.mdx index 5cc30610..9ca987c0 100644 --- a/docs/flashbots-mev-share/release-notes/2023-07.mdx +++ b/docs/flashbots-mev-share/release-notes/2023-07.mdx @@ -2,13 +2,13 @@ ## customized refunds -Configure the percent(s) and recipient(s) for MEV-Share refunds by adding the [`refund`](/flashbots-protect/mev-share#refunds) query parameter to Protect RPC requests +Configure the percent(s) and recipient(s) for MEV-Share refunds by adding the [`refund`](/flashbots-protect/settings-guide#refunds) query parameter to Protect RPC requests or by adding `preferences.validity.refund` argument to the `eth_sendPrivateTransaction` JSON-RPC [method](/flashbots-auction/advanced/rpc-endpoint#eth_sendprivatetransaction). ## builder sharing Share transactions and bundles with additional builders for faster inclusion. -- Users: [Opt in to share with registered builders](/flashbots-protect/mev-share#builders) +- Users: [Opt in to share with registered builders](/flashbots-protect/settings-guide#builders) - Builders: [Register to receive bundles](https://github.com/flashbots/dowg#builders) ## debugging guide diff --git a/docs/flashbots-mev-share/release-notes/2023-09.mdx b/docs/flashbots-mev-share/release-notes/2023-09.mdx index 99c92a6a..ee9e6b18 100644 --- a/docs/flashbots-mev-share/release-notes/2023-09.mdx +++ b/docs/flashbots-mev-share/release-notes/2023-09.mdx @@ -2,7 +2,7 @@ ## default logs hint -A new hint which shares a subset of logs, as described in the [stable configuration](/flashbots-protect/mev-share#stable-configuration). +A new hint which shares a subset of logs, as described in the [hints] settings(/flashbots-protect/settings-guide#hints). Previously these logs were shared by default. Now, users of the private transaction API, Protect RPC, and bundle relay can also request to share these logs when customizing their settings. diff --git a/docs/flashbots-mev-share/searchers/tutorials/flash-loan-arbitrage/bot.mdx b/docs/flashbots-mev-share/searchers/tutorials/flash-loan-arbitrage/bot.mdx index 29ec1968..3bb02282 100644 --- a/docs/flashbots-mev-share/searchers/tutorials/flash-loan-arbitrage/bot.mdx +++ b/docs/flashbots-mev-share/searchers/tutorials/flash-loan-arbitrage/bot.mdx @@ -26,7 +26,7 @@ Client libraries have been developed for the following programming languages (mo To reiterate our goal, we need to find pending transactions from other Ethereum users and backrun them (send our transaction immediately after the user's transaction). If the user's trade moves the price enough, we'll arbitrage the trading pair between two exchanges for a profit. -As MEV-Share receives new transactions, it broadcasts them to searchers via the [Event Stream](/flashbots-mev-share/searchers/event-stream). Each transaction shares varying amounts of data via [hints](/flashbots-protect/mev-share#hints), but by default, transactions that trade on Uniswap, Balancer, or Curve will expose the trading pair's contract address in the log topics. +As MEV-Share receives new transactions, it broadcasts them to searchers via the [Event Stream](/flashbots-mev-share/searchers/event-stream). Each transaction shares varying amounts of data via [hints](/flashbots-protect/mev-refunds#hints), but by default, transactions that trade on Uniswap, Balancer, or Curve will expose the trading pair's contract address in the log topics. Here's an example of an event generated by a user who's (most likely) using MEV-Share's default privacy settings: @@ -141,7 +141,7 @@ _To read more about how the SSE stream works, see the [Event Stream docs](/flash ## Filtering Relevant Transactions -MEV-Share uses [**hints**](/flashbots-protect/mev-share#hints) to selectively share information about a transaction. Based on the hint preferences specifies by the user when connecting, the transactions (or bundles) they send will trigger events containing information about their transaction which is filtered according to their hint preferences. +MEV-Share uses [**hints**](/flashbots-protect/mev-refunds#hints) to selectively share information about a transaction. Based on the hint preferences specifies by the user when connecting, the transactions (or bundles) they send will trigger events containing information about their transaction which is filtered according to their hint preferences. In this guide, we're only concerned with the fields in `logs`: `address` and `topics`. Other fields not covered in this guide are detailed in the [Event Scheme docs](/flashbots-mev-share/searchers/event-stream#event-scheme). diff --git a/docs/flashbots-protect/additional-documentation/bundle-cache.md b/docs/flashbots-protect/additional-documentation/bundle-cache.md index e84fbff7..d4ca377e 100644 --- a/docs/flashbots-protect/additional-documentation/bundle-cache.md +++ b/docs/flashbots-protect/additional-documentation/bundle-cache.md @@ -49,7 +49,7 @@ Once all the transactions you want to include in your bundle are added to the qu If you're being helped with a whitehat recovery, we may provide a web interface for you to do this. -If you want to send a bundle directly, check out the [Flashbots Auction Docs](/flashbots-auction/quick-start#how-to-send-your-first-flashbots-bundle) for instructions on how to do this. +If you want to send a bundle directly, check out the [Flashbots Builder Docs](/flashbots-auction/quick-start#how-to-send-your-first-flashbots-bundle) for instructions on how to do this. ## Fake Funds diff --git a/docs/flashbots-protect/additional-documentation/eth-sendPrivateTransaction.mdx b/docs/flashbots-protect/additional-documentation/eth-sendPrivateTransaction.mdx index 9390538b..b238c4a7 100644 --- a/docs/flashbots-protect/additional-documentation/eth-sendPrivateTransaction.mdx +++ b/docs/flashbots-protect/additional-documentation/eth-sendPrivateTransaction.mdx @@ -183,7 +183,7 @@ example response: #### Privacy options -By default, transactions are sent to the Flashbots MEV-Share Node with the default [Stable](/flashbots-protect/mev-share#stable-configuration) configuration. The `privacy` parameter allows you to customize privacy settings: +By default, transactions are sent to the Flashbots MEV-Share Node with the default [Stable](/flashbots-protect/mev-refunds#stable-configuration) configuration. The `privacy` parameter allows you to customize privacy settings: | Parameter | Type | Description | | ---------- | ------------ | -------------------------------------------------------------------- | diff --git a/docs/flashbots-protect/gas-fee-refunds.md b/docs/flashbots-protect/gas-fee-refunds.md index 9db3a67e..922673c4 100644 --- a/docs/flashbots-protect/gas-fee-refunds.md +++ b/docs/flashbots-protect/gas-fee-refunds.md @@ -6,7 +6,7 @@ title: Gas Fee Refunds 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). +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, MEV refunds from [MEV-Share](/flashbots-protect/mev-refunds). ## Where do refunds come from @@ -34,11 +34,11 @@ The Flashbots block builder does not land 100% of blocks. In order to improve in 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 +* Choose [specific builders](/flashbots-protect/settings-guide#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 RPC: The refund recipient is the address specified in the first [refund parameter](/flashbots-protect/settings-guide#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. diff --git a/docs/flashbots-protect/large-transactions.md b/docs/flashbots-protect/large-transactions.md index 3d628c58..a1db1980 100644 --- a/docs/flashbots-protect/large-transactions.md +++ b/docs/flashbots-protect/large-transactions.md @@ -1,5 +1,5 @@ --- -title: Large transaction allowlist +title: Large Transaction Allowlist --- Some projects may need to post larger transactions (measured in bytes) than the transaction pool allows. Flashbots bundles are not subject to the transaction pool size constraints. However, at the RPC level only transactions to certain contracts are allowed to be over 128kb. diff --git a/docs/flashbots-protect/mev-refunds.mdx b/docs/flashbots-protect/mev-refunds.mdx new file mode 100644 index 00000000..67d00221 --- /dev/null +++ b/docs/flashbots-protect/mev-refunds.mdx @@ -0,0 +1,50 @@ +--- +title: MEV Refunds +--- + +import ProtectButton from '@site/src/components/ProtectButton'; + +## Introduction + +Flashbots Protect users are automatically eligible to receive MEV refunds from [MEV-Share](/flashbots-mev-share/introduction). If your transaction (eg. a large DEX swap) generates MEV, MEV-Share can help you reclaim a significant portion of this value. The remainder is split with searchers and validators to facilitate transaction inclusion. + +By default, all Protect transactions use the [default](/flashbots-protect/settings-guide#default) privacy setting which is continuously optimized by Flashbots to balance efficient execution and protection against harmful MEV. Advanced users can customize their settings when configuring their RPC or by manually editing the query parameters their Protect RPC request. + + + +## Common privacy settings + +You can customize how much information is shared about your transactions in MEV-Share. Each piece of information is called a "hint". Sharing more hints can increase refunds, while sharing fewer hints can increase privacy. Below are some common hint choices for different levels of privacy. See the complete [settings page](/flashbots-protect/settings-guide) for a full list of all settings you can apply to your RPC request. + +### Default + +To use the default privacy settings, you don't need to specify any query parameters. + +```url +https://rpc.flashbots.net +``` + +Currently, this configuration shares the following information: + +- The `hash` of all transactions +- `default_logs` Partial logs (the pool id and the fact that a swap was made) for curve, balancer, and uniswapV2/V3-style trades + +### Max Privacy + +To use Protect with full privacy, set _only_ the `hash` hint in your Protect RPC URL: + +```url +https://rpc.flashbots.net?hint=hash +``` + +This configuration ensures that all identifiable transaction data sent to the MEV-Share Node is concealed from searchers. However, it's important to note that this could make it more challenging for searchers to spot MEV opportunities, leading to a very likely decrease in your MEV refund. + +### Max Refund + +To use Protect with the maximum refund, set _all_ hints in your Protect RPC URL: + +```url +https://rpc.flashbots.net?hint=calldata&hint=contract_address&hint=function_selector&hint=logs +``` + +This configuration provides searchers with comprehensive details about your transaction, giving them a better chance to identify more MEV opportunities and return MEV refunds. diff --git a/docs/flashbots-protect/mev-share.mdx b/docs/flashbots-protect/mev-share.mdx deleted file mode 100644 index 19f36c7c..00000000 --- a/docs/flashbots-protect/mev-share.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: MEV-Share ---- - -import HintsTable from '../specs/mev-share/HintsTable'; -import Builders from '../specs/mev-share/_builders.mdx'; -import ProtectButton from '@site/src/components/ProtectButton'; - -## Introduction - -MEV-Share allows users to reclaim a significant portion of the MEV generated by their transactions, while the remainder goes to searchers and builders to facilitate transaction inclusion. By default, transactions from Protect users are directed to the Flashbots [MEV-Share Node](/flashbots-mev-share/introduction), which facilitates this return. Users are automatically connected to the [Stable](/flashbots-protect/mev-share#stable-configuration) configuration, a setting continuously optimized by Flashbots to balance efficient execution and protection against harmful MEV. This document provides a guide on the mechanism and various configurations of MEV-Share. - -Advanced users can customize their transactions and preferences through the advanced panel or by manually configuring their Protect RPC request. - - - -## Common configurations - -### Stable Configuration - -The Stable configuration is the default configuration for Protect RPC. No query parameters are specified to use it. - -```url -https://rpc.flashbots.net/fast -``` - -Currently, this configuration shares the following information: - -- The `hash` of all transactions -- `default_logs` Partial logs (the pool id and the fact that a swap was made) for curve, balancer, and uniswapV2/V3-style trades -- Transactions are only forwarded to the Flashbots block builder - -This may change as the configuration is tuned to maximize benefits. - -### Max Privacy - -To use Protect with full privacy, set _only_ the `hash` hint in your Protect RPC URL: - -```url -https://rpc.flashbots.net?hint=hash -``` - -This configuration ensures that all identifiable transaction data sent to the MEV-Share Node is concealed from searchers. However, it's important to note that this could make it more challenging for searchers to spot MEV opportunities, leading to a very likely decrease in your MEV kickback. - -### Max Kickback - -To use Protect with the maximum kickback, set _all_ hints in your Protect RPC URL: - -```url -https://rpc.flashbots.net?hint=calldata&hint=contract_address&hint=function_selector&hint=logs&hint=hash -``` - -This configuration provides searchers with comprehensive details about your transaction, giving them a better chance to identify more MEV opportunities and return MEV refunds. - -## Examples - -Here are some examples of configurations that you might choose, depending on your goals. - -|
Goal
| Flashbots Protect RPC URL | -| --- | --- | -| Stable | `https://rpc.flashbots.net/fast` | -| Max Privacy | `https://rpc.flashbots.net?hint=hash` | -| Max Kickback | `https://rpc.flashbots.net/?hint=calldata&hint=contract_address&hint=function_selector&hint=logs&hint=hash` | -| Add Builders (share with other builders for faster inclusion) | `https://rpc.flashbots.net?builder=flashbots&builder=XYZ` | -| Change Refund (send more to validator for faster inclusion) | `https://rpc.flashbots.net?refund=userAddr:10` | - -## Configuration Reference - -The Protect RPC uses query parameters within the URL to convey your preferences. These parameters can include hints about your transaction, the builders to whom your transaction is directed, and the distribution of potential refunds if your transaction is bundled. - -### Hints - -To customize your hint setup, use the hint parameter to control the visibility of your transaction data to searchers. The default [Stable](/flashbots-protect/mev-share#stable-configuration) hint configuration will be used if no hints are provided. If you specify one or more hints, any hint that is _not_ included will be disabled. - - - -Here is an example: - -```url -https://rpc.flashbots.net?hint=calldata&hint=logs&hint=hash -``` - -This configuration shares calldata, logs, and transaction hash with searchers. It does not share the contract address or function selector. - -### Builders - -Designate which builders will receive your transaction with the `builder` parameter. This parameter can be repeated multiple times to include different builders. The builders listed below are currently supported. - -Note that all transactions are shared with the Flashbots block builder, even if it is not explicitly specified. - - - -It's important to understand that while adding more builders can increase your transaction inclusion rate, it also requires you to place trust in those builders. Here's an example of how to utilize the `builder` parameter: - -```url -https://rpc.flashbots.net?builder=ABC&builder=XYZ -``` - -This configuration sends your transaction to ABC block builder, XYZ block builder, and Flashbots block builder. - -### Refunds - -You can tailor your refund settings using the refund parameter. This determines the distribution of the searcher's payment among different addresses for bundled transactions. If not specified, the transaction originator (tx.origin) will by default receive 90% of the searcher's payment. - -The refund parameter contains two colon-separated values: an address for the refund and the percentage of the searcher's payment to be refunded. To distribute the payment across multiple addresses, append a new refund parameter for each address. - -Here is an example of a refund parameter that sends 10% of the searcher's payment to the address `userAddr`: - -```URL -https://rpc.flashbots.net?refund=userAddr:10 -``` - -The sum of all refund percentages must be less than 100. The remaining percentage, inferred from 100 - total refund percentages, is the payment to the validator. - -**Note**: Keeping a larger percentage of the refund may result in longer block inclusion times as it reduces the payment to the validator. - -### Priority fee - -When sending a private transaction to an RPC endpoint, the priority fee (tips) should be greater than zero. A transaction with a 0 priority fee will not be shared with block builders and will only be included on-chain if a searcher bundles them via MEV-Share. diff --git a/docs/flashbots-protect/overview.mdx b/docs/flashbots-protect/overview.mdx index 9e9aea0a..aff1a82b 100644 --- a/docs/flashbots-protect/overview.mdx +++ b/docs/flashbots-protect/overview.mdx @@ -12,18 +12,15 @@ title: MEV Protection Overview import ProtectButton from '@site/src/components/ProtectButton'; -> **Privacy notice: Flashbots Protect RPC does not track** user information (i.e. IP, location, etc.). No user information is stored or logged. +Flashbots Protect is a cheaper and safer way to transact on Ethereum. It protects your transactions from frontrunning and gives you refunds on gas fees and MEV. -Flashbots Protect is a secure way to protect Ethereum transactions from harmful front-running and sandwich attacks and to receive refunds on MEV generated from any back-running. +Key benefits: +- **Frontrunning protection:** Transactions are sent to a private Flashbots mempool where they will be hidden from frontrunning and sandwich bots. +- **Refunds**: If your transaction creates MEV, you an earn an [MEV refund](/flashbots-protect/mev-refunds). If your transaction pays high priority fees, you can earn [gas fee refunds](/flashbots-protect/gas-fee-refunds). +- **No failed transactions:** Transactions are only included in the block if they do not revert. Users do not pay fees for failed transactions. +- **Configurable:** You can customize your privacy, speed, and refund settings. -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 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. +Use Flashbots Protect by clicking the button below or by sending `eth_sendRawTransaction` API requests to `rpc.flashbots.net/fast`. @@ -31,3 +28,5 @@ You can use Flashbots Protect by clicking the button below or by sending transac
We want to thank MiningDAO, mistX, and Nethermind for significant code contributions, testing, and being early adopters of Flashbots Protect. + +**Privacy notice: Flashbots Protect RPC does not track** user information (i.e. IP, location, etc.). No user information is stored or logged. diff --git a/docs/flashbots-protect/quick-start.mdx b/docs/flashbots-protect/quick-start.mdx index 56512350..c32100d2 100644 --- a/docs/flashbots-protect/quick-start.mdx +++ b/docs/flashbots-protect/quick-start.mdx @@ -1,21 +1,21 @@ --- -title: Quick start +title: Quick Start --- import ProtectButton from '@site/src/components/ProtectButton'; -## Key Considerations +### Key Considerations 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 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. +- **Frontrunning protection:** Transactions are hidden from the public mempool away from front-running and sandwich bots. +- **Refunds**: If your transaction creates MEV, you an earn an [MEV refund](/flashbots-protect/mev-refunds). If your transaction pays high priority fees, you can earn [gas fee refunds](/flashbots-protect/gas-fee-refunds). +- **No failed transactions:** Transactions are only included in the block if they do not revert. Users do not pay fees for failed transactions. +- **Configurable:** You can customize your privacy, speed, and refund settings. ### Faster Transactions -Using Protect in fast mode accelerates the inclusion of your transaction. Click the "fast" option when [configuring your Protect RPC](/flashbots-protect/quick-start#using-flashbots-protect) or manually set your RPC to `rpc.flashbots.net/fast`. +Use Protect in fast mode to land your transactions faster on chain. Click the "fast" option when [configuring your Protect RPC](/flashbots-protect/quick-start#using-flashbots-protect) or manually set your RPC to `rpc.flashbots.net/fast`. Fast mode details: @@ -26,7 +26,7 @@ Fast mode details: ### Customer Support -Wallets and applications can receive customer support for transactions tagged with their `originId`. To opt into customer support update your RPC URL to `rpc.flashbots.net/fast?originId=[your-wallet-name]`. +Wallets and applications can receive customer support for transactions tagged with their `originId`. To opt into customer support, update your RPC URL to `rpc.flashbots.net/fast?originId=[your-wallet-name]`. :::warning Do Not Switch RPCs Before Transaction Confirmation diff --git a/docs/flashbots-protect/settings-guide.md b/docs/flashbots-protect/settings-guide.md new file mode 100644 index 00000000..790865de --- /dev/null +++ b/docs/flashbots-protect/settings-guide.md @@ -0,0 +1,134 @@ +--- +title: Settings Guide +--- + +import HintsTable from '../specs/mev-share/HintsTable'; +import Builders from '../specs/mev-share/_builders.mdx'; + +The Protect RPC uses query parameters and URL paths to convey your preferences. These parameters indicate which builders to share your transaction with, how potential refunds should be distributed, when to send transactions to the mempool, and other features. + +### Default + +```url +https://rpc.flashbots.net +``` + +By default, Flashbots Protect uses the following settings: +- Transactions are only forwarded to the Flashbots block builder +- Transactions are retried for 25 blocks and dropped if they do not land on chain within this time +- The `hash` and `default_logs` [hints](/flashbots-protect/settings-guide#hints) are shared with MEV-Share searchers +- 90% of MEV refunds are sent to `tx.origin` (the remaining 10% is sent to the validator) +- 100% of gas fee refunds are sent to `tx.origin` +- 0 priority fee transactions are not included on chain +- Reverted transactions are not included on chain + +This may change as the configuration is tuned to maximize benefits. + +### Fast + +Speed up your transactions by using fast mode. + +```url +https://rpc.flashbots.net/fast +``` + +Compared with the default configuration: +- Transactions are shared with all [registered builders](https://github.com/flashbots/dowg/blob/main/builder-registrations.json) +- Validators receive a higher percentage of the MEV-Share refund increasing the probability that the transaction will be included in the winning block. + +### Hints + +Change what transaction data is visible to MEV-Share searchers with the `hint` query parameter. The [default](/flashbots-protect/settings-guide#default) hint configuration will be used if no hints are provided. If you specify one or more hints, any hint that is _not_ included will be disabled. + + + +Here is an example: + +```url +https://rpc.flashbots.net?hint=contract_address&hint=logs +``` + +This configuration shares the contract address and logs with searchers. It does not share the calldata or function selector. + +### Builders + +Designate which builders will receive your transaction with the `builder` query parameter. This parameter can be repeated multiple times to include different builders. The builders listed below are currently supported. + +Note that all transactions are shared with the Flashbots block builder, even if it is not explicitly specified. + + + +It's important to understand that while adding more builders can increase your transaction inclusion rate, it also requires you to place trust in those builders. Here's an example of how to utilize the `builder` parameter: + +```url +https://rpc.flashbots.net?builder=ABC&builder=XYZ +``` + +This configuration sends your transaction to ABC block builder, XYZ block builder, and the Flashbots block builder. + +### Refunds + +Tailor your refund settings using the `refund` query parameter. This determines how MEV and gas fee refunds will be distributed across different addresses. If not specified, the transaction originator (tx.origin) will receive all refunds. + +The refund parameter contains two colon-separated values: an address for the refund and the percentage of the payment that should be refunded to that address. + +Here is an example of a refund parameter that sends 10% of refunds to the address `recipientAddress`: + +```URL +https://rpc.flashbots.net?refund=recipientAddress:10 +``` + +#### MEV Refund Recipients + +MEV refunds can be split across multiple recipients. To distribute the payment across multiple addresses, append a new refund parameter for each address. + +The sum of all refund percentages must be less than 100. The remaining percentage, inferred from 100 - total refund percentages, is the payment to the validator. + +**Note**: Keeping a larger percentage of the refund may result in longer block inclusion times as it reduces the payment to the validator. + +#### Gas Fee Refund Recipients + +Gas fee refunds can only be sent to a single recipient. If multiple addresses are specified, the first refund address listed will receive 100% of the gas fee refund. There is no additional payment split with the validator. + +### Mempool Configuration + +Send certain transactions to the public mempool to improve the likelihood of inclusion by including the `useMempool` query parameter. If either of the following conditions are true, Flashbots will send all pending transactions with this parameter to the public mempool: +1. The Ethereum validator responsible for proposing the next block does not run [MEV-Boost](/flashbots-mev-boost/introduction). Approximately 10% of Ethereum blocks do not include any private transactions. Sending your transaction to the public mempool will give you access to those blocks at the expense of privacy and MEV refunds. +2. The transaction has not been included for 25 blocks: Some transactions pay very low priority fees are unlikely to land within 25 blocks. Send them to the public mempool to allow them to wait for lower gas prices. + +To enable this feature, add the `useMempool` parameter to your Protect RPC URL: + +```url +https://rpc.flashbots.net?useMempool=true +``` + +For analytics or other purposes, you can also specify a custom mempool URL by adding the `mempoolRpc` parameter: + +```url +https://rpc.flashbots.net?useMempool=true&mempoolRpc=https://your-custom-node-url +``` + +### Reverted Transactions + +Allow reverted transactions by including the `canRevert` query parameter in your request. By default, Flashbots Protect does not land reverted transactions on chain to save users gas fees. You can override this feature to receive faster feedback about failing transactions. + +```url +https://rpc.flashbots.net?canRevert=true +``` + +### Bundle Mode + +Use the Protect PRC in bundle mode to interactively construct a bundle of transactions that you want to be land together. This setting is typically used for whitehat rescues and you can find the complete documentation in the [Flashbots API docs](https://docs.flashbots.net/flashbots-protect/additional-documentation/bundle-cache). + +Bundle mode has a few differences from the regular Protect experience: +- Protect will not immediately attempt to land transactions sent in bundle mode. Instead, new transactions will be queued and kept in a pending state. +- To send all pending transactions as a bundle, you must make a separate API request to Flashbots. +- Querying the balance of an address in bundle mode will return a fake balance of 100 ETH. + +### Custom Read RPC + +Use a custom RPC endpoint for **read** requests by including the `url` query parameter in your request. **Write** requests (eg. `eth_sendRawTransaction`) will still be sent to the Protect RPC. This feature is recommended for wallets and applications with large volumes of read requests. + +```url +https://rpc.flashbots.net?url=http://RPC-ENDPOINT.COM +``` diff --git a/docs/sidebars.js b/docs/sidebars.js index ef85cc47..601cc609 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -53,8 +53,9 @@ module.exports = { "Flashbots Protect": [ 'flashbots-protect/overview', 'flashbots-protect/quick-start', - 'flashbots-protect/mev-share', + 'flashbots-protect/mev-refunds', 'flashbots-protect/gas-fee-refunds', + 'flashbots-protect/settings-guide', 'flashbots-protect/cancellations', 'flashbots-protect/nonce-management', 'flashbots-protect/stuck_transactions',