From c3ce2f5c9728be285773e44df13499f73974d4bf Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Tue, 19 Nov 2024 19:38:11 +0000 Subject: [PATCH 1/8] Dockerfile: ensure `/zips` is treated as a safe directory. Signed-off-by: Daira-Emma Hopwood --- Dockerfile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Dockerfile b/Dockerfile index 48fd6085e..ab2a6036b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,6 +20,8 @@ RUN apt-get install -y \ RUN rm /usr/lib/python3.11/EXTERNALLY-MANAGED RUN pip install rst2html5 +RUN git config --global --add safe.directory /zips + ENV PATH=${PATH}:/root/.local/bin WORKDIR "/zips" From 098f9e865e6f79973507d1e31ee36aa0e021ca47 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Tue, 19 Nov 2024 19:46:08 +0000 Subject: [PATCH 2/8] Dockerfile: install MultiMarkdown-6. Signed-off-by: Daira-Emma Hopwood --- .gitignore | 2 ++ Dockerfile | 7 +++++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index bc00a6a2d..57bbccb2c 100644 --- a/.gitignore +++ b/.gitignore @@ -26,5 +26,7 @@ .zipfilelist.* .draftfilelist.* +MultiMarkdown-6 + protocol/aux/ protocol/protocol.ver diff --git a/Dockerfile b/Dockerfile index ab2a6036b..af77cee29 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,10 +2,10 @@ FROM debian:latest RUN apt-get update RUN apt-get install -y \ - gawk \ perl \ sed \ git \ + cmake \ python3 \ python3-pip \ pandoc \ @@ -18,10 +18,13 @@ RUN apt-get install -y \ texlive-bibtex-extra RUN rm /usr/lib/python3.11/EXTERNALLY-MANAGED -RUN pip install rst2html5 +RUN pip install 'docutils==0.21.2' 'rst2html5==2.0.1' RUN git config --global --add safe.directory /zips +# Use a fork so that we're running pinned code. +RUN git clone -b develop https://github.com/Electric-Coin-Company/MultiMarkdown-6 && cd MultiMarkdown-6 && make release && cd build && make && make install + ENV PATH=${PATH}:/root/.local/bin WORKDIR "/zips" From efa3ec76f94938f015453586c37478a948401e04 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Tue, 19 Nov 2024 20:29:41 +0000 Subject: [PATCH 3/8] Use, and document how to install, MultiMarkdown-6. fixes #961, fixes #893 Signed-off-by: Daira-Emma Hopwood --- Makefile | 4 ++-- protocol/README.rst | 4 ++-- zips/zip-guide-markdown.md | 16 +++++++++++----- zips/zip-guide.rst | 16 +++++++++++----- 4 files changed, 26 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index 7448c3d2a..a887b8087 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ -# Dependencies: see zip-guide.rst and protocol/README.rst +# Dependencies: see zips/zip-guide.rst and protocol/README.rst -MARKDOWN_OPTION?=--pandoc +MARKDOWN_OPTION?=--mmd .PHONY: all-zips all tag-release protocol all-protocol discard all-zips: .Makefile.uptodate diff --git a/protocol/README.rst b/protocol/README.rst index 96535392b..ae2f3c101 100644 --- a/protocol/README.rst +++ b/protocol/README.rst @@ -6,7 +6,7 @@ Build dependencies on Debian-based systems include, at least: .. code:: - apt install python3-pip pandoc perl sed perl \ + apt install python3-pip perl sed cmake \ texlive texlive-science texlive-fonts-extra texlive-bibtex-extra biber latexmk Prior to Bullseye you may also need the ``awk`` and ``texlive-generic-recommended`` @@ -16,7 +16,7 @@ For link checking, you will also need the following Python packages: .. code:: - pip3 install docutils==0.19 rst2html5 certifi PyPDF2 + pip3 install 'docutils==0.21.2' 'rst2html5==2.0.1' certifi PyPDF2 Building diff --git a/zips/zip-guide-markdown.md b/zips/zip-guide-markdown.md index bdf82facc..a5b119647 100644 --- a/zips/zip-guide-markdown.md +++ b/zips/zip-guide-markdown.md @@ -177,11 +177,17 @@ or "SHOULD" conformance requirement is more appropriate. ## Valid markup This is optional before publishing a PR, but to check whether a document is valid -reStructuredText or Markdown, first install `rst2html5` and `pandoc`. E.g. on -Debian-based distros:: - - sudo apt install python3-pip pandoc perl sed - pip3 install docutils==0.19 rst2html5 +reStructuredText or Markdown, first install `docutils` and `rst2html5`, and +build ``MultiMarkdown-6``. E.g. on Debian-based distros:: + + 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 Then, with `draft-myzip.rst` or `draft-myzip.md` in the root directory of a clone of this repo, run:: diff --git a/zips/zip-guide.rst b/zips/zip-guide.rst index ca39e538d..cba38add9 100644 --- a/zips/zip-guide.rst +++ b/zips/zip-guide.rst @@ -186,11 +186,17 @@ Valid markup ------------ This is optional before publishing a PR, but to check whether a document is valid -reStructuredText or Markdown, first install ``rst2html5`` and ``pandoc``. E.g. on -Debian-based distros:: - - sudo apt install python3-pip pandoc perl sed - pip3 install docutils==0.19 rst2html5 +reStructuredText or Markdown, first install ``docutils`` and ``rst2html5``, and +build ``MultiMarkdown-6``. E.g. on Debian-based distros:: + + 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 Then, with ``draft-myzip.rst`` or ``draft-myzip.md`` in the root directory of a clone of this repo, run:: From cf9b8430ed6467de798a288c2e6f0ffc9563e74d Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Sat, 23 Nov 2024 10:24:34 +0000 Subject: [PATCH 4/8] Ensure that Markdown ZIPs also have section bookmarks. Signed-off-by: Daira-Emma Hopwood --- render.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/render.sh b/render.sh index f312aed6d..4fdbf2cbc 100755 --- a/render.sh +++ b/render.sh @@ -86,5 +86,6 @@ cat <( s|\s*.?\s*([^<]*(?:[^<]*[^<]*)?)|
\3 |g' \ +'s|
\s*.?\s*([^<]*(?:[^<]*[^<]*)?)|
\3 |g; + s|([^<]*(?:[^<]*[^<]*)?)|\3 |g;' \ > "${outputfile}" From 668a006cda61bce7489706d51132e82ff2f4f069 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Sun, 24 Nov 2024 11:14:55 +0000 Subject: [PATCH 5/8] CSS: fix rendering of citation links for Markdown. Signed-off-by: Daira-Emma Hopwood --- rendered/css/style.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rendered/css/style.css b/rendered/css/style.css index d3d22b1ec..f1cd9577d 100644 --- a/rendered/css/style.css +++ b/rendered/css/style.css @@ -334,11 +334,11 @@ span.section-heading:hover + span { opacity: 1; } -a.footnote_reference::before, a.footnote-ref::before { +a.footnote_reference::before, a.footnote-ref::before, a.footnote::before { content: "["; } -a.footnote_reference::after, a.footnote-ref::after { +a.footnote_reference::after, a.footnote-ref::after, a.footnote::after { content: "]"; } @@ -369,7 +369,7 @@ a.footnote_reference::after, a.footnote-ref::after { /* }}} rst-specific */ /* {{{ md-specific */ -a.footnote-ref sup { +a.footnote-ref sup, a.footnote sup { vertical-align: baseline; font-size: 100%; } From 4476360d617eb0696d50ae9e9704006bc77b6462 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Sun, 24 Nov 2024 11:15:18 +0000 Subject: [PATCH 6/8] ZIP 231: Fix a typo. Signed-off-by: Daira-Emma Hopwood --- zips/zip-0231.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zips/zip-0231.md b/zips/zip-0231.md index dc41d80a0..cf002832f 100644 --- a/zips/zip-0231.md +++ b/zips/zip-0231.md @@ -103,7 +103,7 @@ while decreasing the amount of data that needs to be stored on-chain overall. - Recipients do not need to be able to receive multiple memos per note. This capability can however be enabled under the existing proposal by "chaining" memos, including the decryption key for another memo within the memo that - is decryptabble by a recipient. + is decryptable by a recipient. # Specification From 757f498c911d24cf8f95be756bfb11397d03232d Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Sun, 24 Nov 2024 11:24:52 +0000 Subject: [PATCH 7/8] $\LaTeX$ works now in Markdown. Signed-off-by: Daira-Emma Hopwood --- zips/zip-guide-markdown.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zips/zip-guide-markdown.md b/zips/zip-guide-markdown.md index a5b119647..e3e5294ef 100644 --- a/zips/zip-guide-markdown.md +++ b/zips/zip-guide-markdown.md @@ -142,12 +142,12 @@ ZIPs are different from RFCs in the following ways: ## Using mathematical notation -Embedded LaTeX, e.g. $x + y$, is allowed and encouraged in ZIPs. The syntax for +Embedded $\LaTeX$, e.g. $x + y$, is allowed and encouraged in ZIPs. The syntax for inline math is "\$latex code\$" in either Markdown or (as a non-standard extension) reStructuredText. This syntax does not work in tables for reStructuredText; in that case use ":math:\`latex code\`" instead. -The rendered HTML will use KaTeX [^katex], which only supports a subset of LaTeX, +The rendered HTML will use KaTeX [^katex], which only supports a subset of $\LaTeX$, so you will need to double-check that the rendering is as intended. In general the conventions in the Zcash protocol specification SHOULD be followed. From 2bbe6521d8b2fd19b797e3e3e7ec4bb62f30ea1f Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Sun, 24 Nov 2024 11:25:10 +0000 Subject: [PATCH 8/8] Re-render HTML. Signed-off-by: Daira-Emma Hopwood --- rendered/zip-0231.html | 1186 +++++++++++++++--------------- rendered/zip-0233.html | 412 ++++++----- rendered/zip-0234.html | 515 ++++++------- rendered/zip-0235.html | 382 +++++----- rendered/zip-0253.html | 223 +++--- rendered/zip-0254.html | 176 +++-- rendered/zip-guide-markdown.html | 478 ++++++------ rendered/zip-guide.html | 12 +- 8 files changed, 1719 insertions(+), 1665 deletions(-) diff --git a/rendered/zip-0231.html b/rendered/zip-0231.html index 208c1eed2..54e094867 100644 --- a/rendered/zip-0231.html +++ b/rendered/zip-0231.html @@ -21,171 +21,171 @@ Category: Consensus / Wallet Created: 2024-04-26 License: MIT -Discussions-To: <https://github.com/zcash/zips/issues/627> -

Terminology

-

The key words “MUST”, “MUST NOT”, “SHOULD”, and “MAY” in this -document are to be interpreted as described in BCP 14 1 -when, and only when, they appear in all capitals.

-

The term “network upgrade” in this document is to be interpreted as -described in ZIP 200. 2

-

The character § is used when referring to sections of the Zcash -Protocol Specification. 3

-

The terms “Mainnet” and “Testnet” are to be interpreted as described -in § 3.12 ‘Mainnet and Testnet’. 4

-

Abstract

-

Currently, the memo sent in a shielded output is limited to at most -512 bytes. This ZIP proposes to allow larger memos, and to enable memo -data to be shared between multiple recipients of a transaction.

-

Motivation

-

In Zcash transaction versions v2 to v5 inclusive, each Sapling or -Orchard shielded output contains a ciphertext comprised of a 52-byte -note plaintext, and a corresponding 512-byte memo field. 5 -Recipients can only decrypt the outputs sent to them, and thus can also -only observe the memo fields included with the outputs they can -decrypt.

-

The shielded transaction protocol hides the sender(s) (that is, the -addresses corresponding to the keys used to spend the input notes) from -all of the recipients. For certain kinds of transactions, it is -desirable to make one or more sender addresses available to one or more -recipients (for example, a reply address). In such circumstances it is -important to authenticate the sender addresses, to give the recipient a -guarantee that the address is controlled by a sender of the transaction; -failure to authenticate this address can enable phishing attacks. These -Authenticated Reply Addresses require zero-knowledge proofs, and for the -Orchard protocol these proofs are too large to fit into a 512-byte memo -field.

-

It is also desirable, for clients with more stringent bandwidth -constraints, to be able to transmit encrypted notes to the client -without including the encrypted memo data. In the current light client -protocol 6, this is done by truncating the note -ciphertext to just the part that encrypts the memo. However, that has -the effect of truncating the authentication tag, and so the resulting -decryption algorithm does not meet standard security notions for an -authenticated encryption scheme. It is a goal of this proposal to +Discussions-To: <https://github.com/zcash/zips/issues/627> + + +

Terminology

+ +

The key words “MUST”, “MUST NOT”, “SHOULD”, and “MAY” in this document are to +be interpreted as described in BCP 14 1 when, and only when, they appear +in all capitals.

+ +

The term “network upgrade” in this document is to be interpreted as described in +ZIP 200. 2

+ +

The character § is used when referring to sections of the Zcash Protocol +Specification. 3

+ +

The terms “Mainnet” and “Testnet” are to be interpreted as described in +§ 3.12 ‘Mainnet and Testnet’. 4

+ +

Abstract

+ +

Currently, the memo sent in a shielded output is limited to at most 512 bytes. +This ZIP proposes to allow larger memos, and to enable memo data to be shared +between multiple recipients of a transaction.

+ +

Motivation

+ +

In Zcash transaction versions v2 to v5 inclusive, each Sapling or Orchard +shielded output contains a ciphertext comprised of a 52-byte note plaintext, +and a corresponding 512-byte memo field. 5 Recipients +can only decrypt the outputs sent to them, and thus can also only observe the +memo fields included with the outputs they can decrypt.

+ +

The shielded transaction protocol hides the sender(s) (that is, the addresses +corresponding to the keys used to spend the input notes) from all of the +recipients. For certain kinds of transactions, it is desirable to make one or +more sender addresses available to one or more recipients (for example, a reply +address). In such circumstances it is important to authenticate the sender +addresses, to give the recipient a guarantee that the address is controlled by +a sender of the transaction; failure to authenticate this address can enable +phishing attacks. These Authenticated Reply Addresses require zero-knowledge +proofs, and for the Orchard protocol these proofs are too large to fit into a +512-byte memo field.

+ +

It is also desirable, for clients with more stringent bandwidth constraints, +to be able to transmit encrypted notes to the client without including the +encrypted memo data. In the current light client protocol 6, this +is done by truncating the note ciphertext to just the part that encrypts the +memo. However, that has the effect of truncating the authentication tag, and +so the resulting decryption algorithm does not meet standard security notions +for an authenticated encryption scheme. It is a goal of this proposal to rectify this, simplifying the security argument.

-

Instead of the memo data, this ZIP proposes that it is possible to -indicate whether a memo is present for the recipient. When using the -light client protocol, a recipient need not download full transaction -information if this indication tells them that they have not received -any memo in the transaction.

-

At present, it is not possible to transmit the same memo data to -multiple transaction recipients without redundantly encoding that data, -and sending memo data greater than 512 bytes requires sending multiple -outputs; the problem is compounded when attempting to send more than 512 -bytes to each recipient. By separating memo data from the decryption -capability for those memos, it admits a greater variety of applications -that utilize memo data, while decreasing the amount of data that needs -to be stored on-chain overall.

-

Requirements

+ +

Instead of the memo data, this ZIP proposes that it is possible to indicate whether +a memo is present for the recipient. When using the light client protocol, a recipient +need not download full transaction information if this indication tells them that they +have not received any memo in the transaction.

+ +

At present, it is not possible to transmit the same memo data to multiple +transaction recipients without redundantly encoding that data, and sending +memo data greater than 512 bytes requires sending multiple outputs; the +problem is compounded when attempting to send more than 512 bytes to each +recipient. By separating memo data from the decryption capability for those +memos, it admits a greater variety of applications that utilize memo data, +while decreasing the amount of data that needs to be stored on-chain overall.

+ +

Requirements

+
    -
  • Recipients can receive memo data that is greater than 512 bytes in -length.
    • -
  • Multiple recipients, across any of the shielded pools, can be given -the capability to view the same memo data.
    • -
  • The exact number and exact lengths of distinct decryptable memos -should not be revealed, even to the transaction recipients, although an -upper bound on the total length of memo data that the observer does not -have the capability to view will be leaked to transaction recipients, -and the overall maximum possible length of memo data will be revealed -on-chain.
    • -
  • A recipient can determine whether or not they have been given the -capability to view any memo solely by decrypting the note -ciphertext.
    • -
  • Memo chunks within a transaction can be individually pruned from -block storage without preventing the transaction from being verified -when transmitting block data to peers.
    • -
  • The ciphertext of the note alone can be decrypted using a scheme -that meets a standard security notion for authenticated encryption, -without more than a small constant overhead in ciphertext size.
    • +
  • Recipients can receive memo data that is greater than 512 bytes in length.
    • +
  • Multiple recipients, across any of the shielded pools, can be given the +capability to view the same memo data.
    • +
  • The exact number and exact lengths of distinct decryptable memos should not +be revealed, even to the transaction recipients, although an upper bound on +the total length of memo data that the observer does not have the capability +to view will be leaked to transaction recipients, and the overall maximum +possible length of memo data will be revealed on-chain.
    • +
  • A recipient can determine whether or not they have been given the capability +to view any memo solely by decrypting the note ciphertext.
    • +
  • Memo chunks within a transaction can be individually pruned from block storage +without preventing the transaction from being verified when transmitting block +data to peers.
    • +
  • The ciphertext of the note alone can be decrypted using a scheme that meets +a standard security notion for authenticated encryption, without more than a +small constant overhead in ciphertext size.
-

Non-requirements

+ +

Non-requirements

+
    -
  • Recipients do not need to be able to receive multiple memos per -note. This capability can however be enabled under the existing proposal -by “chaining” memos, including the decryption key for another memo -within the memo that is decryptabble by a recipient.
    • +
  • Recipients do not need to be able to receive multiple memos per note. This +capability can however be enabled under the existing proposal by “chaining” +memos, including the decryption key for another memo within the memo that +is decryptable by a recipient.
-

Specification

-

Since this proposal is defined only for v6 and later transactions, it -is not necessary to consider Sprout JoinSplit outputs. The following -sections apply to both Sapling and Orchard outputs.

-

Memo bundle

-

A memo bundle consists of a sequence of 256-byte memo chunks, each -individually encrypted. These memo chunks represent zero or more -encrypted memos.

-

Each transaction may contain a single memo bundle, and a memo bundle -may contain at most memo_chunk_limit memo chunks. This -limits the total amount of memo data that can be conveyed within a -single transaction to memo_chunk_limit * 256 bytes.

-

memo_chunk_limit is a parameter to this specification, -to be decided upon by the community. The authors of this ZIP propose a -maximum of 64 chunks, resulting in a maximum total memo data length of -16 KiB.

-

Memo bundles are encoded in transactions in a prunable manner: each -memo chunk can be replaced by its representative digest.

-

Memo encryption

-

During transaction construction, each output with memo data is -assigned a 32-byte memo key \(\mathsf{K^{memo}}\). These keys SHOULD be -generated randomly, and MUST NOT be used to encrypt more than one memo -within a single transaction. If an output has no memo data, it is -assigned the memo key consisting of 32 \(\mathtt{0xFF}\) bytes.

-

In note plaintexts of v6-onward transactions, the 512-byte memo field -is replaced by \(\mathsf{K^{memo}}\).

-

The transaction builder generates a 32-byte salt value \(\mathsf{salt}\) from a CSPRNG. A new salt -MUST be generated for each memo bundle.

-

The symmetric encryption key for a memo is derived from its \(\mathsf{K^{memo}}\) as follows:

-

\(\hspace{2em}\mathsf{encryption\_key} = -\mathsf{PRF^{expand}_{K^{memo}}}([\mathtt{0xE0}] \,||\, -\mathsf{salt})\)

-

The first byte \(\mathtt{0xE0}\) -should be added to the documentation of inputs to \(\mathsf{PRF^{expand}}\) in § 4.1.2 ‘Pseudo -Random Functions’ 7.

-

If the generated key is 32 \(\mathtt{0xFF}\) bytes, the transaction -constructor MAY repeat this procedure with a different salt, in order to -avoid the recipient misinterpreting the output as having no memo data. -Since that has negligible probability, it alternatively MAY omit this -check.

-

Each memo is padded to a multiple of 256 bytes with zeroes, and split -into 256-byte chunks. Each memo chunk is encrypted with ChaCha20Poly1305 -8 as follows:

-

\(\hspace{2em}\mathsf{IETF\_AEAD\_CHACHA20\_POLY1305}(\mathsf{encryption\_key}, -\mathsf{nonce}, \mathsf{memo\_chunk})\)

-

where \(\mathsf{nonce} = -\mathsf{I2BEOSP}_{88}(\mathsf{counter}) \,||\, -[\mathsf{final\_chunk}]\).

-

This is a variant of the STREAM construction 9.

+ +

Specification

+ +

Since this proposal is defined only for v6 and later transactions, it is not +necessary to consider Sprout JoinSplit outputs. The following sections apply +to both Sapling and Orchard outputs.

+ +

Memo bundle

+ +

A memo bundle consists of a sequence of 256-byte memo chunks, each individually +encrypted. These memo chunks represent zero or more encrypted memos.

+ +

Each transaction may contain a single memo bundle, and a memo bundle may contain +at most memo_chunk_limit memo chunks. This limits the total amount of memo data +that can be conveyed within a single transaction to memo_chunk_limit * 256 bytes.

+ +

memo_chunk_limit is a parameter to this specification, to be decided upon +by the community. The authors of this ZIP propose a maximum of 64 chunks, +resulting in a maximum total memo data length of 16 KiB.

+ +

Memo bundles are encoded in transactions in a prunable manner: each memo chunk +can be replaced by its representative digest.

+ +

Memo encryption

+ +

During transaction construction, each output with memo data is assigned a 32-byte +memo key \(\mathsf{K^{memo}}\). These keys SHOULD be generated randomly, and MUST NOT +be used to encrypt more than one memo within a single transaction. If an output has +no memo data, it is assigned the memo key consisting of 32 \(\mathtt{0xFF}\) bytes.

+ +

In note plaintexts of v6-onward transactions, the 512-byte memo field is replaced +by \(\mathsf{K^{memo}}\).

+ +

The transaction builder generates a 32-byte salt value \(\mathsf{salt}\) from a CSPRNG. +A new salt MUST be generated for each memo bundle.

+ +

The symmetric encryption key for a memo is derived from its \(\mathsf{K^{memo}}\) as follows:

+ +

\(\hspace{2em}\mathsf{encryption\_key} = \mathsf{PRF^{expand}_{K^{memo}}}([\mathtt{0xE0}] \,||\, \mathsf{salt})\)

+ +

The first byte \(\mathtt{0xE0}\) should be added to the documentation of inputs to +\(\mathsf{PRF^{expand}}\) in § 4.1.2 ‘Pseudo Random Functions’ 7.

+ +

If the generated key is 32 \(\mathtt{0xFF}\) bytes, the transaction constructor MAY +repeat this procedure with a different salt, in order to avoid the recipient +misinterpreting the output as having no memo data. Since that has negligible +probability, it alternatively MAY omit this check.

+ +

Each memo is padded to a multiple of 256 bytes with zeroes, and split into +256-byte chunks. Each memo chunk is encrypted with ChaCha20Poly1305 8 +as follows:

+ +

\(\hspace{2em}\mathsf{IETF\_AEAD\_CHACHA20\_POLY1305}(\mathsf{encryption\_key}, \mathsf{nonce}, \mathsf{memo\_chunk})\)

+ +

where \(\mathsf{nonce} = \mathsf{I2BEOSP}_{88}(\mathsf{counter}) \,||\, [\mathsf{final\_chunk}]\).

+ +

This is a variant of the STREAM construction 9.

+
    -
  • \(\mathsf{counter}\) is a -big-endian chunk counter starting at zero and incrementing by one for -each subsequent chunk within a particular memo.
    • -
  • \(\mathsf{final\_chunk}\) is the -byte \(\mathtt{0x01}\) for the final -memo chunk, and \(\mathtt{0x00}\) for -all preceding chunks.
    • +
  • \(\mathsf{counter}\) is a big-endian chunk counter starting at zero and incrementing +by one for each subsequent chunk within a particular memo.
    • +
  • \(\mathsf{final\_chunk}\) is the byte \(\mathtt{0x01}\) for the final memo chunk, and +\(\mathtt{0x00}\) for all preceding chunks.
-

Finally, the encrypted memo chunks for all memos are combined into a -single sequence using an order-preserving shuffle. Memo chunks from -different memos MAY be interleaved in any order, but memo chunks from -the same memo MUST have the same relative order. The following diagram -shows an example shuffle of three memos:

+ +

Finally, the encrypted memo chunks for all memos are combined into a single +sequence using an order-preserving shuffle. Memo chunks from different memos MAY +be interleaved in any order, but memo chunks from the same memo MUST have the +same relative order. The following diagram shows an example shuffle of three +memos:

+ 
[
     (memo_a, 0),
     (memo_b, 0),
@@ -193,556 +193,558 @@ 
Memo encryption

     (memo_c, 0),
     (memo_c, 1),
     (memo_a, 2),
-]
-

Memo decryption

-

When a recipient decrypts a shielded output, they obtain a memo key -\(\mathsf{K^{memo}}\). From this they -derive encryption_key as above, and then proceed as -follows:

+] + + +

Memo decryption

+ +

When a recipient decrypts a shielded output, they obtain a memo key \(\mathsf{K^{memo}}\). +From this they derive encryption_key as above, and then proceed as follows:

+
    -
  • Set counter = 0 and -final_chunk = 0x00.
    • -
  • Attempt to decrypt each memo chunk in order. Pruned memo chunks are -skipped.
    • -
  • Each time decryption succeeds for a memo chunk, increment -counter by 1, and then continue attempting to decrypt -subsequent chunks.
    • -
  • Once all memo chunks have been trial-decrypted once, set -final_chunk = 0x01 and then attempt to decrypt the memo -chunks again, starting immediately after the last successfully-decrypted -chunk (or at the start if none were), and without incrementing -counter. -
      -
    • This step can be made secret-independent by attempting to decrypt -every memo chunk again, and ignoring the results of all chunks up to and -including the last successfully-decrypted chunk.
      • -
    • -
  • If no memo chunk decrypts successfully with -final_chunk = 0x01, discard any memo chunks that were -decrypted, and return nothing. Otherwise, concatenate the decrypted memo -chunks in order and return the concatenation as the memo.
    • +
  • Set counter = 0 and final_chunk = 0x00.
    • +
  • Attempt to decrypt each memo chunk in order. Pruned memo chunks are skipped.
    • +
  • Each time decryption succeeds for a memo chunk, increment counter by 1, and +then continue attempting to decrypt subsequent chunks.
    • +
  • Once all memo chunks have been trial-decrypted once, set final_chunk = 0x01 +and then attempt to decrypt the memo chunks again, starting immediately after +the last successfully-decrypted chunk (or at the start if none were), and +without incrementing counter.
    • +
  • This step can be made secret-independent by attempting to decrypt every memo +chunk again, and ignoring the results of all chunks up to and including the +last successfully-decrypted chunk.
    • +
  • If no memo chunk decrypts successfully with final_chunk = 0x01, discard any +memo chunks that were decrypted, and return nothing. Otherwise, concatenate +the decrypted memo chunks in order and return the concatenation as the memo.
-

If any chunk of the memo encrypted to memo_key has been -pruned, the decryption process above returns nothing (as -final_chunk will be set to 0x01 with the wrong -counter value), ensuring that a malformed memo is not returned.

-

Encoding in transactions

+ +

If any chunk of the memo encrypted to memo_key has been pruned, the decryption +process above returns nothing (as final_chunk will be set to 0x01 with the +wrong counter value), ensuring that a malformed memo is not returned.

+ +

Encoding in transactions

+ ----++++ + - - - - + + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + +
BytesNameData TypeDescription Bytes Name Data Type Description
1fAllPruneduint81 if all chunks have been pruned, otherwise 0. 1 fAllPruned uint8 1 if all chunks have been pruned, otherwise 0.
32nonceOrHashbyte[32]The nonce for deriving encryption keys, or the overall hash. 32 nonceOrHash byte[32] The nonce for deriving encryption keys, or the overall hash.
† variesnMemoChunkscompactSizeThe number of memo chunks. † varies nMemoChunks compactSize The number of memo chunks.
† variesprunedbyte[\(\mathsf{ceiling}(\mathtt{nMemoChunks}/8)\)]Bitflags indicating the type of each entry in -vMemoChunks. † varies pruned byte[\(\mathsf{ceiling}(\mathtt{nMemoChunks}/8)\)] Bitflags indicating the type of each entry in vMemoChunks.
† variesvMemoChunksMemoChunk[nMemoChunks]A sequence of encrypted memo chunks. † varies vMemoChunks MemoChunk[nMemoChunks] A sequence of encrypted memo chunks.
-

† These fields are present if and only if -fAllPruned == 0.

+ +

† These fields are present if and only if fAllPruned == 0.

+

If fAllPruned == 0, then:

+
    -
  • nonceOrHash represents the nonce for deriving -encryption keys.
    • -
  • Each bit of pruned, in little-endian order, indicates -the type of the corresponding entry in vMemoChunks. A bit -value of 0 indicates that the entry will be of type -byte[272] representing an encrypted memo chunk. A bit value -of 1 indicates the entry will be a byte[32] and contains -the memo_chunk_digest for a pruned chunk.
    • +
  • nonceOrHash represents the nonce for deriving encryption keys.
    • +
  • Each bit of pruned, in little-endian order, indicates the type of the +corresponding entry in vMemoChunks. A bit value of 0 indicates that +the entry will be of type byte[272] representing an encrypted memo +chunk. A bit value of 1 indicates the entry will be a byte[32] and +contains the memo_chunk_digest for a pruned chunk.
+

If fAllPruned == 1, then:

+
    -
  • nonceOrHash represents the overall hash for the memo -bundle as defined in Transaction -sighash.
    • -
  • The nMemoChunks, pruned, and -vMemoChunks fields will be absent.
    • +
  • nonceOrHash represents the overall hash for the memo bundle as defined in +Transaction sighash.
    • +
  • The nMemoChunks, pruned, and vMemoChunks fields will be absent.
-

Transaction sighash

+ +

Transaction sighash

+ 
memo_chunk_digest = H(AEAD(MemoChunk, memo_key))
-memo_bundle_digest = H(concat(memo_chunk_digests))
-

The memo bundle digest structure is a performance optimization for -the case where all memo chunks in a transaction have been pruned.

-

TODO: finish this to be a modification to the equivalent of ZIP 244 -for transaction v6.

-

Transaction fees

+memo_bundle_digest = H(concat(memo_chunk_digests)) + + +

The memo bundle digest structure is a performance optimization for the case +where all memo chunks in a transaction have been pruned.

+ +

TODO: finish this to be a modification to the equivalent of ZIP 244 for +transaction v6.

+ +

Transaction fees

+

(This section will become a modification to ZIP 317.)

-

A memo bundle may contain two free chunks if there are any shielded -outputs in the transaction. Otherwise, each memo chunk requires -marginal_fee as defined in ZIP 317 10.

-

Network protocol

-

Nodes must reject GetData responses having an -fAllPruned value that is nonzero, or any byte of -pruned that is nonzero.

-

Changes to the -Zcash Protocol Specification

-

The following changes affecting the definitions of note plaintexts -and note ciphertexts, and the algorithms for encryption and -decryption.

+ +

A memo bundle may contain two free chunks if there are any shielded outputs in +the transaction. Otherwise, each memo chunk requires marginal_fee as defined +in ZIP 317 10.

+ +

Network protocol

+ +

Nodes must reject GetData responses having an fAllPruned value that is nonzero, +or any byte of pruned that is nonzero.

+ +

Changes to the Zcash Protocol Specification

+ +

The following changes affecting the definitions of note plaintexts and note ciphertexts, +and the algorithms for encryption and decryption.

+

In § 3.2.1 ‘Note Plaintexts and Memo Fields’:

+

  • Change

    +
    -

    Each Sapling or Orchard note plaintext (denoted \(\mathbf{np}\)) consists of

    -

    \(\hspace{2em}(\mathsf{leadByte} \;⦂\; -\mathbb{B^{Y}}, \mathsf{d} \;⦂\; \mathbb{B^{[\ell_{\mathsf{d}}]}}, -\mathsf{rseed} \;⦂\; \mathbb{B^{Y[32]}}, \mathsf{memo} \;⦂\; -\mathbb{B^{Y[512]}})\)

    +

    Each Sapling or Orchard note plaintext (denoted \(\mathbf{np}\)) consists of

    + +

    \(\hspace{2em}(\mathsf{leadByte} \;⦂\; \mathbb{B^{Y}}, \mathsf{d} \;⦂\; \mathbb{B^{[\ell_{\mathsf{d}}]}}, \mathsf{rseed} \;⦂\; \mathbb{B^{Y[32]}}, \mathsf{memo} \;⦂\; \mathbb{B^{Y[512]}})\)

    +

    to

    +
    -

    The form of a Sapling or Orchard note plaintext depends on the -version of the transaction in which it will be included; specifically -whether that version is pre-v6, or v6-onward.

    -

    Each pre-v6 Sapling or Orchard note plaintext (denoted \(\mathbf{np}\)) consists of

    -

    \(\hspace{2em}(\mathsf{leadByte} \;⦂\; -\mathbb{B^{Y}}, \mathsf{d} \;⦂\; \mathbb{B^{[\ell_{\mathsf{d}}]}}, -\mathsf{rseed} \;⦂\; \mathbb{B^{Y[32]}}, \mathsf{memo} \;⦂\; -\mathbb{B^{Y[512]}})\)

    -

    Each v6-onward Sapling or Orchard note plaintext (denoted \(\mathbf{np}\)) consists of

    -

    \(\hspace{2em}(\mathsf{leadByte} \;⦂\; -\mathbb{B^{Y}}, \mathsf{d} \;⦂\; \mathbb{B^{[\ell_{\mathsf{d}}]}}, -\mathsf{rseed} \;⦂\; \mathbb{B^{Y[32]}}, \mathsf{K^{memo}} \;⦂\; -\mathbb{B^{Y[32]}})\)

    +

    The form of a Sapling or Orchard note plaintext depends on the version of +the transaction in which it will be included; specifically whether that +version is pre-v6, or v6-onward.

    + +

    Each pre-v6 Sapling or Orchard note plaintext (denoted \(\mathbf{np}\)) consists of

    + +

    \(\hspace{2em}(\mathsf{leadByte} \;⦂\; \mathbb{B^{Y}}, \mathsf{d} \;⦂\; \mathbb{B^{[\ell_{\mathsf{d}}]}}, \mathsf{rseed} \;⦂\; \mathbb{B^{Y[32]}}, \mathsf{memo} \;⦂\; \mathbb{B^{Y[512]}})\)

    + +

    Each v6-onward Sapling or Orchard note plaintext (denoted \(\mathbf{np}\)) consists of

    + +

    \(\hspace{2em}(\mathsf{leadByte} \;⦂\; \mathbb{B^{Y}}, \mathsf{d} \;⦂\; \mathbb{B^{[\ell_{\mathsf{d}}]}}, \mathsf{rseed} \;⦂\; \mathbb{B^{Y[32]}}, \mathsf{K^{memo}} \;⦂\; \mathbb{B^{Y[32]}})\)

-

In § 5.5 ‘Encodings of Note Plaintexts and Memo Fields’ 11:

+ +

In § 5.5 ‘Encodings of Note Plaintexts and Memo Fields’ 11:

+
    -

  • Change the paragraph that describes “The encoding of a Sapling or -Orchard note plaintext” to refer to “The encoding of a pre-v6 Sapling or -Orchard note plaintext”.

    • +

  • Change the paragraph that describes “The encoding of a Sapling or Orchard note plaintext” +to refer to “The encoding of a pre-v6 Sapling or Orchard note plaintext”.

  • Add a new paragraph at the end of the section:

    +
    -

    The encoding of a v6-onward Sapling or Orchard note plaintext -consists of:

    - ------- - - - - - - - - - -
    8-bit \(\mathsf{leadByte}\)88-bit \(\mathsf{d}\)64-bit \(\mathsf{v}\)256-bit \(\mathsf{rseed}\)32-byte \(\mathsf{K^{memo}}\)
    +

    The encoding of a v6-onward Sapling or Orchard note plaintext consists of:

    + +

    | | | | | | +|—————————|———————|———————|————————–|—————————–| +| 8-bit \(\mathsf{leadByte}\) | 88-bit \(\mathsf{d}\) | 64-bit \(\mathsf{v}\) | 256-bit \(\mathsf{rseed}\) | 32-byte \(\mathsf{K^{memo}}\) |

    +
    • A byte 0x03, indicating this version of the encoding of a v6-onward Sapling or Orchard note plaintext.
      • -
    • 11 bytes specifying \(\mathsf{d}\).
      • -
    • 8 bytes specifying \(\mathsf{v}\).
      • -
    • 32 bytes specifying \(\mathsf{rseed}\).
      • -
    • 32 bytes specifying \(\mathsf{K^{memo}}\).
      • +
    • 11 bytes specifying \(\mathsf{d}\).
      • +
    • 8 bytes specifying \(\mathsf{v}\).
      • +
    • 32 bytes specifying \(\mathsf{rseed}\).
      • +
    • 32 bytes specifying \(\mathsf{K^{memo}}\).
    -

    A value consisting of 32 \(\mathtt{0xFF}\) bytes for \(\mathsf{K^{memo}}\) is used to indicate -that there is no memo for this note plaintext.

    + +

    A value consisting of 32 \(\mathtt{0xFF}\) bytes for \(\mathsf{K^{memo}}\) is used +to indicate that there is no memo for this note plaintext.

-

In § 4.7.2 ‘Sending Notes (Sapling)’ 12 -and § 4.7.3 ‘Sending Notes (Orchard)’ 13:

+ +

In § 4.7.2 ‘Sending Notes (Sapling)’ 12 and +§ 4.7.3 ‘Sending Notes (Orchard)’ 13:

+
    -

  • Add a reference to this ZIP specifying the construction of the -memo bundle and derivation of \(\mathsf{K^{memo}}\) in the case of a -v6-onward note plaintext.

    • +

  • Add a reference to this ZIP specifying the construction of the memo bundle and +derivation of \(\mathsf{K^{memo}}\) in the case of a v6-onward note plaintext.

  • Change

    +
    -

    Let \(\mathbf{np} = (\mathsf{leadByte}, -\mathsf{d}, \mathsf{v}, \mathsf{rseed}, \mathsf{memo})\).

    +

    Let \(\mathbf{np} = (\mathsf{leadByte}, \mathsf{d}, \mathsf{v}, \mathsf{rseed}, \mathsf{memo})\).

    +

    to

    +
    -

    Let \(\mathbf{np}\) be the encoding -of a Sapling note plaintext using \(\mathsf{leadByte}\), \(\mathsf{d}\), \(\mathsf{v}\), \(\mathsf{rseed}\), and either \(\mathsf{memo}\) for a pre-v6 note plaintext -or \(\mathsf{K^{memo}}\) for a -v6-onward note plaintext.

    +

    Let \(\mathbf{np}\) be the encoding of a Sapling note plaintext using \(\mathsf{leadByte}\), \(\mathsf{d}\), +\(\mathsf{v}\), \(\mathsf{rseed}\), and either \(\mathsf{memo}\) for a pre-v6 note plaintext or +\(\mathsf{K^{memo}}\) for a v6-onward note plaintext.

    -

    replacing “Sapling” with Orchard in the case of § 4.7.3.

    • + +

    replacing “Sapling” with Orchard in the case of § 4.7.3.

-

In § 4.20.1 ‘Encryption (Sapling and Orchard)’ 14:

+ +

In § 4.20.1 ‘Encryption (Sapling and Orchard)’ 14:

+

  • Change

    +
    -

    Let \(\mathbf{np} = (\mathsf{leadByte}, -\mathsf{d}, \mathsf{v}, \mathsf{rseed}, \mathsf{memo})\) be the -Sapling or Orchard note plaintext. \(\mathbf{np}\) is encoded as defined in § -5.5 ‘Encodings of Note Plaintexts and Memo Fields’.

    +

    Let \(\mathbf{np} = (\mathsf{leadByte}, \mathsf{d}, \mathsf{v}, \mathsf{rseed}, \mathsf{memo})\) +be the Sapling or Orchard note plaintext. \(\mathbf{np}\) is encoded as defined +in § 5.5 ‘Encodings of Note Plaintexts and Memo Fields’.

    +

    to

    +
    -

    Let \(\mathbf{np}\) be the encoding -of the Sapling or Orchard note plaintext (which may be pre-v6 or -v6-onward), as defined in § 5.5 ‘Encodings of Note Plaintexts and Memo -Fields’.

    +

    Let \(\mathbf{np}\) be the encoding of the Sapling or Orchard note plaintext (which may be +pre-v6 or v6-onward), as defined in § 5.5 ‘Encodings of Note Plaintexts and Memo Fields’.

  • Add another normative note to that section:

    +
      -
    • \(\mathsf{C^{enc}}\) will be of -length either 580 or 100 bytes, depending on whether \(\mathbf{np}\) is a pre-v6 or v6-onward note -plaintext.
      • +
    • \(\mathsf{C^{enc}}\) will be of length either 580 or 100 bytes, depending on whether +\(\mathbf{np}\) is a pre-v6 or v6-onward note plaintext.
-

In § 4.20.2 ‘Decryption using an Incoming Viewing Key (Sapling and -Orchard)’ 15 and § 4.20.3 ‘Decryption using a -Full Viewing Key (Sapling and Orchard)’ 16:

+ +

In § 4.20.2 ‘Decryption using an Incoming Viewing Key (Sapling and Orchard)’ 15 +and § 4.20.3 ‘Decryption using a Full Viewing Key (Sapling and Orchard)’ 16:

+
    -
  • Replace \(\mathsf{memo} \;⦂\; -\mathbb{B^{Y[512]}}\) with \(\mathsf{memoOrKey}\).
    • -
  • Specify that the type of \(\mathsf{memoOrKey}\) is \(\mathbb{B^{Y[512]}}\) when decrypting a -pre-v6 note ciphertext, or \(\mathbb{B^{Y[32]}}\) when decrypting a -v6-onward note ciphertext. In the latter case, it is used as \(\mathsf{K^{memo}}\) to decrypt the memo -bundle as described in Memo bundle.
    • +
  • Replace \(\mathsf{memo} \;⦂\; \mathbb{B^{Y[512]}}\) with \(\mathsf{memoOrKey}\).
    • +
  • Specify that the type of \(\mathsf{memoOrKey}\) is \(\mathbb{B^{Y[512]}}\) when +decrypting a pre-v6 note ciphertext, or \(\mathbb{B^{Y[32]}}\) when decrypting a +v6-onward note ciphertext. In the latter case, it is used as \(\mathsf{K^{memo}}\) +to decrypt the memo bundle as described in Memo bundle.
-

Applicability

+ +

Applicability

+

All of these changes apply identically to Mainnet and Testnet.

-

Open issues

-

Limit on the number of memo -chunks

-

memo_chunk_limit == 64 is recommended. This results in a -maximum of 16 KiB of memo data per transaction.

-

Interaction with ZIP 302 17

+ +

Open issues

+ +

Limit on the number of memo chunks

+ +

memo_chunk_limit == 64 is recommended. This results in a maximum of 16 KiB +of memo data per transaction.

+ +

Interaction with ZIP 302 17

+

TBD

-

Rationale

-

Memo bundle size restriction

-

Restricting the total amount of memo data in a bundle, for example to -16 KiB, limits the rate at which the chain size can grow cheaply (from a -computational perspective; memo bundles are much easier to produce than -proofs or signatures).

-

The current behaviour for previous transaction versions (no limit on -the number of memos) is not altered by this ZIP, because memos in those -transactions are tied to individual shielded outputs (incurring their -computational cost), and are not natively aggregatable.

-

Memo chunk size

+ +

Rationale

+ +

Memo bundle size restriction

+ +

Restricting the total amount of memo data in a bundle, for example to 16 KiB, +limits the rate at which the chain size can grow cheaply (from a computational +perspective; memo bundles are much easier to produce than proofs or signatures).

+ +

The current behaviour for previous transaction versions (no limit on the number +of memos) is not altered by this ZIP, because memos in those transactions are +tied to individual shielded outputs (incurring their computational cost), and +are not natively aggregatable.

+ +

Memo chunk size

+

TODO: this table needs to be recalculated with a 16 KiB limit.

-

With 10 KiB limit on amount of memo data as the constant in this -table, the maximum number of unique memos you can create, and the cost -in bytes of that memo data plus auth when using a 32-byte memo key, -is:

+ +

With 10 KiB limit on amount of memo data as the constant in this table, the +maximum number of unique memos you can create, and the cost in bytes of that +memo data plus auth when using a 32-byte memo key, is:

+ +++++ + - - - + + + + - - - + + + - - - + + + - - - + + + - - - + + +
Chunk sizeMemo size ≤ 256 bytesMemo size = 512 bytes Chunk size Memo size ≤ 256 bytes Memo size = 512 bytes
Pre-23120 @ 10240 ( 0.00%)20 @ 10240 ( 0.00%) Pre-231 20 @ 10240 ( 0.00%) 20 @ 10240 ( 0.00%)
51220 @ 11220 (+ 9.57%)20 @ 11220 (+ 9.57%) 512 20 @ 11220 (+ 9.57%) 20 @ 11220 (+ 9.57%)
25640 @ 12200 (+19.14%)20 @ 11540 (+12.70%) 256 40 @ 12200 (+19.14%) 20 @ 11540 (+12.70%)
256 20-out20 @ 6100 (-40.43%) 256 20-out 20 @ 6100 (-40.43%)
-

In the “256 20-out” case you have a distinguisher compared to old -transactions, in that you can tell the transaction is sending at most -256 bytes per recipient rather than 512 if it is sending the max number -of memos. But that’s inherently baked into the decision to use a smaller -memo chunk size (and it is still possible for the chunks to all be a -single memo sent to all outputs, or anything in between).

-

Memo key size

-

If we used a 16-byte memo key instead of 32 bytes, the transaction -size overhead becomes:

+ +

In the “256 20-out” case you have a distinguisher compared to old transactions, +in that you can tell the transaction is sending at most 256 bytes per recipient +rather than 512 if it is sending the max number of memos. But that’s inherently +baked into the decision to use a smaller memo chunk size (and it is still +possible for the chunks to all be a single memo sent to all outputs, or anything +in between).

+ +

Memo key size

+ +

If we used a 16-byte memo key instead of 32 bytes, the transaction size overhead +becomes:

+ +++++ + - - - + + + + - - - + + + - - - + + + - - - + + + - - - + + +
Chunk sizeMemo size ≤ 256 bytesMemo size = 512 bytes Chunk size Memo size ≤ 256 bytes Memo size = 512 bytes
Pre-23120 @ 10240 ( 0.00%)20 @ 10240 ( 0.00%) Pre-231 20 @ 10240 ( 0.00%) 20 @ 10240 ( 0.00%)
51220 @ 10900 (+ 6.45%)20 @ 10900 (+ 6.45%) 512 20 @ 10900 (+ 6.45%) 20 @ 10900 (+ 6.45%)
25640 @ 11560 (+12.89%)20 @ 11220 (+ 9.57%) 256 40 @ 11560 (+12.89%) 20 @ 11220 (+ 9.57%)
256 20-out20 @ 5780 (-43.55%) 256 20-out 20 @ 5780 (-43.55%)
-

The decrease in overhead is relatively modest in most cases, but more -noticeable for small memos with a 256-byte memo chunk.

-

However, 128-bit keys don’t meet Zcash’s target security level of 125 -bits, as argued in 18.

+ +

The decrease in overhead is relatively modest in most cases, but more noticeable +for small memos with a 256-byte memo chunk.

+ +

However, 128-bit keys don’t meet Zcash’s target security level of 125 bits, +as argued in 18.

+

The benefits of 256-bit keys are:

+
    -
  • They incur only a small transaction size overhead above the minimum -key size that would meet the target security level.
    • -
  • This key length matches what we already use elsewhere for symmetric -keys.
    • +
  • They incur only a small transaction size overhead above the minimum key size +that would meet the target security level.
    • +
  • This key length matches what we already use elsewhere for symmetric keys.
-

Encryption format

-

Including a per-transaction \(\mathsf{salt}\) in the derivation of \(\mathsf{encryption_key}\) gives protection -against accidental (or intentional) reuse of \(\mathsf{K^{memo}}\) reuse across multiple -transactions. We do not protect against \(\mathsf{K^{memo}}\) reuse within a -transaction; it is up to the transaction builder to ensure that the same -\(\mathsf{K^{memo}}\) is not used to -encrypt two different memos (and if they did so, normal clients would -either never observe the second memo, or would decrypt parts of each -memo and get a nonsensical and potentially insecure “spliced” memo).

-

We do not include commitments to the shielded outputs in the -derivation of \(\mathsf{encryption_key}\) for two -reasons:

+ +

Encryption format

+ +

Including a per-transaction \(\mathsf{salt}\) in the derivation of +\(\mathsf{encryption_key}\) gives protection against accidental (or intentional) +reuse of \(\mathsf{K^{memo}}\) reuse across multiple transactions. We do not +protect against \(\mathsf{K^{memo}}\) reuse within a transaction; it is up to +the transaction builder to ensure that the same \(\mathsf{K^{memo}}\) is not +used to encrypt two different memos (and if they did so, normal clients would +either never observe the second memo, or would decrypt parts of each memo and +get a nonsensical and potentially insecure “spliced” memo).

+ +

We do not include commitments to the shielded outputs in the derivation of +\(\mathsf{encryption_key}\) for two reasons:

+
    -
  • It would force the transaction builder to fully define all shielded -outputs before encrypting the memos, which might prevent potential use -cases of PCZTs 19.
    • -
  • We don’t want to unnecessarily prevent the ability to create a -transaction with a memo bundle and no shielded outputs, as there may be -use cases for, e.g. a fully-transparent transaction with encrypted memo, -or a ZSA issuance transaction with exposed memo data using a well-known -\(\mathsf{K^{memo}}\).
    • +
  • It would force the transaction builder to fully define all shielded outputs +before encrypting the memos, which might prevent potential use cases of PCZTs 19.
    • +
  • We don’t want to unnecessarily prevent the ability to create a transaction +with a memo bundle and no shielded outputs, as there may be use cases for, +e.g. a fully-transparent transaction with encrypted memo, or a ZSA issuance +transaction with exposed memo data using a well-known \(\mathsf{K^{memo}}\).
-

Pruned encoding

-

The separation of memo data from note data, and the new ability to -easily store variable-length memo data, opens up an attack vector -against node operators for storing arbitrary data. The transaction -digest commitments to the memo bundle are structured such that if a node -operator is presented with a memo key (i.e. they are given the -capability to decrypt a particular memo), they can identify and prune -the corresponding memo chunks, while still enabling the transaction to -be validated as part of its corresponding block and broadcast over the -network.

-

The transaction encoding permits pruning at the individual chunk -level in order to facilitate pruning an individual memo from a -transaction without affecting the other memos. This enables node -operators to be responsive to, for example, GDPR deletion requests.

-

Note that broadcasting a partially-pruned transaction means that the -pruned chunks no longer contribute to the upper bound on memo data.

-

The prunable structure does not introduce a censorship axis; memo -bundles do not reveal which memo chunks correspond to which memos, and -therefore a network adversary cannot selectively censor individual -memos. They can censor any/all chunks within specific transactions, -however shielded transactions do not reveal their senders, recipients, -or amounts, and thus also cannot be individually targeted for -censorship.

-

Transaction fees

-

Making the fee linear in the number of chunks has the following -properties:

+ +

Pruned encoding

+ +

The separation of memo data from note data, and the new ability to easily store +variable-length memo data, opens up an attack vector against node operators for +storing arbitrary data. The transaction digest commitments to the memo bundle +are structured such that if a node operator is presented with a memo key (i.e. +they are given the capability to decrypt a particular memo), they can identify +and prune the corresponding memo chunks, while still enabling the transaction to +be validated as part of its corresponding block and broadcast over the network.

+ +

The transaction encoding permits pruning at the individual chunk level in order +to facilitate pruning an individual memo from a transaction without affecting the +other memos. This enables node operators to be responsive to, for example, GDPR +deletion requests.

+ +

Note that broadcasting a partially-pruned transaction means that the pruned +chunks no longer contribute to the upper bound on memo data.

+ +

The prunable structure does not introduce a censorship axis; memo bundles do not +reveal which memo chunks correspond to which memos, and therefore a network +adversary cannot selectively censor individual memos. They can censor any/all +chunks within specific transactions, however shielded transactions do not reveal +their senders, recipients, or amounts, and thus also cannot be individually +targeted for censorship.

+ +

Transaction fees

+ +

Making the fee linear in the number of chunks has the following properties:

+
    -
  • The required fee to add more memo chunks scales at the same rate as -adding logical actions, so it isn’t a cheaper mechanism for an adversary -to bloat chain size.
    • -
  • A “baseline transaction” (one spent note, one output to an external -recipient with a memo, one change output without a memo) has the same -fee as before.
    • -
  • A “broadcast transaction” (many outputs to different recipients all -given the same memo) is the same fee as before (but a smaller -transaction).
    • -
  • A “many memos transaction” (many outputs to different recipients all -with unique memos) is at most around twice the fee as before.
    • +
  • The required fee to add more memo chunks scales at the same rate as adding +logical actions, so it isn’t a cheaper mechanism for an adversary to bloat +chain size.
    • +
  • A “baseline transaction” (one spent note, one output to an external recipient +with a memo, one change output without a memo) has the same fee as before.
    • +
  • A “broadcast transaction” (many outputs to different recipients all given the +same memo) is the same fee as before (but a smaller transaction).
    • +
  • A “many memos transaction” (many outputs to different recipients all with +unique memos) is at most around twice the fee as before.
-

Combined with the memo bundle size restriction, the maximum -additional fee for a memo bundle over prior transactions is 0.0019 -ZEC.

-

Deployment

-

This ZIP is proposed to activate with Network Upgrade 7. 20

-

Reference implementation

+ +

Combined with the memo bundle size restriction, the maximum additional fee for +a memo bundle over prior transactions is 0.0019 ZEC.

+ +

Deployment

+ +

This ZIP is proposed to activate with Network Upgrade 7. 20

+ +

Reference implementation

+

TBD

-

References

-
+ +

References

+ +
    -

  1. 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”↩︎

    2. -

  2. ZIP 200: Network Upgrade -Mechanism↩︎

    3. -

  3. Zcash Protocol -Specification, Version 2024.5.1 [NU6] or later↩︎

    4. -

  4. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and -Testnet↩︎

    5. -

  5. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 3.2.1: Note -Plaintexts and Memo Fields↩︎

    6. -

  6. ZIP 307: Light Client Protocol -for Payment Detection↩︎

    7. -

  7. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 4.1.2: Pseudo -Random Functions↩︎

    8. -

  8. RFC 8439: ChaCha20 -and Poly1305 for IETF Protocols↩︎

    9. -

  9. Online -Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance↩︎

    10. -

  10. ZIP 317: Proportional Transfer -Fee Mechanism↩︎

    11. -

  11. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 5.5: Encodings -of Note Plaintexts and Memo Fields↩︎

    12. -

  12. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 4.7.2: Sending -Notes (Sapling)↩︎

    13. -

  13. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 4.7.3: Sending -Notes (Orchard)↩︎

    14. -

  14. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 4.20.1: Encryption -(Sapling and Orchard)↩︎

    15. -

  15. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 4.20.2: -Decryption using an Incoming Viewing Key (Sapling and Orchard)↩︎

    16. -

  16. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 4.20.3: -Decryption using a Full Viewing Key (Sapling and Orchard)↩︎

    17. -

  17. ZIP 302: Standardized Memo Field -Format↩︎

    18. -

  18. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 8.7: In-band -secret distribution↩︎

    19. -

  19. zcash/zips issue #693: -Standardize a protocol for creating shielded transactions offline↩︎

    20. -

  20. ZIP 254: Deployment of the NU7 -Network Upgrade↩︎

    21. + +
  21. +

    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”  ↩︎

    +
    22. + +
  22. +

    ZIP 200: Network Upgrade Mechanism  ↩︎

    +
    23. + +
  23. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6] or later  ↩︎

    +
    24. + +
  24. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and Testnet  ↩︎

    +
    25. + +
  25. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.2.1: Note Plaintexts and Memo Fields  ↩︎

    +
    26. + +
  26. +

    ZIP 307: Light Client Protocol for Payment Detection  ↩︎

    +
    27. + +
  27. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.1.2: Pseudo Random Functions  ↩︎

    +
    28. + +
  28. +

    RFC 8439: ChaCha20 and Poly1305 for IETF Protocols  ↩︎

    +
    29. + +
  29. +

    Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance  ↩︎

    +
    30. + +
  30. +

    ZIP 317: Proportional Transfer Fee Mechanism  ↩︎

    +
    31. + +
  31. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.5: Encodings of Note Plaintexts and Memo Fields  ↩︎

    +
    32. + +
  32. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.7.2: Sending Notes (Sapling)  ↩︎

    +
    33. + +
  33. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.7.3: Sending Notes (Orchard)  ↩︎

    +
    34. + +
  34. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.20.1: Encryption (Sapling and Orchard)  ↩︎

    +
    35. + +
  35. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.20.2: Decryption using an Incoming Viewing Key (Sapling and Orchard)  ↩︎

    +
    36. + +
  36. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.20.3: Decryption using a Full Viewing Key (Sapling and Orchard)  ↩︎

    +
    37. + +
  37. +

    ZIP 302: Standardized Memo Field Format  ↩︎

    +
    38. + +
  38. +

    Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 8.7: In-band secret distribution  ↩︎

    +
    39. + +
  39. +

    zcash/zips issue #693: Standardize a protocol for creating shielded transactions offline  ↩︎

    +
    40. + +
  40. +

    ZIP 254: Deployment of the NU7 Network Upgrade  ↩︎

    +
    41. +
-
+ diff --git a/rendered/zip-0233.html b/rendered/zip-0233.html index 4f8188360..e486657c4 100644 --- a/rendered/zip-0233.html +++ b/rendered/zip-0233.html @@ -22,232 +22,238 @@ Category: Consensus / Ecosystem Created: 2023-08-16 License: BSD-2-Clause -Discussions-To: <https://github.com/zcash/zips/issues/922> -

Terminology

-

The key word “MUST” in this document is to be interpreted as -described in BCP 14 1 when, and only when, it appears in -all capitals.

-

The term “network upgrade” in this document is to be interpreted as -described in ZIP 200. 2

-

The character § is used when referring to sections of the Zcash -Protocol Specification. 3

-

The terms “Mainnet” and “Testnet” are to be interpreted as described -in § 3.12 ‘Mainnet and Testnet’. 4

-

“ZEC/TAZ” refers to the native currency of Zcash on a given network, -i.e. ZEC on Mainnet and TAZ on Testnet.

-

“Block Subsidy” - The algorithmic issuance of ZEC/TAZ on block -creation, as defined by consensus. This is split between the miner and -Funding Streams.

-

“Issuance” - The method by which ZEC/TAZ becomes available for -circulation on the network. [TODO: there is a potential terminology -conflict between this and issuance as defined in ZIP 227.]

-

“Burning” - The method by which ZEC/TAZ becomes unavailable for -circulation on the network.

-

\(\mathsf{MAX\_MONEY}\), as defined -in § 5.3 ‘Constants’ 5, is the total ZEC/TAZ supply cap -measured in zatoshi, corresponding to 21,000,000 ZEC. This is slightly -larger than the supply cap for the current issuance mechanism, but is -the value used in existing critical consensus checks.

-

Abstract

-

This ZIP proposes the introduction of a mechanism to voluntarily burn -funds, removing those funds entirely from circulation on the network. -This mechanism, in combination with ZIP 234 6 and -ZIP 235 7, comprises a long-term strategy for -the sustainability of the network. We will refer to the combined effects -of these three ZIPs as the “Network Sustainability Mechanism”.

-

Motivation

-

This mechanism seeks to address concerns about the sustainability of -the network design shared by Bitcoin-like systems:

-
    -
  1. Long Term Consensus Sustainability: By enabling the -burning of funds, the network gains the ability to create “headroom” -between the chain value and \(\mathsf{MAX\_MONEY}\). This lays necessary -groundwork for extending the block subsidy system, which currently has a -clear final end date.
    2. -
  2. Benefits to ZEC Holders: Burning funds reduces the -supply of ZEC, benefiting network users in proportion to their holdings -without requiring them to opt into any scheme, introducing extra risk, -active oversight, or accounting complexity.
    3. +Discussions-To: <https://github.com/zcash/zips/issues/922> + + +

    Terminology

    + +

    The key word “MUST” in this document is to be interpreted as described in +BCP 14 1 when, and only when, it appears in all capitals.

    + +

    The term “network upgrade” in this document is to be interpreted as described +in ZIP 200. 2

    + +

    The character § is used when referring to sections of the Zcash Protocol +Specification. 3

    + +

    The terms “Mainnet” and “Testnet” are to be interpreted as described in +§ 3.12 ‘Mainnet and Testnet’. 4

    + +

    “ZEC/TAZ” refers to the native currency of Zcash on a given network, i.e. +ZEC on Mainnet and TAZ on Testnet.

    + +

    “Block Subsidy” - The algorithmic issuance of ZEC/TAZ on block creation, as +defined by consensus. This is split between the miner and Funding Streams.

    + +

    “Issuance” - The method by which ZEC/TAZ becomes available for circulation +on the network. [TODO: there is a potential terminology conflict between +this and issuance as defined in ZIP 227.]

    + +

    “Burning” - The method by which ZEC/TAZ becomes unavailable for circulation +on the network.

    + +

    \(\mathsf{MAX\_MONEY}\), as defined in § 5.3 ‘Constants’ 5, +is the total ZEC/TAZ supply cap measured in zatoshi, corresponding to +21,000,000 ZEC. This is slightly larger than the supply cap for the current +issuance mechanism, but is the value used in existing critical consensus +checks.

    + +

    Abstract

    + +

    This ZIP proposes the introduction of a mechanism to voluntarily burn funds, +removing those funds entirely from circulation on the network. This mechanism, +in combination with ZIP 234 6 and ZIP 235 7, comprises a +long-term strategy for the sustainability of the network. We will refer to the +combined effects of these three ZIPs as the “Network Sustainability Mechanism”.

    + +

    Motivation

    + +

    This mechanism seeks to address concerns about the sustainability of the network +design shared by Bitcoin-like systems:

    + +
      +
    1. Long Term Consensus Sustainability: By enabling the burning of funds, the +network gains the ability to create “headroom” between the chain value and +\(\mathsf{MAX\_MONEY}\). This lays necessary groundwork for extending the +block subsidy system, which currently has a clear final end date.
      2. +
    2. Benefits to ZEC Holders: Burning funds reduces the supply of ZEC, +benefiting network users in proportion to their holdings without requiring +them to opt into any scheme, introducing extra risk, active oversight, or +accounting complexity.
    -

    Specification

    -

    Burn amount

    -

    Each transaction gains a \(\mathsf{burn\_amount}\) property, -specifying the value in zatoshis that is burned when the transaction is -mined. The burned value subtracts from the remaining value in the -“transparent transaction value pool” as described in § 3.4 ‘Transactions -and Treestates’ 8.

    -

    \(\mathsf{burn\_amount}\) does not -result in an output being produced in any chain value pool, and -therefore from the point at which the transaction is applied to the -global chain state, \(\mathsf{burn\_amount}\) is subtracted from -the issued supply. It is unavailable for circulation on the network at -least through to the end of the block in which the transaction is mined. -ZIP 234 9 specifies a potential mechanism by -which the burned funds would again become available.

    -

    Changes to ZIP 230 10

    -

    The following field is appended to the Common Transaction Fields of -the v6 transaction format after nExpiryHeight 11:

    + +

    Specification

    + +

    Burn amount

    + +

    Each transaction gains a \(\mathsf{burn\_amount}\) property, specifying the +value in zatoshis that is burned when the transaction is mined. The burned value +subtracts from the remaining value in the “transparent transaction value pool” +as described in § 3.4 ‘Transactions and Treestates’ 8.

    + +

    \(\mathsf{burn\_amount}\) does not result in an output being produced in any +chain value pool, and therefore from the point at which the transaction is +applied to the global chain state, \(\mathsf{burn\_amount}\) is subtracted from the +issued supply. It is unavailable for circulation on the network at least through +to the end of the block in which the transaction is mined. ZIP 234 6 +specifies a potential mechanism by which the burned funds would again become +available.

    + +

    Changes to ZIP 230 9

    + +

    The following field is appended to the Common Transaction Fields of the v6 +transaction format after nExpiryHeight 10:

    + ----++++ + - - - - + + + + + - - - - + + + +
    BytesNameData TypeDescription Bytes Name Data Type Description
    8burnAmountuint64The value to be burned in this transaction, in zatoshis. 8 burnAmount uint64 The value to be burned in this transaction, in zatoshis.
    -

    The \(\mathsf{burn\_amount}\) of a -transaction is defined to be the value of the burnAmount -field if present, and otherwise 0.

    + +

    The \(\mathsf{burn\_amount}\) of a transaction is defined to be the value of the +burnAmount field if present, and otherwise 0.

    +

    Notes:

    +
      -
    • If both this ZIP and ZIP 2002 are selected for inclusion in the same -Network Upgrade, then the ambiguity in ordering of the fields added by -these ZIPs would need to be resolved.
      • -
    • Older transaction versions can continue to be supported after a -network upgrade, but burning is not possible for these transactions. For -example, NU5 supports both v4 and v5 transaction formats, for both -coinbase and non-coinbase transactions.
      • +
    • If both this ZIP and ZIP 2002 are selected for inclusion in the same Network +Upgrade, then the ambiguity in ordering of the fields added by these ZIPs +would need to be resolved.
      • +
    • Older transaction versions can continue to be supported after a network upgrade, +but burning is not possible for these transactions. For example, NU5 supports +both v4 and v5 transaction formats, for both coinbase and non-coinbase transactions.
    -

    Changes to the -Zcash Protocol Specification

    -

    Make a change to § 3.4 ‘Transactions and Treestates’ 12 -implementing the specification in Burn -amount.

    -

    In § 7.1 ‘Transaction Encoding and Consensus’ 13, -add:

    + +

    Changes to the Zcash Protocol Specification

    + +

    Make a change to § 3.4 ‘Transactions and Treestates’ 8 +implementing the specification in Burn amount.

    + +

    In § 7.1 ‘Transaction Encoding and Consensus’ 11, add:

    +
    -

    [NU7 onward] \(\mathsf{burn\_amount}\) MUST be in the -range \(\{ 0 .. \mathsf{MAX\_MONEY} -\}\).

    +

    [NU7 onward] \(\mathsf{burn\_amount}\) MUST be in the range \(\{ 0 .. \mathsf{MAX\_MONEY} \}\).

    -

    Modifications -relative to ZIP 244 14

    -

    Relative to the sighash algorithm defined in ZIP 244, the sighash -algorithm that applies to v6 transactions differs by appending the -encoding of \(\mathsf{burn\_amount}\) -to the Common Transaction Fields that are the input to the digest in -T.1: header_digest 15:

    + +

    Modifications relative to ZIP 244 12

    + +

    Relative to the sighash algorithm defined in ZIP 244, the sighash algorithm +that applies to v6 transactions differs by appending the encoding of +\(\mathsf{burn\_amount}\) to the Common Transaction Fields that are the input +to the digest in T.1: header_digest 13:

    +
    -
    T.1f: burn_amount (8-byte little-endian burn amount)
    +
     T.1f: burn_amount (8-byte little-endian burn amount)
+
    -

    Note: If both this ZIP and ZIP 2002 are selected for inclusion in the -same Network Upgrade, then the ambiguity in ordering of the fields added -by these ZIPs would need to be resolved.

    -

    Applicability

    + +

    Note: If both this ZIP and ZIP 2002 are selected for inclusion in the same +Network Upgrade, then the ambiguity in ordering of the fields added by these +ZIPs would need to be resolved.

    + +

    Applicability

    +

    All of these changes apply identically to Mainnet and Testnet.

    -

    Rationale

    -

    All technical decisions in this ZIP are balanced between the -necessary robustness of the NSM mechanics, and simplicity of -implementation.

    -

    New transaction field for -burn amount

    -

    An explicit value distinguishes the burned ZEC from the transaction -fee. Explicitness also ensures any arithmetic flaws in any -implementations are more likely to be observed and caught -immediately.

    -

    Deployment

    -

    This ZIP is proposed to activate with Network Upgrade 7. 16

    -

    References

    -
    + +

    Rationale

    + +

    All technical decisions in this ZIP are balanced between the necessary +robustness of the NSM mechanics, and simplicity of implementation.

    + +

    New transaction field for burn amount

    + +

    An explicit value distinguishes the burned ZEC from the transaction fee. +Explicitness also ensures any arithmetic flaws in any implementations are more +likely to be observed and caught immediately.

    + +

    Deployment

    + +

    This ZIP is proposed to activate with Network Upgrade 7. 14

    + +

    References

    + +
      -

    1. 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”↩︎

      2. -

    2. ZIP 200: Network Upgrade -Mechanism↩︎

      3. -

    3. Zcash Protocol -Specification, Version 2024.5.1 [NU6] or later↩︎

      4. -

    4. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and -Testnet↩︎

      5. -

    5. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 5.3: Constants↩︎

      6. -

    6. ZIP 234: Network Sustainability -Mechanism: Issuance Smoothing↩︎

      7. -

    7. ZIP 235: Burn 60% of Transaction -Fees↩︎

      8. -

    8. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 3.4: -Transactions And Treestates↩︎

      9. -

    9. ZIP 234: Network Sustainability -Mechanism: Issuance Smoothing↩︎

      10. -

    10. ZIP 230: Version 6 Transaction -Format↩︎

      11. -

    11. ZIP 230: Version -6 Transaction Format. Section ‘Transaction Format’↩︎

      12. -

    12. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 3.4: -Transactions And Treestates↩︎

      13. -

    13. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 7.1.2 -Transaction Consensus Rules↩︎

      14. -

    14. ZIP 244: Transaction Identifier -Non-Malleability↩︎

      15. -

    15. ZIP 244: -Transaction Identifier Non-Malleability. Section T.1: -header_digest↩︎

      16. -

    16. ZIP 254: Deployment of the NU7 -Network Upgrade↩︎

      17. + +
    17. +

      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”  ↩︎

      +
      18. + +
    18. +

      ZIP 200: Network Upgrade Mechanism  ↩︎

      +
      19. + +
    19. +

      Zcash Protocol Specification, Version 2024.5.1 [NU6] or later  ↩︎

      +
      20. + +
    20. +

      Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and Testnet  ↩︎

      +
      21. + +
    21. +

      Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.3: Constants  ↩︎

      +
      22. + +
    22. +

      ZIP 234: Network Sustainability Mechanism: Issuance Smoothing  ↩︎

      +
      23. + +
    23. +

      ZIP 235: Burn 60% of Transaction Fees  ↩︎

      +
      24. + +
    24. +

      Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.4: Transactions And Treestates  ↩︎

      +
      25. + +
    25. +

      ZIP 230: Version 6 Transaction Format  ↩︎

      +
      26. + +
    26. +

      ZIP 230: Version 6 Transaction Format. Section ‘Transaction Format’  ↩︎

      +
      27. + +
    27. +

      Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 7.1.2 Transaction Consensus Rules  ↩︎

      +
      28. + +
    28. +

      ZIP 244: Transaction Identifier Non-Malleability  ↩︎

      +
      29. + +
    29. +

      ZIP 244: Transaction Identifier Non-Malleability. Section T.1: header_digest  ↩︎

      +
      30. + +
    30. +

      ZIP 254: Deployment of the NU7 Network Upgrade  ↩︎

      +
      31. +
    -
    + diff --git a/rendered/zip-0234.html b/rendered/zip-0234.html index fac4f75ae..7898fb543 100644 --- a/rendered/zip-0234.html +++ b/rendered/zip-0234.html @@ -22,284 +22,299 @@ Category: Consensus Created: 2023-08-23 License: BSD-2-Clause -Discussions-To: <https://github.com/zcash/zips/issues/923> -

    Terminology

    -

    The key word “MUST” in this document is to be interpreted as -described in BCP 14 1 when, and only when, it appears in -all capitals.

    -

    The term “network upgrade” in this document is to be interpreted as -described in ZIP 200. 2

    -

    The character § is used when referring to sections of the Zcash -Protocol Specification. 3

    -

    The terms “Mainnet” and “Testnet” are to be interpreted as described -in § 3.12 ‘Mainnet and Testnet’. 4

    -

    The symbol “\(\,\cdot\,\)” means -multiplication, as described in § 2 ‘Notation’. 5

    -

    “ZEC/TAZ” refers to the native currency of Zcash on a given network, -i.e. ZEC on Mainnet and TAZ on Testnet.

    -

    The terms “Block Subsidy”, “Issuance”, and “Burning” are to be -interpreted as described in ZIP 233. 6

    -

    Let \(\mathsf{PostBlossomHalvingInterval}\) be as -defined in 7.

    -

    \(\mathsf{MAX\_MONEY}\), as defined -in § 5.3 ‘Constants’ 8, is the total ZEC/TAZ supply cap -measured in zatoshi, corresponding to 21,000,000 ZEC. This is slightly -larger than the supply cap for the current issuance mechanism, but is -the value used in existing critical consensus checks.

    -

    “Issued Supply” - The Issued Supply at a given height of a block -chain is the total ZEC/TAZ value in all chain value pool balances at -that height, as calculated by \(\mathsf{IssuedSupply}(\mathsf{height})\) -defined in § 4.17 ‘Chain Value Pool Balances’. 9

    -

    “Money Reserve” - The Money Reserve at a given height of a block -chain is the total ZEC/TAZ value remaining to be issued, as calculated -by \(\mathsf{MAX\_MONEY} - -\mathsf{IssuedSupply}(\mathsf{height})\).

    -

    Abstract

    -

    This ZIP proposes a change to how nodes calculate the block -subsidy.

    -

    Instead of following a step function around the 4-year halving -intervals inherited from Bitcoin, we propose a smooth logarithmic curve, -defined as a fixed portion of the current value of the Money Reserve at -a given block height.

    -

    The new issuance scheme would approximate the current issuance over -4-year intervals, assuming no ZEC/TAZ is burned during that time, and -retains the overall supply cap of MAX_MONEY.

    -

    Motivation

    +Discussions-To: <https://github.com/zcash/zips/issues/923> + + +

    Terminology

    + +

    The key word “MUST” in this document is to be interpreted as described in +BCP 14 1 when, and only when, it appears in all capitals.

    + +

    The term “network upgrade” in this document is to be interpreted as described +in ZIP 200. 2

    + +

    The character § is used when referring to sections of the Zcash Protocol +Specification. 3

    + +

    The terms “Mainnet” and “Testnet” are to be interpreted as described in +§ 3.12 ‘Mainnet and Testnet’. 4

    + +

    The symbol “\(\,\cdot\,\)” means multiplication, as described in § 2 ‘Notation’. +5

    + +

    “ZEC/TAZ” refers to the native currency of Zcash on a given network, i.e. +ZEC on Mainnet and TAZ on Testnet.

    + +

    The terms “Block Subsidy”, “Issuance”, and “Burning” are to be interpreted +as described in ZIP 233. 6

    + +

    Let \(\mathsf{PostBlossomHalvingInterval}\) be as defined in 7.

    + +

    \(\mathsf{MAX\_MONEY}\), as defined in § 5.3 ‘Constants’ 8, +is the total ZEC/TAZ supply cap measured in zatoshi, corresponding to +21,000,000 ZEC. This is slightly larger than the supply cap for the current +issuance mechanism, but is the value used in existing critical consensus +checks.

    + +

    “Issued Supply” - The Issued Supply at a given height of a block chain is +the total ZEC/TAZ value in all chain value pool balances at that height, as +calculated by \(\mathsf{IssuedSupply}(\mathsf{height})\) defined in +§ 4.17 ‘Chain Value Pool Balances’. 9

    + +

    “Money Reserve” - The Money Reserve at a given height of a block chain is +the total ZEC/TAZ value remaining to be issued, as calculated by +\(\mathsf{MAX\_MONEY} - \mathsf{IssuedSupply}(\mathsf{height})\).

    + +

    Abstract

    + +

    This ZIP proposes a change to how nodes calculate the block subsidy.

    + +

    Instead of following a step function around the 4-year halving intervals +inherited from Bitcoin, we propose a smooth logarithmic curve, defined as a +fixed portion of the current value of the Money Reserve at a given block height.

    + +

    The new issuance scheme would approximate the current issuance over 4-year +intervals, assuming no ZEC/TAZ is burned during that time, and retains the +overall supply cap of MAX_MONEY.

    + +

    Motivation

    +

    Key Objectives:

    -
      -
    1. We want to introduce an automated mechanism that allows users of the -network to contribute to the long-term sustainability of the -network.
      2. -
    2. We want to enable ZEC that has been burned to be recreated in the -future to benefit network sustainability.
      3. + +
        +
      1. We want to introduce an automated mechanism that allows users of the network +to contribute to the long-term sustainability of the network.
        2. +
      2. We want to enable ZEC that has been burned to be recreated in the future to +benefit network sustainability.
      3. We want to retain the existing ZEC supply cap of 21 million.
        4. -
      4. We want the issuance rate to remain similar to the historical rate -for Zcash (and before that, Bitcoin).
        5. -
      5. We want issuance to be easy for all network users to understand and -predict.
        6. -
      6. We want the new issuance to activate at a block with as minimal a -delta from the current issuance as possible.
        7. +
      7. We want the issuance rate to remain similar to the historical rate for Zcash +(and before that, Bitcoin).
        8. +
      8. We want issuance to be easy for all network users to understand and predict.
        9. +
      9. We want the new issuance to activate at a block with as minimal a delta from +the current issuance as possible.
      -

      The current Zcash economic model, inherited from Bitcoin, includes a -halving mechanism that dictates the issuance of new coins. While this -has been foundational, halvings can lead to abrupt changes in the rate -of new coins being introduced to the market. Such sudden shifts can -potentially disrupt the network’s economic model, potentially impacting -its security and stability. Furthermore, the halvings schedule is fixed -and does not provide any way to “recycle” funds into future -issuance.

      -

      This new NSM-based issuance scheme solves these problems by ensuring -a more consistent and predictable rate of coin issuance, while -preserving the core aspects of Zcash’s issuance policy and the -21-million-coin cap. At the same time, it introduces the first mechanism -to recreate and distribute ZEC that has been removed from circulation, -as well as unclaimed transaction fees, across future block -subsidies.

      -

      Requirements

      -

      Smoothing the issuance curve is possible using an exponential decay -formula that satisfies the following requirements:

      -
        -
      1. The issuance can be summarized into a reasonably simple -explanation.
        2. + +

        The current Zcash economic model, inherited from Bitcoin, includes a halving +mechanism that dictates the issuance of new coins. While this has been +foundational, halvings can lead to abrupt changes in the rate of new coins +being introduced to the market. Such sudden shifts can potentially disrupt the +network’s economic model, potentially impacting its security and stability. +Furthermore, the halvings schedule is fixed and does not provide any way to +“recycle” funds into future issuance.

        + +

        This new NSM-based issuance scheme solves these problems by ensuring a more +consistent and predictable rate of coin issuance, while preserving the core +aspects of Zcash’s issuance policy and the 21-million-coin cap. At the same +time, it introduces the first mechanism to recreate and distribute ZEC that has +been removed from circulation, as well as unclaimed transaction fees, across +future block subsidies.

        + +

        Requirements

        + +

        Smoothing the issuance curve is possible using an exponential decay formula +that satisfies the following requirements:

        + +
          +
        1. The issuance can be summarized into a reasonably simple explanation.
        2. Block subsidies approximate a continuous function.
          3. -
        3. If the Money Reserve is greater than 0, then the block subsidy must -be non-zero, preventing any final “unmined” zatoshis.
          4. -
        4. For any 4-year period, all paid out block subsidies are -approximately equal to half of the Money Reserve at the beginning of -that 4-year period, if no ZEC is burned during those 4 years.
          5. -
        5. Decrease the short-term impact of the deployment of this ZIP on -block subsidy recipients, and minimize the potential reputation risk to -Zcash of changing the block subsidy amount.
          6. -
        6. The immediate change in issuance when this mechanism activates -should be minimal.
          7. +
        7. If the Money Reserve is greater than 0, then the block subsidy must be +non-zero, preventing any final “unmined” zatoshis.
          8. +
        8. For any 4-year period, all paid out block subsidies are approximately equal +to half of the Money Reserve at the beginning of that 4-year period, if no +ZEC is burned during those 4 years.
          9. +
        9. Decrease the short-term impact of the deployment of this ZIP on block subsidy +recipients, and minimize the potential reputation risk to Zcash of changing +the block subsidy amount.
          10. +
        10. The immediate change in issuance when this mechanism activates should be +minimal.
        -

        Specification

        -

        Parameters

        -

        \(\mathsf{BLOCK\_SUBSIDY\_FRACTION} = 4126 -/ 10\_000\_000\_000 = 0.0000004126\)

        -

        \(\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT} = -\mathsf{TBD}\)

        + +

        Specification

        + +

        Parameters

        + +

        \(\mathsf{BLOCK\_SUBSIDY\_FRACTION} = 4126 / 10\_000\_000\_000 = 0.0000004126\)

        + +

        \(\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT} = \mathsf{TBD}\)

        +

        The block height will be chosen by the following criteria:

        +
        • It is after NU7 activation height.
        • It is calculated to be the lowest height after the second halving at which the NSM issuance would be less than the current BTC-style issuance -neglecting any burnt ZEC (i.e. assuming the amount of ZEC burnt -is exactly 0).
          • +neglecting any burnt ZEC (i.e. assuming the amount of ZEC burnt is +exactly 0).
        -

        This selection is intended to achieve Key Objective 6 while still -being at a constant, predictable height. An alternative would be to have -a dynamic “latch”-style activation, which would calculate the activation -height by testing the “less than” conditional with every block after the -second halving. We prefer the pre-defined constant height parameter, to -give everyone more time certainty at the cost of issuance -level certainty.

        -

        The difference in up-front calculation versus dynamic calculation is -in whether or not burns are accounted for (since future burns cannot be + +

        This selection is intended to achieve Key Objective 6 while still being at +a constant, predictable height. An alternative would be to have a dynamic +“latch”-style activation, which would calculate the activation height by +testing the “less than” conditional with every block after the second halving. +We prefer the pre-defined constant height parameter, to give everyone more +time certainty at the cost of issuance level certainty.

        + +

        The difference in up-front calculation versus dynamic calculation is in +whether or not burns are accounted for (since future burns cannot be calculated up-front). This means with the pre-defined constant parameter -approach, issuance will jump up some amount at activation. This -amount should be equivalent to all ZEC burnt prior to that height times -\(\mathsf{BLOCK\_SUBSIDY\_FRACTION}\). -For example, if a total of 100,000 ZEC were burnt prior to the -pre-defined constant activation height, then at activation the issuance -would be larger than BTC-style issuance by \(100\_000\textsf{ ZEC} \cdot -\mathsf{BLOCK\_SUBSIDY\_FRACTION}\), which we calculate equals -\(0.04126\) ZEC. This example is chosen -to demonstrate that a very large burn amount (much larger than expected) -would elevate issuance by a relatively small amount. For this reason, we -believe a pre-defined constant is a better approach to achieving Key -Objective 6 than a “dynamic latch” logic because it is so much simpler -to implement and reason about.

        -

        \(\mathsf{MoneyReserveAfter}(\mathsf{height}) -=\) The value of the Money Reserve after the specified block -height.

        -

        Issuance Calculation

        -

        At the \(\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT}\), nodes -should switch from the current issuance calculation, to the -following:

        -

        \(\mathsf{BlockSubsidy}(\mathsf{height}) = -\mathsf{ceiling}(\mathsf{BLOCK\_SUBSIDY\_FRACTION} \cdot -\mathsf{MoneyReserveAfter}(\mathsf{height} - 1))\)

        -

        Applicability

        +approach, issuance will jump up some amount at activation. This amount +should be equivalent to all ZEC burnt prior to that height times +\(\mathsf{BLOCK\_SUBSIDY\_FRACTION}\). For example, if a total of 100,000 ZEC +were burnt prior to the pre-defined constant activation height, then at +activation the issuance would be larger than BTC-style issuance by +\(100\_000\textsf{ ZEC} \cdot \mathsf{BLOCK\_SUBSIDY\_FRACTION}\), +which we calculate equals \(0.04126\) ZEC. This example is chosen to +demonstrate that a very large burn amount (much larger than expected) would +elevate issuance by a relatively small amount. For this reason, we believe +a pre-defined constant is a better approach to achieving Key Objective 6 +than a “dynamic latch” logic because it is so much simpler to implement +and reason about.

        + +

        \(\mathsf{MoneyReserveAfter}(\mathsf{height}) =\) The value of the Money Reserve +after the specified block height.

        + +

        Issuance Calculation

        + +

        At the \(\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT}\), nodes should switch from the current issuance +calculation, to the following:

        + +

        \(\mathsf{BlockSubsidy}(\mathsf{height}) = \mathsf{ceiling}(\mathsf{BLOCK\_SUBSIDY\_FRACTION} \cdot \mathsf{MoneyReserveAfter}(\mathsf{height} - 1))\)

        + +

        Applicability

        +

        All of these changes apply identically to Mainnet and Testnet.

        -

        Rationale

        + +

        Rationale

        +
          -
        • Using an exponential decay function satisfies Requirements -1 and 2 above.
          • -
        • We round up to the next zatoshi to satisfy Requirement -3 above.
          • +
        • Using an exponential decay function satisfies Requirements 1 and 2 above.
          • +
        • We round up to the next zatoshi to satisfy Requirement 3 above.
        -

        BLOCK_SUBSIDY_FRACTION

        -

        Let \(\mathsf{IntendedMoneyReserveFractionRemainingAfterFourYears} -= 0.5\).

        -

        The value \(4126 / -10\_000\_000\_000\) satisfies the approximation within \(\pm 0.002\%\):

        -

        \((1 - -\mathsf{BLOCK\_SUBSIDY\_FRACTION})^\mathsf{PostBlossomHalvingInterval} -\approx -\mathsf{IntendedMoneyReserveFractionRemainingAfterFourYears}\)

        -

        This implies that after a period of 4 years around half of Money -Reserve will have been issued as block subsidies, thus satisfying -Requirement 4.

        -

        The largest possible value in the Money Reserve is \(\mathsf{MAX\_MONEY}\), in the theoretically -possible case that all issued funds are burned. If this happened, the -largest interim sum in the block subsidy calculation would be \(\mathsf{MAX\_MONEY} \cdot 4126 / -10\_000\_000\_000\).

        + +

        BLOCK_SUBSIDY_FRACTION

        + +

        Let \(\mathsf{IntendedMoneyReserveFractionRemainingAfterFourYears} = 0.5\).

        + +

        The value \(4126 / 10\_000\_000\_000\) satisfies the approximation within \(\pm 0.002\%\):

        + +

        \((1 - \mathsf{BLOCK\_SUBSIDY\_FRACTION})^\mathsf{PostBlossomHalvingInterval} \approx \mathsf{IntendedMoneyReserveFractionRemainingAfterFourYears}\)

        + +

        This implies that after a period of 4 years around half of Money Reserve will +have been issued as block subsidies, thus satisfying Requirement 4.

        + +

        The largest possible value in the Money Reserve is \(\mathsf{MAX\_MONEY}\), in the +theoretically possible case that all issued funds are burned. If this happened, +the largest interim sum in the block subsidy calculation would be +\(\mathsf{MAX\_MONEY} \cdot 4126 / 10\_000\_000\_000\).

        +

        This uses 62.91 bits, which is just under the 63-bit limit for signed -two’s complement 64-bit integer amount types.

        +two’s complement 64-bit integer amount types.

        +

        The numerator could be brought closer to the limit by using a larger -denominator, but the difference in the amount issued would be very -small. So we chose a power-of-10 denominator for simplicity.

        +denominator, but the difference in the amount issued would be very small. So we +chose a power-of-10 denominator for simplicity.

        +

        TODO for ZIP owners: How many ZEC per day?

        -

        Visualization of the -Smoothed Curve

        -

        The following graph compares issuance for the current halving-based -step function vs the smoothed curve.

        + +

        Visualization of the Smoothed Curve

        + +

        The following graph compares issuance for the current halving-based step +function vs the smoothed curve.

        +
        - - +A graph showing a comparison of the halving-based step function vs the smoothed curve +
        A graph showing a comparison of the halving-based step function vs the smoothed curve
        -

        The graph below shows the balance of the Money Reserve assuming -smooth issuance is implemented.

        + +

        The graph below shows the balance of the Money Reserve assuming smooth issuance +is implemented.

        +
        - - +A graph showing the balance of the Money Reserve assuming smooth issuance is implemented +
        A graph showing the balance of the Money Reserve assuming smooth issuance is implemented
        -

        Appendix: Simulation

        -

        The NSM -Simulator allows us to simulate the effects of this ZIP on the Money -Reserve and the block subsidy, as well as generate plots like the ones -above. Its output:

        -
        Last block is 47917869 in ~113.88 years
        -

        indicates that, assuming that no ZEC is ever burned, the Money -Reserve will be depleted after 113.88 years, and the block subsidy will -be 0 ZEC after that point.

        + +

        Appendix: Simulation

        + +

        The NSM Simulator allows us to +simulate the effects of this ZIP on the Money Reserve and the block subsidy, as +well as generate plots like the ones above. Its output:

        + +
        Last block is 47917869 in ~113.88 years
+
        + +

        indicates that, assuming that no ZEC is ever burned, the Money Reserve will be +depleted after 113.88 years, and the block subsidy will be 0 ZEC after that +point.

        +

        This fragment of the output:

        + 
        Halving  1 at block  1680000:
   NSM subsidies:    262523884819889 (~ 2625238.848 ZEC,        1.563 ZEC per block)
   legacy subsidies: 262500000000000 (~ 2625000.000 ZEC,        1.562 ZEC per block)
-  difference:           23884819889 (~         238 ZEC),         NSM/legacy: 1.0001
        -

        shows that the difference between the smoothed out and the current -issuance schemes is 238 ZEC after 1680000 blocks (around 4 years).

        -

        Appendix: Considerations -for the Future

        -

        Future protocol changes may not increase the payout rate to a -reasonable approximation beyond the four year half-life constraint.

        -

        Deployment

        -

        This ZIP is proposed to activate with Network Upgrade 7. 10 It MUST be deployed at the same -time or after ZIP 233 (“NSM: Burning” 11).

        -

        References

        -
        + difference: 23884819889 (~ 238 ZEC), NSM/legacy: 1.0001 + + +

        shows that the difference between the smoothed out and the current issuance +schemes is 238 ZEC after 1680000 blocks (around 4 years).

        + +

        Appendix: Considerations for the Future

        + +

        Future protocol changes may not increase the payout rate to a reasonable +approximation beyond the four year half-life constraint.

        + +

        Deployment

        + +

        This ZIP is proposed to activate with Network Upgrade 7. 10 +It MUST be deployed at the same time or after ZIP 233 (“NSM: Burning” 6).

        + +

        References

        + +
          -

        1. 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”↩︎

          2. -

        2. ZIP 200: Network Upgrade -Mechanism↩︎

          3. -

        3. Zcash Protocol -Specification, Version 2024.5.1 [NU6] or later↩︎

          4. -

        4. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and -Testnet↩︎

          5. -

        5. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 2: Notation↩︎

          6. -

        6. ZIP 233: Network Sustainability -Mechanism: Burning↩︎

          7. -

        7. Zcash -Protocol Specification, Version 2024.5.1 [NU6]. Section 7.7.3 Difficulty -Adjustment↩︎

          8. -

        8. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 5.3: Constants↩︎

          9. -

        9. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 4.17 Chain Value Pool -Balances↩︎

          10. -

        10. ZIP 254: Deployment of the NU7 -Network Upgrade↩︎

          11. -

        11. ZIP 233: Network Sustainability -Mechanism: Burning↩︎

          12. + +
        12. +

          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”  ↩︎

          +
          13. + +
        13. +

          ZIP 200: Network Upgrade Mechanism  ↩︎

          +
          14. + +
        14. +

          Zcash Protocol Specification, Version 2024.5.1 [NU6] or later  ↩︎

          +
          15. + +
        15. +

          Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and Testnet  ↩︎

          +
          16. + +
        16. +

          Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 2: Notation  ↩︎

          +
          17. + +
        17. +

          ZIP 233: Network Sustainability Mechanism: Burning  ↩︎

          +
          18. + +
        18. +

          Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 7.7.3 Difficulty Adjustment  ↩︎

          +
          19. + +
        19. +

          Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.3: Constants  ↩︎

          +
          20. + +
        20. +

          Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.17 Chain Value Pool Balances  ↩︎

          +
          21. + +
        21. +

          ZIP 254: Deployment of the NU7 Network Upgrade  ↩︎

          +
          22. +
        -
        + diff --git a/rendered/zip-0235.html b/rendered/zip-0235.html index 07a86bd7d..c893b8541 100644 --- a/rendered/zip-0235.html +++ b/rendered/zip-0235.html @@ -22,141 +22,146 @@ Category: Ecosystem Created: 2023-09-21 License: BSD-2-Clause -Discussions-To: <https://github.com/zcash/zips/issues/924> -

        Terminology

        -

        The key word “MUST” in this document is to be interpreted as -described in BCP 14 1 when, and only when, it appears in -all capitals.

        -

        The term “network upgrade” in this document is to be interpreted as -described in ZIP 200. 2

        -

        The character § is used when referring to sections of the Zcash -Protocol Specification. 3

        -

        The terms “Mainnet” and “Testnet” are to be interpreted as described -in § 3.12 ‘Mainnet and Testnet’. 4

        -

        The symbol “\(\,\cdot\,\)” means -multiplication, as described in § 2 ‘Notation’. 5

        -

        “ZEC/TAZ” refers to the native currency of Zcash on a given network, -i.e. ZEC on Mainnet and TAZ on Testnet.

        -

        The terms “Block Subsidy”, “Issuance”, and “Burning” are to be -interpreted as described in ZIP 233. 6

        -

        Abstract

        -

        This ZIP proposes to burn 60% of transaction fees, while the -remaining 40% is directed as before, providing a deflationary effect, -and building the groundwork for long-term support of the Zcash network -via the new block subsidy rules proposed by ZIP 234 7.

        -

        Motivation

        -

        ZIP 233 (“Network Sustainability Mechanism: Burning” 8) -describes a method by which ZEC can be burned to support network -sustainability.

        -

        By introducing a requirement that a certain proportion of transaction -fees be burned, we ensure that ZEC will be removed from circulating -supply to contribute to the long-term sustainability of the network as -described below:

        -

        Benefits to the Network

        -
          -
        1. Network Sustainability: This mechanism involves -temporarily reducing the supply of ZEC, similar to asset burning in -Ethereum’s EIP-1559 9, but with long-term sustainability -benefits, as the burned funds effectively boost future mining rewards, -making it an attractive option for current and future Zcash users.
          2. -
        2. Incentivizing Transaction Inclusion: By maintaining -a 40% share of transaction fees for miners, we continue incentivizing -miners to prioritize including transactions in their blocks. This helps -ensure the continued efficient processing of transactions and supports a -robust and responsive network.
          3. -
        3. Aligning Interests: Burning transaction fees aligns -the interests of miners with the long-term health of the network, -incentivizing them to prioritize security and efficiency. As miners -focus on maintaining a robust network, overall adoption and usage can -increase, leading to higher transaction volumes in the long run. This -structure discourages short-term profit-seeking behaviors, as miners -benefit more from a stable and thriving ecosystem than from engaging in -malicious activities that could undermine the network’s reputation and -security.
          4. -
        4. Future-Proofing the Network: Burning a portion of -transaction fees is a forward-looking approach that prepares the Zcash -network for future challenges and opportunities. It establishes a -financial buffer that can be instrumental in addressing unforeseen -issues and seizing strategic advantages as the Zcash ecosystem -evolves.
          5. +Discussions-To: <https://github.com/zcash/zips/issues/924> + + +

          Terminology

          + +

          The key word “MUST” in this document is to be interpreted as described in +BCP 14 1 when, and only when, it appears in all capitals.

          + +

          The term “network upgrade” in this document is to be interpreted as described +in ZIP 200. 2

          + +

          The character § is used when referring to sections of the Zcash Protocol +Specification. 3

          + +

          The terms “Mainnet” and “Testnet” are to be interpreted as described in +§ 3.12 ‘Mainnet and Testnet’. 4

          + +

          The symbol “\(\,\cdot\,\)” means multiplication, as described in § 2 ‘Notation’. +5

          + +

          “ZEC/TAZ” refers to the native currency of Zcash on a given network, i.e. +ZEC on Mainnet and TAZ on Testnet.

          + +

          The terms “Block Subsidy”, “Issuance”, and “Burning” are to be interpreted +as described in ZIP 233. 6

          + +

          Abstract

          + +

          This ZIP proposes to burn 60% of transaction fees, while the remaining 40% is +directed as before, providing a deflationary effect, and building the groundwork +for long-term support of the Zcash network via the new block subsidy rules +proposed by ZIP 234 7.

          + +

          Motivation

          + +

          ZIP 233 (“Network Sustainability Mechanism: Burning” 6) describes a +method by which ZEC can be burned to support network sustainability.

          + +

          By introducing a requirement that a certain proportion of transaction fees be +burned, we ensure that ZEC will be removed from circulating supply to contribute +to the long-term sustainability of the network as described below:

          + +

          Benefits to the Network

          + +
            +
          1. Network Sustainability: This mechanism involves temporarily reducing the +supply of ZEC, similar to asset burning in Ethereum’s EIP-1559 8, +but with long-term sustainability benefits, as the burned funds effectively +boost future mining rewards, making it an attractive option for current and +future Zcash users.
            2. +
          2. Incentivizing Transaction Inclusion: By maintaining a 40% share of +transaction fees for miners, we continue incentivizing miners to prioritize +including transactions in their blocks. This helps ensure the continued +efficient processing of transactions and supports a robust and responsive +network.
            3. +
          3. Aligning Interests: Burning transaction fees aligns the interests +of miners with the long-term health of the network, incentivizing them +to prioritize security and efficiency. As miners focus on maintaining a +robust network, overall adoption and usage can increase, leading to higher +transaction volumes in the long run. This structure discourages short-term +profit-seeking behaviors, as miners benefit more from a stable and thriving +ecosystem than from engaging in malicious activities that could undermine the +network’s reputation and security.
            4. +
          4. Future-Proofing the Network: Burning a portion of transaction fees +is a forward-looking approach that prepares the Zcash network for future +challenges and opportunities. It establishes a financial buffer that can be +instrumental in addressing unforeseen issues and seizing strategic advantages +as the Zcash ecosystem evolves.
          -

          Requirements

          + +

          Requirements

          +
            -
          • For each block, at least 60% (rounded down) of the total fees are to -be burned.
            • -
          • No restrictions are placed on the destination of the remaining -proportion of fees.
            • +
          • For each block, at least 60% (rounded down) of the total fees are to be +burned.
            • +
          • No restrictions are placed on the destination of the remaining proportion of +fees.
          • Any fractions are rounded in favor of the miner.
          -

          Specification

          -

          Consensus Rule Changes

          -

          For a given block, the coinbase transaction MUST have a \(\mathsf{burn\_amount}\), as defined in 10, that is greater than or equal to -\(\mathsf{floor}(\mathsf{transactionFees} -\cdot 6 / 10)\).

          -

          The version of a coinbase transaction MUST be v6 or later 11.

          -

          Applicability

          + +

          Specification

          + +

          Consensus Rule Changes

          + +

          For a given block, the coinbase transaction MUST have a \(\mathsf{burn\_amount}\), +as defined in 6, that is greater than or equal to +\(\mathsf{floor}(\mathsf{transactionFees} \cdot 6 / 10)\).

          + +

          The version of a coinbase transaction MUST be v6 or later 9.

          + +

          Applicability

          +

          All of these changes apply identically to Mainnet and Testnet.

          -

          Rationale

          -

          We believe the proposed changes to be relatively low-impact in terms -of implementation and protocol changes. Additionally, transaction fees -are currently small enough that the reduction in miner fees is unlikely -to be a concern.

          -

          Rationale -for requiring the coinbase transaction to be v6 or later

          -

          There is no explicit mechanism in prior transaction versions to burn -the required funds. Since \(\mathsf{burn\_amount} = 0\) for transaction -versions prior to v6, absent the rule about the coinbase transaction -version it would be technically possible to satisfy the constraint on -\(\mathsf{burn\_amount}\) with earlier -versions than v6, but only when \(\mathsf{transactionFees} = 0\). That would -introduce a corner case in the transaction consensus rules that is not -useful, since it is expected that the \(\mathsf{transactionFees}\) will normally be -non-zero.

          -

          Estimated impact on miners

          -

          Over 100,000 blocks starting at block 2235515, there were 316130 -transactions. 60608 of them are categorized as ‘sandblasting’ -transactions. The remaining transactions have an average of 5.46 logical -actions (see ZIP 317 12).

          -

          The total fees paid to miners from those transactions, assuming the -ZIP 317 regime, would be 87.86 ZEC. 100,000 blocks is approximately 3 -months of blocks. Extrapolating to a year, we would expect 351.44 ZEC in -fees paid to miners over a year.

          -

          If 60% of these fees burned, that would be 210.864 ZEC per year. 13

          -

          Considerations for the -Future

          -

          If transaction fees were to increase, further modifications can -easily be proposed to alter the 60%/40% split. Finding the optimal fee -split may require an iterative approach involving adjustments based on -real-world data and network dynamics.

          -

          Looking further into the future, there may come a time when the -transaction fees become greater than the block subsidy issuance. At that -time we may need to reconsider the 60/40 split. However, this will -likely not be the case for the next 8-10 years due to forecasts based on -issuance models and network traffic.

          -

          Further ZIPs may be proposed to burn ZEC in various ways to support -network sustainability, including but not limited to:

          + +

          Rationale

          + +

          We believe the proposed changes to be relatively low-impact in terms of +implementation and protocol changes. Additionally, transaction fees are +currently small enough that the reduction in miner fees is unlikely to be a +concern.

          + +

          Rationale for requiring the coinbase transaction to be v6 or later

          + +

          There is no explicit mechanism in prior transaction versions to burn the +required funds. Since \(\mathsf{burn\_amount} = 0\) for transaction versions +prior to v6, absent the rule about the coinbase transaction version it +would be technically possible to satisfy the constraint on \(\mathsf{burn\_amount}\) +with earlier versions than v6, but only when \(\mathsf{transactionFees} = 0\). +That would introduce a corner case in the transaction consensus rules that +is not useful, since it is expected that the \(\mathsf{transactionFees}\) +will normally be non-zero.

          + +

          Estimated impact on miners

          + +

          Over 100,000 blocks starting at block 2235515, there were 316130 transactions. +60608 of them are categorized as ‘sandblasting’ transactions. The remaining +transactions have an average of 5.46 logical actions (see ZIP 317 10).

          + +

          The total fees paid to miners from those transactions, assuming the ZIP 317 +regime, would be 87.86 ZEC. 100,000 blocks is approximately 3 months of blocks. +Extrapolating to a year, we would expect 351.44 ZEC in fees paid to miners over +a year.

          + +

          If 60% of these fees burned, that would be 210.864 ZEC per year. 11

          + +

          Considerations for the Future

          + +

          If transaction fees were to increase, further modifications can easily be +proposed to alter the 60%/40% split. Finding the optimal fee split may require +an iterative approach involving adjustments based on real-world data and network +dynamics.

          + +

          Looking further into the future, there may come a time when the transaction fees +become greater than the block subsidy issuance. At that time we may need to +reconsider the 60/40 split. However, this will likely not be the case for the +next 8–10 years due to forecasts based on issuance models and network traffic.

          + +

          Further ZIPs may be proposed to burn ZEC in various ways to support network +sustainability, including but not limited to:

          +
          • ZSA fees
          • Fees and donations specific to decentralized applications
            • @@ -164,69 +169,64 @@

            Considerations for the
          • Cross-chain bridge usage / Cross-chain messaging
          • Note sorting micro-transactional fees

          -

          Deployment

          -

          The implementation of this ZIP MUST be deployed at the same time or -after ZIP 233 (“NSM: Burning” 14), and ZIP 234 (“NSM: -Issuance Smoothing” 15).

          -

          References

          -
          + +

          Deployment

          + +

          The implementation of this ZIP MUST be deployed at the same time or after +ZIP 233 (“NSM: Burning” 6), and ZIP 234 (“NSM: Issuance Smoothing” +7).

          + +

          References

          + +
            -

          1. 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”↩︎

            2. -

          2. ZIP 200: Network Upgrade -Mechanism↩︎

            3. -

          3. Zcash Protocol -Specification, Version 2024.5.1 [NU6] or later↩︎

            4. -

          4. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and -Testnet↩︎

            5. -

          5. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 2: Notation↩︎

            6. -

          6. ZIP 233: Network Sustainability -Mechanism: Burning↩︎

            7. -

          7. ZIP 234: Network Sustainability -Mechanism: Issuance Smoothing↩︎

            8. -

          8. ZIP 233: Network Sustainability -Mechanism: Burning↩︎

            9. -

          9. EIP-1559: Fee market -change for ETH 1.0 chain↩︎

            10. -

          10. ZIP 233: Network Sustainability -Mechanism: Burning↩︎

            11. -

          11. ZIP 230: Version 6 Transaction -Format↩︎

            12. -

          12. ZIP 317: Proportional Transfer -Fee Mechanism↩︎

            13. -

          13. GitHub repository -eigerco/zsf-fee-estimator↩︎

            14. -

          14. ZIP 233: Network Sustainability -Mechanism: Burning↩︎

            15. -

          15. ZIP 234: Network Sustainability -Mechanism: Issuance Smoothing↩︎

            16. + +
          16. +

            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”  ↩︎

            +
            17. + +
          17. +

            ZIP 200: Network Upgrade Mechanism  ↩︎

            +
            18. + +
          18. +

            Zcash Protocol Specification, Version 2024.5.1 [NU6] or later  ↩︎

            +
            19. + +
          19. +

            Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and Testnet  ↩︎

            +
            20. + +
          20. +

            Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 2: Notation  ↩︎

            +
            21. + +
          21. +

            ZIP 233: Network Sustainability Mechanism: Burning  ↩︎

            +
            22. + +
          22. +

            ZIP 234: Network Sustainability Mechanism: Issuance Smoothing  ↩︎

            +
            23. + +
          23. +

            EIP-1559: Fee market change for ETH 1.0 chain  ↩︎

            +
            24. + +
          24. +

            ZIP 230: Version 6 Transaction Format  ↩︎

            +
            25. + +
          25. +

            ZIP 317: Proportional Transfer Fee Mechanism  ↩︎

            +
            26. + +
          26. +

            GitHub repository eigerco/zsf-fee-estimator  ↩︎

            +
            27. +
          -
          + diff --git a/rendered/zip-0253.html b/rendered/zip-0253.html index 49a248e2f..1c4dadbae 100644 --- a/rendered/zip-0253.html +++ b/rendered/zip-0253.html @@ -13,139 +13,120 @@ Category: Consensus / Network Created: 2024-07-17 License: MIT -Discussions-To: <https://github.com/zcash/zips/issues/806> -

          Terminology

          -

          The key word “MUST” in this document are to be interpreted as -described in BCP 14 1 when, and only when, they appear in -all capitals.

          -

          The term “network upgrade” in this document is to be interpreted as -described in ZIP 200 2.

          -

          The terms “Testnet” and “Mainnet” are to be interpreted as described -in section 3.12 of the Zcash Protocol Specification 3.

          -

          Abstract

          +Discussions-To: <https://github.com/zcash/zips/issues/806> + + +

          Terminology

          + +

          The key word “MUST” in this document are to be interpreted as described in +BCP 14 1 when, and only when, they appear in all capitals.

          + +

          The term “network upgrade” in this document is to be interpreted as described in ZIP 200 2.

          + +

          The terms “Testnet” and “Mainnet” are to be interpreted as described in +section 3.12 of the Zcash Protocol Specification 3.

          + +

          Abstract

          +

          This proposal defines the deployment of the NU6 network upgrade.

          -

          Specification

          -

          NU6 deployment

          -

          The primary sources of information about NU6 consensus protocol -changes are:

          + +

          Specification

          + +

          NU6 deployment

          + +

          The primary sources of information about NU6 consensus protocol changes are:

          +
            -
          • The Zcash Protocol Specification 4.
            • -
          • ZIP 200: Network Upgrade Mechanism 5.
            • -
          • ZIP 236: Blocks should balance exactly 6.
            • -
          • ZIP 1015: Block Reward Allocation for Non-Direct Development Funding -7.
            • -
          • ZIP 2001: Lockbox Funding Streams 8.
            • +
          • The Zcash Protocol Specification 4.
            • +
          • ZIP 200: Network Upgrade Mechanism 2.
            • +
          • ZIP 236: Blocks should balance exactly 5.
            • +
          • ZIP 1015: Block Reward Allocation for Non-Direct Development Funding 6.
            • +
          • ZIP 2001: Lockbox Funding Streams 7.
          -

          The network handshake and peer management mechanisms defined in ZIP -201 9 also apply to this upgrade.

          -

          The following ZIPs have been updated in varying degrees to take into -account NU6:

          + +

          The network handshake and peer management mechanisms defined in ZIP 201 8 also apply to this upgrade.

          + +

          The following ZIPs have been updated in varying degrees to take into account NU6:

          +
            -
          • ZIP 207: Funding Streams 10.
            • -
          • ZIP 214: Consensus rules for a Zcash Development Fund 11.
            • +
          • ZIP 207: Funding Streams 9.
            • +
          • ZIP 214: Consensus rules for a Zcash Development Fund 10.
          -

          The following network upgrade constants 12 -are defined for the NU6 upgrade:

          + +

          The following network upgrade constants 2 are defined for the NU6 upgrade:

          +
          CONSENSUS_BRANCH_ID
          -
          -0xC8E71055 -
          +
          0xC8E71055
          +
          ACTIVATION_HEIGHT (NU6)
          -
          -Testnet: 2976000 -
          -
          -Mainnet: 2726400 -
          +
          Testnet: 2976000
          + +
          Mainnet: 2726400
          +
          MIN_NETWORK_PROTOCOL_VERSION (NU6)
          -
          -Testnet: 170110 -
          -
          -Mainnet: 170120 -
          +
          Testnet: 170110
          + +
          Mainnet: 170120
          -

          For each network (Testnet and Mainnet), nodes compatible with NU6 -activation on that network MUST advertise a network protocol version -that is greater than or equal to the MIN_NETWORK_PROTOCOL_VERSION (NU6) -for that activation.

          -

          Backward compatibility

          -

          Prior to the network upgrade activating on each network, NU6 and -pre-NU6 nodes are compatible and can connect to each other. However, NU6 -nodes will have a preference for connecting to other NU6 nodes, so -pre-NU6 nodes will gradually be disconnected in the run up to -activation.

          -

          Once the network upgrades, even though pre-NU6 nodes can still accept -the numerically larger protocol version used by NU6 as being valid, NU6 -nodes will always disconnect peers using lower protocol versions.

          -

          NU6 does not define a new transaction version or impose a new minimum -transaction version. NU6 transactions are therefore in the same v4 or v5 -formats as NU5 transactions. This does not imply that transactions are -valid across the NU6 activation, since signatures MUST use the -appropriate consensus branch ID.

          -

          References

          -
          + +

          For each network (Testnet and Mainnet), nodes compatible with NU6 activation on that network MUST advertise a network protocol version that is greater than or equal to the MIN_NETWORK_PROTOCOL_VERSION (NU6) for that activation.

          + +

          Backward compatibility

          + +

          Prior to the network upgrade activating on each network, NU6 and pre-NU6 nodes are compatible and can connect to each other. However, NU6 nodes will have a preference for connecting to other NU6 nodes, so pre-NU6 nodes will gradually be disconnected in the run up to activation.

          + +

          Once the network upgrades, even though pre-NU6 nodes can still accept the numerically larger protocol version used by NU6 as being valid, NU6 nodes will always disconnect peers using lower protocol versions.

          + +

          NU6 does not define a new transaction version or impose a new minimum transaction version. NU6 transactions are therefore in the same v4 or v5 formats as NU5 transactions. This does not imply that transactions are valid across the NU6 activation, since signatures MUST use the appropriate consensus branch ID.

          + +

          References

          + +
            -

          1. 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”↩︎

            2. -

          2. ZIP 200: Network Upgrade -Mechanism↩︎

            3. -

          3. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and -Testnet↩︎

            4. -

          4. Zcash Protocol -Specification, Version 2024.5.1 or later↩︎

            5. -

          5. ZIP 200: Network Upgrade -Mechanism↩︎

            6. -

          6. ZIP 236: Blocks should balance -exactly↩︎

            7. -

          7. ZIP 1015: Block Reward Allocation -for Non-Direct Development Funding↩︎

            8. -

          8. ZIP 2001: Lockbox Funding -Streams↩︎

            9. -

          9. ZIP 201: Network Peer Management -for Overwinter↩︎

            10. -

          10. ZIP 207: Funding Streams↩︎

            11. -

          11. ZIP 214: Consensus rules for a -Zcash Development Fund↩︎

            12. -

          12. ZIP 200: Network Upgrade -Mechanism↩︎

            13. + +
          13. +

            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”  ↩︎

            +
            14. + +
          14. +

            ZIP 200: Network Upgrade Mechanism  ↩︎

            +
            15. + +
          15. +

            Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and Testnet  ↩︎

            +
            16. + +
          16. +

            Zcash Protocol Specification, Version 2024.5.1 or later  ↩︎

            +
            17. + +
          17. +

            ZIP 236: Blocks should balance exactly  ↩︎

            +
            18. + +
          18. +

            ZIP 1015: Block Reward Allocation for Non-Direct Development Funding  ↩︎

            +
            19. + +
          19. +

            ZIP 2001: Lockbox Funding Streams  ↩︎

            +
            20. + +
          20. +

            ZIP 201: Network Peer Management for Overwinter  ↩︎

            +
            21. + +
          21. +

            ZIP 207: Funding Streams  ↩︎

            +
            22. + +
          22. +

            ZIP 214: Consensus rules for a Zcash Development Fund  ↩︎

            +
            23. +
          -
          + diff --git a/rendered/zip-0254.html b/rendered/zip-0254.html index 4a7091e92..8e33af549 100644 --- a/rendered/zip-0254.html +++ b/rendered/zip-0254.html @@ -13,107 +13,101 @@ Category: Consensus / Network Created: 2024-10-31 License: MIT -Discussions-To: <https://github.com/zcash/zips/issues/839> -

          Terminology

          -

          The key word “MUST” in this document is to be interpreted as -described in BCP 14 1 when, and only when, it appears in -all capitals.

          -

          The term “network upgrade” in this document is to be interpreted as -described in ZIP 200. 2

          -

          The character § is used when referring to sections of the Zcash -Protocol Specification. 3

          -

          The terms “Mainnet” and “Testnet” are to be interpreted as described -in § 3.12 ‘Mainnet and Testnet’. 4

          -

          Abstract

          +Discussions-To: <https://github.com/zcash/zips/issues/839> + + +

          Terminology

          + +

          The key word “MUST” in this document is to be interpreted as described in +BCP 14 1 when, and only when, it appears in all capitals.

          + +

          The term “network upgrade” in this document is to be interpreted as described +in ZIP 200. 2

          + +

          The character § is used when referring to sections of the Zcash Protocol +Specification. 3

          + +

          The terms “Mainnet” and “Testnet” are to be interpreted as described in +§ 3.12 ‘Mainnet and Testnet’. 4

          + +

          Abstract

          +

          This proposal defines the deployment of the NU7 network upgrade.

          -

          Specification

          -

          NU7 deployment

          -

          The primary sources of information about NU7 consensus protocol -changes are:

          + +

          Specification

          + +

          NU7 deployment

          + +

          The primary sources of information about NU7 consensus protocol changes are:

          +
            -
          • The Zcash Protocol Specification 5.
            • -
          • ZIP 200: Network Upgrade Mechanism 6.
            • +
          • The Zcash Protocol Specification 3.
            • +
          • ZIP 200: Network Upgrade Mechanism 2.
          -

          The network handshake and peer management mechanisms defined in ZIP -201 7 also apply to this upgrade.

          -

          The following network upgrade constants 8 are -defined for the NU7 upgrade:

          + +

          The network handshake and peer management mechanisms defined in ZIP 201 +5 also apply to this upgrade.

          + +

          The following network upgrade constants 2 are defined for the +NU7 upgrade:

          +
          CONSENSUS_BRANCH_ID
          -
          -0x77190AD8 -
          +
          0x77190AD8
          +
          ACTIVATION_HEIGHT (NU7)
          -
          -Testnet: TBD -
          -
          -Mainnet: TBD -
          +
          Testnet: TBD
          + +
          Mainnet: TBD
          +
          MIN_NETWORK_PROTOCOL_VERSION (NU7)
          -
          -Testnet: 170130 -
          -
          -Mainnet: 170140 -
          +
          Testnet: 170130
          + +
          Mainnet: 170140
          -

          For each network (Testnet and Mainnet), nodes compatible with NU7 -activation on that network MUST advertise a network protocol version -that is greater than or equal to the MIN_NETWORK_PROTOCOL_VERSION (NU7) -for that activation.

          -

          Backward compatibility

          -

          Prior to the network upgrade activating on each network, NU7 and -pre-NU7 nodes are compatible and can connect to each other. However, NU7 -nodes will have a preference for connecting to other NU7 nodes, so -pre-NU7 nodes will gradually be disconnected in the run up to -activation.

          -

          Once the network upgrades, even though pre-NU7 nodes can still accept -the numerically larger protocol version used by NU7 as being valid, NU7 -nodes will always disconnect peers using lower protocol versions.

          -

          References

          -
          + +

          For each network (Testnet and Mainnet), nodes compatible with NU7 activation +on that network MUST advertise a network protocol version that is greater +than or equal to the MIN_NETWORK_PROTOCOL_VERSION (NU7) for that activation.

          + +

          Backward compatibility

          + +

          Prior to the network upgrade activating on each network, NU7 and pre-NU7 +nodes are compatible and can connect to each other. However, NU7 nodes will +have a preference for connecting to other NU7 nodes, so pre-NU7 nodes will +gradually be disconnected in the run up to activation.

          + +

          Once the network upgrades, even though pre-NU7 nodes can still accept the +numerically larger protocol version used by NU7 as being valid, NU7 nodes +will always disconnect peers using lower protocol versions.

          + +

          References

          + +
            -

          1. 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”↩︎

            2. -

          2. ZIP 200: Network Upgrade -Mechanism↩︎

            3. -

          3. Zcash Protocol -Specification, Version 2024.5.1 or later↩︎

            4. -

          4. Zcash Protocol -Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and -Testnet↩︎

            5. -

          5. Zcash Protocol -Specification, Version 2024.5.1 or later↩︎

            6. -

          6. ZIP 200: Network Upgrade -Mechanism↩︎

            7. -

          7. ZIP 201: Network Peer Management -for Overwinter↩︎

            8. -

          8. ZIP 200: Network Upgrade -Mechanism↩︎

            9. + +
          9. +

            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”  ↩︎

            +
            10. + +
          10. +

            ZIP 200: Network Upgrade Mechanism  ↩︎

            +
            11. + +
          11. +

            Zcash Protocol Specification, Version 2024.5.1 or later  ↩︎

            +
            12. + +
          12. +

            Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.12: Mainnet and Testnet  ↩︎

            +
            13. + +
          13. +

            ZIP 201: Network Peer Management for Overwinter  ↩︎

            +
            14. +
          -
          + diff --git a/rendered/zip-guide-markdown.html b/rendered/zip-guide-markdown.html index 87cc0679a..ca7f527a2 100644 --- a/rendered/zip-guide-markdown.html +++ b/rendered/zip-guide-markdown.html @@ -19,238 +19,288 @@ Category: {Consensus | Standards Track | Network | RPC | Wallet | Informational | Process} Created: yyyy-mm-dd License: {usually MIT} -Pull-Request: <https://github.com/zcash/zips/pull/???> -

          Don’t Panic

          -

          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.

          +Pull-Request: <https://github.com/zcash/zips/pull/???> + + +

          Don’t Panic

          + +

          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.

          +

          {Delete this section.}

          -

          Terminology

          -

          {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 1 -when, and only when, they appear in all capitals.

          -

          {Avoid duplicating definitions from other ZIPs. Instead use wording -like this:}

          -

          The terms “Mainnet” and “Testnet” in this document are to be -interpreted as defined in the Zcash protocol specification 2.

          -

          The term “full validator” in this document is to be interpreted as -defined in the Zcash protocol specification 3.

          + +

          Terminology

          + +

          {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 1 when, and +only when, they appear in all capitals.

          + +

          {Avoid duplicating definitions from other ZIPs. Instead use wording like this:}

          + +

          The terms “Mainnet” and “Testnet” in this document are to be interpreted as +defined in the Zcash protocol specification 2.

          + +

          The term “full validator” in this document is to be interpreted as defined in +the Zcash protocol specification 3.

          +

          The terms below are to be interpreted as follows:

          -
          -
          {Term to be defined}
          -
          -

          {Definition.}

          -
          -
          {Another term}
          -
          -

          {Definition.}

          -
          -
          -

          Abstract

          + +

          {Term to be defined}

          + +

          :{Definition.} +

          + +

          {Another term}

          + +

          :{Definition.} +

          + +

          Abstract

          +

          {Describe what this proposal does, typically in a few paragraphs.

          -

          The Abstract should only provide a summary of the ZIP; the ZIP should -remain complete without the Abstract.

          -

          Use links where applicable, e.g. 4 5.}

          -

          Motivation

          + +

          The Abstract should only provide a summary of the ZIP; the ZIP should remain +complete without the Abstract.

          + +

          Use links where applicable, e.g. 4 5.}

          + +

          Motivation

          +

          {Why is this proposal needed?

          -

          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.

          + +

          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.

          +

          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 at a high level 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.}

          -

          Requirements

          -

          {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.}

          -

          Non-requirements

          -

          {This section is entirely optional. If it is present, it describes -issues that the proposal is not attempting to address, that -someone might otherwise think it does or should.}

          -

          Specification

          +and if applicable, the history of how this area has changed. Then describe +at a high level 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.}

          + +

          Requirements

          + +

          {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.}

          + +

          Non-requirements

          + +

          {This section is entirely optional. If it is present, it describes issues that +the proposal is not attempting to address, that someone might otherwise think +it does or should.}

          + +

          Specification

          +

          {Replace this entire section.}

          -

          The Specification section describes what should change, using precise -language and conformance key words. Anything that is required in -order to implement the ZIP (or follow its process, in the case of a -Process ZIP) should be in this section.

          -

          Avoid overspecification! Also avoid underspecification. Specification -is hard. Don’t be afraid to ask for help.

          -

          Feel free to copy from other ZIPs doing similar things, e.g. defining -RPC calls, consensus rules, etc.

          -

          ZIPs MUST take into account differences between the Zcash Mainnet and -Testnet 6 where applicable. A consensus ZIP -MUST be able to be deployed on both Mainnet and Testnet.

          -

          Unless the specification is particularly simple, you will need to -organise it under subheadings.

          -

          Example subheading

          -

          At least while the ZIP is in Draft, we encourage writing open -questions and TODOs.

          -

          Open questions

          + +

          The Specification section describes what should change, using precise language and +conformance key words. Anything that is required in order to implement the ZIP +(or follow its process, in the case of a Process ZIP) should be in this section.

          + +

          Avoid overspecification! Also avoid underspecification. Specification is hard. +Don’t be afraid to ask for help.

          + +

          Feel free to copy from other ZIPs doing similar things, e.g. defining RPC calls, +consensus rules, etc.

          + +

          ZIPs MUST take into account differences between the Zcash Mainnet and Testnet +2 where applicable. A consensus ZIP MUST be able to be deployed +on both Mainnet and Testnet.

          + +

          Unless the specification is particularly simple, you will need to organise it under +subheadings.

          + +

          Example subheading

          + +

          At least while the ZIP is in Draft, we encourage writing open questions and TODOs.

          + +

          Open questions

          +
            -
          • What happens if a full validator can’t parse the fandangle as a -doohicky?
            • +
          • What happens if a full validator can’t parse the fandangle as a doohicky?
          +

          TODO: define byte encoding for the Jabberwock.

          -

          Comparison of ZIPs to RFCs

          -

          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 7.

          + +

          Comparison of ZIPs to RFCs

          + +

          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 6.

          +

          ZIPs are different from RFCs in the following ways:

          +
            -
          • 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 necessarily require creating a new ZIP, although -that is an option if the change is extensive enough to warrant it.
            • -
          • 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.
            • -
          • Security considerations SHOULD be spread throughout the text, in the -places where they are most relevant.
            • +
          • 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 necessarily +require creating a new ZIP, although that is an option if the change is extensive +enough to warrant it.
            • +
          • 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.
            • +
          • Security considerations SHOULD be spread throughout the text, in the places +where they are most relevant.
          -

          Using mathematical notation

          -

          Embedded LaTeX, e.g. \(x + y\), is -allowed and encouraged in ZIPs. The syntax for inline math is -“$latex code$” in either Markdown or (as a non-standard -extension) reStructuredText. This syntax does not work in tables for -reStructuredText; in that case use “:math:`latex code`” -instead.

          -

          The rendered HTML will use KaTeX 8, which only supports a -subset of LaTeX, so you will need to double-check that the rendering is -as intended.

          -

          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.

          -

          Notes and warnings

          -
          -

          “.. note::” in reStructuredText, or -“:::info” (terminated by “:::”) in Markdown, -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.

          -
          -
          -

          “.. warning::” in reStructuredText, or -“:::warning” (terminated by “:::”) in -Markdown, 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.

          -
          -

          Valid markup

          -

          This is optional before publishing a PR, but to check whether a -document is valid reStructuredText or Markdown, first install -rst2html5 and pandoc. E.g. on Debian-based -distros::

          -
          sudo apt install python3-pip pandoc perl sed
-pip3 install docutils==0.19 rst2html5
          -

          Then, with draft-myzip.rst or -draft-myzip.md in the root directory of a clone of this -repo, run::

          -
          make draft-myzip.html
          -

          (or just “make”) and view draft-myzip.html -in a web browser.

          -

          Citations and references

          -

          Each reference should be given a short name, e.g. “snark” 9. The syntax to cite that reference -is “[#snark]_” in reStructuredText, or -“[^snark]” in Markdown.

          -

          The corresponding entry in the References -section should look like this in reStructuredText:

          -
          .. [#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.
          + +

          Using mathematical notation

          + +

          Embedded \(\LaTeX\), e.g. \(x + y\), is allowed and encouraged in ZIPs. The syntax for +inline math is “$latex code$” in either Markdown or (as a +non-standard extension) reStructuredText. This syntax does not work in tables for +reStructuredText; in that case use “:math:`latex code`” instead.

          + +

          The rendered HTML will use KaTeX 7, which only supports a subset of \(\LaTeX\), +so you will need to double-check that the rendering is as intended.

          + +

          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.

          + +

          Notes and warnings

          + +

          :::info +“.. note::” in reStructuredText, or “:::info” (terminated by +“:::”) in Markdown, 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.
          +
          ::
          + +
          ::warning +“.. warning::” in reStructuredText, or “:::warning” (terminated by +“:::”) in Markdown, 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.
          +
          ::
          +
          + +

          Valid markup

          + +

          This is optional before publishing a PR, but to check whether a document is valid +reStructuredText or Markdown, first install docutils and rst2html5, and +build MultiMarkdown-6. E.g. on Debian-based distros::

          + +
          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
+
          + +

          Then, with draft-myzip.rst or draft-myzip.md in the root directory of a clone +of this repo, run::

          + +
          make draft-myzip.html
+
          + +

          (or just “make”) and view draft-myzip.html in a web browser.

          + +

          Citations and references

          + +

          Each reference should be given a short name, e.g. “snark” 8. The syntax to cite +that reference is “[#snark]_” in reStructuredText, or “[^snark]” in Markdown.

          + +

          The corresponding entry in the References section should look like this in +reStructuredText:

          + +
          .. [#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.
+
          +

          or like this in 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.
          -

          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.

          -

          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.

          + +
          [^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.
+
          + +

          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.

          + +

          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.

          +

          To link to another section of the same ZIP, use

          -
          `Section title`_
          + +
          `Section title`_
+
          +

          in reStructuredText, or

          -
          [Section title]
          + +
          [Section title]
+
          +

          in Markdown.

          -

          Citing the Zcash -protocol specification

          -

          For references to the Zcash protocol specification, prefer to link to -a section anchor, and name the reference as -[^protocol-<anchor>]. 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.

          -

          Do not include the “https://zips.z.cash/” part of URLs -to ZIPs or the protocol spec.

          -

          Reference implementation

          -

          {This section is entirely optional; if present, it usually gives -links to zcashd or zebrad PRs.}

          -

          References

          -
          + +

          Citing the Zcash protocol specification

          + +

          For references to the Zcash protocol specification, prefer to link to a section +anchor, and name the reference as [^protocol-<anchor>]. 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.

          + +

          Do not include the “https://zips.z.cash/” part of URLs to ZIPs or the protocol spec.

          + +

          Reference implementation

          + +

          {This section is entirely optional; if present, it usually gives links to zcashd or +zebrad PRs.}

          + +

          References

          + +
            -

          1. 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”↩︎

            2. -

          2. Zcash Protocol -Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet↩︎

            3. -

          3. Zcash -Protocol Specification, Version 2022.3.8. Section 3.3: The Block -Chain↩︎

            4. -

          4. Zcash Protocol -Specification, Version 2022.3.8 or later↩︎

            5. -

          5. Zcash -Protocol Specification, Version 2022.3.8. Section 1: Introduction↩︎

            6. -

          6. Zcash Protocol -Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet↩︎

            7. -

          7. ZIP 0: ZIP Process↩︎

            8. -

          8. KaTeX - The fastest math -typesetting library for the web↩︎

            9. -

          9. The -Hunting of the Snark. Lewis Carroll, with illustrations by Henry -Holiday. MacMillan and Co. London. March 29, 1876.↩︎

            10. + +
          10. +

            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”  ↩︎

            +
            11. + +
          11. +

            Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet  ↩︎

            +
            12. + +
          12. +

            Zcash Protocol Specification, Version 2022.3.8. Section 3.3: The Block Chain  ↩︎

            +
            13. + +
          13. +

            Zcash Protocol Specification, Version 2022.3.8 or later  ↩︎

            +
            14. + +
          14. +

            Zcash Protocol Specification, Version 2022.3.8. Section 1: Introduction  ↩︎

            +
            15. + +
          15. +

            ZIP 0: ZIP Process  ↩︎

            +
            16. + +
          16. +

            KaTeX - The fastest math typesetting library for the web  ↩︎

            +
            17. + +
          17. +

            The Hunting of the Snark. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.  ↩︎

            +
            18. +
          -
          + diff --git a/rendered/zip-guide.html b/rendered/zip-guide.html index 04af9b14d..cd6a14055 100644 --- a/rendered/zip-guide.html +++ b/rendered/zip-guide.html @@ -100,9 +100,15 @@

Valid markup

-

This is optional before publishing a PR, but to check whether a document is valid reStructuredText or Markdown, first install rst2html5 and pandoc. E.g. on Debian-based distros:

- 
sudo apt install python3-pip pandoc perl sed
-pip3 install docutils==0.19 rst2html5
+

This is optional before publishing a PR, but to check whether a document is valid reStructuredText or Markdown, first install docutils and rst2html5, and build MultiMarkdown-6. E.g. on Debian-based distros:

+ 
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

Then, with draft-myzip.rst or draft-myzip.md in the root directory of a clone of this repo, run:

make draft-myzip.html

(or just "make") and view draft-myzip.html in a web browser.