BEP-322: Builder API Specification for BNB Smart Chain

[forcodedancing]

BEP-322: Builder API Specification for BNB Smart Chain

• BEP-322: Builder API Specification for BNB Smart Chain
  • 1. Summary
  • 2. Motivation
  • 3. Specification
    • 3.1 BSC Trust Model
    • 3.2 Workflow
    • 3.3 Payment & Economic Considerations
    • 3.4 APIs
  • 4. References
  • 5. License

1. Summary

In Ethereum, a builder 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 Ethereum Builder API
Specification has been supported by almost all the mainstream
Ethereum consensus clients. Nowadays, the inclusion rate of blocks from builders
is about 90% (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.

• Improve stability of network: 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.

• Improve MEV economy by building MEV market: 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.

• Improve transparency: 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 BSC 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. It will
lead to different designs for 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 (more validators are coming) 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.
  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

A setup phase is needed before builders submit transactions to validators:

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.
Meanwhile, the registration interfaces are not included in this specification. However, an example
is presented to demonstrate this.

After setup, during each block production interval, the overall workflow for proposing transactions is as follows:

1. builders will submit bids to the current proposer or multiple registered validators.

2. the proposer should respond successfully if the bid is successfully received.

3. the proposer will select one bid from all bids according to the max value it can extract.

4. the proposer will ask the builder for full transactions if its bid is chosen, it also gives the builder its signature
   as a receipt.

5. the builder should return the full transactions.

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).

8. the proposer will append a transaction to record builder fee to its builder smart contract. This step is optional.

9. 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.

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.

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 (e.g., chatting groups, github, blogs) 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 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

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 run a node with or without support for builder.
The implementation should support a validator to turn on/off the feature
based on its choice.

Thirdly, for a validator it needs to interact with many builders at the same time.
To protect validators, a proxy layer could be implemented to hide validator’s real
IP information, against DDoS, and others.

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, when a validator accepts
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 accounting, a builder can claim its income from the contract without any interaction with the validator.

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.

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.

3.4.1 Builder APIs

The following APIs should be implemented on Builder.

3.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.

Path	/bsc/v1/builder/txs
Http Method	POST
Request Body	{ "message": { "block": "height of the block", "timestamp": "timestamp", "transaction_merkle_root": "merkle root of transactions", "gas_value": "gas value for this block", "builder_fee_value": "the fee that builder would like to give", "builder_address": "builder address", "consensus_address": "validator consensus address", }, "signature": "signature of the message", "return_transactions": "the builder should transactions back or not" }
Success Response	{ "message": { "timestamp": "timestamp", "bid":{ "block": "height of the block", "builder_address": "builder address", "gas_value": "gas value for this block", "builder_fee_value": "the fee that builder would like to give", "transaction_merkle_root": "merkle root of transactions", "transaction_count": "total count of transactions" }, "transactions": [ {}, {}, {} ] }, "signature": "signature of the message" }
Error Response	{ "code": 400, //example here, there are others "message": "response message" }

3.4.1.2 Query Status

This api is used to check the status of a builder.

Path	/bsc/v1/builder/status
Http Method	GET
Request Body	N/A
Success Response	HTTP status code is 200
Error Response	{ "code": 400, //example here, there are others "message": "response message" }

3.4.1.3 Notify Issues

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 txs
api is timeout-ed, a validator can notify the builder.

Path	/bsc/v1/builder/issue
Http Method	POST
Request Body	{ "message": { "issue_code": "code the predefined issues", "timestamp": "timestamp", "consensus_address": "validator consensus address" }, "signature": "signature of the message" }
Success Response	HTTP status code is 200
Error Response	{ "code": 400, //example here, there are others "message": "response message" }

3.4.2 Validator APIs

The following APIs should be implemented on the validator side or BSC clients.

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
builder_fee_value (profit = gas_fee * validator_commission_rate - builder_fee_value) to
find the most profitable bid.

Path	/bsc/v1/builder/bid
Http Method	POST
Request Body	{ "message": { "block": "height of the block", "timestamp": "timestamp", "builder_address": "builder address", "gas_value": "gas value for this block", "builder_fee_value": "the fee that builder would like to get", "transaction_merkle_root": "merkle root of transactions", "transaction_count": "total count of transactions" }, "signature": "signature of the message", "transactions": [ //optional {}, {}, {} ] }
Success Response	HTTP status code is 200
Error Response	{ "code": 400, //example here, there are others "message": "response message" }

3.4.2.2 Record Builder Fee

After accepting a bid, a validator needs to append one accounting transaction to
book-keep builder fee to its builder smart contract.

// for a validator to record builder fee
    function bookkeep(uint256 blockHeight, address builderAddress, uint256 fee) external;

For bookkeep 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. References

• BSC Builder Specs
• Example Smart Contracts

5. License

The content is licensed under
CC0.

[forcodedancing]

The latest version is https://github.com/bnb-chain/BEPs/pull/322