diff --git a/BEPs/BEP322.md b/BEPs/BEP322.md deleted file mode 100644 index eb84ee14..00000000 --- a/BEPs/BEP322.md +++ /dev/null @@ -1,417 +0,0 @@ -
- BEP: 322 - Title: Builder API Specification for BNB Smart Chain - Status: Draft - Type: Standards - Created: 2023-11-15 -- -# BEP-322: Builder API Specification for BNB Smart Chain - - - -- [BEP-322: Builder API Specification for BNB Smart Chain](#bep-322-builder-api-specification-for-bnb-smart-chain) - - [1. Summary](#1-summary) - - [2. Motivation](#2-motivation) - - [3. Background](#3-background) - - [3.1 BSC Trust Model](#31-bsc-trust-model) - - [3.2 BSC Consensus](#32-bsc-consensus) - - [4 Workflow](#4-workflow) - - [4.1 Definition](#41-definition) - - [4.2 One-Round Interaction (default)](#42-one-round-interaction-default) - - [4.3 Two-Round Interaction (optional)](#43-two-round-interaction-optional) - - [4.4 APIs](#44-apis) - - [4.4.1 Builder APIs](#441-builder-apis) - - [4.4.1.1 Retrieve Transactions](#4411-retrieve-transactions) - - [4.4.1.2 Issues Report](#4412-issues-report) - - [4.4.2 Validator APIs](#442-validator-apis) - - [4.4.2.1 Bid Block](#4421-bid-block) - - [5. Further Discussion](#5-further-discussion) - - [5.1 Implementation Consideration](#51-implementation-consideration) - - [5.2 Payment \& Economic Considerations](#52-payment--economic-considerations) - - [5.3 Builder Registration](#53-builder-registration) - - [6. References](#6-references) - - [7. License](#7-license) - - - -## 1. Summary - -This BEP introduces a suite of interaction processes and API specifications to establish a fairer and more transparent -MEV framework on the BNB Smart Chain. Participants can follow this specification to collaborate on building and -proposing blocks. - -## 2. Motivation - -The Ethereum MEV market is thriving, with -the [Ethereum Builder API Specification](https://github.com/ethereum/builder-specs)) widely supported by -mainstream consensus clients. As of October 2023, the inclusion rate of blocks from builders is -approximately [90%](https://dune.com/ChainsightAnalytics/mev-after-ethereum-merge)). - -The BNB Smart Chain MEV market still remains at a Wild West stage. The absence of PBS adoption results in a chaotic -landscape with different architectures and API standards. Nowadays, it is very challenging for validators to -to integrate with multiple MEV providers. Moreover, the absence of native support from the BSC clients -further exacerbates the instability of MEV services. To tackle these issues, this BEP proposes compliant guidelines and -standards with the following aims: - -- **Improve Stability**: Unified specifications for both validators and MEV providers to enhance integration and - stabilize the market. - -- **Improve Economy**: A unified architectural specification increases speculators' costs, fostering a healthy market - competition. Validators can extract more value by integrating with multiple MEV providers, which benefits delegators - as well. - -- **Improve Transparency**: This specification aims to bring transparency to the BSC MEV market, exposing profit - distribution among stakeholders to the public. - -## 3. Background - -Before diving into the specification, let's analyze the BSC trust model and its distinctive consensus protocol. - -### 3.1 BSC 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. -As of the end of 2023, there were approximately 40 validators on BSC (with more expected to join) and a total of -20 million BNB staked. In Ethereum, the barrier to becoming a validator is very low (i.e., 32 ETH), leading to over -800,000 Ethereum validators according -to [Nasdaq](https://www.nasdaq.com/articles/the-most-pressing-issue-on-ethereum-is-validator-size-growth). - -Meanwhile, in the Ethereum PBS architecture, the 'relay' role is expected to be trusted by both builders and validators. -However, in BSC, validator misbehavior results in reputation damage and un-delegations, reducing the need for -introducing -another trusted role. In this specification, we eliminate the 'relay' role. However, this adjustment should not -compromise -the security and trust model for the MEV market between builders and validators. - -### 3.2 BSC Consensus - -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. - -## 4 Workflow - -### 4.1 Definition - -- **Builder**: the party that specializes in the construction of BSC execution payloads using transactions received from - searchers and p2p network (trusted by searchers and users for fair inclusion). - -- **Proposer**: the party that signs and submits a block to the network, referred to as the validator. - -- **Mev-sentry**: the party that runs in front of a validator to proxy requests and enhance network security. - -- **Bid**: used by a builder to do competitive bidding for a block space. A bid should include the following - information: - - **block_number**. The height of the block. - - **parent_hash**. The hash of the parent block. - - **gas_fee**. The total gas fee of the bid. - - **gas_used**. The total gas used of the bid. - - **builder_fee**. The fee that the builder would like to take from the validator. - - **txs**. The transaction list in the bid(optional). - - **signature**. The signature of the bid. - -### 4.2 One-Round Interaction (default) - -Builders and validators collaborate to propose blocks during each block production interval. Two interaction options -exist -between them: one-round and two-round. With one-round, builders include transactions with their bids, allowing -validators -to immediately seal a block without additional transaction retrieves. *One-round is the default option for trusted -relationship*. - - - -1) Builders submit bids with transactions to the in-turn validator. -2) The validator picks the most valuable bid from all received within a predefined time. -3) The validator executes the full transactions and verifies the bid (gas received is the same as what claimed in the - bid). -4) If the bid turns out to be invalid, the proposer will use other bid or a locally mined block and also report - detailed errors to the builder. The validator may blacklist the builder for some time or forever if the builder - offers invalid bid. -5) The validator seals the final block. - -In practical settings, opting for a **One-round with MEV-Sentry (optional)** configuration stands out as the optimal -solution -for ensuring both security and efficient payment processes. Subsequently, we will delve into the specific role that -MEV-Sentry can fulfill in the upcoming section. - -### 4.3 Two-Round Interaction (optional) - -Two-round interaction involves builders sending bids without transactions initially. If selected, validators retrieve -transactions through another RPC call before sealing the block. The two-round process is considered more time-consuming -compared to the one-round interaction. *It's suggested to adopt two-round interaction for builders who do not fully -trust validator and are not concerned about the additional latency caused by one extra round of communication.* - - - -1) Builders submit bids without transactions to the in-turn validator. -2) The validator picks the most valuable bid from all received bids within a predefined time. -3) The Validator asks the builder for corresponding transactions related to the chosen bid, and also gives the builder - its signature as a receipt. The builder should return the full list of transactions. -4) The validator executes the transactions and verifies the bid (gas received is the same as what is claimed in the - bid). -5) If the bid turns to be invalid, the proposer will use other bid or a locally mined block and also report detailed - errors to the builder. The validator may blacklist the builder for some time or forever if the builder offers invalid - transactions. -6) The validator seals the final block. - -There are some **edge cases** should be elaborated: - -- If there is no profitable bid compared to local work, the validator should use locally mined block. - -- In two-round interaction, if the validator cannot receive the full list of transactions before timeout, the - validator should use the locally mined block too, and 1) notify the builder using issue report API; 2) blacklist - the builder for a while or even forever. - -- If a builder finds that its transactions are stolen by a validator, the builder should 1) refuse to send bids - to the validator, 2) disclose the steal to public channels for social influences if necessary. - -**Two-Round with MEV-Sentry(optional)** interaction: - -A MEV-Sentry can be used for validators to provide several functionalities. The sentry has its own wallet, -which should be different from the validator's consensus wallet, and append a transfer transaction to send builder fee. -It can also filter bids and only forward the more profitable ones to a validator. Meanwhile, a validator needs to -interact with many builders at the same time, sentry helps to hide the validator’s real IP -information and protect against DDoS and other threats. Therefore, it is highly suggested for validators to run such a -layer in front of itself in production. - - - -After introducing the overall interactions, we would like to highlight some main differences between Ethereum -Builder Specification here for the readers who are familiar with it. - -- As mentioned in the background, the BSC trust model and consensus are different from Ethereum, it is justifiable for - builders to - send transactions to validators after receiving the receipt signature. In case a builder finds a validator stealing - transactions, it can 1) not submit bids to evil validators anymore, 2) reveal evidence to the public channels - (e.g., Discords, Github, blogs) for social influence. - -- In Ethereum, the fee settlement between builders and validators is conducted using the 'coinbase' reward (for reward - to - builders) - and token transfer (for the fee to validators). In BSC, the coinbase reward will be transferred to the system contract - for - later distribution to all delegators. A different way is proposed in this proposal, a validator can run an MEV-Sentry - to append a transfer transaction for payment. It will be further discussed in the later section. - -### 4.4 APIs - -The following APIs are introduced on Builder and BSC client sides, to implement the aforementioned workflows. -The full specification of these APIs are defined -in [a repo with swagger and smart contracts](https://github.com/bnb-chain/builder-specs). - -#### 4.4.1 Builder APIs - -The following APIs should be implemented on Builder. - -##### 4.4.1.1 Retrieve Transactions - -This api is used by the validator to ask for full transactions once a builder's bid is chosen. The request body will be -treated as a receipt for payment settlement. - -Request: - -```json -{ - "jsonrpc": "2.0", - "method": "mev_retrieveTransactions", - "params": [ - { - "bid": { - "block": "the block number", - "parentHash": "the hash of the parent block", - "gasFee": "the total gas fee of the bid", - "gasUsed": "the total gas used of the bid", - "builderFee": "the fee that the builder would like to take from the validator" - }, - "signature": "the signature of the bid" - } - ], - "id": 1 -} -``` - -Response: - -```json -{ - "jsonrpc": "2.0", - "result": { - "bid": { - "block": "the block number", - "parentHash": "the hash of the parent block", - "gasFee": "the total gas fee of the bid", - "gasUsed": "the total gas used of the bid", - "builderFee": "the fee that the builder would like to take from the validator", - "txs": [ - "the transactions in the bid" - ] - }, - "signature": "the signature of the bid" - }, - "id": 1 -} -``` - -##### 4.4.1.2 Issues Report - -This API is used to report issues to a builder. For example, if a validator finds that a builder's transactions are -invalid or the transaction API is timeout-ed, a validator can notify the builder. - -Request: - -```json -{ - "jsonrpc": "2.0", - "method": "mev_reportIssue", - "params": [ - { - "validator": "validator address", - "bidHash": "hash of the bid", - "error": { - "code": -38001, - "message": "response message" - } - } - ], - "id": 1 -} -``` - -Response: - -```json -{ - "jsonrpc": "2.0", - "result": null, - "id": 1 -} -``` - -#### 4.4.2 Validator APIs - -The following APIs should be implemented on the validator side or BSC clients. - -##### 4.4.2.1 Bid Block - -This API is used by the builder to submit its bid for the current block production. In general, a proposer will use the -`gas_fee` and `builder_fee_value` (`profit = gas_fee * validator_commission_rate - builder_fee_value`) to find the most -profitable bid. - -Request: - -```json -{ - "jsonrpc": "2.0", - "method": "mev_sendBid", - "params": [ - { - "bid": { - "block_number": 123456, - "parent_hash": "the hash of the parent block", - "txs": [ - "the transactions in the bid" - ], - "gasUsed": 100, - "gasFee": 100000000000, - "builderFee": 100000000000 - }, - "signature": "the signature of the bid" - } - ], - "id": 64 -} -``` - -Response: - -```json -{ - "jsonrpc": "2.0", - "id": 64, - "result": "the hash of the bid" -} -``` - -or some error: -```json -{ - "jsonrpc": "2.0", - "id": 64, - "error": { - "code": -38005, - "message": "the validator is not in-turn to propose currently, try again later" - } -} -``` - -## 5. Further Discussion - -### 5.1 Implementation Consideration - -With a shorter block time of 3 seconds in BSC compared to Ethereum's 12 seconds, designing for time efficiency becomes -crucial. Validators must set a cut-off time to stop receiving new bids, and a timeout to retrieve transactions from -the winning builder. To be more flexible, validators can choose to run a node with or without support for builders, -so a switch should be considered to turn on/off the feature based on its choice. - - - -### 5.2 Payment & Economic Considerations - -On the BNB Smart Chain, the block reward will be transferred to a system contract by consensus engine and distributed to -delegators and validators based on the staked amount every day. **This distribution mechanism is also applicable to MEV -income.** Without changing bsc consensus rule, the following approaches can be taken for payment - -or the payment from users to builders,both off-chain and on-chain solutions can be considered: - -- Users can subscribe to builders' service. For example, users can pay builder service every month based on different - levels of prices. - -- Users can insert a transfer transaction into his/her bundles to pay the builder. - -For the payment between builders and validators: - -- A validator can run a proxy and append transfer transactions to pay builders. If a validator does not append the - transfer transaction, a builder can still use the receipt (with the validator’s signature) to ask for settlement using - other approaches. - -- A validator and a builder can negotiate other off-chain and on-chain approaches that are out of the scope of the - specification. - -Furthermore, let's also discuss what will happen if a builder or a validator misbehaves. - -- If a builder wins a bid and does not return the full list of transactions to a validator, the validator can easily - detect this - and stop service for the builder. Eventually, the builder will get no income from block production and users - will also leave the builder. - -- If a validator steals transactions from a builder when there is potential value. The victim builder can detect this. - It can stop sending bids to the validator and post evidence (i.e., the signature from a validator) about the - misbehavior. The validator will lose the income from the builder and even more builders. - -### 5.3 Builder Registration - -The process for builders to register to validators is not defined in this specification. However, a promising solution -is highlighted and suggested–using a smart contract for builder registration. - -In BSC, one smart contract can be implemented to provide the following functionalities: - -- a validator can register its information (e.g., consensus address, proxy URL) for participation. -- a builder can deposit some amount of BNB for participation. -- a builder can register to validators by providing its information (e.g., builder address). - -With this kind of smart contract, builders and validators can discover each other easily. It also provides transparency -for all related stakeholders. An [example](#6-references) is presented to demonstrate such a smart contract. - -## 6. References - -* [BSC Builder Specs](https://github.com/bnb-chain/builder-specs) -* [Example Smart Contracts](https://github.com/bnb-chain/builder-specs/examples) - -## 7. License - -The content is licensed under -[CC0](https://creativecommons.org/publicdomain/zero/1.0/). \ No newline at end of file diff --git a/BEPs/assets/bep-322/block_timing.png b/BEPs/assets/bep-322/block_timing.png deleted file mode 100644 index 40f197bf..00000000 Binary files a/BEPs/assets/bep-322/block_timing.png and /dev/null differ diff --git a/BEPs/assets/bep-322/workflow_1round.png b/BEPs/assets/bep-322/workflow_1round.png deleted file mode 100644 index 7d0fc6e0..00000000 Binary files a/BEPs/assets/bep-322/workflow_1round.png and /dev/null differ diff --git a/BEPs/assets/bep-322/workflow_2round.png b/BEPs/assets/bep-322/workflow_2round.png deleted file mode 100644 index c04ac890..00000000 Binary files a/BEPs/assets/bep-322/workflow_2round.png and /dev/null differ diff --git a/BEPs/assets/bep-322/workflow_2round_proxy.png b/BEPs/assets/bep-322/workflow_2round_proxy.png deleted file mode 100644 index 9ffce46a..00000000 Binary files a/BEPs/assets/bep-322/workflow_2round_proxy.png and /dev/null differ diff --git a/BEPs/assets/bep-322/workflow_topology.png b/BEPs/assets/bep-322/workflow_topology.png deleted file mode 100644 index 4fcce753..00000000 Binary files a/BEPs/assets/bep-322/workflow_topology.png and /dev/null differ