mirror of https://github.com/zcash/zips.git
813 lines
34 KiB
ReStructuredText
813 lines
34 KiB
ReStructuredText
::
|
||
|
||
ZIP: 0
|
||
Title: ZIP Process
|
||
Owners: Daira Emma Hopwood <daira@electriccoin.co>
|
||
teor <teor@zfnd.org>
|
||
Jack Grigg <str4d@electriccoin.co>
|
||
Conrado Gouvea <conrado@zfnd.org>
|
||
Aditya Bharadwaj <nighthawk24@gmail.com>
|
||
Arya <arya@zfnd.org>
|
||
Original-Authors: Daira Emma Hopwood
|
||
Josh Cincinnati
|
||
George Tankersley
|
||
Deirdre Connolly
|
||
Credits: Luke Dashjr
|
||
Status: Active
|
||
Category: Process
|
||
Created: 2019-02-16
|
||
License: BSD-2-Clause
|
||
|
||
|
||
|
||
Terminology
|
||
===========
|
||
|
||
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY",
|
||
"RECOMMENDED", "OPTIONAL", and "REQUIRED" in this document are to
|
||
be interpreted as described in BCP 14 [#BCP14]_ when, and only when,
|
||
they appear in all capitals.
|
||
|
||
The term "network upgrade" in this document is to be interpreted as
|
||
described in ZIP 200. [#zip-0200]_
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
A Zcash Improvement Proposal (ZIP) is a design document providing
|
||
information to the Zcash community, or describing a new feature for
|
||
Zcash or its processes or environment. The ZIP should provide a concise
|
||
technical specification of the feature and a rationale for the feature.
|
||
|
||
We intend ZIPs to be the primary mechanism for proposing new features,
|
||
for collecting community input on an issue, and for documenting the
|
||
design decisions that have gone into Zcash. The Owner(s) of the ZIP
|
||
(usually the authors(s)) are responsible for building consensus within
|
||
the community and documenting dissenting opinions.
|
||
|
||
Because the ZIPs are maintained as text files in a versioned repository,
|
||
their revision history is the historical record of the feature proposal.
|
||
|
||
This document is based partly on the work done by Luke Dashjr with
|
||
`BIP 2 <https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki>`__.
|
||
|
||
|
||
ZIP Workflow
|
||
============
|
||
|
||
The ZIP process begins with a new idea for Zcash. Each potential ZIP
|
||
must have Owners — one or more people who write the ZIP using the style
|
||
and format described below, shepherd the discussions in the appropriate
|
||
forums, and attempt to build community consensus around the idea. The
|
||
ZIP Owners should first attempt to ascertain whether the idea is ZIP-able.
|
||
Small enhancements or patches to a particular piece of software often
|
||
don't require standardisation between multiple projects; these don't
|
||
need a ZIP and should be injected into the relevant project-specific
|
||
development workflow with a patch submission to the applicable issue
|
||
tracker. Additionally, many ideas have been brought forward for changing
|
||
Zcash that have been rejected for various reasons. The first step should
|
||
be to search past discussions to see if an idea has been considered
|
||
before, and if so, what issues arose in its progression. After
|
||
investigating past work, the best way to proceed is by posting about the
|
||
new idea to the `Zcash Community Forum <https://forum.zcashcommunity.com/>`__.
|
||
|
||
Vetting an idea publicly before going as far as writing a ZIP is meant
|
||
to save both the potential Owners and the wider community time. Asking
|
||
the Zcash 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 (searching the internet does not always do the trick).
|
||
It also helps to make sure the idea is applicable to the entire
|
||
community and not just the Owners. Just because an idea sounds good to
|
||
the Owners does not mean it will work for most people in most areas
|
||
where Zcash is used.
|
||
|
||
Once the Owners have asked the Zcash community as to whether an idea
|
||
has any chance of acceptance, a draft ZIP should be presented to the
|
||
`Zcash Community Forum <https://forum.zcashcommunity.com/>`__.
|
||
This gives the Owners a chance to flesh out the draft ZIP to make it
|
||
properly formatted, of high quality, and to address additional concerns
|
||
about the proposal. Following a discussion, the proposal should be
|
||
submitted to the ZIPs git repository [#zips-repo]_ as a pull request.
|
||
This draft must be written in ZIP style as described below, and named
|
||
with an alias such as ``draft-zatoshizakamoto-42millionzec`` until the
|
||
ZIP Editors have assigned it a ZIP number (Owners MUST NOT self-assign
|
||
ZIP numbers).
|
||
|
||
ZIP Owners are responsible for collecting community feedback on both
|
||
the initial idea and the ZIP before submitting it for review. However,
|
||
wherever possible, long open-ended discussions on forums should be avoided.
|
||
|
||
It is highly recommended that a single ZIP contain a single key proposal
|
||
or new idea. The more focused the ZIP, the more successful it tends to
|
||
be. If in doubt, split your ZIP into several well-focused ones.
|
||
|
||
When the ZIP draft is complete, the ZIP Editors will assign the ZIP a
|
||
number (if that has not already been done) and one or more Categories,
|
||
and merge the pull request to the ZIPs git repository. The ZIP Editors
|
||
will not unreasonably reject a ZIP. Reasons for rejecting ZIPs include
|
||
duplication of effort, disregard for formatting rules, being too
|
||
unfocused or too broad, being technically unsound, not providing proper
|
||
motivation or not in keeping with the Zcash philosophy. For a ZIP to be
|
||
accepted it must meet certain minimum criteria. It must be a clear and
|
||
complete description of the proposed enhancement. The enhancement must
|
||
represent a net improvement. The proposed implementation, if applicable,
|
||
must be solid and must not complicate the protocol unduly.
|
||
|
||
The ZIP Owners may update the draft as necessary in the git repository.
|
||
Updates to drafts should also be submitted by the Owners as pull requests.
|
||
|
||
|
||
ZIP Numbering Conventions
|
||
-------------------------
|
||
|
||
The ZIP Editors currently use the following conventions when numbering
|
||
ZIPs:
|
||
|
||
* if a ZIP directly corresponds to a BIP (Bitcoin Improvement Proposal),
|
||
and the number doesn't clash, assign the same number;
|
||
* if it affects the consensus layer or the core protocol, assign a
|
||
number in the range 200..299;
|
||
* if it affects only higher layers but is needed for interoperability
|
||
between node implementations or other parts of the ecosystem, assign
|
||
a number in the range 300..399;
|
||
* if it is specific to an implementation (e.g. zcashd or zebra), assign
|
||
a number in the range 400..499;
|
||
* if it concerns Consensus Process, assign a number in the range 0..9
|
||
or above 1000;
|
||
* try to number ZIPs that should or will be deployed together
|
||
consecutively (subject to the above conventions), and in a coherent
|
||
reading order.
|
||
|
||
These conventions are subject to change by consensus of the ZIP Editors.
|
||
|
||
|
||
Transferring ZIP Ownership
|
||
--------------------------
|
||
|
||
It occasionally becomes necessary to transfer ownership of ZIPs to a new
|
||
Owner. In general, we'd like to retain the original Owner as a
|
||
co-Owner of the transferred ZIP, but that's really up to the original
|
||
Owner. A good reason to transfer ownership is because the original
|
||
Owner no longer has the time or interest in updating it or following
|
||
through with the ZIP process, or has fallen off the face of the 'net
|
||
(i.e. is unreachable or not responding to email). A bad reason to
|
||
transfer ownership is because you don't agree with the direction of the
|
||
ZIP. We try to build consensus around a ZIP, but if that's not possible,
|
||
you can always submit a competing ZIP.
|
||
|
||
If you are interested in assuming ownership of a ZIP, send a message
|
||
asking to take over, addressed to all of the current Owner(s) and the
|
||
ZIP Editors. If the Owner(s) who are proposed to be removed don't respond
|
||
in a timely manner, the ZIP Editors and any remaining current Owners will
|
||
make a decision (such decisions may be reversed).
|
||
|
||
If an author of a ZIP is no longer an Owner, an Original-Authors: field
|
||
SHOULD be added to the ZIP metadata indicating the original authorship
|
||
(without email addresses), unless the original author(s) request otherwise.
|
||
|
||
|
||
ZIP Editors
|
||
-----------
|
||
|
||
The current ZIP Editors are:
|
||
|
||
* Daira Emma Hopwood and Jack Grigg, associated with the Electric Coin
|
||
Company;
|
||
* teor, Conrado Gouvea, and Arya, associated with the Zcash Foundation.
|
||
* Aditya Bharadwaj, associated with Nighthawk Apps.
|
||
|
||
All can be reached at zips@z.cash. The current design of the ZIP Process
|
||
dictates that there are always at least two ZIP Editors: at least one
|
||
from the Electric Coin Company and at least one from the Zcash Foundation.
|
||
|
||
ZIP Editors MUST declare any potential or perceived conflict of interest
|
||
they have relating to their responsibilities as ZIP Editors.
|
||
|
||
ZIP Editors MUST be publicly transparent about any external influence
|
||
or constraints that have been placed or attempted to be placed on their
|
||
actions as ZIP Editors (including from the Electric Coin Company,
|
||
Zcash Foundation, or Nighthawk Apps), whether or not it affects those
|
||
actions. This should not be interpreted as requiring ZIP Editors to
|
||
reveal knowledge of undisclosed security vulnerabilities or mitigations.
|
||
|
||
Additional Editors may be selected, with their consent, by consensus
|
||
among the current Editors.
|
||
|
||
An Editor may be removed or replaced by consensus among the current
|
||
Editors. However, if the other ZIP Editors have consensus, an Editor
|
||
can not prevent their own removal.
|
||
|
||
Any Editor can resign by informing the other Editors in writing.
|
||
|
||
Whenever the ZIP Editors change, the new ZIP Editors SHOULD:
|
||
|
||
* review this ZIP to make sure it reflects current practice,
|
||
* update the Owners of this ZIP,
|
||
* review access to the `ZIPs repository <https://github.com/zcash/zips>`_,
|
||
* update the <zips@z.cash> email alias, and
|
||
* invite new Editors to the Zcash Community Forum, and the #zips channel on Discord.
|
||
|
||
If it has been at least 12 months since the last ZIP Editor change, the ZIP Editors SHOULD:
|
||
|
||
* review this ZIP to make sure it reflects current practice.
|
||
|
||
|
||
ZIP Editor Responsibilities
|
||
---------------------------
|
||
|
||
The ZIP Editors subscribe to the `Zcash Community Forum.
|
||
<https://forum.zcashcommunity.com/>`__
|
||
|
||
Each new ZIP SHOULD be submitted as a "pull request" to the ZIPs git
|
||
repository [#zips-repo]_. It SHOULD NOT contain a ZIP number unless
|
||
one had already been assigned by the ZIP Editors. The pull request
|
||
SHOULD initially be marked as a Draft. The ZIP content SHOULD be
|
||
submitted in reStructuredText [#rst]_ or Markdown [#markdown]_
|
||
format. Generating HTML for a ZIP is OPTIONAL.
|
||
|
||
For each new ZIP that comes in, the ZIP Editors SHOULD:
|
||
|
||
* Read the ZIP to check if it is ready: sound and complete. The ideas
|
||
must make technical sense, even if they don't seem likely to be
|
||
accepted.
|
||
* Check that the title accurately describes the content.
|
||
* Ensure that the ZIP draft has been sent to the Zcash Community Forum
|
||
and as a PR to the ZIPs git repository [#zips-repo]_.
|
||
* Ensure that motivation and backward compatibility have been
|
||
addressed, if applicable.
|
||
* Check that the licensing terms are acceptable for ZIPs.
|
||
|
||
Reviewing a ZIP
|
||
---------------
|
||
|
||
Any ZIP Editor can suggest changes to a ZIP. These suggestions are the
|
||
opinion of the individual ZIP Editor. Any technical or process review that
|
||
ZIP Editors perform is expected to be independent of their contractual or
|
||
other relationships.
|
||
|
||
ZIP Owners are free to clarify, modify, or decline suggestions from ZIP Editors.
|
||
If the ZIP Editors make a change to a ZIP that the Owners disagree with, then
|
||
the Editors SHOULD revert the change.
|
||
|
||
|
||
Typically, the ZIP Editors suggest changes in two phases:
|
||
|
||
* `content review`: multiple ZIP Editors discuss the ZIP, 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. This ensures the ZIP is consistent
|
||
with other Zcash specifications.
|
||
|
||
If the ZIP isn't ready, the Editors will send it back to the Owners for
|
||
revision, with specific instructions. This decision is made by consensus
|
||
among the current Editors.
|
||
|
||
When a ZIP is ready, the ZIP Editors will:
|
||
|
||
* Ensure that a unique ZIP number has been assigned in the pull request.
|
||
* Regenerate the corresponding HTML documents, if required.
|
||
* Remove Draft status and merge the pull request.
|
||
|
||
The ZIP editors monitor ZIP changes and update ZIP headers as
|
||
appropriate.
|
||
|
||
Rejecting a ZIP or update
|
||
-------------------------
|
||
|
||
The ZIP Editors MAY reject a new ZIP or an update to an existing ZIP,
|
||
by consensus among the current Editors. Rejections can be based on any
|
||
of the following reasons:
|
||
|
||
* it violates the Zcash Code of Conduct [#conduct]_ ;
|
||
* it appears too unfocused or broad;
|
||
* it duplicates effort in other ZIPs without sufficient technical justification
|
||
(however, alternative proposals to address similar or overlapping problems
|
||
are not excluded for this reason);
|
||
* it has manifest security flaws (including being unrealistically dependent
|
||
on user vigilance to avoid security weaknesses);
|
||
* it disregards compatibility with the existing Zcash blockchain or ecosystem;
|
||
* it is manifestly unimplementable;
|
||
* it includes buggy code, pseudocode, or algorithms;
|
||
* it manifestly violates common expectations of a significant portion of the
|
||
Zcash community;
|
||
* it updates a ZIP's status, or fails to make a needed status update, in a way
|
||
inconsistent with the requirements in `Specification of Status Workflow`_;
|
||
* in the case of a Proposed, Active, Implemented, or Final ZIP, the update
|
||
makes a substantive change to which there is significant community opposition;
|
||
* it is dependent on a patent that could potentially be an obstacle to
|
||
adoption of the ZIP;
|
||
* it includes commercial advertising or spam;
|
||
* it disregards formatting rules;
|
||
* it makes non-editorial edits to previous entries in a ZIP's Change history,
|
||
if there is one;
|
||
* an update to an existing ZIP extends or changes its scope to an extent
|
||
that would be better handled as a separate ZIP;
|
||
* a new ZIP has a category that does not reflect its content, or an update
|
||
would change a ZIP to an inappropriate category;
|
||
* it violates any specific "MUST" or "MUST NOT" rule in this document;
|
||
* the expressed political views of a Owner of the document are inimical
|
||
to the Zcash Code of Conduct [#conduct]_ (except in the case of an update
|
||
removing that Owner);
|
||
* it is not authorized by the stated ZIP Owners;
|
||
* it removes an Owner without their consent (unless the reason for removal
|
||
is directly related to a breach of the Code of Conduct by that Owner);
|
||
* it violates a conformance requirement of any Active Process ZIP
|
||
(including this ZIP).
|
||
|
||
The ZIP Editors MUST NOT unreasonably deny publication of a ZIP proposal
|
||
or update that does not violate any of these criteria. If they refuse a
|
||
proposal or update, they MUST give an explanation of which of the
|
||
criteria were violated, with the exception that spam may be deleted
|
||
without an explanation.
|
||
|
||
Note that it is not the primary responsibility of the ZIP Editors to
|
||
review proposals for security, correctness, or implementability.
|
||
|
||
Communicating with the ZIP Editors
|
||
----------------------------------
|
||
|
||
Please send all ZIP-related communications either:
|
||
|
||
* by email to <zips@z.cash>,
|
||
* by opening an issue on the `ZIPs issue tracker <https://github.com/zcash/zips/issues>`_, or
|
||
* by sending a message in the `#zips channel on the Zcash R&D Discord <https://discord.com/channels/809218587167293450/809251050741170187>`_.
|
||
|
||
**All communications should abide by the Zcash Code of Conduct** [#conduct]_
|
||
**and follow the GNU Kind Communication Guidelines** [#gnukind]_.
|
||
|
||
ZIP Editor Meeting Practices
|
||
----------------------------
|
||
|
||
The ZIP Editors SHOULD meet on a regular basis to review draft changes to
|
||
ZIPs. Meeting times are agreed by consensus among the current ZIP Editors.
|
||
A ZIP Editor meeting can be held even if some ZIP Editors are not available, but
|
||
all Editors SHOULD be informed of significant decisions that are likely to be made
|
||
at upcoming meetings.
|
||
|
||
The ZIP Editors will appoint a ZIP Secretary, which can be a shared or rotating
|
||
role. The ZIP Secretary will:
|
||
|
||
* share a draft agenda with the ZIP Editors at least 24 hours before each ZIP Editors' meeting;
|
||
* share draft minutes of significant decisions with the ZIP Editors in the week after the
|
||
ZIP Editors' meeting; and
|
||
* share significant ZIP changes, including significant changes of status (in
|
||
particular, progression of a ZIP to Proposed status), on the Zcash Community
|
||
Forum.
|
||
|
||
If the draft agenda is empty, any ZIP Editor MAY submit agenda items, or suggest
|
||
that the meeting is cancelled.
|
||
|
||
ZIP format and structure
|
||
========================
|
||
|
||
ZIPs SHOULD be written in reStructuredText [#rst]_, Markdown [#markdown]_,
|
||
or LaTeX [#latex]_. For ZIPs written in LaTeX, a ``Makefile`` MUST be
|
||
provided to build (at least) a PDF version of the document.
|
||
|
||
Each ZIP SHOULD have the following parts:
|
||
|
||
* Preamble — Headers containing metadata about the ZIP (`see
|
||
below <#zip-header-preamble>`__).
|
||
The License field of the preamble indicates the licensing terms,
|
||
which MUST be acceptable according to `the ZIP licensing requirements <#zip-licensing>`__.
|
||
|
||
* Terminology — Definitions of technical or non-obvious terms used
|
||
in the document.
|
||
|
||
* Abstract — A short (~200 word) description of the technical issue
|
||
being addressed.
|
||
|
||
* Motivation — The motivation is critical for ZIPs that want to change
|
||
the Zcash protocol. It should clearly explain why the existing
|
||
protocol is inadequate to address the problem that the ZIP solves.
|
||
|
||
* Specification — The technical specification should describe the
|
||
interface and semantics of any new feature. The specification should be
|
||
detailed enough to allow competing, interoperable implementations for
|
||
any of the current Zcash platforms.
|
||
|
||
* 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. The rationale should provide evidence of
|
||
consensus within the community and discuss important objections or
|
||
concerns raised during discussion.
|
||
|
||
For longer ZIPs it can potentially be easier to have inline Rationale
|
||
subsections interspersed throughout the Specification part. When taking
|
||
this approach, the content of these subsections should be annotated
|
||
with HTML tags to make it collapsible (so the rationale is available
|
||
for review but doesn't get in the way of reading the specification).
|
||
ZIPs written in Markdown can use the following syntax (note the
|
||
newline after the ``<summary>`` tag)::
|
||
|
||
# Specification
|
||
|
||
## Foobar
|
||
|
||
Important details.
|
||
|
||
<details>
|
||
<summary>
|
||
|
||
### Rationale for foobar
|
||
</summary>
|
||
|
||
Important but hidden rationale!
|
||
</details>
|
||
|
||
ZIPs written in reStructuredText can use the following syntax::
|
||
|
||
Specification
|
||
=============
|
||
|
||
Foobar
|
||
------
|
||
|
||
Important details.
|
||
|
||
Rationale for foobar
|
||
''''''''''''''''''''
|
||
|
||
.. raw:: html
|
||
|
||
<details>
|
||
<summary>Click to show/hide</summary>
|
||
|
||
Important but hidden rationale!
|
||
|
||
.. raw:: html
|
||
|
||
</details>
|
||
|
||
* Security and privacy considerations — If applicable, security
|
||
and privacy considerations should be explicitly described, particularly
|
||
if the ZIP makes explicit trade-offs or assumptions. For guidance on
|
||
this section consider RFC 3552 [#RFC3552]_ as a starting point.
|
||
|
||
* Reference implementation — Literal code implementing the ZIP's
|
||
specification, and/or a link to the reference implementation of
|
||
the ZIP's specification. The reference implementation MUST be
|
||
completed before any ZIP is given status “Implemented” or “Final”,
|
||
but it generally need not be completed before the ZIP is accepted
|
||
into “Proposed”.
|
||
|
||
ZIP stubs
|
||
---------
|
||
|
||
A ZIP stub records that the ZIP Editors have reserved a number for a
|
||
ZIP that is under development. It is not a ZIP, but exists in the ZIPs
|
||
git repository [#zips-repo]_ at the same path that will be used for the
|
||
corresponding ZIP if and when it is published. It consists only of a
|
||
preamble, which MUST use Reserved as the value of the Status field.
|
||
|
||
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 MAY be reused, possibly for an entirely different ZIP.
|
||
|
||
ZIP header preamble
|
||
-------------------
|
||
|
||
Each ZIP or ZIP stub MUST begin with a RFC 822-style header preamble.
|
||
For ZIPs and ZIP stubs written in reStructuredText, this is represented
|
||
as ``::`` on the first line, followed by a blank line, then the preamble
|
||
indented by 2 spaces.
|
||
|
||
The following header fields are REQUIRED for ZIPs::
|
||
|
||
ZIP:
|
||
Title:
|
||
Owners:
|
||
Status:
|
||
Category:
|
||
Created:
|
||
License:
|
||
|
||
The following additional header fields are OPTIONAL for ZIPs::
|
||
|
||
Credits:
|
||
Original-Authors:
|
||
Discussions-To:
|
||
Pull-Request:
|
||
Obsoleted-By:
|
||
Updated-By:
|
||
Obsoletes:
|
||
Updates:
|
||
|
||
For ZIP stubs, only the ZIP:, Title:, Status:, and Category: fields
|
||
are REQUIRED. Typically the other fields applicable to ZIP stubs are
|
||
Credits:, Discussions-To: and Pull-Request:, which are OPTIONAL.
|
||
|
||
The Owners header lists the names and email addresses of all the
|
||
Owners of the ZIP. The format of the Owners header value SHOULD be::
|
||
|
||
Random J. User <address@dom.ain>
|
||
|
||
If there are multiple Owners, each should be on a separate line.
|
||
|
||
Credits: and Original-Authors: fields SHOULD NOT include email addresses.
|
||
|
||
The "Owners", "Credits", and "Original-Authors" headers always use
|
||
these plural spellings even 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 indicate the URL where the ZIP is
|
||
being discussed. No Discussions-To header is necessary if the ZIP is being
|
||
discussed privately with the Owner.
|
||
|
||
The Pull-Request header, if present, gives an URL to a Pull Request for
|
||
the ZIP.
|
||
|
||
The Category header specifies the type of ZIP, as described in
|
||
`ZIP categories`_. Multiple categories MAY be specified, separated by
|
||
" ``/`` ".
|
||
|
||
The Created header records the date that the ZIP was submitted.
|
||
Dates should be in yyyy-mm-dd format, e.g. 2001-08-14.
|
||
|
||
For ZIPs written in reStructuredText, URLs in header fields SHOULD be
|
||
surrounded by ``<`` ``>``; this ensures that the link is rendered correctly.
|
||
|
||
Auxiliary Files
|
||
---------------
|
||
|
||
ZIPs may include auxiliary files such as diagrams. Auxiliary files
|
||
should be included in a subdirectory for that ZIP; that is, for any ZIP
|
||
that requires more than one file, all of the files SHOULD be in a
|
||
subdirectory named zip-XXXX.
|
||
|
||
|
||
ZIP categories
|
||
==============
|
||
|
||
Each ZIP is in one or more of the following categories, as specified
|
||
in the Category header:
|
||
|
||
Consensus
|
||
Rules that affect the consensus protocol followed by all Zcash
|
||
implementations.
|
||
Standards
|
||
Non-consensus changes affecting most or all Zcash implementations, or
|
||
the interoperability of applications using Zcash.
|
||
Process
|
||
A Process ZIP describes a process surrounding Zcash, or proposes a
|
||
change to (or an event in) a process. They may propose an implementation,
|
||
but not to Zcash's codebase; they often require community consensus;
|
||
unlike Informational ZIPs, 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 Zcash development.
|
||
Consensus Process
|
||
A subcategory of Process ZIP that specifies requirements and processes
|
||
that are to be realized by one or more Consensus ZIPs, and/or by social
|
||
consensus of the Zcash community.
|
||
Informational
|
||
An Informational ZIP describes non-consensus Zcash design issues, or
|
||
general guidelines or information for the Zcash community. These ZIPs
|
||
do not necessarily represent a Zcash community consensus or
|
||
recommendation, so users and implementors are free to ignore
|
||
Informational ZIPs or follow their advice.
|
||
Network
|
||
Specifications of peer-to-peer networking behaviour.
|
||
RPC
|
||
Specifications of the RPC interface provided by zcashd nodes.
|
||
Wallet
|
||
Specifications affecting wallets (e.g. non-consensus changes to how
|
||
transactions, addresses, etc. are constructed or interpreted).
|
||
Ecosystem
|
||
Specifications otherwise useful to the Zcash ecosystem.
|
||
|
||
New categories may be added by consensus among the ZIP Editors.
|
||
|
||
Consensus and Standards ZIPs SHOULD have a Reference Implementation section,
|
||
which includes or (more often) links to an implementation.
|
||
|
||
Consensus ZIPs SHOULD have a Deployment section, describing 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 have reserved this ZIP number, and there MAY
|
||
be a Pull Request for it, but no ZIP has been published. The ZIP Editors
|
||
SHOULD publish a stub header so that the reservation appears in the
|
||
`ZIP index <https://zips.z.cash#index-of-zips>`__. This status MUST
|
||
only be used for ZIP stubs.
|
||
|
||
* Draft: All initial ZIP submissions have this status.
|
||
|
||
* Withdrawn: The Owners of a ZIP MAY remove it from consideration by
|
||
the community, by changing its status to Withdrawn (in a PR or by
|
||
request to the ZIP Editors).
|
||
|
||
* Active: Typically only used for Process or Informational ZIPs, achieved
|
||
once rough consensus on a Proposed ZIP is reached in PR/forum posts.
|
||
|
||
* Proposed: Typically the stage after Draft, added to a ZIP after
|
||
consideration, feedback, and rough consensus from the community.
|
||
|
||
* Rejected: If no progress on a Draft or Proposed ZIP has been made for
|
||
one year, the ZIP Editors SHOULD move it to Rejected status. It can
|
||
revert back to Draft or Proposed if the Owners resume work or resolve
|
||
issues preventing consensus.
|
||
|
||
* Implemented: When a Consensus or Standards ZIP has a working
|
||
reference implementation but before activation on the Zcash network.
|
||
The status MAY indicate which node implementation has implemented
|
||
the ZIP, e.g. "Implemented (zcashd)" or "Implemented (zebra)".
|
||
|
||
* Final: When a Consensus or Standards ZIP is both implemented and
|
||
activated on the Zcash network.
|
||
|
||
* Obsolete: The status when a ZIP is no longer relevant (typically when
|
||
superseded by another ZIP).
|
||
|
||
Specification of Status Workflow
|
||
--------------------------------
|
||
|
||
Owners of a ZIP MAY decide on their own to change the status between
|
||
Draft or Withdrawn. All other changes in status MUST be approved by
|
||
consensus among the current ZIP Editors.
|
||
|
||
A ZIP SHOULD only change status from Draft (or Rejected) to Proposed,
|
||
when the Owner deems it is complete and there is rough consensus on the
|
||
forums, validated by consensus among the current ZIP Editors. If it's a
|
||
Consensus ZIP, a Deployment section MUST be present in order for the ZIP
|
||
to change status to Proposed. Typically, although not necessarily, this
|
||
will specify a network upgrade in which the consensus change is to activate.
|
||
|
||
A ZIP's status is Released if it is Proposed, Active, Implemented, or Final
|
||
(i.e. not Draft, Rejected, Obsolete, or Withdrawn).
|
||
|
||
A ZIP SHOULD NOT be changed from a non-Released status to a Released
|
||
status if there is significant community opposition to its content.
|
||
(However, Draft ZIPs explicitly MAY describe proposals to which there
|
||
is, or could be expected, significant community opposition.)
|
||
|
||
A Released ZIP MUST NOT be changed to a non-Released status if the
|
||
specification is already implemented and is in common use, or where a
|
||
Process ZIP still reflects a consensus of the community.
|
||
|
||
A Standards ZIP SHOULD only change status from Proposed to Implemented
|
||
once the Owners provide an associated reference implementation. For
|
||
Consensus ZIPs, an implementation MUST have been merged into at least
|
||
one consensus node codebase (currently zcashd and/or zebra), typically
|
||
in the period after the network upgrade's specification freeze but before
|
||
the implementation audit. If the Owners miss this deadline, the Editors
|
||
or Owners MAY choose to update the Deployment section of the ZIP to
|
||
target another upgrade, at their discretion.
|
||
|
||
A Process or Informational ZIP SHOULD change status from Proposed to
|
||
Active when it achieves rough consensus on the forum or PR. Such a
|
||
proposal is said to have rough consensus if it has been substantially
|
||
complete and open to discussion on the forum or GitHub PR for at least
|
||
one month, has been in Proposed status for at least one week, and no
|
||
person maintains any unaddressed substantiated objections to it. Addressed
|
||
or obstructive objections can be ignored/overruled by general agreement
|
||
that they have been sufficiently addressed, but clear reasoning MUST be
|
||
given in such circumstances.
|
||
|
||
When an Active, Implemented, or Final ZIP is no longer relevant –for
|
||
example because its implementation has fallen out of use or its process
|
||
is no longer followed– its status SHOULD be changed to Obsolete. This
|
||
change MUST also be objectively verifiable and/or discussed. Final ZIPs
|
||
MAY be updated; the specification is still in force but modified by
|
||
another specified ZIP or ZIPs (check the optional Updated-By header).
|
||
|
||
If a non-editorial update is made to an Obsolete, Withdrawn, or
|
||
Rejected ZIP, its status MUST be changed appropriately.
|
||
|
||
|
||
ZIP Comments
|
||
============
|
||
|
||
Comments from the community on the ZIP should occur on the Zcash
|
||
Community Forum and the comment fields of the pull requests in
|
||
any open ZIPs. Editors will use these sources to judge rough consensus.
|
||
|
||
|
||
ZIP Licensing
|
||
=============
|
||
|
||
New ZIPs may be accepted with the following licenses. Each new ZIP MUST
|
||
identify at least one acceptable license in its preamble. Each license
|
||
MUST be referenced by their respective abbreviation given below.
|
||
|
||
For example, a preamble might include the following License header::
|
||
|
||
License: BSD-2-Clause
|
||
GNU-All-Permissive
|
||
|
||
In this case, the ZIP text is fully licensed under both the OSI-approved
|
||
BSD 2-clause license as well as the GNU All-Permissive License, and
|
||
anyone may modify and redistribute the text provided they comply with
|
||
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. This case SHOULD be indicated in the Reference Implementation
|
||
section of the ZIP. Again, each license MUST be referenced by its
|
||
respective abbreviation given below.
|
||
|
||
Statements of code licenses in ZIPs are only advisory; anyone intending
|
||
to use the code should look for license statements in the code itself.
|
||
|
||
ZIPs are not required to be *exclusively* licensed under approved
|
||
terms, and MAY also be licensed under unacceptable licenses
|
||
*in addition to* at least one acceptable license. In this case, only the
|
||
acceptable license(s) should be listed in the License header.
|
||
|
||
|
||
Recommended licenses
|
||
--------------------
|
||
|
||
* MIT: `Expat/MIT/X11 license <https://opensource.org/licenses/MIT>`__
|
||
* BSD-2-Clause: `OSI-approved BSD 2-clause
|
||
license <https://opensource.org/licenses/BSD-2-Clause>`__
|
||
* BSD-3-Clause: `OSI-approved BSD 3-clause
|
||
license <https://opensource.org/licenses/BSD-3-Clause>`__
|
||
* CC0-1.0: `Creative Commons CC0 1.0
|
||
Universal <https://creativecommons.org/publicdomain/zero/1.0/>`__
|
||
* GNU-All-Permissive: `GNU All-Permissive
|
||
License <https://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html>`__
|
||
* Apache-2.0: `Apache License, version
|
||
2.0 <https://www.apache.org/licenses/LICENSE-2.0>`__
|
||
|
||
In addition, it is RECOMMENDED that literal code included in the ZIP be
|
||
dual-licensed under the same license terms as the project it modifies.
|
||
For example, literal code intended for zcashd would ideally be
|
||
dual-licensed under the MIT license terms as well as one of the above
|
||
with the rest of the ZIP text.
|
||
|
||
Not recommended, but acceptable licenses
|
||
----------------------------------------
|
||
|
||
* BSL-1.0: `Boost Software License, version
|
||
1.0 <https://www.boost.org/LICENSE_1_0.txt>`__
|
||
* CC-BY-4.0: `Creative Commons Attribution 4.0
|
||
International <https://creativecommons.org/licenses/by/4.0/>`__
|
||
* CC-BY-SA-4.0: `Creative Commons Attribution-ShareAlike 4.0
|
||
International <https://creativecommons.org/licenses/by-sa/4.0/>`__
|
||
* AGPL-3.0+: `GNU Affero General Public License (AGPL), version 3 or
|
||
newer <https://www.gnu.org/licenses/agpl-3.0.en.html>`__
|
||
* FDL-1.3: `GNU Free Documentation License, version
|
||
1.3 <https://www.gnu.org/licenses/fdl-1.3.en.html>`__
|
||
* GPL-2.0+: `GNU General Public License (GPL), version 2 or
|
||
newer <https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>`__
|
||
* LGPL-2.1+: `GNU Lesser General Public License (LGPL), version 2.1 or
|
||
newer <https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>`__
|
||
|
||
Not acceptable licenses
|
||
-----------------------
|
||
|
||
All licenses not explicitly included in the above lists are not
|
||
acceptable terms and MUST NOT be used for a Zcash Improvement Proposal.
|
||
|
||
Rationale
|
||
---------
|
||
|
||
Bitcoin's BIP 1 allowed the Open Publication License or releasing into
|
||
the public domain; was this insufficient?
|
||
|
||
* The OPL is generally regarded as obsolete, and not a license suitable
|
||
for new publications.
|
||
* The OPL license terms allowed for the author to prevent publication
|
||
and derived works, which was widely considered inappropriate.
|
||
* In some jurisdictions, releasing a work to the public domain is not
|
||
recognised as a legitimate legal action, leaving the ZIP simply
|
||
copyrighted with no redistribution or modification allowed at all.
|
||
|
||
Why are there software licenses included?
|
||
|
||
* Some ZIPs, especially in the Consensus category, may include literal
|
||
code in the ZIP itself which may not be available under the exact
|
||
license terms of the ZIP.
|
||
* Despite this, not all software licenses would be acceptable for
|
||
content included in ZIPs.
|
||
|
||
|
||
See Also
|
||
========
|
||
|
||
* `RFC 7282: On Consensus and Humming in the
|
||
IETF <https://www.rfc-editor.org/rfc/rfc7282.html>`__
|
||
* `Zcash Network Upgrade Pipeline <https://electriccoin.co/blog/the-zcash-network-upgrade-pipeline/>`__
|
||
|
||
|
||
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" <https://www.rfc-editor.org/info/bcp14>`_
|
||
.. [#RFC3552] `RFC 3552: Guidelines for Writing RFC Text on Security Considerations <https://www.rfc-editor.org/rfc/rfc3552.html>`_
|
||
.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <zip-0200.rst>`_
|
||
.. [#conduct] `Zcash Code of Conduct <https://github.com/zcash/zcash/blob/master/code_of_conduct.md>`_
|
||
.. [#gnukind] `GNU Kind Communication Guidelines <https://www.gnu.org/philosophy/kind-communication.en.html>`_
|
||
.. [#rst] `reStructuredText documentation <https://docutils.sourceforge.io/rst.html>`_
|
||
.. [#markdown] `The Markdown Guide <https://www.markdownguide.org/>`_
|
||
.. [#latex] `LaTeX — a document preparation system <https://www.latex-project.org/>`_
|
||
.. [#zips-repo] `ZIPs git repository <https://github.com/zcash/zips>`_
|