mirror of https://github.com/zcash/zips.git
255 lines
14 KiB
HTML
255 lines
14 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<title>ZIP guide-markdown: {Something Short and To the Point}</title>
|
||
<meta charset="utf-8" />
|
||
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="css/style.css">
|
||
</head>
|
||
<body>
|
||
<pre><code>ZIP: Unassigned {numbers are assigned by ZIP editors}
|
||
Title: {Something Short and To the Point}
|
||
Owners: First Owner <email>
|
||
...
|
||
Credits: First Credited
|
||
...
|
||
Status: Draft
|
||
Category: {Consensus | Standards Track | Network | RPC | Wallet | Informational | Process}
|
||
Created: yyyy-mm-dd
|
||
License: {usually MIT}
|
||
Pull-Request: <<a href="https://github.com/zcash/zips/pull/???">https://github.com/zcash/zips/pull/???</a>></code></pre>
|
||
<h1 id="dont-panic">Don’t Panic</h1>
|
||
<p>If this is your first time writing a ZIP, the structure and format
|
||
may look intimidating. But really, it’s just meant to reflect
|
||
common-sense practice and some technical conventions. Feel free to start
|
||
with a simple initial draft that gets ideas across, even if it doesn’t
|
||
quite follow this format. The community and ZIP editors will help you
|
||
figure things out and get it into shape later.</p>
|
||
<p>{Delete this section.}</p>
|
||
<h1 id="terminology">Terminology</h1>
|
||
<p>{Edit this to reflect the key words that are actually used.} The key
|
||
words “MUST”, “REQUIRED”, “MUST NOT”, “SHOULD”, and “MAY” in this
|
||
document are to be interpreted as described in BCP 14 <a href="#fn1"
|
||
class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>
|
||
when, and only when, they appear in all capitals.</p>
|
||
<p>{Avoid duplicating definitions from other ZIPs. Instead use wording
|
||
like this:}</p>
|
||
<p>The terms “Mainnet” and “Testnet” in this document are to be
|
||
interpreted as defined in the Zcash protocol specification <a
|
||
href="#fn2" class="footnote-ref" id="fnref2"
|
||
role="doc-noteref"><sup>2</sup></a>.</p>
|
||
<p>The term “full validator” in this document is to be interpreted as
|
||
defined in the Zcash protocol specification <a href="#fn3"
|
||
class="footnote-ref" id="fnref3"
|
||
role="doc-noteref"><sup>3</sup></a>.</p>
|
||
<p>The terms below are to be interpreted as follows:</p>
|
||
<dl>
|
||
<dt>{Term to be defined}</dt>
|
||
<dd>
|
||
<p>{Definition.}</p>
|
||
</dd>
|
||
<dt>{Another term}</dt>
|
||
<dd>
|
||
<p>{Definition.}</p>
|
||
</dd>
|
||
</dl>
|
||
<h1 id="abstract">Abstract</h1>
|
||
<p>{Describe what this proposal does, typically in a few paragraphs.</p>
|
||
<p>The Abstract should only provide a summary of the ZIP; the ZIP should
|
||
remain complete without the Abstract.</p>
|
||
<p>Use links where applicable, e.g. <a href="#fn4" class="footnote-ref"
|
||
id="fnref4" role="doc-noteref"><sup>4</sup></a> <a href="#fn5"
|
||
class="footnote-ref" id="fnref5"
|
||
role="doc-noteref"><sup>5</sup></a>.}</p>
|
||
<h1 id="motivation">Motivation</h1>
|
||
<p>{Why is this proposal needed?</p>
|
||
<p>This is one of the most important sections of the ZIP, and should be
|
||
detailed and comprehensive. It shouldn’t include any of the actual
|
||
specification – don’t put conformance requirements in this section.</p>
|
||
<p>Explain the status quo, why the status quo is in need of improvement,
|
||
and if applicable, the history of how this area has changed. Then
|
||
describe <em>at a high level</em> why this proposed solution addresses
|
||
the perceived issues. It is ok if this is somewhat redundant with the
|
||
abstract, but here you can go into a lot more detail.}</p>
|
||
<h1 id="requirements">Requirements</h1>
|
||
<p>{Describe design constraints on, or goals for the solution –
|
||
typically one paragraph for each constraint or goal. Again, don’t
|
||
actually specify anything here; this section is primarily for use as a
|
||
consistency check that what is specified meets the requirements.}</p>
|
||
<h1 id="non-requirements">Non-requirements</h1>
|
||
<p>{This section is entirely optional. If it is present, it describes
|
||
issues that the proposal is <em>not</em> attempting to address, that
|
||
someone might otherwise think it does or should.}</p>
|
||
<h1 id="specification">Specification</h1>
|
||
<p>{Replace this entire section.}</p>
|
||
<p>The Specification section describes what should change, using precise
|
||
language and conformance key words. Anything that is <em>required in
|
||
order to implement the ZIP</em> (or follow its process, in the case of a
|
||
Process ZIP) should be in this section.</p>
|
||
<p>Avoid overspecification! Also avoid underspecification. Specification
|
||
is hard. Don’t be afraid to ask for help.</p>
|
||
<p>Feel free to copy from other ZIPs doing similar things, e.g. defining
|
||
RPC calls, consensus rules, etc.</p>
|
||
<p>ZIPs MUST take into account differences between the Zcash Mainnet and
|
||
Testnet <a href="#fn6" class="footnote-ref" id="fnref6"
|
||
role="doc-noteref"><sup>6</sup></a> where applicable. A consensus ZIP
|
||
MUST be able to be deployed on both Mainnet and Testnet.</p>
|
||
<p>Unless the specification is particularly simple, you will need to
|
||
organise it under subheadings.</p>
|
||
<h2 id="example-subheading">Example subheading</h2>
|
||
<p>At least while the ZIP is in Draft, we encourage writing open
|
||
questions and TODOs.</p>
|
||
<h3 id="open-questions">Open questions</h3>
|
||
<ul>
|
||
<li>What happens if a full validator can’t parse the fandangle as a
|
||
doohicky?</li>
|
||
</ul>
|
||
<p>TODO: define byte encoding for the Jabberwock.</p>
|
||
<h2 id="comparison-of-zips-to-rfcs">Comparison of ZIPs to RFCs</h2>
|
||
<p>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 <a href="#fn7"
|
||
class="footnote-ref" id="fnref7"
|
||
role="doc-noteref"><sup>7</sup></a>.</p>
|
||
<p>ZIPs are different from RFCs in the following ways:</p>
|
||
<ul>
|
||
<li>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 <em>necessarily</em> require creating a new ZIP, although
|
||
that is an option if the change is extensive enough to warrant it.</li>
|
||
<li>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.</li>
|
||
<li>Security considerations SHOULD be spread throughout the text, in the
|
||
places where they are most relevant.</li>
|
||
</ul>
|
||
<h2 id="using-mathematical-notation">Using mathematical notation</h2>
|
||
<p>Embedded LaTeX <span
|
||
class="math inline"><em>x</em> + <em>y</em></span> is allowed and
|
||
encouraged in ZIPs. The syntax for inline math is
|
||
“<code>:math:</code>latex
|
||
code`<code>" in reStructuredText or "</code><span
|
||
class="math inline"><em>l</em><em>a</em><em>t</em><em>e</em><em>x</em><em>c</em><em>o</em><em>d</em><em>e</em></span>`”
|
||
in Markdown. The rendered HTML will use KaTeX <a href="#fn8"
|
||
class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>,
|
||
which only supports a subset of LaTeX, so you will need to double-check
|
||
that the rendering is as intended.</p>
|
||
<p>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.</p>
|
||
<h2 id="notes-and-warnings">Notes and warnings</h2>
|
||
<div class="info">
|
||
<p>“<code>.. note::</code>” in reStructuredText, or
|
||
“<code>:::info</code>” (terminated by “<code>:::</code>”) in Markdown,
|
||
can be used for an aside from the main text.</p>
|
||
<p>The rendering of notes is colourful and may be distracting, so they
|
||
should only be used for important points.</p>
|
||
</div>
|
||
<div class="warning">
|
||
<p>“<code>.. warning::</code>” in reStructuredText, or
|
||
“<code>:::warning</code>” (terminated by “<code>:::</code>”) in
|
||
Markdown, can be used for warnings.</p>
|
||
<p>Warnings should be used very sparingly — for example to signal that a
|
||
entire specification, or part of it, may be inapplicable or could cause
|
||
significant interoperability or security problems. In most cases, a
|
||
“MUST” or “SHOULD” conformance requirement is more appropriate.</p>
|
||
</div>
|
||
<h2 id="valid-markup">Valid markup</h2>
|
||
<p>This is optional before publishing a PR, but to check whether a
|
||
document is valid reStructuredText or Markdown, first install
|
||
<code>rst2html5</code> and <code>pandoc</code>. E.g. on Debian-based
|
||
distros::</p>
|
||
<pre><code>sudo apt install python3-pip pandoc perl sed
|
||
pip3 install docutils==0.19 rst2html5</code></pre>
|
||
<p>Then, with <code>draft-myzip.rst</code> or
|
||
<code>draft-myzip.md</code> in the root directory of a clone of this
|
||
repo, run::</p>
|
||
<pre><code>make draft-myzip.html</code></pre>
|
||
<p>(or just “<code>make</code>”) and view <code>draft-myzip.html</code>
|
||
in a web browser.</p>
|
||
<h2 id="citations-and-references">Citations and references</h2>
|
||
<p>Each reference should be given a short name, e.g. “snark” <a
|
||
href="#fn9" class="footnote-ref" id="fnref9"
|
||
role="doc-noteref"><sup>9</sup></a>. The syntax to cite that reference
|
||
is “<code>[#snark]_</code>” in reStructuredText, or
|
||
“<code>[^snark]</code>” in Markdown.</p>
|
||
<p>The corresponding entry in the <a href="#references">References</a>
|
||
section should look like this in reStructuredText:</p>
|
||
<div class="sourceCode" id="cb4"><pre
|
||
class="sourceCode rst"><code class="sourceCode rest"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="dt">.. [#snark] </span>`The Hunting of the Snark <<a href="https://www.gutenberg.org/files/29888/29888-h/29888-h.htm">https://www.gutenberg.org/files/29888/29888-h/29888-h.htm</a>>_. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.</span></code></pre></div>
|
||
<p>or like this in Markdown::</p>
|
||
<div class="sourceCode" id="cb5"><pre
|
||
class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="ot">[^snark]</span> <span class="co">[</span><span class="ot">The Hunting of the Snark</span><span class="co">](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm)</span>. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.</span></code></pre></div>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
<p>To link to another section of the same ZIP, use</p>
|
||
<div class="sourceCode" id="cb6"><pre
|
||
class="sourceCode rst"><code class="sourceCode rest"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="ot">`Section title`_</span></span></code></pre></div>
|
||
<p>in reStructuredText, or</p>
|
||
<div class="sourceCode" id="cb7"><pre
|
||
class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="co">[</span><span class="ot">Section title</span><span class="co">]</span></span></code></pre></div>
|
||
<p>in Markdown.</p>
|
||
<h3 id="citing-the-zcash-protocol-specification">Citing the Zcash
|
||
protocol specification</h3>
|
||
<p>For references to the Zcash protocol specification, prefer to link to
|
||
a section anchor, and name the reference as
|
||
<code>[^protocol-<anchor>]</code>. 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.</p>
|
||
<p>Do not include the “<code>https://zips.z.cash/</code>” part of URLs
|
||
to ZIPs or the protocol spec.</p>
|
||
<h1 id="reference-implementation">Reference implementation</h1>
|
||
<p>{This section is entirely optional; if present, it usually gives
|
||
links to zcashd or zebrad PRs.}</p>
|
||
<h1 id="references">References</h1>
|
||
<aside id="footnotes" class="footnotes footnotes-end-of-document"
|
||
role="doc-endnotes">
|
||
<hr />
|
||
<ol>
|
||
<li id="fn1"><p><a
|
||
href="https://www.rfc-editor.org/info/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”</a><a href="#fnref1" class="footnote-back"
|
||
role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn2"><p><a href="protocol/protocol.pdf#networks">Zcash Protocol
|
||
Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet</a><a
|
||
href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn3"><p><a href="protocol/protocol.pdf#blockchain">Zcash
|
||
Protocol Specification, Version 2022.3.8. Section 3.3: The Block
|
||
Chain</a><a href="#fnref3" class="footnote-back"
|
||
role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn4"><p><a href="protocol/protocol.pdf">Zcash Protocol
|
||
Specification, Version 2022.3.8 or later</a><a href="#fnref4"
|
||
class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn5"><p><a href="protocol/protocol.pdf#introduction">Zcash
|
||
Protocol Specification, Version 2022.3.8. Section 1: Introduction</a><a
|
||
href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn6"><p><a href="protocol/protocol.pdf#networks">Zcash Protocol
|
||
Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet</a><a
|
||
href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn7"><p><a href="zip-0000">ZIP 0: ZIP Process</a><a
|
||
href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn8"><p><a href="https://katex.org/">KaTeX - The fastest math
|
||
typesetting library for the web</a><a href="#fnref8"
|
||
class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
<li id="fn9"><p><a
|
||
href="https://www.gutenberg.org/files/29888/29888-h/29888-h.htm">The
|
||
Hunting of the Snark</a>. Lewis Carroll, with illustrations by Henry
|
||
Holiday. MacMillan and Co. London. March 29, 1876.<a href="#fnref9"
|
||
class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
||
</ol>
|
||
</aside>
|
||
</body>
|
||
</html>
|