Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ZIPs 226 and 227: minor editorial changes #47

Merged
merged 2 commits into from
Nov 13, 2023
Merged

ZIPs 226 and 227: minor editorial changes #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c4b25da
ZIPs 226 and 227: remove trailing whitespace.
daira Nov 8, 2023
284047e
ZIP 226: use `\star` instead of `*` for bit representations.
daira Nov 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
<p>Participation in the Zcash project is subject to a <a href="https://github.com/zcash/zcash/blob/master/code_of_conduct.md">Code of Conduct</a>.</p>
<p>The Zcash protocol is documented in its <a href="protocol/protocol.pdf">Protocol Specification</a>.</p>
<p>To start contributing, first read <a href="zip-0000">ZIP 0</a> which documents the ZIP process. Then clone <a href="https://github.com/zcash/zips">this repo</a> from GitHub, and start adding your draft ZIP, formatted either as reStructuredText or as Markdown.</p>
<p>For example, if using reStructuredText, use a filename matching <code>draft-*.rst</code>. Use <code>make</code> to check that you are using correct <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> or <a href="https://pandoc.org/MANUAL.html#pandocs-markdown">Markdown</a> syntax, and double-check the generated <code>draft-*.html</code> file before filing a Pull Request.</p>
<p>For example, if using reStructuredText, use a filename matching <code>draft-*.rst</code>. Use <code>make</code> to check that you are using correct <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> or <a href="https://pandoc.org/MANUAL.html#pandocs-markdown">Markdown</a> syntax, and double-check the generated <code>draft-*.html</code> file before filing a Pull Request. See <a href="protocol/README">here</a> for the project dependencies.</p>
</section>
<section id="nu5-zips"><h2><span class="section-heading">NU5 ZIPs</span><span class="section-anchor"> <a rel="bookmark" href="#nu5-zips"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This is the list of ZIPs relevant to the NU5 Upgrade, which <a href="https://z.cash/upgrade/nu5/">activated on 31st May 2022</a>:</p>
Expand Down
4 changes: 2 additions & 2 deletions zip-0226.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@
<span class="math">\(\mathsf{Orchard}.\mathsf{Output}\)</span>
are as defined in the Zcash protocol specification <a id="footnote-reference-25" class="footnote_reference" href="#protocol-abstractcommit">17</a>. This note commitment scheme is instantiated using the Sinsemilla Commitment <a id="footnote-reference-26" class="footnote_reference" href="#protocol-concretesinsemillacommit">25</a> as follows:</p>
<div class="math">\(\begin{align}
\mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})}
\mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}\star, pk_{d}\star, v, \rho, \psi, \mathsf{AssetBase})}
:=\begin{cases}
\mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}\star, pk_{d}\star, v, \rho, \psi)}, &amp;\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\
\mathsf{cm}_{\mathsf{ZSA}} &amp;\text{otherwise}
Expand All @@ -130,7 +130,7 @@
<p>where:</p>
<div class="math">\(\begin{align}
\mathsf{cm}_{\mathsf{ZSA}} :=&amp;\ \mathsf{SinsemillaHashToPoint}( \texttt{"z.cash:ZSA-NoteCommit-M"}, \\
&amp;\ \ \ \mathsf{g_{d}*} \,||\, \mathsf{pk_{d}*} \,||\, \mathsf{I2LEBSP_{64}(v)} \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho) \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi) \,||\, \mathsf{asset\_base}) \\
&amp;\ \ \ \mathsf{g_{d}\star} \,||\, \mathsf{pk_{d}\star} \,||\, \mathsf{I2LEBSP_{64}(v)} \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho) \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi) \,||\, \mathsf{asset\_base}) \\
&amp;\ + [\mathsf{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""})
\end{align}\)</div>
<p>Note that
Expand Down
48 changes: 24 additions & 24 deletions zip-0226.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ This ZIP builds on the issuance mechanism introduced in ZIP 227 [#zip-0227]_.

Overview
========
In order to be able to represent different Assets, we need to define a data field that uniquely represents the Asset in question, which we call the Asset Identifier :math:`\mathsf{AssetId}`.
In order to be able to represent different Assets, we need to define a data field that uniquely represents the Asset in question, which we call the Asset Identifier :math:`\mathsf{AssetId}`.
This Asset Identifier maps to an Asset Base :math:`\mathsf{AssetBase}` that is stored in Orchard-based ZSA notes.
These terms are formally defined in ZIP 227 [#zip-0227]_.

Expand Down Expand Up @@ -79,16 +79,16 @@ This Asset Base will be the base point of the value commitment for the specific
Rationale for Asset Identifiers
```````````````````````````````

In future network and protocol upgrades, the same Asset description string can be carried on, potentially mapping into a different shielded pool. In that case, nodes should know how to transform the Asset Identifier, the Asset Digest, and the Asset Base from one shielded pool to another, while ensuring there are no balance violations [#zip-0209]_.
In future network and protocol upgrades, the same Asset description string can be carried on, potentially mapping into a different shielded pool. In that case, nodes should know how to transform the Asset Identifier, the Asset Digest, and the Asset Base from one shielded pool to another, while ensuring there are no balance violations [#zip-0209]_.

Note Structure & Commitment
---------------------------

Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e.
Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e.
:math:`\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}^*`.

An Orchard ZSA note differs from an Orchard note [#protocol-notes]_ by additionally including the Asset Base, :math:`\mathsf{AssetBase}`. So a ZSA note is a tuple :math:`(\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}})`,
where
where

- :math:`\mathsf{AssetBase} : \mathbb{P}^*` is the unique element of the Pallas group [#protocol-pallasandvesta]_ that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 [#zip-0227]_, a valid group element that is not the identity and is not :math:`\bot`. The byte representation of the Asset Base is defined as :math:`\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase})`.

Expand All @@ -101,19 +101,19 @@ We define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm
where :math:`\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, and where :math:`\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}` and :math:`\mathsf{Orchard}.\mathsf{Output}` are as defined in the Zcash protocol specification [#protocol-abstractcommit]_.
This note commitment scheme is instantiated using the Sinsemilla Commitment [#protocol-concretesinsemillacommit]_ as follows:

.. math:: \begin{align}
\mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})}
:=\begin{cases}
\mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}\star, pk_{d}\star, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\
.. math:: \begin{align}
\mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}\star, pk_{d}\star, v, \rho, \psi, \mathsf{AssetBase})}
:=\begin{cases}
\mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}\star, pk_{d}\star, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\
\mathsf{cm}_{\mathsf{ZSA}} &\text{otherwise}
\end{cases}
\end{align}

where:

.. math:: \begin{align}
\mathsf{cm}_{\mathsf{ZSA}} :=&\ \mathsf{SinsemillaHashToPoint}( \texttt{"z.cash:ZSA-NoteCommit-M"}, \\
&\ \ \ \mathsf{g_{d}*} \,||\, \mathsf{pk_{d}*} \,||\, \mathsf{I2LEBSP_{64}(v)} \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho) \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi) \,||\, \mathsf{asset\_base}) \\
&\ \ \ \mathsf{g_{d}\star} \,||\, \mathsf{pk_{d}\star} \,||\, \mathsf{I2LEBSP_{64}(v)} \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho) \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi) \,||\, \mathsf{asset\_base}) \\
&\ + [\mathsf{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""})
\end{align}

Expand All @@ -122,22 +122,22 @@ Note that :math:`\mathsf{repr}_{\mathbb{P}}` and :math:`\mathsf{GroupHash}^{\mat
The nullifier is generated in the same manner as in the Orchard protocol [#protocol-commitmentsandnullifiers]_.

The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext [#protocol-notept]_.
It consists of
It consists of

.. math:: (\mathsf{leadByte} : \mathbb{B}^{\mathbb{Y}}, \mathsf{d} : \mathbb{B}^{[\ell_{\mathsf{d}}]}, \mathsf{v} : \{0 .. 2^{\ell_{\mathsf{value}}} - 1\}, \mathsf{rseed} : \mathbb{B}^{\mathbb{Y}[32]}, \mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]}, \mathsf{memo} : \mathbb{B}^{\mathbb{Y}[512]})

Rationale for Note Commitment
`````````````````````````````

In the ZSA protocol, the instance of the note commitment scheme, :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}`, differs from the Orchard note commitment :math:`\mathsf{NoteCommit^{Orchard}_{rcm}}` in that for Custom Assets, the Asset Base will be added as an input to the commitment computation.
In the case where the Asset is the ZEC Asset, the commitment is computed identically to the Orchard note commitment, without making use of the ZEC Asset Base as an input.
In the ZSA protocol, the instance of the note commitment scheme, :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}`, differs from the Orchard note commitment :math:`\mathsf{NoteCommit^{Orchard}_{rcm}}` in that for Custom Assets, the Asset Base will be added as an input to the commitment computation.
In the case where the Asset is the ZEC Asset, the commitment is computed identically to the Orchard note commitment, without making use of the ZEC Asset Base as an input.
As we will see, the nested structure of the Sinsemilla-based commitment [#protocol-concretesinsemillacommit]_ allows us to add the Asset Base as a final recursive step.

The note commitment output is still indistinguishable from the original Orchard ZEC note commitments, by definition of the Sinsemilla hash function [#protocol-concretesinsemillahash]_. ZSA note commitments will therefore be added to the same Orchard Note Commitment Tree. In essence, we have:

.. math:: \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase})} \in \mathsf{NoteCommit^{Orchard}.Output}

This definition can be viewed as a generalization of the Orchard note commitment, and will allow maintaining a single commitment instance for the note commitment, which will be used both for pre-ZSA Orchard and ZSA notes.
This definition can be viewed as a generalization of the Orchard note commitment, and will allow maintaining a single commitment instance for the note commitment, which will be used both for pre-ZSA Orchard and ZSA notes.

Value Commitment
----------------
Expand Down Expand Up @@ -204,20 +204,20 @@ After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the bin
Rationale for Value Balance Verification
````````````````````````````````````````

We assume :math:`n` Actions in a transfer. Out of these :math:`n` Actions, we further distinguish (for the sake of clarity) between Actions related to ZEC and Actions related to Custom Assets.
We assume :math:`n` Actions in a transfer. Out of these :math:`n` Actions, we further distinguish (for the sake of clarity) between Actions related to ZEC and Actions related to Custom Assets.
We denote by :math:`S_{\mathsf{ZEC}} \subseteq [1,n]` the set of indices of Actions that are related to ZEC, and by :math:`S_{\mathsf{CA}} = [1,n] \setminus S_{\mathsf{ZEC}}` the set of indices of Actions that are related to Custom Assets.

The right hand side of the value balance verification equation can be expanded to:

.. math:: ((\sum_{i \in S_{\mathsf{ZEC}}} \mathsf{cv^{net}}_{i}) + (\sum_{j \in S_{\mathsf{CA}}} \mathsf{cv^{net}}_{j})) - ([\mathsf{v^{balanceOrchard}}]\mathcal{V}^{\mathsf{Orchard}} + [0]\mathcal{R}^{\mathsf{Orchard}}) - (\sum_{(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}} [\mathsf{v}]\mathsf{AssetBase} + [0]\mathcal{R}^{\mathsf{Orchard}})
This equation contains the balance check of the Orchard protocol [#protocol-binding]_.
With ZSA, transfer Actions for Custom Assets must also be balanced across Asset Bases.
All Custom Assets are contained within the shielded pool, and cannot be unshielded via a regular transfer.

This equation contains the balance check of the Orchard protocol [#protocol-binding]_.
With ZSA, transfer Actions for Custom Assets must also be balanced across Asset Bases.
All Custom Assets are contained within the shielded pool, and cannot be unshielded via a regular transfer.
Custom Assets can be burnt, the mechanism for which reveals the amount and identifier of the Asset being burnt, within the :math:`\mathsf{assetBurn}` set.
As such, for a correctly constructed transaction, we will get :math:`\sum_{j \in S_{\mathsf{CA}}} \mathsf{cv}_j^{\mathsf{net}} - \sum_{(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}} [\mathsf{v}]\mathsf{AssetBase} = \mathsf{\sum_{j \in S_{\mathsf{CA}}} rcv_{j}^{net}}\mathcal{R}^{\mathsf{Orchard}}`.

When the Asset is not being burnt, the net balance of the input and output values is zero, and there will be no addition to the :math:`\mathsf{assetBurn}` vector.
When the Asset is not being burnt, the net balance of the input and output values is zero, and there will be no addition to the :math:`\mathsf{assetBurn}` vector.
Therefore, the relationship between :math:`\mathsf{bvk}` and :math:`\mathsf{bsk}` will hold if and only if, per Custom Asset, the sum of the net values of the relevant Actions equals the corresponding :math:`\mathsf{v}_k` value (or equals :math:`0` if that Asset is not in the :math:`\mathsf{assetBurn}` set), and for ZEC, the sum of the net values of the relevant Actions equals the :math:`\mathsf{v^{balanceOrchard}}` value.

As in the Orchard protocol, the binding signature verification key, :math:`\mathsf{bvk}`, will only be valid (and hence verify the signature correctly), as long as the committed values sum to zero. In contrast, in this protocol, the committed values must sum to zero **per Asset Base**, as the Pedersen commitments add up homomorphically only with respect to the same value base point.
Expand All @@ -237,7 +237,7 @@ When the number of input notes of a particular Asset Base is smaller than the re

Wallets and other clients have to choose from the following to ensure the Asset Base is preserved for the output note of a Split Action:

1. The Split Input note could be another note containing the same Asset Base that is being spent by this transaction (but not by this Split Input).
1. The Split Input note could be another note containing the same Asset Base that is being spent by this transaction (but not by this Split Input).
2. The Split Input note could be a different unspent note containing the same Asset Base (note that the note will not actually be spent).
3. The Split Input note could be an already spent note containing the same Asset Base (note that by zeroing the value in the circuit, we prevent double spending).

Expand Down Expand Up @@ -322,8 +322,8 @@ The transaction format for v6 transactions is described in ZIP 230 [#zip-0230]_.
TxId Digest
===========

The transaction digest algorithm defined in ZIP 244 [#zip-0244]_ is modified by the ZSA protocol to add a new branch for issuance information, along with modifications within the ``orchard_digest`` to account for the inclusion of the Asset Base.
The details of these changes are described in this section, and highlighted using the ``[UPDATED FOR ZSA]`` or ``[ADDED FOR ZSA]`` text label. We omit the details of the sections that do not change for the ZSA protocol.
The transaction digest algorithm defined in ZIP 244 [#zip-0244]_ is modified by the ZSA protocol to add a new branch for issuance information, along with modifications within the ``orchard_digest`` to account for the inclusion of the Asset Base.
The details of these changes are described in this section, and highlighted using the ``[UPDATED FOR ZSA]`` or ``[ADDED FOR ZSA]`` text label. We omit the details of the sections that do not change for the ZSA protocol.

txid_digest
-----------
Expand All @@ -345,7 +345,7 @@ When Orchard Actions are present in the transaction, this digest is a BLAKE2b-25
T.4b: orchard_actions_memos_digest (32-byte hash output) [UPDATED FOR ZSA]
T.4c: orchard_actions_noncompact_digest (32-byte hash output) [UPDATED FOR ZSA]
T.4d: flagsOrchard (1 byte)
T.4e: valueBalanceOrchard (64-bit signed little-endian)
T.4e: valueBalanceOrchard (64-bit signed little-endian)
T.4f: anchorOrchard (32 bytes)

T.4a: orchard_actions_compact_digest
Expand Down