This page is the Simplified Technical English version of ZIP 0. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 0: ZIP Process
ZIP: 0
Title: ZIP Process
Owners: Jack Grigg <thestr4d@gmail.com>
Mark Henderson <mark@shieldedlabs.net>
Daira-Emma Hopwood <daira@jacaranda.org>
Arya <arya@zfnd.org>
Marek <marek@zfnd.org>
Kris Nuttycombe <kris@nutty.land>
Sam H. Smith <sam@shieldedlabs.net>
Sean Bowe <sean@bowe.tech>
Tal Derei <tal@bowe.tech>
Dev Ojha <dev@valargroup.dev>
Original-Authors: Josh Cincinnati
George Tankersley
Deirdre Connolly
Teor
Aditya Bharadwaj
Conrado Gouvêa
Credits: Luke Dashjr
Status: Active
Category: Process
Created: 2019-02-16
License: BSD-2-Clause
Terminology
On this page, STE words are in the place of the BCP 14 key words of the source. Refer to the key word table.
In this document, the term "network upgrade" has the same meaning as in ZIP 200. [zip-0200]
Abstract
A Zcash Improvement Proposal (ZIP) is a design document. A ZIP contains information for the Zcash community, or the description of a new feature for Zcash or its processes or environment. We recommend that the ZIP contains a short technical specification of the feature and a rationale for the feature.
We intend ZIPs to be the primary mechanism for these functions:
- The proposal of new features.
- The collection of community input on an issue.
- The documentation of the design decisions in Zcash.
The Owners of the ZIP (usually the authors) are responsible for two tasks: to build consensus in the community, and to document dissenting opinions.
The ZIPs are text files in a versioned repository. Thus their revision history is the historical record of the feature proposal.
A part of the basis of this document is the work that Luke Dashjr did with BIP 2.
Specification
ZIP Workflow
The start of the ZIP process is a new idea for Zcash. Each potential ZIP must have Owners. The Owners are one or more persons who do these tasks:
- They write the ZIP in the style and format of the sections below.
- They shepherd the discussions in the applicable forums.
- They try to build community consensus for the idea.
We recommend that the Owners first try to find out if the idea is ZIP-able. For small enhancements or patches to one piece of software, standardisation between multiple projects is often not necessary. A ZIP is not necessary for these changes. We recommend that these changes are put into the development workflow of the applicable project, with a patch submission to the applicable issue tracker.
Also, many ideas to change Zcash were proposed and then rejected for different reasons. We recommend that the first step is a search of past discussions. The purpose of the search is to see if the idea was considered before and, if so, the issues that occurred in its progression. After the search of past work, the best way to continue is usually to post about the new idea to the Zcash Community Forum.
The public vetting of an idea, before a person writes a ZIP, has a purpose: to save time for the potential Owners and the wider community. The potential Owners can first ask the Zcash community if an idea is original. Then it is less probable that they use too much time on an idea that is certain to be rejected because of earlier discussions. (A search of the internet is not always sufficient.)
With this step, they can also make sure that the idea is applicable to the full community and not only to the Owners. An idea that seems good to the Owners is not necessarily satisfactory for most persons in most areas where persons use Zcash. But some Owners can already have the necessary experience and knowledge of the history of Zcash development. Those Owners can decide if the idea is applicable without this vetting step.
When the Owners believe that an idea has some chance of acceptance, we recommend that they show a ZIP draft to the Zcash Community Forum. Thus the Owners have an opportunity to make the ZIP draft complete, with correct formatting and high quality. This applies particularly to first-time submitters. Concerns about the ZIP draft can also be addressed at an early stage, and thus the quantity of rework can be smaller. But for a ZIP draft to be merged, it is not a requirement to address concerns at this stage.
After a discussion, we recommend that the Owners send the ZIP draft to the ZIPs git repository [zips-repo] as a pull request. This ZIP draft must be in ZIP style, as in the description below. Its name must be an alias such as draft-zatoshizakamoto-42millionzec until the ZIP Editors assign a ZIP number to it. (Owners must not assign ZIP numbers to their own ZIP drafts.)
Before the Owners send the ZIP draft for review, they have the responsibility to collect community feedback on the initial idea and the ZIP draft. But, where possible, we recommend that there are no long open-ended discussions on forums. In some cases, a ZIP becomes necessary for technical or process reasons that are not in doubt. In those cases, it is possible that a forum discussion is not necessary.
We strongly recommend that one ZIP contains one key proposal or new idea. A ZIP with more focus is usually more successful. If you are not sure, divide your ZIP draft into several ZIP drafts that each have a clear focus.
When the ZIP draft is complete, the ZIP Editors will do these tasks:
- Assign a number to the ZIP, if that is not already done.
- Assign one or more Categories to the ZIP.
- Merge the pull request into the ZIPs git repository.
The ZIP Editors will not unreasonably reject a ZIP. Reasons to reject a ZIP include:
- The ZIP is a duplication of effort.
- The ZIP has disregard for formatting rules.
- The ZIP is too unfocused or too broad.
- The ZIP is technically unsound.
- The ZIP does not have satisfactory motivation.
- The ZIP is not in agreement with the Zcash philosophy.
For a ZIP to be accepted, it must be in agreement with some minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must be a net improvement. The proposed implementation, if applicable, must be solid and must not add unnecessary complexity to the protocol.
The Owners can update the ZIP draft as necessary in the ZIPs git repository. We recommend that the Owners also send updates to ZIP drafts as pull requests.
ZIP Numbering Conventions
At this time, the ZIP Editors use these conventions when they assign numbers to ZIPs:
- If a ZIP directly corresponds to a BIP (Bitcoin Improvement Proposal), and there is no number conflict, assign the same number.
- If it has an effect on the consensus layer or the core protocol, assign a number in the range 200..299.
- If it has an effect only on higher layers, but is necessary for interoperability, assign a number in the range 300..399. The interoperability is between node implementations or other parts of the ecosystem.
- If it is specific to an implementation (for example
zebraorzcashd), assign a number in the range 400..499. - If it is about Consensus Process, assign a number in the range 0..9 or 1000..1199.
- If it only contains descriptions of updates to existing ZIPs or the Zcash Protocol Specification, or both, assign a number in the range 2000..2999. (After deployment, those documents will be a complete specification in themselves.)
- Try to assign consecutive numbers to ZIPs that will be deployed together, and to ZIPs that we recommend to deploy together. Use a coherent reading order. (The conventions above have priority.)
The ZIP Editors can change these conventions by consensus.
Transferring ZIP Ownership
It is sometimes necessary to transfer ownership of ZIPs to a new Owner. In general, we prefer to keep the original Owner as a co-Owner of the transferred ZIP, but the original Owner makes that decision.
A good reason to transfer ownership is one of these:
- The original Owner no longer has the time or the interest to update the ZIP or to follow through with the ZIP process.
- The original Owner disappeared from the internet (that is, the Owner is unreachable or does not reply to email).
A bad reason to transfer ownership is that you do not agree with the direction of the ZIP. We try to build consensus for a ZIP. But if that is not possible, you can always send a competing ZIP.
If you want to take ownership of a ZIP, send a message to ask to take over. Address the message to all of the current Owners and the ZIP Editors. If the Owners proposed for removal do not reply in a timely manner, the ZIP Editors and any remaining current Owners will make a decision. (Such decisions can be reversed.)
If an author of a ZIP is no longer an Owner, we recommend that an Original-Authors: field is added to the ZIP metadata. This field contains the original authorship (without email addresses). This recommendation does not apply if the original authors request differently.
ZIP Editors
The current ZIP Editors are:
- Jack Grigg, Daira-Emma Hopwood, and Kris Nuttycombe in their individual capacities.
- Arya and Marek, associated with the Zcash Foundation.
- Mark Henderson and Sam H. Smith, associated with Shielded Labs.
- Sean Bowe and Tal Derei, associated with Project Tachyon.
- Dev Ojha, associated with Valar Group.
You can send email to all of them at zips@z.cash. The current design of the ZIP Process has this condition: there are always a minimum of two ZIP Editors, and a minimum of one is from the Zcash Foundation.
ZIP Editors must declare any potential or perceived conflict of interest that they have in relation to their responsibilities as ZIP Editors.
Daira-Emma Hopwood declares a conflict of interest, because ze is a ZIP Editor and also Head of Research and Assurance at Zcash Open Development Lab. Ze will try to make the disadvantages of that combination of roles as small as possible. In particular, ze commits to resign from the ZIP Editor role after the deployment of Zcash Shielded Assets. This applies if ze is still, at that time, in a management role at a company with primary involvement in the development of Zcash.
Sean Bowe declares a potential conflict of interest between the role of ZIP Editor and the role of maintainer of Zakura. Zakura is a Zcash consensus full node implementation.
ZIP Editors must be publicly transparent about any external influence or constraints on their actions as ZIP Editors. This applies to influence or constraints that a party placed on those actions, and to those that a party tried to place. (This includes influence or constraints from Zcash Foundation, Shielded Labs, or other organizations that the ZIP Editors are associated with.) This rule applies if the influence or constraint has an effect on those actions, and also if it has no effect. Do not interpret this as a requirement for ZIP Editors to reveal knowledge of undisclosed security vulnerabilities or mitigations.
The current ZIP Editors can select additional ZIP Editors by consensus, with the consent of the selected persons.
The current ZIP Editors can remove or replace a ZIP Editor by consensus. But if the other ZIP Editors have consensus, a ZIP Editor cannot prevent their own removal.
Any ZIP Editor can resign. To resign, the ZIP Editor informs the other ZIP Editors in writing.
Each time the ZIP Editors change, we recommend that the new ZIP Editors do these tasks:
- Do a review of this ZIP to make sure that it is in agreement with current practice.
- Update the Owners of this ZIP.
- Do a review of access to the ZIPs git repository.
- Update the <zips@z.cash> email alias.
- Invite new ZIP Editors to the Zcash Community Forum, and the #zips channel on Discord.
When the last review of this ZIP is 12 months old or more, we recommend that the ZIP Editors do a review of it again. The purpose is to make sure that it is in agreement with current practice. (This applies if the last review was a response to a ZIP Editor change, and also if it was not.)
ZIP Editor Responsibilities
The ZIP Editors subscribe to the Zcash Community Forum.
We recommend that each new ZIP draft is sent as a "pull request" to the ZIPs git repository [zips-repo]. We recommend that it does not contain a ZIP number, unless the ZIP Editors assigned one before. We recommend that the ZIP content is in reStructuredText [rst] or Markdown [markdown] format. The initial value of the Status field must be Draft. The pull request must not include generated HTML.
For each new ZIP draft that the ZIP Editors receive, we recommend that they do these tasks:
- Read the ZIP draft to see if it is ready: sound and complete. The ideas must be technically sensible, even if their acceptance does not seem probable. Refer to Reviewing a ZIP below for more detail.
- Make sure that the Title, Category, and other metadata fields are accurate for the content.
- Make sure that a pull request for the ZIP draft is in the ZIPs git repository [zips-repo].
- Make sure that an announcement of the ZIP draft is on the Zcash Community Forum and the
#zipschannel of the Zcash R&D Discord. - Make sure that the licensing terms are acceptable for ZIPs.
For proposals to revise an existing ZIP, we recommend that the ZIP Editors do these tasks:
- Read the proposed change to see if it is ready: sound, complete, and non-disruptive to the existing deployments of the ZIP, if there are any. Refer to Reviewing a ZIP below for more detail.
- Some proposed changes primarily have an effect on already-deployed aspects of the Zcash consensus protocol. We recommend that such changes are specified in an "Update ZIP" that contains a description of the changes to make. This is in the place of a pull request that contains direct changes to the existing ZIPs or the Zcash Protocol Specification. The ZIP Editors can decide that an Update ZIP is not necessary for compatible changes or clarifications.
- If an existing ZIP will change, make sure that the Title, Category, and other metadata fields are still accurate for the changed content.
- If the ZIP has a Change History section, make sure that its update is accurate. If it has none, consider if the ZIP is a "living ZIP", and if a Change History section is an advantage.
- Make sure that the update is in the ZIPs git repository [zips-repo] as a pull request.
- A proposed update can be substantive and not only editorial. If so, make sure that an announcement of it is on the Zcash Community Forum and the
#zipschannel of the Zcash R&D Discord. - Make sure that the licensing terms are still acceptable for ZIPs.
Announcements of new ZIP drafts and updated ZIPs are a help for transparency. They are also an encouragement for timely community engagement and feedback. We recommend that such announcements clearly contain the ZIP number, the title, and a short summary.
After acceptance of an Update ZIP, the ZIP Editors have the responsibility to apply its changes to any existing specifications. But the ZIP Editors must do this only after the Status of the Update ZIP is at least Proposed.
When the ZIP Editors apply an Update ZIP, they also add these items to each updated document:
- The References entries for the citations in the applied text, if these entries are to the Zcash Protocol Specification or to ZIPs.
- A Change History entry, if the document has a Change History section.
It is not necessary for the Update ZIP to contain a description of these items. The Update ZIP must contain any other reference that is necessary for the applied text, such as one to a third-party document.
If a new Revision is added to a ZIP, then the name of its original deployment is Revision 0. In some cases, the Revisions of a ZIP can have different deployment Status. This is visible in the Status field. Refer to ZIP Status Field below.
The ZIP Editors are also generally responsible for administration and access control of the ZIPs git repository [zips-repo].
Reviewing a ZIP
Any ZIP Editor can suggest changes to a ZIP. These suggestions are the opinion of the individual ZIP Editor. The expectation is that each technical or process review that ZIP Editors do is independent of their contractual or other relationships.
The Owners are free to clarify, change, or refuse suggestions from ZIP Editors. If the ZIP Editors make a change to a ZIP and the Owners object to it, the ZIP Editors must do one of these: revert the change, or give a public rationale for the decision to override the objection.
Examples of reasons to override an objection are that the change is necessary for one of these purposes:
- To document the deployment status of the ZIP accurately.
- To call attention to a security or privacy issue, or to significant community opposition.
- To enforce a process requirement of this ZIP or a different ZIP.
If it is found later that a previous publication or update was made in violation of a process requirement, the ZIP Editors can revert it.
We recommend that any changes to a ZIP by the ZIP Editors are communicated to the Owners.
Usually, the ZIP Editors suggest changes in two phases:
content review: multiple ZIP Editors discuss the ZIP draft or update, and suggest changes to the overall content. This is a "big picture" review.format review: two ZIP Editors do a detailed review of the structure and format of the ZIP draft. With this review, they make sure that the ZIP draft is consistent with other Zcash specifications.
We recommend that the ZIP Editors identify general weaknesses in the ZIP draft in the content review. These weaknesses can include:
- Insufficient or unclear motivation.
- Unclear, under-documented, or missing privacy implications.
- Significant objectives of the ZIP draft that are not clearly documented in the
Requirementssection. - Missing trust assumptions.
- Security risks that are insufficiently addressed.
- Unaddressed backward compatibility issues.
Also, ZIP Editors can ask community security or privacy experts for input on proposals that have significant implications.
Note that a review of proposals for security, correctness, or implementability is not the primary responsibility of the ZIP Editors.
If the ZIP draft is not ready, we recommend that the ZIP Editors make suggestions to the Owners for the revision of the ZIP draft.
Some pull requests contain only updates to ZIP drafts that the creator of the pull request owns. If such a pull request is free from spam, abusive or malicious content, and other such items, we recommend that the ZIP Editors approve it. A substantive editorial review is not necessary for this approval. Thus the Owners can merge their changes into the main branch almost at will.
If changes to a ZIP draft are merged into main, an issue to track the ZIP draft must be opened, if none is open. In this situation, we recommend that the applicable unresolved suggestions or comments are moved to this issue. The applicable ones are those that it is necessary to address before the ZIP draft can become a numbered ZIP.
If the ZIP draft is not ready, the ZIP Editors will send it back to the Owners for revision, with specific instructions. The current ZIP Editors make this decision by consensus.
We recommend that the format review generally occurs after the content review feedback is addressed. The purpose is to prevent unnecessary document churn or merge conflicts.
When a ZIP draft is ready, the ZIP Editors will do these tasks:
- Make sure that the ZIP draft has a unique ZIP number in the pull request.
- Regenerate the related HTML documents, if this is necessary.
- Remove Draft status and merge the pull request.
The ZIP Editors monitor ZIP changes and update ZIP headers as applicable.
Rejecting a ZIP or update
The ZIP Editors can reject a new ZIP draft or an update to an existing ZIP, by consensus among the current ZIP Editors. A rejection can have any of these reasons as its basis:
- It is a violation of the Zcash Code of Conduct [conduct].
- It appears too unfocused or too broad.
- It is a duplication of effort in other ZIPs and does not have sufficient technical justification. (But alternative proposals to address similar or overlapping problems are not excluded for this reason.)
- It has manifest security flaws. (These include an unrealistic dependence on user vigilance to prevent security weaknesses.)
- It does not contain adequate consideration of privacy implications.
- It has disregard for compatibility with the existing Zcash block chain or ecosystem.
- It is manifestly unimplementable.
- It includes buggy code, pseudocode, or algorithms.
- It is a manifest violation of common expectations of a significant part of the Zcash community.
- Its update to a ZIP status, or its lack of a necessary status update, is inconsistent with the requirements in Specification of Status Workflow.
- For a Proposed, Active, Implemented, or Final ZIP, the update contains a substantive change that has significant community opposition.
- It is dependent on a patent that can be an obstacle to adoption of the ZIP.
- It includes commercial advertising or spam.
- It has disregard for formatting rules.
- It contains non-editorial edits to previous entries in the Change History of a ZIP, if there is one.
- An update to an existing ZIP contains an extension or change of its scope that is better handled as a separate ZIP.
- A new ZIP draft has a category that is not in agreement with its content. Or an update contains a change of a ZIP to an inappropriate category.
- It is a violation of any specific "must" or "must not" rule in this document.
- The expressed political views of an Owner of the document are hostile to the Zcash Code of Conduct [conduct]. (The removal of that Owner by an update is an exception.)
- The stated Owners of the ZIP did not authorize it.
- It contains the removal of an Owner without the consent of that Owner. (An exception is a removal for a reason that is directly related to a breach of the Code of Conduct by that Owner.)
- It is a violation of a conformance requirement of any Active Process ZIP (including this ZIP).
The ZIP Editors must not unreasonably deny publication of a ZIP draft or update that is not in violation of any of these criteria. If they refuse a ZIP draft or update, they must give an explanation of the criteria that were violated. As an exception, spam can be deleted without an explanation.
Communicating with the ZIP Editors
Send all ZIP-related communications by one of these methods:
- By email to <zips@z.cash>.
- By an issue that you open on the ZIPs issue tracker.
- By a message in the #zips channel on the Zcash R&D Discord.
Obey the Zcash Code of Conduct in all communications [conduct].
ZIP Editor Meeting Practices
We recommend that the ZIP Editors meet at regular intervals to do a review of draft changes to ZIPs. The current ZIP Editors agree on meeting times by consensus. A ZIP Editor meeting can be held even if some ZIP Editors are not available. But we recommend that all ZIP Editors are informed of significant decisions that are likely to be made at future meetings.
The ZIP Editors will appoint a ZIP Secretary. This can be a shared role or a rotating role. The ZIP Secretary will do these tasks:
- Share a draft agenda with the ZIP Editors a minimum of 24 hours before each ZIP Editor meeting.
- Share draft minutes of significant decisions with the ZIP Editors in the week after the ZIP Editor meeting.
- Share significant ZIP changes on the Zcash Community Forum. These include significant changes of status (in particular, progression of a ZIP to Proposed status).
If the draft agenda is empty, any ZIP Editor can send agenda items, or suggest the cancellation of the meeting.
ZIP format and structure
We recommend that the format of ZIPs is reStructuredText [rst], Markdown [markdown], or LaTeX [latex]. A ZIP in LaTeX must have a Makefile to build (at least) a PDF version of the document.
We recommend that each ZIP has these parts:
- Preamble
- Headers that contain metadata about the ZIP. (Refer to ZIP header preamble below.) The licensing terms are in the License field of the preamble. These terms must be acceptable in accordance with the ZIP licensing requirements.
- Terminology
- Definitions of technical or non-obvious terms in the document.
- Abstract
-
We recommend that the abstract is a short summary (approximately 200 words) with a clear description of these items:
- The issue that is addressed in the ZIP.
- The proposed solution.
- The intended outcome.
The ZIP must stay complete without the abstract.
We recommend that the abstract, as far as practical, contains sufficient context for readers to understand these points quickly:
- What the ZIP is about.
- Why it is important.
- How it fits into the wider Zcash ecosystem.
In addition to the summary of the technical content, we recommend that the abstract contains a short mention of any significant privacy implications. We recommend that the abstract is not vague or too generic. We recommend that it is an accurate, high-level summary of the ZIP. From such a summary, reviewers can understand the key ideas and potential implications although they do not read the full document.
- Motivation
- The motivation is critical for ZIPs whose purpose is to change the Zcash protocol. We recommend that it contains a clear explanation of why the existing protocol is inadequate for the problem that is solved in the ZIP.
- Privacy Implications
-
Some ZIPs contain trade-offs or assumptions that can have an effect on the privacy of Zcash users or protocol participants. We recommend that such a ZIP has this section. This section is not part of the Specification. Thus conformance requirements on implementations or processes must not be directly included or duplicated in it. Instead, it contains a high-level overview of the privacy implications that can be necessary to consider for deployment of the ZIP.
For example, the contents of this section can include:
- Trust assumptions with an effect on privacy that are introduced or changed by the ZIP.
- Privacy trade-offs or changes to anonymity guarantees.
- Potential data leakage (for example, from metadata, timing, or usage patterns).
- Exposure to known or novel privacy attack vectors.
We recommend that any applicable threat models are considered in the ZIP. A ZIP can contain new privacy-relevant assumptions or risks that are not addressed at this time. For such a ZIP, we recommend that updates to those threat models are proposed.
A change can have an effect on how wallets create, interpret, or expose transaction data, or can be a change to user-facing protocol behavior. For such a change, we recommend that the implications for user privacy in that context are assessed in the ZIP.
- Requirements
- This section contains a description of the high-level goals that must be achieved with the Specification. This section must not itself include conformance requirements. Thus it is possible to do a consistency check that the specified content is in agreement with the Requirements.
- Specification
- We recommend that the technical specification contains a description of the interface and semantics of any new feature. We recommend that the specification has sufficient detail for competing, interoperable implementations to be possible for any of the current Zcash platforms.
- Rationale
-
The rationale is an addition to the specification. It contains the motivation for the design and the reasons for particular design decisions. We recommend that it contains a description of the alternative designs that were considered and of related work. We recommend that the rationale contains evidence of consensus in the community and a discussion of important objections or concerns that were raised during discussion.
For longer ZIPs, it can be easier to put inline Rationale subsections at different points in the Specification part. With this approach, annotate the content of these subsections with HTML tags to make it collapsible. (Thus the rationale is available for review but is not an obstacle to a reader of the specification.) This syntax is available for ZIPs in Markdown (note the newline after the
<summary>tag):# Specification ## Foobar Important details. <details> <summary> ### Rationale for foobar </summary> Important but hidden rationale! </details>
This syntax is available for ZIPs in reStructuredText:
Specification ============= Foobar ------ Important details. Rationale for foobar '''''''''''''''''''' .. raw:: html <details> <summary>Click to show/hide</summary> Important but hidden rationale! .. raw:: html </details>
- Reference implementation
- Literal code that implements the specification of the ZIP, or a link to the reference implementation of that specification, or the two together. The reference implementation must be complete before any ZIP has status “Implemented” or “Final”. But it is generally not necessary for it to be complete before the ZIP is accepted into “Proposed”.
- Change History
-
A list of dates. Each date has details of any semantic changes to the ZIP (not editorial changes). This section is optional. If it is present, the Preamble must include a Last-Updated field.
We recommend that "living ZIPs" include this section. (These are Released ZIPs that have semantic changes after their initial transition out of Draft.) If semantic changes are made to a ZIP with a Change History section, the Change History section and Last-Updated field must also be updated.
ZIP stubs
A ZIP stub is a record that the ZIP Editors reserved a number for a ZIP that is in development. A ZIP stub is not a ZIP. But it exists in the ZIPs git repository [zips-repo] at the path of the corresponding ZIP. That path will be used for the corresponding ZIP if and when it is published. A ZIP stub has only a preamble. The value of the Status field in the preamble must be Reserved.
ZIP stubs can be added and removed, or replaced by the corresponding ZIP, at the discretion of the ZIP Editors. If a ZIP stub is removed, then its number can be used again, possibly for a fully different ZIP.
ZIP header preamble
The first part of each ZIP or ZIP stub must be an RFC 822-style header preamble. For ZIPs and ZIP stubs in reStructuredText, the representation is as follows: :: on the first line, then a blank line, then the preamble with an indent of 2 spaces.
A ZIP must have these header fields:
ZIP: Title: Owners: Status: Category: Created: License:
These additional header fields are optional for ZIPs:
Credits: Original-Authors: Discussions-To: Pull-Request: Last-Updated: Obsoleted-By: Updated-By: Obsoletes: Updates:
For a ZIP stub, the only fields that it must have are ZIP:, Title:, Status:, and Category:. Usually, the other fields applicable to ZIP stubs are Credits:, Discussions-To: and Pull-Request:. These fields are optional.
The Owners header contains the names and email addresses of all the Owners of the ZIP. We recommend that the format of the Owners header value is:
Random J. User <address@dom.ain>
If there are multiple Owners, put each Owner on a separate line.
We recommend that Credits: and Original-Authors: fields do not include email addresses.
The "Owners", "Credits", and "Original-Authors" headers always have these plural spellings. This applies even if there is only one Owner, one person to be credited, or one original author.
While a ZIP is in public discussions (usually during the initial Draft phase), a Discussions-To header will contain the URL where the ZIP is discussed. No Discussions-To header is necessary if the ZIP is discussed privately with the Owner.
The Pull-Request header, if present, contains a URL to a pull request for the ZIP.
The Category header contains the type of ZIP, as described in ZIP categories. Multiple categories can be specified, with " / " as the separator.
The Created header contains the submission date of the ZIP. Write dates in yyyy-mm-dd format, for example 2001-08-14.
For ZIPs in reStructuredText, we recommend that URLs in header fields are surrounded by < >. Then the link is rendered correctly.
Auxiliary Files
ZIPs can include auxiliary files such as diagrams. Put auxiliary files in a subdirectory for that ZIP. That is, for any ZIP that has more than one file, we recommend that all of the files are in a subdirectory named zip-XXXX.
ZIP categories
Each ZIP is in one or more of these categories, as specified in the Category header:
- Consensus
- Rules that have an effect on the consensus protocol that all Zcash implementations obey.
- Standards
- Non-consensus changes that have an effect on most or all Zcash implementations, or on the interoperability of applications that use Zcash.
- Process
- A Process ZIP contains the description of a process related to Zcash, or a proposal for a change to (or an event in) a process. Process ZIPs can contain a proposal for an implementation, but not a proposal for an implementation in the Zcash codebase. Community consensus is often necessary for them. Process ZIPs are different from Informational ZIPs: they are more than recommendations, and users are usually not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Zcash development.
- Consensus Process
- A subcategory of Process ZIP. It contains the specification of requirements and processes. These are to be realized by one or more Consensus ZIPs, by social consensus of the Zcash community, or by the two together.
- Informational
- An Informational ZIP contains the description of non-consensus Zcash design issues, or general guidelines or information for the Zcash community. These ZIPs are not necessarily a Zcash community consensus or recommendation. Thus users and implementors are free to ignore Informational ZIPs or to follow their advice.
- Network
- Specifications of peer-to-peer networking behaviour.
- RPC
- Specifications of the RPC interface that
zebraorzcashdnodes supply. - Wallet
- Specifications that have an effect on wallets (for example, non-consensus changes to how transactions, addresses, and other items are created or interpreted).
- Ecosystem
- Specifications that are useful to the Zcash ecosystem in other ways.
The ZIP Editors can add new categories by consensus.
We recommend that Consensus and Standards ZIPs have a Reference Implementation section. This section includes an implementation or (more often) a link to one.
We recommend that Consensus ZIPs have a Deployment section. This section contains a description of how and when the consensus change is planned to be deployed (for example, in a particular network upgrade).
ZIP Status Field
- Reserved
- The ZIP Editors reserved this ZIP number, and there can be a pull request for it, but no ZIP is published. We recommend that the ZIP Editors publish a stub header, so that the reservation is in the ZIP index. This status must be used only for ZIP stubs.
- Draft
- All initial ZIP submissions have this status.
- Withdrawn
- The Owners can remove their ZIP from consideration by the community. To do this, they change its status to Withdrawn (in a pull request or by request to the ZIP Editors).
- Active
- Usually used only for Process or Informational ZIPs. A Proposed ZIP has this status after rough consensus on it is reached in pull request or forum posts.
- Proposed
- Usually the stage after Draft. This status is added to a ZIP after consideration, feedback, and rough consensus from the community.
- Rejected
- If there is no progress on a Draft or Proposed ZIP for one year, we recommend that the ZIP Editors move it to Rejected status. The ZIP can have Draft or Proposed status again if the Owners start work again or resolve the issues that are an obstacle to consensus.
- Implemented
- This status applies when a Consensus or Standards ZIP has a working reference implementation, but before activation on the Zcash network. The status can contain the name of the node implementation that implemented the ZIP, for example "Implemented (zebra)" or "Implemented (zcashd)".
- Final
- This status applies when a Consensus or Standards ZIP is implemented and also activated on the Zcash network.
- Obsolete
- The status when a ZIP is no longer applicable (usually when it is superseded by a different ZIP).
If a ZIP has multiple Revisions, they can have different deployment status. In that case, we recommend that the status of each Revision is specified. The format is "[Revision 0] <Status-0>, [Revision 1] <Status-1>, ..." where "<Status-n>" is one of the alternatives above.
After any Revision is Released (as defined in the next section), all later Revisions must also be at least Proposed. (That is, they must not be Reserved or Draft.) For example, this status is not valid:
[Revision 0] Final, [Revision 1] Draft
It is not valid, because we recommend that changes that are in Draft are not applied yet.
Specification of Status Workflow
The Owners can decide on their own to change the status of their ZIP between Draft or Withdrawn. All other changes in status must have the approval of the current ZIP Editors, by consensus.
We recommend that the status of a ZIP changes from Draft (or Rejected) to Proposed only when two conditions are true. First, the Owner thinks that the ZIP is complete. Second, there is rough consensus on the forums, validated by consensus among the current ZIP Editors.
For a Consensus ZIP, a Deployment section must be present before the status of the ZIP can change to Proposed. Usually, but not necessarily, this section will contain the specification of a network upgrade for the activation of the consensus change.
The status of a ZIP is Released if it is Proposed, Active, Implemented, or Final (that is, not Draft, Rejected, Obsolete, or Withdrawn).
For a ZIP that has significant security or privacy implications, this rule applies: its status must not be changed from non-Released to Released before qualified security or privacy experts do an independent security review of the design.
Similarly, a change to a Released ZIP must have more independent review if one of these results is possible:
- The conclusions of a previous security or privacy review become invalid.
- Significant security or privacy implications stay unaddressed.
We recommend that a ZIP is not changed from a non-Released status to a Released status if there is significant community opposition to its content. (But Draft ZIPs explicitly can contain descriptions of proposals that have, or can be expected to have, significant community opposition.)
A Released ZIP must not be changed to a non-Released status in these two cases:
- The specification is already implemented and is in common use.
- The ZIP is a Process ZIP that is still a reflection of a consensus of the community.
We recommend that the status of a Standards ZIP changes from Proposed to Implemented only after the Owners supply an associated reference implementation. For Consensus ZIPs, the merge of an implementation into a minimum of one consensus node codebase must be complete. (At this time, this is zebra, zcashd, or the two together.) Usually the merge occurs in the period after the specification freeze of the network upgrade but before the implementation audit.
If the Owners miss this deadline, the ZIP Editors or the Owners can update the Deployment section of the ZIP at their discretion. The updated section has a different network upgrade as its target.
When a Process or Informational ZIP has rough consensus on the forum or pull request, we recommend that its status changes from Proposed to Active. Such a ZIP has rough consensus if all of these conditions are true:
- It was substantially complete and open to discussion on the forum or GitHub pull request for a minimum of one month.
- It was in Proposed status for a minimum of one week.
- No person still has any unaddressed substantiated objections to it.
Addressed or obstructive objections can be ignored or overruled by general agreement that they are sufficiently addressed. But clear reasoning must be given in such circumstances.
When an Active, Implemented, or Final ZIP is no longer applicable, we recommend that its status is changed to Obsolete. Examples of causes are that its implementation is no longer in use, or that its process is no longer followed. This change must also be objectively verifiable or discussed, or both.
Final ZIPs can be updated. Then the specification is still in force but is changed by another specified ZIP or ZIPs. (Refer to the optional Updated-By header.)
If a non-editorial update is made to an Obsolete, Withdrawn, or Rejected ZIP, its status must be changed as applicable.
The process above also applies to any later Revisions of a ZIP.
ZIP Comments
We recommend that the community makes comments on the ZIP in two places. The places are the Zcash Community Forum and the comment fields of the pull requests in any open ZIPs. The ZIP Editors will use these sources to judge rough consensus.
ZIP Licensing
New ZIPs can be accepted with the licenses that follow. Each new ZIP must have a minimum of one acceptable license identified in its preamble. Each license must be referenced by its abbreviation, given below.
For example, a preamble can include this License header:
License: BSD-2-Clause
GNU-All-Permissive
In this case, these two licenses each apply fully to the ZIP text: the OSI-approved BSD 2-clause license and the GNU All-Permissive License. Anyone can change and redistribute the text if they obey the terms of either license. In other words, the license list is an "OR choice", not an "AND also" requirement.
It is also possible to license source code differently from the ZIP text. We recommend that this case is indicated in the Reference Implementation section of the ZIP. Again, each license must be referenced by its abbreviation, given below.
Statements of code licenses in ZIPs are only advisory. If you intend to use the code, look for license statements in the code itself.
It is not necessary for ZIPs to be licensed exclusively under approved terms. ZIPs can also be licensed under unacceptable licenses in addition to a minimum of one acceptable license. In this case, list only the acceptable licenses in the License header.
Recommended licenses
- MIT: Expat/MIT/X11 license
- BSD-2-Clause: OSI-approved BSD 2-clause license
- BSD-3-Clause: OSI-approved BSD 3-clause license
- CC0-1.0: Creative Commons CC0 1.0 Universal
- GNU-All-Permissive: GNU All-Permissive License
- Apache-2.0: Apache License, version 2.0
Also, we recommend that literal code that is included in the ZIP, or written for and linked by the ZIP, is multi-licensed. The licenses are the union of the licenses of the projects that the code is intended for. Specifically, we recommend that code intended for zebra, zcashd, Zallet, Zaino, or their dependencies is multi-licensed under at least the MIT and Apache-2.0 license terms.
If a ZIP has a link to a reference implementation that does not obey that recommendation, its license terms must be documented in the ZIP.
Not recommended, but acceptable licenses
- BSL-1.0: Boost Software License, version 1.0
- CC-BY-4.0: Creative Commons Attribution 4.0 International
- CC-BY-SA-4.0: Creative Commons Attribution-ShareAlike 4.0 International
- FDL-1.3: GNU Free Documentation License, version 1.3
Not acceptable licenses
All licenses that are not explicitly in the lists above are not acceptable terms. They must not be used for a Zcash Improvement Proposal.
Rationale
In BIP 1 of Bitcoin, the approved options were the Open Publication License or release into the public domain. Was this insufficient?
- The OPL is generally regarded as obsolete, and not a license suitable for new publications.
- With the OPL license terms, the author was able to prevent publication and derived works. This was widely considered inappropriate.
- In some jurisdictions, the release of a work to the public domain is not recognised as a legitimate legal action. The result is a ZIP that only has copyright, with no permission at all for redistribution or change.
Why are software licenses included?
- Some ZIPs, especially in the Consensus category, can include literal code in the ZIP itself. It is possible that this code is not available under the exact license terms of the ZIP.
- But not all software licenses are acceptable for content in ZIPs.
Why are GPL/AGPL/LGPL-style licenses not included?
- No existing ZIP had these licenses.
- There is no reason to use such licenses for documentation. Also, literal code under these licenses in a ZIP can have an unwanted effect on the distribution terms of the full ZIP.
- If necessary, code under such licenses can be linked for informational purposes. This is also possible if the incompatibility of the code with one or more of the
zebra,zcashd,Zallet, andZainolicenses is noted.
See Also
Acknowledgements
We thank George Tankersley, Deirdre Connolly, Teor, Aditya Bharadwaj, and Conrado Gouvêa for their past contributions as ZIP Editors.
References
- [BCP14]
- Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
- [zip-0200]
- ZIP 200: Network Upgrade Mechanism
- [conduct]
- Zcash Code of Conduct
- [rst]
- reStructuredText documentation
- [markdown]
- The Markdown Guide
- [latex]
- LaTeX — a document preparation system
- [zips-repo]
- ZIPs git repository