+ 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. Specification](#3-specification) + - [3.1 Trust Model](#31-trust-model) + - [3.2 Workflow](#32-workflow) + - [3.3 Payment & Economic Considerations](#33-payment--economic-considerations) + - [3.4 APIs](#34-apis) + - [4. License](#4-license) + +## 1. Summary + +In Ethereum, a [builder](https://github.com/ethereum/builder-specs) orders transactions from users/searchers and submits +them to consensus +layer clients for proposing new blocks. This BEP introduces a builder +api specification for running builders on BNB Smart Chain. This +specification mainly defines the communication workflow and the +application interfaces between builders and validators, as well as the +economic considerations for real adoptions. + +## 2. Motivation + +The specification is defined in [Ethereum Builder API +Specification](https://github.com/ethereum/builder-specs), and it has been supported by almost all the mainstream +Ethereum consensus clients. Nowadays, the inclusion rate of blocks from builders +is [about 90%](https://dune.com/ChainsightAnalytics/mev-after-ethereum-merge) (based on the statistics of October 2023). + +However, on BNB Smart Chain, there is no such specification yet. By +introducing such a specification, it will resolve some problems as well +as bring new benefits for the ecosystem. + +- Firstly, currently validators are using different customized + implementations for MEV with different levels of quality, which + brings instability to the network. With a specification, it will + provide guidelines and standards to follow, minimizing the + instability issues. + +- Secondly, validators can only integrate with a single MEV provider + now, due to the lack of support on BSC clients. With this + specification, validators can integrate with multiple builders at + the same time. + +- Thirdly, this specification will also bring transparency to + different stakeholders, including BNB delegators. With the + adoption of builders, it is probable that delegators can earn more + because builders are supposed to submit more profitable blocks. + +## 3. Specification + +### 3.1 Trust Model + +Before we move on to the design of Builder Specification, let's have an +analysis of the BSC trust model and compare it to Ethereum, for it will +affect how the design works and differentiate the designs in these two +networks. + +- Validators are more trustworthy in BNB Smart Chain. In BSC, the + validators should delegate a lot of BNB (more than 10 thousand in + general) and maintain a high reputation. Misbehaviour will lead to + reputation damage and un-delegations. Currently, there are about + 40 validators with 20M BNB staked, including active and inactive + ones. In Ethereum, the barrier to becoming a validator is very + low (i.e., 32 ETH), and there are more than [800 thousand Ethereum + validators](https://www.nasdaq.com/articles/the-most-pressing-issue-on-ethereum-is-validator-size-growth). + It means that a validator can be anyone, and it can enter or quit + easily. That's quite different from BSC. + +- Meanwhile, the relay role in Ethereum Builder API is supposed to be + trusted by both builders and validators. In BSC, the necessity of + introducing another trusted role is not that much. In this + specification, we don't utilize relay; however, it is still + workable to add relay between builders and validators. + +### 3.2 Workflow + +#### 3.2.1 Overall Workflow + + + +The overall workflow is as follows: + +1) a validator registers itself to a builder with some preferences + (e.g., gas limit). + +2) the builder will save the validator's information. + +3) the builder will respond to the request with success or failure. + +4) after registration, during each block production interval, a builder + will submit a bid to the current proposer or multiply registered validators. + +5) the proposer should respond to success if the bid is successfully received. + +6) the proposer will select one bid from all bids according to the max value it can extract. + +7) the proposer will ask the builder for full transactions if its bid is chosen, it also gives the builder its signature + as a receipt. The receipt can be used for payment settlement. + +8) the builder should return the full transactions. + +9) the proposer will seal a block using the transactions from the + winning builder, if there is no bid or the transactions do not + return in time, the proposer can still seal a block using local transactions. + +10) the proposer will notify the builder if something is wrong (e.g., + timeout to retrieve transitions from the builder, or the proposed + block is invalid). + +Here, we would like to highlight some main differences between Ethereum +Builder Specification here for the readers who are familiar with it. + +- In Ethereum, a block header is passed from a builder to a validator + for sign, and then a block can be broadcast to the network + without revealing the transactions to a validator. In BSC, to + generate a valid block header, transactions in the block should be + executed as well as several system contract calls (e.g., transfer + coinbase, deposit to the validator set contract), it is not possible for a + builder to do these. Meanwhile, as mentioned in the previous + section, the trust model in BSC is different to Ethereum; it is + workable 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 for + social influence. + +- In Ethereum, the fee settlement between builders and validators is + conducted using coinbase reward (for reward to builders) and token + transfer (for 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 and a builder can do the payment settlement via the + receipts which contain the validator's signatures through + off-chain or on-chain (e.g., smart contracts). It will be further + discussed in the later section. + +#### 3.2.2 Edge Cases + +For the two-way and multiple round communication between builders and +validators, there could be some special cases. + +- If the validator cannot receive full transactions before timeout, + the validator should 1) notify the builder using issue api (see + later more details), 2) refuse the builder's bids for a while or + even forever. + +- If a validator finds the transactions from a builder is invalid, + the validator should 1) notify the builder using api calls, 2) + refuse the builder's bids for a while or even forever. + +- If a builder finds that its transactions are stolen by the + validator, the builder 1) can still get its builder fee for it + already gets the validator's signature for payment, 2) refuses to + send bids to the validator, 3) discloses the steal to public + channels for social influences if necessary. + +#### 3.2.3 Implementation Considerations + +Firstly, on BSC, the blocking time is only 3 seconds, which means a +validator must set a cut-off time to stop receiving new bids, and a +timeout to retrieve transactions from the winning builder. + + + +Secondly, a validator can choose to participate in or not. The +implementation should support a validator to turn on/off the feature +based on its choice. + +### 3.3 Payment & Economic Considerations + +On BNB Smart Chain, the coinbase reward must be distributed to the block +proposer (i.e., a validator) and transferred to a system contract. +Without changing the consensus rule, these following approaches can be +taken for payment. + +For payment from users to builders, off-chain or 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 builder can settle +with validators via the receipts (when asking for full transactions from +a builder, a receipt with a validator's signature must be disclosed to +the builder) off-chain or on-chain (e.g., smart contracts). Because the +builder fee is paid by validators (not all the delegators), validators +can evaluate and increase the commission rate if needed. + +For the payment, we propose the following smart contract interfaces if +on-chain approach is used: + +```solidity +// to allow validator deposit + function deposit() external payable; + +// to allow builder claim builder fee + function claim(uint256 block, uint256 timestamp, + address builder, address validator, + uint256 gasValue, uint256 builderFeeValue, + bytes transactionMerkleRoot, bytes signature) external; +``` + +Be noted, in the claim function, the `signature` field is the +signature of all other parameters (e.g., builderFeeValue) from a +proposer. When asking for full transactions from a builder, the builder +will receive the signature and the builder can claim its reward. + +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 full 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, consequently 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 and stop + sending bids to the validator, and also can 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. + +### 3.4 APIs + +Following APIs are introduced on Builder and BSC client sides, to +implement the aforementioned workflows. The full specification of these +APIs is defined in [a repo with swagger and smart +contracts](https://github.com/bnb-chain/builder-specs). + +#### 3.1.1 Builder APIs + +The following APIs should be implemented on Builder. + +##### 3.1.1.1 Register Validator + +A smart contract should be implemented on the builder side. Then a +validator can call the smart contract to register itself. The contract +interface looks like this. + +```solidity +// register to a builder + function register(int256 gasLimit, string baseUrl) external; + +// unregister from a builder + function unregister() external; + +// returns the base url of the builder + function baseUrl() external view returns (string); +``` + +##### 3.1.1.2 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. + +
| Path | +/bsc/v1/builder/txs | +
| Http Method | +POST | +
| Request Body | +
+
+
+ |
+
| Success Response | +
+
+
+ |
+
| Error Response | +
+
+
+ |
+
| Path | +/bsc/v1/builder/status | +
| Http Method | +GET | +
| Request Body | ++N/A + | +
| Success Response | ++HTTP status code is 200 + | +
| Error Response | +
+
+
+ |
+
| Path | +/bsc/v1/builder/issues | +
| Http Method | +POST | +
| Request Body | +
+
+
+ |
+
| Success Response | ++HTTP status code is 200 + | +
| Error Response | +
+
+
+ |
+
| Path | +/bsc/v1/builder/bid | +
| Http Method | +POST | +
| Request Body | +
+
+
+ |
+
| Success Response | ++HTTP status code is 200 + | +
| Error Response | +
+
+
+ |
+