From 69562802cf192f2edbd3d03d3154aee2b4313208 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 20 Mar 2020 15:05:31 +0000 Subject: [PATCH] Protocol spec: add macro and Makefile support for NU4. Signed-off-by: Daira Hopwood --- protocol/Makefile | 31 +++++++++++++++-- protocol/protocol.tex | 79 +++++++++++++++++++++++++++++++++---------- 2 files changed, 91 insertions(+), 19 deletions(-) diff --git a/protocol/Makefile b/protocol/Makefile index cc407d12..506684c6 100644 --- a/protocol/Makefile +++ b/protocol/Makefile @@ -18,10 +18,10 @@ NOCRUFT?=|awk '{gsub(/[({<][/][^ ]* ?/,"")}1' |sed '/name{index:.*} has been ref .PHONY: all-specs all all-specs: Makefile.uptodate - $(MAKE) heartwood.pdf blossom.pdf sapling.pdf sprout.pdf + $(MAKE) nufour.pdf heartwood.pdf blossom.pdf sapling.pdf sprout.pdf all: Makefile.uptodate - $(MAKE) heartwood blossom sapling sprout + $(MAKE) nufour heartwood blossom sapling sprout Makefile.uptodate: Makefile $(MAKE) clean @@ -39,6 +39,9 @@ blossom.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_saplin heartwood.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png $(MAKE) heartwood +nufour.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png + $(MAKE) nufour + .PHONY: auxsprout auxsprout: printf '\\renewcommand{\\docversion}{Version %s [\\SproutSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver @@ -88,6 +91,18 @@ heartwood: mv -f aux/heartwood.pdf . cp -f heartwood.pdf protocol.pdf +.PHONY: auxnufour +auxnufour: + printf '\\toggletrue{isnufour}\n\\renewcommand{\\docversion}{Version %s [\\NufourSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver + mkdir -p aux + rm -f aux/nufour.* + $(LATEXMK) -jobname=nufour -auxdir=aux -outdir=aux $(EXTRAOPT) protocol $(NOCRUFT) + +.PHONY: nufour +nufour: + $(MAKE) auxnufour + mv -f aux/nufour.pdf . + .PHONY: nolatexmk-sprout nolatexmk-sprout: printf '\\renewcommand{\\docversion}{Version %s [\\SproutSpec]}' "$$(git describe --tags --abbrev=6)" |tee protocol.ver @@ -137,6 +152,18 @@ nolatexmk-heartwood: sh mymakeindex.sh -o heartwood.ind heartwood.idx $(LATEX) -jobname=heartwood protocol.tex || { touch incremental_merkle.png; exit 1; } +.PHONY: nolatexmk-nufour +nolatexmk-nufour: + printf '\\toggletrue{isnufour}\n\\renewcommand{\\docversion}{Version %s [\\NufourSpec]}' "$$(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 nufour.aux nufour.bbl nufour.blg nufour.brf nufour.bcf + $(LATEX) -jobname=nufour protocol.tex || { touch incremental_merkle.png; exit 1; } + biber nufour + $(LATEX) -jobname=nufour protocol.tex || { touch incremental_merkle.png; exit 1; } + $(LATEX) -jobname=nufour protocol.tex || { touch incremental_merkle.png; exit 1; } + sh mymakeindex.sh -o nufour.ind nufour.idx + $(LATEX) -jobname=nufour protocol.tex || { touch incremental_merkle.png; exit 1; } + .PHONY: clean clean: rm -f aux/* html/* protocol.ver protocol.pdf diff --git a/protocol/protocol.tex b/protocol/protocol.tex index 9f5eff23..0926103f 100644 --- a/protocol/protocol.tex +++ b/protocol/protocol.tex @@ -484,12 +484,15 @@ \newcommand{\SaplingSpec}{Overwinter+Sapling} \newcommand{\BlossomSpec}{Overwinter+Sapling+Blossom} \newcommand{\HeartwoodSpec}{Overwinter+Sapling+Blossom+Heartwood} +\newcommand{\NufourSpec}{Overwinter+Sapling+Blossom+Heartwood+NU4} \newtoggle{issapling} \togglefalse{issapling} \newtoggle{isblossom} \togglefalse{isblossom} \newtoggle{isheartwood} \togglefalse{isheartwood} +\newtoggle{isnufour} +\togglefalse{isnufour} \InputIfFileExists{protocol.ver}{}{} \newcommand{\doctitle}{Zcash Protocol Specification} @@ -511,15 +514,37 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg \newcommand{\setwarning}{\color{\warningcolor}} \newcommand{\warningcolor}{BrickRed} \newcommand{\changedcolor}{magenta} +\newcommand{\changedcolorname}{\changedcolor} \newcommand{\setchanged}{\color{\changedcolor}} \newcommand{\changed}[1]{\texorpdfstring{{\setchanged{#1}}}{#1}} \newcommand{\saplingcolor}{green} +\newcommand{\saplingcolorname}{\saplingcolor} \newcommand{\overwintercolor}{blue} +\newcommand{\overwintercolorname}{\overwintercolor} \newcommand{\blossomcolor}{red} +\newcommand{\blossomcolorname}{\blossomcolor} \newcommand{\heartwoodcolor}{orange} +\newcommand{\heartwoodcolorname}{orange} +\newcommand{\nufourcolor}{red!50!blue!85} +\newcommand{\nufourcolorname}{purple} \newcommand{\labelcolor}{yellow!20} +\iftoggle{isnufour}{ + \providecommand{\baseurl}{https://zips.z.cash/protocol/nufour.pdf} + \toggletrue{isheartwood} + \newcommand{\setnufour}{\color{\nufourcolor}} + \newcommand{\nufour}[1]{\texorpdfstring{{\setnufour{#1}}}{#1}} + \newcommand{\notnufour}[1]{} + \newcommand{\notbeforenufour}[1]{#1} +} { + \newcommand{\setnufour}{} + \newcommand{\nufour}[1]{} + \newcommand{\notnufour}[1]{#1} + \newcommand{\notbeforenufour}[1]{} +} + \iftoggle{isheartwood}{ + \providecommand{\baseurl}{https://zips.z.cash/protocol/protocol.pdf} \toggletrue{isblossom} \newcommand{\setheartwood}{\color{\heartwoodcolor}} \newcommand{\heartwood}[1]{\texorpdfstring{{\setheartwood{#1}}}{#1}} @@ -533,29 +558,21 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg } \iftoggle{isblossom}{ + \providecommand{\baseurl}{https://zips.z.cash/protocol/blossom.pdf} \toggletrue{issapling} \newcommand{\setblossom}{\color{\blossomcolor}} \newcommand{\blossom}[1]{\texorpdfstring{{\setblossom{#1}}}{#1}} \newcommand{\notblossom}[1]{} \newcommand{\notbeforeblossom}[1]{#1} - \iftoggle{isheartwood}{ - \newcommand{\baseurl}{https://zips.z.cash/protocol/heartwood.pdf} - } { - \newcommand{\baseurl}{https://zips.z.cash/protocol/protocol.pdf} - } } { \newcommand{\setblossom}{} \newcommand{\blossom}[1]{} \newcommand{\notblossom}[1]{#1} \newcommand{\notbeforeblossom}[1]{} - \iftoggle{issapling}{ - \newcommand{\baseurl}{https://zips.z.cash/protocol/sapling.pdf} - } { - \newcommand{\baseurl}{https://zips.z.cash/protocol/sprout.pdf} - } } \iftoggle{issapling}{ + \providecommand{\baseurl}{https://zips.z.cash/protocol/sapling.pdf} \newcommand{\sprout}[1]{} \newcommand{\notsprout}[1]{#1} \newcommand{\setsapling}{\color{\saplingcolor}} @@ -564,6 +581,7 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg \newcommand{\overwinter}[1]{\texorpdfstring{{\setoverwinter{#1}}}{#1}} \newcommand{\optSprout}[1]{{#1}^\mathsf{Sprout}} } { + \providecommand{\baseurl}{https://zips.z.cash/protocol/sprout.pdf} \newcommand{\sprout}[1]{#1} \newcommand{\notsprout}[1]{} \newcommand{\setsapling}{} @@ -642,6 +660,8 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg \newcommand{\BlossomText}{\textbf{Blossom}} \newcommand{\Heartwood}{\termbf{Heartwood}} \newcommand{\HeartwoodText}{\textbf{Heartwood}} +\newcommand{\Nufour}{\termbf{NU4}} +\newcommand{\NufourText}{\textbf{NU4}} \newcommand{\Bitcoin}{\termbf{Bitcoin}} \newcommand{\BitcoinText}{\textbf{Bitcoin}} \newcommand{\CryptoNote}{\termbf{CryptoNote}} @@ -1993,6 +2013,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{\prenufouritem}[1]{\item \prenufour{#1}} +\newcommand{\nufouronwarditem}[1]{\nufour{\item {[\Nufour onward]}\, {#1}}} \newcommand{\preheartwooditem}[1]{\item \preheartwood{#1}} \newcommand{\heartwoodonwarditem}[1]{\heartwood{\item {[\Heartwood onward]}\, {#1}}} \newcommand{\preblossomitem}[1]{\item \preblossom{#1}} @@ -2004,6 +2026,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{\prenufour}[1]{\notbeforenufour{\nufour{[Pre-\Nufour\!]\,}} {#1}} +\newcommand{\nufouronward}[1]{\nufour{[\Nufour onward]\, {#1}}} \newcommand{\preheartwood}[1]{\notbeforeheartwood{[Pre-\Heartwood\!]\,} {#1}} \newcommand{\heartwoodonward}[1]{\heartwood{[\Heartwood onward]\, {#1}}} \newcommand{\preblossom}[1]{\notbeforeblossom{[Pre-\Blossom\!]\,} {#1}} @@ -2023,6 +2047,7 @@ 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{\prenufourpnote}[1]{\callout{\notbeforenufour{\nufour{[Pre-\Nufour\!]\,\,}}}{Note:}{#1}} \newcommand{\preheartwoodpnote}[1]{\callout{\notsprout{[Pre-\Heartwood\!]\,\,}}{Note:}{#1}} \newcommand{\presaplingpnote}[1]{\callout{\notsprout{[Pre-\Sapling\!]\,\,}}{Note:}{#1}} \newcommand{\preoverwinterpnote}[1]{\callout{\notsprout{[Pre-\Overwinter\!]\,\,}}{Note:}{#1}} @@ -2075,9 +2100,17 @@ consensus protocol.} at launch; after the upgrade codenamed \Overwinter; and after the subsequent upgrade codenamed \Sapling. It is a work in progress. Protocol differences from \Zerocash and \Bitcoin are also explained.}} -\blossom{\noindent This specification defines the \Zcash consensus protocol +\notheartwood{\blossom{\noindent This specification defines the \Zcash consensus protocol at launch, and after each of the upgrades codenamed \Overwinter, \Sapling, and \Blossom. It is a work in progress. Protocol differences from \Zerocash and +\Bitcoin are also explained.}} +\notnufour{\heartwood{\noindent This specification defines the \Zcash consensus protocol +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.}} +\nufour{\noindent This specification defines the \Zcash consensus protocol +at launch, and after each of the upgrades codenamed \Overwinter, \Sapling, \Blossom, +\Heartwood, and \Nufour. It is a work in progress. Protocol differences from \Zerocash and \Bitcoin are also explained.} \sprout{\vspace{1ex}}\notsprout{\vspace{2.5ex}} @@ -2118,15 +2151,23 @@ transparent payment scheme used by \defining{\Bitcoin \cite{Nakamoto2008}} with non-interactive arguments of knowledge (\zkSNARKs). Changes from the original \Zerocash are explained in \crossref{differences}, -and highlighted in \changed{\changedcolor} throughout the document. +and highlighted in \changed{\changedcolorname} throughout the document. + \notsprout{Changes specific to the \Overwinter upgrade -are highlighted in \overwinter{\overwintercolor}. +are highlighted in \overwinter{\overwintercolorname}. + Changes specific to the \Sapling upgrade following \Overwinter -are highlighted in \sapling{\saplingcolor}. +are highlighted in \sapling{\saplingcolorname}. + \notbeforeblossom{Changes specific to the \Blossom upgrade following \Sapling -are highlighted in \blossom{\blossomcolor}.} +are highlighted in \blossom{\blossomcolorname}.} + \notbeforeheartwood{Changes specific to the \Heartwood upgrade following \Blossom -are highlighted in \heartwood{\heartwoodcolor}.} +are highlighted in \heartwood{\heartwoodcolorname}.} + +\notbeforenufour{Changes specific to the \Nufour upgrade following \Heartwood +are highlighted in \nufour{\nufourcolorname}.} + 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). @@ -8540,13 +8581,16 @@ A third upgrade, called \Blossom, activated on the production network on 11 Dece at block height $653600$ \cite{Zcash-Blossom}. This section summarizes the strategy for upgrading from \Sprout to \Overwinter then \Sapling -then \Blossom, and for future upgrades. +then \Blossom then \Heartwood\notbeforenufour{ then \Nufour}, and for future upgrades. \defining{The \networkUpgrade mechanism is described in \cite{ZIP-200}.} + \overwinter{The specifications of the \Overwinter upgrade are described in this document, \cite{ZIP-201}, \cite{ZIP-202}, \cite{ZIP-203}, and \cite{ZIP-143}.} + \sapling{The specifications of the \Sapling upgrade are described in this document, \cite{ZIP-205}, and \cite{ZIP-243}.} + \blossom{The specifications of the \Blossom upgrade are described in this document, \cite{ZIP-206}, and \cite{ZIP-208}.} @@ -10266,6 +10310,7 @@ Peter Newell's illustration of the Jubjub bird, from \cite{Carroll1902}. \begin{itemize} \item Remove ``pvc'' \Makefile targets. \item Make the \Heartwood specification the default. + \item Add macros and \Makefile support for building the \Nufour specification. \end{itemize}