BEP-322: Builder API Specification for BNB Smart Chain #322

forcodedancing · 2023-11-15T09:17:30Z

	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

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 widely supported by
mainstream consensus clients. As of October 2023, the inclusion rate of blocks from builders is
approximately 90%.

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.

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.

Builders submit bids with transactions to the in-turn validator.
The validator picks the most valuable bid from all received within a predefined time.
The validator executes the full transactions and verifies the bid (gas received is the same as what claimed in the
bid).
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.
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.

Builders submit bids without transactions to the in-turn validator.
The validator picks the most valuable bid from all received bids within a predefined time.
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.
The validator executes the transactions and verifies the bid (gas received is the same as what is claimed in the
bid).
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.
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.

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.

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:

{
  "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:

{
  "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:

{
  "jsonrpc": "2.0",
  "method": "mev_reportIssue",
  "params": [
    {
      "validator": "validator address",
      "bidHash": "hash of the bid",
      "error": {
        "code": -38001,
        "message": "response message"
      }
    }
  ],
  "id": 1
}

Response:

{
  "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:

{
  "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:

{
  "jsonrpc": "2.0",
  "id": 64,
  "result": "the hash of the bid"
}

error example:

{
  "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.

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 is presented to demonstrate such a smart contract.

6. References

7. License

The content is licensed under
CC0.

48ClubIan · 2023-11-16T17:27:19Z

Regarding 3.1 Trust Model

Since there are much fewer validators on BSC, we should pay much more attention on ddos.

A standard relay (or proxy) implement at validators' side may be necessary for hiding actual address.

Regarding 3.2.1 Overall Workflow

7) receipt is given before step 8) when txs are received and 9) finally sealed. There could be misalign.

If this kind of misalign is acceptable, instead of actively retriving txs from builder (or relayer), I think it makes more sense to just alow builder to send txs directly, at least this should be an option.

Regarding 3.2.2 Edge Cases

Detect/Notify/Refuse/Disclose sounds too weak to act a valid punishment.

I start to think registering to be a builder with deposit on-chain is a good idea...

Regarding 3.3 Payment & Economic

I find it strange that the builder are supposed to charge the validators. 

Why are they charging validators given they already charge end-users ?

Regarding 3.4 APIs
All sub title numbers are incorrect.
3.1.1 should be 3.4.1 etc

3.1.1.1 Register Validator
This is an off-chain behavior anyway, should not be defined in BEP. Builders can accept registration in the way they prefered.

forcodedancing · 2023-11-23T09:29:29Z

@48ClubIan Some thinking about your points. Thanks.

Regarding 3.1 Trust Model
Since there are much fewer validators on BSC, we should pay much more attention on ddos.

A standard relay (or proxy) implement at validators' side may be necessary for hiding actual address.

Make sense. Proxy is not much touched in the spec, however we can put a proxy in front of a validator in implementation to against ddos. This is updated in the latest draft BEP.

Regarding 3.2.1 Overall Workflow
7) receipt is given before step 8) when txs are received and 9) finally sealed. There could be misalign.

If this kind of misalign is acceptable, instead of actively retriving txs from builder (or relayer), I think it makes more sense to just alow builder to send txs directly, at least this should be an option.

Both 2 round and 1 round interactions are supported. For one round interaction, a builder can send transactions and bid information together.

Regarding 3.2.2 Edge Cases
Detect/Notify/Refuse/Disclose sounds too weak to act a valid punishment.

I start to think registering to be a builder with deposit on-chain is a good idea...

There are several considerations 1) no benefit for a builder to do something wrong, 2) if a validator finds a builder doing something wrong, it can refuse the builder.

For the latest draft, a validator will create a smart contract for a builder to register. The implementation is not defined in the spec. A validator can ask his builder for a deposit if needed.

Regarding 3.3 Payment & Economic
I find it strange that the builder are supposed to charge the validators. 

Why are they charging validators given they already charge end-users ?

Two points about this 1) builder can help validator produce more profitable blocks 2) validator selects bids with the highest block - which means a builder needs to reduce its builder fee for competitiveness 3) builder fee can be zero in this spec.

Regarding 3.4 APIs
All sub title numbers are incorrect.
3.1.1 should be 3.4.1 etc

Fixed.

3.1.1.1 Register Validator
This is an off-chain behavior anyway, should not be defined in BEP. Builders can accept registration in the way they prefered.

For registration, currently there could be a smart contract to provide transparency. The implementation is not restricted in the draft BEP.

BEPs/BEP322.md

greyireland · 2024-02-21T13:14:12Z

Is it allowed to query the maximum bid of the current block? You can know the real-time bid of the current block on ETH, allowing real-time competition between builders.

Flashbots relay API: https://flashbots.github.io/relay-specs/#/Data/getReceivedBids
View the example in real time: https://payload.de/data

BEPs/BEP322.md

unclezoro · 2024-02-23T02:41:25Z

BEPs/BEP322.md

@@ -281,8 +331,11 @@ Response:
 ```json


I mean example of both normal and error response.

Fdutoit96 · 2024-02-24T07:17:48Z

Good day how do I pull the request. Sorry I am new to this Sent from Yahoo Mail for iPhone On Friday, February 23, 2024, 6:55 AM, Raina ***@***.***> wrote: @irrun commented on this pull request. In BEPs/BEP322.md:

@@ -281,8 +331,11 @@ Response:

```json added — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

rondales · 2024-02-24T18:52:16Z

	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

1. Summary

2. Motivation

3. Background

3.1 BSC Trust Model

3.2 BSC Consensus

4 Workflow

4.1 Definition

4.2 One-Round Interaction (default)

4.3 Two-Round Interaction (optional)

4.4 APIs

4.4.1 Builder APIs

4.4.1.1 Retrieve Transactions

4.4.1.2 Issues Report

4.4.2 Validator APIs

4.4.2.1 Bid Block

5. Further Discussion

5.1 Implementation Consideration

5.2 Payment & Economic Considerations

5.3 Builder Registration

6. References

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 widely supported by

mainstream consensus clients. As of October 2023, the inclusion rate of blocks from builders is

approximately 90%.

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.

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

Builders submit bids with transactions to the in-turn validator.

The validator picks the most valuable bid from all received within a predefined time.

The validator executes the full transactions and verifies the bid (gas received is the same as what claimed in the

bid).

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.

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

Builders submit bids without transactions to the in-turn validator.

The validator picks the most valuable bid from all received bids within a predefined time.

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.

The validator executes the transactions and verifies the bid (gas received is the same as what is claimed in the

bid).

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.

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.

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.

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:
{

  "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:
{

  "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:
{

  "jsonrpc": "2.0",

  "method": "mev_reportIssue",

  "params": [

    {

      "validator": "validator address",

      "bidHash": "hash of the bid",

      "error": {

        "code": -38001,

        "message": "response message"

      }

    }

  ],

  "id": 1

}
Response:
{

  "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:
{

  "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:
{

  "jsonrpc": "2.0",

  "id": 64,

  "result": "the hash of the bid"

}
error example:
{

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

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 is presented to demonstrate such a smart contract.

6. References

BSC Builder Specs

Example Smart Contracts

7. License

The content is licensed under

CC0.

AlexKNM · 2024-04-13T16:49:44Z

Is this in production already or being tested by some validators like BNB48, Avengers, etc?

…hain#322)" This reverts commit d1ac2a2.

forcodedancing force-pushed the bep_builder branch from cc9d75b to 58c701a Compare November 15, 2023 11:54

BEP-322: builder sepcs

3102c53

forcodedancing force-pushed the bep_builder branch from 58c701a to 3102c53 Compare November 15, 2023 11:55

unclezoro changed the title ~~BEP-322: builder sepcs~~ BEP-322: Builder API Specification for BNB Smart Chain Nov 16, 2023

refine wording

3026162

forcodedancing force-pushed the bep_builder branch from e6f4c1e to 3026162 Compare November 17, 2023 01:30

add more contents, refine some sentences

e77961e

forcodedancing force-pushed the bep_builder branch from 83a5b6b to e77961e Compare November 17, 2023 12:44

forcodedancing added 2 commits November 22, 2023 20:50

update content

173b965

fix a typo

d93eb0c

forcodedancing force-pushed the bep_builder branch from d8725f1 to afa99ea Compare November 23, 2023 04:35

update content

8c251c1

forcodedancing force-pushed the bep_builder branch from afa99ea to 8c251c1 Compare November 23, 2023 04:36

refine content and fix issues

d3d0cc4

forcodedancing force-pushed the bep_builder branch from 4cbcd48 to d3d0cc4 Compare November 23, 2023 10:08

forcodedancing added 3 commits November 26, 2023 21:14

update content to add proxy

79e5e40

uppdate structure

cae74ca

update discussion

ddf8edc

rondales approved these changes Nov 27, 2023

View reviewed changes

update content and figuires

8ecf2e8

irrun force-pushed the bep_builder branch from c0797d1 to 1a0a0a9 Compare November 28, 2023 09:23

enhance: workflow

8dbaf9e

irrun force-pushed the bep_builder branch from b3c1268 to 8dbaf9e Compare November 28, 2023 10:46

unclezoro reviewed Nov 28, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

unclezoro reviewed Nov 28, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

unclezoro reviewed Nov 28, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

unclezoro reviewed Nov 28, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

unclezoro reviewed Nov 28, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

forcodedancing commented Nov 30, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

forcodedancing commented Nov 30, 2023

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

fix: comments from arthur

9f182b7

foxweba3 approved these changes Dec 1, 2023

View reviewed changes

rondales approved these changes Dec 1, 2023

View reviewed changes

zzzckck mentioned this pull request Jan 8, 2024

MEV on BSC - where we are and where we should go #177

Closed

irrun mentioned this pull request Feb 5, 2024

feat: support MEV bnb-chain/bsc#2207

Closed

This was referenced Feb 15, 2024

feat: support MEV bnb-chain/bsc#2214

Closed

feat: support MEV bnb-chain/bsc#2224

Merged

fix: grammer and wording

9d7c5ac

irrun added 2 commits February 21, 2024 22:20

fix: typo

7ba4c02

fix: toc

b0a38b7

unclezoro reviewed Feb 22, 2024

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

unclezoro reviewed Feb 22, 2024

View reviewed changes

BEPs/BEP322.md Outdated Show resolved Hide resolved

fix: review comments

5a728af

unclezoro reviewed Feb 23, 2024

View reviewed changes

fix: review comments

577da97

Pythonberg1997 mentioned this pull request Feb 23, 2024

builder: implement BEP322 builder-api bnb-chain/bsc-builder#7

Merged

unclezoro approved these changes Mar 18, 2024

View reviewed changes

unclezoro merged commit d1ac2a2 into bnb-chain:master Mar 18, 2024

xkwang91 mentioned this pull request Apr 1, 2024

Are bsc testnet validators support PBS? irrun/bsc-mev-cases#1

Open

zzzckck mentioned this pull request Apr 7, 2024

Transactions with 0 gwei are back² bnb-chain/bsc#2371

Closed

rondales added a commit to rondales/BEPs that referenced this pull request Apr 14, 2024

Revert "BEP-322: Builder API Specification for BNB Smart Chain (bnb-c…

c8f6342

…hain#322)" This reverts commit d1ac2a2.

rondales mentioned this pull request Apr 14, 2024

Revert "BEP-322: Builder API Specification for BNB Smart Chain" #379

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

BEP-322: Builder API Specification for BNB Smart Chain #322

BEP-322: Builder API Specification for BNB Smart Chain #322

forcodedancing commented Nov 15, 2023 •

edited by irrun

Loading

48ClubIan commented Nov 16, 2023

forcodedancing commented Nov 23, 2023 •

edited

Loading

greyireland commented Feb 21, 2024

unclezoro Feb 23, 2024

irrun Feb 23, 2024

Fdutoit96 commented Feb 24, 2024 via email

rondales commented Feb 24, 2024

BEP-322: Builder API Specification for BNB Smart Chain

1. Summary

2. Motivation

3. Background

3.1 BSC Trust Model

3.2 BSC Consensus

4 Workflow

4.1 Definition

4.2 One-Round Interaction (default)

4.3 Two-Round Interaction (optional)

4.4 APIs

4.4.1 Builder APIs

4.4.1.1 Retrieve Transactions

4.4.1.2 Issues Report

4.4.2 Validator APIs

4.4.2.1 Bid Block

5. Further Discussion

5.1 Implementation Consideration

5.2 Payment & Economic Considerations

5.3 Builder Registration

6. References

7. License

AlexKNM commented Apr 13, 2024

BEP-322: Builder API Specification for BNB Smart Chain #322

BEP-322: Builder API Specification for BNB Smart Chain #322

Conversation

forcodedancing commented Nov 15, 2023 • edited by irrun Loading

BEP-322: Builder API Specification for BNB Smart Chain

1. Summary

2. Motivation

3. Background

3.1 BSC Trust Model

3.2 BSC Consensus

4 Workflow

4.1 Definition

4.2 One-Round Interaction (default)

4.3 Two-Round Interaction (optional)

4.4 APIs

4.4.1 Builder APIs

4.4.1.1 Retrieve Transactions

4.4.1.2 Issues Report

4.4.2 Validator APIs

4.4.2.1 Bid Block

5. Further Discussion

5.1 Implementation Consideration

5.2 Payment & Economic Considerations

5.3 Builder Registration

6. References

7. License

48ClubIan commented Nov 16, 2023

forcodedancing commented Nov 23, 2023 • edited Loading

greyireland commented Feb 21, 2024

unclezoro Feb 23, 2024

Choose a reason for hiding this comment

irrun Feb 23, 2024

Choose a reason for hiding this comment

Fdutoit96 commented Feb 24, 2024 via email

rondales commented Feb 24, 2024

BEP-322: Builder API Specification for BNB Smart Chain

1. Summary

2. Motivation

3. Background

3.1 BSC Trust Model

3.2 BSC Consensus

4 Workflow

4.1 Definition

4.2 One-Round Interaction (default)

4.3 Two-Round Interaction (optional)

4.4 APIs

4.4.1 Builder APIs

4.4.1.1 Retrieve Transactions

4.4.1.2 Issues Report

4.4.2 Validator APIs

4.4.2.1 Bid Block

5. Further Discussion

5.1 Implementation Consideration

5.2 Payment & Economic Considerations

5.3 Builder Registration

6. References

7. License

AlexKNM commented Apr 13, 2024

forcodedancing commented Nov 15, 2023 •

edited by irrun

Loading

forcodedancing commented Nov 23, 2023 •

edited

Loading