update content

BEPs/BEP322.md

@@ -16,7 +16,8 @@
         - [3.2 Workflow](#32-workflow)
         - [3.3 Payment & Economic Considerations](#33-payment--economic-considerations)
         - [3.4 APIs](#34-apis)
-    - [4. License](#4-license)
+    - [4. References](#4-references)
+    - [5. License](#5-license)
 
 ## 1. Summary
 
@@ -86,11 +87,16 @@ lead to different designs for these two networks.
 
 A setup phase is needed before builders submit transactions to validators:
 
-1) a validator will deploy a smart contract for builders to register. In the smart contract, the validator’s information
-   will be exposed (e.g., how to connect to a validator).
+1) a validator will deploy a smart contract (called as builder smart contract) for builders to register.
+   In the smart contract, the validator’s information will be exposed (e.g., how to connect to a validator).
 
 2) a builder will call the smart contract to register itself with builder wallet address and other information.
 
+To let builders know the smart contract address, a validator can put the information into BSC, i.e., adding the address
+into `Details` field when [creating/editing a validator](https://docs.bnbchain.org/docs/validator/create-val).
+Meanwhile, the registration interfaces are not included in this specification. However, [an example](#4-references)
+is presented to demonstrate this.
+
 ![workflow](./assets/bep-322/workflow_setup.png)
 
 After setup, during each block production interval, the overall workflow for proposing transactions is as follows:
@@ -106,21 +112,23 @@ After setup, during each block production interval, the overall workflow for pro
 
 5) the builder should return the full transactions.
 
-6) the proposer will append a transaction to deposit builder fee to its builder smart contract.
+6) the proposer will execute the full transactions and verify the gas value.
+
+7) 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).
 
-7) the proposer will seal a block using the transactions from the winning builder, if there is no profitable bid
+8) the proposer will seal a block using the transactions from the winning builder, if there is no profitable bid
    compared to local or the transactions do not return in time, the proposer can still seal a block using local
    transactions.
 
-8) 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).
+9) the proposer will append a transaction to record builder fee to its builder smart contract. This step is optional.
 
 ![workflow](./assets/bep-322/workflow_2round.png)
 
-For step 1, a builder can also submit a bid with transactions, then at step 4 a proposer
+In BSC, the time for producing a block is only 3 seconds. To reduce the latency, the following option is also supported
+in this specification. For step 1, a builder can also submit a bid with transactions, then at step 4 a proposer
 does not need to ask for transactions and can send the receipt in an asynchronous way or
-even do not send it. This option is also supported in this specification, as illustrated
-as the following figure.
+even do not send it.
 
 ![workflow](./assets/bep-322/workflow_1round.png)
 
@@ -146,7 +154,7 @@ Builder Specification here for the readers who are familiar with it.
   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 needs to append a transaction to deposit builder fee to
+  validator needs to append a transaction to record builder fee to
   its builder smart contract. It will be further discussed in the later section.
 
 #### 3.2.2 Edge Cases
@@ -205,18 +213,19 @@ be considered.
   the builder.
 
 For the payment between builders and validators, when a validator accepts
-a bid it needs to append one deposit transaction, in which the builder
-fee will be deposited. To support this transaction, the following should be satisfied:
+a bid, it needs to append one accounting transaction to record the builder fee.
+To support this transaction, the following should be satisfied:
 
 * the gas price of the transaction should be zero. Then a validator does not need to pay any gas for it.
 
 * the smart contract call can only be made by coinbase address.
 
 * the transaction should be reverted if there is any reorg.
 
-After deposit, a builder can claim its income from the contract without any interaction with the validator.
+After accounting, a builder can claim its income from the contract without any interaction with the validator.
 
-If a validator does not append the deposit transaction, a builder can still use the receipt (with validator’s signature)
+If a validator does not append the accounting transaction, a builder can still use the receipt (with validator’s
+signature)
 to ask for settlement using other approaches. If a validator does not pay a builder on purpose (i.e., misbehavior),
 then the builder can expose evidence about the misbehavior.
 
@@ -440,24 +449,7 @@ HTTP status code is 200
 
 The following APIs should be implemented on the validator side or BSC clients.
 
-##### 3.4.2.1 Register Builder
-
-A smart contract should be implemented on the validator side.
-Then a builder can call the smart contract to register itself.
-The contract interface looks like this.
-
-```solidity
-// register to a validator
-    function register(string baseUrl) external;
-
-// unregister from a validator
-    function unregister() external;
-
-// returns the base url of the validator
-    function baseUrl() external returns (string);
-```
-
-##### 3.4.2.2 Bid Block
+##### 3.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
@@ -525,27 +517,29 @@ HTTP status code is 200
 </tr>
 </table>
 
-##### 3.4.2.3 Deposit Builder Fee
+##### 3.4.2.2 Record Builder Fee
 
-After accepting a bid, a validator needs to append one deposit transaction to
-deposit builder fee to its builder smart contract. Then builders can claim
+After accepting a bid, a validator needs to append one accounting transaction to
+record builder fee to its builder smart contract. Then builders can claim
 their fee from the smart contract.
 
 ```solidity
-// for a validator to deposit
-    function deposit(uint256 groupId, address builderAddress, uint256 fee) external payable;
-
-// for a builder to claim its income    
-    function claim() external;
+// for a validator to record builder fee
+    function record(uint256 blockHeight, address builderAddress, uint256 fee) external payable;
 ```
 
-For `deposit` transaction,
+For `record` transaction,
 
 * it can be only executed by coinbase address.
 * its gas price should be zero.
 * it will be reverted when there is blockchain reorg.
 
-## 4. License
+## 4. References
+
+* [BSC Builder Specs](https://github.com/bnb-chain/builder-specs)
+* [Example Smart Contracts](https://github.com/bnb-chain/builder-specs/examples)
+
+## 5. License
 
 The content is licensed under
 [CC0](https://creativecommons.org/publicdomain/zero/1.0/).