Libra Enhancement Proposal [LEP]

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


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.

LEP Types

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.

LEP Workflow

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.

Preamble

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 <address@example.com>

else:

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.

LEP Editors

The current LEP editors are:

  • TODO fill in additional editors
  • Matt Garnett (@c-o-l-o-r)

History

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.

See the revision history for further details.

Copyright

Copyright and related rights waived via CC0.

4 Likes

Thanks for contributing. We were thinking about this just the other day. We’d considered the LEP name (it’s just a bit weird to be talking about LIPs all the time).

One quick question – I’ve noticed on EIPs that there seems to be use of both issues and PRs to discuss EIPs. Curious if you have any thoughts from the communities listed about how to best structure the conversation.

We might want to tweak some of the text around “acceptance” of proposals. We’re still in the process of formalizing the association governance process and ultimately it is the association that will choose how to construct the notion of “core developer”. Don’t mean to stall the conversation here – but for better or for worse given the profile of the project it’s important that we are a bit more formal about putting governance processes in place. We should keep discussing on this thread.

For now I think this advice rings true:

The LIP champion (a.k.a. author) should first attempt to ascertain whether the idea is LIP-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.

We’d very much welcome discussion around concrete proposals on this forum.

1 Like

LEP is also good! I couldn’t decide between the two.

I generally tried to leave the criteria for transitioning from draft to last call opaque to allow interpretation by the editors — with the assumption that the Libra Association will control a majority if not all the editorial positions. With that in mind, I believe that the formalization of the governance process can continue in the parallel with setting up an initial LEP framework. Strictly stating that nothing will be progressed from the Draft state to the Final Call state until the governance process is thoroughly defined seems more than reasonable.

I am going out on a limb to guess that formalizing that process may take some time. It would be great to start documenting some of the “LEPs” that the community (Facebook/Calibra included) believe should be incorporated. I don’t think this is the most conducive forum for that after preliminary discussions.

On a related note, it would be great for the Calibra team to do more work in public. Although the codebase is now open source, it is difficult for anyone outside your team to make meaningful contributions without having a list of tasks, milestones, or priorities. Existing decentralized systems have an unbelievable amount of momentum behind them, and a big reason for that is the inclusive developer ecosystem they’ve cultivated. Even if it isn’t in the form of a LEP, it would be great to have concrete development tasks and milestones. Maybe even lower priority items for Libra that Calibra is willing to allow (and help) outside developers to champion!

It can get a bit messy at times, but I think think the current structure of conversations around an EIP is reasonable. My main complaint is using an issue to determine if a proposed idea is even EIP-able. I would prefer those conversations to be had on this forum (or IRL/Twitter/etc). Additionally, I think it would be great to have a subforum on here where only LEP editors can start discussion threads for official draft LEPs. The editor can add the link to the newly created thread upon merging the LEP PR, and I believe that will make following LEPs easier than EIPs. As for the general back-and-forth between the editor and LEP author to get the WIP LEP ready for Draft state, I think the PR thread is acceptable.

2 Likes

I generally tried to leave the criteria for transitioning from draft to last call opaque to allow interpretation by the editors — with the assumption that the Libra Association will control a majority if not all the editorial positions

So the general intention here is for the “association” to be relatively light weight. i.e. the association won’t hire an army of editors. All that will happen here is that the association will decide the process for determining editorship. But most of the editors are likely to be people who don’t work for the association. The W3C is a good parallel here – the people who edit the HTML spec are employed by Google/Mozilla/etc. The W3C organizes the process.

Strictly stating that nothing will be progressed from the Draft state to the Final Call state until the governance process is thoroughly defined seems more than reasonable.

This seems like a reasonable framework. Right now all of the decisions we’ve made are really drafts that are open to change.

It would be great to start documenting some of the “LEPs” that the community (Facebook/Calibra included) believe should be incorporated. I don’t think this is the most conducive forum for that after preliminary discussions.

Yep, agreed. I’d love to see people opening topics on potential LEPs

On a related note, it would be great for the Calibra team to do more work in public. Although the codebase is now open source, it is difficult for anyone outside your team to make meaningful contributions without having a list of tasks, milestones, or priorities. Existing decentralized systems have an unbelievable amount of momentum behind them, and a big reason for that is the inclusive developer ecosystem they’ve cultivated. Even if it isn’t in the form of a LEP, it would be great to have concrete development tasks and milestones. Maybe even lower priority items for Libra that Calibra is willing to allow (and help) outside developers to champion!

Agreed. At Calibra we’re just starting to do a phase of planning – we were pretty focused on the process of shipping the testnet. This will be a good time for us to communicate more. It’s going to take time to shift our approach – but we totally get that it’s not possible to build a community without developing in the open.

It can get a bit messy at times, but I think think the current structure of conversations around an EIP is reasonable. My main complaint is using an issue to determine if a proposed idea is even EIP-able. I would prefer those conversations to be had on this forum (or IRL/Twitter/etc). Additionally, I think it would be great to have a subforum on here where only LEP editors can start discussion threads for official draft LEPs. The editor can add the link to the newly created thread upon merging the LEP PR, and I believe that will make following LEPs easier than EIPs. As for the general back-and-forth between the editor and LEP author to get the WIP LEP ready for Draft state, I think the PR thread is acceptable.

Thanks for the thoughts. Curious if you think Google Docs / etc have a place in the process. Internally we’ve found that interactive doc editing is huge for productivity on these sorts of things.

2 Likes

I think I accidentally omitted the word “members” after Libra Association, but what you describe makes complete sense.

This is great to hear, I’m excited that this is a priority. I’ll be looking forward to more dialogue in the clear!

From the few instances in Ethereum I’ve seen where technical ideas have been disseminated via Google docs to a broad audience, it was difficult to navigate through the noise in the comments. There may be tools to significantly improve this experience that I’m not aware of.

In my opinion, forums (e.g. https://ethresear.ch/) have been a great match for the asynchronous communication style that Ethereum developers / researchers around the world share. However, even if Google docs were objectively a better fit, I think many in the blockchain communities would choose something else out of spite. :slight_smile:

2 Likes