BEP-322: Builder API Specification for BNB Smart Chain

BEPs/BEP322.md

@@ -22,7 +22,8 @@
     - [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 Issues Report](#4411-issues-report)
+        - [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)
@@ -45,14 +46,12 @@ proposing blocks.
 The Ethereum MEV market is thriving, with
 the [Ethereum Builder API Specification](https://github.com/ethereum/builder-specs&#41) 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&#41),
-indicating a robust ecosystem.
+approximately [90%](https://dune.com/ChainsightAnalytics/mev-after-ethereum-merge&#41).
 
 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, validators face significant hurdles when attempting
-to integrate with multiple MEV providers concurrently. Moreover, the absence of native support from the BSC clients
-further
-exacerbates the instability of MEV services. To tackle these issues, this BEP puts forward compliant guidelines and
+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
@@ -67,18 +66,18 @@ standards with the following aims:
 
 ## 3. Background
 
-Before delving into the specification, let's analyze the BSC trust model and its distinctive consensus protocol.
+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 a validator is relatively easier.
+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 MEV architecture, the 'relay' role is expected to be trusted by both builders and validators.
+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
@@ -90,17 +89,17 @@ the security and trust model for the MEV market between builders and validators.
 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 coinbase and depositing to the validator
-set contract), rendering it impossible for builders to broadcast the block.
+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
-  users and searchers (trusted by searchers and users for fair inclusion).
+  searchers and p2p network (trusted by searchers and users for fair inclusion).
 
-- **Proposer**: the party that signs and submits a block to the network, often referred to as the validator.
+- **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.
 
@@ -109,7 +108,10 @@ set contract), rendering it impossible for builders to broadcast the block.
     - **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)
 
@@ -125,11 +127,10 @@ 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,
-   even with the potential illegal transactions).
-4) If the bid turns out to be invalid, the proposer will use 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.
+   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
@@ -150,10 +151,11 @@ trust validator and are not concerned about the additional latency caused by one
 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,
-   even with potential illegal transactions).
-5) If the bid turns to be invalid, the proposer will use 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.
+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:
@@ -174,8 +176,7 @@ which should be different from the validator's consensus wallet, and append a tr
 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 real adoption.
+layer in front of itself in production.
 
 <img src="https://raw.githubusercontent.com/bnb-chain/BEPs/473fb9e9372cbd0fc58d2d58a0e5d79fab1e5552/BEPs/assets/bep-322/workflow_2round_proxy.png" alt="workflow" width="1000"/>
 
@@ -206,7 +207,56 @@ in [a repo with swagger and smart contracts](https://github.com/bnb-chain/builde
 
 The following APIs should be implemented on Builder.
 
-##### 4.4.1.1 Issues Report
+##### 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.
@@ -281,8 +331,11 @@ Response:
 ```json
 {
   "jsonrpc": "2.0",
-  "result": "the bid hash",
-  "id": 64
+  "id": 64,
+  "error": {
+    "code": -38005,
+    "message": "the validator is not in-turn to propose currently, try again later"
+  }
 }
 ```
 
@@ -299,12 +352,11 @@ so a switch should be considered to turn on/off the feature based on its choice.
 
 ### 5.2 Payment & Economic Considerations
 
-A part of BSC's consensus protocol operates as follows: Block proposers initiate transactions by transferring block
-rewards to the validator set contract. During the breathing block at midnight each day, block rewards are distributed to
-delegators and validators based on the staked amounts. **This distribution mechanism is also applicable to MEV income.**
+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
 
-Without changing bsc consensus rule, the following approaches can be taken for the payment from users to builders,
-off-chain or on-chain solutions can be considered:
+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.
@@ -333,9 +385,10 @@ Furthermore, let's also discuss what will happen if a builder or a validator mis
 
 ### 5.3 Builder Registration
 
-While this specification doesn't detail the registration process for builders with validators, it does propose a
-promising solution: employing a smart contract for builder registration. In BSC, one smart contract can be implemented
-to provide the following functionalities:
+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.
@@ -352,4 +405,4 @@ for all related stakeholders. An [example](#6-references) is presented to demons
 ## 7. License
 
 The content is licensed under
-[CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).