Add macros and Makefile support for building the Orchard draft specification.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
2021-01-10 23:50:36 +00:00 · 2021-01-10 23:50:36 +00:00 · 9bc9823a23
parent 3751c9973d
commit 9bc9823a23
3 changed files with 128 additions and 5 deletions
--- a/protocol/Makefile
+++ b/protocol/Makefile
@ -18,10 +18,10 @@ NOCRUFT?=|perl -pe 's|[{\<\(]\/[^ ]* ?||g;s|^.* has been referenced but does not

 .PHONY: all all-specs release
 all: .Makefile.uptodate
-	$(MAKE) canopy heartwood blossom sapling sprout
+	$(MAKE) orchard canopy heartwood blossom sapling sprout

 all-specs: .Makefile.uptodate
-	$(MAKE) canopy.pdf heartwood.pdf blossom.pdf sapling.pdf sprout.pdf
+	$(MAKE) orchard.pdf canopy.pdf heartwood.pdf blossom.pdf sapling.pdf sprout.pdf

 release:
 ifeq ($(shell git tag --points-at HEAD |wc -l),0)
@ -55,6 +55,9 @@ heartwood.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapl
 canopy.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
 	$(MAKE) canopy

+orchard.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
+	$(MAKE) orchard
+
 .PHONY: auxsprout
 auxsprout:
 	printf '\\renewcommand{\\docversion}{Version %s [\\SproutSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver
@ -116,6 +119,18 @@ canopy:
 	mv -f aux/canopy.pdf .
 	cp -f canopy.pdf protocol.pdf

+.PHONY: auxorchard
+auxorchard:
+	printf '\\toggletrue{isorchard}\n\\renewcommand{\\docversion}{Version %s [\\OrchardSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver
+	mkdir -p aux
+	rm -f aux/orchard.*
+	$(LATEXMK) -jobname=orchard -auxdir=aux -outdir=aux $(EXTRAOPT) protocol $(NOCRUFT)
+
+.PHONY: orchard
+orchard:
+	$(MAKE) auxorchard
+	mv -f aux/orchard.pdf .
+
 .PHONY: nolatexmk-sprout
 nolatexmk-sprout:
 	printf '\\renewcommand{\\docversion}{Version %s [\\SproutSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver
@ -177,6 +192,18 @@ nolatexmk-canopy:
 	sh mymakeindex.sh -o canopy.ind canopy.idx
 	$(LATEX) -jobname=canopy protocol.tex || { touch incremental_merkle.png; exit 1; }

+.PHONY: nolatexmk-orchard
+nolatexmk-orchard:
+	printf '\\toggletrue{isorchard}\n\\renewcommand{\\docversion}{Version %s [\\OrchardSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver
+	# If $(LATEX) fails, touch an input so that 'make' won't think it is up-to-date next time.
+	rm -f orchard.aux orchard.bbl orchard.blg orchard.brf orchard.bcf
+	$(LATEX) -jobname=orchard protocol.tex || { touch incremental_merkle.png; exit 1; }
+	biber orchard
+	$(LATEX) -jobname=orchard protocol.tex || { touch incremental_merkle.png; exit 1; }
+	$(LATEX) -jobname=orchard protocol.tex || { touch incremental_merkle.png; exit 1; }
+	sh mymakeindex.sh -o orchard.ind orchard.idx
+	$(LATEX) -jobname=orchard protocol.tex || { touch incremental_merkle.png; exit 1; }
+
 .PHONY: clean
 clean:
-	rm -f aux/* html/* protocol.ver protocol.pdf canopy.pdf heartwood.pdf blossom.pdf sapling.pdf sprout.pdf
+	rm -f aux/* html/* protocol.ver protocol.pdf orchard.pdf canopy.pdf heartwood.pdf blossom.pdf sapling.pdf sprout.pdf
--- a/protocol/protocol.tex
+++ b/protocol/protocol.tex
@ -483,6 +483,7 @@
 \newcommand{\BlossomSpec}{Overwinter+Sapling+Blossom}
 \newcommand{\HeartwoodSpec}{Overwinter+Sapling+Blossom+Heartwood}
 \newcommand{\CanopySpec}{Overwinter+Sapling+Blossom+Heartwood+Canopy}
+\newcommand{\OrchardSpec}{Orchard proposal}
 \newtoggle{issapling}
 \togglefalse{issapling}
 \newtoggle{isblossom}
@ -491,6 +492,8 @@
 \togglefalse{isheartwood}
 \newtoggle{iscanopy}
 \togglefalse{iscanopy}
+\newtoggle{isorchard}
+\togglefalse{isorchard}
 \InputIfFileExists{protocol.ver}{}{}

 \newcommand{\doctitle}{Zcash Protocol Specification}
@ -525,8 +528,24 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg
 \newcommand{\heartwoodcolorname}{orange}
 \newcommand{\canopycolor}{red!50!blue!85}
 \newcommand{\canopycolorname}{purple}
+\newcommand{\orchardcolor}{black!15!blue!65!green!65}
+\newcommand{\orchardcolorname}{slate blue}
 \newcommand{\labelcolor}{yellow!20}

+\iftoggle{isorchard}{
+  \providecommand{\baseurl}{https://zips.z.cash/protocol/orchard.pdf}
+  \toggletrue{iscanopy}
+  \newcommand{\setorchard}{\color{\orchardcolor}}
+  \newcommand{\orchard}[1]{\texorpdfstring{{\setorchard{#1}}}{#1}}
+  \newcommand{\notorchard}[1]{}
+  \newcommand{\notbeforeorchard}[1]{#1}
+} {
+  \newcommand{\setorchard}{}
+  \newcommand{\orchard}[1]{}
+  \newcommand{\notorchard}[1]{#1}
+  \newcommand{\notbeforeorchard}[1]{}
+}
+
 \iftoggle{iscanopy}{
  \providecommand{\baseurl}{https://zips.z.cash/protocol/protocol.pdf}
  \toggletrue{isheartwood}
@ -658,6 +677,8 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg
 \newcommand{\HeartwoodText}{\textbf{Heartwood}}
 \newcommand{\Canopy}{\termbf{Canopy}}
 \newcommand{\CanopyText}{\textbf{Canopy}}
+\newcommand{\Orchard}{\termbf{Orchard}}
+\newcommand{\OrchardText}{\textbf{Orchard}}
 \newcommand{\Bitcoin}{\termbf{Bitcoin}}
 \newcommand{\BitcoinText}{\textbf{Bitcoin}}
 \newcommand{\CryptoNote}{\termbf{CryptoNote}}
@ -2030,6 +2051,8 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg
 \newcommand{\consensusrule}[1]{\needspace{4ex}\vspace{2ex}\callout{}{Consensus rule:}{#1}}
 \newenvironment{consensusrules}{\introlist\callout{}{Consensus rules:}\begin{itemize}}{\end{itemize}}

+\newcommand{\preorcharditem}[1]{\item \preorchard{#1}}
+\newcommand{\orchardonwarditem}[1]{\orchard{\item {[\Orchard proposal]}\, {#1}}}
 \newcommand{\precanopyitem}[1]{\item \precanopy{#1}}
 \newcommand{\canopyonwarditem}[1]{\canopy{\item {[\Canopy onward]}\, {#1}}}
 \newcommand{\preheartwooditem}[1]{\item \preheartwood{#1}}
@ -2044,6 +2067,8 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg
 \newcommand{\overwinteronwarditem}[1]{\overwinter{\item {[\Overwinter onward]}\, {#1}}}
 \newcommand{\sproutspecificitem}[1]{\item \sproutspecific{#1}}

+\newcommand{\preorchard}[1]{\notbeforeorchard{\orchard{[Pre-\Orchard\!]\,}} {#1}}
+\newcommand{\orchardonward}[1]{\orchard{[\Orchard proposal]\, {#1}}}
 \newcommand{\precanopy}[1]{\notbeforecanopy{\canopy{[Pre-\Canopy\!]\,}} {#1}}
 \newcommand{\canopyonward}[1]{\canopy{[\Canopy onward]\, {#1}}}
 \newcommand{\preheartwood}[1]{\notbeforeheartwood{\heartwood{[Pre-\Heartwood\!]\,}} {#1}}
@ -2066,6 +2091,8 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg
 \newcommand{\nnote}[1]{\needspace{4ex}\vspace{2ex}\callout{}{Non-normative note:}{#1}}
 \newenvironment{nnotes}{\introlist\callout{}{Non-normative notes:}\begin{itemize}}{\end{itemize}}

+\newcommand{\orchardonwardnnote}[1]{\orchard{\callout{[\Orchard proposal]\,\,}{Non-normative note:}{#1}}}
+\newcommand{\orchardonwardpnote}[1]{\orchard{\callout{[\Orchard proposal]\,\,}{Note:}{#1}}}
 \newcommand{\canopyonwardnnote}[1]{\canopy{\callout{[\Canopy onward]\,\,}{Non-normative note:}{#1}}}
 \newcommand{\canopyonwardpnote}[1]{\canopy{\callout{[\Canopy onward]\,\,}{Note:}{#1}}}
 \newcommand{\precanopypnote}[1]{\callout{\notbeforecanopy{\canopy{[Pre-\Canopy\!]\,\,}}}{Note:}{#1}}
@ -2129,10 +2156,15 @@ at launch, and after each of the upgrades codenamed \Overwinter, \Sapling, and
 at launch, and after each of the upgrades codenamed \Overwinter, \Sapling, \Blossom,
 and \Heartwood. It is a work in progress. Protocol differences from \Zerocash and
 \Bitcoin are also explained.}}
-\canopy{\noindent This specification defines the \Zcash consensus protocol
+\notorchard{\canopy{\noindent This specification defines the \Zcash consensus protocol
 at launch, and after each of the upgrades codenamed \Overwinter, \Sapling, \Blossom,
 \Heartwood, and \Canopy. It is a work in progress. Protocol differences from \Zerocash and
-\Bitcoin are also explained.}
+\Bitcoin are also explained.}}
+\orchard{\noindent This draft specification defines the \Zcash consensus protocol
+at launch; after each of the upgrades codenamed \Overwinter, \Sapling, \Blossom,
+\Heartwood, and \Canopy; and proposed changes for \Orchard. It is a work in progress.
+Protocol differences from \Zerocash and \Bitcoin are also explained.}
+

 \sprout{\vspace{1ex}}\notsprout{\vspace{2.5ex}}
 \noindent \textbf{Keywords:}~ \StrSubstitute[0]{\keywords}{,}{, }.
@ -2189,6 +2221,11 @@ are highlighted in \heartwood{\heartwoodcolorname}.}
 \notbeforecanopy{Changes specific to the \Canopy upgrade following \Heartwood
 are highlighted in \canopy{\canopycolorname}.}

+\notbeforeorchard{Changes specific to the \Orchard proposal following \Canopy
+are highlighted in \orchard{\orchardcolorname}.
+
+\pnote{\Orchard is a feature proposal, not a network upgrade in itself.}}
+
 All of these are also changes from \Zerocash.
 The name \Sprout is used for the \Zcash protocol prior to \Sapling
 (both before and after \Overwinter), and in particular its shielded protocol.
@ -4845,6 +4882,10 @@ for \Sapling, but using the \Heartwood{} \consensusBranchID \hexint{F5B9230B} as
 for \Sapling, but using the \Canopy{} \consensusBranchID \hexint{E9FF75A6} as defined in
 \cite{ZIP-251}.}

+\orchardonward{The \sighashAlgorithm used after activation of the network upgrade that
+includes \Orchard, for both version 4 and version 5 \transactions, is defined in \cite{ZIP-244}.
+It will use a new \consensusBranchID \hexint{TODO}.}
+

 \lsubsection{Non-malleability\pSproutOrNothingText}{sproutnonmalleability}

@ -8954,6 +8995,9 @@ A fifth upgrade, called \defining{\Canopy}, activated on \Mainnet on 18~November
 at \blockHeight $1046400$ (coinciding with the first \blockSubsidy \halving)
 \cite{Zcash-Canopy} \cite{ZIP-251}.

+This draft specification describes a set of changes codenamed \Orchard, which are
+proposed to activate in a future \networkUpgrade.
+
 This section summarizes the strategy for upgrading from \Sprout to subsequent versions
 of the protocol (\Overwinter, \Sapling, \Blossom, \Heartwood, and \Canopy), and for
 future upgrades.
@ -8975,6 +9019,12 @@ future upgrades.
 \canopy{The specifications of the \Canopy upgrade are described in this document,
 \cite{ZIP-251}, \cite{ZIP-207}, \cite{ZIP-211}, \cite{ZIP-212}, \cite{ZIP-214}, and \cite{ZIP-215}.}

+\orchard{The specifications of the \Orchard proposal will be described in this document
+and \cite{ZIP-224}. For convenience we will also include the Transparent Zcash Extensions
+proposal \cite{ZIP-222}, and related changes from \cite{ZIP-244} and \cite{ZIP-245},
+in this document, as though they activate at the same time as \Orchard. It is not guaranteed
+that these will in fact all activate in the same upgrade.}
+
 \vspace{1ex}
 \introlist
 Each \networkUpgrade is introduced as a
@ -10879,6 +10929,7 @@ Peter Newell's illustration of the Jubjub bird, from \cite{Carroll1902}.

 \historyentry{2020.1.16}{}
 \begin{itemize}
+    \item Add macros and \Makefile support for building the \Orchard draft specification.
    \item Clarify the encoding of \blockHeights for the ``height in coinbase'' rule.
          The description of this rule has also moved from \shortcrossref{blockheader} to
          \crossref{txnencodingandconsensus}.
--- a/protocol/zcash.bib
+++ b/protocol/zcash.bib
@ -1014,6 +1014,24 @@ Last revised February~5, 2018.}
   urldate={2020-03-19}
 }

+@misc{ZIP-222,
+   presort={ZIP-0222},
+   author={Jack Grigg and Kris Nuttycombe},
+   title={Transparent {Z}cash {E}xtensions},
+   howpublished={Zcash Improvement Proposal 222. Created July~1, 2019.},
+   url={https://zips.z.cash/zip-0222},
+   urldate={2020-10-09}
+}
+
+@misc{ZIP-224,
+   presort={ZIP-0224},
+   author={Daira Hopwood and Jack Grigg and Sean Bowe and Kris Nuttycombe and Ying Tong Lai},
+   title={Orchard Shielded Protocol},
+   howpublished={Zcash Improvement Proposal 224. Reserved.},
+   url={https://zips.z.cash/zip-0224},
+   urldate={2021-01-10}
+}
+
@misc{ZIP-243,
   presort={ZIP-0243},
   author={Jack Grigg and Daira Hopwood},
@ -1023,6 +1041,24 @@ Last revised February~5, 2018.}
   urldate={2019-08-28}
 }

+@misc{ZIP-244,
+   presort={ZIP-0244},
+   author={Kris Nuttycombe},
+   title={Transaction Signature Validation for Transparent {Z}cash Extensions},
+   howpublished={Zcash Improvement Proposal 244. Reserved.},
+   url={https://zips.z.cash/zip-0244},
+   urldate={2021-01-10}
+}
+
+@misc{ZIP-245,
+   presort={ZIP-0245},
+   author={Daira Hopwood and Kris Nuttycombe},
+   title={Transaction Non-Malleability},
+   howpublished={Zcash Improvement Proposal 245. Reserved.},
+   url={https://zips.z.cash/zip-0245},
+   urldate={2021-01-10}
+}
+
@misc{ZIP-250,
   presort={ZIP-0250},
   author={Daira Hopwood},
@ -1041,6 +1077,15 @@ Last revised February~5, 2018.}
   urldate={2020-03-24}
 }

+@misc{ZIP-252,
+   presort={ZIP-0252},
+   author={Daira Hopwood},
+   title={Deployment of the {NU5} Network Upgrade},
+   howpublished={Zcash Improvement Proposal 252. Reserved.},
+   url={https://zips.z.cash/zip-0252},
+   urldate={2021-01-10}
+}
+
@misc{ZIP-302,
   presort={ZIP-0302},
   author={Jay Graber and Jack Grigg},