Example subheading

At least while the ZIP is in Draft, we encourage writing open questions and TODOs.

Comparison of ZIPs to RFCs

Like RFCs, ZIPs are precise technical documents that SHOULD give enough implementation information to implement part of a Zcash-related protocol or follow a Zcash-related process 7.

ZIPs are different from RFCs in the following ways:

• Many (but not all) ZIPs are "living documents"; they are updated in-place as the relevant areas of the protocol or process change. Unlike in the RFC process, making a change in an area described by a published ZIP does not necessarily require creating a new ZIP, although that is an option if the change is extensive enough to warrant it.
• The expected structure of a ZIP is more constrained than an RFC. For example, the Specification section is REQUIRED, and all of the conformance requirements MUST go in that section. The ZIP editors will help you to ensure that things go in the right sections.
• Security considerations SHOULD be spread throughout the text, in the places where they are most relevant.

Using mathematical notation

Embedded \(\LaTeX\!\) , e.g. \(x + y\!\) , is allowed and encouraged in ZIPs. The syntax for inline math is "$latex code$" in either Markdown or (as a non-standard extension) reStructuredText. This syntax does not work in tables for reStructuredText; in that case use ":math:`latex code`" instead.

The rendered HTML will use KaTeX 6, which only supports a subset of \(\LaTeX\!\) , so you will need to double-check that the rendering is as intended.

In general the conventions in the Zcash protocol specification SHOULD be followed. If you find this difficult, don't worry too much about it in initial drafts; the ZIP editors will catch any inconsistencies in review.

Notes and warnings

Valid markup

This is optional before publishing a PR, but to check whether a document is valid reStructuredText or Markdown, first install rst2html5 and pandoc. E.g. on Debian-based distros:

sudo apt install python3-pip pandoc perl sed
pip3 install docutils==0.19 rst2html5

Then, with draft-myzip.rst or draft-myzip.md in the root directory of a clone of this repo, run:

make draft-myzip.html

(or just "make") and view draft-myzip.html in a web browser.

Citations and references

Each reference should be given a short name, e.g. "snark" 8. The syntax to cite that reference is "[#snark]_" in reStructuredText, or "[^snark]" in Markdown.

The corresponding entry in the References section should look like this in reStructuredText:

.. [#snark] `The Hunting of the Snark <https://www.gutenberg.org/files/29888/29888-h/29888-h.htm>`_. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.

or like this in Markdown:

[^snark] [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.

Note that each entry must be on a single line regardless of how long that makes the line. In Markdown there must be a blank line between entries.

The current rendering of a Markdown ZIP reorders the references according to their first use; the rendering of a reStructuredText ZIP keeps them in the same order as in the References section.

To link to another section of the same ZIP, use "`Section title`_" in reStructuredText, or "[Section title]" in Markdown.

Citing the Zcash protocol specification

For references to the Zcash protocol specification, prefer to link to a section anchor, and name the reference as [#protocol-<anchor>]. This makes it more likely that the link will remain valid if sections are renumbered or if content is moved. The anchors in the protocol specification can be displayed by clicking on a section heading in most PDF viewers. References to particular sections should be versioned, even though the link will point to the most recent stable version.

Do not include the "https://zips.z.cash/" part of URLs to ZIPs or the protocol spec.