From b2f033f84d89bf2d8c642355fe10de1afa33cc14 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Mon, 13 Jul 2020 18:41:50 +0100 Subject: [PATCH] Add spec changes for ZIPs 207 and 214. Signed-off-by: Daira Hopwood --- protocol/protocol.tex | 190 +++++++++++++++++++++++++++++++++++++----- zip-0214.html | 6 +- zip-0214.rst | 14 ++-- 3 files changed, 178 insertions(+), 32 deletions(-) diff --git a/protocol/protocol.tex b/protocol/protocol.tex index cea70cbe..b9a13f53 100644 --- a/protocol/protocol.tex +++ b/protocol/protocol.tex @@ -1475,6 +1475,17 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg \newcommand{\BlockSubsidy}{\mathsf{BlockSubsidy}} \newcommand{\MinerSubsidy}{\mathsf{MinerSubsidy}} \newcommand{\FoundersReward}{\mathsf{FoundersReward}} +\newcommand{\FundingStreams}{\mathsf{FundingStreams}} +\newcommand{\fs}{\mathsf{fs}} +\newcommand{\fsNumerator}{\fs\mathsf{.Numerator}} +\newcommand{\fsDenominator}{\fs\mathsf{.Denominator}} +\newcommand{\fsStartHeight}{\fs\mathsf{.StartHeight}} +\newcommand{\fsEndHeight}{\fs\mathsf{.EndHeight}} +\newcommand{\fsValue}{\fs\mathsf{.Value}} +\newcommand{\fsAddressList}{\fs\mathsf{.AddressList}} +\newcommand{\fsAddressIndex}{\fs\mathsf{.AddressIndex}} +\newcommand{\fsNumAddresses}{\fs\mathsf{.NumAddresses}} +\newcommand{\fsRedeemScriptHash}{\fs\mathsf{.RedeemScriptHash}} \newcommand{\SlowStartInterval}{\mathsf{SlowStartInterval}} \newcommand{\SlowStartShift}{\mathsf{SlowStartShift}} \newcommand{\SlowStartRate}{\mathsf{SlowStartRate}} @@ -1484,14 +1495,18 @@ electronic commerce and payment, financial privacy, proof of work, zero knowledg \newcommand{\NumFounderAddresses}{\mathsf{NumFounderAddresses}} \newcommand{\FounderAddressChangeInterval}{\mathsf{FounderAddressChangeInterval}} \newcommand{\FoundersFraction}{\mathsf{FoundersFraction}} +\newcommand{\FundingStreamAddressChangeInterval}{\mathsf{FundingStreamAddressChangeInterval}} +\newcommand{\FundingStreamAddressPeriod}{\mathsf{FundingStreamAddressPeriod}} \newcommand{\BlockHeight}{\mathsf{height}} \newcommand{\FounderAddressAdjustedHeight}{\mathsf{FounderAddressAdjustedHeight}} \newcommand{\FoundersRewardLastBlockHeight}{\mathsf{FoundersRewardLastBlockHeight}} \newcommand{\Halving}{\mathsf{Halving}} +\newcommand{\HalvingNum}{\mathsf{halving}} +\newcommand{\HeightForHalving}{\mathsf{HeightForHalving}} \newcommand{\FounderAddress}{\mathsf{FounderAddress}} \newcommand{\FounderAddressList}{\mathsf{FounderAddressList}} \newcommand{\FounderAddressIndex}{\mathsf{FounderAddressIndex}} -\newcommand{\RedeemScriptHash}{\mathsf{RedeemScriptHash}} +\newcommand{\FounderRedeemScriptHash}{\mathsf{FounderRedeemScriptHash}} \newcommand{\blockSubsidy}{\term{block subsidy}} \newcommand{\minerSubsidy}{\term{miner subsidy}} @@ -3116,24 +3131,34 @@ considered disjoint, even if they have the same bit pattern.} } -\lsubsection{Block Subsidy and Founders' Reward}{subsidyconcepts} +\lsubsection{Block Subsidy\canopy{, Funding Streams,} and Founders' Reward}{subsidyconcepts} Like \Bitcoin, \Zcash creates currency when \blocks are mined. The value created on -mining a \block is called the \defining{\blockSubsidy}. It is composed of a \defining{\minerSubsidy} and a -\defining{\foundersReward}. As in \Bitcoin, the miner of a \block also receives \defining{\transactionFees}. +mining a \block is called the \defining{\blockSubsidy}. -The calculations of the \blockSubsidy, \minerSubsidy, and \foundersReward depend on -the \blockHeight, as defined in \crossref{blockchain}. +\precanopy{The \blockSubsidy is composed of a \defining{\minerSubsidy} and a \defining{\foundersReward}.} -These calculations are described in \crossref{subsidies}. +\canopyonward{The \blockSubsidy is composed of a \minerSubsidy and a series of \defining{\fundingStreams}.} + +As in \Bitcoin, the miner of a \block also receives \defining{\transactionFees}. + +The calculations of the \blockSubsidy, \minerSubsidy, \notcanopy{and }\foundersReward\canopy{, and \fundingStreams} +depend on the \blockHeight, as defined in \crossref{blockchain}. + +The calculations are described in \crossref{subsidies}. \lsubsection{Coinbase Transactions}{coinbasetransactions} The first (and only the first) \transaction in a block is a \defining{\coinbaseTransaction}, which collects and spends any \minerSubsidy and \transactionFees paid by \transactions -included in this \block. The \coinbaseTransaction{} \MUST also pay the \foundersReward -as described in \crossref{foundersreward}. +included in this \block. + +\precanopy{The \coinbaseTransaction{} \MUST also pay the \foundersReward as described in \\ +\crossref{foundersreward}.} + +\canopyonward{The \coinbaseTransaction \MUST also pay the \fundingStreams as described in \\ +\crossref{fundingstreams}.} \lsubsection{Mainnet and Testnet}{networks} @@ -5735,8 +5760,8 @@ contain the \transaction in which a \note was output. \vspace{-2ex} \nnote{ Normally only \noteCiphertexts of \transactions in \blocks need to be decrypted. -A client \MAY attempt to decrypt a \noteCiphertext of a \transaction in the \mempool, -using the next \blockHeight for $\BlockHeight$. However, in that case it \MUSTNOT assume that +A client \MAY attempt to decrypt a \noteCiphertext of a \transaction in the \mempool\canopy{, +using the next \blockHeight for $\BlockHeight$}. However, in that case it \MUSTNOT assume that the \transaction will be mined and \MUST treat the decrypted information as provisional. } %nnote } %sapling @@ -9761,9 +9786,9 @@ in its \blockHeader is defined as $\floor{\hfrac{2^{256}}{\ToTarget(\nBits) + 1} \introlist -\lsubsection{Calculation of Block Subsidy and Founders' Reward}{subsidies} +\lsubsection{Calculation of Block Subsidy\canopy{, Funding Streams,} and Founders' Reward}{subsidies} -\crossref{subsidyconcepts} defines the \defining{\blockSubsidy, \minerSubsidy, and \foundersReward}. +\crossref{subsidyconcepts} defines the \blockSubsidy, \minerSubsidy,\notcanopy{ and} \foundersReward\canopy{, and \fundingStreams}. Their amounts in \zatoshi are calculated from the \blockHeight using the formulae below. @@ -9771,6 +9796,8 @@ Let\notbeforeblossom{ the constants} $\SlowStartInterval$,\, $\PreBlossomHalving \blossom{$\PostBlossomHalvingInterval$,\, $\BlossomActivationHeight$,\, }$\MaxBlockSubsidy$, and $\FoundersFraction$ be as defined in \crossref{constants}. +\canopy{Let $\FundingStreams$ be as specified in \crossref{zip214fundingstreams}.} + \vspace{1ex} \begin{formulae} \item $\SlowStartShift \typecolon \Nat := \hfrac{\SlowStartInterval}{2}$ @@ -9784,7 +9811,7 @@ and $\FoundersFraction$ be as defined in \crossref{constants}. \vspace{0.5ex} \item $\BlockSubsidy(\BlockHeight \typecolon \Nat) := \begin{cases} \SlowStartRate \mult \BlockHeight,&\caseif \BlockHeight < \hfrac{\SlowStartInterval}{2} \\[1.4ex] - \SlowStartRate \mult (\BlockHeight + 1),&\caseif \hfrac{\SlowStartInterval}{2} \leq \BlockHeight \\[0.4ex] + \SlowStartRate \mult (\BlockHeight + 1),&\caseif \hfrac{\SlowStartInterval}{2} \leq \BlockHeight \\ &\text{ and } \BlockHeight < \SlowStartInterval \\[1.4ex] \floor{\hfrac{\MaxBlockSubsidy}{2^{\Halving(\BlockHeight)}}}\!\!,&\notblossom{\caseotherwise}\notbeforeblossom{\caseif \SlowStartInterval \leq \BlockHeight} \\[-1ex] \notbeforeblossom { @@ -9798,7 +9825,21 @@ and $\FoundersFraction$ be as defined in \crossref{constants}. 0,&\caseotherwise \end{cases}$ - \item $\MinerSubsidy(\BlockHeight \typecolon \Nat) := \BlockSubsidy(\BlockHeight) - \FoundersReward(\BlockHeight)$. +\canopy { + \vspace{0.5ex} + \item for $\fs \in \FundingStreams$,\, $\fsValue(\BlockHeight) :=$ + \vspace{-0.5ex} + \item \tab $\begin{cases} + 0,&\caseif \BlockHeight < \CanopyActivationHeight \\ + \floor{\BlockSubsidy(\BlockHeight) \mult + \hfrac{\fsNumerator}{\fsDenominator}},&\caseif \fsStartHeight \leq \BlockHeight + \text{ and } \BlockHeight < \fsEndHeight \\ + 0,&\caseotherwise + \end{cases}$ +} %canopy + + \item $\MinerSubsidy(\BlockHeight) := \BlockSubsidy(\BlockHeight) - \FoundersReward(\BlockHeight) + \canopy{\,- \ssum{\fs\, \in\, \FundingStreams}{} \fsValue(\BlockHeight)}$. \end{formulae} \introsection @@ -9907,22 +9948,22 @@ Define: \blossom{\maximum\Of{\setof{\BlockHeight \typecolon \Nat \suchthat \Halving(\BlockHeight) < 1}}}$\,. \end{formulae} -Let $\RedeemScriptHash(\BlockHeight \typecolon \Nat)$ be the standard redeem script hash, as defined in +Let $\FounderRedeemScriptHash(\BlockHeight \typecolon \Nat)$ be the standard redeem script hash, as specified in \cite{Bitcoin-Multisig}, for the P2SH multisig address with Base58Check form given by $\FounderAddressList_{\,\FounderAddressIndex(\BlockHeight)}$. \vspace{-1ex} -\consensusrule{ -A \coinbaseTransaction for \blockHeight $\BlockHeight \in \range{1}{\FoundersRewardLastBlockHeight}$ +\consensusrule{\precanopy{ +A \coinbaseTransaction at $\BlockHeight \in \range{1}{\FoundersRewardLastBlockHeight}$ \MUST include at least one output that pays exactly $\FoundersReward(\BlockHeight)$ \zatoshi -with a standard P2SH script of the form \ScriptOP{HASH160} \;$\RedeemScriptHash(\BlockHeight)$\; \ScriptOP{EQUAL} +with a standard P2SH script of the form \ScriptOP{HASH160} \;$\FounderRedeemScriptHash(\BlockHeight)$\; \ScriptOP{EQUAL} as its $\scriptPubKey$. -} +}} \vspace{1ex} \begin{pnotes} \item No \foundersReward is required to be paid for $\BlockHeight > \FoundersRewardLastBlockHeight$ - (i.e.\ after the first halving), or for $\BlockHeight = 0$ (i.e.\ the \genesisBlock). + (i.e.\ after the first halving), or for $\BlockHeight = 0$ (i.e.\ the \genesisBlock)\canopy{, or after \Canopy activation}. \item The \foundersReward addresses are not treated specially in any other way, and there can be other outputs to them, in \coinbaseTransactions or otherwise. In particular, it is valid for a \coinbaseTransaction with @@ -9942,6 +9983,108 @@ as its $\scriptPubKey$. \end{nnotes} } %blossom +\canopy{ +\lsubsection{Payment of Funding Streams}{fundingstreams} + +The \defining{\fundingStreams} are paid by outputs in the \coinbaseTransaction, to one of a pre-defined +set of addresses, depending on the \blockHeight. + +A \fundingStream $\fs$ is defined by a \blockSubsidy fraction (represented as a numerator and +denominator), a start \blockHeight (inclusive), an end \blockHeight (exclusive), and a sequence +of address representations: + +\begin{formulae} + \item $\fsNumerator \typecolon \PosInt$ + \item $\fsDenominator \typecolon \PosInt$ + \item $\fsStartHeight \typecolon \Nat$ + \item $\fsEndHeight \typecolon \Nat$ + \vspace{-1ex} + \item $\fsAddressList \typecolon \typeexp{\byteseqs}{\PosInt}$. +\end{formulae} + +Define: + +\begin{formulae} + \item $\HeightForHalving(\HalvingNum \typecolon \Nat) := + \minimum\Of{\setof{\BlockHeight \typecolon \Nat \suchthat \Halving(\BlockHeight) = \HalvingNum}}$ + \item $\FundingStreamAddressChangeInterval := \PostBlossomHalvingInterval / 48$ + \item $\FundingStreamAddressPeriod(\BlockHeight) := + \floor{\hfrac{\BlockHeight - (\HeightForHalving(1) - \PostBlossomHalvingInterval)}{\FundingStreamAddressChangeInterval}}$. +\end{formulae} + +For each \fundingStream $\fs$, define: + +\begin{formulae} + \item $\fsAddressIndex(\BlockHeight) := 1 + \FundingStreamAddressPeriod(\BlockHeight) - \FundingStreamAddressPeriod(\fsStartHeight)$ + \item $\fsNumAddresses := \fsAddressIndex(\fsEndHeight - 1)$. +\end{formulae} + +$\fsAddressList$ \MUST be of length $\fsNumAddresses$. Each element of $\fsAddressList$ +\MUST represent either a \transparent P2SH address as specified in \crossref{transparentaddrencoding}, +or a \Sapling \paymentAddress as specified in \crossref{saplingpaymentaddrencoding}. + +Recall from \crossref{subsidies} the definition of $\fsValue$. A \fundingStream $\fs$ is +``active'' at \blockHeight $\BlockHeight$ when $\fsValue(\BlockHeight) > 0$. + +\consensusrule{ +\canopyonward{ +The \coinbaseTransaction at \blockHeight $\BlockHeight$ \MUST contain at least +one output per \fundingStream $\fs$ active at $\BlockHeight$, that pays +$\fsValue(\BlockHeight)$ \zatoshi in the prescribed way to the stream's +recipient address represented by $\fsAddressList_{\fsAddressIndex(\BlockHeight)}$. + +\begin{itemize} + \item The ``prescribed way'' to pay a \transparent P2SH address is to use a standard + P2SH script of the form \ScriptOP{HASH160} \;$\fsRedeemScriptHash(\BlockHeight)$\; \ScriptOP{EQUAL} + as the $\scriptPubKey$. Here $\fsRedeemScriptHash(\BlockHeight)$ is the standard + redeem script hash for the recipient address given by + $\fsAddressList_{\,\fsAddressIndex(\BlockHeight)}$ in Base58Check form. The + standard redeem script hash is specified in \cite{Bitcoin-Multisig} for + P2SH multisig addresses, or \cite{Bitcoin-P2SH} for other P2SH addresses. + \item The ``prescribed way" to pay a \Sapling address is as defined in \cite{ZIP-213}; + that is, following the post-\Heartwood consensus rules specified + for \Sapling outputs of \coinbaseTransactions in \crossref{txnencoding}. +\end{itemize} +} %canopyonward +} %consensusrule + +\begin{pnotes} + \item The \fundingStream addresses are not treated specially in any other way, and + there can be other outputs to them, in \coinbaseTransactions or otherwise. + In particular, it is valid for a \coinbaseTransaction to have + other outputs, possibly to the same address, that do not meet the criterion + in the above consensus rule, as long as at least one output meets it. +\end{pnotes} + +\lsubsubsection{ZIP 214 Funding Streams}{zip214fundingstreams} + +Let $\CanopyActivationHeight$ be as defined in \crossref{constants}. + +\vspace{0.5ex} +\cite{ZIP-214} defines three \fundingStreams: + +\renewcommand{\arraystretch}{1} + +\begin{formulae} +\item \begin{tabular}{|l|c|c|c|c|} +\hline +Stream & Numerator & Denominator & Start height & End height \\\hline +\texttt{FS\_ZIP214\_ECC} & $7$ & $100$ & $\CanopyActivationHeight$ & $2726400$ \\ +\texttt{FS\_ZIP214\_ZF} & $5$ & $100$ & $\CanopyActivationHeight$ & $2726400$ \\ +\texttt{FS\_ZIP214\_MG} & $8$ & $100$ & $\CanopyActivationHeight$ & $2726400$ \\\hline +\end{tabular} +\end{formulae} + +\begin{pnotes} + \item $\CanopyActivationHeight$ is different between \Mainnet and \Testnet. + \item On \Testnet, the \activationHeight of \Canopy will be before the first halving. + Therefore, the consequence of the above rules for \Testnet is that the amount sent to + each recipient \fundingStream address will initially (before \Testnet \blockHeight $1046400$) + be double the corresponding initial amount on \Mainnet. This reduces to the same amount + as on \Mainnet, from \Testnet \blockHeights $1046400$ (inclusive) to $2726400$ (exclusive). +\end{pnotes} +} %canopy + \lsubsection{Changes to the Script System}{scripts} @@ -10631,6 +10774,9 @@ Peter Newell's illustration of the Jubjub bird, from \cite{Carroll1902}. ``the test network'' to \Testnet. This follows the terminology used in ZIPs. \item Update stale references to \Bitcoin documentation. +\canopy{ + \item Add changes for \cite{ZIP-207} and \cite{ZIP-214}. +} \end{itemize} @@ -10910,7 +11056,7 @@ Peter Newell's illustration of the Jubjub bird, from \cite{Carroll1902}. of the \blockChain. This inconsistency was pointed out by NCC Group in their \Blossom specification audit. \blossom{ - \item Revert changes for funding streams from Withdrawn ZIP 207. + \item Revert changes for \fundingStreams from Withdrawn ZIP 207. } %blossom \end{itemize} diff --git a/zip-0214.html b/zip-0214.html index 80900f17..fd5e13d5 100644 --- a/zip-0214.html +++ b/zip-0214.html @@ -59,21 +59,21 @@ Discussions-To: <https://forum.zcashcommunity.com/t/community-sentiment-polli - FS_ECC + FS_ZIP214_ECC 7 100 1046400 2726400 - FS_ZF + FS_ZIP214_ZF 5 100 1046400 2726400 - FS_MG + FS_ZIP214_MG 8 100 1046400 diff --git a/zip-0214.rst b/zip-0214.rst index 69374265..4213828a 100644 --- a/zip-0214.rst +++ b/zip-0214.rst @@ -102,13 +102,13 @@ ZIP 207 [#zip-0207]_ SHALL be activated in Canopy. The following funding streams are defined for Mainnet: - ========== =========== ============= ============== ============ - Stream Numerator Denominator Start height End height - ========== =========== ============= ============== ============ - ``FS_ECC`` 7 100 1046400 2726400 - ``FS_ZF`` 5 100 1046400 2726400 - ``FS_MG`` 8 100 1046400 2726400 - ========== =========== ============= ============== ============ + ================= =========== ============= ============== ============ + Stream Numerator Denominator Start height End height + ================= =========== ============= ============== ============ + ``FS_ZIP214_ECC`` 7 100 1046400 2726400 + ``FS_ZIP214_ZF`` 5 100 1046400 2726400 + ``FS_ZIP214_MG`` 8 100 1046400 2726400 + ================= =========== ============= ============== ============ As specified in [#zip-0207]_, a funding stream is active for a span of blocks that includes the block at its start height, but excludes the block at its end