mirror of https://github.com/zcash/zips.git
304 lines
18 KiB
HTML
304 lines
18 KiB
HTML
<!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 <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="dontpanic"><span class="section-heading">Don’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’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"><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 “MUST”, “REQUIRED”, “MUST NOT”, “SHOULD”, and “MAY” 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 “Mainnet” and “Testnet” 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 “full validator” 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’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"><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 – 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"><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’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’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 “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="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 “<code>$latex code$</code>” in either Markdown or (as a
|
||
non-standard extension) reStructuredText. This syntax does not work in tables for
|
||
reStructuredText; in that case use “<code>:math:`latex code`</code>” 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’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>“<code>.. note::</code>” in reStructuredText or “<code><div class="note"></div></code>” 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>“<code>.. warning::</code>” in reStructuredText or “<code><div class="warning"></div></code>” 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 “MUST”
|
||
or “SHOULD” 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 “<code>make</code>”) 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. “snark” <a href="#fn:8" id="fnref:8" title="see footnote" class="footnote"><sup>8</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>
|
||
|
||
<pre><code class="rst">.. [#snark] `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.
|
||
</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-<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="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 — “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="#fnref:1" title="return to body" class="reversefootnote"> ↩︎</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"> ↩︎</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"> ↩︎</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"> ↩︎</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"> ↩︎</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"> ↩︎</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"> ↩︎</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"> ↩︎</a></p>
|
||
</li>
|
||
|
||
</ol>
|
||
</div>
|
||
</body>
|
||
</html>
|