| NEP | Title | Authors | DiscussionsTo | Status | Type | Created |
|---|---|---|---|---|---|---|
1 |
NEP Purpose and Guideline |
Living |
Process |
03-Mar-2022 |
A NEP is a design document for providing information to the NEAR community or describing a new feature for the NEAR protocol or Smart Contract standards. The NEP should provide a concise technical specification and a rationale for the feature.
NEPs are intended to be the primary mechanism for proposing new features, coordinating formal feedback, and documenting design decisions that were integrated into NEAR’s runtime or Smart Contract ecosystem.
As such, the NEP’s author is responsible for building consensus within the community and documenting dissenting opinions.
Because NEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. A list of NEPs is available on GitHub.
The purpose of the NEP process is to ensure seamless protocol upgrades and to empower the community to contribute to the development of the NEAR platform. Given the complexity of the protocol and the large number of participants across the ecosystem, the process introduces working groups as a way to operationalize the review of NEPs that builds legitimacy and community support.
The working groups are responsible for coordinating the public review of NEPs, gauging the viability and community support, and overseeing decisions. Each group will focus on various ecosystem needs, such as the protocol, standards, and tools.
Pagoda has selected a few leading subject matter experts to help bootstrap the first two groups: Protocols and Contract Standards. Putting these groups into practice will require flexibility. The goal is to iterate and eventually introduce more groups and broader participation. Visit https://near.org/developer-governance to learn more about these groups, their members, and the upcoming meetings.
The typical primary audience for NEPs are the core developers of the NEAR reference implementations and decentralized applications developers
There are two kinds of NEPs:
- A Standards NEP describes a new NEAR Smart Contract implementation standard.
- A Protocol NEP describes a new feature for the NEAR protocol.
Currently, both types of NEPs follow the same process.
Everyone in the community is welcome to propose, discuss, and review ideas to improve the NEAR protocol and standards. The NEP process begins with a new idea for the NEAR ecosystem. A single NEP should contain a single key proposal or new idea.
Each NEP must have an author: someone who writes the NEP using the style and format described below. The author, or another champion, shepherds the discussions in the appropriate forums and attempts to build community consensus around the idea to help it progress toward completion.
Before submitting a NEP, the author should first attempt to ascertain whether the idea is NEP-able. Vetting an idea publicly before writing a NEP saves the potential author time. Asking the NEAR community first if an idea is original helps prevent effort on something that is guaranteed to be rejected based on prior discussions. It also helps ensure the idea is applicable to the entire community. Just because an idea sounds good to the author does not mean it will work for most people in most use cases.
In general, the process to socialize an idea is:
- Check prior proposals: Many ideas for changing NEAR come up frequently. Please search the governance site forums and NEPs in this repo before proposing something new.
- Share the idea: Join the governance site and make a post to the appropriate section. For instance, during the ideation phase of a standard, one might start a new conversation in the Development » Standards section. Similarly, during the ideation phase of a proposal to change the protocol, one might start a new conversation in the Development » Proposals section.
- Get feedback: The forum has comment threading which allows the community and NEAR Collective to ideate, ask questions, wrestle with approaches, etc. If more immediate responses are desired, consider bringing the conversation to Discord.
Following the above initial discussions, the author should submit a draft NEP via a GitHub pull request. The draft must follow the NEP style as described below, else it will fail review immediately (although the moderators may correct minor errors).
The NEP workflow is:
- You, the NEP author, fork the NEPs repository, and create a file named neps/nep-9999.md that contains your new NEP. Use “9999” as your draft NEP number.
- Your first update is to change the nep filename to match the Pull Request number. For example, if the PR is 305, the NEP should be neps/nep-0305.md.
- In the “Type:” header field, enter “Standards” or “Protocol” as appropriate, and for the “Status:” field enter “Draft”. For full details, see NEP Header Preamble.
- Push this to your GitHub fork and submit a pull request.
- The NEP moderators review your PR for structure, formatting, and other errors. For a markdown-formatted NEP, nep-template.md is provided as a template.
Approval criteria are:
- The content is sound and complete. The ideas must make technical sense. The moderators do not consider whether they seem likely for acceptance.
- The title accurately describes the content.
- The language (spelling, grammar, sentence structure, etc.) and code style are correct and conformant.
- If the NEP is not ready for approval, the moderators will send it back to the author for revision, with specific instructions in the pull request. The review by the moderators is expected to finish within one week.
- Once the moderators agree that the PR is ready for review, the moderators will notify the approvers (working group members) to assign a team of at least two reviewers (subject matter experts) to review the NEP. The reviewers will review the technical details of the proposal and assess its merits. They may ask clarification questions, request changes, or reject the proposal. If the assigned reviewers feel that they do not have the relevant expertise to fully review the NEP, they can request the working group to re-assign subject matter experts for the NEP.
- The review by the reviewers is expected to finish within one week. After completing the review, the reviewer must add an explicit comment to indicate the next step and tag the appropriate member:
- To request revisions from the author: "As the assigned Reviewer, I request from the author @author-username to address [provide concerns or suggestions]."
- To move to the next stage: "As the assigned Reviewer, I do not have any feedback for the author. I recommend moving this NEP forward and for the working group to [accept or reject] it based on [provide reasoning, including a sense of importance or urgency of this NEP]."
- The author of the proposal is free to revise the proposal and re-request reviews from reviewers. If a proposal is in the review stage for more than two months, the moderator will automatically reject it. To re-open the proposal, the author must start over with the NEP process again.
- Once the two reviewers agree that the proposal is close to the voting stage, the moderators will assign the approvers (working group) to review the NEP. The approvers will review the proposal and add their voting indication.
- The final review period by the approvers is expected to finish within one week. After completing the review, the approvers must add an explicit comment with their voting indication:
- To reject: "As a working group member, I lean towards rejecting this proposal based on [provide reasoning]."
- To approve: "As a working group member, I lean towards approving this NEP based on [provide reasoning]."
- Once all the approvers add their voting indication, the moderator will review the voting indication for a 2/3 majority vote:
- If the votes lean toward rejection: The moderator will summarize the feedback and close the NEP.
- If the votes lean toward approval: The moderator will schedule a public call (see NEP Communication) for the author to present the NEP and for the working group members to formalize the voting decision. If the working group members agree that the NEP is overall beneficial for the NEAR ecosystem and vote to approve it, then the proposal is considered accepted. After the call, the moderator will summarize the decision on the NEP.
NEP discussions should happen asynchronously within the NEP’s public thread.
However, if a discussion becomes circular and could benefit from a synchronous conversation, any participants on a given NEP can suggest for the moderator to schedule an ad hoc meeting. For example, if a reviewer and author have multiple rounds of comments, they may request a call. The moderator can help coordinate the call and post the registration link on the NEP. The person who requested the call should designate a note taker to post a summary on the NEP after the call.
When a NEP gets to the final voting stage, the moderator will schedule a public working group meeting to discuss the NEP with the author and formalize the decision. The moderator will first coordinate a time with the author and working group members, and then post the meeting time and registration link on the NEP at least one week in advance.
In general, NEPs are no longer modified after they have reached the Final state.
A given NEP can have one of the following states:
- Draft: The first formally tracked stage of a NEP in development. A NEP is merged by a NEP Moderator into the NEP repository when properly formatted.
- Review: A NEP moderator marks a NEP as ready for Subject Matter Experts Review.
- If the NEP is not approved within two months, it is automatically rejected.
- Voting: This is the final voting period for a NEP. The working group will vote on whether to accept or reject the NEP. This period is limited to two weeks. If during this period necessary normative changes are required, the NEP will revert back to Review.
- Approved: If the working group votes to approve, they will move the NEP to Approved. Once approved, Standards NEPs exist in a state of finality and should only be updated to correct errata and add non-normative clarifications.
- Rejected: If the working group votes to reject, they will move the NEP to Rejected.
- Living - A special status for NEPs that are designed to be continually updated and not reach a state of finality. This includes most notably NEP-0001.
The NEP process has various roles and responsibilities.
Author
Anyone can participate
- Writes proposal following the standards
- Submits proposal with prototype when ready for review and changes the status to “Draft”
- Addresses comments
- Presents to working group and incorporates necessary changes
- Provides final implementation with sufficient testing and documentation once approved
Moderator
Assigned by working group
- Ensures proposal meets standards
- If proposal needs revisions, provides comments on improvements and keeps status as “Draft”
- If proposal does not meet standards, changes status to “Rejected”
- If proposal is ready for review, changes status to “Review”
- Coordinates working group to assign reviewers and review proposals
- Does not assess the technical feasibility or writes any parts of the proposal
Reviewer (Subject Matter Experts)
Assigned by working group
- Gives feedback on proposals
- Assesses technical feasibility of proposals
- Does not have the ability to approve proposal
Approver (Community Working Groups)
Appointed by Pagoda in the bootstrapping phase
- Assigns reviewers to proposals
- Attends working group meetings to review proposals
- Votes to approve or reject proposals
Each NEP should have the following parts/sections:
- Preamble - RFC 822 style headers containing meta-data about the NEP, including the NEP number, a short descriptive title, the names, and optionally the contact info for each author, etc.
- Summary - a short (~200 word) description of the technical issue being addressed.
- Motivation - The motivation section should clearly explain why the existing contract ecosystem is inadequate to address the problem that the NEP solves. This can include collecting documented support for the NEP from important projects in the NEAR ecosystem. NEP submissions without sufficient motivation may be rejected.
- Rationale and alternatives - The rationale fleshes out the specification by describing 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 platforms.
- Specification - The technical specification should describe the syntax and semantics of the contract or protocol feature. The specification should be detailed enough to allow competing, interoperable implementations for at least the current major NEAR version.
- Draft Implementation - A draft implementation showing the viability of the proposal must be completed before any NEP is given the “Approved” status. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of API details. Once approved, the final implementation must include test code and documentation.
- Security Implications - If there are security concerns in relation to the NEP, those concerns should be explicitly written out to make sure reviewers of the NEP are aware of them.
- Drawbacks - Throughout the discussion of a NEP, various ideas will be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This both helps record the thought process behind the final version of the NEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions. In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued.
- Unresolved Issues - While a NEP is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the NEP to be ready for consideration are complete and reduces people duplicating prior discussion.
- Future possibilities - Future possibilities describes any natural extensions and evolutions to the NEP proposal and how it would affect the project. Try to use this section as a tool to more fully consider all possible interactions with the project in your proposal. Also consider how this all fits into the roadmap for the project and of the relevant sub-teams.
- Copyright Waiver - All NEPs must be in the public domain. See the bottom of this NEP for an example copyright waiver.
Each NEP must begin with an RFC 822 style header preamble. The headers must appear in the following order.
NEP: <NEP number>
Title: <NEP title>
Author: <list of authors' real names and optionally, email addresses>
Status: <Draft | Review | Voting | Approved | Rejected | Living>
DiscussionsTo (Optional): <URL of current canonical discussion thread or threads>
Type: <Standards | Protocol>
Requires (Optional): <NEP numbers>
Replaces (Optional): <NEP number>
SupersededBy (Optional): <NEP number>
Created: <date created on, in dd-mmm-yyyy format>
Title: The NEP title header should not be more than 4-5 words, describing
Author: The Author header lists the names, and optionally the email addresses of all the authors/owners of the NEP. The format of the Author header value must be
Random J. User <[email protected]>;
Other I. User <[email protected]>
if the email address is included, and just
Random J. User
DiscussionsTo: The DiscussionsTo header provides the URL to the current canonical discussion thread for the NEP.
Type: The Type header specifies the type of NEP: Standards or Protocol
Created: The Created header records the date that the NEP was assigned a number, should be in dd-mmm-yyyy format, e.g. 03-Mar-2022.
Requires: NEPs may have a Requires header, indicating the NEP numbers that this NEP depends on.
SupersededBy: NEPs may also have a SupersededBy header indicating that a NEP has been rendered obsolete by a later document; the value is the number of the NEP that replaces the current document.
Replaces: A newer NEP marked with a SupercededBy header must have a Replaces header containing the number of the NEP that it rendered obsolete.
Images, diagrams and auxiliary files should be included in a subdirectory of the assets folder for that NEP as follows: assets/nep-N (where N is to be replaced with the NEP number). When linking to an image in the NEP, use relative links such as …/assets/nep-1/image.png
It occasionally becomes necessary to transfer ownership of NEPs to a new author. In general, it is preferable to retain the original author as a co-author of the transferred NEP, but that is 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 NEP process. A bad reason to transfer ownership is because the author does not agree with the direction of the NEP. One aim of the NEP process is to try to build consensus around a NEP, but if that is not possible, an author can submit a competing NEP.
If you are interested in assuming ownership of a NEP, you can also do this via pull request. Fork the NEP repository, make your ownership modification, and submit a pull request. In the PR description, tag the original author and provide a summary of the work that was previously done. Also clearly state the intent of the fork and the relationship of the new PR to the old one. For example: "Forked to address the remaining review comments in NEP # since the original author does not have time to address them."
When referring to a NEP by number, it should be written in the hyphenated form NEP-X where Xis the NEP’s assigned number.
NEPs are encouraged to follow RFC 2119 for terminology and to insert the following at the beginning of the Specification section:
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The content of this document was derived heavily from the PEP, BIP, Rust RFC and EIP standards bootstrap documents:
- Klock, F et al. Rust: RFC-0002: RFC Process. https://github.com/rust-lang/rfcs/blob/master/text/0002-rfc-process.md
- Taaki, A. et al. Bitcoin Improvement Proposal: BIP:1, BIP Purpose and Guidelines. https://github.com/bitcoin/bips/blob/master/bip-0001.mediawiki
- Warsaw, B. et al. Python Enhancement Proposal: PEP Purpose and Guidelines. https://github.com/python/peps/blob/main/pep-0001.txt
- Becze, M. et al. Ethereum Improvement Proposal EIP1: EIP Purpose and Guidelines. https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md
Copyright and related rights waived via CC0.