[Edited to change LIP => LEP]
Although Libra is still in an early and malleable state, formalization of Libra’s core engineering roadmap will help contributors join the effort. Most large open-source projects and protocols have some sort of proposal process which augments their governance mechanisms (PEP, BIP, EIP, RFC, etc). I would like the Libra Association to open a new repository on GitHub (
libra/leps) for this purpose. I propose the following as
LEP: 0001 Title: LEP Purpose and Guidelines Author: Matt Garnett Status: Active Type: Meta Created: 2019-06-20
What is a LEP?
LEP stands for Libra Improvement Proposal. A LEP is a design document that describes a new feature, idea, or process to the Libra community. The LEP should provide a concise technical specification and rationale for implementation.
We intend LEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that go into Libra. The LEP champion is responsible for building consensus within the community and documenting dissenting opinions.
Because the LEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
There are three kinds of LEP:
A Standards Track LEP describes any change that affects most or all Libra implementations, such as a change to the network protocol, a change in block or transaction validity rules, or any change or addition that affects the interoperability of applications using Libra.
An Informational LEP describes a Libra design issue, or provides general guidelines or information to the Libra community, but does not propose a new feature. Informational LEPs do not necessarily represent a Libra community consensus or recommendation, so users and implementors are free to ignore Informational LEPs or follow their advice.
A Meta LEP describes a process surrounding Libra, or proposes a change to (or an event in) a process. Meta LEPs are like Standards Track LEPs but apply to areas other than the Libra protocol itself. They may propose an implementation, but not to Libra’s codebase; they often require community consensus; unlike Informational LEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Libra development.
The LEP process begins with a new idea for Libra. Each potential LEP must have a champion --someone who writes the LEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea.
The LEP champion (a.k.a. author) should first attempt to ascertain whether the idea is LEP-able. Posting to the community forum is the best way to go about this. Asking the Libra community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions. It also helps to make sure the idea is applicable to the entire community and not just the author.
- Work in Progress – Once the champion has asked the Libra community as to whether an idea has any chance of acceptance, a work-in-progress (WIP) LEP should be submitted as pull request to this repo. Once this WIP is written in LEP style as described below, it will be merged into this repo as a draft LEP and assigned a LEP number.
- Draft – After the LEP officially merged as a draft, the champion should continue to actively seek feedback on the proposal regarding its merit and/or implementation. After a sufficient amount of analysis, an LEP editor will decide whether or not to move the LEP to last call.
- Last Call – When a LEP is transitioned to Last Call, it is given an end review date. If by the end of that time period there are no substantial unaddressed complaints, the LEP will become final (or accepted for changes requiring a hardfork).
- Accepted – LEPs in the stage will be implemented by the core developers on a timeline of their own discretion. The LEP is moved to Final once it is implemented and incorporated into a hard fork.
- Final – At this point, the LEP represents the current state-of-the-art. A Final LEP should only be updated to correct errata.
Other exceptional statuses include:
- Active – This is similar to Final, but denotes a LEP which may be updated without changing its LEP number.
- Deferred – This is for core LEPs that have been put off for a future hard fork.
- Rejected – A LEP that is fundamentally broken or a LEP that was rejected by the core developers and will not be implemented.
- Superseded – A LEP which was previously final but is no longer considered state-of-the-art. Another LEP will be in Final status and reference the Superseded LEP.
What belongs in a successful LEP?
Each LEP should have the following parts:
- Preamble – RFC 822 style headers containing meta-data about the LEP, including the LEP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc.
- Abstract – A short (~200 word) description of the technical issue being addressed.
- Specification – The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations of the Libra platform.
- Motivation – The motivation is critical for LEPs that want to change the Libra protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the LEP solves. LEP submissions without sufficient motivation may be rejected outright.
- Rationale – The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
- Backwards Compatibility – All LEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The LEP must explain how the author proposes to deal with these incompatibilities. LEP submissions without a sufficient backwards compatibility treatise may be rejected outright.
- Reference Implementation – The reference implementation must be completed before any LEP is given status “Final”, but it need not be completed before the LEP is accepted. It is better to finish the specification and rationale first and reach consensus on it before writing code.
- The final implementation must include test code and documentation appropriate for the Libra protocol.
- Copyright Waiver - All LEPs must be in the public domain. See the bottom of this LEP for an example copyright waiver.
LEP Formats and Templates
LEPs should be written in markdown format.
Each LEP must begin with an RFC 822 style header preamble. The headers must appear in the following order. Headers marked with “*” are optional and are described below. All other headers are required.
LEP: <LEP number> Title: <LEP title> Author: <list of authors' real names and optionally, email addresses> * Discussions-To: <url> Status: <Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded> Type: <Standards Track | Informational | Meta> Created: <date created on, in ISO 8601 (yyyy-mm-dd) format> * Review-Period-End: <end of review period, in ISO 8601 (yyyy-mm-dd) format> * Replaces: <LEP number> * Requires: <LEP number(s)> * Superseded-By: <LEP number> * Resolution: <url>
Author name format
The Author header lists the names, and optionally the email addresses, of all the authors/owners of the LEP. If the email address is included the format is:
Random J. User <email@example.com>
Random J. User
If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions.
Transferring LEP Ownership
It occasionally becomes necessary to transfer ownership of LEPs to a new champion. In general, we’d like to retain the original author as a co-author of the transferred LEP, but that’s really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the LEP process, or has fallen off the face of the 'net (i.e. is unreachable or isn’t responding to email). A bad reason to transfer ownership is because you don’t agree with the direction of the LEP. We try to build consensus around an LEP, but if that’s not possible, you can always submit a competing LEP.
If you are interested in assuming ownership of an LEP, send a message asking to take over, addressed to both the original author and the LEP editor. If the original author doesn’t respond to email in a timely manner, the LEP editor will make a unilateral decision.
The current LEP editors are:
- TODO fill in additional editors
- Matt Garnett (@c-o-l-o-r)
This document was derived heavily from Bitcoin’s BIP-0001 written by Amir Taaki and Ethereum’s EIP-1 written by Martin Becze and Hudson Jameson which were both in turn derived from Python’s PEP-0001. In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in the Libra Improvement Process, and should not be bothered with technical questions specific to Libra or the LEP. Please direct all comments to the LEP editors.
Copyright and related rights waived via CC0.