diff --git a/docs/assets/mev/mev-overview.png b/docs/assets/mev/mev-overview.png new file mode 100644 index 0000000000..a526bc2523 Binary files /dev/null and b/docs/assets/mev/mev-overview.png differ diff --git a/docs/assets/mev/mev-topology.png b/docs/assets/mev/mev-topology.png new file mode 100644 index 0000000000..2bf4bb8e66 Binary files /dev/null and b/docs/assets/mev/mev-topology.png differ diff --git a/docs/mev/builder-integration.md b/docs/mev/builder-integration.md new file mode 100644 index 0000000000..16c4513c33 --- /dev/null +++ b/docs/mev/builder-integration.md @@ -0,0 +1,86 @@ +# Integration Guide for Builder + +The [Builder API Specification](https://github.com/bnb-chain/BEPs/blob/master/BEPs/BEP322.md) +defines the standard interface that builders should implement, while the +specific implementation is left open to MEV API providers. The BNB Chain +community offers a simple [implementation example](https://github.com/bnb-chain/bsc-builder) for +reference. + +## Customize Builder + +Although the builder offers great flexibility, there are still some +essential standards that must be followed: + +1. The builder needs to set up a **builder account**, which is used to + sign the block bid and receive fees. The builder can ask for a tip + (builder fee) on the block that it sends to the sentry. If the + block is finally selected, the **builder account** will receive + the tip. + +2. The builder needs to implement the **mev_reportIssue** API to + receive the errors report from validators. + +3. In order to prevent transaction leakage, the builder can only send + block bids to the in-turn validator. + +4. At most 3 block bids are allowed to be sent at the same height from + the same builder. + +Here are some sentry APIs that may interest a builder: + +1. **mev_bestBidGasFee**. It will return the current most profitable + reward that the validator received among all the blocks received + from all builders. The reward is calculated as: **gasFee\*(1 - + commissionRate) - tipToBuilder**. A builder may compare the + **bestBidGasFee** with a local one and then decide to send the + block bid or not. + +2. **mev_params.** It will return the + **BidSimulationLeftOver**,**ValidatorCommission**, **GasCeil** and + **BidFeeCeil** settings on the validator. If the current time is + after **(except block time - BidSimulationLeftOver)**, then there + is no need to send block bids any more; **ValidatorCommission** + and **BidFeeCeil** helps the builder to build its fee charge + strategy. The **GasCeil** helps a builder know when to stop adding + more transactions. + +Builders have the freedom to define various aspects like pricing models +for users, creating intuitive APIs, and define the bundle verification +rules. + +## Setup with Example Builder + +**Step 1: Find Validator Information** + +For validators that open MEV integration, the public information is +shown at [bsc-mev-info](https://github.com/bnb-chain/bsc-mev-info). +Builders can also provide information here to the validator. + +**Step 2: Set up Builder.** + +The builder must sign the bid using an account, such as the etherbase +account specified in the config.toml file. + +```toml +[Eth.Miner.Mev] +BuilderEnabled = true # open bid sending +BuilderAccount = "0x..." # builder address which signs bid, usually it is the same as etherbase address +``` + +Configure the validator node list, including the address of the +validator and the public URL. The public URL refers to the sentry +service. + +```toml +[[Eth.Miner.Mev.Validators]] +Address = "0x23707D3D...6455B52B3" +URL = "https://bsc-fuji.io" + +[[Eth.Miner.Mev.Validators]] +Address = "0x52825922...3A1A7A422" +URL = "http://bsc-mathwallet.io" +``` + +**Step 3: Publish information** + +It is highly recommended to publish information in [bsc-mev-info](https://github.com/bnb-chain/bsc-mev-info). diff --git a/docs/mev/faqs.md b/docs/mev/faqs.md new file mode 100644 index 0000000000..1f9d8928b5 --- /dev/null +++ b/docs/mev/faqs.md @@ -0,0 +1,26 @@ +# FAQs + +1. Do builders fetch the in-turn proposer's GasCeil to build block？ + + Yes, you could using RPC mev_params to query validator's MEV information + before building block, it can help to 1) calculate a valid header with gas no + more than GasCeil; 2) calculate the left bidding time by + BidSimulationLeftOver; 3) calculate suitable builderFee by + validatorCommission. + + +2. How does the validator choose the best bid? + + The block reward is calculated as **gasFee**, the validator reward is + calculated as **gasFee*commissionRate - builderFee**. Every + time the validator receives a new bid, it will compare its reward with + the existing best bid. If it has better block reward and validator + reward, the new bid will go into simulation. If simulation succeeds + before block sealing, it will be compared with local mined block reward. + If the bid's block reward and validator reward are both superior to the + local block, it will be sealed by the validator. + + +3. Who can become the builder? + + Anyone is allowed to become a builder. \ No newline at end of file diff --git a/docs/mev/overview.md b/docs/mev/overview.md new file mode 100644 index 0000000000..ea1f3f7c39 --- /dev/null +++ b/docs/mev/overview.md @@ -0,0 +1,92 @@ +# Overview + +The BSC network has introduced the [Builder API +Specification](https://github.com/bnb-chain/BEPs/blob/master/BEPs/BEP322.md) +to establish a fair and unified MEV market. Previously, BSC clients +lacked native support for validators to integrate with multiple MEV +providers at once. The network became unstable because of the many +different versions of the client software being used. The latest BSC +client adopts the [Proposer-Builder Separation](https://ethereum.org/en/roadmap/pbs/) model. +Within this unified framework, several aspects of the BSC network have +been improved: + +- **Stability**: Validators only need to use the official client to seamlessly integrate with various Builders. + +- **Economy**: Builders that can enter without permission promote healthy market competition. Validators can extract + more value by integrating with more builders, which benefits delegators as well. + +- **Transparency**: This specification aims to bring transparency to the BSC MEV market, exposing profit distribution + among stakeholders to the public. + +## What is MEV and PBS + +MEV, also known as Maximum (or Miner) Extractable Value, can be +described as the measure of total value that may be extracted from +transaction ordering. Common examples include arbitraging swaps on +decentralized exchanges or identifying opportunities to liquidate DeFi +positions. Maximizing MEV requires advanced technical expertise and +custom software integrated into regular validators. The returns are +likely higher with centralized operators. + +Proposer-builder separation(PBS) solves this problem by reconfiguring +the economics of MEV. Block builders create blocks and submit them to +the block proposer, and the block proposer simply chooses the most +profitable one, paying a fee to the block builder. This means even if a +small group of specialized block builders dominate MEV extraction, the +reward still goes to any validator on the network. + +## How it Works on BSC + +![MEV on BSC](../assets/mev/mev-overview.png) + +The figure above illustrates the basic workflow of PBS operating on the +BSC network. + +- MEV Searchers are independent network participants who detect + profitable MEV opportunities and submit their transactions to + builders. Transactions from searchers are usually bundled together + and included in a block, or none of them will be included. + +- The builder collects transactions from various sources to create an + unsealed block and offer it to the block proposer. The builder + will specify in the request the amount of fees the proposer needs + to pay to the builder if this block is adopted. The unsealed block + from the builder is also called a **block bid** as it may request + tips. + +- The proposer chooses the most profitable block from multiple + builders, and pays the fee to the builder by appending a payment + transaction at the end of the block. + +A new component called **Sentry** has been introduced to enhance +network security and account isolation. It assists proposers in +communicating with builders and enables payment processing. + +## What is More + +The PBS model on BSC differs in several aspects from its implementation +on Ethereum. This is primarily due to： + +1. **Different Trust Model**. Validators in the BNB Smart Chain are + considered more trustworthy, as it requires substantial BNB + delegation and must maintain a high reputation. This stands in + contrast to Ethereum, where becoming an Ethereum validator is much + easier, the barrier to becoming a validator is very low (i.e., 32 + ETH). + +2. **Different Consensus Algorithms.** In Ethereum, a block header is + transferred from a builder to a validator for signing, allowing + the block to be broadcasted to the network without disclosing the + transactions to the validator. In contrast, in BSC, creating a + valid block header requires executing transactions and system + contract calls (such as transferring reward and depositing to the + validator set contract), making it impossible for builders to + propose the whole block. + +3. **Different Blocking Time.** With a shorter block time of 3 seconds + in BSC compared to Ethereum's 12 seconds, designing for time + efficiency becomes crucial. + +These differences have led to different designs on BSC's PBS regarding +payment, interaction, and APIs. For more design philosophy, please refer +to [BEP322:Builder API Specification for BNB Smart Chain](https://github.com/bnb-chain/BEPs/blob/master/BEPs/BEP322.md). \ No newline at end of file diff --git a/docs/mev/validator-integration.md b/docs/mev/validator-integration.md new file mode 100644 index 0000000000..381ec6b831 --- /dev/null +++ b/docs/mev/validator-integration.md @@ -0,0 +1,116 @@ +# Integration Guide for Validator + +## Decison Make + +When activating MEV functionality, validators encounter a mix of +opportunities and challenges. Before enabling this feature, validators +need to carefully evaluate these risk accordingly: + +1. More maintenance work. Apart from the validator, additional + maintenance of the Sentry service and its related network + components is required. + +2. Network risk. Due to Sentry service being exposed to the public + network, it is inevitably susceptible to possible network attacks. + +3. Financial risk. Validators need to pay fees to builders, securely + managing accounts is a crucial topic. + +After identifying these risks, let's begin the journey. + +## Validator Topology + +![Validator Topology](../assets/mev/mev-topology.png) + +It is suggested that to split the internal network into two part: + +1. Private network. The private network is isolated from the public + network. All access to components within this network is strictly + restricted. The Validator and Payment wallet are expected to be + deployed within a private network environment. + +2. Nat network. The components in this network can communicate with the + public internet under certain constraints, and the communication + can be established through load balancers provided by various + cloud platforms. Sentry service should be deployed within a NAT + network environment. It is essential to configure appropriate + safeguards on the network gateway to prevent DoS attacks and other + potential threats. + +## Preparation + +The BNB Chain community has maintained an open-source version of the +Sentry service. You can clone the code repository from +[here](https://github.com/bnb-chain/bsc-mev-sentry). + +Before actually deploying the Sentry service, it is crucial to carefully +consider and determine several key parameters: + +1. **BidFeeCeil.** This represents the maximum fee that a validator is + willing to pay for a block proposed by a builder. When this value + is 0, it signifies that the validator does not accept any charges + from the builder. + +2. **BidSimulationLeftOver.** This parameter indicates how long before + the block time the validator should cease simulating the blocks + from the builder. It is generally advisable to set it to a few + tens of milliseconds. Setting it too small may result in blocks + being broadcast too late and subsequently discarded during network + congestion. + +It is suggested that to purchase a domain that is related to the moniker +name of the validator. The builders will send requests through this +domain. A BSC account should be created in advance as the payment +account. No BNB is required in that account if **BidFeeCeil** is zero, +otherwise, it needs to be ensured that there is enough balance in the +account. + +Go to the [bsc-mev-info](https://github.com/bnb-chain/bsc-mev-info) +repo to find more information about running builders which will be used +during setup. + +## Quick Setup + +**Step 1**: **Setup Sentry.** + +Deploy the sentry service according to the readme of [sentry repo](https://github.com/bnb-chain/bsc-mev-sentry). + +Here are a few key points to highlight. + +- One sentry service can manage multiple validators. + +- The **PrivateURL** of validator is used by the sentry to access the + validator, it can be IP:Port or internal domain URL. + +- The **PublicHostName** of validator is used by the builder to access + the validator, the sentry will forward to different validators + according to different hostname of the request. + +- For each Builder, define its Address and public URL. The address + will be used to authorize the identity of builders. + +**Step 2: Change the Config of Validator.** + +Upgrade the validators to version v1.4.x or later, add a few new +sections in the config.toml. Example: + +```toml + [Eth.Miner.Mev] + Enabled = true # open bid receiving + ValidatorCommission = 100 # validator claim 1% from block reward + BidSimulationLeftOver = 50000000 # 50ms, the time left for bid simulation + SentryURL = "http://bsc-mev-sentry.io" # it is used for the validator to access the sentry, it should be a private URL or IP:Port. + + [[Eth.Miner.Mev.Builders]] + Address = "0x45EbEBe8...664D59c12" # builder address which validator is willing to receive bid from + + [[Eth.Miner.Mev.Builders]] + Address = "0x980A75eC...fc9b863D5" # builder address which validator is willing to receive bid from +``` + +**Step 3: Publish information** + +It is highly recommended to publish information in [bsc-mev-info](https://github.com/bnb-chain/bsc-mev-info) +so other builders can find it. + + \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 997369c080..372e013854 100644 --- a/sidebars.js +++ b/sidebars.js @@ -152,7 +152,18 @@ const sidebars = { //collapsible: true, collapsed: true, label: 'Validator', - items: ['validator/overview', 'validator/create-val', 'validator/run-val'], + items: ['validator/overview', 'validator/create-val', 'validator/run-val', + { + type: 'category', + label:'MEV', + items:[ + {type:'doc', id:'mev/overview', label:'Overview'}, + {type:'doc', id:'mev/validator-integration', label:'Validator Integration Guide'}, + {type:'doc', id:'mev/builder-integration', label:'Builder Integration Guide'}, + {type:'doc', id:'mev/faqs', label:'FAQs'}, + ] + } + ], }, { type: 'category',