From 9bc9823a23a8e9d4ba138b7b35d1689d8cb499e9 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Sun, 10 Jan 2021 23:50:36 +0000 Subject: [PATCH] Add macros and Makefile support for building the Orchard draft specification. Signed-off-by: Daira Hopwood --- protocol/Makefile | 33 +++++++++++++++++++++++--- protocol/protocol.tex | 55 +++++++++++++++++++++++++++++++++++++++++-- protocol/zcash.bib | 45 +++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+), 5 deletions(-) diff --git a/protocol/Makefile b/protocol/Makefile index 0eae9729..52e715ce 100644 --- 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 diff --git a/protocol/protocol.tex b/protocol/protocol.tex index 73ceef8c..31efb718 100644 --- 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}. diff --git a/protocol/zcash.bib b/protocol/zcash.bib index 1ba47795..e5e7390f 100644 --- 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},