diff --git a/BEPs/BEP322.md b/BEPs/BEP322.md new file mode 100644 index 00000000..eb84ee14 --- /dev/null +++ b/BEPs/BEP322.md @@ -0,0 +1,417 @@ +
+	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*. + +workflow + +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.* + +workflow + +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. + +workflow + +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. + +block_timing + +### 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 new file mode 100644 index 00000000..40f197bf Binary files /dev/null and b/BEPs/assets/bep-322/block_timing.png differ diff --git a/BEPs/assets/bep-322/workflow_1round.png b/BEPs/assets/bep-322/workflow_1round.png new file mode 100644 index 00000000..7d0fc6e0 Binary files /dev/null and b/BEPs/assets/bep-322/workflow_1round.png differ diff --git a/BEPs/assets/bep-322/workflow_2round.png b/BEPs/assets/bep-322/workflow_2round.png new file mode 100644 index 00000000..c04ac890 Binary files /dev/null and b/BEPs/assets/bep-322/workflow_2round.png differ diff --git a/BEPs/assets/bep-322/workflow_2round_proxy.png b/BEPs/assets/bep-322/workflow_2round_proxy.png new file mode 100644 index 00000000..9ffce46a Binary files /dev/null and b/BEPs/assets/bep-322/workflow_2round_proxy.png differ diff --git a/BEPs/assets/bep-322/workflow_topology.png b/BEPs/assets/bep-322/workflow_topology.png new file mode 100644 index 00000000..4fcce753 Binary files /dev/null and b/BEPs/assets/bep-322/workflow_topology.png differ