Skip to content

Latest commit

 

History

History
89 lines (66 loc) · 6.14 KB

BEP1.md

File metadata and controls

89 lines (66 loc) · 6.14 KB
Raw
  BEP: 1
  Title: Purpose and Guidelines
  Status: Living
  Type: Process
  Created: 2019-04-11

BEP 1: Purpose and Guidelines

1. What is BEP?

BEP stands for BNB Chain Evolution Proposal. Each BEP will be a proposal document providing information to the BNB Chain community, both BNB Beacon Chain and BNB Smart Chain. The BEP should provide a concise technical specification of the feature or improvement and the rationale behind it. Each BEP proposer is responsible for building consensus within the community and documenting dissenting opinions. Each BEP has a unique index number.

2. BEP Rationale

BEP is the primary mechanism for proposing new features, for collecting community technical input on issues, and for documenting the design decisions that go into BNB Chain. Because BEPs are maintained as text files in a versioned repository, their revisions are the historical records of feature proposals.

For BNB Chain contributors, it is a convenient way to track the progress of their implementation by BEPs. It will help end users to know the status of a given feature, function or improvement.

3. BEP Types

There are three types of BEP:

  • Standards: A Standards BEP describes functional changes on BNB Chain, such as a change to the network protocol, proposer selection mechanism in consensus algorithm, change in block size or fee mechanism in application level. It will effect the implementation of BNB Chain.
  • Information: An Information BEP will clarify some concepts of the BNB Chain, it may not effect the BNB Chain client implementation.
  • Process: This kind of proposal will change the workflow of BNB Chain working process, like this BEP itself.

4. BEP Workflow

overall workflow

Figure 1: BEP workflow

Once the idea is accepted, each status change is requested by the BEP author and reviewed by the BEP editors. Use a pull request to update the status.

  • Idea: If you have an idea but not sure if it worths a BEP or not, you may discuss with the community first before you put too much effort. You may post your idea in bnb chain forum and visit the bep-discussion channel in our discord to let the community know it.
  • Pre-Draft: If your idea is accepted, it is still not a BEP yet. A formal document will be needed to describe your idea, the Pre-Draft document should follow the BEP format. And you need to create a pull request and the BEP editors will review it.
  • Draft: Once the Pre-Draft pull request is accepted by the community and reviewed by the BEP editors, it can be merged. The pull request number will be used as the BEP number, which means it is a legal BEP now. The BEP editors will add the status, then it will be recorded and maintained by the community. The BEP author should keep pushing it forward, the author can update the BEP by creating new pull requests.
  • Final: This proposal is finalized and a reference implementation should be provided.
  • Enabled: This proposal is enabled in BNB Chain mainnet, if it is a hard fork, the fork number has reached.

Other exceptional statuses include:

  • Living: A BEP will be long-term maintained, like this BEP.
  • Stagnant: A BEP has not been updated for more than 6 months, it will enter Stagnant state.
  • Withdrawn: A BEP that is dropped and will not be implemented. Usually, it is due to some prerequisite conditions that are not true anymore.

5. BEP Format

It is important to keep BEP clear and well organized, BEPs need to follow this format(BEP1 is excepted):

  • Preamble: a short metadata about the BEP, it should be put at the top of the BEP. Here is an example:
  BEP: 127
  Title: Temporary Maintenance Mode for Validators
  Status: Enabled
  Type: Standards
  Created: 2022-01-10
  Author(optional): it can be a name or an email.
  Description(optional): enabled by BSC Euler upgrade, block height 18907621, Jun-22-2022
  Discussions(optional): could be a link to the bnb forum, where it is discussed.
  • Summary: a very short summary with a single sentence, someone could understand the purpose of the BEP by reading it even without technical background.
  • Abstract(optional): a short paragraph to give more introduction about the BEP, could be multi-sentence. Someone could read the abstract to know the general workflow of the BEP.
  • Motivation: it is a critical part of the BEP, it should explain very clearly why this proposal is needed.
  • Specification: it is another critical part, the detail workflow and configuration need to be provided. Diagrams are needed to make it easy to be understood if it is hard to be described in text.
  • Rational(optional): it adds more information to support the specification, i.e. why the design in the specification is preferred.
  • Forward Compatibility(optional): if the BEP will introduce compatibility problems in the future, probably because of some scheduled changes in the future that would be broken by the BEP. In such case, this part is a must to describe the detail incompatibilities and how to deal with it.
  • Backward Compatibility(optional): similar to Forward Compatibility, if the BEP introduces compatibility problems to the previous or current system, then this part is a must to describe the detail incompatibilities and how to deal with it.
  • Reference Implementations(optional): before the BEP enters the Final state, a reference implementation will be needed. However, if the BEP does not need a implementation, it can be omitted.
  • License: to show the copyright of the BEP.

6. Reference

Ethereum Improvement Proposals: https://github.com/ethereum/EIPs

Bitcoin Improvement Proposals: https://github.com/bitcoin/bips

7. License

All the content are licensed under CC0.