docs: add docs for mev integration (#293)

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).

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.

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).

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.
+
+

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',