zips/rendered/zip-guide-markdown.html

304 lines
18 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<title>ZIP guide-markdown: {Something Short and To the Point}</title>
<meta charset="utf-8" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous" onload="renderMathInElement(document.body);"></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 &lt;email&gt;
...
Credits: First Credited
...
Status: Draft
Category: {Consensus | Standards Track | Network | RPC | Wallet | Informational | Process}
Created: yyyy-mm-dd
License: {usually MIT}
Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/???">https://github.com/zcash/zips/pull/???</a>&gt;
</code></pre>
<h1 id="dontpanic"><span class="section-heading">Don&#8217;t Panic</span><span class="section-anchor"> <a rel="bookmark" href="#dontpanic"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h1>
<p>If this is your first time writing a ZIP, the structure and format may look
intimidating. But really, it&#8217;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&#8217;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"><span class="section-heading">Terminology</span><span class="section-anchor"> <a rel="bookmark" href="#terminology"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h1>
<p>{Edit this to reflect the key words that are actually used.}
The key words &#8220;MUST&#8221;, &#8220;REQUIRED&#8221;, &#8220;MUST NOT&#8221;, &#8220;SHOULD&#8221;, and &#8220;MAY&#8221; in this
document are to be interpreted as described in BCP 14 <a href="#fn:1" id="fnref:1" title="see footnote" class="footnote"><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 &#8220;Mainnet&#8221; and &#8220;Testnet&#8221; in this document are to be interpreted as
defined in the Zcash protocol specification <a href="#fn:2" id="fnref:2" title="see footnote" class="footnote"><sup>2</sup></a>.</p>
<p>The term &#8220;full validator&#8221; in this document is to be interpreted as defined in
the Zcash protocol specification <a href="#fn:3" id="fnref:3" title="see footnote" class="footnote"><sup>3</sup></a>.</p>
<p>The terms below are to be interpreted as follows:</p>
<p>{Term to be defined}</p>
<p>:{Definition.}
</p>
<p>{Another term}</p>
<p>:{Definition.}
</p>
<h1 id="abstract"><span class="section-heading">Abstract</span><span class="section-anchor"> <a rel="bookmark" href="#abstract"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></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="#fn:4" id="fnref:4" title="see footnote" class="footnote"><sup>4</sup></a> <a href="#fn:5" id="fnref:5" title="see footnote" class="footnote"><sup>5</sup></a>.}</p>
<h1 id="motivation"><span class="section-heading">Motivation</span><span class="section-anchor"> <a rel="bookmark" href="#motivation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></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&#8217;t include any of the actual specification &#8211;
don&#8217;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"><span class="section-heading">Requirements</span><span class="section-anchor"> <a rel="bookmark" href="#requirements"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h1>
<p>{Describe design constraints on, or goals for the solution &#8211; typically one
paragraph for each constraint or goal. Again, don&#8217;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"><span class="section-heading">Non-requirements</span><span class="section-anchor"> <a rel="bookmark" href="#non-requirements"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></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"><span class="section-heading">Specification</span><span class="section-anchor"> <a rel="bookmark" href="#specification"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></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&#8217;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="#fn:2" title="see footnote" class="footnote"><sup>2</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="examplesubheading"><span class="section-heading">Example subheading</span><span class="section-anchor"> <a rel="bookmark" href="#examplesubheading"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>At least while the ZIP is in Draft, we encourage writing open questions and TODOs.</p>
<h3 id="openquestions"><span class="section-heading">Open questions</span><span class="section-anchor"> <a rel="bookmark" href="#openquestions"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<ul>
<li>What happens if a full validator can&#8217;t parse the fandangle as a doohicky?</li>
</ul>
<p>TODO: define byte encoding for the Jabberwock.</p>
<h2 id="comparisonofzipstorfcs"><span class="section-heading">Comparison of ZIPs to RFCs</span><span class="section-anchor"> <a rel="bookmark" href="#comparisonofzipstorfcs"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></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="#fn:6" id="fnref:6" title="see footnote" class="footnote"><sup>6</sup></a>.</p>
<p>ZIPs are different from RFCs in the following ways:</p>
<ul>
<li>Many (but not all) ZIPs are &#8220;living documents&#8221;; 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="usingmathematicalnotation"><span class="section-heading">Using mathematical notation</span><span class="section-anchor"> <a rel="bookmark" href="#usingmathematicalnotation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>Embedded <span class="math">\(\LaTeX\)</span>, e.g. <span class="math">\(x + y\)</span>, is allowed and encouraged in ZIPs. The syntax for
inline math is &#8220;<code>$latex code$</code>&#8221; in either Markdown or (as a
non-standard extension) reStructuredText. This syntax does not work in tables for
reStructuredText; in that case use &#8220;<code>:math:`latex code`</code>&#8221; instead.</p>
<p>The rendered HTML will use KaTeX <a href="#fn:7" id="fnref:7" title="see footnote" class="footnote"><sup>7</sup></a>, which only supports a subset of <span class="math">\(\LaTeX\)</span>,
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&#8217;t worry too much about it in initial drafts; the
ZIP editors will catch any inconsistencies in review.</p>
<h2 id="notesandwarnings"><span class="section-heading">Notes and warnings</span><span class="section-anchor"> <a rel="bookmark" href="#notesandwarnings"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<div class="note"></div>
<p>&#8220;<code>.. note::</code>&#8221; in reStructuredText or &#8220;<code>&lt;div class=&quot;note&quot;&gt;&lt;/div&gt;</code>&#8221; in Markdown
(followed by a blank line in either case), can be used for an aside from the main
text. The rendering of notes is colourful and may be distracting, so they should
only be used for important points.</p>
<div class="warning"></div>
<p>&#8220;<code>.. warning::</code>&#8221; in reStructuredText or &#8220;<code>&lt;div class=&quot;warning&quot;&gt;&lt;/div&gt;</code>&#8221; in
Markdown (followed by a blank line in either case), can be used for warnings.
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 &#8220;MUST&#8221;
or &#8220;SHOULD&#8221; conformance requirement is more appropriate.</p>
<p>In Markdown, notes and warnings can currently only be a single paragraph.</p>
<h2 id="validmarkup"><span class="section-heading">Valid markup</span><span class="section-anchor"> <a rel="bookmark" href="#validmarkup"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This is optional before publishing a PR, but to check whether a document is valid
reStructuredText or Markdown, first install <code>docutils</code> and <code>rst2html5</code>, and
build <code>MultiMarkdown-6</code>. E.g. on Debian-based distros::</p>
<pre><code>sudo apt install python3-pip perl sed cmake
pip3 install 'docutils==0.21.2' 'rst2html5==2.0.1'
git clone -b develop https://github.com/Electric-Coin-Company/MultiMarkdown-6
cd MultiMarkdown-6
make release
cd build
make
sudo make install
</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 &#8220;<code>make</code>&#8221;) and view <code>draft-myzip.html</code> in a web browser.</p>
<h2 id="citationsandreferences"><span class="section-heading">Citations and references</span><span class="section-anchor"> <a rel="bookmark" href="#citationsandreferences"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>Each reference should be given a short name, e.g. &#8220;snark&#8221; <a href="#fn:8" id="fnref:8" title="see footnote" class="footnote"><sup>8</sup></a>. The syntax to cite
that reference is &#8220;<code>[#snark]_</code>&#8221; in reStructuredText, or &#8220;<code>[^snark]</code>&#8221; in Markdown.</p>
<p>The corresponding entry in the <a href="#references">References</a> section should look like this in
reStructuredText:</p>
<pre><code class="rst">.. [#snark] `The Hunting of the Snark &lt;<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>&gt;_. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
</code></pre>
<p>or like this in Markdown::</p>
<pre><code class="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.
</code></pre>
<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>
<pre><code class="rst">`Section title`_
</code></pre>
<p>in reStructuredText, or</p>
<pre><code class="markdown">[Section title]
</code></pre>
<p>in Markdown.</p>
<h3 id="citingthezcashprotocolspecification"><span class="section-heading">Citing the Zcash protocol specification</span><span class="section-anchor"> <a rel="bookmark" href="#citingthezcashprotocolspecification"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>For references to the Zcash protocol specification, prefer to link to a section
anchor, and name the reference as <code>[^protocol-&lt;anchor&gt;]</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 &#8220;<code>https://zips.z.cash/</code>&#8221; part of URLs to ZIPs or the protocol spec.</p>
<h1 id="referenceimplementation"><span class="section-heading">Reference implementation</span><span class="section-anchor"> <a rel="bookmark" href="#referenceimplementation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h1>
<p>{This section is entirely optional; if present, it usually gives links to zcashd or
zebrad PRs.}</p>
<h1 id="references"><span class="section-heading">References</span><span class="section-anchor"> <a rel="bookmark" href="#references"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h1>
<div class="footnotes">
<hr />
<ol>
<li id="fn:1">
<p><a href="https://www.rfc-editor.org/info/bcp14">Information on BCP 14 — &#8220;RFC 2119: Key words for use in RFCs to Indicate Requirement Levels&#8221; and &#8220;RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words&#8221;</a> <a href="#fnref:1" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:2">
<p><a href="protocol/protocol.pdf#networks">Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet</a> <a href="#fnref:2" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:3">
<p><a href="protocol/protocol.pdf#blockchain">Zcash Protocol Specification, Version 2022.3.8. Section 3.3: The Block Chain</a> <a href="#fnref:3" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:4">
<p><a href="protocol/protocol.pdf">Zcash Protocol Specification, Version 2022.3.8 or later</a> <a href="#fnref:4" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:5">
<p><a href="protocol/protocol.pdf#introduction">Zcash Protocol Specification, Version 2022.3.8. Section 1: Introduction</a> <a href="#fnref:5" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:6">
<p><a href="zip-0000">ZIP 0: ZIP Process</a> <a href="#fnref:6" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:7">
<p><a href="https://katex.org/">KaTeX - The fastest math typesetting library for the web</a> <a href="#fnref:7" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
<li id="fn:8">
<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="#fnref:8" title="return to body" class="reversefootnote">&#160;&#8617;&#xfe0e;</a></p>
</li>
</ol>
</div>
</body>
</html>