From e6fef4069670f16c27331512ccb19b769f35c984 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Wed, 15 Mar 2023 18:33:08 +0530 Subject: [PATCH 01/42] Moving changes in zsa-zips to zsa1 (#10) Co-authored-by: daniben31 Co-authored-by: Deirdre Connolly Co-authored-by: Daira Hopwood Co-authored-by: Jonathan S. Rouach Co-authored-by: str4d Co-authored-by: Paul --- README.rst | 4 +- index.html | 4 +- zip-0226.html | 634 ++++++++++++++++++++++- zip-0226.rst | 355 ++++++++++++- zip-0227-asset-identifier-relation.png | Bin 0 -> 44943 bytes zip-0227-asset-identifier-relation.svg | 293 +++++++++++ zip-0227-key-components-zsa.png | Bin 0 -> 61722 bytes zip-0227-key-components-zsa.svg | 270 ++++++++++ zip-0227.html | 681 ++++++++++++++++++++++++- zip-0227.rst | 442 +++++++++++++++- 10 files changed, 2671 insertions(+), 12 deletions(-) create mode 100644 zip-0227-asset-identifier-relation.png create mode 100644 zip-0227-asset-identifier-relation.svg create mode 100644 zip-0227-key-components-zsa.png create mode 100644 zip-0227-key-components-zsa.svg diff --git a/README.rst b/README.rst index 1cfdcc654..d41b7de0e 100644 --- a/README.rst +++ b/README.rst @@ -107,8 +107,8 @@ Index of ZIPs 222 Transparent Zcash Extensions Draft 224 Orchard Shielded Protocol Final 225 Version 5 Transaction Format Final - 226 Transfer and Burn of Zcash Shielded Assets Reserved - 227 Issuance of Zcash Shielded Assets Reserved + 226 Transfer and Burn of Zcash Shielded Assets Draft + 227 Issuance of Zcash Shielded Assets Draft 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final 244 Transaction Identifier Non-Malleability Final diff --git a/index.html b/index.html index cdd234c7b..a150585e0 100644 --- a/index.html +++ b/index.html @@ -81,8 +81,8 @@ 222 Transparent Zcash Extensions Draft 224 Orchard Shielded Protocol Final 225 Version 5 Transaction Format Final - 226 Transfer and Burn of Zcash Shielded Assets Reserved - 227 Issuance of Zcash Shielded Assets Reserved + 226 Transfer and Burn of Zcash Shielded Assets Draft + 227 Issuance of Zcash Shielded Assets Draft 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final 244 Transaction Identifier Non-Malleability Final diff --git a/zip-0226.html b/zip-0226.html index 41e18d5bf..5241a9763 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -3,6 +3,7 @@ ZIP 226: Transfer and Burn of Zcash Shielded Assets +
@@ -15,10 +16,639 @@ Deirdre Connolly <deirdre@zfnd.org> Credits: Daniel Benarroch Aurelien Nicolas -Status: Reserved + Teor +Status: Draft Category: Consensus +Created: 2022-05-01 +License: MIT Discussions-To: <https://github.com/zcash/zips/issues/618> -Pull-Request: <https://github.com/zcash/zips/pull/649> +Pull-Request: <https://github.com/zcash/zips/pull/676> +

Terminology

+

The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

+

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

+

The term "Orchard" in this document is to be interpreted as described in ZIP 224 3.

+

We define the following additional terms:

+
    +
  • Asset: A type of note that can be transferred on the Zcash block chain, identified by the + \(\mathsf{AssetId}\) + parameter. +
      +
    • ZEC is the default (and currently the only defined) Asset for the Zcash mainnet.
      • +
    • TAZ is the default (and currently the only defined) Asset for the Zcash testnet.
      • +
    • We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ.
      • +
    +
    • +
  • Native Asset: a Custom Asset with issuance defined on the Zcash block chain.
    • +
  • Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash block chain.
    • +
  • Split Input: an Action input identifying a Custom Asset note, used to ensure that the output note of that Action is of a validly issued + \(\mathsf{AssetId}\) + when there is no corresponding real input note to spend. The Action does not spend the note identified by the Split Input.
    • +
  • Split Action: an Action that contains a Split Input.
    • +
+
+

Abstract

+

ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol &mdash; a set of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain.

+

Creation of such Assets is defined in ZIP 227 5. Transfer and burn of such Assets is defined in ZIP 226 4. The ZSA protocol is proposed to be instantiated by a modification to the Orchard protocol, as specified in these ZIPs.

+
+

Motivation

+

None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes.

+
+

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 + \(\mathsf{AssetId}\) + . This Asset Identifier maps to an Asset Base + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 5.

+

The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 8 is preserved across Assets (see the Orchard Binding Signature 10), and by extension the balance of an Orchard transaction. That is, the sum of all the + \(\mathsf{value^{net}}\) + from each Action Description, computed as + \(\mathsf{value^{old}-value^{new}}\) + , must be balanced only with respect to the same Asset Identifier. This is specially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

+

As was initially proposed by Jack Grigg and Daira Hopwood 22 23, we propose to make this happen by changing the value base point, + \(\mathcal{V}^{\mathsf{Orchard}}\) + , in the Homomorphic Pedersen Commitment that derives the value commitment, + \(\mathsf{cv^{net}}\) + , of the net value in an Orchard Action.

+

Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + an auxiliary input to the proof for each Action statement 20, represented already as a point on the Pallas curve. The circuit then should check that the same + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + is used in the old note commitment and the new note commitment 17, and as the base point + \(\mathcal{V}^\mathsf{Orchard}\) + in the value commitment 18. This ensures (1) that the input and output notes are of the same + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + , and (2) that only actions with the same Asset Base will balance out in the Orchard binding signature.

+

In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 19 for Custom Assets, as we need to enforce that the + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + of the output note of that split Action is the output of a valid + \(\mathsf{ZSAValueBase^{Orchard}}\) + computation defined in ZIP 227 5.

+

Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the + \(\mathsf{valueBalance}\) + of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets.

+
+

Specification

+

Most of the protocol is kept the same as the Orchard protocol released with NU5, except for the following.

+

Asset Identifiers

+

For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an Asset description, + \(\mathsf{asset\_desc}\) + , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, + \(\mathsf{AssetId}\) + , the Asset Digest, and the Asset Base ( + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 5.

+

This + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + will be the base point of the value commitment for the specific Custom Asset. Note that the + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + of the ZEC Asset will be kept as the original value base point, + \(\mathcal{V}^\mathsf{Orchard}\) + .

+

In future network and protocol upgrades, the same Asset description string can be carried on, with potentially a mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, + \(\mathsf{AssetId}\) + , the Asset Digest, and the Asset Base from one shielded protocol to another.

+
+

Note Structure & Commitment

+

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

+

A ZSA note differs from an Orchard note 6 by additionally including the Asset Base, + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + . So a ZSA note is a tuple + \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})\) + , where

+
    +
  • + \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P*}\) + is the unique element of the Pallas group 14 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 5. The byte representation of the Asset Base is defined as + \(\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) + .
    • +
+

Specifically, we define the note commitment scheme + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) + as follows:

+
\(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \{0 .. 2^{l_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P*} \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)
+

where + \(\mathbb{P}, l_{\mathbb{P}}, q_{\mathbb{P}}\) + are as defined for the Pallas curve 14, and + \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) + are as defined in the Zcash protocol specification 9. This note commitment scheme is instantiated using the Sinsemilla Commitment 17 as follows:

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

where (note that + \(\mathsf{repr}_{\mathbb{P}}\) + is as defined for the Pallas curve 14, + \(l^{\mathsf{Orchard}}_{\mathsf{base}}\) + is as defined in §5.3 13, and + \(\mathsf{I2LEBSP}\) + is as defined in §5.1 12 of the Zcash protocol specification):

+
\(\begin{align} +\mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ +&\mathsf{g_{d}*}\; \| \; \mathsf{pk_{d}*}\; \| \; \mathsf{I2LEBSP_{64}(v)}\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho)\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi)\; \| \; \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) +\end{align}\)
+

The nullifier is generated in the same manner as in the Orchard protocol 11.

+

The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 7. It consists of

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

Rationale for Note Commitment

+

In the ZSA protocol, the instance of the note commitment scheme, + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) + , differs from the Orchard note commitment + \(\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 17 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

+

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

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

Value Commitment

+

In the case of the ZSA protocol, the value of different Asset Identifiers in a given transaction will be committed using a different value base point. The value commitment becomes:

+
\(\mathsf{cv^{net}:=ValueCommit^{OrchardZSA}_{rcv}(v^{net}_{AssetId}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}:= \mathsf{[v^{net}_{AssetId}]}\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}} + [\mathsf{rcv}]\mathcal{R}^{\mathsf{Orchard}}\)
+

where + \(\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{AssetId}}\) + such that + \(\mathsf{v^{old}_{AssetId}}\) + and + \(\mathsf{v^{new}_{AssetId}}\) + are the values of the old and new notes of Asset Identifier + \(\mathsf{AssetId}\) + respectively,

+

+ \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + is defined in ZIP 227 5, and

+

+ \(\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}\) + , as in the Orchard protocol.

+

We define + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}\) + so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 3.

+

Rationale for Value Commitment

+

The Orchard Protocol uses a Homomorphic Pedersen Commitment 18 to perform the value commitment, with fixed base points + \(\mathcal{V}^{\mathsf{Orchard}}\) + and + \(\mathcal{R}^{\mathsf{Orchard}}\) + as the values represent the amount of ZEC being transferred.

+

The use of different value base points for different Assets enables the final balance of the transaction to be securely computed, such that each Asset Identifier is balanced independently, which is required as different Assets are not meant to be mutually fungible.

+
+
+

Value Balance Verification

+

In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 10.

+

For a total of + \(n\) + Actions in a transfer, the prover MUST still sign the SIGHASH of the transaction using the binding signature key + \(\mathsf{bsk} = \sum_{\mathsf{ \forall i\in \{1,...,n\}}} \mathsf{rcv_{i}}\) + .

+

Then the verifier MUST compute

+
\(\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} = \sum \mathsf{rcv_{i}^{net}}\mathcal{R}^{\mathsf{Orchard}}\)
+

and use it to verify the bindingSignature on the SIGHASH message.

+

Rationale for Value Balance Verification

+

The main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, + \(\mathsf{v^{balanceOrchard}}\) + . No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is burnt, as we will see below in the burn mechanism.

+

As in the Orchard protocol, the binding signature verification key, + \(\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 only sum to zero per Asset Base, as the Pedersen commitments add up homomorphically only with respect to the same value base point.

+
+
+

Split Notes

+

One of the key functionalities in a UTXO-based protocol is the fact that input notes are usually split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output. This requires a 1-to-many (Orchard) transaction. However, because each Action represents an input and an output, the resulting transaction must have multiple inputs. In order to cope with this today, the Actions that have not been assigned input notes are instead given dummy spend notes 19, which we call split Actions and split notes respectively. Basically, the input note is “faked” inside of the proof in order to hide which Action contains the real spend note.

+

This, however, brings some issues when it comes to adding multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base, but it must be enforced to be an actual output of a GroupHash computation (in fact we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). If not, then the prover could essentially input a multiple (or linear combination) of an existing Asset Base, with the goal to attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

+

In order to prevent this, we make some modifications to the circuit. Specifically we remove the dummy note functionality for Custom Assets and we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof.

+

This creates a chain of induction that ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified. If this were not done then it would be possible to violate balance, for example by using a value base point derived from those of other Assets.

+

Note that we do not care about whether the note identified by a Split Input is owned by the sender, or whether it was nullified before.

+

Wallets and other clients have a choice to make 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).
    2. +
  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. +
  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).
    4. +
+

The specific circuit changes are presented below.

+
+

Circuit Statement

+

The advantage of the design described above, with respect to the circuit statement, is that every ZSA Action statement is kept closely similar to the Orchard Action statement 20, except for a few additions that ensure the security of the Asset Identifier system.

+

Asset Identifier Equality: the following constraints must be added to ensure that the input and output note are of the same + \(\mathsf{AssetId}\) + :

+
    +
  • The Asset Base, + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + , for the note is witnessed once, as an auxiliary input.
    • +
  • In the Old note commitment integrity constraint in the Orchard Action statement 20, + \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) + is replaced with + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + .
    • +
  • In the New note commitment integrity constraint in the Orchard Action statement 20, + \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) + is replaced with + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + .
    • +
+

Correct Value Commitment: the following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes:

+
    +
  • The fixed-base multiplication constraints between the value and the value base point of the value commitment, + \(\mathsf{cv}\) + , is replaced with a variable-base multiplication between the two.
    • +
  • The witness to the value base point, as defined in the value base equation is the auxiliary input + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + .
    • +
+

Enforce Secure Identifier for Split Actions: the following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action:

+
    +
  • +
    +
    The Value Commitment Integrity should be changed
    +
    +
      +
    • Replace the input note value by a generic value, + \(\mathsf{v}'\) + , as + \(\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) +
      • +
    +
    +
    +
    • +
  • +
    +
    Add a boolean split variable as an auxiliary witness. This variable is to be activated split = 1 if the Action in question is a split and split = 0 if the Action is actually spending an input note:
    +
    +
      +
    • If split = 1 then set + \(\mathsf{v}' = 0\) + otherwise + \(\mathsf{v}'=\mathsf{v^{old}}\) + from the auxiliary input.
      • +
    +
    +
    +
    • +
  • +
    +
    The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes):
    +
    +
      +
    • Check that (path, pos) is a valid Merkle path of depth + \(\mathsf{MerkleDepth^Orchard}\) + , from + \(\mathsf{cm^old}\) + to the anchor + \(\mathsf{rt^Orchard}\) + .
      • +
    +
    +
    +
    • +
  • +
    +
    The Nullifier Integrity will be changed to prevent the identification of notes
    +
    +
      +
    • Replace the + \(\psi_{old}\) + value with a generic + \(\psi'\) + as + \(\mathsf{nf_old = DeriveNullifier_nk}(\rho^\mathsf{old}, \psi', \mathsf{cm^old})\) +
      • +
    • if + \(\mathtt{split} = 0\) + then constrain + \(\psi' = \psi^{old}\) + . (Otherwise + \(\psi'\) + should be sampled randomly.)
      • +
    +
    +
    +
    • +
+

Enabling Backwards Compatibility with ZEC Notes: the following constraints must be added to enable backwards compatibility with Orchard ZEC notes.

+

The old note commitment is computed using a “rolling-aggregate” Sinsemilla commitment. This means that the commitment is computed by adding new chunks or windows to the accumulated value. This method will be used in order to maintain a single commitment instance for the old note commitment, that will be used both for Orchard ZEC notes and for ZSA notes. The original Orchard ZEC notes will be conserved and not actually be converted into ZSA notes, as we will always need to compute them. However, new notes will always be ZSA notes with an Asset Base.

+

The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (ZEC-Orchard note). If the note is an old note, from before the upgrade, the commitment is computed in the original Orchard fashion. If the note is a new ZSA note, there are two cases:

+
    +
  • +
    +
    If the Asset Base auxiliary input present but set to + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + = + \(\mathcal{V}^\mathsf{Orchard}\) +
    +
    +
      +
    • NoteCommitment has a “compatibility” path that computes the note commitment as in plain Orchard (i.e.: without including the Asset Base)
      • +
    • This path also uses the original domain separator for ZEC note commitment
      • +
    +
    +
    +
    • +
  • +
    +
    Else,
    +
    +
      +
    • The note commitment adds the identfier, + \(\mathsf{AssetId}\) + , as a final “chunk” of the Sinsemilla commitment
      • +
    • The note commitment uses a different domain separator for ZSA note commitment
      • +
    +
    +
    +
    • +
+
+

Backward Compatibility

+

In order to have a "clean" backwards compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - The input notes with an Asset Base denote the Custom Assets, generating a note commitment that includes the Asset Identifier; whereas the notes without an Asset Base denote the ZEC notes from before the protocol upgrade, and generate a note commitment that does not include the Asset Base, in order to maintain the referencability to the Merkle tree - The value commitment is abstracted to allow for the value base-point as a variable private input to the proof - The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include split input notes.

+
+
+

Burn Mechanism

+

The burn mechanism may be needed for off-boarding the Wrapped Assets from the chain, or enabling advanced tokenomics on Assets. It is part of the Issuance/Burn protocol, but given that it can be seen as an extension of the Transfer protocol, we add it here for readability.

+

In essence, the burn mechanism is a transparent / revealing extension to the transfer protocol that enables a specific amount of any Asset identifier to be sent into “oblivion”. Our burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.

+

First, contrary to the strict transfer transaction, we allow the sender to include a + \(\mathsf{valueBalance_{AssetId}}\) + variable for every Asset Identifier that is being burnt. As we will show in the transaction structure, this is separate from the regular + \(\mathsf{valueBalance^Orchard}\) + that is the default transparent value for the ZEC Asset. We require that for every + \(\mathsf{valueBalance_{AssetId}}\) + provided as above by the sender, + \(\mathsf{valueBalance_{AssetId}} \neq 0\) + . This is enforced via a consensus rule.

+

For every custom Asset that is burnt, we add to the assetBurn vector the tuple + \((\mathsf{valueBalance_{AssetId}, AssetId})\) + such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.

+

+ \(\mathsf{assetBurn = \{ (v^{AssetId}, AssetId)}\ |\ \forall\ \mathsf{AssetId}\ \textit{s.t.}\ \mathsf{v^{AssetId}} \neq 0 \}\) +

+

The value balances for each Asset Identifier in assetBurn represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

+

Finally, the validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective + \(\mathsf{AssetId}\) + as the value base point of the Pedersen Commitment. This is done as follows

+

+ \(\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\forall \mathsf{AssetId}\textit{ s.t. }\mathsf{v^{AssetId}\neq 0}} \mathsf{ValueCommit_0^{OrchardZSA}(v^{AssetId}, AssetId) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}}\) +

+

In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt.

+

Note: Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

+
+

ZSA Transaction Structure

+

The transaction format is similar to the version 5 transaction format described in the Zcash specification 21, with the following additions to the Orchard bundle:

+ + + + + + + + + + + + + + + + + + + + + + + +
BytesNameData TypeDescription
variesnAssetBurncompactSizenumber of Assets burnt
40*nAssetBurnvAssetBurnbytes[40][nAssetBurn]32 bytes Asset type_t, 8 bytes of valueBalance
+

In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the + \(\mathsf{AssetId}\) + ). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action.

+
+

Other Considerations

+

Transaction Fees

+

The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 24.

+
+

Security and Privacy

+
    +
  • Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure.
    • +
  • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
    • +
  • We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
    • +
  • Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. +
      +
    • One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
      • +
    +
    • +
+
+

Deployment

+

The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions.

+
+
+

Test Vectors

+
    +
  • LINK TBD
    • +
+
+

Reference Implementation

+
    +
  • LINK TBD
    • +
  • LINK TBD
    • +
+
+

References

+ + + + + + + +
1RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
+ + + + + + + +
2ZIP 200: Network Upgrade Mechanism
+ + + + + + + +
3ZIP 224: Orchard
+ + + + + + + +
4ZIP 226: Transfer and Burn of Zcash Shielded Assets
+ + + + + + + +
5ZIP 227: Issuance of Zcash Shielded Assets
+ + + + + + + +
6Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes
+ + + + + + + +
7Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields
+ + + + + + + +
8Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions
+ + + + + + + +
9Zcash Protocol Specification, Version 2022.3.8. Section 4.1.8: Commitment
+ + + + + + + +
10Zcash Protocol Specification, Version 2022.3.8. Section 4.14: Balance and Binding Signature (Orchard)
+ + + + + + + +
11Zcash Protocol Specification, Version 2022.3.8. Section 4.16: Note Commitments and Nullifiers
+ + + + + + + +
12Zcash Protocol Specification, Version 2022.3.8. Section 5.1: Integers, Bit Sequences, and Endianness
+ + + + + + + +
13Zcash Protocol Specification, Version 2022.3.8. Section 5.3: Constants
+ + + + + + + +
14Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.6: Pallas and Vesta
+ + + + + + + +
15Pallas/Vesta supporting evidence
+ + + + + + + +
16Zcash Protocol Specification, Version 2022.3.8. Section 5.4.1.9: Sinsemilla hash function
+ + + + + + + +
17Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.4: Sinsemilla commitments
+ + + + + + + +
18Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
+ + + + + + + +
19Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard)
+ + + + + + + +
20Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard)
+ + + + + + + +
21Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
+ + + + + + + +
22User-Defined Assets and Wrapped Assets
+ + + + + + + +
23Comment on Generalized Value Commitments
+ + + + + + + +
24ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
+
\ No newline at end of file diff --git a/zip-0226.rst b/zip-0226.rst index 58ec75e1c..d42ffab57 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -9,7 +9,358 @@ Deirdre Connolly Credits: Daniel Benarroch Aurelien Nicolas - Status: Reserved + Teor + Status: Draft Category: Consensus + Created: 2022-05-01 + License: MIT Discussions-To: - Pull-Request: + Pull-Request: + + +Terminology +=========== + +The key word "MUST" in this document is to be interpreted as described in RFC 2119 [#RFC2119]_. + +The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. + +The term "Orchard" in this document is to be interpreted as described in ZIP 224 [#zip-0224]_. + +We define the following additional terms: + +- Asset: A type of note that can be transferred on the Zcash block chain, identified by the :math:`\mathsf{AssetId}` parameter. + + - ZEC is the default (and currently the only defined) Asset for the Zcash mainnet. + - TAZ is the default (and currently the only defined) Asset for the Zcash testnet. + - We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ. + +- Native Asset: a Custom Asset with issuance defined on the Zcash block chain. +- Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash block chain. +- Split Input: an Action input identifying a Custom Asset note, used to ensure that the output note of that Action is of a validly issued :math:`\mathsf{AssetId}` when there is no corresponding real input note to spend. The Action does not spend the note identified by the Split Input. +- Split Action: an Action that contains a Split Input. + +Abstract +======== + +ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol — a set +of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain. + +Creation of such Assets is defined in ZIP 227 [#zip-0227]_. Transfer and burn of such Assets is defined +in ZIP 226 [#zip-0226]_. The ZSA protocol is proposed to be instantiated by a modification to the +Orchard protocol, as specified in these ZIPs. + +Motivation +========== + +None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling +multi-asset support on the Zcash chain will open the door for a host of applications, and +enhance the ecosystem with application developers and Asset custody institutions for +issuance and bridging purposes. + +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}`. +This Asset Identifier maps to an Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` that is stored in Orchard-based ZSA notes. +These terms are formally defined in ZIP 227 [#zip-0227]_. + +The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description [#protocol-actions]_ is preserved across Assets (see the Orchard Binding Signature [#protocol-binding]_), and by extension the balance of an Orchard transaction. That is, the sum of all the :math:`\mathsf{value^{net}}` from each Action Description, computed as :math:`\mathsf{value^{old}-value^{new}}`, must be balanced **only with respect to the same Asset Identifier**. This is specially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred. + +As was initially proposed by Jack Grigg and Daira Hopwood [#initial-zsa-issue]_ [#generalized-value-commitments]_, we propose to make this happen by changing the value base point, :math:`\mathcal{V}^{\mathsf{Orchard}}`, in the Homomorphic Pedersen Commitment that derives the value commitment, :math:`\mathsf{cv^{net}}`, of the *net value* in an Orchard Action. + +Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` an auxiliary input to the proof for each Action statement [#protocol-actionstatement]_, represented already as a point on the Pallas curve. The circuit then should check that the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` is used in the old note commitment and the new note commitment [#protocol-concretesinsemillacommit]_, **and** as the base point :math:`\mathcal{V}^\mathsf{Orchard}` in the value commitment [#protocol-concretevaluecommit]_. This ensures (1) that the input and output notes are of the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`, and (2) that only actions with the same Asset Base will balance out in the Orchard binding signature. + +In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the output note of that split Action is the output of a valid :math:`\mathsf{ZSAValueBase^{Orchard}}` computation defined in ZIP 227 [#zip-0227]_. + +Finally, in this ZIP we also describe the *burn* mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the :math:`\mathsf{valueBalance}` of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets. + +Specification +============= + +Most of the protocol is kept the same as the Orchard protocol released with NU5, except for the following. + +Asset Identifiers +----------------- + +For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}` , the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. + +This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. + +In future network and protocol upgrades, the same Asset description string can be carried on, with potentially a mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base from one shielded protocol to another. + +Note Structure & Commitment +--------------------------- + +Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e. +:math:`\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P*}`. + +A ZSA note differs from an Orchard note [#protocol-notes]_ by additionally including the Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. So a ZSA note is a tuple :math:`(\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})`, +where + +- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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]_. The byte representation of the Asset Base is defined as :math:`\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})`. + +Specifically, we define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows: + +.. math:: \mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \{0 .. 2^{l_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P*} \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output} + +where :math:`\mathbb{P}, l_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, and :math:`\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \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}^{\mathsf{Orchard}})} + :=\begin{cases} + \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{... if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ + \mathsf{cm}_{\mathsf{ZSA}} &\text{... otherwise} + \end{cases} + \end{align} + +where (note that :math:`\mathsf{repr}_{\mathbb{P}}` is as defined for the Pallas curve [#protocol-pallasandvesta]_, :math:`l^{\mathsf{Orchard}}_{\mathsf{base}}` is as defined in §5.3 [#protocol-constants]_, and :math:`\mathsf{I2LEBSP}` is as defined in §5.1 [#protocol-endian]_ of the Zcash protocol specification): + +.. math:: \begin{align} + \mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ + &\mathsf{g_{d}*}\; \| \; \mathsf{pk_{d}*}\; \| \; \mathsf{I2LEBSP_{64}(v)}\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho)\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi)\; \| \; \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) + \end{align} + +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 + +.. math:: (\mathsf{leadByte} : \mathbb{B}^{\mathbb{Y}}, \mathsf{d} : \mathbb{B}^{[l_{\mathsf{d}}]}, \mathsf{v} : \{0 .. 2^{l_{\mathsf{value}}} - 1\}, \mathsf{rseed} : \mathbb{B}^{\mathbb{Y}[32]}, \mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]}, \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. +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, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification. + +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}^{\mathsf{Orchard}})} \in \mathsf{NoteCommit^{Orchard}.Output} + + + + +Value Commitment +---------------- + +In the case of the ZSA protocol, the value of different Asset Identifiers in a given transaction will be committed using a **different value base point**. The value commitment becomes: + +.. math:: \mathsf{cv^{net}:=ValueCommit^{OrchardZSA}_{rcv}(v^{net}_{AssetId}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}:= \mathsf{[v^{net}_{AssetId}]}\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}} + [\mathsf{rcv}]\mathcal{R}^{\mathsf{Orchard}} + +where :math:`\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{AssetId}}` such that :math:`\mathsf{v^{old}_{AssetId}}` and :math:`\mathsf{v^{new}_{AssetId}}` are the values of the old and new notes of Asset Identifier :math:`\mathsf{AssetId}` respectively, + +.. _`value base`: + +:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` is defined in ZIP 227 [#zip-0227]_, and + +:math:`\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}`, as in the Orchard protocol. + +We define :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}` so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 [#zip-0224]_. + +Rationale for Value Commitment +'''''''''''''''''''''''''''''' + +The Orchard Protocol uses a Homomorphic Pedersen Commitment [#protocol-concretevaluecommit]_ to perform the value commitment, with fixed base points :math:`\mathcal{V}^{\mathsf{Orchard}}` and :math:`\mathcal{R}^{\mathsf{Orchard}}` as the values represent the amount of ZEC being transferred. + +The use of different value base points for different Assets enables the final balance of the transaction to be securely computed, such that each Asset Identifier is balanced independently, which is required as different Assets are not meant to be mutually fungible. + + +Value Balance Verification +-------------------------- + +In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol [#protocol-binding]_. + +For a total of :math:`n` Actions in a transfer, the prover MUST still sign the `SIGHASH` of the transaction using the binding signature key +:math:`\mathsf{bsk} = \sum_{\mathsf{ \forall i\in \{1,...,n\}}} \mathsf{rcv_{i}}`. + +Then the verifier MUST compute + +.. math:: \mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} = \sum \mathsf{rcv_{i}^{net}}\mathcal{R}^{\mathsf{Orchard}} + +and use it to verify the `bindingSignature` on the `SIGHASH` message. + +Rationale for Value Balance Verification +'''''''''''''''''''''''''''''''''''''''' + +The main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is *burnt*, as we will see below in the `burn mechanism`_. + +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 only sum to zero **per Asset Base**, as the Pedersen commitments add up homomorphically only with respect to the same value base point. + + +Split Notes +----------- + +One of the key functionalities in a UTXO-based protocol is the fact that input notes are usually split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output. This requires a 1-to-many (Orchard) transaction. However, because each Action represents an input and an output, the resulting transaction must have multiple inputs. In order to cope with this today, the Actions that have not been assigned input notes are instead given *dummy spend notes* [#protocol-dummynotes]_, which we call split Actions and split notes respectively. Basically, the input note is “faked” inside of the proof in order to hide which Action contains the *real* spend note. + +This, however, brings some issues when it comes to adding multiple Asset Identifiers, as the output note of the split Actions *cannot* contain *any* Asset Base, but it must be enforced to be an actual output of a GroupHash computation (in fact we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). If not, then the prover could essentially input a multiple (or linear combination) of an existing Asset Base, with the goal to attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds. + +In order to prevent this, we make some modifications to the circuit. Specifically we remove the dummy note functionality for Custom Assets and we enforce that *every* input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value +will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof. + +This creates a chain of induction that ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified. If this were not done then it would be possible to violate balance, for example by using a value base point derived from those of other Assets. + +Note that we do not care about whether the note identified by a Split Input is owned by the sender, or whether it was nullified before. + +Wallets and other clients have a choice to make 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). +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). + +The specific circuit changes are presented below. + +Circuit Statement +----------------- + +The advantage of the design described above, with respect to the circuit statement, is that every *ZSA Action statement* is kept closely similar to the Orchard Action statement [#protocol-actionstatement]_, except for a few additions that ensure the security of the Asset Identifier system. + +**Asset Identifier Equality:** the following constraints must be added to ensure that +the input and output note are of the same :math:`\mathsf{AssetId}`: + +- The Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`, for the note is witnessed once, as an auxiliary input. +- In the Old note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. +- In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. + +**Correct Value Commitment:** the following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes: + +- The fixed-base multiplication constraints between the value and the value base point of the value commitment, :math:`\mathsf{cv}`, is replaced with a variable-base multiplication between the two. +- The witness to the value base point, as defined in the `value base`_ equation is the auxiliary input :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`. + +**Enforce Secure Identifier for Split Actions:** the following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action: + +- The Value Commitment Integrity should be changed + - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}` +- Add a boolean ``split`` variable as an auxiliary witness. This variable is to be activated ``split = 1`` if the Action in question is a split and ``split = 0`` if the Action is actually spending an input note: + - If ``split = 1`` then set :math:`\mathsf{v}' = 0` otherwise :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. +- The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes): + - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^old}` to the anchor :math:`\mathsf{rt^Orchard}`. +- The Nullifier Integrity will be changed to prevent the identification of notes + - Replace the :math:`\psi_{old}` value with a generic :math:`\psi'` as :math:`\mathsf{nf_old = DeriveNullifier_nk}(\rho^\mathsf{old}, \psi', \mathsf{cm^old})` + - if :math:`\mathtt{split} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled randomly.) + +**Enabling Backwards Compatibility with ZEC Notes:** the following constraints must be added to enable backwards compatibility with Orchard ZEC notes. + +The old note commitment is computed using a “rolling-aggregate” Sinsemilla commitment. This means that the commitment is computed by adding new chunks or windows to the accumulated value. This method will be used in order to maintain a single commitment instance for the old note commitment, that will be used both for Orchard ZEC notes and for ZSA notes. The original Orchard ZEC notes will be conserved and not actually be converted into ZSA notes, as we will always need to compute them. +However, new notes will always be ZSA notes with an Asset Base. + +The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (ZEC-Orchard note). If the note is an old note, from before the upgrade, the commitment is computed in the original Orchard fashion. If the note is a new ZSA note, there are two cases: + +- If the Asset Base auxiliary input present but set to :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` = :math:`\mathcal{V}^\mathsf{Orchard}` + - NoteCommitment has a “compatibility” path that computes the note commitment as in plain Orchard (i.e.: without including the Asset Base) + - This path also uses the original domain separator for ZEC note commitment +- Else, + - The note commitment adds the identfier, :math:`\mathsf{AssetId}`, as a final “chunk” of the Sinsemilla commitment + - The note commitment uses a different domain separator for ZSA note commitment + + +Backward Compatibility +---------------------- + +In order to have a "clean" backwards compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: +- The input notes with an Asset Base denote the Custom Assets, generating a note commitment that includes the Asset Identifier; whereas the notes without an Asset Base denote the ZEC notes from before the protocol upgrade, and generate a note commitment that does not include the Asset Base, in order to maintain the referencability to the Merkle tree +- The value commitment is abstracted to allow for the value base-point as a variable private input to the proof +- The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include split input notes. + + +Burn Mechanism +============== +The burn mechanism may be needed for off-boarding the Wrapped Assets from the chain, or enabling advanced tokenomics on Assets. It is part of the Issuance/Burn protocol, but given that it can be seen as an extension of the Transfer protocol, we add it here for readability. + +In essence, the burn mechanism is a transparent / revealing extension to the transfer protocol that enables a specific amount of any Asset identifier to be sent into “oblivion”. Our burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. + +First, contrary to the strict transfer transaction, we allow the sender to include a :math:`\mathsf{valueBalance_{AssetId}}` variable for every Asset Identifier that is being burnt. As we will show in the transaction structure, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset. +We require that for every :math:`\mathsf{valueBalance_{AssetId}}` provided as above by the sender, :math:`\mathsf{valueBalance_{AssetId}} \neq 0`. This is enforced via a consensus rule. + +For every custom Asset that is burnt, we add to the `assetBurn` vector the tuple :math:`(\mathsf{valueBalance_{AssetId}, AssetId})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer. + + +:math:`\mathsf{assetBurn = \{ (v^{AssetId}, AssetId)}\ |\ \forall\ \mathsf{AssetId}\ \textit{s.t.}\ \mathsf{v^{AssetId}} \neq 0 \}` + +The value balances for each Asset Identifier in `assetBurn` represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). + +Finally, the validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective :math:`\mathsf{AssetId}` as the value base point of the Pedersen Commitment. This is done as follows + +:math:`\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\forall \mathsf{AssetId}\textit{ s.t. }\mathsf{v^{AssetId}\neq 0}} \mathsf{ValueCommit_0^{OrchardZSA}(v^{AssetId}, AssetId) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}}` + +In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt. + +**Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets. + +ZSA Transaction Structure +========================= + +The transaction format is similar to the version 5 transaction format described in the Zcash specification [#protocol-transactionstructure]_, with the following additions to the Orchard bundle: + ++-----------------+-------------+-----------------------------------+-------------------------+ +| Bytes | Name | Data Type | Description | ++=================+=============+===================================+=========================+ +| varies | nAssetBurn | compactSize | number of Assets burnt | ++-----------------+-------------+-----------------------------------+-------------------------+ +| 40*nAssetBurn | vAssetBurn | bytes[40][nAssetBurn] | 32 bytes Asset type_t, | +| | | | 8 bytes of valueBalance | ++-----------------+-------------+-----------------------------------+-------------------------+ + +In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the :math:`\mathsf{AssetId}`). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action. + +Other Considerations +==================== + +Transaction Fees +---------------- + +The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade [#zip-0317b]_. + +Security and Privacy +-------------------- + +- Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure. +- When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design. +- We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state. +- Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. + + - One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. + +Deployment +----------- +The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions. + +Test Vectors +============ + +- LINK TBD + +Reference Implementation +======================== + +- LINK TBD +- LINK TBD + +References +========== + +.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ +.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism `_ +.. [#zip-0224] `ZIP 224: Orchard `_ +.. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ +.. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ +.. [#protocol-notes] `Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes `_ +.. [#protocol-notept] `Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields `_ +.. [#protocol-actions] `Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions `_ +.. [#protocol-abstractcommit] `Zcash Protocol Specification, Version 2022.3.8. Section 4.1.8: Commitment `_ +.. [#protocol-binding] `Zcash Protocol Specification, Version 2022.3.8. Section 4.14: Balance and Binding Signature (Orchard) `_ +.. [#protocol-commitmentsandnullifiers] `Zcash Protocol Specification, Version 2022.3.8. Section 4.16: Note Commitments and Nullifiers `_ +.. [#protocol-endian] `Zcash Protocol Specification, Version 2022.3.8. Section 5.1: Integers, Bit Sequences, and Endianness `_ +.. [#protocol-constants] `Zcash Protocol Specification, Version 2022.3.8. Section 5.3: Constants `_ +.. [#protocol-pallasandvesta] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.6: Pallas and Vesta `_ +.. [#pasta-evidence] `Pallas/Vesta supporting evidence `_ +.. [#protocol-concretesinsemillahash] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.1.9: Sinsemilla hash function `_ +.. [#protocol-concretesinsemillacommit] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.4: Sinsemilla commitments `_ +.. [#protocol-concretevaluecommit] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard) `_ +.. [#protocol-dummynotes] `Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard) `_ +.. [#protocol-actionstatement] `Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard) `_ +.. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) `_ +.. [#initial-zsa-issue] `User-Defined Assets and Wrapped Assets `_ +.. [#generalized-value-commitments] `Comment on Generalized Value Commitments `_ +.. [#zip-0317b] `ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs `_ \ No newline at end of file diff --git a/zip-0227-asset-identifier-relation.png b/zip-0227-asset-identifier-relation.png new file mode 100644 index 0000000000000000000000000000000000000000..d073f7aa80a0ddecd60084dc28a7502c111470b5 GIT binary patch literal 44943 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 PfEQR%{Z++Fi;w>Um{*4{ literal 0 HcmV?d00001 diff --git a/zip-0227-asset-identifier-relation.svg b/zip-0227-asset-identifier-relation.svg new file mode 100644 index 000000000..de18d9914 --- /dev/null +++ b/zip-0227-asset-identifier-relation.svg @@ -0,0 +1,293 @@ + + + +image/svg+xmlAssetDigestAssetIdAssetBaseAssetIdProtocolAssetIdAsset Digest diff --git a/zip-0227-key-components-zsa.png b/zip-0227-key-components-zsa.png new file mode 100644 index 0000000000000000000000000000000000000000..aa9fa5d21d48885d21a987130a4504a92b74614e GIT binary patch literal 61722 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 literal 0 HcmV?d00001 diff --git a/zip-0227-key-components-zsa.svg b/zip-0227-key-components-zsa.svg new file mode 100644 index 000000000..217acc635 --- /dev/null +++ b/zip-0227-key-components-zsa.svg @@ -0,0 +1,270 @@ + + + +image/svg+xmlskissIssuance validating keyIssuance master keyZSA Key ComponentsiskikIssuance authorizing key diff --git a/zip-0227.html b/zip-0227.html index 89f120fef..ff51aae3b 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -3,6 +3,7 @@ ZIP 227: Issuance of Zcash Shielded Assets +
@@ -15,10 +16,686 @@ Deirdre Connolly <deirdre@zfnd.org> Credits: Daniel Benarroch Aurelien Nicolas -Status: Reserved + Teor +Status: Draft Category: Consensus +Created: 2022-05-01 +License: MIT Discussions-To: <https://github.com/zcash/zips/issues/618> -Pull-Request: <https://github.com/zcash/zips/pull/649> +Pull-Request: <https://github.com/zcash/zips/pull/676> +

Terminology

+

The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

+

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

+

The term "Orchard" in this document is to be interpreted as described in ZIP 224 3.

+

The terms "Asset", "custom Asset", and "Wrapped Asset" in this document are to be interpreted as described in ZIP 226 4.

+

We define the following additional terms:

+
    +
  • Issuance Action: an instance of a single issuance of a Zcash Shielded Asset. It defines the issuance of a single Asset Identifier.
    • +
  • Issuance Bundle: the bundle in the transaction that contains all the issuance actions of that transaction.
    • +
+
+

Abstract

+

ZIP 226 4 and ZIP 227 6 propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 6. The transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

+
+

Motivation

+

This ZIP is a supporting ZIP for ZIP 226 4, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function.

+

This ZIP enables only transparent issuance, since as a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.

+

The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash block chain), as well as for institutions to create bridges from other chains and import "wrapped" Assets. This enables what we hope will be a useful set of applications.

+
+

Use Cases

+

The design presented in this ZIP enables issuance of shielded Assets in various modes:

+
    +
  • The issuer may or may not know the receivers of the issued Asset in advance.
    • +
  • The Asset can be of non-fungible type, where each Asset type can be made part of a single “series”.
    • +
  • The supply of the Asset can be limited in advance or not.
    • +
  • The Asset can be a wrapped version of an Asset issued by another chain (as long as there is a bridge that supports transfer of that Asset between chains).
    • +
+

See the Concrete Applications section for more details.

+
+

Requirements

+
    +
  • Any user of the Zcash block chain can issue custom Assets on chain.
    • +
  • The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain.
    • +
  • At the time of issuance, the issuer should be able to allocate all the Assets to the corresponding owners by creating the corresponding (shielded) output notes to the respective addresses. This allows for allocation to be totally private even though the issuance mechanism is itself transparent.
    • +
  • Issuing or changing the attributes of a specific Asset should require cryptographic authorization.
    • +
  • The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier.
    • +
  • An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets.
    • +
  • Every "issuance action" should contain a finalize boolean that defines whether the specific Custom Asset can have further tokens issued or not.
    • +
+
+

Specification

+

As explained, the issuance protocol allows for a single issuance action to be sent to many receivers, by generating as many output notes as distinct recipients. Furthermore, every bundle can contain many issuance actions.

+

Issuance Keys and Issuance Authorization Signature Scheme

+

The ZSA Protocol adds the following three keys to the key components 12:

+
    +
  1. The issuance master key, denoted as + \(\mathsf{sk}_{\mathsf{iss}}\) + , as the name suggests, is the master key that is used to derive the other two keys.
    2. +
  2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as + \(\mathsf{isk}\) + . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
    3. +
  3. The issuance validating key, denoted as + \(\mathsf{ik}\) + , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
    4. +
+

Issuance Authorization Signature Scheme

+

We define the issuance authorization signature scheme + \(\mathsf{IssueAuthSig}\) + similar to + \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) + , the Orchard spend authorization signature scheme 16. Specifically, we instantiate + \(\mathsf{IssueAuthSig}\) + as + \(\mathsf{RedPallas}\) + without key re-randomization using generator + \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) + where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in the Zcash protocol specification 13.

+
+

Issuance Key Derivation

+

The issuance master key is generated by choosing a bit sequence uniformly at random from + \(\mathbb{B}^{\mathbb{Y}[32]}\) + , like the Orchard spending key 14. In + \(\mathsf{zcashd}\) + , this key is derived in a manner similar to the generation of the Orchard master key in ZIP 32 10, as detailed below:

+
    +
  • Details TBD
    • +
+

The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 14, as described below.

+
    +
  • The issuance authorizing key is derived from the issuance master key, + \(\mathsf{sk}_{\mathsf{iss}}\) + , as a private signature key:
    • +
+
\(\mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} )\)
+
    +
  • The issuance validating key is derived from the issuance authorizing key, + \(\mathsf{isk}\) + , as a public verification key:
    • +
+
\(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
+

This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 9. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

+

The derivation of these keys are shown in the following diagram:

+
+ +
Diagram of Issuance Key Components for the ZSA Protocol
+
+
+
+

Asset Identifier

+

For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair + \((\mathsf{ik}, \mathsf{asset\_desc})\) + , where + \(\mathsf{ik}\) + is the issuance key and + \(\mathsf{asset\_desc}\) + is a byte string.

+

A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, + \(\mathsf{AssetDigest}\) + , which is simply is a + \(\textsf{BLAKE2b-512}\) + hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

+

Let

+
    +
  • + \(\mathsf{asset\_desc}\) + be the asset description, a UTF-8 encoded string of up to 512 bytes, which includes any information pertaining to the issuance.
    • +
  • + \(\mathsf{ik}\) + be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
    • +
+

Define + \(\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\) + , where

+
    +
  • + \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) + .
    • +
+

Define + \(\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\) + , where

+

In the case of Orchard, we define + \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\) + where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in 13.

+

The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

+
+ +
Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol
+
+
+

Global Issuance State

+

Issuance requires the following additions to the global state defined at block boundaries:

+
    +
  • + \(\mathsf{previously\_finalized}\) + , a set of + \(\mathsf{AssetId}\) + that have been finalized (i.e.: the finalize flag has been set to 1 in some issuance transaction preceding the block boundary).
    • +
+
+

Issuance Action Description

+

An issuance action, IssueAction, is the instance of issuing a specific custom Asset, and contains the following fields:

+
    +
  • + \(\mathsf{assetDescSize}\) + : the size of the Asset description, a number between + \(0\) + and + \(512\) + , stored in two bytes.
    • +
  • + \(\mathsf{asset\_desc}\) + : the Asset description, a UTF-8 encoded string of up to 512 bytes
    • +
  • notes: an array containing the unencrypted output notes of the recipients of the Asset, of type Note
    • +
  • finalize: a boolean that defines whether the issuance of that specific custom Asset is finalized or not
    • +
+

An asset's + \(\mathsf{AssetId}\) + is added to the + \(\mathsf{previously\_finalized}\) + set after a block that contains any issuance transaction for that asset with finalize = 1. It then cannot be removed from this set. For Assets with + \(\mathsf{AssetId} \in \mathsf{previously\_finalized}\) + , no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with + \(\mathsf{AssetId} \not\in \mathsf{previously\_finalized}\) + , new issuance actions can be issued in future transactions. These must use the same Asset description, + \(\mathsf{asset\_desc}\) + , and can either maintain finalize = 0 or change it to finalize = 1, denoting that this custom Asset cannot be issued after the containing block.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SizeNameData TypeDescription
2 bytes + \(\mathsf{assetDescSize}\) + byteThe length of the + \(\mathsf{asset\_desc}\) + string in bytes
Varies + \(\mathsf{asset\_desc}\) + byteUTF-8 encoded string, of size + \(\mathsf{assetDescSize}\) + bytes
VariesnNotescompactSizeThe number of notes in the issuance action
noteSize * nNotesvNotesNote[nNotes]A sequence of note descriptions within the issuance action
1 byteflagsIssuancebyteAn 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0.
+

We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the NoteCommitmentTree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.

+
+

Issuance Bundle

+

An issuance bundle, IssueBundle, is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields:

+
    +
  • + \(\mathsf{ik}\) + : the issuance validating key, that allows the validators to verify that the + \(\mathsf{AssetId}\) + is properly associated with the issuer.
    • +
  • actions: an array of issuance actions, of type IssueAction.
    • +
  • issueAuthSig: the signature of the transaction SIGHASH, signed by the issuance authorizing key, + \(\mathsf{isk}\) + , that validates the issuance .
    • +
+

The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 18.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BytesNameData TypeDescription
VariesnIssueActionscompactSizeThe number of issuance actions in the bundle
VariesvIssueActionsIssueAction[nIssueActions]A sequence of issuance actions descriptions
32 + \(\mathsf{ik}\) + byte[32]The issuance validating key of the issuer, used to validate the signature
64issueAuthSigbyte[64]The signature of the transaction SIGHASH, signed by the issuer
+
+

Issuance Protocol

+

The issuer program performs the following operations

+

For all actions IssueAction:

+
    +
  • encode + \(\mathsf{asset\_desc}\) + as a UTF-8 byte string of size up to 512.
    • +
  • compute + \(\mathsf{AssetDigest}\) + from the issuance validating key + \(\mathsf{ik}\) + and + \(\mathsf{asset\_desc}\) + as decribed in the Asset Identifier section.
    • +
  • compute + \(\mathsf{AssetBase^{Protocol}}\) + from + \(\mathsf{AssetDigest}\) + as decribed in the Asset Identifier section.
    • +
  • set the finalize boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
    • +
  • For each recipient + \(i\) + : +
      +
    • generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is + \(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d},i}, \mathsf{v}_i, \rho_i, \psi_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!\) + .
      • +
    +
    • +
  • encode the IssueAction into the vector vIssueActions of the bundle
    • +
+

For the IssueBundle:

+
    +
  • encode the vIssueActions vector
    • +
  • encode the + \(\mathsf{ik}\) + as 32 byte-string
    • +
  • sign the SIGHASH of the transaction with the issuance authorizing key, + \(\mathsf{isk}\) + , using the + \(\mathsf{IssueAuthSig}\) + signature scheme. The signature is then added to the issuance bundle.
    • +
+

NOTE that the commitment is not included in the IssuanceAction itself. As explained below, it is later computed by the validators and added to the NoteCommitmentTree.

+
+

Consensus Rule Changes

+

For the IssueBundle:

+
    +
  • Verify the RedPallas-based issuance authorization signature on SIGHASH, issueAuthSig, is verified by invoking issueAuthSig.VerifySig(ik, SIGHASH)
    • +
+

For each IssueAction in IssueBundle:

+
    +
  • check that + \(0 < \mathsf{assetDescSize} <= 512\) + .
    • +
  • check that + \(\mathsf{asset\_desc}\) + is a string of length + \(\mathsf{assetDescSize}\) + bytes.
    • +
  • retrieve + \(\mathsf{AssetBase}\) + from the first note in the sequence and check that + \(\mathsf{AssetBase}\) + is derived from the issuance validating key + \(\mathsf{ik}\) + and + \(\mathsf{asset\_desc}\) + as described in the Asset Identifier section.
    • +
  • check that the + \(\mathsf{AssetId}\) + does not exist in the previously_finalized set in the global state.
    • +
  • check that every note in the IssueAction contains the same + \(\mathsf{AssetBase}\) + and is properly constructed as + \(note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})\) + .
    • +
+

If all of the above checks pass, do the following:

+
    +
  • For each note, compute the note commitment as + \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) + as defined in the Note Structure and Commitment section of ZIP 226 5 and
    • +
  • add + \(\mathsf{cm}\) + to the Merkle tree of note commitments, NoteCommitmentTree.
    • +
  • If finalize = 1, add + \(\mathsf{AssetId}\) + to the previously_finalized set immediately after the block in which this transaction occurs.
    • +
+
+
+

Rationale

+

The following is a list of rationale for different decisions made in the proposal:

+
    +
  • The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools.
    • +
  • The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”.
    • +
  • The + \(\mathsf{asset\_desc}\) + is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: +
      +
    • links for storage such as for NFTs.
      • +
    • metadata for Assets, encoded in any format.
      • +
    • bridging information for Wrapped Assets (chain of origin, issuer name, etc)
      • +
    • information to be committed by the issuer, though not enforceable by the protocol.
      • +
    +
    • +
  • We require a check whether the finalize flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the previously_finalized set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
    • +
+

Concrete Applications

+

Asset Features

+
    +
  • By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example, +
      +
    • by setting finalize = 1 from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed.
      • +
    +
    • +
  • Issuers can also stop the existing supply production of any Asset associated to their issuer keys. This could be done by +
      +
    • issuing a last set of tokens of that specific + \(\mathsf{AssetId}\) + , for which finalize = 1, or by
      • +
    • issuing a transaction with a single note in the issuance action pertaining to that + \(\mathsf{AssetId}\) + , where the note will contain a value = 0. This can be used for application-specific purposes (NFT collections) or for security purposes to revoke the Asset issuance (see Security and Privacy Considerations).
      • +
    • Note in the above cases, that the setting of the finalize flag will take effect at the block boundary, that is, after all the transactions in the block.
      • +
    +
    • +
  • The issuance and burn mechanisms can be used in conjunction to determine the supply of Assets on the Zcash ecosystem. This allows for the bridging of Assets defined on other chains.
    • +
  • Furthermore, NFT issuance is enabled by issuing in a single bundle several issuance actions, where each + \(\mathsf{AssetId}\) + corresponds to value = 1 at the fundamental unit level. Issuers and users should make sure that finalize = 1 for each of the actions in this scenario.
    • +
+
+
+

TxId Digest

+

As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

+

A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

+ 
issuance_txid_digest
+├── issue_actions_digest
+└── issuanceValidatingKey
+

In the specification below, nodes of the tree are presented in depth-first order.

+

issuance_txid_digest

+

A BLAKE2b-256 hash of the following values

+ 
T.1: issue_actions_digest    (32-byte hash output)
+T.2: issuanceValidatingKey   (32 bytes)
+

The personalization field of this hash is set to:

+ 
"ZTxIdSAIssueHash"
+

In case the transaction has no issuance components, ''issue_actions_digest'' is:

+ 
BLAKE2b-256("ZTxIdSAIssueHash", [])
+

T.1: issue_actions_digest

+

A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:

+ 
T.1a: notes_digest            (32-byte hash output)
+T.1b: assetDescription        (field encoding bytes)
+T.1c: flagsIssuance           (1 byte)
+

The personalization field of this hash is set to:

+ 
"ZTxIdIssActHash"
+
T.1a: notes_digest
+

A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:

+ 
T.1a.1: recipient                    (field encoding bytes)
+T.1a.2: value                        (field encoding bytes)
+T.1a.3: asset                        (field encoding bytes)
+T.1a.4: rho                          (field encoding bytes)
+T.1a.5: rseed                        (field encoding bytes)
+

The personalization field of this hash is set to:

+ 
"ZTxIdIANoteHash"
+
T.1a.1: recipient
+

This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 17.

+
+
T.1a.2: value
+

Note value encoded as little-endian 8-byte representation of u64 raw value.

+
+
T.1a.3: asset
+

Asset Base encoded as 32-byte representation of Pallas point.

+
+
T.1a.4: rho
+

Nullifier encoded as 32-byte representation of Pallas point.

+
+
T.1a.5: rseed
+

The ZIP 212 32-byte seed randomness for a note.

+
+
+
T.1b: assetDescription
+

UTF-8 encoding of the Asset description string.

+
+
T.1c: flagsIssuance
+

An 8-bit value representing a set of flags. Ordered from LSB to MSB:

+
    +
  • finalize
    • +
  • The remaining bits are set to 0.
    • +
+
+
+

T.2: issuanceValidatingKey

+

A byte encoding of issuance validating key for the bundle as defined in the Issuance Key Derivation section.

+
+
+
+

Security and Privacy Considerations

+

Issuer Key or AssetId Compromise

+

The design of this protocol does not allow for a rotation of the issuer validating key, that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended:

+
    +
  • If an issuer validating key is compromised, the finalize boolean for all the Assets issued with that key should be set to 1 and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new + \(\mathsf{AssetId}\) + .
    • +
+

Bridging Assets For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

+
+

Other Considerations

+

Implementing Zcash Nodes

+

Although not enforced in the global state, it is RECOMMENDED that Zcash full validators keep track of the total supply of Assets as a mutable mapping issuanceSupplyInfoMap from + \(\mathsf{AssetId}\) + to + \(\mathsf{issuanceSupplyInfoMap := (totalSupply, finalize)}\) + in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

+
+

Fee Structures

+

The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 8.

+
+

Future Work

+

In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying + \(\mathsf{ik}\) + of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether.

+
+
+

Test Vectors

+
    +
  • LINK TBD
    • +
+
+

Reference Implementation

+
    +
  • LINK TBD
    • +
  • LINK TBD
    • +
+
+

Deployment

+

This ZIP is proposed to activate with Network Upgrade 6.

+
+

References

+ + + + + + + +
1RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
+ + + + + + + +
2ZIP 200: Network Upgrade Mechanism
+ + + + + + + +
3ZIP 224: Orchard
+ + + + + + + +
4ZIP 226: Transfer and Burn of Zcash Shielded Assets
+ + + + + + + +
5ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment
+ + + + + + + +
6ZIP 227: Issuance of Zcash Shielded Assets
+ + + + + + + +
7ZIP 244: Transaction Identifier Non-Malleability
+ + + + + + + +
8ZIP 317b: ZSA Extension Proportional Fee Mechanism
+ + + + + + + +
9ZIP 32: Shielded Hierarchical Deterministic Wallets
+ + + + + + + +
10ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation
+ + + + + + + +
11ZIP 316: Unified Addresses and Unified Viewing Keys
+ + + + + + + +
12Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
+ + + + + + + +
13Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
+ + + + + + + +
14Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
+ + + + + + + +
15Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
+ + + + + + + +
16Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
+ + + + + + + +
17Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
+ + + + + + + +
18Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
+
\ No newline at end of file diff --git a/zip-0227.rst b/zip-0227.rst index 2834a7727..879232ad0 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -9,7 +9,445 @@ Deirdre Connolly Credits: Daniel Benarroch Aurelien Nicolas - Status: Reserved + Teor + Status: Draft Category: Consensus + Created: 2022-05-01 + License: MIT Discussions-To: - Pull-Request: + Pull-Request: + +Terminology +=========== + +The key word "MUST" in this document is to be interpreted as described in RFC 2119 [#RFC2119]_. + +The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. + +The term "Orchard" in this document is to be interpreted as described in ZIP 224 [#zip-0224]_. + +The terms "Asset", "custom Asset", and "Wrapped Asset" in this document are to be interpreted as described in ZIP 226 [#zip-0226]_. + +We define the following additional terms: + +- Issuance Action: an instance of a single issuance of a Zcash Shielded Asset. It defines the issuance of a single Asset Identifier. +- Issuance Bundle: the bundle in the transaction that contains all the issuance actions of that transaction. + +Abstract +======== + +ZIP 226 [#zip-0226]_ and ZIP 227 [#zip-0227]_ propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 [#zip-0227]_. The transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA. + +Motivation +========== + +This ZIP is a supporting ZIP for ZIP 226 [#zip-0226]_, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function. + +This ZIP enables only *transparent* issuance, since as a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked. + +The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash block chain), as well as for institutions to create bridges from other chains and import "wrapped" Assets. This enables what we hope will be a useful set of applications. + + +Use Cases +========= + +The design presented in this ZIP enables issuance of shielded Assets in various modes: + +- The issuer may or may not know the receivers of the issued Asset in advance. +- The Asset can be of non-fungible type, where each Asset type can be made part of a single “series”. +- The supply of the Asset can be limited in advance or not. +- The Asset can be a wrapped version of an Asset issued by another chain (as long as there is a bridge that supports transfer of that Asset between chains). + +See the `Concrete Applications`_ section for more details. + +Requirements +============ + +- Any user of the Zcash block chain can issue custom Assets on chain. +- The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain. +- At the time of issuance, the issuer should be able to allocate all the Assets to the corresponding owners by creating the corresponding (shielded) output notes to the respective addresses. This allows for allocation to be totally private even though the issuance mechanism is itself transparent. +- Issuing or changing the attributes of a specific Asset should require cryptographic authorization. +- The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier. +- An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets. +- Every "issuance action" should contain a ``finalize`` boolean that defines whether the specific Custom Asset can have further tokens issued or not. + + +Specification +============= + +As explained, the issuance protocol allows for a single issuance action to be sent to many receivers, by generating as many output notes as distinct recipients. Furthermore, every bundle can contain many issuance actions. + +Issuance Keys and Issuance Authorization Signature Scheme +--------------------------------------------------------- + +The ZSA Protocol adds the following three keys to the key components [#protocol-addressesandkeys]_: + +1. The issuance master key, denoted as :math:`\mathsf{sk}_{\mathsf{iss}}`, as the name suggests, is the master key that is used to derive the other two keys. + +2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. + +3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. + +Issuance Authorization Signature Scheme +``````````````````````````````````````` + +We define the issuance authorization signature scheme :math:`\mathsf{IssueAuthSig}` similar to :math:`\mathsf{SpendAuthSig}^{\mathsf{Orchard}}`, the Orchard spend authorization signature scheme [#protocol-concretespendauthsig]_. +Specifically, we instantiate :math:`\mathsf{IssueAuthSig}` as :math:`\mathsf{RedPallas}` without key re-randomization using generator :math:`\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})` where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in the Zcash protocol specification [#protocol-concretegrouphashpallasandvesta]_. + +Issuance Key Derivation +``````````````````````` + +The issuance master key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_. +In :math:`\mathsf{zcashd}`, this key is derived in a manner similar to the generation of the Orchard master key in ZIP 32 [#zip-0032-orchard-master]_, as detailed below: + +- Details TBD + +The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below. + +- The issuance authorizing key is derived from the issuance master key, :math:`\mathsf{sk}_{\mathsf{iss}}`, as a private signature key: + +.. math:: \mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} ) + +- The issuance validating key is derived from the issuance authorizing key, :math:`\mathsf{isk}`, as a public verification key: + +.. math:: \mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk}) + +This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe. + +The derivation of these keys are shown in the following diagram: + +.. figure:: zip-0227-key-components-zsa.png + :width: 450px + :align: center + :figclass: align-center + + Diagram of Issuance Key Components for the ZSA Protocol + + +Asset Identifier +---------------- + +For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair :math:`(\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. + +A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier. +From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. + +Let + +- :math:`\mathsf{asset\_desc}` be the asset description, a UTF-8 encoded string of up to 512 bytes, which includes any information pertaining to the issuance. +- :math:`\mathsf{ik}` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. + +Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`, +where + +- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`. + +Define :math:`\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`, +where + +In the case of Orchard, we define :math:`\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})` +where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in [#protocol-concretegrouphashpallasandvesta]_. + +The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram: + +.. figure:: zip-0227-asset-identifier-relation.png + :width: 600px + :align: center + :figclass: align-center + + Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol + + +Global Issuance State +--------------------- + +Issuance requires the following additions to the global state defined at block boundaries: + +- :math:`\mathsf{previously\_finalized}`, a set of :math:`\mathsf{AssetId}` that have been finalized (i.e.: the ``finalize`` flag has been set to ``1`` in some issuance transaction preceding the block boundary). + +Issuance Action Description +--------------------------- + +An issuance action, `IssueAction`, is the instance of issuing a specific custom Asset, and contains the following fields: + +- :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. +- :math:`\mathsf{asset\_desc}`: the Asset description, a UTF-8 encoded string of up to 512 bytes +- `notes`: an array containing the unencrypted output notes of the recipients of the Asset, of type `Note` +- ``finalize``: a boolean that defines whether the issuance of that specific custom Asset is finalized or not + +An asset's :math:`\mathsf{AssetId}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with ``finalize = 1``. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetId} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetId} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain ``finalize = 0`` or change it to ``finalize = 1``, denoting that this custom Asset cannot be issued after the containing block. + +================= =============================== ========================== =========================================================================================== +Size Name Data Type Description +================= =============================== ========================== =========================================================================================== +2 bytes :math:`\mathsf{assetDescSize}` byte The length of the :math:`\mathsf{asset\_desc}` string in bytes +Varies :math:`\mathsf{asset\_desc}` byte UTF-8 encoded string, of size :math:`\mathsf{assetDescSize}` bytes +Varies nNotes compactSize The number of notes in the issuance action +noteSize * nNotes vNotes Note[nNotes] A sequence of note descriptions within the issuance action +1 byte ``flagsIssuance`` byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0. +================= =============================== ========================== =========================================================================================== + +We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the `NoteCommitmentTree` as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers. + +Issuance Bundle +--------------- + +An issuance bundle, `IssueBundle`, is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields: + +- :math:`\mathsf{ik}`: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer. +- `actions`: an array of issuance actions, of type `IssueAction`. +- `issueAuthSig`: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathsf{isk}`, that validates the issuance . + +The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_. + +======= ==================== ========================== ========================================================================= +Bytes Name Data Type Description +======= ==================== ========================== ========================================================================= +Varies nIssueActions compactSize The number of issuance actions in the bundle +Varies vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions +32 :math:`\mathsf{ik}` byte[32] The issuance validating key of the issuer, used to validate the signature +64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer +======= ==================== ========================== ========================================================================= + +Issuance Protocol +----------------- +The issuer program performs the following operations + +For all actions `IssueAction`: + +- encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512. +- compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Asset Identifier`_ section. +- compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Asset Identifier`_ section. +- set the ``finalize`` boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``) +- For each recipient :math:`i`: + + - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d},i}, \mathsf{v}_i, \rho_i, \psi_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`. + +- encode the `IssueAction` into the vector `vIssueActions` of the bundle + +For the `IssueBundle`: + +- encode the `vIssueActions` vector +- encode the :math:`\mathsf{ik}` as 32 byte-string +- sign the `SIGHASH` of the transaction with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle. + + +NOTE that the commitment is not included in the `IssuanceAction` itself. As explained below, it is later computed by the validators and added to the `NoteCommitmentTree`. + + +Consensus Rule Changes +---------------------- + +For the IssueBundle: + +- Verify the RedPallas-based issuance authorization signature on `SIGHASH`, `issueAuthSig`, is verified by invoking `issueAuthSig.VerifySig(ik, SIGHASH)` + +For each `IssueAction` in `IssueBundle`: + +- check that :math:`0 < \mathsf{assetDescSize} <= 512`. +- check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathsf{assetDescSize}` bytes. +- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Asset Identifier`_ section. +- check that the :math:`\mathsf{AssetId}` does not exist in the ``previously_finalized`` set in the global state. +- check that every note in the `IssueAction` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})`. + +If all of the above checks pass, do the following: + +- For each note, compute the note commitment as :math:`\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}` as defined in the Note Structure and Commitment section of ZIP 226 [#zip-0226-notestructure]_ and +- add :math:`\mathsf{cm}` to the Merkle tree of note commitments, `NoteCommitmentTree`. +- If ``finalize = 1``, add :math:`\mathsf{AssetId}` to the ``previously_finalized`` set immediately after the block in which this transaction occurs. + + +Rationale +========= +The following is a list of rationale for different decisions made in the proposal: + +- The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools. +- The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”. +- The :math:`\mathsf{asset\_desc}` is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: + + - links for storage such as for NFTs. + - metadata for Assets, encoded in any format. + - bridging information for Wrapped Assets (chain of origin, issuer name, etc) + - information to be committed by the issuer, though not enforceable by the protocol. + +- We require a check whether the ``finalize`` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the ``previously_finalized`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. + +Concrete Applications +--------------------- + +**Asset Features** + +- By using the ``finalize`` boolean and the burning mechanism defined in [#zip-0226]_, issuers can control the supply production of any Asset associated to their issuer keys. For example, + + - by setting ``finalize = 1`` from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed. + +- Issuers can also stop the existing supply production of any Asset associated to their issuer keys. This could be done by + + - issuing a last set of tokens of that specific :math:`\mathsf{AssetId}`, for which ``finalize = 1``, or by + - issuing a transaction with a single note in the issuance action pertaining to that :math:`\mathsf{AssetId}`, where the note will contain a ``value = 0``. This can be used for application-specific purposes (NFT collections) or for security purposes to revoke the Asset issuance (see Security and Privacy Considerations). + - Note in the above cases, that the setting of the ``finalize`` flag will take effect at the block boundary, that is, after all the transactions in the block. + +- The issuance and burn mechanisms can be used in conjunction to determine the supply of Assets on the Zcash ecosystem. This allows for the bridging of Assets defined on other chains. + +- Furthermore, NFT issuance is enabled by issuing in a single bundle several issuance actions, where each :math:`\mathsf{AssetId}` corresponds to ``value = 1`` at the fundamental unit level. Issuers and users should make sure that ``finalize = 1`` for each of the actions in this scenario. + + + +TxId Digest +=========== + +As in ZIP 244 [#zip-0244]_, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used. + +A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:: + + issuance_txid_digest + ├── issue_actions_digest + └── issuanceValidatingKey + +In the specification below, nodes of the tree are presented in depth-first order. + +issuance_txid_digest +-------------------- +A BLAKE2b-256 hash of the following values :: + + T.1: issue_actions_digest (32-byte hash output) + T.2: issuanceValidatingKey (32 bytes) + +The personalization field of this hash is set to:: + + "ZTxIdSAIssueHash" + +In case the transaction has no issuance components, ''issue_actions_digest'' is:: + + BLAKE2b-256("ZTxIdSAIssueHash", []) + +T.1: issue_actions_digest +````````````````````````` +A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:: + + T.1a: notes_digest (32-byte hash output) + T.1b: assetDescription (field encoding bytes) + T.1c: flagsIssuance (1 byte) + +The personalization field of this hash is set to:: + + "ZTxIdIssActHash" + +T.1a: notes_digest +'''''''''''''''''' +A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:: + + T.1a.1: recipient (field encoding bytes) + T.1a.2: value (field encoding bytes) + T.1a.3: asset (field encoding bytes) + T.1a.4: rho (field encoding bytes) + T.1a.5: rseed (field encoding bytes) + +The personalization field of this hash is set to:: + + "ZTxIdIANoteHash" + +T.1a.1: recipient +................. +This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification [#protocol-orchardpaymentaddrencoding]_. + +T.1a.2: value +............. +Note value encoded as little-endian 8-byte representation of u64 raw value. + +T.1a.3: asset +............. +Asset Base encoded as 32-byte representation of Pallas point. + +T.1a.4: rho +........... +Nullifier encoded as 32-byte representation of Pallas point. + +T.1a.5: rseed +............. +The ZIP 212 32-byte seed randomness for a note. + +T.1b: assetDescription +'''''''''''''''''''''' +UTF-8 encoding of the Asset description string. + +T.1c: flagsIssuance +''''''''''''''''''' +An 8-bit value representing a set of flags. Ordered from LSB to MSB: + +- ``finalize`` +- The remaining bits are set to `0`. + + +T.2: issuanceValidatingKey +`````````````````````````` +A byte encoding of issuance validating key for the bundle as defined in the `Issuance Key Derivation`_ section. + + +Security and Privacy Considerations +=================================== + +**Issuer Key or AssetId Compromise** + +The design of this protocol does not allow for a rotation of the issuer validating key, that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended: + +- If an issuer validating key is compromised, the ``finalize`` boolean for all the Assets issued with that key should be set to `1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`. + +**Bridging Assets** +For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 [#zip-0226]_. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset. + +Other Considerations +==================== + +Implementing Zcash Nodes +------------------------ + +Although not enforced in the global state, it is RECOMMENDED that Zcash full validators keep track of the total supply of Assets as a mutable mapping `issuanceSupplyInfoMap` from :math:`\mathsf{AssetId}` to :math:`\mathsf{issuanceSupplyInfoMap := (totalSupply, finalize)}` in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets. + +Fee Structures +-------------- + +The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b [#zip-0317b]_. + +Future Work +----------- + +In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying :math:`\mathsf{ik}` of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether. + +Test Vectors +============ + +- LINK TBD + +Reference Implementation +======================== + +- LINK TBD +- LINK TBD + +Deployment +========== + +This ZIP is proposed to activate with Network Upgrade 6. + +References +========== + +.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ +.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism `_ +.. [#zip-0224] `ZIP 224: Orchard `_ +.. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ +.. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ +.. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ +.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0317b] `ZIP 317b: ZSA Extension Proportional Fee Mechanism `_ +.. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ +.. [#zip-0032-orchard-master] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation `_ +.. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ +.. [#protocol-addressesandkeys] `Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys `_ +.. [#protocol-concretegrouphashpallasandvesta] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta `_ +.. [#protocol-orchardkeycomponents] `Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components `_ +.. [#protocol-spendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard) `_ +.. [#protocol-concretespendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard) `_ +.. [#protocol-orchardpaymentaddrencoding] `Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses `_ +.. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) `_ \ No newline at end of file From 16198c68a33c2f9c1e80ff3bde488daf0c399ad9 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Mon, 17 Apr 2023 13:45:18 +0530 Subject: [PATCH 02/42] Update zip-0226.rst Co-authored-by: Daira Hopwood --- zip-0226.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/zip-0226.rst b/zip-0226.rst index d42ffab57..623ca7aad 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -25,7 +25,8 @@ The key word "MUST" in this document is to be interpreted as described in RFC 21 The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. -The term "Orchard" in this document is to be interpreted as described in ZIP 224 [#zip-0224]_. +The terms "Orchard" and "Action" in this document are to be interpreted as described in +ZIP 224 [#zip-0224]_. We define the following additional terms: From 17d255abeb2d144acc4baa7c7052c79d07283267 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Mon, 17 Apr 2023 15:01:59 +0530 Subject: [PATCH 03/42] Apply suggestions from ZIP review Includes improvements to mathematical notation, and typographical edits. Co-authored-by: Daira Hopwood Co-authored-by: Deirdre Connolly --- zip-0226.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/zip-0226.rst b/zip-0226.rst index 623ca7aad..e2ea9a985 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -49,7 +49,8 @@ of protocol features that enable the creation, transfer, and burn of Custom Asse Creation of such Assets is defined in ZIP 227 [#zip-0227]_. Transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. The ZSA protocol is proposed to be instantiated by a modification to the -Orchard protocol, as specified in these ZIPs. +Orchard protocol, as specified in these ZIPs (although it has been designed with adaption +to possible future shielded protocols in mind). Motivation ========== @@ -65,13 +66,13 @@ In order to be able to represent different Assets, we need to define a data fiel This Asset Identifier maps to an Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 [#zip-0227]_. -The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description [#protocol-actions]_ is preserved across Assets (see the Orchard Binding Signature [#protocol-binding]_), and by extension the balance of an Orchard transaction. That is, the sum of all the :math:`\mathsf{value^{net}}` from each Action Description, computed as :math:`\mathsf{value^{old}-value^{new}}`, must be balanced **only with respect to the same Asset Identifier**. This is specially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred. +The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description [#protocol-actions]_ is preserved across Assets (see the Orchard Binding Signature [#protocol-binding]_), and by extension the balance of an Orchard transaction. That is, the sum of all the :math:`\mathsf{value^{net}}` from each Action Description, computed as :math:`\mathsf{value^{old}-value^{new}}`, must be balanced **only with respect to the same Asset Identifier**. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred. As was initially proposed by Jack Grigg and Daira Hopwood [#initial-zsa-issue]_ [#generalized-value-commitments]_, we propose to make this happen by changing the value base point, :math:`\mathcal{V}^{\mathsf{Orchard}}`, in the Homomorphic Pedersen Commitment that derives the value commitment, :math:`\mathsf{cv^{net}}`, of the *net value* in an Orchard Action. -Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` an auxiliary input to the proof for each Action statement [#protocol-actionstatement]_, represented already as a point on the Pallas curve. The circuit then should check that the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` is used in the old note commitment and the new note commitment [#protocol-concretesinsemillacommit]_, **and** as the base point :math:`\mathcal{V}^\mathsf{Orchard}` in the value commitment [#protocol-concretevaluecommit]_. This ensures (1) that the input and output notes are of the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`, and (2) that only actions with the same Asset Base will balance out in the Orchard binding signature. +Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` an auxiliary input to the proof for each Action statement [#protocol-actionstatement]_, represented already as a point on the Pallas curve. The circuit then should check that the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` is used in the old note commitment and the new note commitment [#protocol-concretesinsemillacommit]_, **and** as the base point :math:`\mathcal{V}^\mathsf{Orchard}` in the value commitment [#protocol-concretevaluecommit]_. This ensures (1) that the input and output notes are of the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature. -In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the output note of that split Action is the output of a valid :math:`\mathsf{ZSAValueBase^{Orchard}}` computation defined in ZIP 227 [#zip-0227]_. +In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the output note of that Split Action is the output of a valid :math:`\mathsf{ZSAValueBase^{Orchard}}` computation defined in ZIP 227 [#zip-0227]_. Finally, in this ZIP we also describe the *burn* mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the :math:`\mathsf{valueBalance}` of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets. @@ -83,35 +84,35 @@ Most of the protocol is kept the same as the Orchard protocol released with NU5, Asset Identifiers ----------------- -For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}` , the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. +For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. -In future network and protocol upgrades, the same Asset description string can be carried on, with potentially a mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base from one shielded protocol to another. +In future network and protocol upgrades, the same Asset description string can be carried on, potentially mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base from one shielded protocol to another. Note Structure & Commitment --------------------------- Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e. -:math:`\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P*}`. +:math:`\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*`. A ZSA note differs from an Orchard note [#protocol-notes]_ by additionally including the Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. So a ZSA note is a tuple :math:`(\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})`, where -- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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]_. The byte representation of the Asset Base is defined as :math:`\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})`. +- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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]_. The byte representation of the Asset Base is defined as :math:`\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})`. Specifically, we define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows: -.. math:: \mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \{0 .. 2^{l_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P*} \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output} +.. math:: \mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output} -where :math:`\mathbb{P}, l_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, and :math:`\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}` are as defined in the Zcash protocol specification [#protocol-abstractcommit]_. +where :math:`\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, and :math:`\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \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}^{\mathsf{Orchard}})} :=\begin{cases} - \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{... if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ - \mathsf{cm}_{\mathsf{ZSA}} &\text{... otherwise} + \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ + \mathsf{cm^{OrchardZSA}} &\text{otherwise} \end{cases} \end{align} @@ -119,7 +120,7 @@ where (note that :math:`\mathsf{repr}_{\mathbb{P}}` is as defined for the Pallas .. math:: \begin{align} \mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ - &\mathsf{g_{d}*}\; \| \; \mathsf{pk_{d}*}\; \| \; \mathsf{I2LEBSP_{64}(v)}\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho)\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi)\; \| \; \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) + &\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \end{align} The nullifier is generated in the same manner as in the Orchard protocol [#protocol-commitmentsandnullifiers]_. From a2270aabcb5ac620be2d284423309855e14be1db Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Mon, 17 Apr 2023 15:48:46 +0530 Subject: [PATCH 04/42] Changes to issuance key derivation details (#8) This covers the changes made to derive the issuance key independently of the Orchard key structure, using the techniques from [ZIP 32](https://zips.z.cash/zip-0032). --- zip-0227.html | 378 +++++++++++++++++++++++++++++--------------------- zip-0227.rst | 81 +++++++---- 2 files changed, 268 insertions(+), 191 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index ff51aae3b..03e102c91 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -63,46 +63,81 @@
  • Every "issuance action" should contain a finalize boolean that defines whether the specific Custom Asset can have further tokens issued or not.
    • -

    Specification

    -

    As explained, the issuance protocol allows for a single issuance action to be sent to many receivers, by generating as many output notes as distinct recipients. Furthermore, every bundle can contain many issuance actions.

    -

    Issuance Keys and Issuance Authorization Signature Scheme

    -

    The ZSA Protocol adds the following three keys to the key components 12:

    -
      -
    1. The issuance master key, denoted as - \(\mathsf{sk}_{\mathsf{iss}}\) - , as the name suggests, is the master key that is used to derive the other two keys.
      2. -
    2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as - \(\mathsf{isk}\) - . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
      3. -
    3. The issuance validating key, denoted as - \(\mathsf{ik}\) - , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
      4. -
    -

    Issuance Authorization Signature Scheme

    -

    We define the issuance authorization signature scheme - \(\mathsf{IssueAuthSig}\) - similar to - \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) - , the Orchard spend authorization signature scheme 16. Specifically, we instantiate - \(\mathsf{IssueAuthSig}\) - as - \(\mathsf{RedPallas}\) - without key re-randomization using generator - \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) - where - \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in the Zcash protocol specification 13.

    -
    -

    Issuance Key Derivation

    -

    The issuance master key is generated by choosing a bit sequence uniformly at random from - \(\mathbb{B}^{\mathbb{Y}[32]}\) - , like the Orchard spending key 14. In - \(\mathsf{zcashd}\) - , this key is derived in a manner similar to the generation of the Orchard master key in ZIP 32 10, as detailed below:

    +

    Specification: Issuance Keys and Issuance Authorization Signature Scheme

    +

    The ZSA Protocol adds the following three keys to the key components 15:

    +
      +
    1. The issuance master key, denoted as + \(\mathsf{sk}_{\mathsf{iss}}\) + , as the name suggests, is the master key that is used to derive the other two keys.
      2. +
    2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as + \(\mathsf{isk}\) + . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
      3. +
    3. The issuance validating key, denoted as + \(\mathsf{ik}\) + , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
      4. +
    +

    The relations between these keys are shown in the following diagram:

    +
    + +
    Diagram of Issuance Key Components for the ZSA Protocol
    +
    +

    Issuance Authorization Signature Scheme

    +

    We define the issuance authorization signature scheme + \(\mathsf{IssueAuthSig}\) + similar to + \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) + , the Orchard spend authorization signature scheme 19. Specifically, we instantiate + \(\mathsf{IssueAuthSig}\) + as + \(\mathsf{RedPallas}\) + without key re-randomization using generator + \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) + where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in the Zcash protocol specification 16.

    +
    +

    Issuance Key Derivation

    +

    The issuance master key is generated by choosing a bit sequence uniformly at random from + \(\mathbb{B}^{\mathbb{Y}[32]}\) + , like the Orchard spending key 17.

    +

    Issuance master key derivation for hierarchical deterministic wallets

    +

    The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 10. We reuse the functions defined there in what follows in this section.

    +

    Let + \(S\) + be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key + \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssuance"}, S)\) + .

    +

    As in ZIP 32 for Orchard 11, we only use hardened child key derivation for the issuance master key. We reuse the + \(\mathsf{CDKsk}\) + function for Orchard child key derivation from ZIP 32.

    +

    We use the notation of ZIP 32 13 for shielded HD paths, and define the issuance master key path as + \(m_\mathsf{Issuance} / purpose / coin\_type' / account'\) + . We fix the path levels as follows:

      -
    • Details TBD
      • +
    • + \(purpose\) + : a constant set to + \(227'\) + (or + \(\texttt{0x800000e3}\) + ) following the BIP 43 recommendation.
      • +
    • + \(coin\_type\) + : Defined as in ZIP 32 12.
      • +
    • + \(account\) + : fixed to index + \(0\) + .
    -

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 14, as described below.

    +

    Given the extended issuance master key + \((\mathsf{sk}, \mathsf{c})\) + , we set the issuance master key to be + \(\mathsf{sk_{iss}} := \mathsf{sk}\) + .

    +
    +

    Derivation of issuance authorizing key and issuance validating key

    +

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 17, as described below.

    • The issuance authorizing key is derived from the issuance master key, \(\mathsf{sk}_{\mathsf{iss}}\) @@ -115,70 +150,67 @@ , as a public verification key:
    \(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
    -

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 9. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    -

    The derivation of these keys are shown in the following diagram:

    -
    - -
    Diagram of Issuance Key Components for the ZSA Protocol
    -
    +

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 9. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    -

    Asset Identifier

    -

    For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair - \((\mathsf{ik}, \mathsf{asset\_desc})\) - , where - \(\mathsf{ik}\) - is the issuance key and +

    +

    Specification: Asset Identifier

    +

    For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair + \((\mathsf{ik}, \mathsf{asset\_desc})\) + , where + \(\mathsf{ik}\) + is the issuance key and + \(\mathsf{asset\_desc}\) + is a byte string.

    +

    A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, + \(\mathsf{AssetDigest}\) + , which is simply is a + \(\textsf{BLAKE2b-512}\) + hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

    +

    Let

    +
      +
    • \(\mathsf{asset\_desc}\) - is a byte string.

      -

      A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, - \(\mathsf{AssetDigest}\) - , which is simply is a - \(\textsf{BLAKE2b-512}\) - hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) - for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

      -

      Let

      -
        -
      • - \(\mathsf{asset\_desc}\) - be the asset description, a UTF-8 encoded string of up to 512 bytes, which includes any information pertaining to the issuance.
        • -
      • - \(\mathsf{ik}\) - be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
        • -
      -

      Define - \(\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\) - , where

      -
        -
      • - \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) - .
        • -
      -

      Define - \(\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\) - , where

      -

      In the case of Orchard, we define - \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\) - where - \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 13.

      -

      The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

      -
      - -
      Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol
      -
      -
    -

    Global Issuance State

    -

    Issuance requires the following additions to the global state defined at block boundaries:

    -
      -
    • - \(\mathsf{previously\_finalized}\) - , a set of - \(\mathsf{AssetId}\) - that have been finalized (i.e.: the finalize flag has been set to 1 in some issuance transaction preceding the block boundary).
      • -
    -
    + be the asset description, a UTF-8 encoded string of up to 512 bytes, which includes any information pertaining to the issuance. +
  • + \(\mathsf{ik}\) + be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
    • + +

    Define + \(\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\) + , where

    +
      +
    • + \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) + .
      • +
    +

    Define + \(\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\) + , where

    +

    In the case of Orchard, we define + \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\) + where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in 16.

    +

    The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

    +
    + +
    Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol
    +
    +
    +

    Specification: Global Issuance State

    +

    Issuance requires the following additions to the global state defined at block boundaries:

    +
      +
    • + \(\mathsf{previously\_finalized}\) + , a set of + \(\mathsf{AssetId}\) + that have been finalized (i.e.: the finalize flag has been set to 1 in some issuance transaction preceding the block boundary).
      • +
    +
    +

    Specification: Issuance Action, Issuance Bundle and Issuance Protocol

    Issuance Action Description

    An issuance action, IssueAction, is the instance of issuing a specific custom Asset, and contains the following fields:

      @@ -271,7 +303,7 @@ \(\mathsf{isk}\) , that validates the issuance .
    -

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 18.

    +

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 21.

    @@ -324,12 +356,12 @@ \(\mathsf{ik}\) and \(\mathsf{asset\_desc}\) - as decribed in the Asset Identifier section. + as decribed in the Specification: Asset Identifier section.
  • compute \(\mathsf{AssetBase^{Protocol}}\) from \(\mathsf{AssetDigest}\) - as decribed in the Asset Identifier section.
    • + as decribed in the Specification: Asset Identifier section.
  • set the finalize boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
  • For each recipient \(i\) @@ -356,52 +388,52 @@

    NOTE that the commitment is not included in the IssuanceAction itself. As explained below, it is later computed by the validators and added to the NoteCommitmentTree.

    -

    Consensus Rule Changes

    -

    For the IssueBundle:

    -
      -
    • Verify the RedPallas-based issuance authorization signature on SIGHASH, issueAuthSig, is verified by invoking issueAuthSig.VerifySig(ik, SIGHASH)
      • -
    -

    For each IssueAction in IssueBundle:

    -
      -
    • check that - \(0 < \mathsf{assetDescSize} <= 512\) - .
      • -
    • check that - \(\mathsf{asset\_desc}\) - is a string of length - \(\mathsf{assetDescSize}\) - bytes.
      • -
    • retrieve - \(\mathsf{AssetBase}\) - from the first note in the sequence and check that - \(\mathsf{AssetBase}\) - is derived from the issuance validating key - \(\mathsf{ik}\) - and - \(\mathsf{asset\_desc}\) - as described in the Asset Identifier section.
      • -
    • check that the - \(\mathsf{AssetId}\) - does not exist in the previously_finalized set in the global state.
      • -
    • check that every note in the IssueAction contains the same - \(\mathsf{AssetBase}\) - and is properly constructed as - \(note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})\) - .
      • -
    -

    If all of the above checks pass, do the following:

    -
      -
    • For each note, compute the note commitment as - \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) - as defined in the Note Structure and Commitment section of ZIP 226 5 and
      • -
    • add - \(\mathsf{cm}\) - to the Merkle tree of note commitments, NoteCommitmentTree.
      • -
    • If finalize = 1, add - \(\mathsf{AssetId}\) - to the previously_finalized set immediately after the block in which this transaction occurs.
      • -
    -
    + +

    Specification: Consensus Rule Changes

    +

    For the IssueBundle:

    +
      +
    • Verify the RedPallas-based issuance authorization signature on SIGHASH, issueAuthSig, is verified by invoking issueAuthSig.VerifySig(ik, SIGHASH)
      • +
    +

    For each IssueAction in IssueBundle:

    +
      +
    • check that + \(0 < \mathsf{assetDescSize} <= 512\) + .
      • +
    • check that + \(\mathsf{asset\_desc}\) + is a string of length + \(\mathsf{assetDescSize}\) + bytes.
      • +
    • retrieve + \(\mathsf{AssetBase}\) + from the first note in the sequence and check that + \(\mathsf{AssetBase}\) + is derived from the issuance validating key + \(\mathsf{ik}\) + and + \(\mathsf{asset\_desc}\) + as described in the Specification: Asset Identifier section.
      • +
    • check that the + \(\mathsf{AssetId}\) + does not exist in the previously_finalized set in the global state.
      • +
    • check that every note in the IssueAction contains the same + \(\mathsf{AssetBase}\) + and is properly constructed as + \(note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})\) + .
      • +
    +

    If all of the above checks pass, do the following:

    +
      +
    • For each note, compute the note commitment as + \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) + as defined in the Note Structure and Commitment section of ZIP 226 5 and
      • +
    • add + \(\mathsf{cm}\) + to the Merkle tree of note commitments, NoteCommitmentTree.
      • +
    • If finalize = 1, add + \(\mathsf{AssetId}\) + to the previously_finalized set immediately after the block in which this transaction occurs.
      • +

    Rationale

    The following is a list of rationale for different decisions made in the proposal:

    @@ -423,7 +455,7 @@

    Concrete Applications

    Asset Features

      -
    • By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example, +
    • By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example,
      • by setting finalize = 1 from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed.
      @@ -447,7 +479,7 @@

    TxId Digest

    -

    As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

    +

    As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

    A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

    issuance_txid_digest
 ├── issue_actions_digest
@@ -478,7 +510,7 @@
                         
    The personalization field of this hash is set to:
    
                         
    "ZTxIdIANoteHash"
    
                         
    T.1a.1: recipient 
    
-                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 17.
    
+                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 20.
    
                         
    
                         
    T.1a.2: value 
    
                             
    Note value encoded as little-endian 8-byte representation of u64 raw value.
    
@@ -517,7 +549,7 @@
                     \(\mathsf{AssetId}\)
                 .
    • -

    Bridging Assets For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

    +

    Bridging Assets For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

    Other Considerations

    Implementing Zcash Nodes

    @@ -528,7 +560,7 @@ in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

    Fee Structures

    -

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 8.

    +

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 8.

    Future Work

    In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying @@ -631,10 +663,34 @@

    - +
    + + + +
    11ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation
    + + + + + + + +
    12ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels
    + + + + + + + +
    13ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path
    + + + + @@ -642,7 +698,7 @@
    14 ZIP 316: Unified Addresses and Unified Viewing Keys
    - + @@ -650,7 +706,7 @@
    1215 Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
    - + @@ -658,7 +714,7 @@
    1316 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
    - + @@ -666,7 +722,7 @@
    1417 Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
    - + @@ -674,7 +730,7 @@
    1518 Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -682,7 +738,7 @@
    1619 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -690,7 +746,7 @@
    1720 Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
    - + diff --git a/zip-0227.rst b/zip-0227.rst index 879232ad0..cf9b094b5 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -72,13 +72,8 @@ Requirements - Every "issuance action" should contain a ``finalize`` boolean that defines whether the specific Custom Asset can have further tokens issued or not. -Specification -============= - -As explained, the issuance protocol allows for a single issuance action to be sent to many receivers, by generating as many output notes as distinct recipients. Furthermore, every bundle can contain many issuance actions. - -Issuance Keys and Issuance Authorization Signature Scheme ---------------------------------------------------------- +Specification: Issuance Keys and Issuance Authorization Signature Scheme +======================================================================== The ZSA Protocol adds the following three keys to the key components [#protocol-addressesandkeys]_: @@ -88,19 +83,48 @@ The ZSA Protocol adds the following three keys to the key components [#protocol- 3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. +The relations between these keys are shown in the following diagram: + +.. figure:: zip-0227-key-components-zsa.png + :width: 450px + :align: center + :figclass: align-center + + Diagram of Issuance Key Components for the ZSA Protocol + + Issuance Authorization Signature Scheme -``````````````````````````````````````` +--------------------------------------- We define the issuance authorization signature scheme :math:`\mathsf{IssueAuthSig}` similar to :math:`\mathsf{SpendAuthSig}^{\mathsf{Orchard}}`, the Orchard spend authorization signature scheme [#protocol-concretespendauthsig]_. Specifically, we instantiate :math:`\mathsf{IssueAuthSig}` as :math:`\mathsf{RedPallas}` without key re-randomization using generator :math:`\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})` where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in the Zcash protocol specification [#protocol-concretegrouphashpallasandvesta]_. Issuance Key Derivation -``````````````````````` +----------------------- The issuance master key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_. -In :math:`\mathsf{zcashd}`, this key is derived in a manner similar to the generation of the Orchard master key in ZIP 32 [#zip-0032-orchard-master]_, as detailed below: -- Details TBD +Issuance master key derivation for hierarchical deterministic wallets +````````````````````````````````````````````````````````````````````` + +The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section. + +Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. +We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssuance"}, S)`. + +As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key. +We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32. + +We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose / coin\_type' / account'`. We fix the path levels as follows: + +- :math:`purpose`: a constant set to :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. +- :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_. +- :math:`account`: fixed to index :math:`0`. + +Given the *extended issuance master key* :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance master key to be :math:`\mathsf{sk_{iss}} := \mathsf{sk}`. + +Derivation of issuance authorizing key and issuance validating key +`````````````````````````````````````````````````````````````````` The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below. @@ -114,18 +138,8 @@ The issuance authorizing key and issuance validating key are derived from the is This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe. -The derivation of these keys are shown in the following diagram: - -.. figure:: zip-0227-key-components-zsa.png - :width: 450px - :align: center - :figclass: align-center - - Diagram of Issuance Key Components for the ZSA Protocol - - -Asset Identifier ----------------- +Specification: Asset Identifier +=============================== For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair :math:`(\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. @@ -158,13 +172,17 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol -Global Issuance State ---------------------- +Specification: Global Issuance State +==================================== Issuance requires the following additions to the global state defined at block boundaries: - :math:`\mathsf{previously\_finalized}`, a set of :math:`\mathsf{AssetId}` that have been finalized (i.e.: the ``finalize`` flag has been set to ``1`` in some issuance transaction preceding the block boundary). + +Specification: Issuance Action, Issuance Bundle and Issuance Protocol +================================================================================= + Issuance Action Description --------------------------- @@ -216,8 +234,8 @@ The issuer program performs the following operations For all actions `IssueAction`: - encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512. -- compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Asset Identifier`_ section. -- compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Asset Identifier`_ section. +- compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section. +- compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section. - set the ``finalize`` boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``) - For each recipient :math:`i`: @@ -235,8 +253,8 @@ For the `IssueBundle`: NOTE that the commitment is not included in the `IssuanceAction` itself. As explained below, it is later computed by the validators and added to the `NoteCommitmentTree`. -Consensus Rule Changes ----------------------- +Specification: Consensus Rule Changes +===================================== For the IssueBundle: @@ -246,7 +264,7 @@ For each `IssueAction` in `IssueBundle`: - check that :math:`0 < \mathsf{assetDescSize} <= 512`. - check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathsf{assetDescSize}` bytes. -- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Asset Identifier`_ section. +- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Specification: Asset Identifier`_ section. - check that the :math:`\mathsf{AssetId}` does not exist in the ``previously_finalized`` set in the global state. - check that every note in the `IssueAction` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})`. @@ -443,6 +461,9 @@ References .. [#zip-0317b] `ZIP 317b: ZSA Extension Proportional Fee Mechanism `_ .. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ .. [#zip-0032-orchard-master] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation `_ +.. [#zip-0032-orchard-child-key-derivation] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation `_ +.. [#zip-0032-key-path-levels] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels `_ +.. [#zip-0032-orchard-key-path] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path `_ .. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ .. [#protocol-addressesandkeys] `Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys `_ .. [#protocol-concretegrouphashpallasandvesta] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta `_ From 23ef13d031fde0785671995008cedc6348a772d1 Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Mon, 17 Apr 2023 15:52:23 +0530 Subject: [PATCH 05/42] updating html file based on earlier commits --- zip-0226.html | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 5241a9763..6730e3299 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -26,7 +26,7 @@

    Terminology

    The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

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

    -

    The term "Orchard" in this document is to be interpreted as described in ZIP 224 3.

    +

    The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 3.

    We define the following additional terms:

    • Asset: A type of note that can be transferred on the Zcash block chain, identified by the @@ -48,7 +48,7 @@

    Abstract

    ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol &mdash; a set of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain.

    -

    Creation of such Assets is defined in ZIP 227 5. Transfer and burn of such Assets is defined in ZIP 226 4. The ZSA protocol is proposed to be instantiated by a modification to the Orchard protocol, as specified in these ZIPs.

    +

    Creation of such Assets is defined in ZIP 227 5. Transfer and burn of such Assets is defined in ZIP 226 4. The ZSA protocol is proposed to be instantiated by a modification to the Orchard protocol, as specified in these ZIPs (although it has been designed with adaption to possible future shielded protocols in mind).

    Motivation

    None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes.

    @@ -63,7 +63,7 @@ \(\mathsf{value^{net}}\) from each Action Description, computed as \(\mathsf{value^{old}-value^{new}}\) - , must be balanced only with respect to the same Asset Identifier. This is specially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

    + , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

    As was initially proposed by Jack Grigg and Daira Hopwood 22 23, we propose to make this happen by changing the value base point, \(\mathcal{V}^{\mathsf{Orchard}}\) , in the Homomorphic Pedersen Commitment that derives the value commitment, @@ -77,10 +77,10 @@ \(\mathcal{V}^\mathsf{Orchard}\) in the value commitment 18. This ensures (1) that the input and output notes are of the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - , and (2) that only actions with the same Asset Base will balance out in the Orchard binding signature.

    + , and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

    In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 19 for Custom Assets, as we need to enforce that the \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - of the output note of that split Action is the output of a valid + of the output note of that Split Action is the output of a valid \(\mathsf{ZSAValueBase^{Orchard}}\) computation defined in ZIP 227 5.

    Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the @@ -94,7 +94,7 @@ \(\mathsf{asset\_desc}\) , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, \(\mathsf{AssetId}\) - , the Asset Digest, and the Asset Base ( + , the Asset Digest, and the Asset Base ( \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 5.

    This @@ -104,7 +104,7 @@ of the ZEC Asset will be kept as the original value base point, \(\mathcal{V}^\mathsf{Orchard}\) .

    -

    In future network and protocol upgrades, the same Asset description string can be carried on, with potentially a mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, +

    In future network and protocol upgrades, the same Asset description string can be carried on, potentially mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, \(\mathsf{AssetId}\) , the Asset Digest, and the Asset Base from one shielded protocol to another.

    @@ -112,7 +112,7 @@

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

    A ZSA note differs from an Orchard note 6 by additionally including the Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) @@ -121,7 +121,7 @@ , where

    • - \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P*}\) + \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) is the unique element of the Pallas group 14 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 5. The byte representation of the Asset Base is defined as \(\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .
      • @@ -129,17 +129,17 @@

      Specifically, we define the note commitment scheme \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) as follows:

      -
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \mathbb{B}^{[l_{\mathbb{P}}]} \times \{0 .. 2^{l_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P*} \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)
      +
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)

      where - \(\mathbb{P}, l_{\mathbb{P}}, q_{\mathbb{P}}\) + \(\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}\) are as defined for the Pallas curve 14, and \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) are as defined in the Zcash protocol specification 9. This note commitment scheme is instantiated using the Sinsemilla Commitment 17 as follows:

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

      where (note that @@ -151,7 +151,7 @@ is as defined in §5.1 12 of the Zcash protocol specification):

      \(\begin{align} \mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ -&\mathsf{g_{d}*}\; \| \; \mathsf{pk_{d}*}\; \| \; \mathsf{I2LEBSP_{64}(v)}\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\rho)\; \| \; \mathsf{I2LEBSP}_{l^{\mathsf{Orchard}}_{\mathsf{base}}}(\psi)\; \| \; \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) +&\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \end{align}\)

      The nullifier is generated in the same manner as in the Orchard protocol 11.

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 7. It consists of

      From ef71dda27a8aa6ea3677cf2938631fa6189f0579 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Mon, 8 May 2023 09:59:30 +0530 Subject: [PATCH 06/42] Rearrangements and minor changes to the Security and Privacy Considerations (#13) Minor changes to the Security and Privacy Considerations to make it more in line with the format specified in ZIP 0. --- zip-0226.html | 30 +++++++++++++++--------------- zip-0226.rst | 23 ++++++++++++----------- zip-0227.html | 21 +++++++++++++-------- zip-0227.rst | 11 +++++++---- 4 files changed, 47 insertions(+), 38 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 6730e3299..1bff6e08e 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -424,25 +424,25 @@ \(\mathsf{AssetId}\) ). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action.

      +

      Security and Privacy Considerations

      +
        +
      • Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure.
        • +
      • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
        • +
      • We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
        • +
      • Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. +
          +
        • One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
          • +
        +
        • +
      +

      Other Considerations

      Transaction Fees

      The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 24.

      -

      Security and Privacy

      -
        -
      • Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure.
        • -
      • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
        • -
      • We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
        • -
      • Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. -
          -
        • One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
          • -
        -
        • -
      -
      -

      Deployment

      -

      The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions.

      -
      +
      +

      Deployment

      +

      The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions.

      Test Vectors

        diff --git a/zip-0226.rst b/zip-0226.rst index e2ea9a985..7a1b1aa8d 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -306,16 +306,8 @@ The transaction format is similar to the version 5 transaction format described In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the :math:`\mathsf{AssetId}`). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action. -Other Considerations -==================== - -Transaction Fees ----------------- - -The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade [#zip-0317b]_. - -Security and Privacy --------------------- +Security and Privacy Considerations +=================================== - Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure. - When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design. @@ -324,8 +316,17 @@ Security and Privacy - One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. +Other Considerations +==================== + +Transaction Fees +---------------- + +The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade [#zip-0317b]_. + Deployment ------------ +========== + The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions. Test Vectors diff --git a/zip-0227.html b/zip-0227.html index 03e102c91..79be37b76 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -542,14 +542,19 @@

      Security and Privacy Considerations

      -

      Issuer Key or AssetId Compromise

      -

      The design of this protocol does not allow for a rotation of the issuer validating key, that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended:

      -
        -
      • If an issuer validating key is compromised, the finalize boolean for all the Assets issued with that key should be set to 1 and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new - \(\mathsf{AssetId}\) - .
        • -
      -

      Bridging Assets For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

      +

      Issuance Key Compromise

      +

      The design of this protocol does not currently allow for a rotation of the issuance validating key that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended:

      +
        +
      • If an issuance validating key is compromised, the finalize boolean for all the Assets issued with that key should be set to + \(1\) + and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new + \(\mathsf{AssetId}\) + .
        • +
      +
      +

      Bridging Assets

      +

      For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

      +

      Other Considerations

      Implementing Zcash Nodes

      diff --git a/zip-0227.rst b/zip-0227.rst index cf9b094b5..f0fc92a03 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -405,13 +405,16 @@ A byte encoding of issuance validating key for the bundle as defined in the `Iss Security and Privacy Considerations =================================== -**Issuer Key or AssetId Compromise** +Issuance Key Compromise +----------------------- + +The design of this protocol does not currently allow for a rotation of the issuance validating key that would allow for replacing the key of a specific Asset (see `Future Work`_). In case of compromise, the following actions are recommended: -The design of this protocol does not allow for a rotation of the issuer validating key, that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended: +- If an issuance validating key is compromised, the ``finalize`` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`. -- If an issuer validating key is compromised, the ``finalize`` boolean for all the Assets issued with that key should be set to `1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`. +Bridging Assets +--------------- -**Bridging Assets** For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 [#zip-0226]_. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset. Other Considerations From ae57a85f81dbc279ea1c6fa1c6d8c8f01c1f9a79 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 9 May 2023 18:42:18 +0530 Subject: [PATCH 07/42] Rearranging ZIP structure (#14) This rearranges and rewrites various sections of the ZIP to make it more in line with the suggestions in ZIP 0. It also updates the Split Notes, Circuit Statement and Burn Mechanism sections with more information. --- zip-0226.html | 508 +++++++++++++++++++++++++++----------------------- zip-0226.rst | 178 ++++++++++-------- zip-0227.html | 15 +- zip-0227.rst | 22 ++- 4 files changed, 397 insertions(+), 326 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 1bff6e08e..6636fb043 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -22,11 +22,11 @@ Created: 2022-05-01 License: MIT Discussions-To: <https://github.com/zcash/zips/issues/618> -Pull-Request: <https://github.com/zcash/zips/pull/676> +Pull-Request: <https://github.com/zcash/zips/pull/680>

      Terminology

      The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

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

      -

      The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 3.

      +

      The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 4.

      We define the following additional terms:

      • Asset: A type of note that can be transferred on the Zcash block chain, identified by the @@ -40,15 +40,15 @@
      • Native Asset: a Custom Asset with issuance defined on the Zcash block chain.
      • Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash block chain.
        • -
      • Split Input: an Action input identifying a Custom Asset note, used to ensure that the output note of that Action is of a validly issued - \(\mathsf{AssetId}\) - when there is no corresponding real input note to spend. The Action does not spend the note identified by the Split Input.
        • +
      • Split Input: an Action input used to ensure that the output note of that Action is of a validly issued + \(\mathsf{AssetBase}\) + when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in Split Notes.
      • Split Action: an Action that contains a Split Input.

      Abstract

      -

      ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol &mdash; a set of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain.

      -

      Creation of such Assets is defined in ZIP 227 5. Transfer and burn of such Assets is defined in ZIP 226 4. The ZSA protocol is proposed to be instantiated by a modification to the Orchard protocol, as specified in these ZIPs (although it has been designed with adaption to possible future shielded protocols in mind).

      +

      ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol — a set of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain.

      +

      Creation of such Assets is defined in ZIP 227 6. Transfer and burn of such Assets is defined in ZIP 226 5. The ZSA protocol is proposed to be instantiated by a modification to the Orchard protocol, as specified in these ZIPs (although it has been designed with adaption to possible future shielded protocols in mind).

      Motivation

      None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes.

      @@ -58,31 +58,31 @@ \(\mathsf{AssetId}\) . This Asset Identifier maps to an Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 5.

      -

      The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 8 is preserved across Assets (see the Orchard Binding Signature 10), and by extension the balance of an Orchard transaction. That is, the sum of all the + that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 6.

      +

      The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 9 is preserved across Assets (see the Orchard Binding Signature 11), and by extension the balance of an Orchard transaction. That is, the sum of all the \(\mathsf{value^{net}}\) from each Action Description, computed as \(\mathsf{value^{old}-value^{new}}\) , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

      -

      As was initially proposed by Jack Grigg and Daira Hopwood 22 23, we propose to make this happen by changing the value base point, +

      As was initially proposed by Jack Grigg and Daira Hopwood 23 24, we propose to make this happen by changing the value base point, \(\mathcal{V}^{\mathsf{Orchard}}\) , in the Homomorphic Pedersen Commitment that derives the value commitment, \(\mathsf{cv^{net}}\) , of the net value in an Orchard Action.

      Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - an auxiliary input to the proof for each Action statement 20, represented already as a point on the Pallas curve. The circuit then should check that the same + an auxiliary input to the proof for each Action statement 21, represented already as a point on the Pallas curve. The circuit then should check that the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - is used in the old note commitment and the new note commitment 17, and as the base point + is used in the old note commitment and the new note commitment 18, and as the base point \(\mathcal{V}^\mathsf{Orchard}\) - in the value commitment 18. This ensures (1) that the input and output notes are of the same + in the value commitment 19. This ensures (1) that the input and output notes are of the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) , and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

      -

      In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 19 for Custom Assets, as we need to enforce that the +

      In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 20 for Custom Assets, as we need to enforce that the \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) of the output note of that Split Action is the output of a valid \(\mathsf{ZSAValueBase^{Orchard}}\) - computation defined in ZIP 227 5.

      + computation defined in ZIP 227 6.

      Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the \(\mathsf{valueBalance}\) of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets.

      @@ -96,7 +96,7 @@ \(\mathsf{AssetId}\) , the Asset Digest, and the Asset Base ( \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 5.

      + for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 6.

      This \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) will be the base point of the value commitment for the specific Custom Asset. Note that the @@ -104,9 +104,9 @@ of the ZEC Asset will be kept as the original value base point, \(\mathcal{V}^\mathsf{Orchard}\) .

      -

      In future network and protocol upgrades, the same Asset description string can be carried on, potentially mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, - \(\mathsf{AssetId}\) - , the Asset Digest, and the Asset Base from one shielded protocol to another.

      +

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

      +

      Note Structure & Commitment

      Let @@ -114,7 +114,7 @@ be the type of a ZSA note, i.e. \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*\) .

      -

      A ZSA note differs from an Orchard note 6 by additionally including the Asset Base, +

      A ZSA note differs from an Orchard note 7 by additionally including the Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) . So a ZSA note is a tuple \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})\) @@ -122,7 +122,7 @@

      • \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) - is the unique element of the Pallas group 14 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 5. The byte representation of the Asset Base is defined as + is the unique element of the Pallas group 15 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6. The byte representation of the Asset Base is defined as \(\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .
      @@ -132,9 +132,9 @@
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)

      where \(\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}\) - are as defined for the Pallas curve 14, and + are as defined for the Pallas curve 15, and \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) - are as defined in the Zcash protocol specification 9. This note commitment scheme is instantiated using the Sinsemilla Commitment 17 as follows:

      + are as defined in the Zcash protocol specification 10. This note commitment scheme is instantiated using the Sinsemilla Commitment 18 as follows:

      \(\begin{align} \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} :=\begin{cases} @@ -142,28 +142,30 @@ \mathsf{cm^{OrchardZSA}} &\text{otherwise} \end{cases} \end{align}\)
      -

      where (note that - \(\mathsf{repr}_{\mathbb{P}}\) - is as defined for the Pallas curve 14, - \(l^{\mathsf{Orchard}}_{\mathsf{base}}\) - is as defined in §5.3 13, and - \(\mathsf{I2LEBSP}\) - is as defined in §5.1 12 of the Zcash protocol specification):

      +

      where:

      \(\begin{align} \mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ &\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \end{align}\)
      -

      The nullifier is generated in the same manner as in the Orchard protocol 11.

      -

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 7. It consists of

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

      Note that + \(\mathsf{repr}_{\mathbb{P}}\) + is as defined for the Pallas curve 15, + \(\ell^{\mathsf{Orchard}}_{\mathsf{base}}\) + is as defined in §5.3 14, and + \(\mathsf{I2LEBSP}\) + is as defined in §5.1 13 of the Zcash protocol specification.

      +

      The nullifier is generated in the same manner as in the Orchard protocol 12.

      +

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 8. It consists of

      +
      \((\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}^{\mathbb{Y}[32]}, \mathsf{memo} : \mathbb{B}^{\mathbb{Y}[512]})\)

      Rationale for Note Commitment

      In the ZSA protocol, the instance of the note commitment scheme, \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) , differs from the Orchard note commitment \(\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 17 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

      -

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

      + 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 18 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

      +

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

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

      This definition can be viewed as a hypernym 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

      @@ -178,17 +180,17 @@ are the values of the old and new notes of Asset Identifier \(\mathsf{AssetId}\) respectively,

      -

      +

      \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) - is defined in ZIP 227 5, and

      + is defined in ZIP 227 6, and

      \(\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}\) , as in the Orchard protocol.

      We define \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}\) - so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 3.

      + so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4.

      Rationale for Value Commitment

      -

      The Orchard Protocol uses a Homomorphic Pedersen Commitment 18 to perform the value commitment, with fixed base points +

      The Orchard Protocol uses a Homomorphic Pedersen Commitment 19 to perform the value commitment, with fixed base points \(\mathcal{V}^{\mathsf{Orchard}}\) and \(\mathcal{R}^{\mathsf{Orchard}}\) @@ -197,7 +199,7 @@

      Value Balance Verification

      -

      In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 10.

      +

      In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 11.

      For a total of \(n\) Actions in a transfer, the prover MUST still sign the SIGHASH of the transaction using the binding signature key @@ -216,186 +218,178 @@

      Split Notes

      -

      One of the key functionalities in a UTXO-based protocol is the fact that input notes are usually split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output. This requires a 1-to-many (Orchard) transaction. However, because each Action represents an input and an output, the resulting transaction must have multiple inputs. In order to cope with this today, the Actions that have not been assigned input notes are instead given dummy spend notes 19, which we call split Actions and split notes respectively. Basically, the input note is “faked” inside of the proof in order to hide which Action contains the real spend note.

      -

      This, however, brings some issues when it comes to adding multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base, but it must be enforced to be an actual output of a GroupHash computation (in fact we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). If not, then the prover could essentially input a multiple (or linear combination) of an existing Asset Base, with the goal to attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

      -

      In order to prevent this, we make some modifications to the circuit. Specifically we remove the dummy note functionality for Custom Assets and we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof.

      -

      This creates a chain of induction that ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified. If this were not done then it would be possible to violate balance, for example by using a value base point derived from those of other Assets.

      -

      Note that we do not care about whether the note identified by a Split Input is owned by the sender, or whether it was nullified before.

      -

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

      +

      A Split Input is a copy of a previously issued input note (that is, a note that has previously been included in the Merkle tree), with the following changes:

      +
        +
      • A split_flag boolean is set to 1.
        • +
      • The value of the note is replaced with the value 0 during the computation of the value commitment.
        • +
      +

      Input notes are sometimes split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output.

      +

      When the number of input notes of a particular Asset Base is smaller than the required number of output notes for the same Asset Base, the sender creates Split Inputs of the same Asset Base as padding for the input-less Actions. Note that we do not care about whether the previously issued note copied to create a Split Input is owned by the sender, or whether it was nullified before.

      +

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

      The specific circuit changes are presented below.

      +

      Rationale for Split Notes

      +

      In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 20 to the Actions that have not been assigned input notes.

      +

      The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

      +

      Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the split_flag boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified.

      +

      Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets.

      +

      Circuit Statement

      -

      The advantage of the design described above, with respect to the circuit statement, is that every ZSA Action statement is kept closely similar to the Orchard Action statement 20, except for a few additions that ensure the security of the Asset Identifier system.

      -

      Asset Identifier Equality: the following constraints must be added to ensure that the input and output note are of the same - \(\mathsf{AssetId}\) - :

      -
        -
      • The Asset Base, - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) - , for the note is witnessed once, as an auxiliary input.
        • -
      • In the Old note commitment integrity constraint in the Orchard Action statement 20, - \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) - is replaced with - \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) - .
        • -
      • In the New note commitment integrity constraint in the Orchard Action statement 20, - \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) - is replaced with - \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) - .
        • -
      -

      Correct Value Commitment: the following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes:

      -
        -
      • The fixed-base multiplication constraints between the value and the value base point of the value commitment, - \(\mathsf{cv}\) - , is replaced with a variable-base multiplication between the two.
        • -
      • The witness to the value base point, as defined in the value base equation is the auxiliary input - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) - .
        • -
      -

      Enforce Secure Identifier for Split Actions: the following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action:

      -
        -
      • -
        -
        The Value Commitment Integrity should be changed
        -
        -
          -
        • Replace the input note value by a generic value, - \(\mathsf{v}'\) - , as - \(\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) -
          • -
        -
        -
        -
        • -
      • -
        -
        Add a boolean split variable as an auxiliary witness. This variable is to be activated split = 1 if the Action in question is a split and split = 0 if the Action is actually spending an input note:
        -
        -
          -
        • If split = 1 then set - \(\mathsf{v}' = 0\) - otherwise - \(\mathsf{v}'=\mathsf{v^{old}}\) - from the auxiliary input.
          • -
        -
        -
        -
        • -
      • -
        -
        The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes):
        -
        -
          -
        • Check that (path, pos) is a valid Merkle path of depth - \(\mathsf{MerkleDepth^Orchard}\) - , from - \(\mathsf{cm^old}\) - to the anchor - \(\mathsf{rt^Orchard}\) - .
          • -
        -
        -
        -
        • -
      • -
        -
        The Nullifier Integrity will be changed to prevent the identification of notes
        -
        -
          -
        • Replace the - \(\psi_{old}\) - value with a generic - \(\psi'\) - as - \(\mathsf{nf_old = DeriveNullifier_nk}(\rho^\mathsf{old}, \psi', \mathsf{cm^old})\) -
          • -
        • if - \(\mathtt{split} = 0\) - then constrain - \(\psi' = \psi^{old}\) - . (Otherwise - \(\psi'\) - should be sampled randomly.)
          • -
        -
        -
        -
        • -
      -

      Enabling Backwards Compatibility with ZEC Notes: the following constraints must be added to enable backwards compatibility with Orchard ZEC notes.

      -

      The old note commitment is computed using a “rolling-aggregate” Sinsemilla commitment. This means that the commitment is computed by adding new chunks or windows to the accumulated value. This method will be used in order to maintain a single commitment instance for the old note commitment, that will be used both for Orchard ZEC notes and for ZSA notes. The original Orchard ZEC notes will be conserved and not actually be converted into ZSA notes, as we will always need to compute them. However, new notes will always be ZSA notes with an Asset Base.

      -

      The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (ZEC-Orchard note). If the note is an old note, from before the upgrade, the commitment is computed in the original Orchard fashion. If the note is a new ZSA note, there are two cases:

      -
        -
      • -
        -
        If the Asset Base auxiliary input present but set to - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - = - \(\mathcal{V}^\mathsf{Orchard}\) -
        -
        -
          -
        • NoteCommitment has a “compatibility” path that computes the note commitment as in plain Orchard (i.e.: without including the Asset Base)
          • -
        • This path also uses the original domain separator for ZEC note commitment
          • -
        -
        -
        -
        • -
      • -
        -
        Else,
        -
        -
          -
        • The note commitment adds the identfier, - \(\mathsf{AssetId}\) - , as a final “chunk” of the Sinsemilla commitment
          • -
        • The note commitment uses a different domain separator for ZSA note commitment
          • -
        -
        -
        -
        • -
      -
      -

      Backward Compatibility

      -

      In order to have a "clean" backwards compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - The input notes with an Asset Base denote the Custom Assets, generating a note commitment that includes the Asset Identifier; whereas the notes without an Asset Base denote the ZEC notes from before the protocol upgrade, and generate a note commitment that does not include the Asset Base, in order to maintain the referencability to the Merkle tree - The value commitment is abstracted to allow for the value base-point as a variable private input to the proof - The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include split input notes.

      +

      Every ZSA Action statement is closely similar to the Orchard Action statement 21, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

      +

      Asset Base Equality

      +

      The following constraints must be added to ensure that the input and output note are of the same + \(\mathsf{AssetBase}\) + :

      +
        +
      • The Asset Base, + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + , for the note is witnessed once, as an auxiliary input.
        • +
      • In the Old note commitment integrity constraint in the Orchard Action statement 21, + \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) + is replaced with + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + .
        • +
      • In the New note commitment integrity constraint in the Orchard Action statement 21, + \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) + is replaced with + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + .
        • +
      +
      +

      Value Commitment Correctness

      +

      The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes:

      +
        +
      • The fixed-base multiplication constraints between the value and the value base point of the value commitment, + \(\mathsf{cv}\) + , is replaced with a variable-base multiplication between the two.
        • +
      • The witness to the value base point (as defined in the asset base equation) is the auxiliary input + \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + .
        • +
      +
      +

      Asset Identifier Consistency for Split Actions

      +

      The following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action:

      +
        +
      • +
        +
        The Value Commitment Integrity should be changed
        +
        +
          +
        • Replace the input note value by a generic value, + \(\mathsf{v}'\) + , as + \(\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) +
          • +
        +
        +
        +
        • +
      • +
        +
        Add a boolean split_flag variable as an auxiliary witness. This variable is to be activated split_flag = 1 if the Action in question has a Split Input and split_flag = 0 if the Action is actually spending an input note:
        +
        +
          +
        • If split_flag = 1 then set + \(\mathsf{v}' = 0\) + otherwise + \(\mathsf{v}'=\mathsf{v^{old}}\) + from the auxiliary input.
          • +
        +
        +
        +
        • +
      • +
        +
        The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes):
        +
        +
          +
        • Check that (path, pos) is a valid Merkle path of depth + \(\mathsf{MerkleDepth^Orchard}\) + , from + \(\mathsf{cm^{old}}\) + to the anchor + \(\mathsf{rt^{Orchard}}\) + .
          • +
        +
        +
        +
        • +
      • +
        +
        The Nullifier Integrity will be changed to prevent the identification of notes
        +
        +
          +
        • Replace the + \(\psi_{old}\) + value with a generic + \(\psi'\) + as + \(\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})\) +
          • +
        • if + \(\mathtt{split\_flag} = 0\) + then constrain + \(\psi' = \psi^{old}\) + . (Otherwise + \(\psi'\) + should be sampled randomly.)
          • +
        +
        +
        +
        • +
      +
      +

      Backwards Compatibility with ZEC Notes

      +

      The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 10. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

      +

      Burn Mechanism

      -

      The burn mechanism may be needed for off-boarding the Wrapped Assets from the chain, or enabling advanced tokenomics on Assets. It is part of the Issuance/Burn protocol, but given that it can be seen as an extension of the Transfer protocol, we add it here for readability.

      -

      In essence, the burn mechanism is a transparent / revealing extension to the transfer protocol that enables a specific amount of any Asset identifier to be sent into “oblivion”. Our burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.

      -

      First, contrary to the strict transfer transaction, we allow the sender to include a - \(\mathsf{valueBalance_{AssetId}}\) - variable for every Asset Identifier that is being burnt. As we will show in the transaction structure, this is separate from the regular +

      The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.

      +

      The sender includes a + \(\mathsf{v^{AssetBase}}\) + variable for every Asset Identifier that is being burnt. As we will show in the ZSA Transaction Structure, this is separate from the regular \(\mathsf{valueBalance^Orchard}\) - that is the default transparent value for the ZEC Asset. We require that for every - \(\mathsf{valueBalance_{AssetId}}\) - provided as above by the sender, - \(\mathsf{valueBalance_{AssetId}} \neq 0\) - . This is enforced via a consensus rule.

      -

      For every custom Asset that is burnt, we add to the assetBurn vector the tuple - \((\mathsf{valueBalance_{AssetId}, AssetId})\) + that is the default transparent value for the ZEC Asset.

      +

      For every Custom Asset that is burnt, we add to the + \(\mathsf{assetBurn}\) + vector the tuple + \((\mathsf{AssetBase},\mathsf{v^{AssetBase}})\) such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.

      -

      - \(\mathsf{assetBurn = \{ (v^{AssetId}, AssetId)}\ |\ \forall\ \mathsf{AssetId}\ \textit{s.t.}\ \mathsf{v^{AssetId}} \neq 0 \}\) -

      -

      The value balances for each Asset Identifier in assetBurn represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

      -

      Finally, the validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective - \(\mathsf{AssetId}\) +

      \(\mathsf{assetBurn} = \{ (\mathsf{AssetBase},\mathsf{v^{AssetBase}})\ |\ \forall\ \mathsf{AssetBase}\ \textit{s.t.}\ \mathsf{v^{AssetBase}} \neq 0 \}\)
      +

      The value balances for each Asset Identifier in + \(\mathsf{assetBurn}\) + represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

      +

      The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective + \(\mathsf{AssetBase}\) as the value base point of the Pedersen Commitment. This is done as follows

      -

      - \(\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\forall \mathsf{AssetId}\textit{ s.t. }\mathsf{v^{AssetId}\neq 0}} \mathsf{ValueCommit_0^{OrchardZSA}(v^{AssetId}, AssetId) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}}\) -

      +
      \(\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\mathsf{assetBurn}} \mathsf{ValueCommit_0^{OrchardZSA}(AssetBase, v^{AssetBase}) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}}\)

      In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt.

      -

      Note: Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

      +

      Burn Mechanism Consensus Rules

      +
        +
      1. We require that + \(\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}\) + . That is, Native Assets are not allowed to be burnt.
        2. +
      2. We require that for every + \(\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v^{AssetBase}} \neq 0\) + .
        3. +
      3. We require that there be no duplication of Custom Assets in the + \(\mathsf{assetBurn}\) + set. That is, every + \(\mathsf{AssetBase}\) + has at most one entry in + \(\mathsf{assetBurn}\) + .
        4. +
      +

      Note: Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

      +

      ZSA Transaction Structure

      -

      The transaction format is similar to the version 5 transaction format described in the Zcash specification 21, with the following additions to the Orchard bundle:

      +

      The transaction format is similar to the version 5 transaction format described in the Zcash specification 22, with the following additions to the Orchard bundle:

    1821 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    @@ -410,23 +404,54 @@ - + - - + +
    varies nAssetBurn compactSizenumber of Assets burntThe number of Assets burnt.
    40*nAssetBurn vAssetBurnbytes[40][nAssetBurn]32 bytes Asset type_t, 8 bytes of valueBalanceAssetBurn[nAssetBurn]A sequence of Asset Burn descriptions, encoded per ZSA Asset Burn Description.

    In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the - \(\mathsf{AssetId}\) + \(\mathsf{AssetBase}\) ). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action.

    +

    ZSA Asset Burn Description

    +

    A ZSA Asset Burn description is encoded in a transaction as an of a AssetBurn type:

    + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    32AssetBasebyte[32]For the Orchard-based ZSA protocol, this is the encoding of the Asset Base + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + .
    8valueBurn + \(\{1 .. 2^{64} - 1\}\) + The amount of the AssetType being burnt.
    +

    Security and Privacy Considerations

      -
    • Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure.
      • +
    • The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility.
    • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
    • We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
    • Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. @@ -438,11 +463,16 @@

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 24.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 25.

    +
    +

    Backward Compatibility

    +

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the + \(AssetBase\) + value as well. - The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade. - The value commitment is abstracted to allow for the value base-point as a variable private input to the proof. - The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes.

    +
    +

    Deployment

    +

    The Zcash Shielded Assets protocol will be deployed in a subsequent Network Upgrade.

    -
    -

    Deployment

    -

    The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions.

    Test Vectors

      @@ -472,10 +502,18 @@ - +
      + + + +
      3ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances
      + + + + @@ -483,7 +521,7 @@
      4 ZIP 224: Orchard
      - + @@ -491,7 +529,7 @@
      45 ZIP 226: Transfer and Burn of Zcash Shielded Assets
      - + @@ -499,7 +537,7 @@
      56 ZIP 227: Issuance of Zcash Shielded Assets
      - + @@ -507,7 +545,7 @@
      67 Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes
      - + @@ -515,7 +553,7 @@
      78 Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields
      - + @@ -523,7 +561,7 @@
      89 Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions
      - + @@ -531,7 +569,7 @@
      910 Zcash Protocol Specification, Version 2022.3.8. Section 4.1.8: Commitment
      - + @@ -539,7 +577,7 @@
      1011 Zcash Protocol Specification, Version 2022.3.8. Section 4.14: Balance and Binding Signature (Orchard)
      - + @@ -547,7 +585,7 @@
      1112 Zcash Protocol Specification, Version 2022.3.8. Section 4.16: Note Commitments and Nullifiers
      - + @@ -555,7 +593,7 @@
      1213 Zcash Protocol Specification, Version 2022.3.8. Section 5.1: Integers, Bit Sequences, and Endianness
      - + @@ -563,7 +601,7 @@
      1314 Zcash Protocol Specification, Version 2022.3.8. Section 5.3: Constants
      - + @@ -571,7 +609,7 @@
      1415 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.6: Pallas and Vesta
      - + @@ -579,7 +617,7 @@
      1516 Pallas/Vesta supporting evidence
      - + @@ -587,7 +625,7 @@
      1617 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.1.9: Sinsemilla hash function
      - + @@ -595,7 +633,7 @@
      1718 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.4: Sinsemilla commitments
      - + @@ -603,7 +641,7 @@
      1819 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
      - + @@ -611,7 +649,7 @@
      1920 Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard)
      - + @@ -619,7 +657,7 @@
      2021 Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard)
      - + @@ -627,7 +665,7 @@
      2122 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
      - + @@ -635,7 +673,7 @@
      2223 User-Defined Assets and Wrapped Assets
      - + @@ -643,7 +681,7 @@
      2324 Comment on Generalized Value Commitments
      - + diff --git a/zip-0226.rst b/zip-0226.rst index 7a1b1aa8d..ee9fd2cab 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -15,7 +15,7 @@ Created: 2022-05-01 License: MIT Discussions-To: - Pull-Request: + Pull-Request: Terminology @@ -38,13 +38,13 @@ We define the following additional terms: - Native Asset: a Custom Asset with issuance defined on the Zcash block chain. - Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash block chain. -- Split Input: an Action input identifying a Custom Asset note, used to ensure that the output note of that Action is of a validly issued :math:`\mathsf{AssetId}` when there is no corresponding real input note to spend. The Action does not spend the note identified by the Split Input. +- Split Input: an Action input used to ensure that the output note of that Action is of a validly issued :math:`\mathsf{AssetBase}` when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in `Split Notes`_. - Split Action: an Action that contains a Split Input. Abstract ======== -ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol — a set +ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol — a set of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain. Creation of such Assets is defined in ZIP 227 [#zip-0227]_. Transfer and burn of such Assets is defined @@ -88,7 +88,10 @@ For every new Asset, there must be a new and unique Asset Identifier. Every Asse This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. -In future network and protocol upgrades, the same Asset description string can be carried on, potentially mapping into a different shielded protocol. In that case, the turnstile should know how to transform the Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base from one shielded protocol to another. +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]_. Note Structure & Commitment --------------------------- @@ -116,19 +119,21 @@ This note commitment scheme is instantiated using the Sinsemilla Commitment [#pr \end{cases} \end{align} -where (note that :math:`\mathsf{repr}_{\mathbb{P}}` is as defined for the Pallas curve [#protocol-pallasandvesta]_, :math:`l^{\mathsf{Orchard}}_{\mathsf{base}}` is as defined in §5.3 [#protocol-constants]_, and :math:`\mathsf{I2LEBSP}` is as defined in §5.1 [#protocol-endian]_ of the Zcash protocol specification): +where: .. math:: \begin{align} \mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ &\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \end{align} +Note that :math:`\mathsf{repr}_{\mathbb{P}}` is as defined for the Pallas curve [#protocol-pallasandvesta]_, :math:`\ell^{\mathsf{Orchard}}_{\mathsf{base}}` is as defined in §5.3 [#protocol-constants]_, and :math:`\mathsf{I2LEBSP}` is as defined in §5.1 [#protocol-endian]_ of the Zcash protocol specification. + 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 -.. math:: (\mathsf{leadByte} : \mathbb{B}^{\mathbb{Y}}, \mathsf{d} : \mathbb{B}^{[l_{\mathsf{d}}]}, \mathsf{v} : \{0 .. 2^{l_{\mathsf{value}}} - 1\}, \mathsf{rseed} : \mathbb{B}^{\mathbb{Y}[32]}, \mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]}, \mathsf{memo} : \mathbb{B}^{\mathbb{Y}[512]}) +.. 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}^{\mathbb{Y}[32]}, \mathsf{memo} : \mathbb{B}^{\mathbb{Y}[512]}) Rationale for Note Commitment ''''''''''''''''''''''''''''' @@ -141,8 +146,7 @@ The note commitment output is still indistinguishable from the original Orchard .. math:: \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} \in \mathsf{NoteCommit^{Orchard}.Output} - - +This definition can be viewed as a hypernym 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 ---------------- @@ -153,7 +157,7 @@ In the case of the ZSA protocol, the value of different Asset Identifiers in a g where :math:`\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{AssetId}}` such that :math:`\mathsf{v^{old}_{AssetId}}` and :math:`\mathsf{v^{new}_{AssetId}}` are the values of the old and new notes of Asset Identifier :math:`\mathsf{AssetId}` respectively, -.. _`value base`: +.. _`asset base`: :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` is defined in ZIP 227 [#zip-0227]_, and @@ -194,128 +198,145 @@ As in the Orchard protocol, the binding signature verification key, :math:`\math Split Notes ----------- -One of the key functionalities in a UTXO-based protocol is the fact that input notes are usually split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output. This requires a 1-to-many (Orchard) transaction. However, because each Action represents an input and an output, the resulting transaction must have multiple inputs. In order to cope with this today, the Actions that have not been assigned input notes are instead given *dummy spend notes* [#protocol-dummynotes]_, which we call split Actions and split notes respectively. Basically, the input note is “faked” inside of the proof in order to hide which Action contains the *real* spend note. - -This, however, brings some issues when it comes to adding multiple Asset Identifiers, as the output note of the split Actions *cannot* contain *any* Asset Base, but it must be enforced to be an actual output of a GroupHash computation (in fact we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). If not, then the prover could essentially input a multiple (or linear combination) of an existing Asset Base, with the goal to attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds. +A Split Input is a copy of a previously issued input note (that is, a note that has previously been included in the Merkle tree), with the following changes: -In order to prevent this, we make some modifications to the circuit. Specifically we remove the dummy note functionality for Custom Assets and we enforce that *every* input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value -will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof. +- A ``split_flag`` boolean is set to 1. +- The value of the note is replaced with the value 0 during the computation of the value commitment. -This creates a chain of induction that ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified. If this were not done then it would be possible to violate balance, for example by using a value base point derived from those of other Assets. +Input notes are sometimes split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output. -Note that we do not care about whether the note identified by a Split Input is owned by the sender, or whether it was nullified before. +When the number of input notes of a particular Asset Base is smaller than the required number of output notes for the same Asset Base, the sender creates Split Inputs of the same Asset Base as padding for the input-less Actions. Note that we do not care about whether the previously issued note copied to create a Split Input is owned by the sender, or whether it was nullified before. -Wallets and other clients have a choice to make to ensure the Asset Base is preserved for the output note of a Split Action: +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). 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). -The specific circuit changes are presented below. +Rationale for Split Notes +''''''''''''''''''''''''' + +In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives *dummy spend notes* [#protocol-dummynotes]_ to the Actions that have not been assigned input notes. + +The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions *cannot* contain *any* Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds. + +Therefore, for Custom Assets we enforce that *every* input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the ``split_flag`` boolean). +This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified. + +Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets. + Circuit Statement ----------------- -The advantage of the design described above, with respect to the circuit statement, is that every *ZSA Action statement* is kept closely similar to the Orchard Action statement [#protocol-actionstatement]_, except for a few additions that ensure the security of the Asset Identifier system. +Every *ZSA Action statement* is closely similar to the Orchard Action statement [#protocol-actionstatement]_, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below. + +Asset Base Equality +''''''''''''''''''''''''' -**Asset Identifier Equality:** the following constraints must be added to ensure that -the input and output note are of the same :math:`\mathsf{AssetId}`: +The following constraints must be added to ensure that the input and output note are of the same :math:`\mathsf{AssetBase}`: - The Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`, for the note is witnessed once, as an auxiliary input. - In the Old note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. - In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. -**Correct Value Commitment:** the following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes: +Value Commitment Correctness +'''''''''''''''''''''''''''' + +The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes: - The fixed-base multiplication constraints between the value and the value base point of the value commitment, :math:`\mathsf{cv}`, is replaced with a variable-base multiplication between the two. -- The witness to the value base point, as defined in the `value base`_ equation is the auxiliary input :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`. +- The witness to the value base point (as defined in the `asset base`_ equation) is the auxiliary input :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`. -**Enforce Secure Identifier for Split Actions:** the following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action: +Asset Identifier Consistency for Split Actions +'''''''''''''''''''''''''''''''''''''''''''''' + +The following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action: - The Value Commitment Integrity should be changed - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}` -- Add a boolean ``split`` variable as an auxiliary witness. This variable is to be activated ``split = 1`` if the Action in question is a split and ``split = 0`` if the Action is actually spending an input note: - - If ``split = 1`` then set :math:`\mathsf{v}' = 0` otherwise :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. +- Add a boolean ``split_flag`` variable as an auxiliary witness. This variable is to be activated ``split_flag = 1`` if the Action in question has a Split Input and ``split_flag = 0`` if the Action is actually spending an input note: + - If ``split_flag = 1`` then set :math:`\mathsf{v}' = 0` otherwise :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. - The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes): - - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^old}` to the anchor :math:`\mathsf{rt^Orchard}`. + - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^{old}}` to the anchor :math:`\mathsf{rt^{Orchard}}`. - The Nullifier Integrity will be changed to prevent the identification of notes - - Replace the :math:`\psi_{old}` value with a generic :math:`\psi'` as :math:`\mathsf{nf_old = DeriveNullifier_nk}(\rho^\mathsf{old}, \psi', \mathsf{cm^old})` - - if :math:`\mathtt{split} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled randomly.) + - Replace the :math:`\psi_{old}` value with a generic :math:`\psi'` as :math:`\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})` + - if :math:`\mathtt{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled randomly.) -**Enabling Backwards Compatibility with ZEC Notes:** the following constraints must be added to enable backwards compatibility with Orchard ZEC notes. +Backwards Compatibility with ZEC Notes +'''''''''''''''''''''''''''''''''''''' -The old note commitment is computed using a “rolling-aggregate” Sinsemilla commitment. This means that the commitment is computed by adding new chunks or windows to the accumulated value. This method will be used in order to maintain a single commitment instance for the old note commitment, that will be used both for Orchard ZEC notes and for ZSA notes. The original Orchard ZEC notes will be conserved and not actually be converted into ZSA notes, as we will always need to compute them. -However, new notes will always be ZSA notes with an Asset Base. +The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion [#protocol-abstractcommit]_. If the note is a ZSA note, the note commitment is computed as defined in the `Note Structure & Commitment`_ section. -The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (ZEC-Orchard note). If the note is an old note, from before the upgrade, the commitment is computed in the original Orchard fashion. If the note is a new ZSA note, there are two cases: +Burn Mechanism +============== -- If the Asset Base auxiliary input present but set to :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` = :math:`\mathcal{V}^\mathsf{Orchard}` - - NoteCommitment has a “compatibility” path that computes the note commitment as in plain Orchard (i.e.: without including the Asset Base) - - This path also uses the original domain separator for ZEC note commitment -- Else, - - The note commitment adds the identfier, :math:`\mathsf{AssetId}`, as a final “chunk” of the Sinsemilla commitment - - The note commitment uses a different domain separator for ZSA note commitment +The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. +The sender includes a :math:`\mathsf{v^{AssetBase}}` variable for every Asset Identifier that is being burnt. As we will show in the `ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset. -Backward Compatibility ----------------------- +For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` vector the tuple :math:`(\mathsf{AssetBase},\mathsf{v^{AssetBase}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer. -In order to have a "clean" backwards compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: -- The input notes with an Asset Base denote the Custom Assets, generating a note commitment that includes the Asset Identifier; whereas the notes without an Asset Base denote the ZEC notes from before the protocol upgrade, and generate a note commitment that does not include the Asset Base, in order to maintain the referencability to the Merkle tree -- The value commitment is abstracted to allow for the value base-point as a variable private input to the proof -- The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include split input notes. +.. math:: \mathsf{assetBurn} = \{ (\mathsf{AssetBase},\mathsf{v^{AssetBase}})\ |\ \forall\ \mathsf{AssetBase}\ \textit{s.t.}\ \mathsf{v^{AssetBase}} \neq 0 \} +The value balances for each Asset Identifier in :math:`\mathsf{assetBurn}` represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). -Burn Mechanism -============== -The burn mechanism may be needed for off-boarding the Wrapped Assets from the chain, or enabling advanced tokenomics on Assets. It is part of the Issuance/Burn protocol, but given that it can be seen as an extension of the Transfer protocol, we add it here for readability. +The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective :math:`\mathsf{AssetBase}` as the value base point of the Pedersen Commitment. This is done as follows -In essence, the burn mechanism is a transparent / revealing extension to the transfer protocol that enables a specific amount of any Asset identifier to be sent into “oblivion”. Our burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. +.. math:: \mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\mathsf{assetBurn}} \mathsf{ValueCommit_0^{OrchardZSA}(AssetBase, v^{AssetBase}) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}} -First, contrary to the strict transfer transaction, we allow the sender to include a :math:`\mathsf{valueBalance_{AssetId}}` variable for every Asset Identifier that is being burnt. As we will show in the transaction structure, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset. -We require that for every :math:`\mathsf{valueBalance_{AssetId}}` provided as above by the sender, :math:`\mathsf{valueBalance_{AssetId}} \neq 0`. This is enforced via a consensus rule. +In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt. -For every custom Asset that is burnt, we add to the `assetBurn` vector the tuple :math:`(\mathsf{valueBalance_{AssetId}, AssetId})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer. +Burn Mechanism Consensus Rules +------------------------------ +1. We require that :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}`. That is, Native Assets are not allowed to be burnt. +2. We require that for every :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v^{AssetBase}} \neq 0`. +3. We require that there be no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}` has at most one entry in :math:`\mathsf{assetBurn}`. -:math:`\mathsf{assetBurn = \{ (v^{AssetId}, AssetId)}\ |\ \forall\ \mathsf{AssetId}\ \textit{s.t.}\ \mathsf{v^{AssetId}} \neq 0 \}` +**Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets. -The value balances for each Asset Identifier in `assetBurn` represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). -Finally, the validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective :math:`\mathsf{AssetId}` as the value base point of the Pedersen Commitment. This is done as follows +ZSA Transaction Structure +========================= -:math:`\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\forall \mathsf{AssetId}\textit{ s.t. }\mathsf{v^{AssetId}\neq 0}} \mathsf{ValueCommit_0^{OrchardZSA}(v^{AssetId}, AssetId) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}}` +The transaction format is similar to the version 5 transaction format described in the Zcash specification [#protocol-transactionstructure]_, with the following additions to the Orchard bundle: -In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt. ++---------------+------------+-------------------------+-----------------------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++===============+============+=========================+===================================================================================+ +| varies | nAssetBurn | compactSize | The number of Assets burnt. | ++---------------+------------+-------------------------+-----------------------------------------------------------------------------------+ +| 40*nAssetBurn | vAssetBurn | AssetBurn[nAssetBurn] | A sequence of Asset Burn descriptions, encoded per `ZSA Asset Burn Description`_. | ++---------------+------------+-------------------------+-----------------------------------------------------------------------------------+ -**Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets. +In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the :math:`\mathsf{AssetBase}`). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action. -ZSA Transaction Structure -========================= +ZSA Asset Burn Description +-------------------------- -The transaction format is similar to the version 5 transaction format described in the Zcash specification [#protocol-transactionstructure]_, with the following additions to the Orchard bundle: +A ZSA Asset Burn description is encoded in a transaction as an of a AssetBurn type: -+-----------------+-------------+-----------------------------------+-------------------------+ -| Bytes | Name | Data Type | Description | -+=================+=============+===================================+=========================+ -| varies | nAssetBurn | compactSize | number of Assets burnt | -+-----------------+-------------+-----------------------------------+-------------------------+ -| 40*nAssetBurn | vAssetBurn | bytes[40][nAssetBurn] | 32 bytes Asset type_t, | -| | | | 8 bytes of valueBalance | -+-----------------+-------------+-----------------------------------+-------------------------+ ++-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=======+===========+=============================+===========================================================================================================================+ +| 32 | AssetBase | byte[32] | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. | ++-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +| 8 | valueBurn | :math:`\{1 .. 2^{64} - 1\}` | The amount of the AssetType being burnt. | ++-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ -In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the :math:`\mathsf{AssetId}`). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action. Security and Privacy Considerations =================================== -- Even if the Orchard protocol and ZSA protocol do not share the same anonymity pool (nodes can keep track of the notes that where published with different transaction structures), the migration from one to the other is done automatically and seamlessly. The Orchard bundle will be replaced by the ZSA bundle and all ZEC notes will be fully spendable with the new transaction structure. +- The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility. - When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design. - We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state. - Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. - One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. + Other Considerations ==================== @@ -324,10 +345,18 @@ Transaction Fees The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade [#zip-0317b]_. -Deployment -========== +Backward Compatibility +---------------------- + +In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: +- Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the :math:`AssetBase` value as well. +- The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade. +- The value commitment is abstracted to allow for the value base-point as a variable private input to the proof. +- The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes. -The Zcash Shielded Assets protocol should be deployed by replacing the Orchard protocol in a subsequent Network Upgrade. The design of this protocol ensures that there is no need to use any turnstile mechanism, being that Orchard-based ZEC notes can be used directly within the ZSA Actions. +Deployment +----------- +The Zcash Shielded Assets protocol will be deployed in a subsequent Network Upgrade. Test Vectors ============ @@ -345,6 +374,7 @@ References .. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ .. [#zip-0200] `ZIP 200: Network Upgrade Mechanism `_ +.. [#zip-0209] `ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances `_ .. [#zip-0224] `ZIP 224: Orchard `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ diff --git a/zip-0227.html b/zip-0227.html index 79be37b76..4dde8986f 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -22,7 +22,7 @@ Created: 2022-05-01 License: MIT Discussions-To: <https://github.com/zcash/zips/issues/618> -Pull-Request: <https://github.com/zcash/zips/pull/676> +Pull-Request: <https://github.com/zcash/zips/pull/680>

      Terminology

      The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

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

      @@ -56,7 +56,6 @@
      • Any user of the Zcash block chain can issue custom Assets on chain.
      • The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain.
        • -
      • At the time of issuance, the issuer should be able to allocate all the Assets to the corresponding owners by creating the corresponding (shielded) output notes to the respective addresses. This allows for allocation to be totally private even though the issuance mechanism is itself transparent.
      • Issuing or changing the attributes of a specific Asset should require cryptographic authorization.
      • The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier.
      • An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets.
        • @@ -105,7 +104,7 @@

        Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key - \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssuance"}, S)\) + \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\) .

        As in ZIP 32 for Orchard 11, we only use hardened child key derivation for the issuance master key. We reuse the \(\mathsf{CDKsk}\) @@ -173,7 +172,7 @@

        • \(\mathsf{asset\_desc}\) - be the asset description, a UTF-8 encoded string of up to 512 bytes, which includes any information pertaining to the issuance.
          • + be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
        • \(\mathsf{ik}\) be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
          • @@ -223,7 +222,7 @@ , stored in two bytes.
        • \(\mathsf{asset\_desc}\) - : the Asset description, a UTF-8 encoded string of up to 512 bytes
          • + : the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
        • notes: an array containing the unencrypted output notes of the recipients of the Asset, of type Note
        • finalize: a boolean that defines whether the issuance of that specific custom Asset is finalized or not
        @@ -338,7 +337,7 @@
      - +
      2425 ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
      64 issueAuthSig byte[64]The signature of the transaction SIGHASH, signed by the issuerThe signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme
      @@ -433,6 +432,7 @@
    • If finalize = 1, add \(\mathsf{AssetId}\) to the previously_finalized set immediately after the block in which this transaction occurs.
      • +
    • (Replay Protection) If issue bundle is present, the fees MUST be greater than zero.

    Rationale

    @@ -451,6 +451,7 @@
  • We require a check whether the finalize flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the previously_finalized set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
    • +
  • We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH, potentially allowing for a replay attack.

    • Concrete Applications

    Asset Features

    @@ -526,7 +527,7 @@
    T.1b: assetDescription
    -

    UTF-8 encoding of the Asset description string.

    +

    The Asset description byte string.

    T.1c: flagsIssuance

    An 8-bit value representing a set of flags. Ordered from LSB to MSB:

    diff --git a/zip-0227.rst b/zip-0227.rst index f0fc92a03..a21f1cf08 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -15,7 +15,7 @@ Created: 2022-05-01 License: MIT Discussions-To: - Pull-Request: + Pull-Request: Terminology =========== @@ -65,7 +65,6 @@ Requirements - Any user of the Zcash block chain can issue custom Assets on chain. - The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain. -- At the time of issuance, the issuer should be able to allocate all the Assets to the corresponding owners by creating the corresponding (shielded) output notes to the respective addresses. This allows for allocation to be totally private even though the issuance mechanism is itself transparent. - Issuing or changing the attributes of a specific Asset should require cryptographic authorization. - The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier. - An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets. @@ -110,7 +109,7 @@ Issuance master key derivation for hierarchical deterministic wallets The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section. Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. -We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssuance"}, S)`. +We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)`. As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key. We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32. @@ -148,7 +147,7 @@ From the Asset Digest, we derive a specific Asset Base within each such shielded Let -- :math:`\mathsf{asset\_desc}` be the asset description, a UTF-8 encoded string of up to 512 bytes, which includes any information pertaining to the issuance. +- :math:`\mathsf{asset\_desc}` be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. - :math:`\mathsf{ik}` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`, @@ -189,7 +188,7 @@ Issuance Action Description An issuance action, `IssueAction`, is the instance of issuing a specific custom Asset, and contains the following fields: - :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. -- :math:`\mathsf{asset\_desc}`: the Asset description, a UTF-8 encoded string of up to 512 bytes +- :math:`\mathsf{asset\_desc}`: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. - `notes`: an array containing the unencrypted output notes of the recipients of the Asset, of type `Note` - ``finalize``: a boolean that defines whether the issuance of that specific custom Asset is finalized or not @@ -218,14 +217,14 @@ An issuance bundle, `IssueBundle`, is the aggregate of all the issuance-related The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_. -======= ==================== ========================== ========================================================================= +======= ==================== ========================== ========================================================================================================================== Bytes Name Data Type Description -======= ==================== ========================== ========================================================================= +======= ==================== ========================== ========================================================================================================================== Varies nIssueActions compactSize The number of issuance actions in the bundle Varies vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions 32 :math:`\mathsf{ik}` byte[32] The issuance validating key of the issuer, used to validate the signature -64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer -======= ==================== ========================== ========================================================================= +64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer, validated as in `Issuance Authorization Signature Scheme`_ +======= ==================== ========================== ========================================================================================================================== Issuance Protocol ----------------- @@ -273,6 +272,8 @@ If all of the above checks pass, do the following: - For each note, compute the note commitment as :math:`\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}` as defined in the Note Structure and Commitment section of ZIP 226 [#zip-0226-notestructure]_ and - add :math:`\mathsf{cm}` to the Merkle tree of note commitments, `NoteCommitmentTree`. - If ``finalize = 1``, add :math:`\mathsf{AssetId}` to the ``previously_finalized`` set immediately after the block in which this transaction occurs. +- (Replay Protection) If issue bundle is present, the fees MUST be greater than zero. + Rationale @@ -289,6 +290,7 @@ The following is a list of rationale for different decisions made in the proposa - information to be committed by the issuer, though not enforceable by the protocol. - We require a check whether the ``finalize`` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the ``previously_finalized`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. +- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the ``SIGHASH`` would be computed solely based on the issue bundle. A duplicate bundle would have the same ``SIGHASH``, potentially allowing for a replay attack. Concrete Applications --------------------- @@ -387,7 +389,7 @@ The ZIP 212 32-byte seed randomness for a note. T.1b: assetDescription '''''''''''''''''''''' -UTF-8 encoding of the Asset description string. +The Asset description byte string. T.1c: flagsIssuance ''''''''''''''''''' From 4acb79ce4efb2b9bf7683fe5a9f1b8e20d4acbec Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Fri, 12 May 2023 16:18:43 +0530 Subject: [PATCH 08/42] Corrections and addition of reference links (#16) This adds in the reference links to the test vectors and reference implementations corresponding to the ZSA Protocol. Some corrections to the notation for better consistency and some updates to the formulae for syncing with the implementation are also included here. --- zip-0226.html | 25 +++++++++++++++---------- zip-0226.rst | 25 ++++++++++++++----------- 2 files changed, 29 insertions(+), 21 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 6636fb043..b9426e8d9 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -123,7 +123,7 @@
  • \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) is the unique element of the Pallas group 15 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6. The byte representation of the Asset Base is defined as - \(\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) + \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .

    • Specifically, we define the note commitment scheme @@ -139,24 +139,27 @@ \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} :=\begin{cases} \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ -\mathsf{cm^{OrchardZSA}} &\text{otherwise} +\mathsf{cm}_{\mathsf{ZSA}} &\text{otherwise} \end{cases} \end{align}\)

    where:

    \(\begin{align} -\mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ -&\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) +\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \\ +&\ + [\mathsf{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""}) \end{align}\)

    Note that \(\mathsf{repr}_{\mathbb{P}}\) - is as defined for the Pallas curve 15, + and + \(\mathsf{GroupHash}^{\mathbb{P}}\) + are as defined for the Pallas curve 15, \(\ell^{\mathsf{Orchard}}_{\mathsf{base}}\) is as defined in §5.3 14, and \(\mathsf{I2LEBSP}\) is as defined in §5.1 13 of the Zcash protocol specification.

    The nullifier is generated in the same manner as in the Orchard protocol 12.

    The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 8. It consists of

    -
    \((\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}^{\mathbb{Y}[32]}, \mathsf{memo} : \mathbb{B}^{\mathbb{Y}[512]})\)
    +
    \((\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, \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) @@ -453,7 +456,7 @@

    • The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility.
    • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
      • -
    • We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
      • +
    • We prevent a potential malleability attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
    • Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets.
      • One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
        • @@ -476,13 +479,15 @@

    Test Vectors

    Reference Implementation

    References

    diff --git a/zip-0226.rst b/zip-0226.rst index ee9fd2cab..b10114f23 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -102,7 +102,7 @@ Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e. A ZSA note differs from an Orchard note [#protocol-notes]_ by additionally including the Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. So a ZSA note is a tuple :math:`(\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})`, where -- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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]_. The byte representation of the Asset Base is defined as :math:`\mathsf{asset\_base} : \mathbb{B}^{\mathbb{Y}[32]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})`. +- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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]_. 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}^{\mathsf{Orchard}})`. Specifically, we define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows: @@ -115,25 +115,26 @@ This note commitment scheme is instantiated using the Sinsemilla Commitment [#pr \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} :=\begin{cases} \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ - \mathsf{cm^{OrchardZSA}} &\text{otherwise} + \mathsf{cm}_{\mathsf{ZSA}} &\text{otherwise} \end{cases} \end{align} where: - + .. math:: \begin{align} - \mathsf{cm}_{\mathsf{ZSA}} &:= \mathsf{SinsemillaCommit}_{\mathsf{rcm}}( \texttt{"z.cash:ZSA-NoteCommit"}, \\ - &\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) + \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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \\ + &\ + [\mathsf{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""}) \end{align} -Note that :math:`\mathsf{repr}_{\mathbb{P}}` is as defined for the Pallas curve [#protocol-pallasandvesta]_, :math:`\ell^{\mathsf{Orchard}}_{\mathsf{base}}` is as defined in §5.3 [#protocol-constants]_, and :math:`\mathsf{I2LEBSP}` is as defined in §5.1 [#protocol-endian]_ of the Zcash protocol specification. +Note that :math:`\mathsf{repr}_{\mathbb{P}}` and :math:`\mathsf{GroupHash}^{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, :math:`\ell^{\mathsf{Orchard}}_{\mathsf{base}}` is as defined in §5.3 [#protocol-constants]_, and :math:`\mathsf{I2LEBSP}` is as defined in §5.1 [#protocol-endian]_ of the Zcash protocol specification. 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 -.. 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}^{\mathbb{Y}[32]}, \mathsf{memo} : \mathbb{B}^{\mathbb{Y}[512]}) +.. 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 ''''''''''''''''''''''''''''' @@ -331,7 +332,7 @@ Security and Privacy Considerations - The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility. - When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design. -- We prevent the "roadblock" attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state. +- We prevent a potential malleability attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state. - Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. - One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. @@ -361,13 +362,15 @@ The Zcash Shielded Assets protocol will be deployed in a subsequent Network Upgr Test Vectors ============ -- LINK TBD +- https://github.com/QED-it/zcash-test-vectors Reference Implementation ======================== -- LINK TBD -- LINK TBD +- https://github.com/QED-it/zcash (in `zcashd`) +- https://github.com/QED-it/orchard (in `orchard`) +- https://github.com/QED-it/librustzcash (in `librustzcash`) +- https://github.com/QED-it/halo2 (in `halo2`) References ========== From 994f55ce0fa9121af4d0a565c45b9d89214e0ad7 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 16 May 2023 16:38:43 +0530 Subject: [PATCH 09/42] Applying suggestions from ZIP review Co-authored-by: Daira Hopwood --- zip-0226.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/zip-0226.rst b/zip-0226.rst index b10114f23..ca18b7363 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -147,7 +147,7 @@ The note commitment output is still indistinguishable from the original Orchard .. math:: \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} \in \mathsf{NoteCommit^{Orchard}.Output} -This definition can be viewed as a hypernym 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 ---------------- @@ -262,7 +262,7 @@ The following constraints must be added to prevent senders from changing the Ass - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^{old}}` to the anchor :math:`\mathsf{rt^{Orchard}}`. - The Nullifier Integrity will be changed to prevent the identification of notes - Replace the :math:`\psi_{old}` value with a generic :math:`\psi'` as :math:`\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})` - - if :math:`\mathtt{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled randomly.) + - if :math:`\mathtt{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled uniformly at random on :math:`\mathbb{F}_{q_{\mathbb{P}}}`.) Backwards Compatibility with ZEC Notes '''''''''''''''''''''''''''''''''''''' @@ -291,7 +291,7 @@ In the case that the balance of all the Action values related to a specific Asse Burn Mechanism Consensus Rules ------------------------------ -1. We require that :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}`. That is, Native Assets are not allowed to be burnt. +1. We require that :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}`. That is, ZEC or TAZ is not allowed to be burnt. 2. We require that for every :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v^{AssetBase}} \neq 0`. 3. We require that there be no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}` has at most one entry in :math:`\mathsf{assetBurn}`. From d7e2660c319501b753d4d3b4b37527846b429e54 Mon Sep 17 00:00:00 2001 From: Antoine Rondelet Date: Sun, 21 May 2023 16:18:50 +0100 Subject: [PATCH 10/42] Added link to nested README for build deps (#17) Link to the nested README in `protocol/README` to install all the dependencies needed to build ZIPs and the specs. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d41b7de0e..4de43cdce 100644 --- a/README.rst +++ b/README.rst @@ -37,7 +37,7 @@ Use ``make`` to check that you are using correct `reStructuredText `__ or `Markdown `__ syntax, and double-check the generated ``draft-*.html`` file before filing a Pull Request. - +See `here `__ for the project dependencies. NU5 ZIPs -------- From 3a914c5031424cf0f069065674a9a4b354fa4758 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 25 May 2023 18:33:13 +0530 Subject: [PATCH 11/42] Handling additional suggestions from PR#649 and PR#628 (#19) Making updates based on pending reviews from [PR#649](https://github.com/zcash/zips/pull/649) and [PR#628](https://github.com/zcash/zips/pull/628). --- zip-0226.html | 27 ++++++++++++++++++--------- zip-0226.rst | 13 +++++++------ 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index b9426e8d9..812bfda14 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -122,7 +122,7 @@
    • \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) - is the unique element of the Pallas group 15 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6. The byte representation of the Asset Base is defined as + is the unique element of the Pallas group 15 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .
    @@ -168,7 +168,7 @@ 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 18 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

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

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

    This definition can be viewed as a hypernym 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

    @@ -264,7 +264,7 @@

    Value Commitment Correctness

    -

    The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes:

    +

    The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base:

    • The fixed-base multiplication constraints between the value and the value base point of the value commitment, \(\mathsf{cv}\) @@ -275,11 +275,11 @@

    Asset Identifier Consistency for Split Actions

    -

    The following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action:

    +

    Senders must not be able to change the Asset Base for the output note in a Split Action. We do this via the following constraints:

    • -
      The Value Commitment Integrity should be changed
      +
      The Value Commitment Integrity should be changed:
      • Replace the input note value by a generic value, @@ -296,11 +296,18 @@
        Add a boolean split_flag variable as an auxiliary witness. This variable is to be activated split_flag = 1 if the Action in question has a Split Input and split_flag = 0 if the Action is actually spending an input note:
          -
        • If split_flag = 1 then set +
        • If + \(\texttt{split_flag} = 1\) + then constrain \(\mathsf{v}' = 0\) - otherwise + otherwise constrain \(\mathsf{v}'=\mathsf{v^{old}}\) from the auxiliary input.
          • +
        • If + \(\texttt{split_flag} = 1\) + then constrain + \(\mathsf{v^{old}} \neq 0\) + .
      @@ -339,7 +346,9 @@ \(\psi' = \psi^{old}\) . (Otherwise \(\psi'\) - should be sampled randomly.)
      • + should be sampled uniformly at random on + \(\mathbb{F}_{q_{\mathbb{P}}}\) + .)
    @@ -376,7 +385,7 @@
    1. We require that \(\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}\) - . That is, Native Assets are not allowed to be burnt.
      2. + . That is, ZEC or TAZ is not allowed to be burnt.
    2. We require that for every \(\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v^{AssetBase}} \neq 0\) .
      3. diff --git a/zip-0226.rst b/zip-0226.rst index ca18b7363..86f46cb2d 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -102,7 +102,7 @@ Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e. A ZSA note differs from an Orchard note [#protocol-notes]_ by additionally including the Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. So a ZSA note is a tuple :math:`(\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})`, where -- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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]_. 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}^{\mathsf{Orchard}})`. +- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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 non-bottom group element that is not the identity. 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}^{\mathsf{Orchard}})`. Specifically, we define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows: @@ -233,7 +233,7 @@ Circuit Statement Every *ZSA Action statement* is closely similar to the Orchard Action statement [#protocol-actionstatement]_, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below. Asset Base Equality -''''''''''''''''''''''''' +''''''''''''''''''' The following constraints must be added to ensure that the input and output note are of the same :math:`\mathsf{AssetBase}`: @@ -244,7 +244,7 @@ The following constraints must be added to ensure that the input and output note Value Commitment Correctness '''''''''''''''''''''''''''' -The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base, as represented in the notes: +The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base: - The fixed-base multiplication constraints between the value and the value base point of the value commitment, :math:`\mathsf{cv}`, is replaced with a variable-base multiplication between the two. - The witness to the value base point (as defined in the `asset base`_ equation) is the auxiliary input :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`. @@ -252,12 +252,13 @@ The following constraints must be added to ensure that the value commitment is c Asset Identifier Consistency for Split Actions '''''''''''''''''''''''''''''''''''''''''''''' -The following constraints must be added to prevent senders from changing the Asset Base for the output note in a Split Action: +Senders must not be able to change the Asset Base for the output note in a Split Action. We do this via the following constraints: -- The Value Commitment Integrity should be changed +- The Value Commitment Integrity should be changed: - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}` - Add a boolean ``split_flag`` variable as an auxiliary witness. This variable is to be activated ``split_flag = 1`` if the Action in question has a Split Input and ``split_flag = 0`` if the Action is actually spending an input note: - - If ``split_flag = 1`` then set :math:`\mathsf{v}' = 0` otherwise :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. + - If :math:`\texttt{split_flag} = 1` then constrain :math:`\mathsf{v}' = 0` otherwise constrain :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. + - If :math:`\texttt{split_flag} = 1` then constrain :math:`\mathsf{v^{old}} \neq 0`. - The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes): - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^{old}}` to the anchor :math:`\mathsf{rt^{Orchard}}`. - The Nullifier Integrity will be changed to prevent the identification of notes From 01c8f04e97b4c9fc7cde13ededba084698c7a258 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 25 May 2023 18:59:15 +0530 Subject: [PATCH 12/42] Updates to `txid_digest` (#15) This details the changes to the transaction digest algorithm for the ZSA protocol. - A new branch is added for hashing the information in a transaction related to issuance. - Some branches are added and modified in the orchard_digest subtree to account for the additional Asset Base value that needs to be hashed. --- zip-0226.html | 181 +++++++++++++++++++++++++++++++++++------------ zip-0226.rst | 109 +++++++++++++++++++++++++--- zip-0227.html | 192 ++++++++++++++++++++++++++++++++++---------------- zip-0227.rst | 155 ++++++++++++++++++++++++++++++---------- 4 files changed, 485 insertions(+), 152 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 812bfda14..fbbeece9d 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -59,26 +59,26 @@ . This Asset Identifier maps to an Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 6.

      -

      The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 9 is preserved across Assets (see the Orchard Binding Signature 11), and by extension the balance of an Orchard transaction. That is, the sum of all the +

      The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 14 is preserved across Assets (see the Orchard Binding Signature 16), and by extension the balance of an Orchard transaction. That is, the sum of all the \(\mathsf{value^{net}}\) from each Action Description, computed as \(\mathsf{value^{old}-value^{new}}\) , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

      -

      As was initially proposed by Jack Grigg and Daira Hopwood 23 24, we propose to make this happen by changing the value base point, +

      As was initially proposed by Jack Grigg and Daira Hopwood 28 29, we propose to make this happen by changing the value base point, \(\mathcal{V}^{\mathsf{Orchard}}\) , in the Homomorphic Pedersen Commitment that derives the value commitment, \(\mathsf{cv^{net}}\) , of the net value in an Orchard Action.

      Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - an auxiliary input to the proof for each Action statement 21, represented already as a point on the Pallas curve. The circuit then should check that the same + an auxiliary input to the proof for each Action statement 26, represented already as a point on the Pallas curve. The circuit then should check that the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - is used in the old note commitment and the new note commitment 18, and as the base point + is used in the old note commitment and the new note commitment 23, and as the base point \(\mathcal{V}^\mathsf{Orchard}\) - in the value commitment 19. This ensures (1) that the input and output notes are of the same + in the value commitment 24. This ensures (1) that the input and output notes are of the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) , and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

      -

      In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 20 for Custom Assets, as we need to enforce that the +

      In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 25 for Custom Assets, as we need to enforce that the \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) of the output note of that Split Action is the output of a valid \(\mathsf{ZSAValueBase^{Orchard}}\) @@ -114,7 +114,7 @@ be the type of a ZSA note, i.e. \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*\) .

      -

      A ZSA note differs from an Orchard note 7 by additionally including the Asset Base, +

      A ZSA note differs from an Orchard note 12 by additionally including the Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) . So a ZSA note is a tuple \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})\) @@ -122,7 +122,7 @@

      • \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) - is the unique element of the Pallas group 15 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as + is the unique element of the Pallas group 20 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .
      @@ -132,9 +132,9 @@
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)

      where \(\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}\) - are as defined for the Pallas curve 15, and + are as defined for the Pallas curve 20, and \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) - are as defined in the Zcash protocol specification 10. This note commitment scheme is instantiated using the Sinsemilla Commitment 18 as follows:

      + are as defined in the Zcash protocol specification 15. This note commitment scheme is instantiated using the Sinsemilla Commitment 23 as follows:

      \(\begin{align} \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} :=\begin{cases} @@ -152,21 +152,21 @@ \(\mathsf{repr}_{\mathbb{P}}\) and \(\mathsf{GroupHash}^{\mathbb{P}}\) - are as defined for the Pallas curve 15, + are as defined for the Pallas curve 20, \(\ell^{\mathsf{Orchard}}_{\mathsf{base}}\) - is as defined in §5.3 14, and + is as defined in §5.3 19, and \(\mathsf{I2LEBSP}\) - is as defined in §5.1 13 of the Zcash protocol specification.

      -

      The nullifier is generated in the same manner as in the Orchard protocol 12.

      -

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 8. It consists of

      + is as defined in §5.1 18 of the Zcash protocol specification.

      +

      The nullifier is generated in the same manner as in the Orchard protocol 17.

      +

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 13. It consists of

      \((\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, \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) , differs from the Orchard note commitment \(\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 18 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

      -

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

      + 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 23 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

      +

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

      \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} \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.

      @@ -193,7 +193,7 @@ \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}\) so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4.

      Rationale for Value Commitment

      -

      The Orchard Protocol uses a Homomorphic Pedersen Commitment 19 to perform the value commitment, with fixed base points +

      The Orchard Protocol uses a Homomorphic Pedersen Commitment 24 to perform the value commitment, with fixed base points \(\mathcal{V}^{\mathsf{Orchard}}\) and \(\mathcal{R}^{\mathsf{Orchard}}\) @@ -202,7 +202,7 @@

    Value Balance Verification

    -

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 11.

    +

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 16.

    For a total of \(n\) Actions in a transfer, the prover MUST still sign the SIGHASH of the transaction using the binding signature key @@ -235,14 +235,14 @@

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

    • Rationale for Split Notes

    -

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 20 to the Actions that have not been assigned input notes.

    +

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 25 to the Actions that have not been assigned input notes.

    The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

    Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the split_flag boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified.

    Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets.

    Circuit Statement

    -

    Every ZSA Action statement is closely similar to the Orchard Action statement 21, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    +

    Every ZSA Action statement is closely similar to the Orchard Action statement 26, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    Asset Base Equality

    The following constraints must be added to ensure that the input and output note are of the same \(\mathsf{AssetBase}\) @@ -251,12 +251,12 @@

  • The Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) , for the note is witnessed once, as an auxiliary input.
    • -
  • In the Old note commitment integrity constraint in the Orchard Action statement 21, +
  • In the Old note commitment integrity constraint in the Orchard Action statement 26, \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) .
    • -
  • In the New note commitment integrity constraint in the Orchard Action statement 21, +
  • In the New note commitment integrity constraint in the Orchard Action statement 26, \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) @@ -356,7 +356,7 @@

    • Backwards Compatibility with ZEC Notes

    -

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 10. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    +

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 15. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    @@ -401,7 +401,7 @@

    ZSA Transaction Structure

    -

    The transaction format is similar to the version 5 transaction format described in the Zcash specification 22, with the following additions to the Orchard bundle:

    +

    The transaction format is similar to the version 5 transaction format described in the Zcash specification 27, with the following additions to the Orchard bundle:

    @@ -461,6 +461,57 @@
    +

    TxId Digest

    +

    The transaction digest algorithm defined in ZIP 244 10 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

    +

    A BLAKE2b-256 hash of the following values

    + 
    T.1: header_digest       (32-byte hash output)
+T.2: transparent_digest  (32-byte hash output)
+T.3: sapling_digest      (32-byte hash output)
+T.4: orchard_digest      (32-byte hash output)  [UPDATED FOR ZSA]
+T.5: issuance_digest     (32-byte hash output)  [ADDED FOR ZSA]
    +

    The personalization field remains the same as in ZIP 244 10.

    +

    T.4: orchard_digest

    +

    When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values

    + 
    T.4a: orchard_actions_compact_digest      (32-byte hash output)          [UPDATED FOR ZSA]
+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.4f: anchorOrchard                       (32 bytes)
    +
    T.4a: orchard_actions_compact_digest
    +

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 11 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    + 
    T.4a.i  : nullifier            (field encoding bytes)
+T.4a.ii : cmx                  (field encoding bytes)
+T.4a.iii: ephemeralKey         (field encoding bytes)
+T.4a.iv : encCiphertext[..84]  (First 84 bytes of field encoding)  [UPDATED FOR ZSA]
    +

    The personalization field of this hash is the same as in ZIP 244:

    + 
    "ZTxIdOrcActCHash"
    +
    +
    T.4b: orchard_actions_memos_digest
    +

    A BLAKE2b-256 hash of the subset of Orchard shielded memo field data for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    + 
    T.4b.i: encCiphertext[84..596] (contents of the encrypted memo field)  [UPDATED FOR ZSA]
    +

    The personalization field of this hash remains identical to ZIP 244:

    + 
    "ZTxIdOrcActMHash"
    +
    +
    T.4c: orchard_actions_noncompact_digest
    +

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 11 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    + 
    T.4d.i  : cv                    (field encoding bytes)
+T.4d.ii : rk                    (field encoding bytes)
+T.4d.iii: encCiphertext[596..]  (post-memo suffix of field encoding)  [UPDATED FOR ZSA]
+T.4d.iv : outCiphertext         (field encoding bytes)
    +

    The personalization field of this hash is defined identically to ZIP 244:

    + 
    "ZTxIdOrcActNHash"
    +
    +
    +

    T.5: issuance_digest

    +

    The details of the computation of this value are in ZIP 227 7.

    +
    +
    +
    +

    Signature Digest and Authorizing Data Commitment

    +

    The details of the changes to these algorithms are in ZIP 227 8 9.

    +

    Security and Privacy Considerations

    • The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility.
      • @@ -475,7 +526,7 @@

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 25.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 30.

    Backward Compatibility

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the @@ -548,10 +599,50 @@ - +
    + + + +
    7ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance
    + + + + + + + +
    8ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest
    + + + + + + + +
    9ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment
    + + + + + + + +
    10ZIP 244: Transaction Identifier Non-Malleability
    + + + + + + + +
    11ZIP 307: Light Client Protocol for Payment Detection
    + + + + @@ -559,7 +650,7 @@
    12 Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes
    - + @@ -567,7 +658,7 @@
    813 Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields
    - + @@ -575,7 +666,7 @@
    914 Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions
    - + @@ -583,7 +674,7 @@
    1015 Zcash Protocol Specification, Version 2022.3.8. Section 4.1.8: Commitment
    - + @@ -591,7 +682,7 @@
    1116 Zcash Protocol Specification, Version 2022.3.8. Section 4.14: Balance and Binding Signature (Orchard)
    - + @@ -599,7 +690,7 @@
    1217 Zcash Protocol Specification, Version 2022.3.8. Section 4.16: Note Commitments and Nullifiers
    - + @@ -607,7 +698,7 @@
    1318 Zcash Protocol Specification, Version 2022.3.8. Section 5.1: Integers, Bit Sequences, and Endianness
    - + @@ -615,7 +706,7 @@
    1419 Zcash Protocol Specification, Version 2022.3.8. Section 5.3: Constants
    - + @@ -623,7 +714,7 @@
    1520 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.6: Pallas and Vesta
    - + @@ -631,7 +722,7 @@
    1621 Pallas/Vesta supporting evidence
    - + @@ -639,7 +730,7 @@
    1722 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.1.9: Sinsemilla hash function
    - + @@ -647,7 +738,7 @@
    1823 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.4: Sinsemilla commitments
    - + @@ -655,7 +746,7 @@
    1924 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
    - + @@ -663,7 +754,7 @@
    2025 Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard)
    - + @@ -671,7 +762,7 @@
    2126 Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard)
    - + @@ -679,7 +770,7 @@
    2227 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    - + @@ -687,7 +778,7 @@
    2328 User-Defined Assets and Wrapped Assets
    - + @@ -695,7 +786,7 @@
    2429 Comment on Generalized Value Commitments
    - + diff --git a/zip-0226.rst b/zip-0226.rst index 86f46cb2d..57f08f626 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -89,7 +89,7 @@ For every new Asset, there must be a new and unique Asset Identifier. Every Asse This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. 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]_. @@ -137,7 +137,7 @@ 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. @@ -167,7 +167,7 @@ where :math:`\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{A We define :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}` so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 [#zip-0224]_. Rationale for Value Commitment -'''''''''''''''''''''''''''''' +`````````````````````````````` The Orchard Protocol uses a Homomorphic Pedersen Commitment [#protocol-concretevaluecommit]_ to perform the value commitment, with fixed base points :math:`\mathcal{V}^{\mathsf{Orchard}}` and :math:`\mathcal{R}^{\mathsf{Orchard}}` as the values represent the amount of ZEC being transferred. @@ -189,7 +189,7 @@ Then the verifier MUST compute and use it to verify the `bindingSignature` on the `SIGHASH` message. Rationale for Value Balance Verification -'''''''''''''''''''''''''''''''''''''''' +```````````````````````````````````````` The main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is *burnt*, as we will see below in the `burn mechanism`_. @@ -215,7 +215,7 @@ Wallets and other clients have to choose from the following to ensure the Asset 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). Rationale for Split Notes -''''''''''''''''''''''''' +````````````````````````` In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives *dummy spend notes* [#protocol-dummynotes]_ to the Actions that have not been assigned input notes. @@ -233,7 +233,7 @@ Circuit Statement Every *ZSA Action statement* is closely similar to the Orchard Action statement [#protocol-actionstatement]_, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below. Asset Base Equality -''''''''''''''''''' +``````````````````` The following constraints must be added to ensure that the input and output note are of the same :math:`\mathsf{AssetBase}`: @@ -242,7 +242,7 @@ The following constraints must be added to ensure that the input and output note - In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. Value Commitment Correctness -'''''''''''''''''''''''''''' +```````````````````````````` The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base: @@ -250,7 +250,7 @@ The following constraints must be added to ensure that the value commitment is c - The witness to the value base point (as defined in the `asset base`_ equation) is the auxiliary input :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`. Asset Identifier Consistency for Split Actions -'''''''''''''''''''''''''''''''''''''''''''''' +`````````````````````````````````````````````` Senders must not be able to change the Asset Base for the output note in a Split Action. We do this via the following constraints: @@ -266,7 +266,7 @@ Senders must not be able to change the Asset Base for the output note in a Split - if :math:`\mathtt{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled uniformly at random on :math:`\mathbb{F}_{q_{\mathbb{P}}}`.) Backwards Compatibility with ZEC Notes -'''''''''''''''''''''''''''''''''''''' +`````````````````````````````````````` The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion [#protocol-abstractcommit]_. If the note is a ZSA note, the note commitment is computed as defined in the `Note Structure & Commitment`_ section. @@ -327,6 +327,92 @@ A ZSA Asset Burn description is encoded in a transaction as an of a AssetBurn ty | 8 | valueBurn | :math:`\{1 .. 2^{64} - 1\}` | The amount of the AssetType being burnt. | +-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +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. + +txid_digest +----------- +A BLAKE2b-256 hash of the following values :: + + T.1: header_digest (32-byte hash output) + T.2: transparent_digest (32-byte hash output) + T.3: sapling_digest (32-byte hash output) + T.4: orchard_digest (32-byte hash output) [UPDATED FOR ZSA] + T.5: issuance_digest (32-byte hash output) [ADDED FOR ZSA] + +The personalization field remains the same as in ZIP 244 [#zip-0244]_. + +T.4: orchard_digest +``````````````````` +When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values :: + + T.4a: orchard_actions_compact_digest (32-byte hash output) [UPDATED FOR ZSA] + 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.4f: anchorOrchard (32 bytes) + +T.4a: orchard_actions_compact_digest +'''''''''''''''''''''''''''''''''''' + +A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in +an updated version of the ZIP-307 [#zip-0307]_ ``CompactBlock`` format for all Orchard +Actions belonging to the transaction. For each Action, the following elements are included +in the hash:: + + T.4a.i : nullifier (field encoding bytes) + T.4a.ii : cmx (field encoding bytes) + T.4a.iii: ephemeralKey (field encoding bytes) + T.4a.iv : encCiphertext[..84] (First 84 bytes of field encoding) [UPDATED FOR ZSA] + +The personalization field of this hash is the same as in ZIP 244:: + + "ZTxIdOrcActCHash" + + +T.4b: orchard_actions_memos_digest +'''''''''''''''''''''''''''''''''' + +A BLAKE2b-256 hash of the subset of Orchard shielded memo field data for all Orchard +Actions belonging to the transaction. For each Action, the following elements are included +in the hash:: + + T.4b.i: encCiphertext[84..596] (contents of the encrypted memo field) [UPDATED FOR ZSA] + +The personalization field of this hash remains identical to ZIP 244:: + + "ZTxIdOrcActMHash" + + +T.4c: orchard_actions_noncompact_digest +''''''''''''''''''''''''''''''''''''''' + +A BLAKE2b-256 hash of the remaining subset of Orchard Action information **not** intended +for inclusion in an updated version of the the ZIP 307 [#zip-0307]_ ``CompactBlock`` +format, for all Orchard Actions belonging to the transaction. For each Action, +the following elements are included in the hash:: + + T.4d.i : cv (field encoding bytes) + T.4d.ii : rk (field encoding bytes) + T.4d.iii: encCiphertext[596..] (post-memo suffix of field encoding) [UPDATED FOR ZSA] + T.4d.iv : outCiphertext (field encoding bytes) + +The personalization field of this hash is defined identically to ZIP 244:: + + "ZTxIdOrcActNHash" + +T.5: issuance_digest +```````````````````` +The details of the computation of this value are in ZIP 227 [#zip-0227-txiddigest]_. + +Signature Digest and Authorizing Data Commitment +================================================ + +The details of the changes to these algorithms are in ZIP 227 [#zip-0227-sigdigest]_ [#zip-0227-authcommitment]_. Security and Privacy Considerations =================================== @@ -382,6 +468,11 @@ References .. [#zip-0224] `ZIP 224: Orchard `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ +.. [#zip-0227-txiddigest] `ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance `_ +.. [#zip-0227-sigdigest] `ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest `_ +.. [#zip-0227-authcommitment] `ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment `_ +.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection `_ .. [#protocol-notes] `Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes `_ .. [#protocol-notept] `Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields `_ .. [#protocol-actions] `Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions `_ diff --git a/zip-0227.html b/zip-0227.html index 4dde8986f..4e1773218 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -35,7 +35,7 @@

    Abstract

    -

    ZIP 226 4 and ZIP 227 6 propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 6. The transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    +

    ZIP 226 4 and ZIP 227 7 propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 7. The transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    Motivation

    This ZIP is a supporting ZIP for ZIP 226 4, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function.

    @@ -63,7 +63,7 @@

    Specification: Issuance Keys and Issuance Authorization Signature Scheme

    -

    The ZSA Protocol adds the following three keys to the key components 15:

    +

    The ZSA Protocol adds the following three keys to the key components 18:

    1. The issuance master key, denoted as \(\mathsf{sk}_{\mathsf{iss}}\) @@ -85,7 +85,7 @@ \(\mathsf{IssueAuthSig}\) similar to \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) - , the Orchard spend authorization signature scheme 19. Specifically, we instantiate + , the Orchard spend authorization signature scheme 22. Specifically, we instantiate \(\mathsf{IssueAuthSig}\) as \(\mathsf{RedPallas}\) @@ -93,23 +93,23 @@ \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in the Zcash protocol specification 16.

      + is defined as in the Zcash protocol specification 19.

    Issuance Key Derivation

    The issuance master key is generated by choosing a bit sequence uniformly at random from \(\mathbb{B}^{\mathbb{Y}[32]}\) - , like the Orchard spending key 17.

    + , like the Orchard spending key 20.

    Issuance master key derivation for hierarchical deterministic wallets

    -

    The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 10. We reuse the functions defined there in what follows in this section.

    +

    The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 13. We reuse the functions defined there in what follows in this section.

    Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\) .

    -

    As in ZIP 32 for Orchard 11, we only use hardened child key derivation for the issuance master key. We reuse the +

    As in ZIP 32 for Orchard 14, we only use hardened child key derivation for the issuance master key. We reuse the \(\mathsf{CDKsk}\) function for Orchard child key derivation from ZIP 32.

    -

    We use the notation of ZIP 32 13 for shielded HD paths, and define the issuance master key path as +

    We use the notation of ZIP 32 16 for shielded HD paths, and define the issuance master key path as \(m_\mathsf{Issuance} / purpose / coin\_type' / account'\) . We fix the path levels as follows:

      @@ -122,7 +122,7 @@ ) following the BIP 43 recommendation.
    • \(coin\_type\) - : Defined as in ZIP 32 12.
      • + : Defined as in ZIP 32 15.
    • \(account\) : fixed to index @@ -136,7 +136,7 @@ .

    Derivation of issuance authorizing key and issuance validating key

    -

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 17, as described below.

    +

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 20, as described below.

    • The issuance authorizing key is derived from the issuance master key, \(\mathsf{sk}_{\mathsf{iss}}\) @@ -149,7 +149,7 @@ , as a public verification key:
    \(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
    -

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 9. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    +

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 12. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    @@ -192,7 +192,7 @@ \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 16.

    + is defined as in 19.

    The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

    @@ -302,7 +302,7 @@ \(\mathsf{isk}\) , that validates the issuance . -

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 21.

    +

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 24.

    2530 ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
    @@ -479,57 +479,60 @@ -

    TxId Digest

    -

    As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

    -

    A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

    - 
    issuance_txid_digest
+        
    TxId Digest - Issuance 
    
+            
    This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 8, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.
    
+            
    A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:
    
+            
    issuance_digest
 ├── issue_actions_digest
+│   ├── issue_notes_digest
+│   ├── assetDescription
+│   └── flagsIssuance
 └── issuanceValidatingKey
    
             
    In the specification below, nodes of the tree are presented in depth-first order.
    
-            
    issuance_txid_digest 
    
+            
    T.5: issuance_digest 
    
                 
    A BLAKE2b-256 hash of the following values
    
-                
    T.1: issue_actions_digest    (32-byte hash output)
-T.2: issuanceValidatingKey   (32 bytes)
    
+                
    T.5a: issue_actions_digest    (32-byte hash output)
+T.5b: issuanceValidatingKey   (32 bytes)
    
                 
    The personalization field of this hash is set to:
    
                 
    "ZTxIdSAIssueHash"
    
                 
    In case the transaction has no issuance components, ''issue_actions_digest'' is:
    
                 
    BLAKE2b-256("ZTxIdSAIssueHash", [])
    
-                
    T.1: issue_actions_digest 
    
+                
    T.5a: issue_actions_digest 
    
                     
    A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:
    
-                    
    T.1a: notes_digest            (32-byte hash output)
-T.1b: assetDescription        (field encoding bytes)
-T.1c: flagsIssuance           (1 byte)
    
+                    
    T.5a.i  : notes_digest            (32-byte hash output)
+T.5a.ii : assetDescription        (field encoding bytes)
+T.5a.iii: flagsIssuance           (1 byte)
    
                     
    The personalization field of this hash is set to:
    
                     
    "ZTxIdIssActHash"
    
-                    
    T.1a: notes_digest 
    
+                    
    T.5a.i: issue_notes_digest 
    
                         
    A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:
    
-                        
    T.1a.1: recipient                    (field encoding bytes)
-T.1a.2: value                        (field encoding bytes)
-T.1a.3: asset                        (field encoding bytes)
-T.1a.4: rho                          (field encoding bytes)
-T.1a.5: rseed                        (field encoding bytes)
    
+                        
    T.5a.i.1: recipient                    (field encoding bytes)
+T.5a.i.2: value                        (field encoding bytes)
+T.5a.i.3: assetBase                    (field encoding bytes)
+T.5a.i.4: rho                          (field encoding bytes)
+T.5a.i.5: rseed                        (field encoding bytes)
    
                         
    The personalization field of this hash is set to:
    
                         
    "ZTxIdIANoteHash"
    
-                        
    T.1a.1: recipient 
    
-                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 20.
    
+                        
    T.5a.i.1: recipient 
    
+                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 23.
    
                         
    
-                        
    T.1a.2: value 
    
+                        
    T.5a.i.2: value 
    
                             
    Note value encoded as little-endian 8-byte representation of u64 raw value.
    
                         
    
-                        
    T.1a.3: asset 
    
-                            
    Asset Base encoded as 32-byte representation of Pallas point.
    
+                        
    T.5a.i.3: assetBase 
    
+                            
    Asset Base encoded as the 32-byte representation of a point on the Pallas curve.
    
                         
    
-                        
    T.1a.4: rho 
    
-                            
    Nullifier encoded as 32-byte representation of Pallas point.
    
+                        
    T.5a.i.4: rho 
    
+                            
    Nullifier encoded as 32-byte representation of a point on the Pallas curve.
    
                         
    
-                        
    T.1a.5: rseed 
    
+                        
    T.5a.i.5: rseed 
    
                             
    The ZIP 212 32-byte seed randomness for a note.
    
                         
    
                     
    
-                    
    T.1b: assetDescription 
    
+                    
    T.5a.ii: assetDescription 
    
                         
    The Asset description byte string.
    
                     
    
-                    
    T.1c: flagsIssuance 
    
+                    
    T.5a.iii: flagsIssuance 
    
                         
    An 8-bit value representing a set of flags. Ordered from LSB to MSB:
    
                         
      
                             
    • finalize
      • 
@@ -537,11 +540,58 @@
                         
    
                     
    
                 
    
-                
    T.2: issuanceValidatingKey 
    
+                
    T.5b: issuanceValidatingKey 
    
                     
    A byte encoding of issuance validating key for the bundle as defined in the Issuance Key Derivation section.
    
                 
    
             
    
         
    
+        
    Signature Digest 
    
+            
    The per-input transaction digest algorithm to generate the signature digest in ZIP 244 9 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.
    
+            
    The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:
    
+            
    signature_digest
+├── header_digest
+├── transparent_sig_digest
+├── sapling_digest
+├── orchard_digest
+└── issuance_digest         [ADDED FOR ZSA]
    
+            
    signature_digest 
    
+                
    A BLAKE2b-256 hash of the following values
    
+                
    S.1: header_digest          (32-byte hash output)
+S.2: transparent_sig_digest (32-byte hash output)
+S.3: sapling_digest         (32-byte hash output)
+S.4: orchard_digest         (32-byte hash output)
+S.5: issuance_digest        (32-byte hash output)  [ADDED FOR ZSA]
    
+                
    The personalization field remains the same as in ZIP 244 8.
    
+                
    S.5: issuance_digest 
    
+                    
    Identical to that specified for the transaction identifier.
    
+                
    
+            
    
+        
    
+        
    Authorizing Data Commitment 
    
+            
    The transaction digest algorithm defined in ZIP 244 10 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:
    
+            
    auth_digest
+├── transparent_scripts_digest
+├── sapling_auth_digest
+├── orchard_auth_digest
+└── issuance_auth_digest        [ADDED FOR ZSA]
    
+            
    The pair (Transaction Identifier, Auth Commitment) constitutes a commitment to all the data of a serialized transaction that may be included in a block.
    
+            
    auth_digest 
    
+                
    A BLAKE2b-256 hash of the following values
    
+                
    A.1: transparent_scripts_digest (32-byte hash output)
+A.2: sapling_auth_digest        (32-byte hash output)
+A.3: orchard_auth_digest        (32-byte hash output)
+A.4: issuance_auth_digest       (32-byte hash output)  [ADDED FOR ZSA]
    
+                
    The personalization field of this hash remains the same as in ZIP 244.
    
+                
    A.4: issuance_auth_digest 
    
+                    
    In the case that Issuance Actions are present, this is a BLAKE2b-256 hash of the field encoding of the issueAuthSig field of the transaction:
    
+                    
    A.4a: issueAuthSig            (field encoding bytes)
    
+                    
    The personalization field of this hash is set to:
    
+                    
    "ZTxAuthZSAOrHash"
    
+                    
    In the case that the transaction has no Orchard Actions, issuance_auth_digest is
    
+                    
    BLAKE2b-256("ZTxAuthZSAOrHash", [])
    
+                
    
+            
    
+        
    
         
    Security and Privacy Considerations 
    
             
    Issuance Key Compromise 
    
                 
    The design of this protocol does not currently allow for a rotation of the issuance validating key that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended:
    
@@ -554,7 +604,7 @@
                 
             
    
             
    Bridging Assets 
    
-                
    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.
    
+                
    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.
    
             
    
         
    
         
    Other Considerations 
    
@@ -566,7 +616,7 @@
                  in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.
    
             
    
             
    Fee Structures 
    
-                
    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 8.
    
+                
    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 11.
    
             
    
             
    Future Work 
    
                 
    In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying
@@ -629,10 +679,18 @@
    - +
    + + + +
    6ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest
    + + + + @@ -640,15 +698,31 @@
    7 ZIP 227: Issuance of Zcash Shielded Assets
    - +
    78 ZIP 244: Transaction Identifier Non-Malleability
    + + + + + + + +
    9ZIP 244: Transaction Identifier Non-Malleability: Signature Digest
    + + + + + + + +
    10ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment
    - + @@ -656,7 +730,7 @@
    811 ZIP 317b: ZSA Extension Proportional Fee Mechanism
    - + @@ -664,7 +738,7 @@
    912 ZIP 32: Shielded Hierarchical Deterministic Wallets
    - + @@ -672,7 +746,7 @@
    1013 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation
    - + @@ -680,7 +754,7 @@
    1114 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation
    - + @@ -688,7 +762,7 @@
    1215 ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels
    - + @@ -696,7 +770,7 @@
    1316 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path
    - + @@ -704,7 +778,7 @@
    1417 ZIP 316: Unified Addresses and Unified Viewing Keys
    - + @@ -712,7 +786,7 @@
    1518 Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
    - + @@ -720,7 +794,7 @@
    1619 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
    - + @@ -728,7 +802,7 @@
    1720 Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
    - + @@ -736,7 +810,7 @@
    1821 Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -744,7 +818,7 @@
    1922 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -752,7 +826,7 @@
    2023 Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
    - + diff --git a/zip-0227.rst b/zip-0227.rst index a21f1cf08..de7e9a4f4 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -313,25 +313,30 @@ Concrete Applications -TxId Digest -=========== +TxId Digest - Issuance +====================== +This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. +Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 [#zip-0226-txiddigest]_. As in ZIP 244 [#zip-0244]_, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used. -A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:: +A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:: - issuance_txid_digest - ├── issue_actions_digest - └── issuanceValidatingKey + issuance_digest + ├── issue_actions_digest + │   ├── issue_notes_digest + │   ├── assetDescription + │   └── flagsIssuance + └── issuanceValidatingKey In the specification below, nodes of the tree are presented in depth-first order. -issuance_txid_digest +T.5: issuance_digest -------------------- A BLAKE2b-256 hash of the following values :: - T.1: issue_actions_digest (32-byte hash output) - T.2: issuanceValidatingKey (32 bytes) + T.5a: issue_actions_digest (32-byte hash output) + T.5b: issuanceValidatingKey (32 bytes) The personalization field of this hash is set to:: @@ -341,68 +346,137 @@ In case the transaction has no issuance components, ''issue_actions_digest'' is: BLAKE2b-256("ZTxIdSAIssueHash", []) -T.1: issue_actions_digest -````````````````````````` +T.5a: issue_actions_digest +`````````````````````````` A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:: - T.1a: notes_digest (32-byte hash output) - T.1b: assetDescription (field encoding bytes) - T.1c: flagsIssuance (1 byte) + T.5a.i : notes_digest (32-byte hash output) + T.5a.ii : assetDescription (field encoding bytes) + T.5a.iii: flagsIssuance (1 byte) The personalization field of this hash is set to:: "ZTxIdIssActHash" -T.1a: notes_digest -'''''''''''''''''' +T.5a.i: issue_notes_digest +'''''''''''''''''''''''''' A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:: - T.1a.1: recipient (field encoding bytes) - T.1a.2: value (field encoding bytes) - T.1a.3: asset (field encoding bytes) - T.1a.4: rho (field encoding bytes) - T.1a.5: rseed (field encoding bytes) + T.5a.i.1: recipient (field encoding bytes) + T.5a.i.2: value (field encoding bytes) + T.5a.i.3: assetBase (field encoding bytes) + T.5a.i.4: rho (field encoding bytes) + T.5a.i.5: rseed (field encoding bytes) The personalization field of this hash is set to:: "ZTxIdIANoteHash" -T.1a.1: recipient -................. +T.5a.i.1: recipient +................... This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification [#protocol-orchardpaymentaddrencoding]_. -T.1a.2: value -............. +T.5a.i.2: value +............... Note value encoded as little-endian 8-byte representation of u64 raw value. -T.1a.3: asset -............. -Asset Base encoded as 32-byte representation of Pallas point. +T.5a.i.3: assetBase +................... +Asset Base encoded as the 32-byte representation of a point on the Pallas curve. -T.1a.4: rho -........... -Nullifier encoded as 32-byte representation of Pallas point. - -T.1a.5: rseed +T.5a.i.4: rho ............. +Nullifier encoded as 32-byte representation of a point on the Pallas curve. + +T.5a.i.5: rseed +............... The ZIP 212 32-byte seed randomness for a note. -T.1b: assetDescription -'''''''''''''''''''''' +T.5a.ii: assetDescription +''''''''''''''''''''''''' The Asset description byte string. -T.1c: flagsIssuance -''''''''''''''''''' +T.5a.iii: flagsIssuance +''''''''''''''''''''''' An 8-bit value representing a set of flags. Ordered from LSB to MSB: - ``finalize`` - The remaining bits are set to `0`. -T.2: issuanceValidatingKey -`````````````````````````` +T.5b: issuanceValidatingKey +``````````````````````````` A byte encoding of issuance validating key for the bundle as defined in the `Issuance Key Derivation`_ section. +Signature Digest +================ + +The per-input transaction digest algorithm to generate the signature digest in ZIP 244 [#zip-0244-sigdigest]_ is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. +For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly. + +The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:: + + signature_digest + ├── header_digest + ├── transparent_sig_digest + ├── sapling_digest + ├── orchard_digest + └── issuance_digest [ADDED FOR ZSA] + +signature_digest +---------------- +A BLAKE2b-256 hash of the following values :: + + S.1: header_digest (32-byte hash output) + S.2: transparent_sig_digest (32-byte hash output) + S.3: sapling_digest (32-byte hash output) + S.4: orchard_digest (32-byte hash output) + S.5: issuance_digest (32-byte hash output) [ADDED FOR ZSA] + +The personalization field remains the same as in ZIP 244 [#zip-0244]_. + +S.5: issuance_digest +```````````````````` +Identical to that specified for the transaction identifier. + +Authorizing Data Commitment +=========================== + +The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. +We highlight the changes for the ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:: + + auth_digest + ├── transparent_scripts_digest + ├── sapling_auth_digest + ├── orchard_auth_digest + └── issuance_auth_digest [ADDED FOR ZSA] + +The pair (Transaction Identifier, Auth Commitment) constitutes a commitment to all the data of a serialized transaction that may be included in a block. + +auth_digest +----------- +A BLAKE2b-256 hash of the following values :: + + A.1: transparent_scripts_digest (32-byte hash output) + A.2: sapling_auth_digest (32-byte hash output) + A.3: orchard_auth_digest (32-byte hash output) + A.4: issuance_auth_digest (32-byte hash output) [ADDED FOR ZSA] + +The personalization field of this hash remains the same as in ZIP 244. + +A.4: issuance_auth_digest +````````````````````````` +In the case that Issuance Actions are present, this is a BLAKE2b-256 hash of the field encoding of the ``issueAuthSig`` field of the transaction:: + + A.4a: issueAuthSig (field encoding bytes) + +The personalization field of this hash is set to:: + + "ZTxAuthZSAOrHash" + +In the case that the transaction has no Orchard Actions, ``issuance_auth_digest`` is :: + + BLAKE2b-256("ZTxAuthZSAOrHash", []) Security and Privacy Considerations =================================== @@ -461,8 +535,11 @@ References .. [#zip-0224] `ZIP 224: Orchard `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ +.. [#zip-0226-txiddigest] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ .. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0244-sigdigest] `ZIP 244: Transaction Identifier Non-Malleability: Signature Digest `_ +.. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment `_ .. [#zip-0317b] `ZIP 317b: ZSA Extension Proportional Fee Mechanism `_ .. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ .. [#zip-0032-orchard-master] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation `_ From a434b9ea3b32c4eddf83ad37bcf950dcdf758e8c Mon Sep 17 00:00:00 2001 From: Antoine Rondelet Date: Mon, 29 May 2023 09:59:14 +0100 Subject: [PATCH 13/42] First round of modifications on ZIP227 (#20) Improved style and content of ZIP 227. --------- Co-authored-by: Vivek Arte --- zip-0227.html | 173 +++++++++++++++++++++++++------------------------- zip-0227.rst | 88 ++++++++++++++----------- 2 files changed, 138 insertions(+), 123 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 4e1773218..eafb1de9f 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -26,21 +26,29 @@

    Terminology

    The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

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

    -

    The term "Orchard" in this document is to be interpreted as described in ZIP 224 3.

    -

    The terms "Asset", "custom Asset", and "Wrapped Asset" in this document are to be interpreted as described in ZIP 226 4.

    +

    The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 3.

    We define the following additional terms:

      +
    • Asset: A type of note that can be transferred on the Zcash blockchain. Each Asset is identified by an Asset Identifier Specification: Asset Identifier. +
        +
      • ZEC is the default (and currently the only defined) Asset for the Zcash mainnet.
        • +
      • TAZ is the default (and currently the only defined) Asset for the Zcash testnet.
        • +
      • We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ.
        • +
      +
      • +
    • Native Asset: a Custom Asset with issuance defined on the Zcash blockchain.
      • +
    • Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash blockchain.
    • Issuance Action: an instance of a single issuance of a Zcash Shielded Asset. It defines the issuance of a single Asset Identifier.
    • Issuance Bundle: the bundle in the transaction that contains all the issuance actions of that transaction.

    Abstract

    -

    ZIP 226 4 and ZIP 227 7 propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 7. The transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    +

    This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    Motivation

    -

    This ZIP is a supporting ZIP for ZIP 226 4, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function.

    -

    This ZIP enables only transparent issuance, since as a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.

    -

    The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash block chain), as well as for institutions to create bridges from other chains and import "wrapped" Assets. This enables what we hope will be a useful set of applications.

    +

    This ZIP introduces the issuance mechanism for custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 4) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 4.

    +

    This ZIP only enables transparent issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.

    +

    The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash blockchain), as well as for institutions to create bridges from other chains and import Wrapped Assets. This enables what we hope will be a useful set of applications.

    Use Cases

    The design presented in this ZIP enables issuance of shielded Assets in various modes:

    @@ -54,8 +62,8 @@

    Requirements

      -
    • Any user of the Zcash block chain can issue custom Assets on chain.
      • -
    • The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain.
      • +
    • Any user of the Zcash blockchain can issue custom Assets on chain.
      • +
    • The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash blockchain.
    • Issuing or changing the attributes of a specific Asset should require cryptographic authorization.
    • The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier.
    • An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets.
      • @@ -63,7 +71,7 @@

    Specification: Issuance Keys and Issuance Authorization Signature Scheme

    -

    The ZSA Protocol adds the following three keys to the key components 18:

    +

    The ZSA Protocol adds the following three keys to the key components 17:

    1. The issuance master key, denoted as \(\mathsf{sk}_{\mathsf{iss}}\) @@ -73,7 +81,7 @@ . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
    2. The issuance validating key, denoted as \(\mathsf{ik}\) - , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
      3. + , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.

    The relations between these keys are shown in the following diagram:

    @@ -85,7 +93,7 @@ \(\mathsf{IssueAuthSig}\) similar to \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) - , the Orchard spend authorization signature scheme 22. Specifically, we instantiate + , the Orchard spend authorization signature scheme 21. Specifically, we instantiate \(\mathsf{IssueAuthSig}\) as \(\mathsf{RedPallas}\) @@ -93,36 +101,40 @@ \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in the Zcash protocol specification 19.

    + is defined as in the Zcash protocol specification 18.

    Issuance Key Derivation

    The issuance master key is generated by choosing a bit sequence uniformly at random from \(\mathbb{B}^{\mathbb{Y}[32]}\) - , like the Orchard spending key 20.

    + , like the Orchard spending key 19.

    Issuance master key derivation for hierarchical deterministic wallets

    -

    The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 13. We reuse the functions defined there in what follows in this section.

    +

    The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

    Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\) .

    -

    As in ZIP 32 for Orchard 14, we only use hardened child key derivation for the issuance master key. We reuse the +

    As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the \(\mathsf{CDKsk}\) function for Orchard child key derivation from ZIP 32.

    -

    We use the notation of ZIP 32 16 for shielded HD paths, and define the issuance master key path as - \(m_\mathsf{Issuance} / purpose / coin\_type' / account'\) +

    We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as + \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\) . We fix the path levels as follows:

    • \(purpose\) : a constant set to + \(227\) + (i.e. + \(\texttt{0xe3}). :math:`purpose'\) + is thus \(227'\) (or \(\texttt{0x800000e3}\) ) following the BIP 43 recommendation.
    • \(coin\_type\) - : Defined as in ZIP 32 15.
      • + : Defined as in ZIP 32 14.
    • \(account\) : fixed to index @@ -136,7 +148,7 @@ .

    Derivation of issuance authorizing key and issuance validating key

    -

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 20, as described below.

    +

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 19, as described below.

    • The issuance authorizing key is derived from the issuance master key, \(\mathsf{sk}_{\mathsf{iss}}\) @@ -149,13 +161,15 @@ , as a public verification key:
    \(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
    -

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 12. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    +

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    Specification: Asset Identifier

    -

    For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair - \((\mathsf{ik}, \mathsf{asset\_desc})\) +

    For every new Asset, there must be a new and unique Asset Identifier, denoted + \(\mathsf{AssetId}\) + . We define this to be a globally unique pair + \(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})\) , where \(\mathsf{ik}\) is the issuance key and @@ -182,22 +196,27 @@ , where

    • - \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) + \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) .

    Define \(\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\) , where

    In the case of Orchard, we define - \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\) + \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 19.

    + is defined as in 18.

    The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

    Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol
    +

    Note: To keep notations light and concise, we may omit + \(\mathsf{AssetId}\) + (resp. + \(\mathsf{Protocol}\) + ) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.

    Specification: Global Issuance State

    Issuance requires the following additions to the global state defined at block boundaries:

    @@ -223,7 +242,7 @@
  • \(\mathsf{asset\_desc}\) : the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
    • -
  • notes: an array containing the unencrypted output notes of the recipients of the Asset, of type Note
    • +
  • notes: an array of Note containing the unencrypted output notes of the recipients of the Asset.
  • finalize: a boolean that defines whether the issuance of that specific custom Asset is finalized or not

    • An asset's @@ -240,7 +259,7 @@

    2124 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    - + @@ -248,24 +267,16 @@ - - + + - + - + - + @@ -280,13 +291,14 @@ - - + + - +
    SizeBytes Name Data Type Description
    2 bytes - \(\mathsf{assetDescSize}\) - 2assetDescSize byteThe length of the - \(\mathsf{asset\_desc}\) - string in bytesThe length of the asset_desc string in bytes
    Varies - \(\mathsf{asset\_desc}\) - asset_desc byteUTF-8 encoded string, of size - \(\mathsf{assetDescSize}\) - bytesUTF-8 encoded string, of size assetDescSize bytes
    VariesA sequence of note descriptions within the issuance action
    1 byteflagsIssuance1flagsIssuance byteAn 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0.An 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0. (See: T.5a.iii: flagsIssuance)
    +

    , where noteSize is the size, in bytes, of a Note.

    We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the NoteCommitmentTree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.

    Issuance Bundle

    @@ -302,7 +314,7 @@ \(\mathsf{isk}\) , that validates the issuance . -

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 24.

    +

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 23.

    @@ -320,16 +332,14 @@ - + - + @@ -341,6 +351,7 @@
    The number of issuance actions in the bundle
    VariesIssueActionSize * nIssueActions vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions
    32 - \(\mathsf{ik}\) - ik byte[32] The issuance validating key of the issuer, used to validate the signature
    +

    , where IssueActionSize is the size, in bytes, of an IssueAction description.

    Issuance Protocol

    The issuer program performs the following operations

    @@ -361,7 +372,7 @@ from \(\mathsf{AssetDigest}\) as decribed in the Specification: Asset Identifier section. -
  • set the finalize boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
    • +
  • set the finalize boolean as desired (if more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
  • For each recipient \(i\) : @@ -385,7 +396,7 @@ \(\mathsf{IssueAuthSig}\) signature scheme. The signature is then added to the issuance bundle.
    • -

    NOTE that the commitment is not included in the IssuanceAction itself. As explained below, it is later computed by the validators and added to the NoteCommitmentTree.

    +

    Note: that the commitment is not included in the IssuanceAction itself. As explained below, it is computed later by the validators and added to the NoteCommitmentTree.

    Specification: Consensus Rule Changes

    @@ -425,7 +436,7 @@
    • For each note, compute the note commitment as \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) - as defined in the Note Structure and Commitment section of ZIP 226 5 and
      • + as defined in the Note Structure and Commitment section of ZIP 226 5 and
    • add \(\mathsf{cm}\) to the Merkle tree of note commitments, NoteCommitmentTree.
      • @@ -456,7 +467,7 @@

      Concrete Applications

      Asset Features

        -
      • By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example, +
      • By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example,
        • by setting finalize = 1 from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed.
        @@ -480,7 +491,7 @@

    TxId Digest - Issuance

    -

    This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 8, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

    +

    This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

    A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

    issuance_digest
 ├── issue_actions_digest
@@ -514,10 +525,10 @@
                         
    The personalization field of this hash is set to:
    
                         
    "ZTxIdIANoteHash"
    
                         
    T.5a.i.1: recipient 
    
-                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 23.
    
+                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 22.
    
                         
    
                         
    T.5a.i.2: value 
    
-                            
    Note value encoded as little-endian 8-byte representation of u64 raw value.
    
+                            
    Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
    
                         
    
                         
    T.5a.i.3: assetBase 
    
                             
    Asset Base encoded as the 32-byte representation of a point on the Pallas curve.
    
@@ -546,7 +557,7 @@

    Signature Digest

    -

    The per-input transaction digest algorithm to generate the signature digest in ZIP 244 9 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.

    +

    The per-input transaction digest algorithm to generate the signature digest in ZIP 244 8 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.

    The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

    signature_digest
 ├── header_digest
@@ -561,14 +572,14 @@
 S.3: sapling_digest         (32-byte hash output)
 S.4: orchard_digest         (32-byte hash output)
 S.5: issuance_digest        (32-byte hash output)  [ADDED FOR ZSA]
    -

    The personalization field remains the same as in ZIP 244 8.

    +

    The personalization field remains the same as in ZIP 244 7.

    S.5: issuance_digest

    Identical to that specified for the transaction identifier.

    Authorizing Data Commitment

    -

    The transaction digest algorithm defined in ZIP 244 10 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

    +

    The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

    auth_digest
 ├── transparent_scripts_digest
 ├── sapling_auth_digest
@@ -604,7 +615,7 @@

    Bridging Assets

    -

    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

    +

    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

    Other Considerations

    @@ -616,7 +627,7 @@ in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

    Fee Structures

    -

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 11.

    +

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 10.

    Future Work

    In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying @@ -687,18 +698,10 @@ - - - - - - - -
    7ZIP 227: Issuance of Zcash Shielded Assets
    - + @@ -706,7 +709,7 @@
    87 ZIP 244: Transaction Identifier Non-Malleability
    - + @@ -714,7 +717,7 @@
    98 ZIP 244: Transaction Identifier Non-Malleability: Signature Digest
    - + @@ -722,7 +725,7 @@
    109 ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment
    - + @@ -730,7 +733,7 @@
    1110 ZIP 317b: ZSA Extension Proportional Fee Mechanism
    - + @@ -738,7 +741,7 @@
    1211 ZIP 32: Shielded Hierarchical Deterministic Wallets
    - + @@ -746,7 +749,7 @@
    1312 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation
    - + @@ -754,7 +757,7 @@
    1413 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation
    - + @@ -762,7 +765,7 @@
    1514 ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels
    - + @@ -770,7 +773,7 @@
    1615 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path
    - + @@ -778,7 +781,7 @@
    1716 ZIP 316: Unified Addresses and Unified Viewing Keys
    - + @@ -786,7 +789,7 @@
    1817 Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
    - + @@ -794,7 +797,7 @@
    1918 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
    - + @@ -802,7 +805,7 @@
    2019 Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
    - + @@ -810,7 +813,7 @@
    2120 Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -818,7 +821,7 @@
    2221 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -826,7 +829,7 @@
    2322 Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
    - + diff --git a/zip-0227.rst b/zip-0227.rst index de7e9a4f4..110af801d 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -24,29 +24,35 @@ The key word "MUST" in this document is to be interpreted as described in RFC 21 The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. -The term "Orchard" in this document is to be interpreted as described in ZIP 224 [#zip-0224]_. - -The terms "Asset", "custom Asset", and "Wrapped Asset" in this document are to be interpreted as described in ZIP 226 [#zip-0226]_. +The terms "Orchard" and "Action" in this document are to be interpreted as described in +ZIP 224 [#zip-0224]_. We define the following additional terms: +- Asset: A type of note that can be transferred on the Zcash blockchain. Each Asset is identified by an Asset Identifier `Specification: Asset Identifier`_. + + - ZEC is the default (and currently the only defined) Asset for the Zcash mainnet. + - TAZ is the default (and currently the only defined) Asset for the Zcash testnet. + - We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ. + +- Native Asset: a Custom Asset with issuance defined on the Zcash blockchain. +- Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash blockchain. - Issuance Action: an instance of a single issuance of a Zcash Shielded Asset. It defines the issuance of a single Asset Identifier. - Issuance Bundle: the bundle in the transaction that contains all the issuance actions of that transaction. Abstract ======== -ZIP 226 [#zip-0226]_ and ZIP 227 [#zip-0227]_ propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 [#zip-0227]_. The transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA. +This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA. Motivation ========== -This ZIP is a supporting ZIP for ZIP 226 [#zip-0226]_, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function. - -This ZIP enables only *transparent* issuance, since as a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked. +This ZIP introduces the issuance mechanism for custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 [#zip-0226]_) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 [#zip-0226]_. -The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash block chain), as well as for institutions to create bridges from other chains and import "wrapped" Assets. This enables what we hope will be a useful set of applications. +This ZIP only enables *transparent* issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked. +The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash blockchain), as well as for institutions to create bridges from other chains and import Wrapped Assets. This enables what we hope will be a useful set of applications. Use Cases ========= @@ -63,8 +69,8 @@ See the `Concrete Applications`_ section for more details. Requirements ============ -- Any user of the Zcash block chain can issue custom Assets on chain. -- The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain. +- Any user of the Zcash blockchain can issue custom Assets on chain. +- The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash blockchain. - Issuing or changing the attributes of a specific Asset should require cryptographic authorization. - The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier. - An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets. @@ -80,7 +86,7 @@ The ZSA Protocol adds the following three keys to the key components [#protocol- 2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. -3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. +3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. The relations between these keys are shown in the following diagram: @@ -114,9 +120,9 @@ We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \math As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key. We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32. -We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose / coin\_type' / account'`. We fix the path levels as follows: +We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows: -- :math:`purpose`: a constant set to :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. +- :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. - :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_. - :math:`account`: fixed to index :math:`0`. @@ -140,7 +146,7 @@ This allows the issuer to use the same wallet it usually uses to transfer Assets Specification: Asset Identifier =============================== -For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair :math:`(\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. +For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. @@ -153,12 +159,12 @@ Let Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`, where -- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`. +- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`. Define :math:`\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`, where -In the case of Orchard, we define :math:`\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})` +In the case of Orchard, we define :math:`\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})` where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in [#protocol-concretegrouphashpallasandvesta]_. The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram: @@ -171,6 +177,8 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol +**Note:** To keep notations light and concise, we may omit :math:`\mathsf{AssetId}` (resp. :math:`\mathsf{Protocol}`) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context. + Specification: Global Issuance State ==================================== @@ -189,20 +197,22 @@ An issuance action, `IssueAction`, is the instance of issuing a specific custom - :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. - :math:`\mathsf{asset\_desc}`: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. -- `notes`: an array containing the unencrypted output notes of the recipients of the Asset, of type `Note` +- `notes`: an array of `Note` containing the unencrypted output notes of the recipients of the Asset. - ``finalize``: a boolean that defines whether the issuance of that specific custom Asset is finalized or not An asset's :math:`\mathsf{AssetId}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with ``finalize = 1``. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetId} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetId} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain ``finalize = 0`` or change it to ``finalize = 1``, denoting that this custom Asset cannot be issued after the containing block. -================= =============================== ========================== =========================================================================================== -Size Name Data Type Description -================= =============================== ========================== =========================================================================================== -2 bytes :math:`\mathsf{assetDescSize}` byte The length of the :math:`\mathsf{asset\_desc}` string in bytes -Varies :math:`\mathsf{asset\_desc}` byte UTF-8 encoded string, of size :math:`\mathsf{assetDescSize}` bytes -Varies nNotes compactSize The number of notes in the issuance action -noteSize * nNotes vNotes Note[nNotes] A sequence of note descriptions within the issuance action -1 byte ``flagsIssuance`` byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0. -================= =============================== ========================== =========================================================================================== +==================== ===================== ======================= =========================================================================================== +Bytes Name Data Type Description +==================== ===================== ======================= =========================================================================================== +2 assetDescSize byte The length of the asset\_desc string in bytes +Varies asset\_desc byte UTF-8 encoded string, of size assetDescSize bytes +Varies nNotes compactSize The number of notes in the issuance action +noteSize * nNotes vNotes Note[nNotes] A sequence of note descriptions within the issuance action +1 flagsIssuance byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0. (See: `T.5a.iii: flagsIssuance`_) +==================== ===================== ======================= =========================================================================================== + +, where noteSize is the size, in bytes, of a Note. We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the `NoteCommitmentTree` as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers. @@ -217,14 +227,16 @@ An issuance bundle, `IssueBundle`, is the aggregate of all the issuance-related The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_. -======= ==================== ========================== ========================================================================================================================== -Bytes Name Data Type Description -======= ==================== ========================== ========================================================================================================================== -Varies nIssueActions compactSize The number of issuance actions in the bundle -Varies vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions -32 :math:`\mathsf{ik}` byte[32] The issuance validating key of the issuer, used to validate the signature -64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer, validated as in `Issuance Authorization Signature Scheme`_ -======= ==================== ========================== ========================================================================================================================== +================================= ===================== ========================== =============================================================================== +Bytes Name Data Type Description +================================= ===================== ========================== =============================================================================== +Varies nIssueActions compactSize The number of issuance actions in the bundle +IssueActionSize * nIssueActions vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions +32 ik byte[32] The issuance validating key of the issuer, used to validate the signature +64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer, validated as in `Issuance Authorization Signature Scheme`_ +================================= ===================== ========================== =============================================================================== + +, where IssueActionSize is the size, in bytes, of an IssueAction description. Issuance Protocol ----------------- @@ -235,7 +247,7 @@ For all actions `IssueAction`: - encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512. - compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section. - compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section. -- set the ``finalize`` boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``) +- set the ``finalize`` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``) - For each recipient :math:`i`: - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d},i}, \mathsf{v}_i, \rho_i, \psi_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`. @@ -249,7 +261,7 @@ For the `IssueBundle`: - sign the `SIGHASH` of the transaction with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle. -NOTE that the commitment is not included in the `IssuanceAction` itself. As explained below, it is later computed by the validators and added to the `NoteCommitmentTree`. +**Note:** that the commitment is not included in the `IssuanceAction` itself. As explained below, it is computed later by the validators and added to the `NoteCommitmentTree`. Specification: Consensus Rule Changes @@ -263,6 +275,7 @@ For each `IssueAction` in `IssueBundle`: - check that :math:`0 < \mathsf{assetDescSize} <= 512`. - check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathsf{assetDescSize}` bytes. + - retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Specification: Asset Identifier`_ section. - check that the :math:`\mathsf{AssetId}` does not exist in the ``previously_finalized`` set in the global state. - check that every note in the `IssueAction` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})`. @@ -378,7 +391,7 @@ This is the raw encoding of an Orchard shielded payment address as defined in th T.5a.i.2: value ............... -Note value encoded as little-endian 8-byte representation of u64 raw value. +Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value. T.5a.i.3: assetBase ................... @@ -536,7 +549,6 @@ References .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ .. [#zip-0226-txiddigest] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest `_ -.. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ .. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ .. [#zip-0244-sigdigest] `ZIP 244: Transaction Identifier Non-Malleability: Signature Digest `_ .. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment `_ From e129e68a8a699dd6ddc6e2890522f7fff2913b3d Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 1 Jun 2023 08:38:10 +0530 Subject: [PATCH 14/42] Adding ZSA Orchard Action Description encoding details (#21) This adds details of the changes to the Orchard Action encodings and the changes to the transaction format that occur due to the ZSA Protocol. It also improves the formatting of existing tables for Asset Burn. --- zip-0226.html | 176 ++++++++++++++++++++++++++++++++++++++++++-------- zip-0226.rst | 99 ++++++++++++++++++++++------ 2 files changed, 229 insertions(+), 46 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index fbbeece9d..deff0832f 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -64,7 +64,7 @@ from each Action Description, computed as \(\mathsf{value^{old}-value^{new}}\) , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

    -

    As was initially proposed by Jack Grigg and Daira Hopwood 28 29, we propose to make this happen by changing the value base point, +

    As was initially proposed by Jack Grigg and Daira Hopwood 29 30, we propose to make this happen by changing the value base point, \(\mathcal{V}^{\mathsf{Orchard}}\) , in the Homomorphic Pedersen Commitment that derives the value commitment, \(\mathsf{cv^{net}}\) @@ -401,7 +401,7 @@

    ZSA Transaction Structure

    -

    The transaction format is similar to the version 5 transaction format described in the Zcash specification 27, with the following additions to the Orchard bundle:

    +

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 27. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 27.

    2423 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    @@ -413,24 +413,138 @@ - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + +
    variesnAssetBurncompactSizeOrchard Transaction Fields
    variesnActionsOrchardcompactSize
    852 * nActionsOrchardvActionsOrchardZSAOrchardAction[nActionsOrchard]A sequence of ZSA Orchard Action descriptions, encoded per the ZSA Orchard Action Description Encoding. [UPDATED FOR ZSA]
    1flagsOrchardbyte
    8valueBalanceOrchardint64
    32anchorOrchardbyte[32]
    variessizeProofsOrchardcompactSize
    sizeProofsOrchardproofsOrchardbyte[sizeProofsOrchard]
    64 * nActionsOrchardvSpendAuthSigsOrchardbyte[64 * nActionsOrchard]
    64bindingSigOrchardbyte[64]
    ZSA Burn Fields
    variesnAssetBurncompactSize The number of Assets burnt.
    40*nAssetBurnvAssetBurnAssetBurn[nAssetBurn]40 * nAssetBurnvAssetBurnAssetBurn[nAssetBurn] A sequence of Asset Burn descriptions, encoded per ZSA Asset Burn Description.
    -

    In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the - \(\mathsf{AssetBase}\) - ). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action.

    +

    ZSA Orchard Action Description Encoding

    +

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 28. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData Type
    32cvbyte[32]
    32nullifierbyte[32]
    32rkbyte[32]
    32cmxbyte[32]
    32ephemeralKeybyte[32]
    612encCiphertextbyte[612][UPDATED FOR ZSA]
    80outCiphertextbyte[32]
    +

    ZSA Asset Burn Description

    -

    A ZSA Asset Burn description is encoded in a transaction as an of a AssetBurn type:

    +

    A ZSA Asset Burn description is encoded in a transaction as an instance of an AssetBurn type:

    @@ -443,26 +557,26 @@ - - + + - + - +
    32AssetBasebyte[32]AssetBasebyte[32] For the Orchard-based ZSA protocol, this is the encoding of the Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) .
    8valueBurnvalueBurn \(\{1 .. 2^{64} - 1\}\) The amount of the AssetType being burnt.The amount being burnt.

    TxId Digest

    -

    The transaction digest algorithm defined in ZIP 244 10 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 10 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

    A BLAKE2b-256 hash of the following values

    T.1: header_digest       (32-byte hash output)
@@ -470,7 +584,7 @@
 T.3: sapling_digest      (32-byte hash output)
 T.4: orchard_digest      (32-byte hash output)  [UPDATED FOR ZSA]
 T.5: issuance_digest     (32-byte hash output)  [ADDED FOR ZSA]
    -

    The personalization field remains the same as in ZIP 244 10.

    +

    The personalization field remains the same as in ZIP 244 10.

    T.4: orchard_digest

    When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values

    T.4a: orchard_actions_compact_digest      (32-byte hash output)          [UPDATED FOR ZSA]
@@ -480,7 +594,7 @@
 T.4e: valueBalanceOrchard                 (64-bit signed little-endian)
 T.4f: anchorOrchard                       (32 bytes)
    T.4a: orchard_actions_compact_digest
    -

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 11 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 11 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4a.i  : nullifier            (field encoding bytes)
 T.4a.ii : cmx                  (field encoding bytes)
 T.4a.iii: ephemeralKey         (field encoding bytes)
@@ -495,7 +609,7 @@
                         
    "ZTxIdOrcActMHash"
    T.4c: orchard_actions_noncompact_digest
    -

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 11 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 11 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4d.i  : cv                    (field encoding bytes)
 T.4d.ii : rk                    (field encoding bytes)
 T.4d.iii: encCiphertext[596..]  (post-memo suffix of field encoding)  [UPDATED FOR ZSA]
@@ -505,12 +619,12 @@

    T.5: issuance_digest

    -

    The details of the computation of this value are in ZIP 227 7.

    +

    The details of the computation of this value are in ZIP 227 7.

    Signature Digest and Authorizing Data Commitment

    -

    The details of the changes to these algorithms are in ZIP 227 8 9.

    +

    The details of the changes to these algorithms are in ZIP 227 8 9.

    Security and Privacy Considerations

      @@ -526,7 +640,7 @@

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 30.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 31.

    Backward Compatibility

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the @@ -763,14 +877,22 @@ 27 - Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) + Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) - +
    + + + +
    28Zcash Protocol Specification, Version 2022.3.8. Section 7.5: Action Description Encoding and Consensus
    + + + + @@ -778,7 +900,7 @@
    29 User-Defined Assets and Wrapped Assets
    - + @@ -786,7 +908,7 @@
    2930 Comment on Generalized Value Commitments
    - + diff --git a/zip-0226.rst b/zip-0226.rst index 57f08f626..409f7bf06 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -302,30 +302,90 @@ Burn Mechanism Consensus Rules ZSA Transaction Structure ========================= -The transaction format is similar to the version 5 transaction format described in the Zcash specification [#protocol-transactionstructure]_, with the following additions to the Orchard bundle: +The transaction format closely follows the version 5 transaction format described in the Zcash specification [#protocol-transactionstructure]_. +The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. +We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. +We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. +For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification [#protocol-transactionstructure]_. + + ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+===========================================+=====================================================================+ +| **Orchard Transaction Fields** | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``varies`` |``nActionsOrchard`` |``compactSize`` | | +| | | | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``852 * nActionsOrchard`` |``vActionsOrchard`` |``ZSAOrchardAction[nActionsOrchard]`` |A sequence of ZSA Orchard Action descriptions, encoded per | +| | | |the `ZSA Orchard Action Description Encoding`_. **[UPDATED FOR ZSA]**| ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``1`` |``flagsOrchard`` |``byte`` | | +| | | | | +| | | | | +| | | | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``8`` |``valueBalanceOrchard`` |``int64`` | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``32`` |``anchorOrchard`` |``byte[32]`` | | +| | | | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``varies`` |``sizeProofsOrchard`` |``compactSize`` | | +| | | | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``sizeProofsOrchard`` |``proofsOrchard`` |``byte[sizeProofsOrchard]`` | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``64 * nActionsOrchard`` |``vSpendAuthSigsOrchard`` |``byte[64 * nActionsOrchard]`` | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``64`` |``bindingSigOrchard`` |``byte[64]`` | | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +| **ZSA Burn Fields** | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +| ``varies`` | ``nAssetBurn`` | ``compactSize`` | The number of Assets burnt. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +| ``40 * nAssetBurn`` | ``vAssetBurn`` | ``AssetBurn[nAssetBurn]`` | A sequence of Asset Burn descriptions, | +| | | | encoded per `ZSA Asset Burn Description`_. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ + +ZSA Orchard Action Description Encoding +--------------------------------------- + +The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. +This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. +We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification [#protocol-actionencodingandconsensus]_. +A ZSA Orchard Action description is encoded in a transaction as an instance of an ``ZSAOrchardAction`` type: + ++-------+-------------------+---------------+----------------------+ +| Bytes | Name | Data Type | | ++=======+===================+===============+======================+ +| 32 | ``cv`` | ``byte[32]`` | | ++-------+-------------------+---------------+----------------------+ +| 32 | ``nullifier`` | ``byte[32]`` | | ++-------+-------------------+---------------+----------------------+ +| 32 | ``rk`` | ``byte[32]`` | | ++-------+-------------------+---------------+----------------------+ +| 32 | ``cmx`` | ``byte[32]`` | | ++-------+-------------------+---------------+----------------------+ +| 32 | ``ephemeralKey`` | ``byte[32]`` | | ++-------+-------------------+---------------+----------------------+ +| 612 | ``encCiphertext`` | ``byte[612]`` |**[UPDATED FOR ZSA]** | ++-------+-------------------+---------------+----------------------+ +| 80 | ``outCiphertext`` | ``byte[32]`` | | ++-------+-------------------+---------------+----------------------+ -+---------------+------------+-------------------------+-----------------------------------------------------------------------------------+ -| Bytes | Name | Data Type | Description | -+===============+============+=========================+===================================================================================+ -| varies | nAssetBurn | compactSize | The number of Assets burnt. | -+---------------+------------+-------------------------+-----------------------------------------------------------------------------------+ -| 40*nAssetBurn | vAssetBurn | AssetBurn[nAssetBurn] | A sequence of Asset Burn descriptions, encoded per `ZSA Asset Burn Description`_. | -+---------------+------------+-------------------------+-----------------------------------------------------------------------------------+ - -In terms of the Action size, the ZSA action size differs from the Orchard action size by 32 bytes (due to the addition of the :math:`\mathsf{AssetBase}`). This implies that the size goes from 820 bytes in the Orchard action to 852 bytes in the ZSA Action. ZSA Asset Burn Description -------------------------- -A ZSA Asset Burn description is encoded in a transaction as an of a AssetBurn type: +A ZSA Asset Burn description is encoded in a transaction as an instance of an ``AssetBurn`` type: -+-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| Bytes | Name | Data Type | Description | -+=======+===========+=============================+===========================================================================================================================+ -| 32 | AssetBase | byte[32] | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. | -+-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| 8 | valueBurn | :math:`\{1 .. 2^{64} - 1\}` | The amount of the AssetType being burnt. | -+-------+-----------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ ++-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=======+===============+=============================+===========================================================================================================================+ +| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. | ++-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +| 8 | ``valueBurn`` | :math:`\{1 .. 2^{64} - 1\}` | The amount being burnt. | ++-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ TxId Digest =========== @@ -488,7 +548,8 @@ References .. [#protocol-concretevaluecommit] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard) `_ .. [#protocol-dummynotes] `Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard) `_ .. [#protocol-actionstatement] `Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard) `_ -.. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) `_ +.. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) `_ +.. [#protocol-actionencodingandconsensus] `Zcash Protocol Specification, Version 2022.3.8. Section 7.5: Action Description Encoding and Consensus `_ .. [#initial-zsa-issue] `User-Defined Assets and Wrapped Assets `_ .. [#generalized-value-commitments] `Comment on Generalized Value Commitments `_ .. [#zip-0317b] `ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs `_ \ No newline at end of file From c5eb10f83f4d697d3ef10b6201137fb000c0f8e5 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Sat, 3 Jun 2023 23:29:38 +0530 Subject: [PATCH 15/42] Updates to issue bundle hash personalizations (#22) A few of the issue bundle hash personalizations were 15 characters long instead of the required 16. This is being fixed here. --- zip-0227.html | 4 ++-- zip-0227.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index eafb1de9f..d2869adb0 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -514,7 +514,7 @@ T.5a.ii : assetDescription (field encoding bytes) T.5a.iii: flagsIssuance (1 byte)

    The personalization field of this hash is set to:

    - 
    "ZTxIdIssActHash"
    + 
    "ZTxIdIssActHash_" (1 underscore character)
    T.5a.i: issue_notes_digest

    A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:

    T.5a.i.1: recipient                    (field encoding bytes)
@@ -523,7 +523,7 @@
 T.5a.i.4: rho                          (field encoding bytes)
 T.5a.i.5: rseed                        (field encoding bytes)

    The personalization field of this hash is set to:

    - 
    "ZTxIdIANoteHash"
    + 
    "ZTxIdIANoteHash_" (1 underscore character)
    T.5a.i.1: recipient

    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 22.

    diff --git a/zip-0227.rst b/zip-0227.rst index 110af801d..e112372ab 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -369,7 +369,7 @@ A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belongin The personalization field of this hash is set to:: - "ZTxIdIssActHash" + "ZTxIdIssActHash_" (1 underscore character) T.5a.i: issue_notes_digest '''''''''''''''''''''''''' @@ -383,7 +383,7 @@ A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance A The personalization field of this hash is set to:: - "ZTxIdIANoteHash" + "ZTxIdIANoteHash_" (1 underscore character) T.5a.i.1: recipient ................... From 7913ed5701602984861910809e0736e72bd5fb52 Mon Sep 17 00:00:00 2001 From: Antoine Rondelet Date: Mon, 5 Jun 2023 13:38:43 +0100 Subject: [PATCH 16/42] Fixed math boundary around purpose (#23) As per the title, this is a tiny fix to adjust the boundary of the math environment which wasn't properly closed and thus rendered poorly on the html. --- zip-0227.html | 4 +++- zip-0227.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index d2869adb0..662f46a8b 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -126,7 +126,9 @@ : a constant set to \(227\) (i.e. - \(\texttt{0xe3}). :math:`purpose'\) + \(\texttt{0xe3}\) + ). + \(purpose'\) is thus \(227'\) (or diff --git a/zip-0227.rst b/zip-0227.rst index e112372ab..05b76c9d6 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -122,7 +122,7 @@ We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation fr We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows: -- :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. +- :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}`). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. - :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_. - :math:`account`: fixed to index :math:`0`. From 30a6f5b25489f41b036e2fd5dd6068922552811a Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Fri, 9 Jun 2023 22:30:01 +0530 Subject: [PATCH 17/42] Updates to naming conventions and table format (#28) This makes the naming conventions for variables more consistent, largely with a view to using double backticks for terms that appear in the transaction format and datatype description tables. These tables have also been reformatted to be consistent with other ZIPs in their rst form. The `previously_finalized` set is renamed to `finalized_assets`, and this set now stores `AssetDigest` values rather than `AssetId` values for more compactness in the global state. --- zip-0226.html | 4 +- zip-0226.rst | 4 +- zip-0227.html | 242 ++++++++++++++++++++++---------------------------- zip-0227.rst | 158 +++++++++++++++++--------------- 4 files changed, 195 insertions(+), 213 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index deff0832f..1d41f3a79 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -90,9 +90,7 @@

    Specification

    Most of the protocol is kept the same as the Orchard protocol released with NU5, except for the following.

    Asset Identifiers

    -

    For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an Asset description, - \(\mathsf{asset\_desc}\) - , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, +

    For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an Asset description, assetDesc, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, \(\mathsf{AssetId}\) , the Asset Digest, and the Asset Base ( \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) diff --git a/zip-0226.rst b/zip-0226.rst index 409f7bf06..0092bd1f8 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -84,7 +84,7 @@ Most of the protocol is kept the same as the Orchard protocol released with NU5, Asset Identifiers ----------------- -For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. +For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, ``assetDesc``, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. @@ -322,8 +322,6 @@ For brevity, we omit the descriptions from the table below unless they differ fr +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``1`` |``flagsOrchard`` |``byte`` | | | | | | | -| | | | | -| | | | | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``8`` |``valueBalanceOrchard`` |``int64`` | | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ diff --git a/zip-0227.html b/zip-0227.html index 662f46a8b..8a400bb8c 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -76,12 +76,8 @@

  • The issuance master key, denoted as \(\mathsf{sk}_{\mathsf{iss}}\) , as the name suggests, is the master key that is used to derive the other two keys.
    • -
  • The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as - \(\mathsf{isk}\) - . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
    • -
  • The issuance validating key, denoted as - \(\mathsf{ik}\) - , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
    • +
  • The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as isk. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
    • +
  • The issuance validating key, denoted as ik, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.

    • The relations between these keys are shown in the following diagram:

    @@ -156,13 +152,13 @@ \(\mathsf{sk}_{\mathsf{iss}}\) , as a private signature key: -
    \(\mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} )\)
    +
    \(\mathtt{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} )\)
    • The issuance validating key is derived from the issuance authorizing key, - \(\mathsf{isk}\) + \(\mathtt{isk}\) , as a public verification key:
    -
    \(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
    +
    \(\mathtt{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathtt{isk})\)

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    @@ -171,12 +167,8 @@

    For every new Asset, there must be a new and unique Asset Identifier, denoted \(\mathsf{AssetId}\) . We define this to be a globally unique pair - \(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})\) - , where - \(\mathsf{ik}\) - is the issuance key and - \(\mathsf{asset\_desc}\) - is a byte string.

    + \(\mathsf{AssetId} := (\mathtt{ik}, \mathtt{assetDesc})\) + , where ik is the issuance key and assetDesc is a byte string.

    A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, \(\mathsf{AssetDigest}\) , which is simply is a @@ -186,19 +178,15 @@ for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

    Let

      -
    • - \(\mathsf{asset\_desc}\) - be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
      • -
    • - \(\mathsf{ik}\) - be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
      • +
    • assetDesc be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
      • +
    • ik be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.

    Define \(\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\) , where

    • - \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) + \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathtt{ik}, \mathtt{assetDesc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathtt{ik}) || \mathtt{assetDesc}\!\) .

    Define @@ -223,41 +211,31 @@

    Specification: Global Issuance State

    Issuance requires the following additions to the global state defined at block boundaries:

      -
    • - \(\mathsf{previously\_finalized}\) - , a set of - \(\mathsf{AssetId}\) +
    • finalized_assets, a set of + \(\mathsf{AssetDigest}\) that have been finalized (i.e.: the finalize flag has been set to 1 in some issuance transaction preceding the block boundary).

    Specification: Issuance Action, Issuance Bundle and Issuance Protocol

    Issuance Action Description

    -

    An issuance action, IssueAction, is the instance of issuing a specific custom Asset, and contains the following fields:

    +

    An issuance action, IssueAction, is the instance of issuing a specific custom Asset, and contains the following fields:

      -
    • - \(\mathsf{assetDescSize}\) - : the size of the Asset description, a number between +
    • assetDescSize: the size of the Asset description, a number between \(0\) and \(512\) , stored in two bytes.
      • -
    • - \(\mathsf{asset\_desc}\) - : the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
      • -
    • notes: an array of Note containing the unencrypted output notes of the recipients of the Asset.
      • -
    • finalize: a boolean that defines whether the issuance of that specific custom Asset is finalized or not
      • +
    • assetDesc: the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
      • +
    • vNotes: an array of Note containing the unencrypted output notes of the recipients of the Asset.
      • +
    • flagsIssuance: a byte that stores the finalize boolean that defines whether the issuance of that specific Custom Asset is finalized or not

    An asset's - \(\mathsf{AssetId}\) - is added to the - \(\mathsf{previously\_finalized}\) - set after a block that contains any issuance transaction for that asset with finalize = 1. It then cannot be removed from this set. For Assets with - \(\mathsf{AssetId} \in \mathsf{previously\_finalized}\) + \(\mathsf{AssetDigest}\) + is added to the finalized_assets set after a block that contains any issuance transaction for that asset with finalize = 1. It then cannot be removed from this set. For Assets with + \(\mathsf{AssetDigest} \in \mathtt{finalized\_assets}\) , no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with - \(\mathsf{AssetId} \not\in \mathsf{previously\_finalized}\) - , new issuance actions can be issued in future transactions. These must use the same Asset description, - \(\mathsf{asset\_desc}\) - , and can either maintain finalize = 0 or change it to finalize = 1, denoting that this custom Asset cannot be issued after the containing block.

    + \(\mathsf{AssetDigest} \not\in \mathtt{finalized\_assets}\) + , new issuance actions can be issued in future transactions. These must use the same Asset description, assetDesc, and can either maintain finalize = 0 or change it to finalize = 1, denoting that this Custom Asset cannot be issued after the containing block.

    3031 ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
    @@ -269,51 +247,58 @@ - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + +
    2assetDescSizebyteThe length of the asset_desc string in bytes2assetDescSizebyteThe length of the assetDesc string in bytes.
    Variesasset_descbyteUTF-8 encoded string, of size assetDescSize bytesassetDescSizeassetDescbyte[assetDescSize]A byte sequence of length assetDescSize bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
    VariesnNotescompactSizeThe number of notes in the issuance actionvariesnNotescompactSizeThe number of notes in the issuance action.
    noteSize * nNotesvNotesNote[nNotes]A sequence of note descriptions within the issuance actionnoteSize * nNotesvNotesNote[nNotes]A sequence of note descriptions within the issuance action, where noteSize is the size, in bytes, of a Note.
    1flagsIssuancebyteAn 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0. (See: T.5a.iii: flagsIssuance)1flagsIssuancebyte +
    +
    An 8-bit value representing a set of flags. Ordered from LSB to MSB:
    +
    +
      +
    • finalize
      • +
    • The remaining bits are set to 0.
      • +
    +
    +
    +
    -

    , where noteSize is the size, in bytes, of a Note.

    -

    We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the NoteCommitmentTree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.

    +

    We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.

    Issuance Bundle

    -

    An issuance bundle, IssueBundle, is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields:

    +

    An issuance bundle, IssueBundle, is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields:

      -
    • - \(\mathsf{ik}\) - : the issuance validating key, that allows the validators to verify that the +
    • ik: the issuance validating key, that allows the validators to verify that the \(\mathsf{AssetId}\) is properly associated with the issuer.
      • -
    • actions: an array of issuance actions, of type IssueAction.
      • -
    • issueAuthSig: the signature of the transaction SIGHASH, signed by the issuance authorizing key, - \(\mathsf{isk}\) +
    • vIssueActions: an array of issuance actions, of type IssueAction.
      • +
    • issueAuthSig: the signature of the transaction SIGHASH, signed by the issuance authorizing key, + \(\mathtt{isk}\) , that validates the issuance .

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 23.

    @@ -328,110 +313,99 @@ - Varies - nIssueActions - compactSize - The number of issuance actions in the bundle + varies + nIssueActions + compactSize + The number of issuance actions in the bundle. - IssueActionSize * nIssueActions - vIssueActions - IssueAction[nIssueActions] - A sequence of issuance actions descriptions + IssueActionSize * nIssueActions + vIssueActions + IssueAction[nIssueActions] + A sequence of issuance action descriptions, where IssueActionSize is the size, in bytes, of an IssueAction description. - 32 - ik - byte[32] - The issuance validating key of the issuer, used to validate the signature + 32 + ik + byte[32] + The issuance validating key of the issuer, used to validate the signature. - 64 - issueAuthSig - byte[64] - The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme + 64 + issueAuthSig + byte[64] + The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme. -

    , where IssueActionSize is the size, in bytes, of an IssueAction description.

    Issuance Protocol

    The issuer program performs the following operations

    -

    For all actions IssueAction:

    +

    For all actions IssueAction:

      -
    • encode - \(\mathsf{asset\_desc}\) - as a UTF-8 byte string of size up to 512.
      • +
    • encode assetDesc as a UTF-8 byte string of size up to 512.
    • compute \(\mathsf{AssetDigest}\) - from the issuance validating key - \(\mathsf{ik}\) - and - \(\mathsf{asset\_desc}\) - as decribed in the Specification: Asset Identifier section.
      • + from the issuance validating key ik and assetDesc as decribed in the Specification: Asset Identifier section.
    • compute \(\mathsf{AssetBase^{Protocol}}\) from \(\mathsf{AssetDigest}\) as decribed in the Specification: Asset Identifier section.
      • -
    • set the finalize boolean as desired (if more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
      • +
    • set the finalize boolean as desired (if more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1).
    • For each recipient \(i\) :
      • generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is - \(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d},i}, \mathsf{v}_i, \rho_i, \psi_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!\) + \(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!\) .
      • -
    • encode the IssueAction into the vector vIssueActions of the bundle
      • +
    • encode the IssueAction into the vector vIssueActions of the bundle.
    -

    For the IssueBundle:

    +

    For the IssueBundle:

      -
    • encode the vIssueActions vector
      • -
    • encode the - \(\mathsf{ik}\) - as 32 byte-string
      • -
    • sign the SIGHASH of the transaction with the issuance authorizing key, - \(\mathsf{isk}\) +
    • encode the vIssueActions vector.
      • +
    • encode the ik as 32 byte-string.
      • +
    • sign the SIGHASH of the transaction with the issuance authorizing key, + \(\mathtt{isk}\) , using the \(\mathsf{IssueAuthSig}\) signature scheme. The signature is then added to the issuance bundle.
    -

    Note: that the commitment is not included in the IssuanceAction itself. As explained below, it is computed later by the validators and added to the NoteCommitmentTree.

    +

    Note: that the commitment is not included in the IssuanceAction itself. As explained below, it is computed later by the validators and added to the note commitment tree.

    Specification: Consensus Rule Changes

    -

    For the IssueBundle:

    +

    For the IssueBundle:

      -
    • Verify the RedPallas-based issuance authorization signature on SIGHASH, issueAuthSig, is verified by invoking issueAuthSig.VerifySig(ik, SIGHASH)
      • +
    • Verify the RedPallas-based issuance authorization signature on SIGHASH, issueAuthSig, is verified by invoking + \(\mathsf{issueAuthSig.VerifySig}(\mathtt{ik}, \mathtt{SIGHASH})\) + .
    -

    For each IssueAction in IssueBundle:

    +

    For each IssueAction in IssueBundle:

    • check that - \(0 < \mathsf{assetDescSize} <= 512\) + \(0 < \mathtt{assetDescSize} <= 512\) .
    • check that - \(\mathsf{asset\_desc}\) + \(\mathtt{assetDesc}\) is a string of length - \(\mathsf{assetDescSize}\) + \(\mathtt{assetDescSize}\) bytes.
    • retrieve \(\mathsf{AssetBase}\) from the first note in the sequence and check that \(\mathsf{AssetBase}\) - is derived from the issuance validating key - \(\mathsf{ik}\) - and - \(\mathsf{asset\_desc}\) - as described in the Specification: Asset Identifier section.
      • + is derived from the issuance validating key ik and assetDesc as described in the Specification: Asset Identifier section.
    • check that the - \(\mathsf{AssetId}\) - does not exist in the previously_finalized set in the global state.
      • -
    • check that every note in the IssueAction contains the same + \(\mathsf{AssetDigest}\) + does not exist in the finalized_assets set in the global state.
      • +
    • check that every note in the IssueAction contains the same \(\mathsf{AssetBase}\) and is properly constructed as - \(note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})\) + \(\mathsf{note} = (\mathsf{g_d, pk_d, v, \rho, rseed, AssetBase})\) .

    If all of the above checks pass, do the following:

    @@ -439,12 +413,12 @@
  • For each note, compute the note commitment as \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) as defined in the Note Structure and Commitment section of ZIP 226 5 and
    • -
  • add +
  • Add \(\mathsf{cm}\) - to the Merkle tree of note commitments, NoteCommitmentTree.
    • + to the Merkle tree of note commitments.
  • If finalize = 1, add - \(\mathsf{AssetId}\) - to the previously_finalized set immediately after the block in which this transaction occurs.
    • + \(\mathsf{AssetDigest}\) + to the finalized_assets set immediately after the block in which this transaction occurs.
  • (Replay Protection) If issue bundle is present, the fees MUST be greater than zero.
    • @@ -453,9 +427,7 @@
    • The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools.
    • The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”.
      • -
    • The - \(\mathsf{asset\_desc}\) - is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: +
    • The assetDesc is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are:
      • links for storage such as for NFTs.
      • metadata for Assets, encoded in any format.
        • @@ -463,7 +435,7 @@
      • information to be committed by the issuer, though not enforceable by the protocol.
      • -
    • We require a check whether the finalize flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the previously_finalized set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
      • +
    • We require a check whether the finalize flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the finalized_assets set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
    • We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH, potentially allowing for a replay attack.

    Concrete Applications

    @@ -632,9 +604,7 @@

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 10.

    Future Work

    -

    In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying - \(\mathsf{ik}\) - of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether.

    +

    In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying ik of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether.

    Test Vectors

    diff --git a/zip-0227.rst b/zip-0227.rst index 05b76c9d6..8ad96c814 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -84,9 +84,9 @@ The ZSA Protocol adds the following three keys to the key components [#protocol- 1. The issuance master key, denoted as :math:`\mathsf{sk}_{\mathsf{iss}}`, as the name suggests, is the master key that is used to derive the other two keys. -2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. +2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as ``isk``. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. -3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. +3. The issuance validating key, denoted as ``ik``, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. The relations between these keys are shown in the following diagram: @@ -135,31 +135,31 @@ The issuance authorizing key and issuance validating key are derived from the is - The issuance authorizing key is derived from the issuance master key, :math:`\mathsf{sk}_{\mathsf{iss}}`, as a private signature key: -.. math:: \mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} ) +.. math:: \mathtt{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} ) -- The issuance validating key is derived from the issuance authorizing key, :math:`\mathsf{isk}`, as a public verification key: +- The issuance validating key is derived from the issuance authorizing key, :math:`\mathtt{isk}`, as a public verification key: -.. math:: \mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk}) +.. math:: \mathtt{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathtt{isk}) This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe. Specification: Asset Identifier =============================== -For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. +For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathtt{ik}, \mathtt{assetDesc})`, where ``ik`` is the issuance key and ``assetDesc`` is a byte string. A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. Let -- :math:`\mathsf{asset\_desc}` be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. -- :math:`\mathsf{ik}` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. +- ``assetDesc`` be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. +- ``ik`` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`, where -- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`. +- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathtt{ik}, \mathtt{assetDesc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathtt{ik}) || \mathtt{assetDesc}\!`. Define :math:`\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`, where @@ -184,107 +184,123 @@ Specification: Global Issuance State Issuance requires the following additions to the global state defined at block boundaries: -- :math:`\mathsf{previously\_finalized}`, a set of :math:`\mathsf{AssetId}` that have been finalized (i.e.: the ``finalize`` flag has been set to ``1`` in some issuance transaction preceding the block boundary). +- ``finalized_assets``, a set of :math:`\mathsf{AssetDigest}` that have been finalized (i.e.: the ``finalize`` flag has been set to ``1`` in some issuance transaction preceding the block boundary). Specification: Issuance Action, Issuance Bundle and Issuance Protocol -================================================================================= +===================================================================== Issuance Action Description --------------------------- -An issuance action, `IssueAction`, is the instance of issuing a specific custom Asset, and contains the following fields: - -- :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. -- :math:`\mathsf{asset\_desc}`: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. -- `notes`: an array of `Note` containing the unencrypted output notes of the recipients of the Asset. -- ``finalize``: a boolean that defines whether the issuance of that specific custom Asset is finalized or not - -An asset's :math:`\mathsf{AssetId}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with ``finalize = 1``. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetId} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetId} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain ``finalize = 0`` or change it to ``finalize = 1``, denoting that this custom Asset cannot be issued after the containing block. - -==================== ===================== ======================= =========================================================================================== -Bytes Name Data Type Description -==================== ===================== ======================= =========================================================================================== -2 assetDescSize byte The length of the asset\_desc string in bytes -Varies asset\_desc byte UTF-8 encoded string, of size assetDescSize bytes -Varies nNotes compactSize The number of notes in the issuance action -noteSize * nNotes vNotes Note[nNotes] A sequence of note descriptions within the issuance action -1 flagsIssuance byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0. (See: `T.5a.iii: flagsIssuance`_) -==================== ===================== ======================= =========================================================================================== - -, where noteSize is the size, in bytes, of a Note. - -We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the `NoteCommitmentTree` as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers. +An issuance action, ``IssueAction``, is the instance of issuing a specific custom Asset, and contains the following fields: + +- ``assetDescSize``: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. +- ``assetDesc``: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. +- ``vNotes``: an array of ``Note`` containing the unencrypted output notes of the recipients of the Asset. +- ``flagsIssuance``: a byte that stores the ``finalize`` boolean that defines whether the issuance of that specific Custom Asset is finalized or not + +An asset's :math:`\mathsf{AssetDigest}` is added to the ``finalized_assets`` set after a block that contains any issuance transaction for that asset with ``finalize = 1``. It then cannot be removed from this set. +For Assets with :math:`\mathsf{AssetDigest} \in \mathtt{finalized\_assets}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. +For Assets with :math:`\mathsf{AssetDigest} \not\in \mathtt{finalized\_assets}`, new issuance actions can be issued in future transactions. +These must use the same Asset description, ``assetDesc``, and can either maintain ``finalize = 0`` or change it to ``finalize = 1``, denoting that this Custom Asset cannot be issued after the containing block. + ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+===========================================+=====================================================================+ +|``2`` |``assetDescSize`` |``byte`` |The length of the ``assetDesc`` string in bytes. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``assetDescSize`` |``assetDesc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | +| | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | +| | | |or later. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``varies`` |``nNotes`` |``compactSize`` |The number of notes in the issuance action. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``noteSize * nNotes`` |``vNotes`` |``Note[nNotes]`` |A sequence of note descriptions within the issuance action, | +| | | |where ``noteSize`` is the size, in bytes, of a Note. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``1`` |``flagsIssuance`` |``byte`` |An 8-bit value representing a set of flags. Ordered from LSB to MSB: | +| | | | * ``finalize`` | +| | | | * The remaining bits are set to ``0``. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ + +We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note. +This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers. Issuance Bundle --------------- -An issuance bundle, `IssueBundle`, is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields: +An issuance bundle, ``IssueBundle``, is the aggregate of all the issuance-related information. +Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. +It contains the following fields: -- :math:`\mathsf{ik}`: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer. -- `actions`: an array of issuance actions, of type `IssueAction`. -- `issueAuthSig`: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathsf{isk}`, that validates the issuance . +- ``ik``: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer. +- ``vIssueActions``: an array of issuance actions, of type `IssueAction`. +- ``issueAuthSig``: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathtt{isk}`, that validates the issuance . The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_. -================================= ===================== ========================== =============================================================================== -Bytes Name Data Type Description -================================= ===================== ========================== =============================================================================== -Varies nIssueActions compactSize The number of issuance actions in the bundle -IssueActionSize * nIssueActions vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions -32 ik byte[32] The issuance validating key of the issuer, used to validate the signature -64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer, validated as in `Issuance Authorization Signature Scheme`_ -================================= ===================== ========================== =============================================================================== - -, where IssueActionSize is the size, in bytes, of an IssueAction description. ++------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++====================================+==========================+===========================================+===========================================================================+ +|``varies`` |``nIssueActions`` |``compactSize`` |The number of issuance actions in the bundle. | ++------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ +|``IssueActionSize * nIssueActions`` |``vIssueActions`` |``IssueAction[nIssueActions]`` |A sequence of issuance action descriptions, where IssueActionSize is | +| | | |the size, in bytes, of an IssueAction description. | ++------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ +|``32`` |``ik`` |``byte[32]`` |The issuance validating key of the issuer, used to validate the signature. | ++------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ +|``64`` |``issueAuthSig`` |``byte[64]`` |The signature of the transaction SIGHASH, signed by the issuer, | +| | | |validated as in `Issuance Authorization Signature Scheme`_. | ++------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ Issuance Protocol ----------------- The issuer program performs the following operations -For all actions `IssueAction`: +For all actions ``IssueAction``: -- encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512. -- compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section. +- encode ``assetDesc`` as a UTF-8 byte string of size up to 512. +- compute :math:`\mathsf{AssetDigest}` from the issuance validating key ``ik`` and ``assetDesc`` as decribed in the `Specification: Asset Identifier`_ section. - compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section. -- set the ``finalize`` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``) +- set the ``finalize`` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``). - For each recipient :math:`i`: - - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d},i}, \mathsf{v}_i, \rho_i, \psi_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`. + - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`. -- encode the `IssueAction` into the vector `vIssueActions` of the bundle +- encode the ``IssueAction`` into the vector ``vIssueActions`` of the bundle. -For the `IssueBundle`: +For the ``IssueBundle``: -- encode the `vIssueActions` vector -- encode the :math:`\mathsf{ik}` as 32 byte-string -- sign the `SIGHASH` of the transaction with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle. +- encode the ``vIssueActions`` vector. +- encode the ``ik`` as 32 byte-string. +- sign the ``SIGHASH`` of the transaction with the issuance authorizing key, :math:`\mathtt{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle. -**Note:** that the commitment is not included in the `IssuanceAction` itself. As explained below, it is computed later by the validators and added to the `NoteCommitmentTree`. +**Note:** that the commitment is not included in the ``IssuanceAction`` itself. As explained below, it is computed later by the validators and added to the note commitment tree. Specification: Consensus Rule Changes ===================================== -For the IssueBundle: +For the ``IssueBundle``: -- Verify the RedPallas-based issuance authorization signature on `SIGHASH`, `issueAuthSig`, is verified by invoking `issueAuthSig.VerifySig(ik, SIGHASH)` +- Verify the RedPallas-based issuance authorization signature on ``SIGHASH``, ``issueAuthSig``, is verified by invoking :math:`\mathsf{issueAuthSig.VerifySig}(\mathtt{ik}, \mathtt{SIGHASH})`. -For each `IssueAction` in `IssueBundle`: +For each ``IssueAction`` in ``IssueBundle``: -- check that :math:`0 < \mathsf{assetDescSize} <= 512`. -- check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathsf{assetDescSize}` bytes. +- check that :math:`0 < \mathtt{assetDescSize} <= 512`. +- check that :math:`\mathtt{assetDesc}` is a string of length :math:`\mathtt{assetDescSize}` bytes. -- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Specification: Asset Identifier`_ section. -- check that the :math:`\mathsf{AssetId}` does not exist in the ``previously_finalized`` set in the global state. -- check that every note in the `IssueAction` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})`. +- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key ``ik`` and ``assetDesc`` as described in the `Specification: Asset Identifier`_ section. +- check that the :math:`\mathsf{AssetDigest}` does not exist in the ``finalized_assets`` set in the global state. +- check that every note in the ``IssueAction`` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`\mathsf{note} = (\mathsf{g_d, pk_d, v, \rho, rseed, AssetBase})`. If all of the above checks pass, do the following: - For each note, compute the note commitment as :math:`\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}` as defined in the Note Structure and Commitment section of ZIP 226 [#zip-0226-notestructure]_ and -- add :math:`\mathsf{cm}` to the Merkle tree of note commitments, `NoteCommitmentTree`. -- If ``finalize = 1``, add :math:`\mathsf{AssetId}` to the ``previously_finalized`` set immediately after the block in which this transaction occurs. +- Add :math:`\mathsf{cm}` to the Merkle tree of note commitments. +- If ``finalize = 1``, add :math:`\mathsf{AssetDigest}` to the ``finalized_assets`` set immediately after the block in which this transaction occurs. - (Replay Protection) If issue bundle is present, the fees MUST be greater than zero. @@ -295,14 +311,14 @@ The following is a list of rationale for different decisions made in the proposa - The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools. - The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”. -- The :math:`\mathsf{asset\_desc}` is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: +- The ``assetDesc`` is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: - links for storage such as for NFTs. - metadata for Assets, encoded in any format. - bridging information for Wrapped Assets (chain of origin, issuer name, etc) - information to be committed by the issuer, though not enforceable by the protocol. -- We require a check whether the ``finalize`` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the ``previously_finalized`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. +- We require a check whether the ``finalize`` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the ``finalized_assets`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. - We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the ``SIGHASH`` would be computed solely based on the issue bundle. A duplicate bundle would have the same ``SIGHASH``, potentially allowing for a replay attack. Concrete Applications @@ -522,7 +538,7 @@ The fee mechanism described in this ZIP will follow the mechanism described in Z Future Work ----------- -In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying :math:`\mathsf{ik}` of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether. +In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying ``ik`` of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether. Test Vectors ============ From 7cbfde6d4165e0fab6b846159f4121d7371f3e27 Mon Sep 17 00:00:00 2001 From: Antoine Rondelet Date: Sun, 11 Jun 2023 14:04:56 +0100 Subject: [PATCH 18/42] Removed redundant terminology in ZIP226, building on ZIP227 (#26) Removed redundant terminology in ZIP226, building on ZIP227, fixed abstract and used consistent terminology to stick to issuance instead of creation of assets. --------- Co-authored-by: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> --- zip-0226.html | 155 +++++++++++++++++++++++++------------------------- zip-0226.rst | 31 +++------- 2 files changed, 85 insertions(+), 101 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 1d41f3a79..3db141036 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -27,62 +27,51 @@

    The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.

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

    The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 4.

    +

    The terms "Asset", "Custom Asset" and "Wrapped Asset" in this document are to be interpreted as described in ZIP 227 6.

    We define the following additional terms:

      -
    • Asset: A type of note that can be transferred on the Zcash block chain, identified by the - \(\mathsf{AssetId}\) - parameter. -
        -
      • ZEC is the default (and currently the only defined) Asset for the Zcash mainnet.
        • -
      • TAZ is the default (and currently the only defined) Asset for the Zcash testnet.
        • -
      • We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ.
        • -
      -
      • -
    • Native Asset: a Custom Asset with issuance defined on the Zcash block chain.
      • -
    • Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash block chain.
    • Split Input: an Action input used to ensure that the output note of that Action is of a validly issued \(\mathsf{AssetBase}\) - when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in Split Notes.
      • + (see 7) when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in Split Notes.
    • Split Action: an Action that contains a Split Input.

    Abstract

    -

    ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol — a set of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain.

    -

    Creation of such Assets is defined in ZIP 227 6. Transfer and burn of such Assets is defined in ZIP 226 5. The ZSA protocol is proposed to be instantiated by a modification to the Orchard protocol, as specified in these ZIPs (although it has been designed with adaption to possible future shielded protocols in mind).

    +

    The ZIP (ZIP 226) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 227 6. The ZSA protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 6, while the transfer and burn of such Assets is defined in this ZIP (ZIP 226). While the proposed ZSA protocol is a modification to the Orchard protocol, it has been designed with adaption to possible future shielded protocols in mind.

    Motivation

    -

    None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes.

    +

    None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes. This ZIP builds on the issuance mechanism introduced in ZIP 227 6.

    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 \(\mathsf{AssetId}\) . This Asset Identifier maps to an Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 6.

    -

    The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 14 is preserved across Assets (see the Orchard Binding Signature 16), and by extension the balance of an Orchard transaction. That is, the sum of all the + that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 6.

    +

    The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 15 is preserved across Assets (see the Orchard Binding Signature 17), and by extension the balance of an Orchard transaction. That is, the sum of all the \(\mathsf{value^{net}}\) from each Action Description, computed as \(\mathsf{value^{old}-value^{new}}\) , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

    -

    As was initially proposed by Jack Grigg and Daira Hopwood 29 30, we propose to make this happen by changing the value base point, +

    As was initially proposed by Jack Grigg and Daira Hopwood 30 31, we propose to make this happen by changing the value base point, \(\mathcal{V}^{\mathsf{Orchard}}\) , in the Homomorphic Pedersen Commitment that derives the value commitment, \(\mathsf{cv^{net}}\) , of the net value in an Orchard Action.

    Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - an auxiliary input to the proof for each Action statement 26, represented already as a point on the Pallas curve. The circuit then should check that the same + an auxiliary input to the proof for each Action statement 27, represented already as a point on the Pallas curve. The circuit then should check that the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - is used in the old note commitment and the new note commitment 23, and as the base point + is used in the old note commitment and the new note commitment 24, and as the base point \(\mathcal{V}^\mathsf{Orchard}\) - in the value commitment 24. This ensures (1) that the input and output notes are of the same + in the value commitment 25. This ensures (1) that the input and output notes are of the same \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) , and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

    -

    In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 25 for Custom Assets, as we need to enforce that the +

    In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 26 for Custom Assets, as we need to enforce that the \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) of the output note of that Split Action is the output of a valid \(\mathsf{ZSAValueBase^{Orchard}}\) - computation defined in ZIP 227 6.

    + computation defined in ZIP 227 6.

    Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the \(\mathsf{valueBalance}\) of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets.

    @@ -94,7 +83,7 @@ \(\mathsf{AssetId}\) , the Asset Digest, and the Asset Base ( \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 6.

    + for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 6.

    This \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) will be the base point of the value commitment for the specific Custom Asset. Note that the @@ -103,7 +92,7 @@ \(\mathcal{V}^\mathsf{Orchard}\) .

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

    +

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

    Note Structure & Commitment

    @@ -112,7 +101,7 @@ be the type of a ZSA note, i.e. \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*\) .

    -

    A ZSA note differs from an Orchard note 12 by additionally including the Asset Base, +

    A ZSA note differs from an Orchard note 13 by additionally including the Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) . So a ZSA note is a tuple \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})\) @@ -120,7 +109,7 @@

    • \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) - is the unique element of the Pallas group 20 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as + is the unique element of the Pallas group 21 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .
    @@ -130,9 +119,9 @@
    \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)

    where \(\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}\) - are as defined for the Pallas curve 20, and + are as defined for the Pallas curve 21, and \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) - are as defined in the Zcash protocol specification 15. This note commitment scheme is instantiated using the Sinsemilla Commitment 23 as follows:

    + are as defined in the Zcash protocol specification 16. This note commitment scheme is instantiated using the Sinsemilla Commitment 24 as follows:

    \(\begin{align} \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} :=\begin{cases} @@ -150,21 +139,21 @@ \(\mathsf{repr}_{\mathbb{P}}\) and \(\mathsf{GroupHash}^{\mathbb{P}}\) - are as defined for the Pallas curve 20, + are as defined for the Pallas curve 21, \(\ell^{\mathsf{Orchard}}_{\mathsf{base}}\) - is as defined in §5.3 19, and + is as defined in §5.3 20, and \(\mathsf{I2LEBSP}\) - is as defined in §5.1 18 of the Zcash protocol specification.

    -

    The nullifier is generated in the same manner as in the Orchard protocol 17.

    -

    The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 13. It consists of

    + is as defined in §5.1 19 of the Zcash protocol specification.

    +

    The nullifier is generated in the same manner as in the Orchard protocol 18.

    +

    The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 14. It consists of

    \((\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, \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) , differs from the Orchard note commitment \(\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 23 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

    -

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

    + 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 24 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

    +

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

    \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} \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.

    @@ -183,15 +172,15 @@ respectively,

    \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) - is defined in ZIP 227 6, and

    + is defined in ZIP 227 6, and

    \(\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}\) , as in the Orchard protocol.

    We define \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}\) - so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4.

    + so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4.

    Rationale for Value Commitment

    -

    The Orchard Protocol uses a Homomorphic Pedersen Commitment 24 to perform the value commitment, with fixed base points +

    The Orchard Protocol uses a Homomorphic Pedersen Commitment 25 to perform the value commitment, with fixed base points \(\mathcal{V}^{\mathsf{Orchard}}\) and \(\mathcal{R}^{\mathsf{Orchard}}\) @@ -200,7 +189,7 @@

    Value Balance Verification

    -

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 16.

    +

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 17.

    For a total of \(n\) Actions in a transfer, the prover MUST still sign the SIGHASH of the transaction using the binding signature key @@ -233,14 +222,14 @@

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

    • Rationale for Split Notes

    -

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 25 to the Actions that have not been assigned input notes.

    +

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

    The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

    Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the split_flag boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified.

    Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets.

    Circuit Statement

    -

    Every ZSA Action statement is closely similar to the Orchard Action statement 26, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    +

    Every ZSA Action statement is closely similar to the Orchard Action statement 27, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    Asset Base Equality

    The following constraints must be added to ensure that the input and output note are of the same \(\mathsf{AssetBase}\) @@ -249,12 +238,12 @@

  • The Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) , for the note is witnessed once, as an auxiliary input.
    • -
  • In the Old note commitment integrity constraint in the Orchard Action statement 26, +
  • In the Old note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) .
    • -
  • In the New note commitment integrity constraint in the Orchard Action statement 26, +
  • In the New note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) @@ -354,7 +343,7 @@

    • Backwards Compatibility with ZEC Notes

    -

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 15. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    +

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 16. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    @@ -399,7 +388,7 @@

    ZSA Transaction Structure

    -

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 27. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 27.

    +

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    @@ -485,7 +474,7 @@

    ZSA Orchard Action Description Encoding

    -

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 28. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    +

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 29. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    @@ -574,7 +563,7 @@

    TxId Digest

    -

    The transaction digest algorithm defined in ZIP 244 10 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 11 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

    A BLAKE2b-256 hash of the following values

    T.1: header_digest       (32-byte hash output)
@@ -582,7 +571,7 @@
 T.3: sapling_digest      (32-byte hash output)
 T.4: orchard_digest      (32-byte hash output)  [UPDATED FOR ZSA]
 T.5: issuance_digest     (32-byte hash output)  [ADDED FOR ZSA]
    -

    The personalization field remains the same as in ZIP 244 10.

    +

    The personalization field remains the same as in ZIP 244 11.

    T.4: orchard_digest

    When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values

    T.4a: orchard_actions_compact_digest      (32-byte hash output)          [UPDATED FOR ZSA]
@@ -592,7 +581,7 @@
 T.4e: valueBalanceOrchard                 (64-bit signed little-endian)
 T.4f: anchorOrchard                       (32 bytes)
    T.4a: orchard_actions_compact_digest
    -

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 11 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 12 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4a.i  : nullifier            (field encoding bytes)
 T.4a.ii : cmx                  (field encoding bytes)
 T.4a.iii: ephemeralKey         (field encoding bytes)
@@ -607,7 +596,7 @@
                         
    "ZTxIdOrcActMHash"
    T.4c: orchard_actions_noncompact_digest
    -

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 11 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 12 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4d.i  : cv                    (field encoding bytes)
 T.4d.ii : rk                    (field encoding bytes)
 T.4d.iii: encCiphertext[596..]  (post-memo suffix of field encoding)  [UPDATED FOR ZSA]
@@ -617,12 +606,12 @@

    T.5: issuance_digest

    -

    The details of the computation of this value are in ZIP 227 7.

    +

    The details of the computation of this value are in ZIP 227 8.

    Signature Digest and Authorizing Data Commitment

    -

    The details of the changes to these algorithms are in ZIP 227 8 9.

    +

    The details of the changes to these algorithms are in ZIP 227 9 10.

    Security and Privacy Considerations

      @@ -638,7 +627,7 @@

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 31.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    Backward Compatibility

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the @@ -711,10 +700,18 @@

    - +
    + + + +
    7ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier
    + + + + @@ -722,7 +719,7 @@
    8 ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance
    - + @@ -730,7 +727,7 @@
    89 ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest
    - + @@ -738,7 +735,7 @@
    910 ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment
    - + @@ -746,7 +743,7 @@
    1011 ZIP 244: Transaction Identifier Non-Malleability
    - + @@ -754,7 +751,7 @@
    1112 ZIP 307: Light Client Protocol for Payment Detection
    - + @@ -762,7 +759,7 @@
    1213 Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes
    - + @@ -770,7 +767,7 @@
    1314 Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields
    - + @@ -778,7 +775,7 @@
    1415 Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions
    - + @@ -786,7 +783,7 @@
    1516 Zcash Protocol Specification, Version 2022.3.8. Section 4.1.8: Commitment
    - + @@ -794,7 +791,7 @@
    1617 Zcash Protocol Specification, Version 2022.3.8. Section 4.14: Balance and Binding Signature (Orchard)
    - + @@ -802,7 +799,7 @@
    1718 Zcash Protocol Specification, Version 2022.3.8. Section 4.16: Note Commitments and Nullifiers
    - + @@ -810,7 +807,7 @@
    1819 Zcash Protocol Specification, Version 2022.3.8. Section 5.1: Integers, Bit Sequences, and Endianness
    - + @@ -818,7 +815,7 @@
    1920 Zcash Protocol Specification, Version 2022.3.8. Section 5.3: Constants
    - + @@ -826,7 +823,7 @@
    2021 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.6: Pallas and Vesta
    - + @@ -834,7 +831,7 @@
    2122 Pallas/Vesta supporting evidence
    - + @@ -842,7 +839,7 @@
    2223 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.1.9: Sinsemilla hash function
    - + @@ -850,7 +847,7 @@
    2324 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.4: Sinsemilla commitments
    - + @@ -858,7 +855,7 @@
    2425 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
    - + @@ -866,7 +863,7 @@
    2526 Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard)
    - + @@ -874,7 +871,7 @@
    2627 Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard)
    - + @@ -882,7 +879,7 @@
    2728 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    - + @@ -890,7 +887,7 @@
    2829 Zcash Protocol Specification, Version 2022.3.8. Section 7.5: Action Description Encoding and Consensus
    - + @@ -898,7 +895,7 @@
    2930 User-Defined Assets and Wrapped Assets
    - + @@ -906,7 +903,7 @@
    3031 Comment on Generalized Value Commitments
    - + diff --git a/zip-0226.rst b/zip-0226.rst index 0092bd1f8..6b71624ad 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -25,40 +25,26 @@ The key word "MUST" in this document is to be interpreted as described in RFC 21 The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. -The terms "Orchard" and "Action" in this document are to be interpreted as described in -ZIP 224 [#zip-0224]_. +The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 [#zip-0224]_. -We define the following additional terms: - -- Asset: A type of note that can be transferred on the Zcash block chain, identified by the :math:`\mathsf{AssetId}` parameter. +The terms "Asset", "Custom Asset" and "Wrapped Asset" in this document are to be interpreted as described in ZIP 227 [#zip-0227]_. - - ZEC is the default (and currently the only defined) Asset for the Zcash mainnet. - - TAZ is the default (and currently the only defined) Asset for the Zcash testnet. - - We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ. +We define the following additional terms: -- Native Asset: a Custom Asset with issuance defined on the Zcash block chain. -- Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash block chain. -- Split Input: an Action input used to ensure that the output note of that Action is of a validly issued :math:`\mathsf{AssetBase}` when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in `Split Notes`_. +- Split Input: an Action input used to ensure that the output note of that Action is of a validly issued :math:`\mathsf{AssetBase}` (see [#zip-0227-assetidentifier]_) when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in `Split Notes`_. - Split Action: an Action that contains a Split Input. Abstract ======== -ZIP 226 and ZIP 227 propose in conjunction the Zcash Shielded Assets (ZSA) protocol — a set -of protocol features that enable the creation, transfer, and burn of Custom Assets on the Zcash chain. - -Creation of such Assets is defined in ZIP 227 [#zip-0227]_. Transfer and burn of such Assets is defined -in ZIP 226 [#zip-0226]_. The ZSA protocol is proposed to be instantiated by a modification to the -Orchard protocol, as specified in these ZIPs (although it has been designed with adaption -to possible future shielded protocols in mind). +This ZIP (ZIP 226) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 227 [#zip-0227]_. The ZSA protocol is an extension of the Orchard protocol that enables the issuance, transfer and burn of custom Assets on the Zcash chain. The issuance of such Assets is defined in ZIP 227 [#zip-0227]_, while the transfer and burn of such Assets is defined in this ZIP (ZIP 226). +While the proposed ZSA protocol is a modification to the Orchard protocol, it has been designed with adaptation to possible future shielded protocols in mind. Motivation ========== -None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling -multi-asset support on the Zcash chain will open the door for a host of applications, and -enhance the ecosystem with application developers and Asset custody institutions for -issuance and bridging purposes. +None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes. +This ZIP builds on the issuance mechanism introduced in ZIP 227 [#zip-0227]_. Overview ======== @@ -526,6 +512,7 @@ References .. [#zip-0224] `ZIP 224: Orchard `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ +.. [#zip-0227-assetidentifier] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier `_ .. [#zip-0227-txiddigest] `ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance `_ .. [#zip-0227-sigdigest] `ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest `_ .. [#zip-0227-authcommitment] `ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment `_ From 69d3f770a43c05d3f6324554095ba77eb1d40ed0 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 29 Jun 2023 20:25:50 +0530 Subject: [PATCH 19/42] Changing issue digest hash personalization values to match with implementation (#29) This makes the changes in ZIP 227 based on [this comment](https://github.com/QED-it/orchard/pull/66#discussion_r1227395737). --- zip-0227.html | 4 ++-- zip-0227.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 8a400bb8c..ac62380ba 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -488,7 +488,7 @@ T.5a.ii : assetDescription (field encoding bytes) T.5a.iii: flagsIssuance (1 byte)

    The personalization field of this hash is set to:

    - 
    "ZTxIdIssActHash_" (1 underscore character)
    + 
    "ZTxIdIssuActHash"
    T.5a.i: issue_notes_digest

    A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:

    T.5a.i.1: recipient                    (field encoding bytes)
@@ -497,7 +497,7 @@
 T.5a.i.4: rho                          (field encoding bytes)
 T.5a.i.5: rseed                        (field encoding bytes)

    The personalization field of this hash is set to:

    - 
    "ZTxIdIANoteHash_" (1 underscore character)
    + 
    "ZTxIdIAcNoteHash"
    T.5a.i.1: recipient

    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 22.

    diff --git a/zip-0227.rst b/zip-0227.rst index 8ad96c814..35e6999ce 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -385,7 +385,7 @@ A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belongin The personalization field of this hash is set to:: - "ZTxIdIssActHash_" (1 underscore character) + "ZTxIdIssuActHash" T.5a.i: issue_notes_digest '''''''''''''''''''''''''' @@ -399,7 +399,7 @@ A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance A The personalization field of this hash is set to:: - "ZTxIdIANoteHash_" (1 underscore character) + "ZTxIdIAcNoteHash" T.5a.i.1: recipient ................... From c4e55ead288cf32209aeb10dc0b8a889797c0fe7 Mon Sep 17 00:00:00 2001 From: Antoine Rondelet Date: Tue, 4 Jul 2023 10:06:45 +0100 Subject: [PATCH 20/42] Added missing indices over sums (#27) This PR adds missing indices over sums. It also fixes and makes improvements to the burn mechanism description. --------- Co-authored-by: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> --- zip-0226.html | 117 +++++++++++++++++++++++++++++++++++++++----------- zip-0226.rst | 40 +++++++++++++---- 2 files changed, 125 insertions(+), 32 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 3db141036..56678253b 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -37,7 +37,7 @@

    Abstract

    -

    The ZIP (ZIP 226) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 227 6. The ZSA protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 6, while the transfer and burn of such Assets is defined in this ZIP (ZIP 226). While the proposed ZSA protocol is a modification to the Orchard protocol, it has been designed with adaption to possible future shielded protocols in mind.

    +

    This ZIP (ZIP 226) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 227 6. The ZSA protocol is an extension of the Orchard protocol that enables the issuance, transfer and burn of custom Assets on the Zcash chain. The issuance of such Assets is defined in ZIP 227 6, while the transfer and burn of such Assets is defined in this ZIP (ZIP 226). While the proposed ZSA protocol is a modification to the Orchard protocol, it has been designed with adaptation to possible future shielded protocols in mind.

    Motivation

    None of the currently deployed Zcash transfer protocols support Custom Assets. Enabling multi-asset support on the Zcash chain will open the door for a host of applications, and enhance the ecosystem with application developers and Asset custody institutions for issuance and bridging purposes. This ZIP builds on the issuance mechanism introduced in ZIP 227 6.

    @@ -178,9 +178,13 @@ , as in the Orchard protocol.

    We define \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}\) - so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4.

    + so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4. As such + \(\mathsf{ValueCommit^{Orchard}_{rcv}(v)}\) + as defined in 4 is used as + \(\mathsf{ValueCommit^{OrchardZSA}_{rcv}(v, \mathcal{V}^{\mathsf{Orchard}})}\) + here.

    Rationale for Value Commitment

    -

    The Orchard Protocol uses a Homomorphic Pedersen Commitment 25 to perform the value commitment, with fixed base points +

    The Orchard Protocol uses a Homomorphic Pedersen Commitment 25 to perform the value commitment, with fixed base points \(\mathcal{V}^{\mathsf{Orchard}}\) and \(\mathcal{R}^{\mathsf{Orchard}}\) @@ -189,17 +193,53 @@

    Value Balance Verification

    -

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 17.

    +

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 17.

    For a total of \(n\) Actions in a transfer, the prover MUST still sign the SIGHASH of the transaction using the binding signature key - \(\mathsf{bsk} = \sum_{\mathsf{ \forall i\in \{1,...,n\}}} \mathsf{rcv_{i}}\) + \(\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_{i}\) .

    Then the verifier MUST compute

    -
    \(\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} = \sum \mathsf{rcv_{i}^{net}}\mathcal{R}^{\mathsf{Orchard}}\)
    -

    and use it to verify the bindingSignature on the SIGHASH message.

    +
    \(\mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{\mathsf{Orchard}})}\)
    +

    After computing + \(\mathsf{bvk}\) + , the verifier MUST use it to verify the bindingSignature on the SIGHASH message.

    Rationale for Value Balance Verification

    -

    The main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, +

    We assume + \(n\) + Actions in a transfer. Out of these + \(n\) + Actions, we further distinguish (for the sake of verbosity and clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume + \(m\) + Actions related to ZEC and + \(n-m\) + actions related to Custom Assets, where + \(m \in [0,n]\) + . Furthermore, we assume for simplicity that given a tuple of + \(n\) + Actions in a transfer, the + \(m\) + Actions related to ZEC are first (in practice Actions could be in whatever order).

    +

    The value balance verification is equivalent to:

    +
    \(\mathsf{bvk} = (\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_j) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{Orchard})}\)
    +

    This equation contains the balance check of the Orchard protocol 17. With ZSA, transfer Actions for Custom Assets MUST also be balanced across asset bases. As such, for a correctly constructed transaction, we MUST get + \(\mathsf{(\sum_{j=m+1}^{n} v_j^{net}) = 0}\) + , and thus be left with + \(\mathsf{\sum_{j=m+1}^{n} rcv_{j}^{net}}\mathcal{R}^{\mathsf{Orchard}}\) + in the expression. If + \(m=n\) + (resp. + \(m=0\) + ), i.e. all Actions relate to ZEC (resp. Custom Assets), then + \(m+1>n\) + (resp. + \(1>m\) + ), and thus the sum + \(\sum_{j=m+1}^{n}\) + (resp. + \(\sum_{i=1}^{m}\) + ) returns the identity element of the group.

    +

    So, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, \(\mathsf{v^{balanceOrchard}}\) . No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is burnt, as we will see below in the burn mechanism.

    As in the Orchard protocol, the binding signature verification key, @@ -222,14 +262,14 @@

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

    • Rationale for Split Notes

    -

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

    +

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

    The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

    Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the split_flag boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified.

    Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets.

    Circuit Statement

    -

    Every ZSA Action statement is closely similar to the Orchard Action statement 27, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    +

    Every ZSA Action statement is closely similar to the Orchard Action statement 27, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    Asset Base Equality

    The following constraints must be added to ensure that the input and output note are of the same \(\mathsf{AssetBase}\) @@ -238,12 +278,12 @@

  • The Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) , for the note is witnessed once, as an auxiliary input.
    • -
  • In the Old note commitment integrity constraint in the Orchard Action statement 27, +
  • In the Old note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) .
    • -
  • In the New note commitment integrity constraint in the Orchard Action statement 27, +
  • In the New note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) @@ -343,7 +383,7 @@

    • Backwards Compatibility with ZEC Notes

    -

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 16. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    +

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 16. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    @@ -360,13 +400,22 @@ \((\mathsf{AssetBase},\mathsf{v^{AssetBase}})\) such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.

    \(\mathsf{assetBurn} = \{ (\mathsf{AssetBase},\mathsf{v^{AssetBase}})\ |\ \forall\ \mathsf{AssetBase}\ \textit{s.t.}\ \mathsf{v^{AssetBase}} \neq 0 \}\)
    +

    We denote by + \(L\) + the cardinality of the + \(\mathsf{assetBurn}\) + set.

    The value balances for each Asset Identifier in \(\mathsf{assetBurn}\) represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

    The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective \(\mathsf{AssetBase}\) - as the value base point of the Pedersen Commitment. This is done as follows

    -
    \(\mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\mathsf{assetBurn}} \mathsf{ValueCommit_0^{OrchardZSA}(AssetBase, v^{AssetBase}) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}}\)
    + as the value base point of the Pedersen Commitment.

    +

    This is done as follows:

    +
    \(\mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v^{balanceOrchard}}, \mathcal{V}^{\mathsf{Orchard}}) - \sum_{k=1}^{L} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v}_{k}, \mathsf{AssetBase}_{k})\)
    +

    After computing + \(\mathsf{bvk}\) + , the verifier MUST use it to verify the bindingSignature on the SIGHASH message.

    In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt.

    Burn Mechanism Consensus Rules

      @@ -385,10 +434,30 @@ .

    Note: Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

    +

    Rationale for Burn Mechanism

    +

    As for the value balance verification, we assume + \(n\) + Actions, + \(m\) + of which are related to ZEC and the remaining + \(n-m\) + Actions related to Custom Assets.

    +

    The burn mechanism verification is equivalent to:

    +
    \(\mathsf{bvk} = ((\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_{j})) - ([\mathsf{v^{balanceOrchard}}]\mathcal{V}^{\mathsf{Orchard}} + [0]\mathcal{R}^{\mathsf{Orchard}}) - (\sum_{k=1}^{L} [\mathsf{v}_{k}]\mathsf{AssetBase}_{k} + [0]\mathcal{R}^{\mathsf{Orchard}})\)
    +

    The relationship between + \(\mathsf{bvk}\) + and + \(\mathsf{bsk}\) + will hold only if the sum of the net values of the Actions equals the sum of + \(\mathsf{v^{balanceOrchard}}\) + and the + \(\mathsf{v_k}\) + values, across base points (i.e. Asset Base).

    +

    ZSA Transaction Structure

    -

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    +

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    3132 ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
    @@ -474,7 +543,7 @@

    ZSA Orchard Action Description Encoding

    -

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 29. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    +

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 29. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    @@ -563,7 +632,7 @@

    TxId Digest

    -

    The transaction digest algorithm defined in ZIP 244 11 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 11 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

    A BLAKE2b-256 hash of the following values

    T.1: header_digest       (32-byte hash output)
@@ -571,7 +640,7 @@
 T.3: sapling_digest      (32-byte hash output)
 T.4: orchard_digest      (32-byte hash output)  [UPDATED FOR ZSA]
 T.5: issuance_digest     (32-byte hash output)  [ADDED FOR ZSA]
    -

    The personalization field remains the same as in ZIP 244 11.

    +

    The personalization field remains the same as in ZIP 244 11.

    T.4: orchard_digest

    When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values

    T.4a: orchard_actions_compact_digest      (32-byte hash output)          [UPDATED FOR ZSA]
@@ -581,7 +650,7 @@
 T.4e: valueBalanceOrchard                 (64-bit signed little-endian)
 T.4f: anchorOrchard                       (32 bytes)
    T.4a: orchard_actions_compact_digest
    -

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 12 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 12 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4a.i  : nullifier            (field encoding bytes)
 T.4a.ii : cmx                  (field encoding bytes)
 T.4a.iii: ephemeralKey         (field encoding bytes)
@@ -596,7 +665,7 @@
                         
    "ZTxIdOrcActMHash"
    T.4c: orchard_actions_noncompact_digest
    -

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 12 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 12 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4d.i  : cv                    (field encoding bytes)
 T.4d.ii : rk                    (field encoding bytes)
 T.4d.iii: encCiphertext[596..]  (post-memo suffix of field encoding)  [UPDATED FOR ZSA]
@@ -606,12 +675,12 @@

    T.5: issuance_digest

    -

    The details of the computation of this value are in ZIP 227 8.

    +

    The details of the computation of this value are in ZIP 227 8.

    Signature Digest and Authorizing Data Commitment

    -

    The details of the changes to these algorithms are in ZIP 227 9 10.

    +

    The details of the changes to these algorithms are in ZIP 227 9 10.

    Security and Privacy Considerations

      @@ -627,7 +696,7 @@

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    Backward Compatibility

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the diff --git a/zip-0226.rst b/zip-0226.rst index 6b71624ad..a9cabad27 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -150,7 +150,7 @@ where :math:`\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{A :math:`\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}`, as in the Orchard protocol. -We define :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}` so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 [#zip-0224]_. +We define :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}` so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 [#zip-0224]_. As such :math:`\mathsf{ValueCommit^{Orchard}_{rcv}(v)}` as defined in [#zip-0224]_ is used as :math:`\mathsf{ValueCommit^{OrchardZSA}_{rcv}(v, \mathcal{V}^{\mathsf{Orchard}})}` here. Rationale for Value Commitment `````````````````````````````` @@ -163,21 +163,29 @@ The use of different value base points for different Assets enables the final ba Value Balance Verification -------------------------- -In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol [#protocol-binding]_. +In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol [#protocol-binding]_. For a total of :math:`n` Actions in a transfer, the prover MUST still sign the `SIGHASH` of the transaction using the binding signature key -:math:`\mathsf{bsk} = \sum_{\mathsf{ \forall i\in \{1,...,n\}}} \mathsf{rcv_{i}}`. +:math:`\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_{i}`. Then the verifier MUST compute -.. math:: \mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} = \sum \mathsf{rcv_{i}^{net}}\mathcal{R}^{\mathsf{Orchard}} +.. math:: \mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{\mathsf{Orchard}})} -and use it to verify the `bindingSignature` on the `SIGHASH` message. +After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the `bindingSignature` on the `SIGHASH` message. Rationale for Value Balance Verification ```````````````````````````````````````` -The main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is *burnt*, as we will see below in the `burn mechanism`_. +We assume :math:`n` Actions in a transfer. Out of these :math:`n` Actions, we further distinguish (for the sake of verbosity and clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume :math:`m` Actions related to ZEC and :math:`n-m` actions related to Custom Assets, where :math:`m \in [0,n]`. Furthermore, we assume for simplicity that given a tuple of :math:`n` Actions in a transfer, the :math:`m` Actions related to ZEC are first (in practice Actions could be in whatever order). + +The value balance verification is equivalent to: + +.. math:: \mathsf{bvk} = (\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_j) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{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. As such, for a correctly constructed transaction, we MUST get :math:`\mathsf{(\sum_{j=m+1}^{n} v_j^{net}) = 0}`, and thus be left with :math:`\mathsf{\sum_{j=m+1}^{n} rcv_{j}^{net}}\mathcal{R}^{\mathsf{Orchard}}` in the expression. If :math:`m=n` (resp. :math:`m=0`), i.e. all Actions relate to ZEC (resp. Custom Assets), then :math:`m+1>n` (resp. :math:`1>m`), and thus the sum :math:`\sum_{j=m+1}^{n}` (resp. :math:`\sum_{i=1}^{m}`) returns the identity element of the group. + +So, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is *burnt*, as we will see below in the `burn mechanism`_. 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 only sum to zero **per Asset Base**, as the Pedersen commitments add up homomorphically only with respect to the same value base point. @@ -267,11 +275,17 @@ For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` v .. math:: \mathsf{assetBurn} = \{ (\mathsf{AssetBase},\mathsf{v^{AssetBase}})\ |\ \forall\ \mathsf{AssetBase}\ \textit{s.t.}\ \mathsf{v^{AssetBase}} \neq 0 \} +We denote by :math:`L` the cardinality of the :math:`\mathsf{assetBurn}` set. + The value balances for each Asset Identifier in :math:`\mathsf{assetBurn}` represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). -The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective :math:`\mathsf{AssetBase}` as the value base point of the Pedersen Commitment. This is done as follows +The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective :math:`\mathsf{AssetBase}` as the value base point of the Pedersen Commitment. + +This is done as follows: -.. math:: \mathsf{bvk = (\sum cv_i^{net})} - \mathsf{ ValueCommit_0^{Orchard}(v^{balanceOrchard})} - \sum_{\mathsf{assetBurn}} \mathsf{ValueCommit_0^{OrchardZSA}(AssetBase, v^{AssetBase}) } = \sum \mathsf{rcv_{i,j}^{net}}\mathcal{R}^{\mathsf{Orchard}} +.. math:: \mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v^{balanceOrchard}}, \mathcal{V}^{\mathsf{Orchard}}) - \sum_{k=1}^{L} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v}_{k}, \mathsf{AssetBase}_{k}) + +After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the `bindingSignature` on the `SIGHASH` message. In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt. @@ -284,6 +298,16 @@ Burn Mechanism Consensus Rules **Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets. +Rationale for Burn Mechanism +```````````````````````````` + +As for the value balance verification, we assume :math:`n` Actions, :math:`m` of which are related to ZEC and the remaining :math:`n-m` Actions related to Custom Assets. + +The burn mechanism verification is equivalent to: + +.. math:: \mathsf{bvk} = ((\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_{j})) - ([\mathsf{v^{balanceOrchard}}]\mathcal{V}^{\mathsf{Orchard}} + [0]\mathcal{R}^{\mathsf{Orchard}}) - (\sum_{k=1}^{L} [\mathsf{v}_{k}]\mathsf{AssetBase}_{k} + [0]\mathcal{R}^{\mathsf{Orchard}}) + +The relationship between :math:`\mathsf{bvk}` and :math:`\mathsf{bsk}` will hold only if the sum of the net values of the Actions equals the sum of :math:`\mathsf{v^{balanceOrchard}}` and the :math:`\mathsf{v_k}` values, across base points (i.e. Asset Base). ZSA Transaction Structure ========================= From f7658185f04de44b47be27bbadd574151e442bcc Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:22:35 +0530 Subject: [PATCH 21/42] Consistency changes for notation and updates to issuance key derivation (#30) This PR improves the naming of variables to make them consistent with the broader ZIPs conventions. It also makes changes to the issuance key derivation and the terms used for the various keys. --- zip-0226.html | 50 ++++-- zip-0226.rst | 29 ++-- zip-0227-key-components-zsa.png | Bin 61722 -> 61500 bytes zip-0227-key-components-zsa.svg | 28 +--- zip-0227.html | 287 +++++++++++++++++++++----------- zip-0227.rst | 123 +++++++------- 6 files changed, 310 insertions(+), 207 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 56678253b..ed8fa975c 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -79,7 +79,9 @@

    Specification

    Most of the protocol is kept the same as the Orchard protocol released with NU5, except for the following.

    Asset Identifiers

    -

    For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an Asset description, assetDesc, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, +

    For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an Asset description, + \(\mathsf{asset\_desc}\) + , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, \(\mathsf{AssetId}\) , the Asset Digest, and the Asset Base ( \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) @@ -132,7 +134,7 @@

    where:

    \(\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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \\ +&\ \ \ \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{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""}) \end{align}\)

    Note that @@ -196,14 +198,14 @@

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 17.

    For a total of \(n\) - Actions in a transfer, the prover MUST still sign the SIGHASH of the transaction using the binding signature key + Actions in a transfer, the prover MUST still sign the SIGHASH transaction hash using the binding signature key \(\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_{i}\) .

    -

    Then the verifier MUST compute

    +

    The verifier MUST compute

    \(\mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{\mathsf{Orchard}})}\)

    After computing \(\mathsf{bvk}\) - , the verifier MUST use it to verify the bindingSignature on the SIGHASH message.

    + , the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash.

    Rationale for Value Balance Verification

    We assume \(n\) @@ -250,7 +252,9 @@

    Split Notes

    A Split Input is a copy of a previously issued input note (that is, a note that has previously been included in the Merkle tree), with the following changes:

      -
    • A split_flag boolean is set to 1.
      • +
    • A + \(\mathsf{split\_flag}\) + boolean is set to 1.
    • The value of the note is replaced with the value 0 during the computation of the value commitment.

    Input notes are sometimes split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output.

    @@ -264,7 +268,9 @@

    Rationale for Split Notes

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

    The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

    -

    Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the split_flag boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified.

    +

    Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the + \(\mathsf{split\_flag}\) + boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified.

    Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets.

    @@ -320,18 +326,24 @@
  • -
    Add a boolean split_flag variable as an auxiliary witness. This variable is to be activated split_flag = 1 if the Action in question has a Split Input and split_flag = 0 if the Action is actually spending an input note:
    +
    Add a boolean + \(\mathsf{split\_flag}\) + variable as an auxiliary witness. This variable is to be activated + \(\mathsf{split\_flag} = 1\) + if the Action in question has a Split Input and + \(\mathsf{split\_flag} = 0\) + if the Action is actually spending an input note:
    • If - \(\texttt{split_flag} = 1\) + \(\mathsf{split\_flag} = 1\) then constrain \(\mathsf{v}' = 0\) otherwise constrain \(\mathsf{v}'=\mathsf{v^{old}}\) from the auxiliary input.
    • If - \(\texttt{split_flag} = 1\) + \(\mathsf{split\_flag} = 1\) then constrain \(\mathsf{v^{old}} \neq 0\) .
      • @@ -368,7 +380,7 @@ \(\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})\)
    • if - \(\mathtt{split\_flag} = 0\) + \(\mathsf{split\_flag} = 0\) then constrain \(\psi' = \psi^{old}\) . (Otherwise @@ -415,7 +427,7 @@
      \(\mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v^{balanceOrchard}}, \mathcal{V}^{\mathsf{Orchard}}) - \sum_{k=1}^{L} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v}_{k}, \mathsf{AssetBase}_{k})\)

      After computing \(\mathsf{bvk}\) - , the verifier MUST use it to verify the bindingSignature on the SIGHASH message.

      + , the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash.

      In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt.

      Burn Mechanism Consensus Rules

        @@ -451,7 +463,7 @@ will hold only if the sum of the net values of the Actions equals the sum of \(\mathsf{v^{balanceOrchard}}\) and the - \(\mathsf{v_k}\) + \(\mathsf{v}_k\) values, across base points (i.e. Asset Base).

    • @@ -699,9 +711,15 @@

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    Backward Compatibility

    -

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the - \(AssetBase\) - value as well. - The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade. - The value commitment is abstracted to allow for the value base-point as a variable private input to the proof. - The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes.

    +

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this:

    +
      +
    • Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the + \(\mathsf{AssetBase}\) + value as well.
      • +
    • The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade.
      • +
    • The value commitment is abstracted to allow for the value base-point as a variable private input to the proof.
      • +
    • The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes.
      • +

    Deployment

    The Zcash Shielded Assets protocol will be deployed in a subsequent Network Upgrade.

    diff --git a/zip-0226.rst b/zip-0226.rst index a9cabad27..8c49827e7 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -70,7 +70,7 @@ Most of the protocol is kept the same as the Orchard protocol released with NU5, Asset Identifiers ----------------- -For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, ``assetDesc``, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. +For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. @@ -109,7 +109,7 @@ 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{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})) \\ + &\ \ \ \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{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""}) \end{align} @@ -165,14 +165,14 @@ Value Balance Verification In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol [#protocol-binding]_. -For a total of :math:`n` Actions in a transfer, the prover MUST still sign the `SIGHASH` of the transaction using the binding signature key +For a total of :math:`n` Actions in a transfer, the prover MUST still sign the SIGHASH transaction hash using the binding signature key :math:`\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_{i}`. -Then the verifier MUST compute +The verifier MUST compute .. math:: \mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{\mathsf{Orchard}})} -After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the `bindingSignature` on the `SIGHASH` message. +After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash. Rationale for Value Balance Verification ```````````````````````````````````````` @@ -195,7 +195,7 @@ Split Notes A Split Input is a copy of a previously issued input note (that is, a note that has previously been included in the Merkle tree), with the following changes: -- A ``split_flag`` boolean is set to 1. +- A :math:`\mathsf{split\_flag}` boolean is set to 1. - The value of the note is replaced with the value 0 during the computation of the value commitment. Input notes are sometimes split in two (or more) output notes, as in most cases, not all the value in a single note is sent to a single output. @@ -215,7 +215,7 @@ In the Orchard protocol, since each Action represents an input and an output, th The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions *cannot* contain *any* Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds. -Therefore, for Custom Assets we enforce that *every* input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the ``split_flag`` boolean). +Therefore, for Custom Assets we enforce that *every* input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the :math:`\mathsf{split\_flag}` boolean). This ensures that the value base points of all output notes of a transfer are actual outputs of a GroupHash, as they originate in the Issuance protocol which is publicly verified. Note that the Orchard dummy note functionality remains in use for ZEC notes, and the Split Input technique is used in order to support Custom Assets. @@ -250,14 +250,14 @@ Senders must not be able to change the Asset Base for the output note in a Split - The Value Commitment Integrity should be changed: - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}` -- Add a boolean ``split_flag`` variable as an auxiliary witness. This variable is to be activated ``split_flag = 1`` if the Action in question has a Split Input and ``split_flag = 0`` if the Action is actually spending an input note: - - If :math:`\texttt{split_flag} = 1` then constrain :math:`\mathsf{v}' = 0` otherwise constrain :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. - - If :math:`\texttt{split_flag} = 1` then constrain :math:`\mathsf{v^{old}} \neq 0`. +- Add a boolean :math:`\mathsf{split\_flag}` variable as an auxiliary witness. This variable is to be activated :math:`\mathsf{split\_flag} = 1` if the Action in question has a Split Input and :math:`\mathsf{split\_flag} = 0` if the Action is actually spending an input note: + - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{v}' = 0` otherwise constrain :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. + - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{v^{old}} \neq 0`. - The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes): - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^{old}}` to the anchor :math:`\mathsf{rt^{Orchard}}`. - The Nullifier Integrity will be changed to prevent the identification of notes - Replace the :math:`\psi_{old}` value with a generic :math:`\psi'` as :math:`\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})` - - if :math:`\mathtt{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled uniformly at random on :math:`\mathbb{F}_{q_{\mathbb{P}}}`.) + - if :math:`\mathsf{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled uniformly at random on :math:`\mathbb{F}_{q_{\mathbb{P}}}`.) Backwards Compatibility with ZEC Notes `````````````````````````````````````` @@ -285,7 +285,7 @@ This is done as follows: .. math:: \mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v^{balanceOrchard}}, \mathcal{V}^{\mathsf{Orchard}}) - \sum_{k=1}^{L} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v}_{k}, \mathsf{AssetBase}_{k}) -After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the `bindingSignature` on the `SIGHASH` message. +After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash. In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt. @@ -307,7 +307,7 @@ The burn mechanism verification is equivalent to: .. math:: \mathsf{bvk} = ((\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_{j})) - ([\mathsf{v^{balanceOrchard}}]\mathcal{V}^{\mathsf{Orchard}} + [0]\mathcal{R}^{\mathsf{Orchard}}) - (\sum_{k=1}^{L} [\mathsf{v}_{k}]\mathsf{AssetBase}_{k} + [0]\mathcal{R}^{\mathsf{Orchard}}) -The relationship between :math:`\mathsf{bvk}` and :math:`\mathsf{bsk}` will hold only if the sum of the net values of the Actions equals the sum of :math:`\mathsf{v^{balanceOrchard}}` and the :math:`\mathsf{v_k}` values, across base points (i.e. Asset Base). +The relationship between :math:`\mathsf{bvk}` and :math:`\mathsf{bsk}` will hold only if the sum of the net values of the Actions equals the sum of :math:`\mathsf{v^{balanceOrchard}}` and the :math:`\mathsf{v}_k` values, across base points (i.e. Asset Base). ZSA Transaction Structure ========================= @@ -505,7 +505,8 @@ Backward Compatibility ---------------------- In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this: -- Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the :math:`AssetBase` value as well. + +- Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the :math:`\mathsf{AssetBase}` value as well. - The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade. - The value commitment is abstracted to allow for the value base-point as a variable private input to the proof. - The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes. diff --git a/zip-0227-key-components-zsa.png b/zip-0227-key-components-zsa.png index aa9fa5d21d48885d21a987130a4504a92b74614e..4b6b017635100b27a61f3bfe2123f84a3f1544f1 100644 GIT binary patch delta 23936 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 diff --git a/zip-0227-key-components-zsa.svg b/zip-0227-key-components-zsa.svg index 217acc635..a7d9d866a 100644 --- a/zip-0227-key-components-zsa.svg +++ b/zip-0227-key-components-zsa.svg @@ -7,7 +7,7 @@ id="svg2" version="1.1" inkscape:version="1.2.2 (b0a84865, 2022-12-01)" - sodipodi:docname="key_components_zsa.svg" + sodipodi:docname="zip-0227-key-components-zsa.svg" inkscape:export-filename="key_components_zsa.png" inkscape:export-xdpi="179.99957" inkscape:export-ydpi="179.99957" @@ -33,8 +33,8 @@ showgrid="false" inkscape:window-width="1158" inkscape:window-height="916" - inkscape:window-x="177" - inkscape:window-y="38" + inkscape:window-x="381" + inkscape:window-y="81" inkscape:window-maximized="0" inkscape:showpageshadow="2" inkscape:pagecheckerboard="0" @@ -179,25 +179,15 @@ id="rect2985-9-7-8" style="fill:#fdb341;fill-opacity:1;stroke:#000000;stroke-width:1.06667;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />skissidkIssuance master keyIssuance derivation key

    Abstract

    -

    This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    +

    This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    Motivation

    -

    This ZIP introduces the issuance mechanism for custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 4) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 4.

    +

    This ZIP introduces the issuance mechanism for Custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 4) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 4.

    This ZIP only enables transparent issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.

    The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash blockchain), as well as for institutions to create bridges from other chains and import Wrapped Assets. This enables what we hope will be a useful set of applications.

    @@ -62,22 +62,28 @@

    Requirements

      -
    • Any user of the Zcash blockchain can issue custom Assets on chain.
      • +
    • Any user of the Zcash blockchain can issue Custom Assets on chain.
    • The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash blockchain.
    • Issuing or changing the attributes of a specific Asset should require cryptographic authorization.
    • The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier.
    • An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets.
      • -
    • Every "issuance action" should contain a finalize boolean that defines whether the specific Custom Asset can have further tokens issued or not.
      • +
    • Every "issuance action" should contain a + \(\mathsf{finalize}\) + boolean that defines whether the specific Custom Asset can have further tokens issued or not.

    Specification: Issuance Keys and Issuance Authorization Signature Scheme

    The ZSA Protocol adds the following three keys to the key components 17:

      -
    1. The issuance master key, denoted as - \(\mathsf{sk}_{\mathsf{iss}}\) - , as the name suggests, is the master key that is used to derive the other two keys.
      2. -
    2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as isk. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
      3. -
    3. The issuance validating key, denoted as ik, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
      4. +
    4. The issuance derivation key, denoted as + \(\mathsf{idk}\) + , as the name suggests, is the key that is used to derive the other two keys.
      5. +
    5. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as + \(\mathsf{isk}\) + . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
      6. +
    6. The issuance validating key, denoted as + \(\mathsf{ik}\) + , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.

    The relations between these keys are shown in the following diagram:

    @@ -89,7 +95,7 @@ \(\mathsf{IssueAuthSig}\) similar to \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) - , the Orchard spend authorization signature scheme 21. Specifically, we instantiate + , the Orchard spend authorization signature scheme 22. Specifically, we instantiate \(\mathsf{IssueAuthSig}\) as \(\mathsf{RedPallas}\) @@ -100,20 +106,20 @@ is defined as in the Zcash protocol specification 18.

    Issuance Key Derivation

    -

    The issuance master key is generated by choosing a bit sequence uniformly at random from +

    The issuance derivation key is generated by choosing a bit sequence uniformly at random from \(\mathbb{B}^{\mathbb{Y}[32]}\) - , like the Orchard spending key 19.

    -

    Issuance master key derivation for hierarchical deterministic wallets

    -

    The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

    + , like the Orchard spending key 20.

    +

    Issuance derivation key generation for hierarchical deterministic wallets

    +

    The issuance derivation key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

    Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\) .

    -

    As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the +

    As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance derivation key. We reuse the \(\mathsf{CDKsk}\) function for Orchard child key derivation from ZIP 32.

    -

    We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as +

    We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance derivation key path as \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\) . We fix the path levels as follows:

      @@ -139,27 +145,29 @@ \(0\) .
    -

    Given the extended issuance master key +

    From the generated \((\mathsf{sk}, \mathsf{c})\) - , we set the issuance master key to be - \(\mathsf{sk_{iss}} := \mathsf{sk}\) + , we set the issuance derivation key to be + \(\mathsf{idk} := \mathsf{sk}\) .

    Derivation of issuance authorizing key and issuance validating key

    -

    The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 19, as described below.

    +

    The issuance authorizing key and issuance validating key are derived from the issuance derivation key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 20, as described below.

      -
    • The issuance authorizing key is derived from the issuance master key, - \(\mathsf{sk}_{\mathsf{iss}}\) - , as a private signature key:
      • +
    • The issuance authorizing key is derived from the issuance derivation key, + \(\mathsf{idk}\) + , as a private signature key. The function + \(\mathsf{PRF^{expand}_{idk}}\) + is as defined in the Zcash protocol specification 19:
    -
    \(\mathtt{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} )\)
    +
    \(\mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{idk}}([\mathtt{0x0a}]) )\)
    • The issuance validating key is derived from the issuance authorizing key, - \(\mathtt{isk}\) + \(\mathsf{isk}\) , as a public verification key:
    -
    \(\mathtt{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathtt{isk})\)
    -

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    +
    \(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
    +

    This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

    @@ -167,8 +175,12 @@

    For every new Asset, there must be a new and unique Asset Identifier, denoted \(\mathsf{AssetId}\) . We define this to be a globally unique pair - \(\mathsf{AssetId} := (\mathtt{ik}, \mathtt{assetDesc})\) - , where ik is the issuance key and assetDesc is a byte string.

    + \(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})\) + , where + \(\mathsf{ik}\) + is the issuance key and + \(\mathsf{asset\_desc}\) + is a byte string.

    A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, \(\mathsf{AssetDigest}\) , which is simply is a @@ -178,15 +190,19 @@ for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

    Let

      -
    • assetDesc be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
      • -
    • ik be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
      • +
    • + \(\mathsf{asset\_desc}\) + be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
      • +
    • + \(\mathsf{ik}\) + be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.

    Define \(\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\) , where

    • - \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathtt{ik}, \mathtt{assetDesc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathtt{ik}) || \mathtt{assetDesc}\!\) + \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\) .

    Define @@ -196,7 +212,7 @@ \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 18.

    + is defined as in 18.

    The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

    @@ -211,31 +227,53 @@

    Specification: Global Issuance State

    Issuance requires the following additions to the global state defined at block boundaries:

      -
    • finalized_assets, a set of - \(\mathsf{AssetDigest}\) - that have been finalized (i.e.: the finalize flag has been set to 1 in some issuance transaction preceding the block boundary).
      • +
    • + \(\mathsf{previously\_finalized}\) + , a set of + \(\mathsf{AssetId}\) + that have been finalized (i.e.: the + \(\mathsf{finalize}\) + flag has been set to + \(1\) + in some issuance transaction preceding the block boundary).

    Specification: Issuance Action, Issuance Bundle and Issuance Protocol

    Issuance Action Description

    -

    An issuance action, IssueAction, is the instance of issuing a specific custom Asset, and contains the following fields:

    +

    An issuance action, IssueAction, is the instance of issuing a specific Custom Asset, and contains the following fields:

      -
    • assetDescSize: the size of the Asset description, a number between +
    • + \(\mathsf{assetDescSize}\) + : the size of the Asset description, a number between \(0\) and \(512\) , stored in two bytes.
      • -
    • assetDesc: the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
      • +
    • + \(\mathsf{asset\_desc}\) + : the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
    • vNotes: an array of Note containing the unencrypted output notes of the recipients of the Asset.
      • -
    • flagsIssuance: a byte that stores the finalize boolean that defines whether the issuance of that specific Custom Asset is finalized or not
      • +
    • flagsIssuance: a byte that stores the + \(\mathsf{finalize}\) + boolean that defines whether the issuance of that specific Custom Asset is finalized or not.

    An asset's \(\mathsf{AssetDigest}\) - is added to the finalized_assets set after a block that contains any issuance transaction for that asset with finalize = 1. It then cannot be removed from this set. For Assets with - \(\mathsf{AssetDigest} \in \mathtt{finalized\_assets}\) + is added to the + \(\mathsf{previously\_finalized}\) + set after a block that contains any issuance transaction for that asset with + \(\mathsf{finalize} = 1\) + . It then cannot be removed from this set. For Assets with + \(\mathsf{AssetDigest} \in \mathsf{previously\_finalized}\) , no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with - \(\mathsf{AssetDigest} \not\in \mathtt{finalized\_assets}\) - , new issuance actions can be issued in future transactions. These must use the same Asset description, assetDesc, and can either maintain finalize = 0 or change it to finalize = 1, denoting that this Custom Asset cannot be issued after the containing block.

    + \(\mathsf{AssetDigest} \not\in \mathsf{previously\_finalized}\) + , new issuance actions can be issued in future transactions. These must use the same Asset description, + \(\mathsf{asset\_desc}\) + , and can either maintain + \(\mathsf{finalize} = 0\) + or change it to + \(\mathsf{finalize} = 1\) + , denoting that this Custom Asset cannot be issued after the containing block.

    @@ -250,11 +288,13 @@ - + - + @@ -279,7 +319,9 @@
    An 8-bit value representing a set of flags. Ordered from LSB to MSB:
      -
    • finalize
      • +
    • + \(\mathsf{finalize}\) +
    • The remaining bits are set to 0.
    @@ -293,15 +335,19 @@

    Issuance Bundle

    An issuance bundle, IssueBundle, is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields:

      -
    • ik: the issuance validating key, that allows the validators to verify that the +
    • + \(\mathsf{ik}\) + : the issuance validating key, that allows the validators to verify that the \(\mathsf{AssetId}\) is properly associated with the issuer.
      • -
    • vIssueActions: an array of issuance actions, of type IssueAction.
      • -
    • issueAuthSig: the signature of the transaction SIGHASH, signed by the issuance authorizing key, - \(\mathtt{isk}\) +
    • vIssueActions: an array of issuance actions, of type IssueAction.
      • +
    • + \(\mathsf{issueAuthSig}\) + : the signature of the transaction SIGHASH, signed by the issuance authorizing key, + \(\mathsf{isk}\) , that validates the issuance .
    -

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 23.

    +

    The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 24.

    2 assetDescSize byteThe length of the assetDesc string in bytes.The length of the + \(\mathsf{asset\_desc}\) + string in bytes.
    assetDescSizeassetDescasset_desc byte[assetDescSize] A byte sequence of length assetDescSize bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
    @@ -343,16 +389,28 @@

    The issuer program performs the following operations

    For all actions IssueAction:

      -
    • encode assetDesc as a UTF-8 byte string of size up to 512.
      • +
    • encode + \(\mathsf{asset\_desc}\) + as a UTF-8 byte string of size up to 512.
    • compute \(\mathsf{AssetDigest}\) - from the issuance validating key ik and assetDesc as decribed in the Specification: Asset Identifier section.
      • + from the issuance validating key + \(\mathsf{ik}\) + and + \(\mathsf{asset\_desc}\) + as decribed in the Specification: Asset Identifier section.
    • compute \(\mathsf{AssetBase^{Protocol}}\) from \(\mathsf{AssetDigest}\) as decribed in the Specification: Asset Identifier section.
      • -
    • set the finalize boolean as desired (if more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1).
      • +
    • set the + \(\mathsf{finalize}\) + boolean as desired (if more issuance actions are to be created for this Asset Identifier, set + \(\mathsf{finalize} = 0\) + , otherwise set + \(\mathsf{finalize} = 1\) + )
    • For each recipient \(i\) : @@ -366,10 +424,12 @@

    For the IssueBundle:

      -
    • encode the vIssueActions vector.
      • -
    • encode the ik as 32 byte-string.
      • -
    • sign the SIGHASH of the transaction with the issuance authorizing key, - \(\mathtt{isk}\) +
    • encode the vIssueActions vector
      • +
    • encode the + \(\mathsf{ik}\) + as 32 byte-string
      • +
    • sign the SIGHASH transaction hash with the issuance authorizing key, + \(\mathsf{isk}\) , using the \(\mathsf{IssueAuthSig}\) signature scheme. The signature is then added to the issuance bundle.
      • @@ -380,9 +440,13 @@

      Specification: Consensus Rule Changes

      For the IssueBundle:

        -
      • Verify the RedPallas-based issuance authorization signature on SIGHASH, issueAuthSig, is verified by invoking - \(\mathsf{issueAuthSig.VerifySig}(\mathtt{ik}, \mathtt{SIGHASH})\) - .
        • +
      • Verify the RedPallas-based issuance authorization signature on the SIGHASH transaction hash, + \(\mathsf{SigHash}\) + , + \(\mathsf{issueAuthSig}\) + , is verified by invoking + \(\mathsf{issueAuthSig.VerifySig(ik, SigHash)}\) +

      For each IssueAction in IssueBundle:

        @@ -390,7 +454,7 @@ \(0 < \mathtt{assetDescSize} <= 512\) .
      • check that - \(\mathtt{assetDesc}\) + \(\mathsf{asset\_desc}\) is a string of length \(\mathtt{assetDescSize}\) bytes.
        • @@ -398,10 +462,16 @@ \(\mathsf{AssetBase}\) from the first note in the sequence and check that \(\mathsf{AssetBase}\) - is derived from the issuance validating key ik and assetDesc as described in the Specification: Asset Identifier section. + is derived from the issuance validating key + \(\mathsf{ik}\) + and + \(\mathsf{asset\_desc}\) + as described in the Specification: Asset Identifier section.
      • check that the \(\mathsf{AssetDigest}\) - does not exist in the finalized_assets set in the global state.
        • + does not exist in the + \(\mathsf{previously\_finalized}\) + set in the global state.
      • check that every note in the IssueAction contains the same \(\mathsf{AssetBase}\) and is properly constructed as @@ -412,13 +482,17 @@
        • For each note, compute the note commitment as \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) - as defined in the Note Structure and Commitment section of ZIP 226 5 and
          • + as defined in the Note Structure and Commitment section of ZIP 226 5 and
        • Add \(\mathsf{cm}\) to the Merkle tree of note commitments.
          • -
        • If finalize = 1, add +
        • If + \(\mathsf{finalize} = 1\) + , add \(\mathsf{AssetDigest}\) - to the finalized_assets set immediately after the block in which this transaction occurs.
          • + to the + \(\mathsf{previously\_finalized}\) + set immediately after the block in which this transaction occurs.
        • (Replay Protection) If issue bundle is present, the fees MUST be greater than zero.
      @@ -427,7 +501,9 @@
      • The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools.
      • The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”.
        • -
      • The assetDesc is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: +
      • The + \(\mathsf{asset\_desc}\) + is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are:
        • links for storage such as for NFTs.
        • metadata for Assets, encoded in any format.
          • @@ -435,37 +511,51 @@
        • information to be committed by the issuer, though not enforceable by the protocol.
        • -
      • We require a check whether the finalize flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the finalized_assets set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
        • -
      • We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH, potentially allowing for a replay attack.
        • +
      • We require a check whether the + \(\mathsf{finalize}\) + flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the + \(\mathsf{previously\_finalized}`\) + set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
        • +
      • We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack.

      Concrete Applications

      Asset Features

        -
      • By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example, +
      • By using the + \(\mathsf{finalize}\) + boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example,
          -
        • by setting finalize = 1 from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed.
          • +
        • by setting + \(\mathsf{finalize} = 1\) + from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed.
      • Issuers can also stop the existing supply production of any Asset associated to their issuer keys. This could be done by
        • issuing a last set of tokens of that specific \(\mathsf{AssetId}\) - , for which finalize = 1, or by
          • + , for which + \(\mathsf{finalize} = 1\) + , or by
        • issuing a transaction with a single note in the issuance action pertaining to that \(\mathsf{AssetId}\) , where the note will contain a value = 0. This can be used for application-specific purposes (NFT collections) or for security purposes to revoke the Asset issuance (see Security and Privacy Considerations).
          • -
        • Note in the above cases, that the setting of the finalize flag will take effect at the block boundary, that is, after all the transactions in the block.
          • +
        • Note in the above cases, that the setting of the + \(\mathsf{finalize}\) + flag will take effect at the block boundary, that is, after all the transactions in the block.
      • The issuance and burn mechanisms can be used in conjunction to determine the supply of Assets on the Zcash ecosystem. This allows for the bridging of Assets defined on other chains.
      • Furthermore, NFT issuance is enabled by issuing in a single bundle several issuance actions, where each \(\mathsf{AssetId}\) - corresponds to value = 1 at the fundamental unit level. Issuers and users should make sure that finalize = 1 for each of the actions in this scenario.
        • + corresponds to value = 1 at the fundamental unit level. Issuers and users should make sure that + \(\mathsf{finalize} = 1\) + for each of the actions in this scenario.

      TxId Digest - Issuance

      -

      This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

      +

      This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

      A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

      issuance_digest
 ├── issue_actions_digest
@@ -499,7 +589,7 @@
                         
      The personalization field of this hash is set to:
      
                         
      "ZTxIdIAcNoteHash"
      
                         
      T.5a.i.1: recipient 
      
-                            
      This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 22.
      
+                            
      This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 23.
      
                         
      
                         
      T.5a.i.2: value 
      
                             
      Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
      
@@ -520,7 +610,9 @@
                     
      T.5a.iii: flagsIssuance 
      
                         
      An 8-bit value representing a set of flags. Ordered from LSB to MSB:
      
                         
        
-                            
      • finalize
        • 
+                            
      • 
+                                \(\mathsf{finalize}\)
+                            
        • 
                             
      • The remaining bits are set to 0.
        • 
                         
      
                     
      
@@ -531,7 +623,7 @@

      Signature Digest

      -

      The per-input transaction digest algorithm to generate the signature digest in ZIP 244 8 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.

      +

      The per-input transaction digest algorithm to generate the signature digest in ZIP 244 8 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.

      The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

      signature_digest
 ├── header_digest
@@ -546,14 +638,14 @@
 S.3: sapling_digest         (32-byte hash output)
 S.4: orchard_digest         (32-byte hash output)
 S.5: issuance_digest        (32-byte hash output)  [ADDED FOR ZSA]
      -

      The personalization field remains the same as in ZIP 244 7.

      +

      The personalization field remains the same as in ZIP 244 7.

      S.5: issuance_digest

      Identical to that specified for the transaction identifier.

      Authorizing Data Commitment

      -

      The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

      +

      The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

      auth_digest
 ├── transparent_scripts_digest
 ├── sapling_auth_digest
@@ -579,9 +671,11 @@

      Security and Privacy Considerations

      Issuance Key Compromise

      -

      The design of this protocol does not currently allow for a rotation of the issuance validating key that would allow for replacing the key of a specific Asset (see Future Work). In case of compromise, the following actions are recommended:

      +

      The design of this protocol does not currently allow for rotation of the issuance validating key that would allow for replacing the key of a specific Asset. In case of compromise, the following actions are recommended:

        -
      • If an issuance validating key is compromised, the finalize boolean for all the Assets issued with that key should be set to +
      • If an issuance validating key is compromised, the + \(\mathsf{finalize}\) + boolean for all the Assets issued with that key should be set to \(1\) and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new \(\mathsf{AssetId}\) @@ -589,7 +683,7 @@

      Bridging Assets

      -

      For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

      +

      For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

      Other Considerations

      @@ -601,10 +695,7 @@ in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

      Fee Structures

      -

      The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 10.

      -
      -

      Future Work

      -

      In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying ik of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether.

      +

      The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 10.

      Test Vectors

      @@ -766,10 +857,18 @@
    - +
    + + + +
    19Zcash Protocol Specification, Version 2022.3.8. Section 4.1.2: Pseudo Random Functions
    + + + + @@ -777,7 +876,7 @@
    20 Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
    - + @@ -785,7 +884,7 @@
    2021 Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -793,7 +892,7 @@
    2122 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -801,7 +900,7 @@
    2223 Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
    - + diff --git a/zip-0227.rst b/zip-0227.rst index 35e6999ce..b2d2225a5 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -43,12 +43,12 @@ We define the following additional terms: Abstract ======== -This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA. +This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA. Motivation ========== -This ZIP introduces the issuance mechanism for custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 [#zip-0226]_) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 [#zip-0226]_. +This ZIP introduces the issuance mechanism for Custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 [#zip-0226]_) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 [#zip-0226]_. This ZIP only enables *transparent* issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked. @@ -69,12 +69,12 @@ See the `Concrete Applications`_ section for more details. Requirements ============ -- Any user of the Zcash blockchain can issue custom Assets on chain. +- Any user of the Zcash blockchain can issue Custom Assets on chain. - The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash blockchain. - Issuing or changing the attributes of a specific Asset should require cryptographic authorization. - The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier. - An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets. -- Every "issuance action" should contain a ``finalize`` boolean that defines whether the specific Custom Asset can have further tokens issued or not. +- Every "issuance action" should contain a :math:`\mathsf{finalize}` boolean that defines whether the specific Custom Asset can have further tokens issued or not. Specification: Issuance Keys and Issuance Authorization Signature Scheme @@ -82,11 +82,11 @@ Specification: Issuance Keys and Issuance Authorization Signature Scheme The ZSA Protocol adds the following three keys to the key components [#protocol-addressesandkeys]_: -1. The issuance master key, denoted as :math:`\mathsf{sk}_{\mathsf{iss}}`, as the name suggests, is the master key that is used to derive the other two keys. +1. The issuance derivation key, denoted as :math:`\mathsf{idk}`, as the name suggests, is the key that is used to derive the other two keys. -2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as ``isk``. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. +2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. -3. The issuance validating key, denoted as ``ik``, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. +3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer. The relations between these keys are shown in the following diagram: @@ -107,59 +107,59 @@ Specifically, we instantiate :math:`\mathsf{IssueAuthSig}` as :math:`\mathsf{Red Issuance Key Derivation ----------------------- -The issuance master key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_. +The issuance derivation key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_. -Issuance master key derivation for hierarchical deterministic wallets -````````````````````````````````````````````````````````````````````` +Issuance derivation key generation for hierarchical deterministic wallets +````````````````````````````````````````````````````````````````````````` -The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section. +The issuance derivation key is generated using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section. Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)`. -As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key. +As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance derivation key. We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32. -We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows: +We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance derivation key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows: - :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}`). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. - :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_. - :math:`account`: fixed to index :math:`0`. -Given the *extended issuance master key* :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance master key to be :math:`\mathsf{sk_{iss}} := \mathsf{sk}`. +From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance derivation key to be :math:`\mathsf{idk} := \mathsf{sk}`. Derivation of issuance authorizing key and issuance validating key `````````````````````````````````````````````````````````````````` -The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below. +The issuance authorizing key and issuance validating key are derived from the issuance derivation key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below. -- The issuance authorizing key is derived from the issuance master key, :math:`\mathsf{sk}_{\mathsf{iss}}`, as a private signature key: +- The issuance authorizing key is derived from the issuance derivation key, :math:`\mathsf{idk}`, as a private signature key. The function :math:`\mathsf{PRF^{expand}_{idk}}` is as defined in the Zcash protocol specification [#protocol-abstractprfs]_: -.. math:: \mathtt{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{sk}_{\mathsf{iss}} ) +.. math:: \mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{idk}}([\mathtt{0x0a}]) ) -- The issuance validating key is derived from the issuance authorizing key, :math:`\mathtt{isk}`, as a public verification key: +- The issuance validating key is derived from the issuance authorizing key, :math:`\mathsf{isk}`, as a public verification key: -.. math:: \mathtt{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathtt{isk}) +.. math:: \mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk}) This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe. Specification: Asset Identifier =============================== -For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathtt{ik}, \mathtt{assetDesc})`, where ``ik`` is the issuance key and ``assetDesc`` is a byte string. +For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. Let -- ``assetDesc`` be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. -- ``ik`` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. +- :math:`\mathsf{asset\_desc}` be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. +- :math:`\mathsf{ik}` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`, where -- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathtt{ik}, \mathtt{assetDesc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathtt{ik}) || \mathtt{assetDesc}\!`. +- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`. Define :math:`\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`, where @@ -184,7 +184,7 @@ Specification: Global Issuance State Issuance requires the following additions to the global state defined at block boundaries: -- ``finalized_assets``, a set of :math:`\mathsf{AssetDigest}` that have been finalized (i.e.: the ``finalize`` flag has been set to ``1`` in some issuance transaction preceding the block boundary). +- :math:`\mathsf{previously\_finalized}`, a set of :math:`\mathsf{AssetId}` that have been finalized (i.e.: the :math:`\mathsf{finalize}` flag has been set to :math:`1` in some issuance transaction preceding the block boundary). Specification: Issuance Action, Issuance Bundle and Issuance Protocol @@ -193,24 +193,22 @@ Specification: Issuance Action, Issuance Bundle and Issuance Protocol Issuance Action Description --------------------------- -An issuance action, ``IssueAction``, is the instance of issuing a specific custom Asset, and contains the following fields: +An issuance action, ``IssueAction``, is the instance of issuing a specific Custom Asset, and contains the following fields: -- ``assetDescSize``: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. -- ``assetDesc``: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. +- :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. +- :math:`\mathsf{asset\_desc}`: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. - ``vNotes``: an array of ``Note`` containing the unencrypted output notes of the recipients of the Asset. -- ``flagsIssuance``: a byte that stores the ``finalize`` boolean that defines whether the issuance of that specific Custom Asset is finalized or not +- ``flagsIssuance``: a byte that stores the :math:`\mathsf{finalize}` boolean that defines whether the issuance of that specific Custom Asset is finalized or not. -An asset's :math:`\mathsf{AssetDigest}` is added to the ``finalized_assets`` set after a block that contains any issuance transaction for that asset with ``finalize = 1``. It then cannot be removed from this set. -For Assets with :math:`\mathsf{AssetDigest} \in \mathtt{finalized\_assets}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. -For Assets with :math:`\mathsf{AssetDigest} \not\in \mathtt{finalized\_assets}`, new issuance actions can be issued in future transactions. -These must use the same Asset description, ``assetDesc``, and can either maintain ``finalize = 0`` or change it to ``finalize = 1``, denoting that this Custom Asset cannot be issued after the containing block. +An asset's :math:`\mathsf{AssetDigest}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with :math:`\mathsf{finalize} = 1`. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetDigest} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetDigest} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain :math:`\mathsf{finalize} = 0` or change it to :math:`\mathsf{finalize} = 1`, denoting that this Custom Asset cannot be issued after the containing block. + +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=============================+==========================+===========================================+=====================================================================+ -|``2`` |``assetDescSize`` |``byte`` |The length of the ``assetDesc`` string in bytes. | +|``2`` |``assetDescSize`` |``byte`` |The length of the :math:`\mathsf{asset\_desc}` string in bytes. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``assetDescSize`` |``assetDesc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | +|``assetDescSize`` |``asset_desc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | | | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | | | | |or later. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ @@ -220,7 +218,7 @@ These must use the same Asset description, ``assetDesc``, and can either maintai | | | |where ``noteSize`` is the size, in bytes, of a Note. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``1`` |``flagsIssuance`` |``byte`` |An 8-bit value representing a set of flags. Ordered from LSB to MSB: | -| | | | * ``finalize`` | +| | | | * :math:`\mathsf{finalize}` | | | | | * The remaining bits are set to ``0``. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ @@ -234,9 +232,9 @@ An issuance bundle, ``IssueBundle``, is the aggregate of all the issuance-relate Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields: -- ``ik``: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer. -- ``vIssueActions``: an array of issuance actions, of type `IssueAction`. -- ``issueAuthSig``: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathtt{isk}`, that validates the issuance . +- :math:`\mathsf{ik}`: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer. +- ``vIssueActions``: an array of issuance actions, of type ``IssueAction``. +- :math:`\mathsf{issueAuthSig}`: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathsf{isk}`, that validates the issuance . The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_. @@ -260,10 +258,10 @@ The issuer program performs the following operations For all actions ``IssueAction``: -- encode ``assetDesc`` as a UTF-8 byte string of size up to 512. -- compute :math:`\mathsf{AssetDigest}` from the issuance validating key ``ik`` and ``assetDesc`` as decribed in the `Specification: Asset Identifier`_ section. +- encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512. +- compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section. - compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section. -- set the ``finalize`` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``). +- set the :math:`\mathsf{finalize}` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set :math:`\mathsf{finalize} = 0`, otherwise set :math:`\mathsf{finalize} = 1`) - For each recipient :math:`i`: - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`. @@ -272,9 +270,9 @@ For all actions ``IssueAction``: For the ``IssueBundle``: -- encode the ``vIssueActions`` vector. -- encode the ``ik`` as 32 byte-string. -- sign the ``SIGHASH`` of the transaction with the issuance authorizing key, :math:`\mathtt{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle. +- encode the ``vIssueActions`` vector +- encode the :math:`\mathsf{ik}` as 32 byte-string +- sign the SIGHASH transaction hash with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle. **Note:** that the commitment is not included in the ``IssuanceAction`` itself. As explained below, it is computed later by the validators and added to the note commitment tree. @@ -285,22 +283,22 @@ Specification: Consensus Rule Changes For the ``IssueBundle``: -- Verify the RedPallas-based issuance authorization signature on ``SIGHASH``, ``issueAuthSig``, is verified by invoking :math:`\mathsf{issueAuthSig.VerifySig}(\mathtt{ik}, \mathtt{SIGHASH})`. +- Verify the RedPallas-based issuance authorization signature on the SIGHASH transaction hash, :math:`\mathsf{SigHash}`, :math:`\mathsf{issueAuthSig}`, is verified by invoking :math:`\mathsf{issueAuthSig.VerifySig(ik, SigHash)}` For each ``IssueAction`` in ``IssueBundle``: - check that :math:`0 < \mathtt{assetDescSize} <= 512`. -- check that :math:`\mathtt{assetDesc}` is a string of length :math:`\mathtt{assetDescSize}` bytes. +- check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathtt{assetDescSize}` bytes. -- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key ``ik`` and ``assetDesc`` as described in the `Specification: Asset Identifier`_ section. -- check that the :math:`\mathsf{AssetDigest}` does not exist in the ``finalized_assets`` set in the global state. +- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Specification: Asset Identifier`_ section. +- check that the :math:`\mathsf{AssetDigest}` does not exist in the :math:`\mathsf{previously\_finalized}` set in the global state. - check that every note in the ``IssueAction`` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`\mathsf{note} = (\mathsf{g_d, pk_d, v, \rho, rseed, AssetBase})`. If all of the above checks pass, do the following: - For each note, compute the note commitment as :math:`\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}` as defined in the Note Structure and Commitment section of ZIP 226 [#zip-0226-notestructure]_ and - Add :math:`\mathsf{cm}` to the Merkle tree of note commitments. -- If ``finalize = 1``, add :math:`\mathsf{AssetDigest}` to the ``finalized_assets`` set immediately after the block in which this transaction occurs. +- If :math:`\mathsf{finalize} = 1`, add :math:`\mathsf{AssetDigest}` to the :math:`\mathsf{previously\_finalized}` set immediately after the block in which this transaction occurs. - (Replay Protection) If issue bundle is present, the fees MUST be greater than zero. @@ -311,34 +309,34 @@ The following is a list of rationale for different decisions made in the proposa - The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools. - The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”. -- The ``assetDesc`` is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: +- The :math:`\mathsf{asset\_desc}` is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: - links for storage such as for NFTs. - metadata for Assets, encoded in any format. - bridging information for Wrapped Assets (chain of origin, issuer name, etc) - information to be committed by the issuer, though not enforceable by the protocol. -- We require a check whether the ``finalize`` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the ``finalized_assets`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. -- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the ``SIGHASH`` would be computed solely based on the issue bundle. A duplicate bundle would have the same ``SIGHASH``, potentially allowing for a replay attack. +- We require a check whether the :math:`\mathsf{finalize}` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the :math:`\mathsf{previously\_finalized}`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. +- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack. Concrete Applications --------------------- **Asset Features** -- By using the ``finalize`` boolean and the burning mechanism defined in [#zip-0226]_, issuers can control the supply production of any Asset associated to their issuer keys. For example, +- By using the :math:`\mathsf{finalize}` boolean and the burning mechanism defined in [#zip-0226]_, issuers can control the supply production of any Asset associated to their issuer keys. For example, - - by setting ``finalize = 1`` from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed. + - by setting :math:`\mathsf{finalize} = 1` from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed. - Issuers can also stop the existing supply production of any Asset associated to their issuer keys. This could be done by - - issuing a last set of tokens of that specific :math:`\mathsf{AssetId}`, for which ``finalize = 1``, or by + - issuing a last set of tokens of that specific :math:`\mathsf{AssetId}`, for which :math:`\mathsf{finalize} = 1`, or by - issuing a transaction with a single note in the issuance action pertaining to that :math:`\mathsf{AssetId}`, where the note will contain a ``value = 0``. This can be used for application-specific purposes (NFT collections) or for security purposes to revoke the Asset issuance (see Security and Privacy Considerations). - - Note in the above cases, that the setting of the ``finalize`` flag will take effect at the block boundary, that is, after all the transactions in the block. + - Note in the above cases, that the setting of the :math:`\mathsf{finalize}` flag will take effect at the block boundary, that is, after all the transactions in the block. - The issuance and burn mechanisms can be used in conjunction to determine the supply of Assets on the Zcash ecosystem. This allows for the bridging of Assets defined on other chains. -- Furthermore, NFT issuance is enabled by issuing in a single bundle several issuance actions, where each :math:`\mathsf{AssetId}` corresponds to ``value = 1`` at the fundamental unit level. Issuers and users should make sure that ``finalize = 1`` for each of the actions in this scenario. +- Furthermore, NFT issuance is enabled by issuing in a single bundle several issuance actions, where each :math:`\mathsf{AssetId}` corresponds to ``value = 1`` at the fundamental unit level. Issuers and users should make sure that :math:`\mathsf{finalize} = 1` for each of the actions in this scenario. @@ -429,7 +427,7 @@ T.5a.iii: flagsIssuance ''''''''''''''''''''''' An 8-bit value representing a set of flags. Ordered from LSB to MSB: -- ``finalize`` +- :math:`\mathsf{finalize}` - The remaining bits are set to `0`. @@ -513,9 +511,9 @@ Security and Privacy Considerations Issuance Key Compromise ----------------------- -The design of this protocol does not currently allow for a rotation of the issuance validating key that would allow for replacing the key of a specific Asset (see `Future Work`_). In case of compromise, the following actions are recommended: +The design of this protocol does not currently allow for rotation of the issuance validating key that would allow for replacing the key of a specific Asset. In case of compromise, the following actions are recommended: -- If an issuance validating key is compromised, the ``finalize`` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`. +- If an issuance validating key is compromised, the :math:`\mathsf{finalize}` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`. Bridging Assets --------------- @@ -535,10 +533,6 @@ Fee Structures The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b [#zip-0317b]_. -Future Work ------------ - -In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying ``ik`` of a given Asset, in case the original one was compromised, without having to change the Asset Identifier altogether. Test Vectors ============ @@ -577,6 +571,7 @@ References .. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ .. [#protocol-addressesandkeys] `Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys `_ .. [#protocol-concretegrouphashpallasandvesta] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta `_ +.. [#protocol-abstractprfs] `Zcash Protocol Specification, Version 2022.3.8. Section 4.1.2: Pseudo Random Functions `_ .. [#protocol-orchardkeycomponents] `Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components `_ .. [#protocol-spendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard) `_ .. [#protocol-concretespendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard) `_ From 5d264015d6dd8ee2c715194c95ce3844a8af9e53 Mon Sep 17 00:00:00 2001 From: Constance Beguier Date: Mon, 24 Jul 2023 16:53:58 +0200 Subject: [PATCH 22/42] Update with circuit changes (#31) - Add the new nullifier equation for split notes - Add a link to Orchard circuit document - Add is_native_asset auxiliary witness - Remove constraint (split_flag=1) => (v_old != 0) - Add constraint (split_flag=1) => (is_native_asset=0) --- zip-0226.html | 98 ++++++++++++++++++++++++++++----------------------- zip-0226.rst | 27 +++++++++----- 2 files changed, 73 insertions(+), 52 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index ed8fa975c..c5a378a95 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -154,7 +154,7 @@ \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) , differs from the Orchard note commitment \(\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 24 allows us to add the Asset Base as a final recursive step, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification.

    + 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 24 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 23. ZSA note commitments will therefore be added to the same Orchard Note Commitment Tree. In essence, we have:

    \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} \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.

    @@ -265,8 +265,19 @@
  • The Split Input note could be a different unspent note containing the same Asset Base (note that the note will not actually be spent).
  • 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).
    • +

    For Split Notes, the nullifier is generated as follows

    +
    \(\mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\rho^{\mathsf{old}}) + \psi') \bmod q_{\mathbb{P}}] \mathcal{K}^\mathsf{Orchard} + \mathsf{cm^{old}} + \mathcal{L}^\mathsf{Orchard})\)
    +

    where + \(\psi'\) + is sampled uniformly at random on + \(\mathbb{F}_{q_{\mathbb{P}}}\) + , + \(\mathcal{K}^{\mathsf{Orchard}}\) + is the Orchard Nullifier Base as defined in 18, and + \(\mathcal{L}^{\mathsf{Orchard}} := \mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard", "L")}\) + .

    Rationale for Split Notes

    -

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

    +

    In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

    The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

    Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the \(\mathsf{split\_flag}\) @@ -275,7 +286,8 @@

    Circuit Statement

    -

    Every ZSA Action statement is closely similar to the Orchard Action statement 27, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    +

    Every ZSA Action statement is closely similar to the Orchard Action statement 27, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

    +

    All modifications in the Circuit are detailed in 33.

    Asset Base Equality

    The following constraints must be added to ensure that the input and output note are of the same \(\mathsf{AssetBase}\) @@ -284,17 +296,28 @@

  • The Asset Base, \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) , for the note is witnessed once, as an auxiliary input.
    • -
  • In the Old note commitment integrity constraint in the Orchard Action statement 27, +
  • In the Old note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) .
    • -
  • In the New note commitment integrity constraint in the Orchard Action statement 27, +
  • In the New note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) .
    • +

    To make the evaluation of the note commitment easier, we add a boolean + \(\mathsf{is\_native\_asset}\) + as an auxiliary witness. We also add some constraints to verify that this variable is activated (i.e. + \(\mathsf{is\_native\_asset} = 1\) + ) if the Asset Base is equal to + \(\mathcal{V}^\mathsf{Orchard}\) + and this variable is not activated (i.e. + \(\mathsf{is\_native\_asset} = 0\) + ) if the Asset Base is not equal to + \(\mathcal{V}^\mathsf{Orchard}\) + .

    Value Commitment Correctness

    The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base:

    @@ -345,8 +368,8 @@
  • If \(\mathsf{split\_flag} = 1\) then constrain - \(\mathsf{v^{old}} \neq 0\) - .
    • + \(\mathsf{is\_native\_asset} = 0\) + because split notes are only available for Custom Assets. @@ -356,46 +379,25 @@
    The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes):
      -
    • Check that (path, pos) is a valid Merkle path of depth +
    • Check for all notes except dummy notes that (path, pos) is a valid Merkle path of depth \(\mathsf{MerkleDepth^Orchard}\) , from \(\mathsf{cm^{old}}\) to the anchor \(\mathsf{rt^{Orchard}}\) .
      • +
    • The new constraint is + \(\underbrace{(\mathsf{v^{old}} = 0 \land \mathsf{is\_native\_asset} = 1)}_\text{It is a dummy note} \lor \underbrace{(\mathsf{Valid\,Merkle\,Path})}_\text{The Merkle Path is valid}\) + .
    -
  • -
    -
    The Nullifier Integrity will be changed to prevent the identification of notes
    -
    -
      -
    • Replace the - \(\psi_{old}\) - value with a generic - \(\psi'\) - as - \(\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})\) -
      • -
    • if - \(\mathsf{split\_flag} = 0\) - then constrain - \(\psi' = \psi^{old}\) - . (Otherwise - \(\psi'\) - should be sampled uniformly at random on - \(\mathbb{F}_{q_{\mathbb{P}}}\) - .)
      • -
    -
    -
    -
    • +
  • The Nullifier Integrity will be changed to prevent the identification of notes as defined in the Split Notes section.

    • Backwards Compatibility with ZEC Notes

    -

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 16. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    +

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 16. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    @@ -469,7 +471,7 @@

    ZSA Transaction Structure

    -

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    +

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    2324 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    @@ -555,7 +557,7 @@

    ZSA Orchard Action Description Encoding

    -

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 29. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    +

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 29. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    @@ -644,7 +646,7 @@

    TxId Digest

    -

    The transaction digest algorithm defined in ZIP 244 11 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 11 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

    A BLAKE2b-256 hash of the following values

    T.1: header_digest       (32-byte hash output)
@@ -652,7 +654,7 @@
 T.3: sapling_digest      (32-byte hash output)
 T.4: orchard_digest      (32-byte hash output)  [UPDATED FOR ZSA]
 T.5: issuance_digest     (32-byte hash output)  [ADDED FOR ZSA]
    -

    The personalization field remains the same as in ZIP 244 11.

    +

    The personalization field remains the same as in ZIP 244 11.

    T.4: orchard_digest

    When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values

    T.4a: orchard_actions_compact_digest      (32-byte hash output)          [UPDATED FOR ZSA]
@@ -662,7 +664,7 @@
 T.4e: valueBalanceOrchard                 (64-bit signed little-endian)
 T.4f: anchorOrchard                       (32 bytes)
    T.4a: orchard_actions_compact_digest
    -

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 12 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 12 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4a.i  : nullifier            (field encoding bytes)
 T.4a.ii : cmx                  (field encoding bytes)
 T.4a.iii: ephemeralKey         (field encoding bytes)
@@ -677,7 +679,7 @@
                         
    "ZTxIdOrcActMHash"
    T.4c: orchard_actions_noncompact_digest
    -

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 12 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 12 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4d.i  : cv                    (field encoding bytes)
 T.4d.ii : rk                    (field encoding bytes)
 T.4d.iii: encCiphertext[596..]  (post-memo suffix of field encoding)  [UPDATED FOR ZSA]
@@ -687,12 +689,12 @@

    T.5: issuance_digest

    -

    The details of the computation of this value are in ZIP 227 8.

    +

    The details of the computation of this value are in ZIP 227 8.

    Signature Digest and Authorizing Data Commitment

    -

    The details of the changes to these algorithms are in ZIP 227 9 10.

    +

    The details of the changes to these algorithms are in ZIP 227 9 10.

    Security and Privacy Considerations

      @@ -708,7 +710,7 @@

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    Backward Compatibility

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this:

    @@ -718,7 +720,7 @@ value as well.
  • The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade.
  • The value commitment is abstracted to allow for the value base-point as a variable private input to the proof.
    • -
  • The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes.
    • +
  • The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include split input notes and will not include dummy input notes.

    • Deployment

    @@ -995,6 +997,14 @@
    + + + + + + + +
    33Modifications to the Orchard circuit for the ZSA Protocol
    diff --git a/zip-0226.rst b/zip-0226.rst index 8c49827e7..2f6bdce34 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -127,7 +127,7 @@ 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. -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, and hence keep a single instance of the Sinsemilla hash function in the circuit for the note commitment verification. +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: @@ -208,6 +208,12 @@ Wallets and other clients have to choose from the following to ensure the Asset 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). +For Split Notes, the nullifier is generated as follows + +.. math:: \mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\rho^{\mathsf{old}}) + \psi') \bmod q_{\mathbb{P}}] \mathcal{K}^\mathsf{Orchard} + \mathsf{cm^{old}} + \mathcal{L}^\mathsf{Orchard}) + +where :math:`\psi'` is sampled uniformly at random on :math:`\mathbb{F}_{q_{\mathbb{P}}}`, :math:`\mathcal{K}^{\mathsf{Orchard}}` is the Orchard Nullifier Base as defined in [#protocol-commitmentsandnullifiers]_, and :math:`\mathcal{L}^{\mathsf{Orchard}} := \mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard", "L")}`. + Rationale for Split Notes ````````````````````````` @@ -226,6 +232,8 @@ Circuit Statement Every *ZSA Action statement* is closely similar to the Orchard Action statement [#protocol-actionstatement]_, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below. +All modifications in the Circuit are detailed in [#circuit-modifications]_. + Asset Base Equality ``````````````````` @@ -235,6 +243,8 @@ The following constraints must be added to ensure that the input and output note - In the Old note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. - In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. +To make the evaluation of the note commitment easier, we add a boolean :math:`\mathsf{is\_native\_asset}` as an auxiliary witness. We also add some constraints to verify that this variable is activated (i.e. :math:`\mathsf{is\_native\_asset} = 1`) if the Asset Base is equal to :math:`\mathcal{V}^\mathsf{Orchard}` and this variable is not activated (i.e. :math:`\mathsf{is\_native\_asset} = 0`) if the Asset Base is not equal to :math:`\mathcal{V}^\mathsf{Orchard}`. + Value Commitment Correctness ```````````````````````````` @@ -252,12 +262,11 @@ Senders must not be able to change the Asset Base for the output note in a Split - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}` - Add a boolean :math:`\mathsf{split\_flag}` variable as an auxiliary witness. This variable is to be activated :math:`\mathsf{split\_flag} = 1` if the Action in question has a Split Input and :math:`\mathsf{split\_flag} = 0` if the Action is actually spending an input note: - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{v}' = 0` otherwise constrain :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. - - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{v^{old}} \neq 0`. + - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{is\_native\_asset} = 0` because split notes are only available for Custom Assets. - The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes): - - Check that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^{old}}` to the anchor :math:`\mathsf{rt^{Orchard}}`. -- The Nullifier Integrity will be changed to prevent the identification of notes - - Replace the :math:`\psi_{old}` value with a generic :math:`\psi'` as :math:`\mathsf{nf_{old}} = \mathsf{DeriveNullifier_{nk}}(\rho^\mathsf{old}, \psi', \mathsf{cm^{old}})` - - if :math:`\mathsf{split\_flag} = 0` then constrain :math:`\psi' = \psi^{old}`. (Otherwise :math:`\psi'` should be sampled uniformly at random on :math:`\mathbb{F}_{q_{\mathbb{P}}}`.) + - Check for all notes except dummy notes that (path, pos) is a valid Merkle path of depth :math:`\mathsf{MerkleDepth^Orchard}`, from :math:`\mathsf{cm^{old}}` to the anchor :math:`\mathsf{rt^{Orchard}}`. + - The new constraint is :math:`\underbrace{(\mathsf{v^{old}} = 0 \land \mathsf{is\_native\_asset} = 1)}_\text{It is a dummy note} \lor \underbrace{(\mathsf{Valid\,Merkle\,Path})}_\text{The Merkle Path is valid}`. +- The Nullifier Integrity will be changed to prevent the identification of notes as defined in the `Split Notes`_ section. Backwards Compatibility with ZEC Notes `````````````````````````````````````` @@ -509,7 +518,7 @@ In order to have backward compatibility with the ZEC notes, we have designed the - Note commitments for ZEC notes will remain the same, while note commitments for Custom Assets will be computed taking into account the :math:`\mathsf{AssetBase}` value as well. - The existing Orchard shielded pool will continue to be used for the new ZSA notes post the upgrade. - The value commitment is abstracted to allow for the value base-point as a variable private input to the proof. -- The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include both dummy and split input notes. +- The ZEC-based Actions will still include dummy input notes, whereas the ZSA-based Actions will include split input notes and will not include dummy input notes. Deployment ----------- @@ -562,4 +571,6 @@ References .. [#protocol-actionencodingandconsensus] `Zcash Protocol Specification, Version 2022.3.8. Section 7.5: Action Description Encoding and Consensus `_ .. [#initial-zsa-issue] `User-Defined Assets and Wrapped Assets `_ .. [#generalized-value-commitments] `Comment on Generalized Value Commitments `_ -.. [#zip-0317b] `ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs `_ \ No newline at end of file +.. [#zip-0317b] `ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs `_ +.. [#circuit-modifications] `Modifications to the Orchard circuit for the ZSA Protocol `_ + From 7444c86f33d5328ad2a3ec8a83d19b90b8a583c8 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 15 Aug 2023 01:17:07 +0530 Subject: [PATCH 23/42] Apply suggestions from ZIP review These are the changes to the rst files based on ZIP editors typographical changes. Co-authored-by: Deirdre Connolly --- zip-0226.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zip-0226.rst b/zip-0226.rst index 2f6bdce34..1255e6af5 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -177,7 +177,7 @@ 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 verbosity and clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume :math:`m` Actions related to ZEC and :math:`n-m` actions related to Custom Assets, where :math:`m \in [0,n]`. Furthermore, we assume for simplicity that given a tuple of :math:`n` Actions in a transfer, the :math:`m` Actions related to ZEC are first (in practice Actions could be in whatever order). +We assume :math:`n` Actions in a transfer. Out of these :math:`n` Actions, we further distinguish (for the sake of verbosity and clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume :math:`m` Actions related to ZEC and :math:`n-m` Actions related to Custom Assets, where :math:`m \in [0,n]`. Furthermore, we assume for simplicity that given a tuple of :math:`n` Actions in a transfer, the :math:`m` Actions related to ZEC are first (in practice Actions could be in whatever order). The value balance verification is equivalent to: @@ -185,7 +185,7 @@ The value balance verification is equivalent to: 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. As such, for a correctly constructed transaction, we MUST get :math:`\mathsf{(\sum_{j=m+1}^{n} v_j^{net}) = 0}`, and thus be left with :math:`\mathsf{\sum_{j=m+1}^{n} rcv_{j}^{net}}\mathcal{R}^{\mathsf{Orchard}}` in the expression. If :math:`m=n` (resp. :math:`m=0`), i.e. all Actions relate to ZEC (resp. Custom Assets), then :math:`m+1>n` (resp. :math:`1>m`), and thus the sum :math:`\sum_{j=m+1}^{n}` (resp. :math:`\sum_{i=1}^{m}`) returns the identity element of the group. -So, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is *burnt*, as we will see below in the `burn mechanism`_. +Thus, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded within a regular transaction (as opposed to a *burn*, covered below in the `burn mechanism`_). All Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one value balance published, which corresponds to the ZEC value balance :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. 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 only sum to zero **per Asset Base**, as the Pedersen commitments add up homomorphically only with respect to the same value base point. From ffae569ae267bf25db519a2d9e3f9d80ee3d020c Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Tue, 15 Aug 2023 01:26:41 +0530 Subject: [PATCH 24/42] making further ZIP editor suggested changes, and updating the html files to match --- zip-0226.html | 8 ++++---- zip-0226.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index c5a378a95..16020be58 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -211,11 +211,11 @@ \(n\) Actions in a transfer. Out of these \(n\) - Actions, we further distinguish (for the sake of verbosity and clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume + Actions, we further distinguish (for the sake of clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume \(m\) Actions related to ZEC and \(n-m\) - actions related to Custom Assets, where + Actions related to Custom Assets, where \(m \in [0,n]\) . Furthermore, we assume for simplicity that given a tuple of \(n\) @@ -241,9 +241,9 @@ (resp. \(\sum_{i=1}^{m}\) ) returns the identity element of the group.

    -

    So, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded, so all Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one Asset of value balance published, that of ZEC, +

    Thus, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded within a regular transaction (as opposed to a burn, covered below in the burn mechanism). All Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one value balance published, which corresponds to the ZEC value balance \(\mathsf{v^{balanceOrchard}}\) - . No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. The only exception to this is in the case that an Asset is burnt, as we will see below in the burn mechanism.

    + . No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden.

    As in the Orchard protocol, the binding signature verification key, \(\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 only sum to zero per Asset Base, as the Pedersen commitments add up homomorphically only with respect to the same value base point.

    diff --git a/zip-0226.rst b/zip-0226.rst index 1255e6af5..399b30408 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -177,7 +177,7 @@ 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 verbosity and clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume :math:`m` Actions related to ZEC and :math:`n-m` Actions related to Custom Assets, where :math:`m \in [0,n]`. Furthermore, we assume for simplicity that given a tuple of :math:`n` Actions in a transfer, the :math:`m` Actions related to ZEC are first (in practice Actions could be in whatever order). +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:`m` Actions related to ZEC and :math:`n-m` Actions related to Custom Assets, where :math:`m \in [0,n]`. Furthermore, we assume for simplicity that given a tuple of :math:`n` Actions in a transfer, the :math:`m` Actions related to ZEC are first (in practice Actions could be in whatever order). The value balance verification is equivalent to: From 51d424b8419fc0b1749857403f0dce4375470978 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 5 Sep 2023 16:46:34 +0530 Subject: [PATCH 25/42] Guidelines to wallets regarding representing Assets to clients (#32) This adds to the specification to provide wallets instructions on displaying Asset information to users in an unambiguous way. This addresses [this comment](https://github.com/zcash/zips/pull/680#discussion_r1147019628). --- zip-0226.html | 5 ----- zip-0226.rst | 4 ---- zip-0227.html | 10 ++++++++++ zip-0227.rst | 10 ++++++++++ 4 files changed, 20 insertions(+), 9 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 16020be58..233998b6e 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -701,11 +701,6 @@
  • The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility.
  • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
  • We prevent a potential malleability attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
    • -
  • Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. -
      -
    • One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
      • -
    -

    • Other Considerations

    diff --git a/zip-0226.rst b/zip-0226.rst index 399b30408..ee6b1e2ba 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -497,10 +497,6 @@ Security and Privacy Considerations - The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility. - When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design. - We prevent a potential malleability attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state. -- Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are the use of a petname system or a list of well-known Assets. - - - One proposal for a petname system for the zcashd wallet is the use of an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. - Other Considerations ==================== diff --git a/zip-0227.html b/zip-0227.html index 2d7b97173..cd25c4b75 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -223,6 +223,13 @@ (resp. \(\mathsf{Protocol}\) ) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.

    +

    Wallets MUST NOT display just the + \(\mathsf{asset\_desc}\) + string to their users as the name of the Asset. Some possible alternatives include:

    +
      +
    • Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
      • +
    • The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets.
      • +

    Specification: Global Issuance State

    Issuance requires the following additions to the global state defined at block boundaries:

    @@ -670,6 +677,9 @@

    Security and Privacy Considerations

    +

    Displaying Asset Identifier information to users

    +

    Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are provided in the Specification: Asset Identifier section.

    +

    Issuance Key Compromise

    The design of this protocol does not currently allow for rotation of the issuance validating key that would allow for replacing the key of a specific Asset. In case of compromise, the following actions are recommended:

      diff --git a/zip-0227.rst b/zip-0227.rst index b2d2225a5..54b93a5ac 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -179,6 +179,11 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho **Note:** To keep notations light and concise, we may omit :math:`\mathsf{AssetId}` (resp. :math:`\mathsf{Protocol}`) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context. +Wallets MUST NOT display just the :math:`\mathsf{asset\_desc}` string to their users as the name of the Asset. Some possible alternatives include: + +- Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. +- The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets. + Specification: Global Issuance State ==================================== @@ -508,6 +513,11 @@ In the case that the transaction has no Orchard Actions, ``issuance_auth_digest` Security and Privacy Considerations =================================== +Displaying Asset Identifier information to users +------------------------------------------------ + +Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are provided in the `Specification: Asset Identifier`_ section. + Issuance Key Compromise ----------------------- From 5dfad3a7b2796d79c90c75577df78d3c5124ec77 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 5 Sep 2023 16:47:05 +0530 Subject: [PATCH 26/42] Adding explicit assumption for canonical encodings for the Asset Base. (#33) This addresses [this comment](https://github.com/zcash/zips/pull/680#discussion_r1268669667). --- zip-0226.html | 3 ++- zip-0226.rst | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 233998b6e..16e795fee 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -115,7 +115,8 @@ \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) .
    -

    Specifically, we define the note commitment scheme +

    Note that the above assumes a canonical encoding, which is true for the Pallas group, but may not hold for future shielded protocols.

    +

    We define the note commitment scheme \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) as follows:

    \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)
    diff --git a/zip-0226.rst b/zip-0226.rst index ee6b1e2ba..6703ac401 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -90,7 +90,9 @@ where - :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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 non-bottom group element that is not the identity. 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}^{\mathsf{Orchard}})`. -Specifically, we define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows: +Note that the above assumes a canonical encoding, which is true for the Pallas group, but may not hold for future shielded protocols. + +We define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows: .. math:: \mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output} From 7c481037426c3b06c36bef2aa28a63b194025ffa Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Wed, 20 Sep 2023 20:33:47 +0530 Subject: [PATCH 27/42] Burn Mechanism Rearrangement (#35) This rearranges the positioning of the burn mechanism in order to remove duplication of material between the burn mechanism section and the value balance verification section. There is also some simplification of the naming convention for the Asset Base variable. --- zip-0226.html | 238 ++++++++++--------------- zip-0226.rst | 131 ++++++-------- zip-0227-asset-identifier-relation.png | Bin 44943 -> 38462 bytes zip-0227-asset-identifier-relation.svg | 17 +- zip-0227.html | 26 +-- zip-0227.rst | 17 +- 6 files changed, 182 insertions(+), 247 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 16e795fee..79fe43a97 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -46,7 +46,7 @@

    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 \(\mathsf{AssetId}\) . This Asset Identifier maps to an Asset Base - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + \(\mathsf{AssetBase}\) that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 6.

    The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 15 is preserved across Assets (see the Orchard Binding Signature 17), and by extension the balance of an Orchard transaction. That is, the sum of all the \(\mathsf{value^{net}}\) @@ -58,19 +58,11 @@ , in the Homomorphic Pedersen Commitment that derives the value commitment, \(\mathsf{cv^{net}}\) , of the net value in an Orchard Action.

    -

    Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - an auxiliary input to the proof for each Action statement 27, represented already as a point on the Pallas curve. The circuit then should check that the same - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - is used in the old note commitment and the new note commitment 24, and as the base point - \(\mathcal{V}^\mathsf{Orchard}\) - in the value commitment 25. This ensures (1) that the input and output notes are of the same - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - , and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

    +

    Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base an auxiliary input to the proof for each Action statement 27, represented already as a point on the Pallas curve. The circuit then should check that the same Asset Base is used in the old note commitment and the new note commitment 24, and as the base point in the value commitment 25. This ensures (1) that the input and output notes are of the same Asset Base, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

    In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 26 for Custom Assets, as we need to enforce that the - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + \(\mathsf{AssetBase}\) of the output note of that Split Action is the output of a valid - \(\mathsf{ZSAValueBase^{Orchard}}\) + \(\mathsf{ZSAValueBase}\) computation defined in ZIP 227 6.

    Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the \(\mathsf{valueBalance}\) @@ -84,13 +76,9 @@ , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, \(\mathsf{AssetId}\) , the Asset Digest, and the Asset Base ( - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 6.

    -

    This - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - will be the base point of the value commitment for the specific Custom Asset. Note that the - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - of the ZEC Asset will be kept as the original value base point, + \(\mathsf{AssetBase}\) + ) are derived as defined in ZIP 227 6.

    +

    This Asset Base will be the base point of the value commitment for the specific Custom Asset. Note that the Asset Base of the ZEC Asset will be kept as the original value base point, \(\mathcal{V}^\mathsf{Orchard}\) .

    Rationale for Asset Identifiers

    @@ -103,16 +91,16 @@ be the type of a ZSA note, i.e. \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*\) .

    -

    A ZSA note differs from an Orchard note 13 by additionally including the Asset Base, - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) +

    An Orchard ZSA note differs from an Orchard note 13 by additionally including the Asset Base, + \(\mathsf{AssetBase}\) . So a ZSA note is a tuple - \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})\) + \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}})\) , where

    • - \(\mathsf{AssetBase}^{\mathsf{Orchard}} : \mathbb{P}*\) + \(\mathsf{AssetBase} : \mathbb{P}*\) is the unique element of the Pallas group 21 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as - \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase}^{\mathsf{Orchard}})\) + \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase})\) .

    Note that the above assumes a canonical encoding, which is true for the Pallas group, but may not hold for future shielded protocols.

    @@ -126,9 +114,9 @@ \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) are as defined in the Zcash protocol specification 16. This note commitment scheme is instantiated using the Sinsemilla Commitment 24 as follows:

    \(\begin{align} -\mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} +\mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})} :=\begin{cases} -\mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ +\mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\ \mathsf{cm}_{\mathsf{ZSA}} &\text{otherwise} \end{cases} \end{align}\)
    @@ -157,13 +145,13 @@ \(\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 24 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 23. ZSA note commitments will therefore be added to the same Orchard Note Commitment Tree. In essence, we have:

    -
    \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}})} \in \mathsf{NoteCommit^{Orchard}.Output}\)
    +
    \(\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.

    Value Commitment

    -

    In the case of the ZSA protocol, the value of different Asset Identifiers in a given transaction will be committed using a different value base point. The value commitment becomes:

    -
    \(\mathsf{cv^{net}:=ValueCommit^{OrchardZSA}_{rcv}(v^{net}_{AssetId}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}:= \mathsf{[v^{net}_{AssetId}]}\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}} + [\mathsf{rcv}]\mathcal{R}^{\mathsf{Orchard}}\)
    +

    In the case of the Orchard-based ZSA protocol, the value of different Asset Identifiers in a given transaction will be committed using a different value base point. The value commitment becomes:

    +
    \(\mathsf{cv^{net}:=ValueCommit^{OrchardZSA}_{rcv}(\mathsf{AssetBase}_{\mathsf{AssetId}}, v^{net}_{AssetId})}:= \mathsf{[v^{net}_{AssetId}]}\mathsf{AssetBase}_{\mathsf{AssetId}} + [\mathsf{rcv}]\mathcal{R}^{\mathsf{Orchard}}\)

    where \(\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{AssetId}}\) such that @@ -174,17 +162,17 @@ \(\mathsf{AssetId}\) respectively,

    - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + \(\mathsf{AssetBase}_{\mathsf{AssetId}}\) is defined in ZIP 227 6, and

    \(\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}\) , as in the Orchard protocol.

    -

    We define - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}\) +

    For ZEC, we define + \(\mathsf{AssetBase}_{\mathsf{AssetId}} :=\mathcal{V}^{\mathsf{Orchard}}\) so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 4. As such \(\mathsf{ValueCommit^{Orchard}_{rcv}(v)}\) as defined in 4 is used as - \(\mathsf{ValueCommit^{OrchardZSA}_{rcv}(v, \mathcal{V}^{\mathsf{Orchard}})}\) + \(\mathsf{ValueCommit^{OrchardZSA}_{rcv}(\mathcal{V}^{\mathsf{Orchard}}, v)}\) here.

    Rationale for Value Commitment

    The Orchard Protocol uses a Homomorphic Pedersen Commitment 25 to perform the value commitment, with fixed base points @@ -195,15 +183,52 @@

    The use of different value base points for different Assets enables the final balance of the transaction to be securely computed, such that each Asset Identifier is balanced independently, which is required as different Assets are not meant to be mutually fungible.

    +

    Burn Mechanism

    +

    The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.

    +

    The sender includes a + \(\mathsf{v_{AssetId}}\) + variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the ZSA Transaction Structure, this is separate from the regular + \(\mathsf{valueBalance^Orchard}\) + that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

    +

    For every Custom Asset that is burnt, we add to the + \(\mathsf{assetBurn}\) + vector the tuple + \((\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})\) + such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.

    +
    \(\mathsf{assetBurn} = \{ (\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})\ |\ \forall\ \mathsf{AssetBase}_{\mathsf{AssetId}}\ \textit{s.t.}\ \mathsf{v_{AssetId}} \neq 0 \}\)
    +

    We denote by + \(L\) + the cardinality of the + \(\mathsf{assetBurn}\) + set.

    +

    Additional Consensus Rules

    +
      +
    1. We require that for every + \((\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase}_{\mathsf{AssetId}} \neq \mathcal{V}^{\mathsf{Orchard}}\) + . That is, ZEC or TAZ is not allowed to be burnt.
      2. +
    2. We require that for every + \((\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v_{AssetId}} \neq 0\) + .
      3. +
    3. We require that there be no duplication of Custom Assets in the + \(\mathsf{assetBurn}\) + set. That is, every + \(\mathsf{AssetBase}_{\mathsf{AssetId}}\) + has at most one entry in + \(\mathsf{assetBurn}\) + .
      4. +
    +

    Note: Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

    +
    +

    Value Balance Verification

    -

    In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol 17.

    +

    In order to verify the balance of the different Assets, the verifier MUST perform a similar process as for the Orchard protocol 17, with the addition of the burn information.

    For a total of \(n\) Actions in a transfer, the prover MUST still sign the SIGHASH transaction hash using the binding signature key \(\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_{i}\) .

    -

    The verifier MUST compute

    -
    \(\mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{\mathsf{Orchard}})}\)
    +

    The verifier MUST compute the value balance verification equation:

    +
    \(\mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(\mathcal{V}^{\mathsf{Orchard}}, v^{balanceOrchard})} - \sum_{(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{AssetBase}, \mathsf{v})\)

    After computing \(\mathsf{bvk}\) , the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash.

    @@ -212,42 +237,36 @@ \(n\) Actions in a transfer. Out of these \(n\) - Actions, we further distinguish (for the sake of clarity) between Actions related to ZEC and Actions related to Custom Assets. We assume - \(m\) - Actions related to ZEC and - \(n-m\) - Actions related to Custom Assets, where - \(m \in [0,n]\) - . Furthermore, we assume for simplicity that given a tuple of - \(n\) - Actions in a transfer, the - \(m\) - Actions related to ZEC are first (in practice Actions could be in whatever order).

    -

    The value balance verification is equivalent to:

    -
    \(\mathsf{bvk} = (\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_j) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{Orchard})}\)
    -

    This equation contains the balance check of the Orchard protocol 17. With ZSA, transfer Actions for Custom Assets MUST also be balanced across asset bases. As such, for a correctly constructed transaction, we MUST get - \(\mathsf{(\sum_{j=m+1}^{n} v_j^{net}) = 0}\) - , and thus be left with - \(\mathsf{\sum_{j=m+1}^{n} rcv_{j}^{net}}\mathcal{R}^{\mathsf{Orchard}}\) - in the expression. If - \(m=n\) - (resp. - \(m=0\) - ), i.e. all Actions relate to ZEC (resp. Custom Assets), then - \(m+1>n\) - (resp. - \(1>m\) - ), and thus the sum - \(\sum_{j=m+1}^{n}\) - (resp. - \(\sum_{i=1}^{m}\) - ) returns the identity element of the group.

    -

    Thus, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded within a regular transaction (as opposed to a burn, covered below in the burn mechanism). All Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one value balance published, which corresponds to the ZEC value balance + Actions, we further distinguish (for the sake of clarity) between Actions related to ZEC and Actions related to Custom Assets. We denote by + \(S_{\mathsf{ZEC}} \subseteq [1,n]\) + the set of indices of Actions that are related to ZEC, and by + \(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:

    +
    \(((\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 17. 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 + \(\mathsf{assetBurn}\) + set. As such, for a correctly constructed transaction, we will get + \(\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 + \(\mathsf{assetBurn}\) + vector. Therefore, the relationship between + \(\mathsf{bvk}\) + and + \(\mathsf{bsk}\) + will hold if and only if, per Custom Asset, the sum of the net values of the relevant Actions equals the corresponding + \(\mathsf{v}_k\) + value (or equals + \(0\) + if that Asset is not in the + \(\mathsf{assetBurn}\) + set), and for ZEC, the sum of the net values of the relevant Actions equals the \(\mathsf{v^{balanceOrchard}}\) - . No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden.

    + value.

    As in the Orchard protocol, the binding signature verification key, \(\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 only sum to zero per Asset Base, as the Pedersen commitments add up homomorphically only with respect to the same value base point.

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

    Split Notes

    @@ -295,17 +314,17 @@ :

    • The Asset Base, - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + \(\mathsf{AssetBase}_{\mathsf{AssetId}}\) , for the note is witnessed once, as an auxiliary input.
    • In the Old note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) is replaced with - \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}_{\mathsf{AssetId}})}\) .
    • In the New note commitment integrity constraint in the Orchard Action statement 27, \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) is replaced with - \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}_{\mathsf{AssetId}})}\) .

    To make the evaluation of the note commitment easier, we add a boolean @@ -327,7 +346,7 @@ \(\mathsf{cv}\) , is replaced with a variable-base multiplication between the two.

  • The witness to the value base point (as defined in the asset base equation) is the auxiliary input - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) + \(\mathsf{AssetBase}_{\mathsf{AssetId}}\) .
    • @@ -342,7 +361,7 @@
  • Replace the input note value by a generic value, \(\mathsf{v}'\) , as - \(\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}\) + \(\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(\mathsf{AssetBase}_{\mathsf{AssetId}}, v’ - v^new)}\)
    • @@ -402,75 +421,6 @@ -

    Burn Mechanism

    -

    The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.

    -

    The sender includes a - \(\mathsf{v^{AssetBase}}\) - variable for every Asset Identifier that is being burnt. As we will show in the ZSA Transaction Structure, this is separate from the regular - \(\mathsf{valueBalance^Orchard}\) - that is the default transparent value for the ZEC Asset.

    -

    For every Custom Asset that is burnt, we add to the - \(\mathsf{assetBurn}\) - vector the tuple - \((\mathsf{AssetBase},\mathsf{v^{AssetBase}})\) - such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.

    -
    \(\mathsf{assetBurn} = \{ (\mathsf{AssetBase},\mathsf{v^{AssetBase}})\ |\ \forall\ \mathsf{AssetBase}\ \textit{s.t.}\ \mathsf{v^{AssetBase}} \neq 0 \}\)
    -

    We denote by - \(L\) - the cardinality of the - \(\mathsf{assetBurn}\) - set.

    -

    The value balances for each Asset Identifier in - \(\mathsf{assetBurn}\) - represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

    -

    The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective - \(\mathsf{AssetBase}\) - as the value base point of the Pedersen Commitment.

    -

    This is done as follows:

    -
    \(\mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v^{balanceOrchard}}, \mathcal{V}^{\mathsf{Orchard}}) - \sum_{k=1}^{L} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v}_{k}, \mathsf{AssetBase}_{k})\)
    -

    After computing - \(\mathsf{bvk}\) - , the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash.

    -

    In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt.

    -

    Burn Mechanism Consensus Rules

    -
      -
    1. We require that - \(\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}\) - . That is, ZEC or TAZ is not allowed to be burnt.
      2. -
    2. We require that for every - \(\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v^{AssetBase}} \neq 0\) - .
      3. -
    3. We require that there be no duplication of Custom Assets in the - \(\mathsf{assetBurn}\) - set. That is, every - \(\mathsf{AssetBase}\) - has at most one entry in - \(\mathsf{assetBurn}\) - .
      4. -
    -

    Note: Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

    -

    Rationale for Burn Mechanism

    -

    As for the value balance verification, we assume - \(n\) - Actions, - \(m\) - of which are related to ZEC and the remaining - \(n-m\) - Actions related to Custom Assets.

    -

    The burn mechanism verification is equivalent to:

    -
    \(\mathsf{bvk} = ((\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_{j})) - ([\mathsf{v^{balanceOrchard}}]\mathcal{V}^{\mathsf{Orchard}} + [0]\mathcal{R}^{\mathsf{Orchard}}) - (\sum_{k=1}^{L} [\mathsf{v}_{k}]\mathsf{AssetBase}_{k} + [0]\mathcal{R}^{\mathsf{Orchard}})\)
    -

    The relationship between - \(\mathsf{bvk}\) - and - \(\mathsf{bsk}\) - will hold only if the sum of the net values of the Actions equals the sum of - \(\mathsf{v^{balanceOrchard}}\) - and the - \(\mathsf{v}_k\) - values, across base points (i.e. Asset Base).

    -
    -
    -

    ZSA Transaction Structure

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    @@ -631,7 +581,7 @@ diff --git a/zip-0226.rst b/zip-0226.rst index 6703ac401..d3bb7263d 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -49,16 +49,16 @@ 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}`. -This Asset Identifier maps to an Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` that is stored in Orchard-based ZSA notes. +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]_. The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description [#protocol-actions]_ is preserved across Assets (see the Orchard Binding Signature [#protocol-binding]_), and by extension the balance of an Orchard transaction. That is, the sum of all the :math:`\mathsf{value^{net}}` from each Action Description, computed as :math:`\mathsf{value^{old}-value^{new}}`, must be balanced **only with respect to the same Asset Identifier**. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred. As was initially proposed by Jack Grigg and Daira Hopwood [#initial-zsa-issue]_ [#generalized-value-commitments]_, we propose to make this happen by changing the value base point, :math:`\mathcal{V}^{\mathsf{Orchard}}`, in the Homomorphic Pedersen Commitment that derives the value commitment, :math:`\mathsf{cv^{net}}`, of the *net value* in an Orchard Action. -Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` an auxiliary input to the proof for each Action statement [#protocol-actionstatement]_, represented already as a point on the Pallas curve. The circuit then should check that the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` is used in the old note commitment and the new note commitment [#protocol-concretesinsemillacommit]_, **and** as the base point :math:`\mathcal{V}^\mathsf{Orchard}` in the value commitment [#protocol-concretevaluecommit]_. This ensures (1) that the input and output notes are of the same :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature. +Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base an auxiliary input to the proof for each Action statement [#protocol-actionstatement]_, represented already as a point on the Pallas curve. The circuit then should check that the same Asset Base is used in the old note commitment and the new note commitment [#protocol-concretesinsemillacommit]_, **and** as the base point in the value commitment [#protocol-concretevaluecommit]_. This ensures (1) that the input and output notes are of the same Asset Base, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature. -In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the output note of that Split Action is the output of a valid :math:`\mathsf{ZSAValueBase^{Orchard}}` computation defined in ZIP 227 [#zip-0227]_. +In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}` of the output note of that Split Action is the output of a valid :math:`\mathsf{ZSAValueBase}` computation defined in ZIP 227 [#zip-0227]_. Finally, in this ZIP we also describe the *burn* mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the :math:`\mathsf{valueBalance}` of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets. @@ -70,9 +70,9 @@ Most of the protocol is kept the same as the Orchard protocol released with NU5, Asset Identifiers ----------------- -For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` for the Orchard-based ZSA protocol) are derived as defined in ZIP 227 [#zip-0227]_. +For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}`) are derived as defined in ZIP 227 [#zip-0227]_. -This :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` will be the base point of the value commitment for the specific Custom Asset. Note that the :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}` of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. +This Asset Base will be the base point of the value commitment for the specific Custom Asset. Note that the Asset Base of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`. Rationale for Asset Identifiers ``````````````````````````````` @@ -85,10 +85,10 @@ Note Structure & Commitment Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e. :math:`\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*`. -A ZSA note differs from an Orchard note [#protocol-notes]_ by additionally including the Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. So a ZSA note is a tuple :math:`(\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}^{\mathsf{Orchard}}})`, +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 -- :math:`\mathsf{AssetBase}^{\mathsf{Orchard}} : \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 non-bottom group element that is not the identity. 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}^{\mathsf{Orchard}})`. +- :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 non-bottom group element that is not the identity. 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})`. Note that the above assumes a canonical encoding, which is true for the Pallas group, but may not hold for future shielded protocols. @@ -100,9 +100,9 @@ where :math:`\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for t 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}^{\mathsf{Orchard}})} + \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})} :=\begin{cases} - \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase}^{\mathsf{Orchard}} = \mathcal{V}^{\mathsf{Orchard}} \\ + \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\ \mathsf{cm}_{\mathsf{ZSA}} &\text{otherwise} \end{cases} \end{align} @@ -133,26 +133,26 @@ As we will see, the nested structure of the Sinsemilla-based commitment [#protoc 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}^{\mathsf{Orchard}})} \in \mathsf{NoteCommit^{Orchard}.Output} +.. 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. Value Commitment ---------------- -In the case of the ZSA protocol, the value of different Asset Identifiers in a given transaction will be committed using a **different value base point**. The value commitment becomes: +In the case of the Orchard-based ZSA protocol, the value of different Asset Identifiers in a given transaction will be committed using a **different value base point**. The value commitment becomes: -.. math:: \mathsf{cv^{net}:=ValueCommit^{OrchardZSA}_{rcv}(v^{net}_{AssetId}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}:= \mathsf{[v^{net}_{AssetId}]}\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}} + [\mathsf{rcv}]\mathcal{R}^{\mathsf{Orchard}} +.. math:: \mathsf{cv^{net}:=ValueCommit^{OrchardZSA}_{rcv}(\mathsf{AssetBase}_{\mathsf{AssetId}}, v^{net}_{AssetId})}:= \mathsf{[v^{net}_{AssetId}]}\mathsf{AssetBase}_{\mathsf{AssetId}} + [\mathsf{rcv}]\mathcal{R}^{\mathsf{Orchard}} where :math:`\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId} - v^{new}_{AssetId}}` such that :math:`\mathsf{v^{old}_{AssetId}}` and :math:`\mathsf{v^{new}_{AssetId}}` are the values of the old and new notes of Asset Identifier :math:`\mathsf{AssetId}` respectively, .. _`asset base`: -:math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` is defined in ZIP 227 [#zip-0227]_, and +:math:`\mathsf{AssetBase}_{\mathsf{AssetId}}` is defined in ZIP 227 [#zip-0227]_, and :math:`\mathcal{R}^{\mathsf{Orchard}}:=\mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard-cv", "r")}`, as in the Orchard protocol. -We define :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{ZEC}} :=\mathcal{V}^{\mathsf{Orchard}}` so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 [#zip-0224]_. As such :math:`\mathsf{ValueCommit^{Orchard}_{rcv}(v)}` as defined in [#zip-0224]_ is used as :math:`\mathsf{ValueCommit^{OrchardZSA}_{rcv}(v, \mathcal{V}^{\mathsf{Orchard}})}` here. +For ZEC, we define :math:`\mathsf{AssetBase}_{\mathsf{AssetId}} :=\mathcal{V}^{\mathsf{Orchard}}` so that the value commitment for ZEC notes is computed identically to the Orchard protocol deployed in NU5 [#zip-0224]_. As such :math:`\mathsf{ValueCommit^{Orchard}_{rcv}(v)}` as defined in [#zip-0224]_ is used as :math:`\mathsf{ValueCommit^{OrchardZSA}_{rcv}(\mathcal{V}^{\mathsf{Orchard}}, v)}` here. Rationale for Value Commitment `````````````````````````````` @@ -161,35 +161,63 @@ The Orchard Protocol uses a Homomorphic Pedersen Commitment [#protocol-concretev The use of different value base points for different Assets enables the final balance of the transaction to be securely computed, such that each Asset Identifier is balanced independently, which is required as different Assets are not meant to be mutually fungible. +Burn Mechanism +-------------- + +The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. + +The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). + +For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` vector the tuple :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer. + +.. math:: \mathsf{assetBurn} = \{ (\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})\ |\ \forall\ \mathsf{AssetBase}_{\mathsf{AssetId}}\ \textit{s.t.}\ \mathsf{v_{AssetId}} \neq 0 \} + +We denote by :math:`L` the cardinality of the :math:`\mathsf{assetBurn}` set. + +Additional Consensus Rules +`````````````````````````` + +1. We require that for every :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase}_{\mathsf{AssetId}} \neq \mathcal{V}^{\mathsf{Orchard}}`. That is, ZEC or TAZ is not allowed to be burnt. +2. We require that for every :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v_{AssetId}} \neq 0`. +3. We require that there be no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}_{\mathsf{AssetId}}` has at most one entry in :math:`\mathsf{assetBurn}`. + +**Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets. Value Balance Verification -------------------------- -In order to verify the balance of the different Assets, the verifier MUST perform exactly the same process as for the Orchard protocol [#protocol-binding]_. +In order to verify the balance of the different Assets, the verifier MUST perform a similar process as for the Orchard protocol [#protocol-binding]_, with the addition of the burn information. For a total of :math:`n` Actions in a transfer, the prover MUST still sign the SIGHASH transaction hash using the binding signature key :math:`\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_{i}`. -The verifier MUST compute +The verifier MUST compute the value balance verification equation: -.. math:: \mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{\mathsf{Orchard}})} +.. math:: \mathsf{bvk} =(\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}(\mathcal{V}^{\mathsf{Orchard}}, v^{balanceOrchard})} - \sum_{(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{AssetBase}, \mathsf{v}) After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash. + 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:`m` Actions related to ZEC and :math:`n-m` Actions related to Custom Assets, where :math:`m \in [0,n]`. Furthermore, we assume for simplicity that given a tuple of :math:`n` Actions in a transfer, the :math:`m` Actions related to ZEC are first (in practice Actions could be in whatever order). +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 value balance verification is equivalent to: +The right hand side of the value balance verification equation can be expanded to: -.. math:: \mathsf{bvk} = (\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_j) - \mathsf{ValueCommit_0^{OrchardZSA}(v^{balanceOrchard}, \mathcal{V}^{Orchard})} +.. 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. As such, for a correctly constructed transaction, we MUST get :math:`\mathsf{(\sum_{j=m+1}^{n} v_j^{net}) = 0}`, and thus be left with :math:`\mathsf{\sum_{j=m+1}^{n} rcv_{j}^{net}}\mathcal{R}^{\mathsf{Orchard}}` in the expression. If :math:`m=n` (resp. :math:`m=0`), i.e. all Actions relate to ZEC (resp. Custom Assets), then :math:`m+1>n` (resp. :math:`1>m`), and thus the sum :math:`\sum_{j=m+1}^{n}` (resp. :math:`\sum_{i=1}^{m}`) returns the identity element of the group. +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}}`. -Thus, the main reason why no changes to the Orchard process are needed is that no Custom Assets can be unshielded within a regular transaction (as opposed to a *burn*, covered below in the `burn mechanism`_). All Custom Assets are contained within the shielded pool. This means that the net balance of the input and output values is zero, with only one value balance published, which corresponds to the ZEC value balance :math:`\mathsf{v^{balanceOrchard}}`. No net amount of any other Asset will be revealed, and the number of Assets in the transaction is also hidden. +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 only sum to zero **per Asset Base**, as the Pedersen commitments add up homomorphically only with respect to the same value base point. +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. Split Notes @@ -241,9 +269,9 @@ Asset Base Equality The following constraints must be added to ensure that the input and output note are of the same :math:`\mathsf{AssetBase}`: -- The Asset Base, :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`, for the note is witnessed once, as an auxiliary input. -- In the Old note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. -- In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}`. +- The Asset Base, :math:`\mathsf{AssetBase}_{\mathsf{AssetId}}`, for the note is witnessed once, as an auxiliary input. +- In the Old note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}_{\mathsf{AssetId}})}`. +- In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}_{\mathsf{AssetId}})}`. To make the evaluation of the note commitment easier, we add a boolean :math:`\mathsf{is\_native\_asset}` as an auxiliary witness. We also add some constraints to verify that this variable is activated (i.e. :math:`\mathsf{is\_native\_asset} = 1`) if the Asset Base is equal to :math:`\mathcal{V}^\mathsf{Orchard}` and this variable is not activated (i.e. :math:`\mathsf{is\_native\_asset} = 0`) if the Asset Base is not equal to :math:`\mathcal{V}^\mathsf{Orchard}`. @@ -253,7 +281,7 @@ Value Commitment Correctness The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base: - The fixed-base multiplication constraints between the value and the value base point of the value commitment, :math:`\mathsf{cv}`, is replaced with a variable-base multiplication between the two. -- The witness to the value base point (as defined in the `asset base`_ equation) is the auxiliary input :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}`. +- The witness to the value base point (as defined in the `asset base`_ equation) is the auxiliary input :math:`\mathsf{AssetBase}_{\mathsf{AssetId}}`. Asset Identifier Consistency for Split Actions `````````````````````````````````````````````` @@ -261,7 +289,7 @@ Asset Identifier Consistency for Split Actions Senders must not be able to change the Asset Base for the output note in a Split Action. We do this via the following constraints: - The Value Commitment Integrity should be changed: - - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(v’ - v^new, \mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}})}` + - Replace the input note value by a generic value, :math:`\mathsf{v}'`, as :math:`\mathsf{cv^{net}} = \mathsf{ValueCommit_rcv^{OrchardZSA}(\mathsf{AssetBase}_{\mathsf{AssetId}}, v’ - v^new)}` - Add a boolean :math:`\mathsf{split\_flag}` variable as an auxiliary witness. This variable is to be activated :math:`\mathsf{split\_flag} = 1` if the Action in question has a Split Input and :math:`\mathsf{split\_flag} = 0` if the Action is actually spending an input note: - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{v}' = 0` otherwise constrain :math:`\mathsf{v}'=\mathsf{v^{old}}` from the auxiliary input. - If :math:`\mathsf{split\_flag} = 1` then constrain :math:`\mathsf{is\_native\_asset} = 0` because split notes are only available for Custom Assets. @@ -275,51 +303,6 @@ Backwards Compatibility with ZEC Notes The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion [#protocol-abstractcommit]_. If the note is a ZSA note, the note commitment is computed as defined in the `Note Structure & Commitment`_ section. -Burn Mechanism -============== - -The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. - -The sender includes a :math:`\mathsf{v^{AssetBase}}` variable for every Asset Identifier that is being burnt. As we will show in the `ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset. - -For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` vector the tuple :math:`(\mathsf{AssetBase},\mathsf{v^{AssetBase}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer. - -.. math:: \mathsf{assetBurn} = \{ (\mathsf{AssetBase},\mathsf{v^{AssetBase}})\ |\ \forall\ \mathsf{AssetBase}\ \textit{s.t.}\ \mathsf{v^{AssetBase}} \neq 0 \} - -We denote by :math:`L` the cardinality of the :math:`\mathsf{assetBurn}` set. - -The value balances for each Asset Identifier in :math:`\mathsf{assetBurn}` represents the amount of that Asset that is being burnt. In the case of ZEC, the value balance represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). - -The validator needs to verify the Balance and Binding Signature by adding the value balances for all Assets, as committed using their respective :math:`\mathsf{AssetBase}` as the value base point of the Pedersen Commitment. - -This is done as follows: - -.. math:: \mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv^{net}}_{i}) - \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v^{balanceOrchard}}, \mathcal{V}^{\mathsf{Orchard}}) - \sum_{k=1}^{L} \mathsf{ValueCommit_0^{OrchardZSA}}(\mathsf{v}_{k}, \mathsf{AssetBase}_{k}) - -After computing :math:`\mathsf{bvk}`, the verifier MUST use it to verify the binding signature on the SIGHASH transaction hash. - -In the case that the balance of all the Action values related to a specific Asset will be zero, there will be no value added to the vector. This way, neither the number of Assets nor their Asset Identifiers will be revealed, except in the case that an Asset is burnt. - -Burn Mechanism Consensus Rules ------------------------------- - -1. We require that :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}`. That is, ZEC or TAZ is not allowed to be burnt. -2. We require that for every :math:`\forall (\mathsf{AssetBase},\mathsf{v^{AssetBase}}) \in \mathsf{assetBurn}\ ,\ \mathsf{v^{AssetBase}} \neq 0`. -3. We require that there be no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}` has at most one entry in :math:`\mathsf{assetBurn}`. - -**Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets. - -Rationale for Burn Mechanism -```````````````````````````` - -As for the value balance verification, we assume :math:`n` Actions, :math:`m` of which are related to ZEC and the remaining :math:`n-m` Actions related to Custom Assets. - -The burn mechanism verification is equivalent to: - -.. math:: \mathsf{bvk} = ((\sum_{i=1}^{m} \mathsf{cv^{net}}_{i}) + (\sum_{j=m+1}^{n} \mathsf{cv^{net}}_{j})) - ([\mathsf{v^{balanceOrchard}}]\mathcal{V}^{\mathsf{Orchard}} + [0]\mathcal{R}^{\mathsf{Orchard}}) - (\sum_{k=1}^{L} [\mathsf{v}_{k}]\mathsf{AssetBase}_{k} + [0]\mathcal{R}^{\mathsf{Orchard}}) - -The relationship between :math:`\mathsf{bvk}` and :math:`\mathsf{bsk}` will hold only if the sum of the net values of the Actions equals the sum of :math:`\mathsf{v^{balanceOrchard}}` and the :math:`\mathsf{v}_k` values, across base points (i.e. Asset Base). - ZSA Transaction Structure ========================= @@ -401,7 +384,7 @@ A ZSA Asset Burn description is encoded in a transaction as an instance of an `` +-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=======+===============+=============================+===========================================================================================================================+ -| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. | +| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}`. | +-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ | 8 | ``valueBurn`` | :math:`\{1 .. 2^{64} - 1\}` | The amount being burnt. | +-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ diff --git a/zip-0227-asset-identifier-relation.png b/zip-0227-asset-identifier-relation.png index d073f7aa80a0ddecd60084dc28a7502c111470b5..064e519600ba816498c8813043db229e9db4af0b 100644 GIT binary patch literal 38462 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 ISKmJDzdiByNB{r; literal 44943 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 PfEQR%{Z++Fi;w>Um{*4{ diff --git a/zip-0227-asset-identifier-relation.svg b/zip-0227-asset-identifier-relation.svg index de18d9914..670ed1784 100644 --- a/zip-0227-asset-identifier-relation.svg +++ b/zip-0227-asset-identifier-relation.svg @@ -26,15 +26,15 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="0.80392436" - inkscape:cx="147.40193" - inkscape:cy="90.804563" + inkscape:cx="261.84055" + inkscape:cy="53.487619" inkscape:document-units="px" - inkscape:current-layer="layer1" + inkscape:current-layer="g481" showgrid="false" inkscape:window-width="1158" inkscape:window-height="916" - inkscape:window-x="2102" - inkscape:window-y="136" + inkscape:window-x="1893" + inkscape:window-y="81" inkscape:window-maximized="0" inkscape:showpageshadow="2" inkscape:pagecheckerboard="0" @@ -177,7 +177,10 @@ inkscape:groupmode="layer" inkscape:label="Layer 1" transform="translate(256.28448,-836.58665)">Protocol\(\mathsf{AssetDigest}\) , which is simply is a \(\textsf{BLAKE2b-512}\) - hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example - \(\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}\) - for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

    + hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

    Let

    • @@ -206,10 +204,10 @@ .

    Define - \(\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\) - , where

    -

    In the case of Orchard, we define - \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\) + \(\mathsf{AssetBase_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\) +

    +

    In the case of the Orchard-based ZSA protocol, we define + \(\mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\) where \(\mathsf{GroupHash}^\mathbb{P}\) is defined as in 18.

    @@ -407,7 +405,7 @@ \(\mathsf{asset\_desc}\) as decribed in the Specification: Asset Identifier section.
  • compute - \(\mathsf{AssetBase^{Protocol}}\) + \(\mathsf{AssetBase}\) from \(\mathsf{AssetDigest}\) as decribed in the Specification: Asset Identifier section.
    • @@ -423,7 +421,7 @@ :
    • generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is - \(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!\) + \(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase}, \mathsf{rcm}_i)\!\) .
    @@ -698,14 +696,16 @@

    Other Considerations

    Implementing Zcash Nodes

    -

    Although not enforced in the global state, it is RECOMMENDED that Zcash full validators keep track of the total supply of Assets as a mutable mapping issuanceSupplyInfoMap from +

    Although not enforced in the global state, it is RECOMMENDED that Zcash full validators keep track of the total supply of Assets as a mutable mapping + \(\mathsf{issuanceSupplyInfoMap}\) + from \(\mathsf{AssetId}\) to - \(\mathsf{issuanceSupplyInfoMap := (totalSupply, finalize)}\) + \(\mathsf{(totalSupply, finalize)}\) in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

    Fee Structures

    -

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 10.

    +

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317 10.

    Test Vectors

    @@ -799,7 +799,7 @@
    - +
    AssetBase byte[32] For the Orchard-based ZSA protocol, this is the encoding of the Asset Base - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + \(\mathsf{AssetBase}\) .
    10ZIP 317b: ZSA Extension Proportional Fee MechanismZIP 317: Proportional Transfer Fee Mechanism
    diff --git a/zip-0227.rst b/zip-0227.rst index 54b93a5ac..1aa501525 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -149,7 +149,7 @@ Specification: Asset Identifier For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string. A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier. -From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. +From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. Let @@ -161,10 +161,9 @@ where - :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`. -Define :math:`\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`, -where +Define :math:`\mathsf{AssetBase_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}})` -In the case of Orchard, we define :math:`\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})` +In the case of the Orchard-based ZSA protocol, we define :math:`\mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})` where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in [#protocol-concretegrouphashpallasandvesta]_. The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram: @@ -265,11 +264,11 @@ For all actions ``IssueAction``: - encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512. - compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section. -- compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section. +- compute :math:`\mathsf{AssetBase}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section. - set the :math:`\mathsf{finalize}` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set :math:`\mathsf{finalize} = 0`, otherwise set :math:`\mathsf{finalize} = 1`) - For each recipient :math:`i`: - - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`. + - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase}, \mathsf{rcm}_i)\!`. - encode the ``IssueAction`` into the vector ``vIssueActions`` of the bundle. @@ -536,12 +535,12 @@ Other Considerations Implementing Zcash Nodes ------------------------ -Although not enforced in the global state, it is RECOMMENDED that Zcash full validators keep track of the total supply of Assets as a mutable mapping `issuanceSupplyInfoMap` from :math:`\mathsf{AssetId}` to :math:`\mathsf{issuanceSupplyInfoMap := (totalSupply, finalize)}` in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets. +Although not enforced in the global state, it is RECOMMENDED that Zcash full validators keep track of the total supply of Assets as a mutable mapping :math:`\mathsf{issuanceSupplyInfoMap}` from :math:`\mathsf{AssetId}` to :math:`\mathsf{(totalSupply, finalize)}` in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets. Fee Structures -------------- -The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b [#zip-0317b]_. +The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317 [#zip-0317b]_. Test Vectors @@ -572,7 +571,7 @@ References .. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ .. [#zip-0244-sigdigest] `ZIP 244: Transaction Identifier Non-Malleability: Signature Digest `_ .. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment `_ -.. [#zip-0317b] `ZIP 317b: ZSA Extension Proportional Fee Mechanism `_ +.. [#zip-0317b] `ZIP 317: Proportional Transfer Fee Mechanism `_ .. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ .. [#zip-0032-orchard-master] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation `_ .. [#zip-0032-orchard-child-key-derivation] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation `_ From 3ba25575ddc54654ea4f4ee6aa375cef02746c8c Mon Sep 17 00:00:00 2001 From: Constance Beguier Date: Thu, 21 Sep 2023 09:10:53 +0200 Subject: [PATCH 28/42] Add enable_zsa flag (#37) This PR adds enable_zsa flag into ZIP 226. --- zip-0226.html | 22 ++++++++++++++++++++++ zip-0226.rst | 9 +++++++++ 2 files changed, 31 insertions(+) diff --git a/zip-0226.html b/zip-0226.html index 79fe43a97..f55478bf0 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -64,6 +64,9 @@ of the output note of that Split Action is the output of a valid \(\mathsf{ZSAValueBase}\) computation defined in ZIP 227 6.

    +

    We include the ability to pause the ZSA functionality, via a + \(\mathsf{enableZSA}\) + boolean flag. When this flag is set to false, it is not possible to perform transactions involving Custom Assets (the circuit will fail).

    Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the \(\mathsf{valueBalance}\) of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets.

    @@ -339,6 +342,25 @@ \(\mathcal{V}^\mathsf{Orchard}\) .

    +
    +

    The + \(\mathsf{enableZSA}\) + Flag

    +

    The following constraints must be added to disable transactions involving Custom Assets when the + \(\mathsf{enableZSA}\) + flag is set to false:

    +
      +
    • if + \(\mathsf{enableZSA}\) + is not activated (i.e. + \(\mathsf{enableZSA} = 0\) + ), then constrain + \(\mathsf{is\_native\_asset} = 1\) + , since the + \(\mathsf{AsssetBase}\) + must be equal to the native asset.
      • +
    +

    Value Commitment Correctness

    The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base:

      diff --git a/zip-0226.rst b/zip-0226.rst index d3bb7263d..10aecbe0e 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -60,6 +60,8 @@ Because in a single transaction all value commitments are balanced, there must b In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}` of the output note of that Split Action is the output of a valid :math:`\mathsf{ZSAValueBase}` computation defined in ZIP 227 [#zip-0227]_. +We include the ability to pause the ZSA functionality, via a :math:`\mathsf{enableZSA}` boolean flag. When this flag is set to false, it is not possible to perform transactions involving Custom Assets (the circuit will fail). + Finally, in this ZIP we also describe the *burn* mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the :math:`\mathsf{valueBalance}` of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets. Specification @@ -275,6 +277,13 @@ The following constraints must be added to ensure that the input and output note To make the evaluation of the note commitment easier, we add a boolean :math:`\mathsf{is\_native\_asset}` as an auxiliary witness. We also add some constraints to verify that this variable is activated (i.e. :math:`\mathsf{is\_native\_asset} = 1`) if the Asset Base is equal to :math:`\mathcal{V}^\mathsf{Orchard}` and this variable is not activated (i.e. :math:`\mathsf{is\_native\_asset} = 0`) if the Asset Base is not equal to :math:`\mathcal{V}^\mathsf{Orchard}`. +The :math:`\mathsf{enableZSA}` Flag +````````````````````````````````````` + +The following constraints must be added to disable transactions involving Custom Assets when the :math:`\mathsf{enableZSA}` flag is set to false: + +- if :math:`\mathsf{enableZSA}` is not activated (i.e. :math:`\mathsf{enableZSA} = 0`), then constrain :math:`\mathsf{is\_native\_asset} = 1`, since the :math:`\mathsf{AsssetBase}` must be equal to the native asset. + Value Commitment Correctness ```````````````````````````` From 00a608c8d92120f5bd68e1adeab17b8cb3b9622a Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 3 Oct 2023 16:35:41 +0530 Subject: [PATCH 29/42] Renaming `idk` to `imk` throughout ZIP 227 (#41) This is a consistent renaming of the issuance derivation key to call it the issuance master key. --- zip-0227.html | 30 +++++++++++++++--------------- zip-0227.rst | 22 +++++++++++----------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 2589caa60..7b4df6c61 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -75,9 +75,9 @@

      Specification: Issuance Keys and Issuance Authorization Signature Scheme

      The ZSA Protocol adds the following three keys to the key components 17:

        -
      1. The issuance derivation key, denoted as - \(\mathsf{idk}\) - , as the name suggests, is the key that is used to derive the other two keys.
        2. +
      2. The issuance master key, denoted as + \(\mathsf{imk}\) + , is the key that is used to derive the other two keys.
      3. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as \(\mathsf{isk}\) . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
        4. @@ -106,20 +106,20 @@ is defined as in the Zcash protocol specification 18.

      Issuance Key Derivation

      -

      The issuance derivation key is generated by choosing a bit sequence uniformly at random from +

      The issuance master key is generated by choosing a bit sequence uniformly at random from \(\mathbb{B}^{\mathbb{Y}[32]}\) , like the Orchard spending key 20.

      -

      Issuance derivation key generation for hierarchical deterministic wallets

      -

      The issuance derivation key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

      +

      Issuance master key generation for hierarchical deterministic wallets

      +

      The issuance master key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

      Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\) .

      -

      As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance derivation key. We reuse the +

      As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the \(\mathsf{CDKsk}\) function for Orchard child key derivation from ZIP 32.

      -

      We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance derivation key path as +

      We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\) . We fix the path levels as follows:

        @@ -147,20 +147,20 @@

      From the generated \((\mathsf{sk}, \mathsf{c})\) - , we set the issuance derivation key to be - \(\mathsf{idk} := \mathsf{sk}\) + , we set the issuance master key to be + \(\mathsf{imk} := \mathsf{sk}\) .

      Derivation of issuance authorizing key and issuance validating key

      -

      The issuance authorizing key and issuance validating key are derived from the issuance derivation key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 20, as described below.

      +

      The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 20, as described below.

        -
      • The issuance authorizing key is derived from the issuance derivation key, - \(\mathsf{idk}\) +
      • The issuance authorizing key is derived from the issuance master key, + \(\mathsf{imk}\) , as a private signature key. The function - \(\mathsf{PRF^{expand}_{idk}}\) + \(\mathsf{PRF^{expand}_{imk}}\) is as defined in the Zcash protocol specification 19:
      -
      \(\mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{idk}}([\mathtt{0x0a}]) )\)
      +
      \(\mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{imk}}([\mathtt{0x0a}]) )\)
      • The issuance validating key is derived from the issuance authorizing key, \(\mathsf{isk}\) diff --git a/zip-0227.rst b/zip-0227.rst index 1aa501525..538a7fc67 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -82,7 +82,7 @@ Specification: Issuance Keys and Issuance Authorization Signature Scheme The ZSA Protocol adds the following three keys to the key components [#protocol-addressesandkeys]_: -1. The issuance derivation key, denoted as :math:`\mathsf{idk}`, as the name suggests, is the key that is used to derive the other two keys. +1. The issuance master key, denoted as :math:`\mathsf{imk}`, is the key that is used to derive the other two keys. 2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer. @@ -107,35 +107,35 @@ Specifically, we instantiate :math:`\mathsf{IssueAuthSig}` as :math:`\mathsf{Red Issuance Key Derivation ----------------------- -The issuance derivation key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_. +The issuance master key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_. -Issuance derivation key generation for hierarchical deterministic wallets -````````````````````````````````````````````````````````````````````````` +Issuance master key generation for hierarchical deterministic wallets +````````````````````````````````````````````````````````````````````` -The issuance derivation key is generated using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section. +The issuance master key is generated using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section. Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)`. -As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance derivation key. +As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key. We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32. -We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance derivation key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows: +We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows: - :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}`). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation. - :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_. - :math:`account`: fixed to index :math:`0`. -From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance derivation key to be :math:`\mathsf{idk} := \mathsf{sk}`. +From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance master key to be :math:`\mathsf{imk} := \mathsf{sk}`. Derivation of issuance authorizing key and issuance validating key `````````````````````````````````````````````````````````````````` -The issuance authorizing key and issuance validating key are derived from the issuance derivation key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below. +The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below. -- The issuance authorizing key is derived from the issuance derivation key, :math:`\mathsf{idk}`, as a private signature key. The function :math:`\mathsf{PRF^{expand}_{idk}}` is as defined in the Zcash protocol specification [#protocol-abstractprfs]_: +- The issuance authorizing key is derived from the issuance master key, :math:`\mathsf{imk}`, as a private signature key. The function :math:`\mathsf{PRF^{expand}_{imk}}` is as defined in the Zcash protocol specification [#protocol-abstractprfs]_: -.. math:: \mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{idk}}([\mathtt{0x0a}]) ) +.. math:: \mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{imk}}([\mathtt{0x0a}]) ) - The issuance validating key is derived from the issuance authorizing key, :math:`\mathsf{isk}`, as a public verification key: From ae5a2d8d2b0b2a86ae948b477b3d94740511dc21 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 5 Oct 2023 14:22:33 +0530 Subject: [PATCH 30/42] Move the updated transaction structure from ZIP 226 to ZIP 230 (#42) This removes the transaction structure fields from ZIP 226 in favour of adding them to ZIP 230, for the v6 Transaction Format. --------- Co-authored-by: Deirdre Connolly Co-authored-by: Daira Hopwood Co-authored-by: str4d Co-authored-by: Paul Co-authored-by: Antoine Rondelet Co-authored-by: Constance Beguier --- README.rst | 1 + index.html | 1 + zip-0226.html | 306 ++++++------------------ zip-0226.rst | 89 +------ zip-0230.html | 647 ++++++++++++++++++++++++++++++++++++++++++++++++++ zip-0230.rst | 350 +++++++++++++++++++++++++++ 6 files changed, 1075 insertions(+), 319 deletions(-) create mode 100644 zip-0230.html create mode 100644 zip-0230.rst diff --git a/README.rst b/README.rst index 4de43cdce..7a5ab50ff 100644 --- a/README.rst +++ b/README.rst @@ -109,6 +109,7 @@ Index of ZIPs 225 Version 5 Transaction Format Final 226 Transfer and Burn of Zcash Shielded Assets Draft 227 Issuance of Zcash Shielded Assets Draft + 230 Version 6 Transaction Format Draft 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final 244 Transaction Identifier Non-Malleability Final diff --git a/index.html b/index.html index a150585e0..b6ddf4519 100644 --- a/index.html +++ b/index.html @@ -83,6 +83,7 @@ 225 Version 5 Transaction Format Final 226 Transfer and Burn of Zcash Shielded Assets Draft 227 Issuance of Zcash Shielded Assets Draft + 230 Version 6 Transaction Format Draft 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final 244 Transaction Identifier Non-Malleability Final diff --git a/zip-0226.html b/zip-0226.html index f55478bf0..d0d4882ce 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -32,7 +32,7 @@
        • Split Input: an Action input used to ensure that the output note of that Action is of a validly issued \(\mathsf{AssetBase}\) - (see 7) when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in Split Notes.
          • + (see 8) when there is no corresponding real input note, in situations where the number of outputs are larger than the number of inputs. See formal definition in Split Notes.
        • Split Action: an Action that contains a Split Input.
      @@ -48,18 +48,18 @@ . This Asset Identifier maps to an Asset Base \(\mathsf{AssetBase}\) that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 6.

      -

      The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 15 is preserved across Assets (see the Orchard Binding Signature 17), and by extension the balance of an Orchard transaction. That is, the sum of all the +

      The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 16 is preserved across Assets (see the Orchard Binding Signature 18), and by extension the balance of an Orchard transaction. That is, the sum of all the \(\mathsf{value^{net}}\) from each Action Description, computed as \(\mathsf{value^{old}-value^{new}}\) , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.

      -

      As was initially proposed by Jack Grigg and Daira Hopwood 30 31, we propose to make this happen by changing the value base point, +

      As was initially proposed by Jack Grigg and Daira Hopwood 31 32, we propose to make this happen by changing the value base point, \(\mathcal{V}^{\mathsf{Orchard}}\) , in the Homomorphic Pedersen Commitment that derives the value commitment, \(\mathsf{cv^{net}}\) , of the net value in an Orchard Action.

      -

      Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base an auxiliary input to the proof for each Action statement 27, represented already as a point on the Pallas curve. The circuit then should check that the same Asset Base is used in the old note commitment and the new note commitment 24, and as the base point in the value commitment 25. This ensures (1) that the input and output notes are of the same Asset Base, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

      -

      In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 26 for Custom Assets, as we need to enforce that the +

      Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base an auxiliary input to the proof for each Action statement 28, represented already as a point on the Pallas curve. The circuit then should check that the same Asset Base is used in the old note commitment and the new note commitment 25, and as the base point in the value commitment 26. This ensures (1) that the input and output notes are of the same Asset Base, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

      +

      In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 27 for Custom Assets, as we need to enforce that the \(\mathsf{AssetBase}\) of the output note of that Split Action is the output of a valid \(\mathsf{ZSAValueBase}\) @@ -94,7 +94,7 @@ be the type of a ZSA note, i.e. \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*\) .

      -

      An Orchard ZSA note differs from an Orchard note 13 by additionally including the Asset Base, +

      An Orchard ZSA note differs from an Orchard note 14 by additionally including the Asset Base, \(\mathsf{AssetBase}\) . So a ZSA note is a tuple \((\mathsf{g_d, pk_d, v, \rho, \psi, \mathsf{AssetBase}})\) @@ -102,7 +102,7 @@

      • \(\mathsf{AssetBase} : \mathbb{P}*\) - is the unique element of the Pallas group 21 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as + is the unique element of the Pallas group 22 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase})\) .
      @@ -113,9 +113,9 @@
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)

      where \(\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}\) - are as defined for the Pallas curve 21, and + are as defined for the Pallas curve 22, and \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\) - are as defined in the Zcash protocol specification 16. This note commitment scheme is instantiated using the Sinsemilla Commitment 24 as follows:

      + are as defined in the Zcash protocol specification 17. This note commitment scheme is instantiated using the Sinsemilla Commitment 25 as follows:

      \(\begin{align} \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})} :=\begin{cases} @@ -133,21 +133,21 @@ \(\mathsf{repr}_{\mathbb{P}}\) and \(\mathsf{GroupHash}^{\mathbb{P}}\) - are as defined for the Pallas curve 21, + are as defined for the Pallas curve 22, \(\ell^{\mathsf{Orchard}}_{\mathsf{base}}\) - is as defined in §5.3 20, and + is as defined in §5.3 21, and \(\mathsf{I2LEBSP}\) - is as defined in §5.1 19 of the Zcash protocol specification.

      -

      The nullifier is generated in the same manner as in the Orchard protocol 18.

      -

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 14. It consists of

      + is as defined in §5.1 20 of the Zcash protocol specification.

      +

      The nullifier is generated in the same manner as in the Orchard protocol 19.

      +

      The ZSA note plaintext also includes the Asset Base in addition to the components in the Orchard note plaintext 15. It consists of

      \((\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, \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\) , differs from the Orchard note commitment \(\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 24 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 23. ZSA note commitments will therefore be added to the same Orchard Note Commitment Tree. In essence, we have:

      + 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 25 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 24. ZSA note commitments will therefore be added to the same Orchard Note Commitment Tree. In essence, we have:

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

      @@ -178,7 +178,7 @@ \(\mathsf{ValueCommit^{OrchardZSA}_{rcv}(\mathcal{V}^{\mathsf{Orchard}}, v)}\) here.

      Rationale for Value Commitment

      -

      The Orchard Protocol uses a Homomorphic Pedersen Commitment 25 to perform the value commitment, with fixed base points +

      The Orchard Protocol uses a Homomorphic Pedersen Commitment 26 to perform the value commitment, with fixed base points \(\mathcal{V}^{\mathsf{Orchard}}\) and \(\mathcal{R}^{\mathsf{Orchard}}\) @@ -190,7 +190,7 @@

      The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.

      The sender includes a \(\mathsf{v_{AssetId}}\) - variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the ZSA Transaction Structure, this is separate from the regular + variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the Orchard-ZSA Transaction Structure, this is separate from the regular \(\mathsf{valueBalance^Orchard}\) that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).

      For every Custom Asset that is burnt, we add to the @@ -224,7 +224,7 @@

      Value Balance Verification

      -

      In order to verify the balance of the different Assets, the verifier MUST perform a similar process as for the Orchard protocol 17, with the addition of the burn information.

      +

      In order to verify the balance of the different Assets, the verifier MUST perform a similar process as for the Orchard protocol 18, with the addition of the burn information.

      For a total of \(n\) Actions in a transfer, the prover MUST still sign the SIGHASH transaction hash using the binding signature key @@ -247,7 +247,7 @@ 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:

      \(((\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 17. 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 +

      This equation contains the balance check of the Orchard protocol 18. 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 \(\mathsf{assetBurn}\) set. As such, for a correctly constructed transaction, we will get \(\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}}\) @@ -296,11 +296,11 @@ \(\mathbb{F}_{q_{\mathbb{P}}}\) , \(\mathcal{K}^{\mathsf{Orchard}}\) - is the Orchard Nullifier Base as defined in 18, and + is the Orchard Nullifier Base as defined in 19, and \(\mathcal{L}^{\mathsf{Orchard}} := \mathsf{GroupHash^{\mathbb{P}}}\texttt{("z.cash:Orchard", "L")}\) .

      Rationale for Split Notes

      -

      In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 26 to the Actions that have not been assigned input notes.

      +

      In the Orchard protocol, since each Action represents an input and an output, the transaction that wants to send one input to multiple outputs must have multiple inputs. The Orchard protocol gives dummy spend notes 27 to the Actions that have not been assigned input notes.

      The Orchard technique requires modification for the ZSA protocol with multiple Asset Identifiers, as the output note of the split Actions cannot contain any Asset Base. We must enforce it to be an actual output of a GroupHash computation (in fact, we want it to be of the same Asset Base as the original input note, but the binding signature takes care that the proper balancing is performed). Without this enforcement the prover could input a multiple (or linear combination) of an existing Asset Base, and thereby attack the network by overflowing the ZEC value balance and hence counterfeiting ZEC funds.

      Therefore, for Custom Assets we enforce that every input note to an ZSA Action must be proven to exist in the set of note commitments in the note commitment tree. We then enforce this real note to be “unspendable” in the sense that its value will be zeroed in split Actions and the nullifier will be randomized, making the note not spendable in the specific Action. Then, the proof itself ensures that the output note is of the same Asset Base as the input note. In the circuit, the split note functionality will be activated by a boolean private input to the proof (aka the \(\mathsf{split\_flag}\) @@ -309,8 +309,8 @@

      Circuit Statement

      -

      Every ZSA Action statement is closely similar to the Orchard Action statement 27, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

      -

      All modifications in the Circuit are detailed in 33.

      +

      Every ZSA Action statement is closely similar to the Orchard Action statement 28, except for a few additions that ensure the security of the Asset Identifier system. We detail these changes below.

      +

      All modifications in the Circuit are detailed in 34.

      Asset Base Equality

      The following constraints must be added to ensure that the input and output note are of the same \(\mathsf{AssetBase}\) @@ -319,12 +319,12 @@

    • The Asset Base, \(\mathsf{AssetBase}_{\mathsf{AssetId}}\) , for the note is witnessed once, as an auxiliary input.
      • -
    • In the Old note commitment integrity constraint in the Orchard Action statement 27, +
    • In the Old note commitment integrity constraint in the Orchard Action statement 28, \(\mathsf{NoteCommit^{Orchard}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}(repr_{\mathbb{P}}(g_d^{old}), repr_{\mathbb{P}}(pk_d^{old}), v^{old}, \rho^{old}, \psi^{old}, \mathsf{AssetBase}_{\mathsf{AssetId}})}\) .
      • -
    • In the New note commitment integrity constraint in the Orchard Action statement 27, +
    • In the New note commitment integrity constraint in the Orchard Action statement 28, \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new})}\) is replaced with \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}(repr_{\mathbb{P}}(g_d^{new}), repr_{\mathbb{P}}(pk_d^{new}), v^{new}, \rho^{new}, \psi^{new}, \mathsf{AssetBase}_{\mathsf{AssetId}})}\) @@ -439,187 +439,15 @@

      The

    Backwards Compatibility with ZEC Notes

    -

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 16. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    +

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 17. If the note is a ZSA note, the note commitment is computed as defined in the Note Structure & Commitment section.

    -

    ZSA Transaction Structure

    -

    The transaction format closely follows the version 5 transaction format described in the Zcash specification 28. The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification 28.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    BytesNameData TypeDescription
    Orchard Transaction Fields
    variesnActionsOrchardcompactSize
    852 * nActionsOrchardvActionsOrchardZSAOrchardAction[nActionsOrchard]A sequence of ZSA Orchard Action descriptions, encoded per the ZSA Orchard Action Description Encoding. [UPDATED FOR ZSA]
    1flagsOrchardbyte
    8valueBalanceOrchardint64
    32anchorOrchardbyte[32]
    variessizeProofsOrchardcompactSize
    sizeProofsOrchardproofsOrchardbyte[sizeProofsOrchard]
    64 * nActionsOrchardvSpendAuthSigsOrchardbyte[64 * nActionsOrchard]
    64bindingSigOrchardbyte[64]
    ZSA Burn Fields
    variesnAssetBurncompactSizeThe number of Assets burnt.
    40 * nAssetBurnvAssetBurnAssetBurn[nAssetBurn]A sequence of Asset Burn descriptions, encoded per ZSA Asset Burn Description.
    -

    ZSA Orchard Action Description Encoding

    -

    The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification 29. A ZSA Orchard Action description is encoded in a transaction as an instance of an ZSAOrchardAction type:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    BytesNameData Type
    32cvbyte[32]
    32nullifierbyte[32]
    32rkbyte[32]
    32cmxbyte[32]
    32ephemeralKeybyte[32]
    612encCiphertextbyte[612][UPDATED FOR ZSA]
    80outCiphertextbyte[32]
    -
    -

    ZSA Asset Burn Description

    -

    A ZSA Asset Burn description is encoded in a transaction as an instance of an AssetBurn type:

    - - - - - - - - - - - - - - - - - - - - - - - -
    BytesNameData TypeDescription
    32AssetBasebyte[32]For the Orchard-based ZSA protocol, this is the encoding of the Asset Base - \(\mathsf{AssetBase}\) - .
    8valueBurn - \(\{1 .. 2^{64} - 1\}\) - The amount being burnt.
    -
    +

    Orchard-ZSA Transaction Structure

    +

    The transaction format for v6 transactions is described in ZIP 230 7.

    TxId Digest

    -

    The transaction digest algorithm defined in ZIP 244 11 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 12 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

    A BLAKE2b-256 hash of the following values

    T.1: header_digest       (32-byte hash output)
@@ -627,7 +455,7 @@ 
    The
 T.3: sapling_digest      (32-byte hash output)
 T.4: orchard_digest      (32-byte hash output)  [UPDATED FOR ZSA]
 T.5: issuance_digest     (32-byte hash output)  [ADDED FOR ZSA]
    -

    The personalization field remains the same as in ZIP 244 11.

    +

    The personalization field remains the same as in ZIP 244 12.

    T.4: orchard_digest

    When Orchard Actions are present in the transaction, this digest is a BLAKE2b-256 hash of the following values

    T.4a: orchard_actions_compact_digest      (32-byte hash output)          [UPDATED FOR ZSA]
@@ -637,7 +465,7 @@ 
    The
 T.4e: valueBalanceOrchard                 (64-bit signed little-endian)
 T.4f: anchorOrchard                       (32 bytes)
    T.4a: orchard_actions_compact_digest
    -

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 12 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the subset of Orchard Action information intended to be included in an updated version of the ZIP-307 13 CompactBlock format for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4a.i  : nullifier            (field encoding bytes)
 T.4a.ii : cmx                  (field encoding bytes)
 T.4a.iii: ephemeralKey         (field encoding bytes)
@@ -652,7 +480,7 @@ 
    The
                         
    "ZTxIdOrcActMHash"
    T.4c: orchard_actions_noncompact_digest
    -

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 12 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    +

    A BLAKE2b-256 hash of the remaining subset of Orchard Action information not intended for inclusion in an updated version of the the ZIP 307 13 CompactBlock format, for all Orchard Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.4d.i  : cv                    (field encoding bytes)
 T.4d.ii : rk                    (field encoding bytes)
 T.4d.iii: encCiphertext[596..]  (post-memo suffix of field encoding)  [UPDATED FOR ZSA]
@@ -662,12 +490,12 @@ 
    The

    T.5: issuance_digest

    -

    The details of the computation of this value are in ZIP 227 8.

    +

    The details of the computation of this value are in ZIP 227 9.

    Signature Digest and Authorizing Data Commitment

    -

    The details of the changes to these algorithms are in ZIP 227 9 10.

    +

    The details of the changes to these algorithms are in ZIP 227 10 11.

    Security and Privacy Considerations

      @@ -678,7 +506,7 @@

      The

    Other Considerations

    Transaction Fees

    -

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 32.

    +

    The fee mechanism for the upgrades proposed in this ZIP will follow the mechanism described in ZIP 317 for the ZSA protocol upgrade 33.

    Backward Compatibility

    In order to have backward compatibility with the ZEC notes, we have designed the circuit to support both ZEC and ZSA notes. As we specify above, there are three main reasons we can do this:

    @@ -757,10 +585,18 @@

    The - +
    + + + +
    7ZIP 230: Version 6 Transaction Format
    + + + + @@ -768,7 +604,7 @@

    The

    8 ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier
    - + @@ -776,7 +612,7 @@

    The

    89 ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance
    - + @@ -784,7 +620,7 @@

    The

    910 ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest
    - + @@ -792,7 +628,7 @@

    The

    1011 ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment
    - + @@ -800,7 +636,7 @@

    The

    1112 ZIP 244: Transaction Identifier Non-Malleability
    - + @@ -808,7 +644,7 @@

    The

    1213 ZIP 307: Light Client Protocol for Payment Detection
    - + @@ -816,7 +652,7 @@

    The

    1314 Zcash Protocol Specification, Version 2022.3.8. Section 3.2: Notes
    - + @@ -824,7 +660,7 @@

    The

    1415 Zcash Protocol Specification, Version 2022.3.8. Section 5.5: Encodings of Note Plaintexts and Memo Fields
    - + @@ -832,7 +668,7 @@

    The

    1516 Zcash Protocol Specification, Version 2022.3.8. Section 3.7: Action Transfers and their Descriptions
    - + @@ -840,7 +676,7 @@

    The

    1617 Zcash Protocol Specification, Version 2022.3.8. Section 4.1.8: Commitment
    - + @@ -848,7 +684,7 @@

    The

    1718 Zcash Protocol Specification, Version 2022.3.8. Section 4.14: Balance and Binding Signature (Orchard)
    - + @@ -856,7 +692,7 @@

    The

    1819 Zcash Protocol Specification, Version 2022.3.8. Section 4.16: Note Commitments and Nullifiers
    - + @@ -864,7 +700,7 @@

    The

    1920 Zcash Protocol Specification, Version 2022.3.8. Section 5.1: Integers, Bit Sequences, and Endianness
    - + @@ -872,7 +708,7 @@

    The

    2021 Zcash Protocol Specification, Version 2022.3.8. Section 5.3: Constants
    - + @@ -880,7 +716,7 @@

    The

    2122 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.6: Pallas and Vesta
    - + @@ -888,7 +724,7 @@

    The

    2223 Pallas/Vesta supporting evidence
    - + @@ -896,7 +732,7 @@

    The

    2324 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.1.9: Sinsemilla hash function
    - + @@ -904,7 +740,7 @@

    The

    2425 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.4: Sinsemilla commitments
    - + @@ -912,7 +748,7 @@

    The

    2526 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
    - + @@ -920,7 +756,7 @@

    The

    2627 Zcash Protocol Specification, Version 2022.3.8. Section 4.8.3: Dummy Notes (Orchard)
    - + @@ -928,7 +764,7 @@

    The

    2728 Zcash Protocol Specification, Version 2022.3.8. Section 4.17.4: Action Statement (Orchard)
    - + @@ -936,7 +772,7 @@

    The

    2829 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    - + @@ -944,7 +780,7 @@

    The

    2930 Zcash Protocol Specification, Version 2022.3.8. Section 7.5: Action Description Encoding and Consensus
    - + @@ -952,7 +788,7 @@

    The

    3031 User-Defined Assets and Wrapped Assets
    - + @@ -960,7 +796,7 @@

    The

    3132 Comment on Generalized Value Commitments
    - + @@ -968,7 +804,7 @@

    The

    3233 ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
    - + diff --git a/zip-0226.rst b/zip-0226.rst index 10aecbe0e..43ea818b0 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -168,7 +168,7 @@ Burn Mechanism The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. -The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). +The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `Orchard-ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent). For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` vector the tuple :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer. @@ -312,91 +312,11 @@ Backwards Compatibility with ZEC Notes The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion [#protocol-abstractcommit]_. If the note is a ZSA note, the note commitment is computed as defined in the `Note Structure & Commitment`_ section. -ZSA Transaction Structure -========================= - -The transaction format closely follows the version 5 transaction format described in the Zcash specification [#protocol-transactionstructure]_. -The Common Transaction Fields, Transparent Transaction Fields, and Sapling Transaction Fields remain the same as in the version 5 transaction format. -We make some modifications to the Orchard Transaction Fields and the Orchard Action Descriptions, which we detail in the first and second tables below respectively. -We also add ZSA Burn Fields to the transaction format, which we detail in the first table below. -For brevity, we omit the descriptions from the table below unless they differ from the descriptions in §7.1 of the Zcash specification [#protocol-transactionstructure]_. - - -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -| Bytes | Name | Data Type | Description | -+=============================+==========================+===========================================+=====================================================================+ -| **Orchard Transaction Fields** | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``varies`` |``nActionsOrchard`` |``compactSize`` | | -| | | | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``852 * nActionsOrchard`` |``vActionsOrchard`` |``ZSAOrchardAction[nActionsOrchard]`` |A sequence of ZSA Orchard Action descriptions, encoded per | -| | | |the `ZSA Orchard Action Description Encoding`_. **[UPDATED FOR ZSA]**| -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``1`` |``flagsOrchard`` |``byte`` | | -| | | | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``8`` |``valueBalanceOrchard`` |``int64`` | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``32`` |``anchorOrchard`` |``byte[32]`` | | -| | | | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``varies`` |``sizeProofsOrchard`` |``compactSize`` | | -| | | | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``sizeProofsOrchard`` |``proofsOrchard`` |``byte[sizeProofsOrchard]`` | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``64 * nActionsOrchard`` |``vSpendAuthSigsOrchard`` |``byte[64 * nActionsOrchard]`` | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``64`` |``bindingSigOrchard`` |``byte[64]`` | | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -| **ZSA Burn Fields** | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -| ``varies`` | ``nAssetBurn`` | ``compactSize`` | The number of Assets burnt. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -| ``40 * nAssetBurn`` | ``vAssetBurn`` | ``AssetBurn[nAssetBurn]`` | A sequence of Asset Burn descriptions, | -| | | | encoded per `ZSA Asset Burn Description`_. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ - -ZSA Orchard Action Description Encoding ---------------------------------------- - -The ZSA Orchard Action size differs from the Orchard Action size by 32 bytes. -This means that the size goes from 820 bytes in the Orchard Action to 852 bytes in the ZSA Orchard Action. -We omit the descriptions from the table below since they are identical to the descriptions in §7.5 of the Zcash specification [#protocol-actionencodingandconsensus]_. -A ZSA Orchard Action description is encoded in a transaction as an instance of an ``ZSAOrchardAction`` type: - -+-------+-------------------+---------------+----------------------+ -| Bytes | Name | Data Type | | -+=======+===================+===============+======================+ -| 32 | ``cv`` | ``byte[32]`` | | -+-------+-------------------+---------------+----------------------+ -| 32 | ``nullifier`` | ``byte[32]`` | | -+-------+-------------------+---------------+----------------------+ -| 32 | ``rk`` | ``byte[32]`` | | -+-------+-------------------+---------------+----------------------+ -| 32 | ``cmx`` | ``byte[32]`` | | -+-------+-------------------+---------------+----------------------+ -| 32 | ``ephemeralKey`` | ``byte[32]`` | | -+-------+-------------------+---------------+----------------------+ -| 612 | ``encCiphertext`` | ``byte[612]`` |**[UPDATED FOR ZSA]** | -+-------+-------------------+---------------+----------------------+ -| 80 | ``outCiphertext`` | ``byte[32]`` | | -+-------+-------------------+---------------+----------------------+ - - -ZSA Asset Burn Description --------------------------- +Orchard-ZSA Transaction Structure +================================= -A ZSA Asset Burn description is encoded in a transaction as an instance of an ``AssetBurn`` type: +The transaction format for v6 transactions is described in ZIP 230 [#zip-0230]_. -+-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| Bytes | Name | Data Type | Description | -+=======+===============+=============================+===========================================================================================================================+ -| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}`. | -+-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| 8 | ``valueBurn`` | :math:`\{1 .. 2^{64} - 1\}` | The amount being burnt. | -+-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ TxId Digest =========== @@ -536,6 +456,7 @@ References .. [#zip-0224] `ZIP 224: Orchard `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ +.. [#zip-0230] `ZIP 230: Version 6 Transaction Format `_ .. [#zip-0227-assetidentifier] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier `_ .. [#zip-0227-txiddigest] `ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance `_ .. [#zip-0227-sigdigest] `ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest `_ diff --git a/zip-0230.html b/zip-0230.html new file mode 100644 index 000000000..c96bfd051 --- /dev/null +++ b/zip-0230.html @@ -0,0 +1,647 @@ + + + + ZIP 230: Version 6 Transaction Format + + + + +
    + 
    ZIP: 230
+Title: Version 6 Transaction Format
+Owners: Daira Emma Hopwood <daira@electriccoin.co>
+        Jack Grigg <jack@electriccoin.co>
+        Kris Nuttycombe <kris@electriccoin.co>
+        Greg Pfeil <greg@electriccoin.co>
+        Deirdre Connolly <deirdre@zfnd.org>
+        Pablo Kogan <pablo@qed-it.com>
+        Vivek Arte <vivek@qed-it.com>
+Credits: Ying Tong Lai
+Status: Draft
+Category: Consensus
+Created: 2023-04-18
+License: MIT
+Discussions-To: <https://github.com/zcash/zips/issues/686>
    +

    Terminology

    +

    The key words "MUST" and "MAY" in this document are to be interpreted as described in RFC 2119. 1

    +

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

    +
    +

    Abstract

    +

    This proposal defines a new Zcash peer-to-peer transaction format, which includes data that supports the Orchard-ZSA protocol and all Zcash Shielded Assets (ZSAs) related operations. The new transaction format defines well-bounded regions of the serialized form to serve each of the existing pools of funds, and adds and describes a new elements containing ZSA-specific elements.

    +

    This ZIP also depends upon and defines modifications to the computation of the values TxId Digest, Signature Digest, and Authorizing Data Commitment defined by ZIP 244 9.

    +
    +

    Motivation

    +

    The Orchard-ZSA protocol requires serialized data elements that are distinct from any previous Zcash transaction. Since ZIP 244 was activated in NU5, the v5 and later serialized transaction formats are not consensus-critical. Thus, this ZIP defines format that can easily accommodate future extensions, where elements or a given pool are kept separate.

    +
    +

    Requirements

    +

    The new format must fully support the Orchard-ZSA protocol.

    +

    The new format should lend itself to future extension or pruning to add or remove value pools.

    +

    The computation of the non-malleable transaction identifier hash must include all newly incorporated elements except those that attest to transaction validity.

    +

    The computation of the commitment to authorizing data for a transaction must include all newly incorporated elements that attest to transaction validity.

    +
    +

    Non-requirements

    +

    More general forms of extensibility, such as definining a key/value format that allows for parsers that are unaware of some components, are not required.

    +
    +

    Specification

    +

    All fields in this specification are encoded as little-endian.

    +

    The Zcash transaction format for transaction version 6 is as follows:

    +

    Transaction Format

    +
    3334 Modifications to the Orchard circuit for the ZSA Protocol
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    Common Transaction Fields
    4headeruint32 +
    +
    Contains:
    +
    +
      +
    • fOverwintered flag (bit 31, always set)
      • +
    • version (bits 30 .. 0) – transaction version.
      • +
    +
    +
    +
    4nVersionGroupIduint32Version group ID (nonzero).
    4nConsensusBranchIduint32Consensus branch ID (nonzero).
    4lock_timeuint32Unix-epoch UTC time or block height, encoded as in Bitcoin.
    4nExpiryHeightuint32A block height in the range {1 .. 499999999} after which the transaction will expire, or 0 to disable expiry. [ZIP-203]
    8feeint64The fee to be paid by this transaction, in zatoshis.
    Transparent Transaction Fields
    variestx_in_countcompactSizeNumber of transparent inputs in tx_in.
    variestx_intx_inTransparent inputs, encoded as in Bitcoin.
    variestx_out_countcompactSizeNumber of transparent outputs in tx_out.
    variestx_outtx_outTransparent outputs, encoded as in Bitcoin.
    Sapling Transaction Fields
    variesnSpendsSaplingcompactSizeNumber of Sapling Spend descriptions in vSpendsSapling.
    96 * nSpendsSaplingvSpendsSaplingSpendDescriptionV6[nSpendsSapling]A sequence of Sapling Spend descriptions, encoded per protocol §7.3 ‘Spend Description Encoding and Consensus’.
    variesnOutputsSaplingcompactSizeNumber of Sapling Output Decriptions in vOutputsSapling.
    756 * nOutputsSaplingvOutputsSaplingOutputDescriptionV6[nOutputsSapling]A sequence of Sapling Output descriptions, encoded per protocol §7.4 ‘Output Description Encoding and Consensus’.
    8valueBalanceSaplingint64The net value of Sapling Spends minus Outputs
    32anchorSaplingbyte[32]A root of the Sapling note commitment tree at some block height in the past.
    192 * nSpendsSaplingvSpendProofsSaplingbyte[192 * nSpendsSapling]Encodings of the zk-SNARK proofs for each Sapling Spend.
    64 * nSpendsSaplingvSpendAuthSigsSaplingbyte[64 * nSpendsSapling]Authorizing signatures for each Sapling Spend.
    192 * nOutputsSaplingvOutputProofsSaplingbyte[192 * nOutputsSapling]Encodings of the zk-SNARK proofs for each Sapling Output.
    64bindingSigSaplingbyte[64]A Sapling binding signature on the SIGHASH transaction hash.
    Orchard-ZSA Transaction Fields
    variesnActionsOrchardcompactSizeThe number of Orchard-ZSA Action descriptions in vActionsOrchard.
    852 * nActionsOrchardvActionsOrchardOrchardZsaAction[nActionsOrchard]A sequence of Orchard-ZSA Action descriptions, encoded per the Orchard-ZSA Action Description Encoding.
    1flagsOrchardbyte +
    +
    An 8-bit value representing a set of flags. Ordered from LSB to MSB:
    +
    +
      +
    • enableSpendsOrchard
      • +
    • enableOutputsOrchard
      • +
    • enableZSAs
      • +
    • The remaining bits are set to 0.
      • +
    +
    +
    +
    8valueBalanceOrchardint64The net value of Orchard spends minus outputs.
    32anchorOrchardbyte[32]A root of the Orchard note commitment tree at some block height in the past.
    variessizeProofsOrchardZSAcompactSizeLength in bytes of proofsOrchardZSA. Value is (TO UPDATE) + \(2720 + 2272 \cdot \mathtt{nActionsOrchard}\) + .
    sizeProofsOrchardZSAproofsOrchardZSAbyte[sizeProofsOrchardZSA]Encoding of aggregated zk-SNARK proofs for Orchard-ZSA Actions.
    64 * nActionsOrchardvSpendAuthSigsOrchardbyte[64 * nActionsOrchard]Authorizing signatures for each Orchard-ZSA Action.
    64bindingSigOrchardbyte[64]An Orchard binding signature on the SIGHASH transaction hash.
    Orchard-ZSA Burn Fields
    variesnAssetBurncompactSizeThe number of Assets burnt.
    40 * nAssetBurnvAssetBurnAssetBurn[nAssetBurn]A sequence of Asset Burn descriptions, encoded per Orchard-ZSA Asset Burn Description.
    Orchard-ZSA Issuance Fields
    variesnIssueActionscompactSizeThe number of issuance actions in the bundle.
    IssueActionSize * nIssueActionsvIssueActionsIssueAction[nIssueActions]A sequence of issuance action descriptions, where IssueActionSize is the size, in bytes, of an IssueAction description.
    32ikbyte[32]The issuance validating key of the issuer, used to validate the signature.
    64issueAuthSigbyte[64]The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme 8.
    +
      +
    • The fields valueBalanceSapling and bindingSigSapling are present if and only if + \(\mathtt{nSpendsSapling} + \mathtt{nOutputsSapling} > 0\) + . If valueBalanceSapling is not present, then + \(\mathsf{v^{balanceSapling}}`\) + is defined to be 0.
      • +
    • The field anchorSapling is present if and only if + \(\mathtt{nSpendsSapling} > 0\) + .
      • +
    • The fields flagsOrchard, valueBalanceOrchard, anchorOrchard, sizeProofsOrchardZSA, proofsOrchardZSA, and bindingSigOrchard are present if and only if + \(\mathtt{nActionsOrchard} > 0\) + . If valueBalanceOrchard is not present, then + \(\mathsf{v^{balanceOrchard}}\) + is defined to be 0.
      • +
    • The elements of vSpendProofsSapling and vSpendAuthSigsSapling have a 1:1 correspondence to the elements of vSpendsSapling and MUST be ordered such that the proof or signature at a given index corresponds to the SpendDescriptionV6 at the same index.
      • +
    • The elements of vOutputProofsSapling have a 1:1 correspondence to the elements of vOutputsSapling and MUST be ordered such that the proof at a given index corresponds to the OutputDescriptionV6 at the same index.
      • +
    • The proofs aggregated in proofsOrchardZSA, and the elements of vSpendAuthSigsOrchard, each have a 1:1 correspondence to the elements of vActionsOrchard and MUST be ordered such that the proof or signature at a given index corresponds to the OrchardZsaAction at the same index.
      • +
    • For coinbase transactions, the enableSpendsOrchard and enableZSAs bits MUST be set to 0.
      • +
    +

    The encodings of tx_in, and tx_out are as in a version 4 transaction (i.e. unchanged from Canopy). The encodings of SpendDescriptionV6, OutputDescriptionV6 , OrchardZsaAction, AssetBurn and IssueAction are described below. The encoding of Sapling Spends and Outputs has changed relative to prior versions in order to better separate data that describe the effects of the transaction from the proofs of and commitments to those effects, and for symmetry with this separation in the Orchard-related parts of the transaction format.

    +

    +

    Sapling Spend Description (SpendDescriptionV6)

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    32cvbyte[32]A value commitment to the net value of the input note.
    32nullifierbyte[32]The nullifier of the input note.
    32rkbyte[32]The randomized validating key for the element of spendAuthSigsSapling corresponding to this Spend.
    +

    The encodings of each of these elements are defined in §7.3 ‘Spend Description Encoding and Consensus’ of the Zcash Protocol Specification 3.

    +
    +

    Sapling Output Description (OutputDescriptionV6)

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    32cvbyte[32]A value commitment to the net value of the output note.
    32cmubyte[32]The u-coordinate of the note commitment for the output note.
    32ephemeralKeybyte[32]An encoding of an ephemeral Jubjub public key.
    580encCiphertextbyte[580]The encrypted contents of the note plaintext.
    80outCiphertextbyte[80]The encrypted contents of the byte string created by concatenation of the transmission key with the ephemeral secret key.
    +

    The encodings of each of these elements are defined in §7.4 ‘Output Description Encoding and Consensus’ of the Zcash Protocol Specification 4.

    +
    +

    Orchard-ZSA Action Description (OrchardZsaAction)

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    32cvbyte[32]A value commitment to the net value of the input note minus the output note.
    32nullifierbyte[32]The nullifier of the input note.
    32rkbyte[32]The randomized validating key for the element of spendAuthSigsOrchard corresponding to this Action.
    32cmxbyte[32]The x-coordinate of the note commitment for the output note.
    32ephemeralKeybyte[32]An encoding of an ephemeral Pallas public key
    612encCiphertextbyte[580]The encrypted contents of the note plaintext.
    80outCiphertextbyte[80]The encrypted contents of the byte string created by concatenation of the transmission key with the ephemeral secret key.
    +

    The encodings of each of these elements are defined in §7.5 ‘Action Description Encoding and Consensus’ of the Zcash Protocol Specification 5.

    +
    +

    Orchard-ZSA Asset Burn Description

    +

    An Orchard-ZSA Asset Burn description is encoded in a transaction as an instance of an AssetBurn type:

    + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    32AssetBasebyte[32]For the Orchard-based ZSA protocol, this is the encoding of the Asset Base + \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) + .
    8valueBurn + \(\{1 .. 2^{64} - 1\}\) + The amount being burnt.
    +

    The encodings of each of these elements are defined in ZIP 226 7.

    +
    +

    Issuance Action Description (IssueAction)

    +

    An issuance action, IssueAction, is the instance of issuing a specific Custom Asset, and contains the following fields:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    2assetDescSizebyteThe length of the asset description string in bytes.
    assetDescSizeasset_descbyte[assetDescSize]A byte sequence of length assetDescSize bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
    variesnNotescompactSizeThe number of notes in the issuance action.
    noteSize * nNotesvNotesNote[nNotes]A sequence of note descriptions within the issuance action, where noteSize is the size, in bytes, of a Note.
    1flagsIssuancebyte +
    +
    An 8-bit value representing a set of flags. Ordered from LSB to MSB:
    +
    +
      +
    • + \(\mathsf{finalize}\) +
      • +
    • The remaining bits are set to 0.
      • +
    +
    +
    +
    +

    The encodings of each of these elements are defined in ZIP 227 8.

    +
    +
    +

    Reference implementation

    +

    TODO

    +
    +

    References

    + + + + + + + +
    1RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
    + + + + + + + +
    2Zcash Protocol Specification, Version 2021.2.16 or later [NU5 proposal]
    + + + + + + + +
    3Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.4: Spend Descriptions
    + + + + + + + +
    4Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.5: Output Descriptions
    + + + + + + + +
    5Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.6: Action Descriptions
    + + + + + + + +
    6ZIP 222: Transparent Zcash Extensions
    + + + + + + + +
    7ZIP 226: Transfer and Burn of Zcash Shielded Assets
    + + + + + + + +
    8ZIP 227: Issuance of Zcash Shielded Assets
    + + + + + + + +
    9ZIP 244: Transaction Identifier Non-Malleability
    + + + + + + + +
    10ZIP 307: Light Client Protocol for Payment Detection
    +
    +
    + + \ No newline at end of file diff --git a/zip-0230.rst b/zip-0230.rst new file mode 100644 index 000000000..a894527dc --- /dev/null +++ b/zip-0230.rst @@ -0,0 +1,350 @@ +:: + + ZIP: 230 + Title: Version 6 Transaction Format + Owners: Daira Emma Hopwood + Jack Grigg + Kris Nuttycombe + Greg Pfeil + Deirdre Connolly + Pablo Kogan + Vivek Arte + Credits: Ying Tong Lai + Status: Draft + Category: Consensus + Created: 2023-04-18 + License: MIT + Discussions-To: + + +Terminology +=========== + +The key words "MUST" and "MAY" in this document are to be interpreted as described in +RFC 2119. [#RFC2119]_ + +The character § is used when referring to sections of the Zcash Protocol Specification +[#protocol]_. + + +Abstract +======== + +This proposal defines a new Zcash peer-to-peer transaction format, which includes data that supports the Orchard-ZSA protocol and all Zcash Shielded Assets (ZSAs) related operations. The +new transaction format defines well-bounded regions of the serialized form to +serve each of the existing pools of funds, and adds and describes a new elements +containing ZSA-specific elements. + +This ZIP also depends upon and defines modifications to the computation of the values +**TxId Digest**, **Signature Digest**, and **Authorizing Data Commitment** defined by ZIP +244 [#zip-0244]_. + + +Motivation +========== + +The Orchard-ZSA protocol requires serialized data elements that are distinct from +any previous Zcash transaction. Since ZIP 244 was activated in NU5, the +v5 and later serialized transaction formats are not consensus-critical. +Thus, this ZIP defines format that can easily accommodate future extensions, +where elements or a given pool are kept separate. + + +Requirements +============ + +The new format must fully support the Orchard-ZSA protocol. + +The new format should lend itself to future extension or pruning to add or remove +value pools. + +The computation of the non-malleable transaction identifier hash must include all +newly incorporated elements except those that attest to transaction validity. + +The computation of the commitment to authorizing data for a transaction must include +all newly incorporated elements that attest to transaction validity. + + +Non-requirements +================ + +More general forms of extensibility, such as definining a key/value format that +allows for parsers that are unaware of some components, are not required. + + +Specification +============= + +All fields in this specification are encoded as little-endian. + +The Zcash transaction format for transaction version 6 is as follows: + +Transaction Format +------------------ + ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++====================================+==========================+========================================+===========================================================================+ +| **Common Transaction Fields** | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``4`` |``header`` |``uint32`` |Contains: | +| | | | * ``fOverwintered`` flag (bit 31, always set) | +| | | | * ``version`` (bits 30 .. 0) – transaction version. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``4`` |``nVersionGroupId`` |``uint32`` |Version group ID (nonzero). | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``4`` |``nConsensusBranchId`` |``uint32`` |Consensus branch ID (nonzero). | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``4`` |``lock_time`` |``uint32`` |Unix-epoch UTC time or block height, encoded as in Bitcoin. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``4`` |``nExpiryHeight`` |``uint32`` |A block height in the range {1 .. 499999999} after which | +| | | |the transaction will expire, or 0 to disable expiry. | +| | | |[ZIP-203] | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``8`` |``fee`` |``int64`` |The fee to be paid by this transaction, in zatoshis. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| **Transparent Transaction Fields** | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``tx_in_count`` |``compactSize`` |Number of transparent inputs in ``tx_in``. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``tx_in`` |``tx_in`` |Transparent inputs, encoded as in Bitcoin. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``tx_out_count`` |``compactSize`` |Number of transparent outputs in ``tx_out``. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``tx_out`` |``tx_out`` |Transparent outputs, encoded as in Bitcoin. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| **Sapling Transaction Fields** | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``nSpendsSapling`` |``compactSize`` |Number of Sapling Spend descriptions in ``vSpendsSapling``. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``96 * nSpendsSapling`` |``vSpendsSapling`` |``SpendDescriptionV6[nSpendsSapling]`` |A sequence of Sapling Spend descriptions, encoded per | +| | | |protocol §7.3 ‘Spend Description Encoding and Consensus’. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``nOutputsSapling`` |``compactSize`` |Number of Sapling Output Decriptions in ``vOutputsSapling``. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``756 * nOutputsSapling`` |``vOutputsSapling`` |``OutputDescriptionV6[nOutputsSapling]``|A sequence of Sapling Output descriptions, encoded per | +| | | |protocol §7.4 ‘Output Description Encoding and Consensus’. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``8`` |``valueBalanceSapling`` |``int64`` |The net value of Sapling Spends minus Outputs | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``32`` |``anchorSapling`` |``byte[32]`` |A root of the Sapling note commitment tree | +| | | |at some block height in the past. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``192 * nSpendsSapling`` |``vSpendProofsSapling`` |``byte[192 * nSpendsSapling]`` |Encodings of the zk-SNARK proofs for each Sapling Spend. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``64 * nSpendsSapling`` |``vSpendAuthSigsSapling`` |``byte[64 * nSpendsSapling]`` |Authorizing signatures for each Sapling Spend. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``192 * nOutputsSapling`` |``vOutputProofsSapling`` |``byte[192 * nOutputsSapling]`` |Encodings of the zk-SNARK proofs for each Sapling Output. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``64`` |``bindingSigSapling`` |``byte[64]`` |A Sapling binding signature on the SIGHASH transaction hash. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| **Orchard-ZSA Transaction Fields** | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``nActionsOrchard`` |``compactSize`` |The number of Orchard-ZSA Action descriptions in | +| | | |``vActionsOrchard``. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``852 * nActionsOrchard`` |``vActionsOrchard`` |``OrchardZsaAction[nActionsOrchard]`` |A sequence of Orchard-ZSA Action descriptions, encoded per | +| | | |the `Orchard-ZSA Action Description Encoding`. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``1`` |``flagsOrchard`` |``byte`` |An 8-bit value representing a set of flags. Ordered from LSB to MSB: | +| | | | * ``enableSpendsOrchard`` | +| | | | * ``enableOutputsOrchard`` | +| | | | * ``enableZSAs`` | +| | | | * The remaining bits are set to ``0``. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``8`` |``valueBalanceOrchard`` |``int64`` |The net value of Orchard spends minus outputs. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``32`` |``anchorOrchard`` |``byte[32]`` |A root of the Orchard note commitment tree at some block | +| | | |height in the past. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``sizeProofsOrchardZSA`` |``compactSize`` |Length in bytes of ``proofsOrchardZSA``. Value is **(TO UPDATE)** | +| | | |:math:`2720 + 2272 \cdot \mathtt{nActionsOrchard}`. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``sizeProofsOrchardZSA`` |``proofsOrchardZSA`` |``byte[sizeProofsOrchardZSA]`` |Encoding of aggregated zk-SNARK proofs for Orchard-ZSA Actions. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``64 * nActionsOrchard`` |``vSpendAuthSigsOrchard`` |``byte[64 * nActionsOrchard]`` |Authorizing signatures for each Orchard-ZSA Action. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``64`` |``bindingSigOrchard`` |``byte[64]`` |An Orchard binding signature on the SIGHASH transaction hash. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| **Orchard-ZSA Burn Fields** | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| ``varies`` | ``nAssetBurn`` | ``compactSize`` | The number of Assets burnt. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| ``40 * nAssetBurn`` | ``vAssetBurn`` | ``AssetBurn[nAssetBurn]`` | A sequence of Asset Burn descriptions, | +| | | | encoded per `Orchard-ZSA Asset Burn Description`_. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +| **Orchard-ZSA Issuance Fields** | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``varies`` |``nIssueActions`` |``compactSize`` |The number of issuance actions in the bundle. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``IssueActionSize * nIssueActions`` |``vIssueActions`` |``IssueAction[nIssueActions]`` |A sequence of issuance action descriptions, where IssueActionSize is | +| | | |the size, in bytes, of an IssueAction description. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``32`` |``ik`` |``byte[32]`` |The issuance validating key of the issuer, used to validate the signature. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``64`` |``issueAuthSig`` |``byte[64]`` |The signature of the transaction SIGHASH, signed by the issuer, | +| | | |validated as in Issuance Authorization Signature Scheme [#zip-0227]_. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ + + +* The fields ``valueBalanceSapling`` and ``bindingSigSapling`` are present if and only if + :math:`\mathtt{nSpendsSapling} + \mathtt{nOutputsSapling} > 0`. If ``valueBalanceSapling`` + is not present, then :math:`\mathsf{v^{balanceSapling}}`` is defined to be 0. + +* The field ``anchorSapling`` is present if and only if :math:`\mathtt{nSpendsSapling} > 0`. + +* The fields ``flagsOrchard``, ``valueBalanceOrchard``, ``anchorOrchard``, + ``sizeProofsOrchardZSA``, ``proofsOrchardZSA``, and ``bindingSigOrchard`` are present if and + only if :math:`\mathtt{nActionsOrchard} > 0`. If ``valueBalanceOrchard`` is not present, + then :math:`\mathsf{v^{balanceOrchard}}` is defined to be 0. + +* The elements of ``vSpendProofsSapling`` and ``vSpendAuthSigsSapling`` have a 1:1 + correspondence to the elements of ``vSpendsSapling`` and MUST be ordered such that the + proof or signature at a given index corresponds to the ``SpendDescriptionV6`` at the + same index. + +* The elements of ``vOutputProofsSapling`` have a 1:1 correspondence to the elements of + ``vOutputsSapling`` and MUST be ordered such that the proof at a given index corresponds + to the ``OutputDescriptionV6`` at the same index. + +* The proofs aggregated in ``proofsOrchardZSA``, and the elements of + ``vSpendAuthSigsOrchard``, each have a 1:1 correspondence to the elements of + ``vActionsOrchard`` and MUST be ordered such that the proof or signature at a given + index corresponds to the ``OrchardZsaAction`` at the same index. + +* For coinbase transactions, the ``enableSpendsOrchard`` and ``enableZSAs`` bits MUST be set to ``0``. + +The encodings of ``tx_in``, and ``tx_out`` are as in a version 4 transaction (i.e. +unchanged from Canopy). The encodings of ``SpendDescriptionV6``, ``OutputDescriptionV6`` +, ``OrchardZsaAction``, ``AssetBurn`` and ``IssueAction`` are described below. The encoding of Sapling Spends and Outputs has +changed relative to prior versions in order to better separate data that describe the +effects of the transaction from the proofs of and commitments to those effects, and for +symmetry with this separation in the Orchard-related parts of the transaction format. + +Sapling Spend Description (``SpendDescriptionV6``) +-------------------------------------------------- + ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+======================================+============================================================+ +|``32`` |``cv`` |``byte[32]`` |A value commitment to the net value of the input note. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``nullifier`` |``byte[32]`` |The nullifier of the input note. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``rk`` |``byte[32]`` |The randomized validating key for the element of | +| | | |spendAuthSigsSapling corresponding to this Spend. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ + +The encodings of each of these elements are defined in §7.3 ‘Spend Description Encoding +and Consensus’ of the Zcash Protocol Specification [#protocol-spenddesc]_. + +Sapling Output Description (``OutputDescriptionV6``) +---------------------------------------------------- + ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+======================================+============================================================+ +|``32`` |``cv`` |``byte[32]`` |A value commitment to the net value of the output note. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``cmu`` |``byte[32]`` |The u-coordinate of the note commitment for the output note.| ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``ephemeralKey`` |``byte[32]`` |An encoding of an ephemeral Jubjub public key. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``580`` |``encCiphertext`` |``byte[580]`` |The encrypted contents of the note plaintext. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``80`` |``outCiphertext`` |``byte[80]`` |The encrypted contents of the byte string created by | +| | | |concatenation of the transmission key with the ephemeral | +| | | |secret key. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ + +The encodings of each of these elements are defined in §7.4 ‘Output Description Encoding +and Consensus’ of the Zcash Protocol Specification [#protocol-outputdesc]_. + +Orchard-ZSA Action Description (``OrchardZsaAction``) +----------------------------------------------------- + ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+======================================+============================================================+ +|``32`` |``cv`` |``byte[32]`` |A value commitment to the net value of the input note minus | +| | | |the output note. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``nullifier`` |``byte[32]`` |The nullifier of the input note. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``rk`` |``byte[32]`` |The randomized validating key for the element of | +| | | |spendAuthSigsOrchard corresponding to this Action. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``cmx`` |``byte[32]`` |The x-coordinate of the note commitment for the output note.| ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``32`` |``ephemeralKey`` |``byte[32]`` |An encoding of an ephemeral Pallas public key | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``612`` |``encCiphertext`` |``byte[580]`` |The encrypted contents of the note plaintext. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ +|``80`` |``outCiphertext`` |``byte[80]`` |The encrypted contents of the byte string created by | +| | | |concatenation of the transmission key with the ephemeral | +| | | |secret key. | ++-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+ + +The encodings of each of these elements are defined in §7.5 ‘Action Description Encoding +and Consensus’ of the Zcash Protocol Specification [#protocol-actiondesc]_. + +Orchard-ZSA Asset Burn Description +---------------------------------- + +An Orchard-ZSA Asset Burn description is encoded in a transaction as an instance of an ``AssetBurn`` type: + ++-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=======+===============+=============================+===========================================================================================================================+ +| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. | ++-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ +| 8 | ``valueBurn`` | :math:`\{1 .. 2^{64} - 1\}` | The amount being burnt. | ++-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ + +The encodings of each of these elements are defined in ZIP 226 [#zip-0226]_. + +Issuance Action Description (``IssueAction``) +--------------------------------------------- + +An issuance action, ``IssueAction``, is the instance of issuing a specific Custom Asset, and contains the following fields: + ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+===========================================+=====================================================================+ +|``2`` |``assetDescSize`` |``byte`` |The length of the asset description string in bytes. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``assetDescSize`` |``asset_desc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | +| | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | +| | | |or later. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``varies`` |``nNotes`` |``compactSize`` |The number of notes in the issuance action. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``noteSize * nNotes`` |``vNotes`` |``Note[nNotes]`` |A sequence of note descriptions within the issuance action, | +| | | |where ``noteSize`` is the size, in bytes, of a Note. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +|``1`` |``flagsIssuance`` |``byte`` |An 8-bit value representing a set of flags. Ordered from LSB to MSB: | +| | | | * :math:`\mathsf{finalize}` | +| | | | * The remaining bits are set to ``0``. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ + +The encodings of each of these elements are defined in ZIP 227 [#zip-0227]_. + +Reference implementation +======================== + +TODO + + +References +========== + +.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ +.. [#protocol] `Zcash Protocol Specification, Version 2021.2.16 or later [NU5 proposal] `_ +.. [#protocol-spenddesc] `Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.4: Spend Descriptions `_ +.. [#protocol-outputdesc] `Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.5: Output Descriptions `_ +.. [#protocol-actiondesc] `Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.6: Action Descriptions `_ +.. [#zip-0222] `ZIP 222: Transparent Zcash Extensions `_ +.. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ +.. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ +.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection `_ From be596bbe94d903611dfb7fb16a92cf766dda61d6 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Mon, 16 Oct 2023 16:37:48 +0530 Subject: [PATCH 31/42] Switching the issuance authorization scheme to using Bitcoin Schnorr over `secp256k1`, as in BIP 340. (#40) We switch the `issueAuthSig` scheme from RedPallas without key re-randomization to the Bitcoin Schnorr signature (as described in bip340). We also perform notation changes of `idk` to `imk`, and adjust the derivation of the issuance keys to fit with the updated Issuance Authorization Signature scheme. --- zip-0227-key-components-zsa.png | Bin 61500 -> 44217 bytes zip-0227-key-components-zsa.svg | 67 +++------ zip-0227.html | 238 ++++++++++++++++++++++---------- zip-0227.rst | 99 ++++++++----- 4 files changed, 248 insertions(+), 156 deletions(-) diff --git a/zip-0227-key-components-zsa.png b/zip-0227-key-components-zsa.png index 4b6b017635100b27a61f3bfe2123f84a3f1544f1..c7d2fd6fca1b4668436eb8412c5fc01a2c9f21b5 100644 GIT binary patch literal 44217 zcmeFYhf`Bu)b~qAlww3gI!1aGLa!ny0@9mw5C|QlgOq?MM5$sZp(9N?NbgaaKq%5X z5d@@$9w3C=_zUPESCcmdI{S3Xpet~vAjzochfg&!R zZoc+*uN_6ae4H}(6$q!{B+^h*F$&7sT?%aGGKQZYqUAwIBGtQOT$`*WYDRhh|6#zx zjd#JlIHpI$+Zk5$Rkr58rX-zUk`F1!^u=%Ry?t)rb3a<*`1)GLAKn?(R$hj#3_-s` zZw7BiE?E8c^Y_=z#$+Am{CvTskxclsK5}Zj#rfY~6Lt#b{~8UPs3o5N+gLbq-#O{O zrfjjX|Fe^veV)p{Og{o@!#>2Or$jbZ7K!*?}`4`M_d~JJC6Q$iu`{s zjF@k!^|a54L`i%Gz8Z$UR0eL02AB~d84%>uMxAUz1UOW)-E>hxy1*|cQrGA11eyh+MSyy>u!EOL_#utOs1RqMJlI@181r4RBO7HD$V z;5FZO^FTQw7Nd?~)s){`WhHk9hz4!o>1$M&>GJz}Qu z<*7V8c+4RY#2`F)UWdGzxra4llwqH(wwnS)syl8N?`f6V0atSnf{~ksZ(Too%N-b_ zKEs0zO&vc=bO2ukqG~0}uWZ0Ml7{P_3Z?#C{w@GRR7LzMgRVgxoC89g`$ndbsFSeh zc6%p|AWgNw-OyQ5nfOED!S1YVc!walcM&8XTHrjUPmvse8)^zO;K=`%-oJPhoz#%b;MzVZS8Kes@J$i1yl3<@Y*+-gw z&Dnj52*!y%>ybmGm3j@s%O-g0^rzx+UCt2EB`F}#N#+L&z>NeyUNf&jgPkQhry5q& z2q#id1Ti*==2Lut#t_>ON$mv9?0^)BT>nAAd&kEBv@I{b*2>$1q6Ll zi7t(WHW`q}TTwFgUAbnQ36`n?YKfY4hXqQ&8*CtBb`95|$5Dk+8GUPkzne&{v0OF% zH?YkN&9LOF!>ZJU#UBwlceTrM?s2gC%iFeTxPy$fBfr$e#Lp!{wIk>wiXU)rkmlsV zJx1FopsV(Xw)9R&0V8RN&O|4-zZ-|G$}l$SdJk4;wmC+n;gO{?V5`g&LW1#nxhaK; z=@3=x>5g=gbPs&^TH=5WwTNtQ@Z!LbosqB;D{!n$LsqCL8M1M-Pz?@6LqEl68?F4BhM}Ett`KRW84^bD#ut5zECWC+SDe}fG)OI;mLUH5S&D6d z;h=vY%K-*?)$a%MN7SO94t%P;$33ub)4ES(#C@>DKAR-&uwydlwS9zaZyvI55E`9_ zpFz_XTko zS8Sq}OpnFRTk0r>4GjeS!&eZ^w*$gVV#=zqWJy~5bP(T|b{kXgT-r7RfoT6ea%SKw z7EPV#O1H)q(jZT8c$oP6k5HP(5>nkSWKX8c%rN4boo_`Qz#iPPzwE1m_HlfgyFa)>IHnsR;ly5XHNUk!|K0eFTW z+5?BnsurkBqEEQ;M6m$_V8KwC9+3z-UQpcWydwj>v-sEFUM-X($O(L1wAHLScn20L zHcCue$dktez!#pBT~Z%>))zjMW(`Vx_yBlDZmo7Pe8OvK#R}*r zMUNo!2Us4yvPWerin8e$w)Y}JhGvw<^5MY?No(#}E$ke$yAzx%tE!8g$7KSgurgU=#T>qqW&u*}p6KSB&kU6ERVR6?*193lSQ;Ww3MtieB83-wwn|pei&% zO{uPkXM^9_v;C^+QYUsJ@*=HrGmEy7u=-3oSW9;R5xTXT@NJPQl;~wguQy3^E7)e! zbZ74=+`DA>5KWXba}cJp(Y9-IE$)EFl$;!8ZeK$vD<-BC$9j7m*Db&uL?R+0f-@uv ziQ*>h`^4)8wj~*1yT4W+Y~qK1I9X6Oe<^+;ZP;p$Zv|)XI5i_}oMjSicFY2KQQx9Z ztI7AJ2fnpKFEt$(*3pPF)r8u6rzwes=BcME%!3Clv|R-_i_ndgu`fppud{|D)TJwq zLp5~^O2gIrNsldHTgx=q3n2I3T8EysuFiRUG{Tfu{~F?^e^xEAyS4{g8RF~jU^`Ds zUD@p5Qw%G58WB)TtMuG>*aA4a=UecW?c7tSNS- zK8Pdpx%PIqiKY34n~$Se(W@DI*K=RmS@djF+HW?i$E@fZYW=O8B-@Y^=w{VS{2Zp%QPky=Dy2g6r*!nZuv}pT;b)But zHcidmwzJOXRLt4qhb`AHyTxo4Yj8$N$D1*%$CC+43tAy(vbp2Fg+soWy{&fMmgeS) z^VkUs&22R`)@LrlrES$&qzW=1QJ2}J6d2{a+%f-$eUVtGu3C@k!&eQB>uknqyE-oG z>>GD9IY~6%w~xeey{jlLc9)yh0MzoXKdAS-7k?`f2RdHVxVx^35OiJcDwn&CiNNTY z*W%}EMinC%se`Ml;xH9=CZ;avGz|vrtTW*=lDh>d(Ah}w&i0X7xa^#n&AeQ60F_R^ zK#@l~Cy;%zM#u0OEhfrspp6f98a{gt`>XaUgAdT5?=6a)$BmNGY&cZKye_3~6>QGzr$GBW| z9JDp$kDpbp9ypq*s}A}eW=U`Lcevv?TysBxM}z6e=NO7jE2Mfs!S6B%TwOv~Fq_Dy zjC)|`i*b${R)9mr!AEgCZu)Nw+LM!w_IP3UR@dqZ=5CsEMUVxlifFY?!3upsp1pV? ztD!w%F7kyeI$Xu2mt#X>Fc34Uf9p12l+v1zkkRphOfBb|mRL18w}vGbl-SO9BW6ZP z*)8gpq+slTsKGWy?&{u0{Z1REZp$1~AeX8N)}`NvJYT^jU$ID{e*M0N+zfb=X&rO> z?I2M-MpOvsbfQJd_)i}fHxU!8ow7T*lGfL>0Y{R`-Ru4h;P`ct(_;w7iz=B4-!KgS zoLG1v54pb{D6J#uh^G6hdvK|X3WJ4mnHqN$Vf9Irf3X*Osu2;{VNH{3}LgK%Iez7k=vJ-hQnvEOpl(WCp+cs zgA_|Q(s?J{13{7>_;`a8u4nb8U9{OXT@*bu7vH=bKGRm^xCi3;#o;)eR=jeUg2;@} z4ryFS8aH3sPaYSgb-+uNubb4QOP(SPAO=|M0ZAMv+hdx-bXM(teeqTLLi zV`@T|w7c@jGTD_^tPeiU2X9g5)FvFk(J*_qu9{$h39-JZQ1YAEi}@oa>cPU&=Z$=T zw4T6L+o`*>l-u~1Xb&$pJ`6oeBOa65b=Wk$YcE!#F@$qhZP`bEIf1z#zpt*YesdMA zvnFC>Ok?oPujdP|>g`@Tj7!&V-@LDz*K%hP+yWmzlJoH-%b*Wmh^LsK{0p5!aiR#*G_>Id)kbc!`ZD2`qv^wJosC$-wZcO)5?2} zo^`p%TpyA)1_yOZ&5$lgvSNNlhq0R0?e$77SW)eo)$IiccUDsoKh_jY(sFIQFdEuv z7eO4wJXnx0K2fHrF!n_zO1eWdRN=~FHDTq2?UR&H5x2U;PTZbWKjsPHzEga~)T0VN zJ?#k{Jl|xLs<_l1>|U$lcz z(ep|2+ftICBR;q4?{BwIV|@%i^G+9xl%CvsIP^NdIFz|NT0p{IOIa$7MxEJ+kSYXF z9n2vu#sAyQBkdfxo+a{%czz_0Zh-#$|ia22NSp9TL!u z^;ccFXZY62V{)B;P6(J#75$_k8QwLDESRqnb(wNZpwM_&D&Vk^7f!8!*o;i84?~RYT7&Zr0)B@lz8F^(nF(`cJ@v_=h>O49Z7K0*JZCvQwnq_MiEs}g) zw#)#q8ATS~gmk5ex8Lcw8{};K%R}7V{WP6QV@TXrU(NDIM8p%vu^lhlp!XX(sH9Ts zA<}v(8LP!Zu@K31$8+1W_+XAzAKTFk%na+%8>^@L;OIZUzPjs#Kf`NP4Kcfd_1a&Q_SM&U5Df9#DKLsqzXyH~nOzR^_+O&{<6?EUv zC`)%_#bd-h7LBZO;WKo>Xocupymv~1D@A0tYr^q&q`PZaR$Qe;1!(tJTO)<@;FDyz z5P9dcPhdIWejj{rj5dGnw-$I6^GJmlOx!FH?BnmVsIgw%Bpc5X!Ow*ue zvg@#Vc&qqi=%G5Sozvf>V3DqGpK3;}N0)zq2Lgk4SKZQJ9?YjtHZN^8xrS|UcDI3! zC9TMr-Z*Y}z%OvfP?4foG(DgFxq7zMDlbcg~#1&h!y7P zU=Ov)h8qbJUo!noqaFKWF8M{85)Oy+IBbJ@(N6~b(kAk?^D124bPlxAor2=Ca^T%y z%fB-xvJ}H6;#1bd{*@gbjT}-@Dw%sb;TBqa-R>Fgvj^e$gK~(+OMHxQ0+pkTQMMgu zXfkZWA_By6wr~;b!SHFVWJCjqokelQ#B#7 zv$DAj3_RGhJDit(7GC;sFAw_@CU6O;+FFGgF~K*L8UA0elD^6bVcLcAb&7B2vo#ez5NO&h%yBn-qRF` z=`QsW>u^#NVil*r?M;qu(H4n!oc?@o1(pku*d>wR#B(GVUkB^Zr(}XYCmsL5v zMg*2I;IQHYz9v>H{+l~j$o8t==W7ldMF4LO)F~o=5(8!iYolTT-n|kljNFx6gy6v} z0BkHFV~XY;h#Dt9c@MuRg7X`92oNvImx(oMcR!piMEZv}L1*JH$&#$#Bkz*5D|<~z z>Hd~ywF83gp5jG9xqxTG$W|t{JlU~>ylCoEE16saCMGGh*A}+YD4XbZ2*Y~Ti;`k4 z4?Qp~e7xl&6c;gZ`35WzrtT5ruF&}#M^)Kt{1h85xsWwCCTOd^Ets#(u!8%l%OyK! zNAHn9!#(=Kit}JItgE&dU1rRl=-Qa4K3VaNOvVneV|a-)rmJlYWi4^sSS5HPY~M}1 z&Qt2WhMWGcE>2Kp^p5s=mWM9RiNkTWXQ|BhiUV-?V6djUgp|&{-csF{Pjw*U&Fu4J zS!OO8li}tA!R;vOCQ{uUfuFYl%85|JaYyKhW_&aJB{{IxbChOapfDS z&_=s9tX_1ngv<7`rO6B>$0=BuKS*jmL3ixoKry-0#Lfj3M+$DD(w zHOdE4gte?xch6ZlI5)Y_oKRNNz74?Y6*sq<4!g!i5R&#ldASW%&A^GU2++gTxiBj1 zvnkla-&e#-1-Tl&--fD?;KXPwRs8zs05cZ3fbzt0~l84ES&` zZ5d}^rFPNDA>bD*(Kd@OM`w%5`!;t01X5J#(mGyT7)hjC6ux^shxkBhojd$kW#UXL zaz)!`VMzRVyp>eFXYFh5-Wn3Qi#8rR$#lP}DpQa`JHOncCvD7B4b%Bp?4o9O#IV_l z{b{*9x@PpEfl_^9EJq7er#!dG*Y71ss-so`05qr^BijW*x`W6-r;YAN?FdtS4(F`y zKhf6D&3g%jNC}-3R`lki^7F+T3gV!hrsA$Dgsx} zq4y8L5hC9j~|gmz?)%8AQqGp%f2 zcpP;?XUWd>x|Nn?9nRoe)OROGB5nh2eZ{+Pf;SL$4*|6dHNnG;+6-fg{Fny0sBnmO zWZN+COKIBJ0v~49PKUBn8g;rj>_AAkhSYklVZn8o-+tp0 z#>eL+l-foP;d2(m%o5;`z`;pNbSyMi@9623>uh}ppjPm}K{F}8s_oDU!Hcz)Prekv zF_N}5W=H1TOb`MGy$_(}E`Kx8eeyM#9wT7^OU)rlOxniImCS|!Ql<~USzuzLFe<^;t0B- zdEkY@5ER2_EnPHqcV+yZ@28YD?vECAs`osF%L*kOg`u3Ir9bYGTqyvpli&?qr>+}u zQIV!~6^tV_5iVAAac+Eu%hN8~-+#ewd=ud$<4#)KU_X64IM!bWT!lnpz#HV+EXI!a z11gCv)8T>jGM$CSS%hU}M~-eAKZe~{*zhp6vuh{0+k?2hnNR|f=cfxbH8c;Eu1IZE z4SVxM3Y6e2GQeeu z(0nk5o1VFKu5sN+Nh#fpMf!6cwJf@;q;a-$X4J@bM?60REJm!>zh*dz^uFTQfjmz_ zVy-6#nYD^926KUkEpxmZ8@WOkge!p^&UOndxe*icay!^@7}I*-xu537<-A%L;uggz z7z(Y7Y-JVlcmsMN_30sO&@{W0jG4ANIy+k%F8j(ubNp9{9v)sg4KW+W_UqeRglJ0^ zt%||azWVYT23^Y!tEMcQf-;dt78s1JnQp_U#!;l;!&Mp72gwDrYUy+QNAX4U6V2P6 zl7nFmT7+LnpDsgYRKgN4$$vb_TCStmXJoo4SaU)5X%7G)3ma{rUzfMef{T(up~GgW zHZJVzD`%VPJzFp$6cr-3?`X_OF-(e#{RP#>DQ+6Y#{AG^BZuPH*w|Zes-jn^pqfSU zilx9^kkj8;WeSrW`7=@G#*1~X(M>PrGwi&}Ijyd%%to8}u08E*^X~9e18~*-#>8M4 zEAhl3o9FbAWrekso5xwOe9eLoZr@rWeg;b=*^fg=u%hqTc4gQrwb@}!C9}%uq}=h) z=)JCq8l05mLXMdB%CBJrDa&Aoi@#@^(%DRetYm*jGk8JJ+;XAXRpwfYrEw+oj?m7f zZ?5#8AYJ#_{hE8Z7e6xgyht{t-P>$$=5AFgVuSl`EC@5(E!~Rr2d^n@5mw`?!W+&> zWH9PeSk+h1?}}Y`XO*T%^8z(1h6VBYTgg*pAT0%L#T=Nw$oRGR_MLE*evqz_EXSGW z%gS2m$EhNd)n0O}j;%wHl|yE&)f{A&%YN+ut7LfP8N7&c(1yiSXgQ5$sk%f998McF zDzO(nR`Wp&o!`Q8&R11rbh6Wzr|T3R%{_^X(6cJ{U$FT^8vW5|p=#(L|FL21jUY?# zb+KoWPg#WkVF}hAZ^WK#m7c(m?wVYJ8W97W+`Vign|@k$A@{+g;{;!6iJWOTiI*mFSuS3KW0SGF`Kk;NOtpzAB!SX z`4w4O#{*`2(xvG3HbG$wxW?sYE;y^j`qdjcM4jTh!$KN#9NKM%%i7_$c9(8DL|on+ z)1GvgtS+7`zg3vMq(?RX={G3;F|J`s;^~?LLFVKGQ4S-;RKV=y?Ojo8B418egY~C3 z>(aM(IkmCP>@w9Zl<*5Slnd;!i75}gb2FQ>rrJX9B#gtYR;NpzNm;GT1v>Ushjc#^ zUI}hb;(9d3=>pd`e_ZUksA>()(cNOcG8#PpwIeUnXP|k8Vi_QZuguKO1oYeHF;l(;WkE=|h zsmUwXs8lYw_ZK3JZ)uKq;cbZQf!*Mvq!^Q~%GR~(lw?-)4y@`|L2LREONgG7?%wRA zAnH%+v~>oli{Tc{ullfwM!fd%?rr;fhCW%lAlKU<(281%uC?M|KuQ~5o%ODXm78|) zd}|le&=DE6&r!|tU7YxF2#o7PzkyHei)mQ|ON1AuOMji8P(y7jarDi}DLtDdJ{NL) zmZl$`NJtDT6(M+0?g%+!Mxs$tLb9qQH=A2%{M;`dDypFkuaGdqmSK# z;%P?+%wx@axNN@4Pb}gxA3O|-soEpP8LsFMbfDw140|LctAMw_7_{VS#%_85ii>_PE z?~d}Wy(pVr2kn=-LQj zJr(ZA9YDrLyJLL^gPHz_3<^mH5+@R~tG9GEeYNh&zVl9o$IjjBlq6k}*m}+gAFfjm6mYwvZSasokArgfAZ^!h>JKdsE-% z&EgBHclh@{R&2`7=h|w!&t-M7hSAUVALAx7AthXV*K7wJ{3jcqxd?EWiI8!G?SmTj zb(Njz<=?l>z14bHHOXDVG{Kjd{8VVqpR~ogvCvHtykXrS1B_qGD{H&9*n%O{qT0Og z`gbR|wNJ~mgRW0t(4K1hn(E5Kn5BRXaLlLLc8}IT=o=G@XVJ;Wwg+K9v-6n6gXjiN+bJCRhJmR0PHRB21ouB^O)$I6 z|HyLN0!{1cnhz`E7u2mZTmOnw@GBmCs4@N#!Ag@{nDUGFE1mcif-}n8RkK3c^{s(M zvdNqOj!qFU?NuT03~FIjM5U&Tb)wIc>oxzObLK8;J<$@nbeKNm?ki38N@jMwn1 zR4$E-p9DzA#qo&BwjcweOQ8f(b^LWx1lVYI9>;;Iq0&gEAk@}1%=y)N)*?%0Dtssp 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

    ?los{j?4zjQ_2VdM<_aHkIzUnZQY+d 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 GZv8*k2+j%s literal 61500 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

    >VYr?NutM-2%d~5ml(Pw;S>3|&1HFmxZ=!nx} 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 validating keyIssuance derivation keyZSA Key ComponentsiskimkikIssuance authorizing keyIssuance master key diff --git a/zip-0227.html b/zip-0227.html index 7b4df6c61..b9cb52bcb 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -43,7 +43,7 @@

    Abstract

    -

    This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    +

    This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the Orchard-ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.

    Motivation

    This ZIP introduces the issuance mechanism for Custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 4) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 4.

    @@ -73,14 +73,11 @@

    Specification: Issuance Keys and Issuance Authorization Signature Scheme

    -

    The ZSA Protocol adds the following three keys to the key components 17:

    +

    The Orchard-ZSA Protocol adds the following keys to the key components 19:

    1. The issuance master key, denoted as \(\mathsf{imk}\) - , is the key that is used to derive the other two keys.
      2. -
    2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as - \(\mathsf{isk}\) - . This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
      3. + , is the key that is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
    3. The issuance validating key, denoted as \(\mathsf{ik}\) , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
      4. @@ -88,38 +85,54 @@

      The relations between these keys are shown in the following diagram:

      -
      Diagram of Issuance Key Components for the ZSA Protocol
      +
      Diagram of Issuance Key Components for the Orchard-ZSA Protocol

      Issuance Authorization Signature Scheme

      -

      We define the issuance authorization signature scheme +

      We instantiate the issuance authorization signature scheme \(\mathsf{IssueAuthSig}\) - similar to - \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) - , the Orchard spend authorization signature scheme 22. Specifically, we instantiate + as a Schnorr signature over the + \(\mathtt{secp256k1}\) + curve, as described in BIP-340 17. We define the constants as per the + \(\mathtt{secp256k1}\) + standard parameters, as described in BIP 340.

      +

      The associated types of the \(\mathsf{IssueAuthSig}\) - as - \(\mathsf{RedPallas}\) - without key re-randomization using generator - \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) - where - \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in the Zcash protocol specification 18.

      + signature scheme are as follows:

      +
        +
      • + \(\mathsf{IssueAuthSig.Message} = \mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}\) +
        • +
      • + \(\mathsf{IssueAuthSig.Signature} = \mathbb{B}^{\mathbb{Y}^{[64]}} \cup \{\bot\}\) +
        • +
      • + \(\mathsf{IssueAuthSig.Public} = \mathbb{B}^{\mathbb{Y}^{[32]}} \cup \{\bot\}\) +
        • +
      • + \(\mathsf{IssueAuthSig.Private} = \mathbb{B}^{\mathbb{Y}^{[32]}}\) +
        • +
      +

      where + \(\mathbb{B}^{\mathbb{Y}^{[k]}}\) + denotes the set of sequences of + \(k\) + bytes, and + \(\mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}\) + denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification 18.

      +

      The signing key generation algorithm and the validating key derivation algorithm are defined in the Issuance Key Derivation section, while the signing and validation algorithms are defined in the Issuance Authorization Signing and Validation section.

      Issuance Key Derivation

      -

      The issuance master key is generated by choosing a bit sequence uniformly at random from - \(\mathbb{B}^{\mathbb{Y}[32]}\) - , like the Orchard spending key 20.

      Issuance master key generation for hierarchical deterministic wallets

      -

      The issuance master key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

      +

      The issuance master key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.

      Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\) .

      -

      As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the +

      As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the \(\mathsf{CDKsk}\) function for Orchard child key derivation from ZIP 32.

      -

      We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as +

      We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\) . We fix the path levels as follows:

        @@ -138,7 +151,7 @@ ) following the BIP 43 recommendation.
      • \(coin\_type\) - : Defined as in ZIP 32 14.
        • + : Defined as in ZIP 32 14.
      • \(account\) : fixed to index @@ -151,25 +164,86 @@ \(\mathsf{imk} := \mathsf{sk}\) .

      -

      Derivation of issuance authorizing key and issuance validating key

      -

      The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 20, as described below.

      -
        -
      • The issuance authorizing key is derived from the issuance master key, - \(\mathsf{imk}\) - , as a private signature key. The function - \(\mathsf{PRF^{expand}_{imk}}\) - is as defined in the Zcash protocol specification 19:
        • -
      -
      \(\mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{imk}}([\mathtt{0x0a}]) )\)
      +

      Derivation of issuance validating key

      +

      Define + \(\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \to \mathsf{IssueAuthSig.Public}\) + as:

        -
      • The issuance validating key is derived from the issuance authorizing key, - \(\mathsf{isk}\) - , as a public verification key:
        • +
      • + \(\mathsf{ik} := \textit{PubKey}(\mathsf{imk})\) +
        • +
      • Return + \(\bot\) + if the + \(\textit{PubKey}\) + algorithm invocation fails, otherwise return + \(\mathsf{ik}\) + .
      -
      \(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
      -

      This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

      +

      where the + \(\textit{PubKey}\) + algorithm is defined in BIP 340 17.

      +

      It is possible for the + \(\textit{PubKey}\) + algorithm to fail with very low probability, which means that + \(\mathsf{IssueAuthSig.DerivePublic}\) + could return + \(\bot\) + with very low probability. If this happens, discard the keys and repeat with a different + \(\mathsf{imk}\) + .

      +

      This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

      +

      Issuance Authorization Signing and Validation

      +

      Define + \(\mathsf{IssueAuthSig.Sign}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \to \mathsf{IssueAuthSig.Signature}\) + as:

      +
        +
      • Let the auxiliary data + \(a = \mathtt{[0x00]}^{32}\) + .
        • +
      • Let + \(\sigma = \mathsf{Sign}(\mathsf{imk},M)\) + .
        • +
      • Return + \(\bot\) + if the + \(\mathsf{Sign}\) + algorithm fails in the previous step, otherwise return + \(\sigma\) + .
        • +
      +

      where the + \(\mathsf{Sign}\) + algorithm is defined in BIP 340 and + \(a\) + denotes the auxiliary data used in BIP 340 17. Note that + \(\mathsf{IssueAuthSig.Sign}\) + could return + \(\bot\) + with very low probability.

      +

      Define + \(\mathsf{IssueAuthSig.Validate}\: : \: (\mathsf{ik}\: : \: \mathsf{IssueAuthSig.Public}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \times (\sigma\: : \: \mathsf{IssueAuthSig.Signature}) \to \mathbb{B}\) + as:

      +
        +
      • Return + \(0\) + if + \(\sigma = \bot\) + .
        • +
      • Return + \(1\) + if + \(\mathsf{Verify}(\mathsf{ik}, M, \sigma)\) + succeeds, otherwise + \(0\) + .
        • +
      +

      where the + \(\mathsf{Verify}\) + algorithm is defined in BIP 340 17.

      +

      Specification: Asset Identifier

      For every new Asset, there must be a new and unique Asset Identifier, denoted @@ -181,7 +255,7 @@ is the issuance key and \(\mathsf{asset\_desc}\) is a byte string.

      -

      A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, +

      A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, \(\mathsf{AssetDigest}\) , which is simply is a \(\textsf{BLAKE2b-512}\) @@ -206,11 +280,11 @@

      Define \(\mathsf{AssetBase_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\)

      -

      In the case of the Orchard-based ZSA protocol, we define +

      In the case of the Orchard-ZSA protocol, we define \(\mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 18.

      + is defined as in 20.

      The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

      @@ -348,11 +422,11 @@
    4. vIssueActions: an array of issuance actions, of type IssueAction.
    5. \(\mathsf{issueAuthSig}\) - : the signature of the transaction SIGHASH, signed by the issuance authorizing key, - \(\mathsf{isk}\) + : the signature of the transaction SIGHASH, signed by the issuance master key, + \(\mathsf{imk}\) , that validates the issuance .
      6. -

      The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 24.

      +

      The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 26.

      @@ -391,7 +465,7 @@

      Issuance Protocol

      -

      The issuer program performs the following operations

      +

      The issuer program performs the following operations:

      For all actions IssueAction:

      • encode @@ -411,16 +485,18 @@ as decribed in the Specification: Asset Identifier section.
      • set the \(\mathsf{finalize}\) - boolean as desired (if more issuance actions are to be created for this Asset Identifier, set + boolean as desired (if more issuance actions are to be created for this + \(\mathsf{AssetBase}\) + , set \(\mathsf{finalize} = 0\) , otherwise set \(\mathsf{finalize} = 1\) - )
        • -
      • For each recipient + ).
        • +
      • for each recipient \(i\) :
          -
        • generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is +
        • generate a ZSA output note that includes the Asset Base. For an Orchard-ZSA note this is \(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase}, \mathsf{rcm}_i)\!\) .
        @@ -429,12 +505,12 @@

      For the IssueBundle:

        -
      • encode the vIssueActions vector
        • +
      • encode the vIssueActions vector.
      • encode the \(\mathsf{ik}\) - as 32 byte-string
        • -
      • sign the SIGHASH transaction hash with the issuance authorizing key, - \(\mathsf{isk}\) + as 32 byte-string.
        • +
      • sign the SIGHASH transaction hash with the issuance master key, + \(\mathsf{imk}\) , using the \(\mathsf{IssueAuthSig}\) signature scheme. The signature is then added to the issuance bundle.
        • @@ -445,12 +521,12 @@

        Specification: Consensus Rule Changes

        For the IssueBundle:

          -
        • Verify the RedPallas-based issuance authorization signature on the SIGHASH transaction hash, - \(\mathsf{SigHash}\) - , +
        • Validate the issuance authorization signature, \(\mathsf{issueAuthSig}\) - , is verified by invoking - \(\mathsf{issueAuthSig.VerifySig(ik, SigHash)}\) + , on the SIGHASH transaction hash, + \(\mathsf{SigHash}\) + , by invoking + \(\mathsf{IssueAuthSig.Validate(ik, SigHash, issueAuthSig)}\)

        For each IssueAction in IssueBundle:

        @@ -560,7 +636,7 @@

      TxId Digest - Issuance

      -

      This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

      +

      This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the Orchard-ZSA protocol can be found in ZIP 226 6. As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

      A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

      issuance_digest
 ├── issue_actions_digest
@@ -594,7 +670,7 @@
                         
      The personalization field of this hash is set to:
      
                         
      "ZTxIdIAcNoteHash"
      
                         
      T.5a.i.1: recipient 
      
-                            
      This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 23.
      
+                            
      This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 25.
      
                         
      
                         
      T.5a.i.2: value 
      
                             
      Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
      
@@ -629,7 +705,7 @@
         
      
         
      Signature Digest 
      
             
      The per-input transaction digest algorithm to generate the signature digest in ZIP 244 8 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.
      
-            
      The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:
      
+            
      The overall structure of the hash is as follows. We highlight the changes for the Orchard-ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol:
      
             
      signature_digest
 ├── header_digest
 ├── transparent_sig_digest
@@ -650,7 +726,7 @@

      Authorizing Data Commitment

      -

      The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:

      +

      The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the Orchard-ZSA protocol to have the following structure. We highlight the changes for the Orchard-ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol:

      auth_digest
 ├── transparent_scripts_digest
 ├── sapling_auth_digest
@@ -685,7 +761,7 @@
                         \(\mathsf{finalize}\)
                      boolean for all the Assets issued with that key should be set to
                         \(1\)
-                     and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new
+                     and the issuer should change to a new issuance master key, and issue new Assets, each with a new
                         \(\mathsf{AssetId}\)
                     .
                 
@@ -851,10 +927,26 @@
                     
                 
             
-            
+            
      
+                        
+                    
+                
+            
      
                 
                     
      
                         17BIP 340: Schnorr Signatures for secp256k1
      
+            
+                
+                    
+                        
+                        
+                    
+                
+            
      18Zcash Protocol Specification, Version 2022.3.8. Section 2: Notation
      
+            
+                
+                    
+                        
@@ -862,7 +954,7 @@
             
      19
                         Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
                     
      
                 
      
-                        
+                        
@@ -870,7 +962,7 @@
             
      
                 
                     
      1820
                         Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
                     
      
                 
      
-                        
+                        
@@ -878,7 +970,7 @@
             
      
                 
                     
      1921
                         Zcash Protocol Specification, Version 2022.3.8. Section 4.1.2: Pseudo Random Functions
                     
      
                 
      
-                        
+                        
@@ -886,7 +978,7 @@
             
      
                 
                     
      2022
                         Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
                     
      
                 
      
-                        
+                        
@@ -894,7 +986,7 @@
             
      
                 
                     
      2123
                         Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
                     
      
                 
      
-                        
+                        
@@ -902,7 +994,7 @@
             
      
                 
                     
      2224
                         Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
                     
      
                 
      
-                        
+                        
@@ -910,7 +1002,7 @@
             
      
                 
                     
      2325
                         Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
                     
      
                 
      
-                        
+                        
diff --git a/zip-0227.rst b/zip-0227.rst
index 538a7fc67..4b9c24756 100644
--- a/zip-0227.rst
+++ b/zip-0227.rst
@@ -43,7 +43,7 @@ We define the following additional terms:
 Abstract
 ========
 
-This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
+This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the Orchard-ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
 
 Motivation
 ==========
@@ -80,13 +80,11 @@ Requirements
 Specification: Issuance Keys and Issuance Authorization Signature Scheme
 ========================================================================
 
-The ZSA Protocol adds the following three keys to the key components [#protocol-addressesandkeys]_:
+The Orchard-ZSA Protocol adds the following keys to the key components [#protocol-addressesandkeys]_:
 
-1. The issuance master key, denoted as :math:`\mathsf{imk}`, is the key that is used to derive the other two keys.
+1. The issuance master key, denoted as :math:`\mathsf{imk}`, is the key that is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
 
-2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
-
-3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
+2. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
 
 The relations between these keys are shown in the following diagram:
 
@@ -95,20 +93,29 @@ The relations between these keys are shown in the following diagram:
     :align: center
     :figclass: align-center
 
-    Diagram of Issuance Key Components for the ZSA Protocol
+    Diagram of Issuance Key Components for the Orchard-ZSA Protocol
 
 
 Issuance Authorization Signature Scheme
 ---------------------------------------
 
-We define the issuance authorization signature scheme :math:`\mathsf{IssueAuthSig}` similar to :math:`\mathsf{SpendAuthSig}^{\mathsf{Orchard}}`, the Orchard spend authorization signature scheme [#protocol-concretespendauthsig]_. 
-Specifically, we instantiate :math:`\mathsf{IssueAuthSig}` as :math:`\mathsf{RedPallas}` without key re-randomization using generator :math:`\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})` where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in the Zcash protocol specification [#protocol-concretegrouphashpallasandvesta]_.
+We instantiate the issuance authorization signature scheme :math:`\mathsf{IssueAuthSig}` as a Schnorr signature over the :math:`\mathtt{secp256k1}` curve, as described in BIP-340 [#bip-0340]_.
+We define the constants as per the :math:`\mathtt{secp256k1}` standard parameters, as described in BIP 340. 
+
+The associated types of the :math:`\mathsf{IssueAuthSig}` signature scheme are as follows:
+
+* :math:`\mathsf{IssueAuthSig.Message} = \mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}`
+* :math:`\mathsf{IssueAuthSig.Signature} = \mathbb{B}^{\mathbb{Y}^{[64]}} \cup \{\bot\}`
+* :math:`\mathsf{IssueAuthSig.Public} = \mathbb{B}^{\mathbb{Y}^{[32]}} \cup \{\bot\}`
+* :math:`\mathsf{IssueAuthSig.Private} = \mathbb{B}^{\mathbb{Y}^{[32]}}`
+
+where :math:`\mathbb{B}^{\mathbb{Y}^{[k]}}` denotes the set of sequences of :math:`k` bytes, and :math:`\mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}` denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification [#protocol-notation]_.
+
+The signing key generation algorithm and the validating key derivation algorithm are defined in the `Issuance Key Derivation`_ section, while the signing and validation algorithms are defined in the `Issuance Authorization Signing and Validation`_ section.
 
 Issuance Key Derivation
 -----------------------
 
-The issuance master key is generated by choosing a bit sequence uniformly at random from :math:`\mathbb{B}^{\mathbb{Y}[32]}`, like the Orchard spending key [#protocol-orchardkeycomponents]_.
-
 Issuance master key generation for hierarchical deterministic wallets
 `````````````````````````````````````````````````````````````````````
 
@@ -128,27 +135,47 @@ We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD path
 
 From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance master key to be :math:`\mathsf{imk} := \mathsf{sk}`.
 
-Derivation of issuance authorizing key and issuance validating key
-``````````````````````````````````````````````````````````````````
+Derivation of issuance validating key
+`````````````````````````````````````
 
-The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key [#protocol-orchardkeycomponents]_, as described below.
+Define :math:`\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \to \mathsf{IssueAuthSig.Public}` as:
 
-- The issuance authorizing key is derived from the issuance master key, :math:`\mathsf{imk}`, as a private signature key. The function :math:`\mathsf{PRF^{expand}_{imk}}` is as defined in the Zcash protocol specification [#protocol-abstractprfs]_:
+* :math:`\mathsf{ik} := \textit{PubKey}(\mathsf{imk})`
+* Return :math:`\bot` if the :math:`\textit{PubKey}` algorithm invocation fails, otherwise return :math:`\mathsf{ik}`.
 
-.. math:: \mathsf{isk} := \mathsf{ToScalar}^{\mathsf{Orchard}}(︀ \mathsf{PRF^{expand}_{imk}}([\mathtt{0x0a}]) )
+where the :math:`\textit{PubKey}` algorithm is defined in BIP 340 [#bip-0340]_. 
 
-- The issuance validating key is derived from the issuance authorizing key, :math:`\mathsf{isk}`, as a public verification key:
-
-.. math:: \mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})
+It is possible for the :math:`\textit{PubKey}` algorithm to fail with very low probability, which means that :math:`\mathsf{IssueAuthSig.DerivePublic}` could return :math:`\bot` with very low probability. 
+If this happens, discard the keys and repeat with a different :math:`\mathsf{imk}`.
 
 This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.
 
+Issuance Authorization Signing and Validation
+---------------------------------------------
+
+Define :math:`\mathsf{IssueAuthSig.Sign}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \to \mathsf{IssueAuthSig.Signature}` as:
+
+* Let the auxiliary data :math:`a = \mathtt{[0x00]}^{32}`.
+* Let :math:`\sigma = \mathsf{Sign}(\mathsf{imk},M)`.
+* Return :math:`\bot` if the :math:`\mathsf{Sign}` algorithm fails in the previous step, otherwise return :math:`\sigma`.
+
+where the :math:`\mathsf{Sign}` algorithm is defined in BIP 340 and :math:`a` denotes the auxiliary data used in BIP 340 [#bip-0340]_.
+Note that :math:`\mathsf{IssueAuthSig.Sign}` could return :math:`\bot` with very low probability.
+
+
+Define :math:`\mathsf{IssueAuthSig.Validate}\: : \: (\mathsf{ik}\: : \: \mathsf{IssueAuthSig.Public}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \times (\sigma\: : \: \mathsf{IssueAuthSig.Signature}) \to \mathbb{B}` as:
+
+* Return :math:`0` if :math:`\sigma = \bot`.
+* Return :math:`1` if :math:`\mathsf{Verify}(\mathsf{ik}, M, \sigma)` succeeds, otherwise :math:`0`.
+
+where the :math:`\mathsf{Verify}` algorithm is defined in BIP 340 [#bip-0340]_.
+
 Specification: Asset Identifier
 ===============================
 
 For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string.
 
-A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier.
+A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier.
 From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.
 
 Let 
@@ -163,7 +190,7 @@ where
 
 Define :math:`\mathsf{AssetBase_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`
 
-In the case of the Orchard-based ZSA protocol, we define :math:`\mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})`
+In the case of the Orchard-ZSA protocol, we define :math:`\mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})`
 where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in [#protocol-concretegrouphashpallasandvesta]_.
 
 The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:
@@ -238,7 +265,7 @@ It contains the following fields:
 
 - :math:`\mathsf{ik}`: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer.
 - ``vIssueActions``: an array of issuance actions, of type ``IssueAction``.
-- :math:`\mathsf{issueAuthSig}`: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathsf{isk}`, that validates the issuance .
+- :math:`\mathsf{issueAuthSig}`: the signature of the transaction SIGHASH, signed by the issuance master key, :math:`\mathsf{imk}`, that validates the issuance .
 
 The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_.
 
@@ -258,25 +285,25 @@ The issuance bundle is then added within the transaction format as a new bundle.
 
 Issuance Protocol
 -----------------
-The issuer program performs the following operations
+The issuer program performs the following operations:
 
 For all actions ``IssueAction``:
 
 - encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512.
 - compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section.
 - compute :math:`\mathsf{AssetBase}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section.
-- set the :math:`\mathsf{finalize}` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set :math:`\mathsf{finalize} = 0`, otherwise set :math:`\mathsf{finalize} = 1`)
-- For each recipient :math:`i`:
+- set the :math:`\mathsf{finalize}` boolean as desired (if more issuance actions are to be created for this :math:`\mathsf{AssetBase}`, set :math:`\mathsf{finalize} = 0`, otherwise set :math:`\mathsf{finalize} = 1`).
+- for each recipient :math:`i`:
 
-    - generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase}, \mathsf{rcm}_i)\!`.
+    - generate a ZSA output note that includes the Asset Base. For an Orchard-ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \rho_i, \mathsf{rseed}_i, \mathsf{AssetBase}, \mathsf{rcm}_i)\!`.
 
 - encode the ``IssueAction`` into the vector ``vIssueActions`` of the bundle.
 
 For the ``IssueBundle``:
 
-- encode the ``vIssueActions`` vector
-- encode the :math:`\mathsf{ik}` as 32 byte-string
-- sign the SIGHASH transaction hash with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle.
+- encode the ``vIssueActions`` vector.
+- encode the :math:`\mathsf{ik}` as 32 byte-string.
+- sign the SIGHASH transaction hash with the issuance master key, :math:`\mathsf{imk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle.
 
 
 **Note:** that the commitment is not included in the ``IssuanceAction`` itself. As explained below, it is computed later by the validators and added to the note commitment tree.
@@ -287,7 +314,7 @@ Specification: Consensus Rule Changes
 
 For the ``IssueBundle``:
 
-- Verify the RedPallas-based issuance authorization signature on the SIGHASH transaction hash, :math:`\mathsf{SigHash}`, :math:`\mathsf{issueAuthSig}`, is verified by invoking :math:`\mathsf{issueAuthSig.VerifySig(ik, SigHash)}`
+- Validate the issuance authorization signature, :math:`\mathsf{issueAuthSig}`, on the SIGHASH transaction hash, :math:`\mathsf{SigHash}`, by invoking :math:`\mathsf{IssueAuthSig.Validate(ik, SigHash, issueAuthSig)}`
 
 For each ``IssueAction`` in ``IssueBundle``:
 
@@ -348,7 +375,7 @@ TxId Digest - Issuance
 ======================
 
 This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data.
-Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 [#zip-0226-txiddigest]_.
+Details of the overall changes to the transaction digest due to the Orchard-ZSA protocol can be found in ZIP 226 [#zip-0226-txiddigest]_.
 As in ZIP 244 [#zip-0244]_, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.
 
 A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below::
@@ -445,7 +472,7 @@ Signature Digest
 The per-input transaction digest algorithm to generate the signature digest in ZIP 244 [#zip-0244-sigdigest]_ is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action.
 For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.
 
-The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the ZSA protocol::
+The overall structure of the hash is as follows. We highlight the changes for the Orchard-ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol::
 
     signature_digest
     ├── header_digest
@@ -473,8 +500,8 @@ Identical to that specified for the transaction identifier.
 Authorizing Data Commitment
 ===========================
 
-The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. 
-We highlight the changes for the ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the ZSA protocol::
+The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the Orchard-ZSA protocol to have the following structure. 
+We highlight the changes for the Orchard-ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol::
 
     auth_digest
     ├── transparent_scripts_digest
@@ -522,7 +549,7 @@ Issuance Key Compromise
 
 The design of this protocol does not currently allow for rotation of the issuance validating key that would allow for replacing the key of a specific Asset. In case of compromise, the following actions are recommended:
 
-- If an issuance validating key is compromised, the :math:`\mathsf{finalize}` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`.
+- If an issuance validating key is compromised, the :math:`\mathsf{finalize}` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance master key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`.
 
 Bridging Assets
 ---------------
@@ -578,6 +605,8 @@ References
 .. [#zip-0032-key-path-levels] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels `_
 .. [#zip-0032-orchard-key-path] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path `_
 .. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_
+.. [#bip-0340] `BIP 340: Schnorr Signatures for secp256k1 `_
+.. [#protocol-Notation] `Zcash Protocol Specification, Version 2022.3.8. Section 2: Notation `_
 .. [#protocol-addressesandkeys] `Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys `_
 .. [#protocol-concretegrouphashpallasandvesta] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta `_
 .. [#protocol-abstractprfs] `Zcash Protocol Specification, Version 2022.3.8. Section 4.1.2: Pseudo Random Functions `_

From d370d1ffa227f833a855c350fb061e556a136565 Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Tue, 17 Oct 2023 14:23:09 +0530
Subject: [PATCH 32/42] updated burn description

Minor addition to burn mechanism description
---
 zip-0226.html | 2 +-
 zip-0226.rst  | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/zip-0226.html b/zip-0226.html
index d0d4882ce..708493766 100644
--- a/zip-0226.html
+++ b/zip-0226.html
@@ -187,7 +187,7 @@
                 
             
             
      Burn Mechanism 
      
-                
      The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.
      
+                
      The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets. Burning makes it globally provable that a given amount of an Asset has been destroyed.
      
                 
      The sender includes a
                     \(\mathsf{v_{AssetId}}\)
                  variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the Orchard-ZSA Transaction Structure, this is separate from the regular
diff --git a/zip-0226.rst b/zip-0226.rst
index 43ea818b0..9036be17a 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -167,6 +167,7 @@ Burn Mechanism
 --------------
 
 The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.
+Burning makes it globally provable that a given amount of an Asset has been destroyed.
 
 The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `Orchard-ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).
 

From 69b0f2383bf0ab5c653a737852ab8f94210b9d75 Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Wed, 18 Oct 2023 22:05:01 +0530
Subject: [PATCH 33/42] Apply suggestions from ZIP review

Co-authored-by: Daira Emma Hopwood 
---
 zip-0227.rst | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/zip-0227.rst b/zip-0227.rst
index 4b9c24756..1501ac7d9 100644
--- a/zip-0227.rst
+++ b/zip-0227.rst
@@ -43,7 +43,7 @@ We define the following additional terms:
 Abstract
 ========
 
-This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the Orchard-ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
+This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjunction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the Orchard-ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
 
 Motivation
 ==========
@@ -82,9 +82,9 @@ Specification: Issuance Keys and Issuance Authorization Signature Scheme
 
 The Orchard-ZSA Protocol adds the following keys to the key components [#protocol-addressesandkeys]_:
 
-1. The issuance master key, denoted as :math:`\mathsf{imk}`, is the key that is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
+1. The issuance master key, denoted as :math:`\mathsf{imk}`, is the key used to authorize the issuance of Asset Identifiers by a given issuer, and is only used by that issuer.
 
-2. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
+2. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate issuance transactions. This key is used to validate the issuance of Asset Identifiers by a given issuer, and is used by all blockchain users (specifically the owners of notes for that Asset, and consensus validators) to associate the Asset in question with the issuer.
 
 The relations between these keys are shown in the following diagram:
 
@@ -99,8 +99,11 @@ The relations between these keys are shown in the following diagram:
 Issuance Authorization Signature Scheme
 ---------------------------------------
 
-We instantiate the issuance authorization signature scheme :math:`\mathsf{IssueAuthSig}` as a Schnorr signature over the :math:`\mathtt{secp256k1}` curve, as described in BIP-340 [#bip-0340]_.
-We define the constants as per the :math:`\mathtt{secp256k1}` standard parameters, as described in BIP 340. 
+We instantiate the issuance authorization signature scheme :math:`\mathsf{IssueAuthSig}` as a BIP-340 Schnorr signature over the secp256k1 curve. The signing and validation algorithms, signature encoding, and public key encoding MUST follow BIP 340 [#bip-0340]_.
+
+Batch verification MAY be used. Precomputation MAY be used if and only if it produces equivalent results; for example, for a given verification key :math:`pk`, :math:`\mathit{lift\_x}(\mathit{int}(pk))` MAY be precomputed.
+
+We define the constants as per the secp256k1 standard parameters, as described in BIP 340. 
 
 The associated types of the :math:`\mathsf{IssueAuthSig}` signature scheme are as follows:
 
@@ -111,7 +114,7 @@ The associated types of the :math:`\mathsf{IssueAuthSig}` signature scheme are a
 
 where :math:`\mathbb{B}^{\mathbb{Y}^{[k]}}` denotes the set of sequences of :math:`k` bytes, and :math:`\mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}` denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification [#protocol-notation]_.
 
-The signing key generation algorithm and the validating key derivation algorithm are defined in the `Issuance Key Derivation`_ section, while the signing and validation algorithms are defined in the `Issuance Authorization Signing and Validation`_ section.
+The issuance authorizing key generation algorithm and the issuance validating key derivation algorithm are defined in the `Issuance Key Derivation`_ section, while the corresponding signing and validation algorithms are defined in the `Issuance Authorization Signing and Validation`_ section.
 
 Issuance Key Derivation
 -----------------------

From 9da0702810ad03668ee608c20af8a9a3b6043597 Mon Sep 17 00:00:00 2001
From: Vivek Arte 
Date: Wed, 18 Oct 2023 22:06:50 +0530
Subject: [PATCH 34/42] updating html file to reflect rst file changes

---
 zip-0227.html | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/zip-0227.html b/zip-0227.html
index b9cb52bcb..38200730e 100644
--- a/zip-0227.html
+++ b/zip-0227.html
@@ -43,7 +43,7 @@
             
         
      
         
      Abstract 
      
-            
      This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the Orchard-ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
      
+            
      This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of Custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjunction with ZIP 226 4. The proposed issuance mechanism is only valid for the Orchard-ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
      
         
      
         
      Motivation 
      
             
      This ZIP introduces the issuance mechanism for Custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 4) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 4.
      
@@ -77,10 +77,10 @@
             
        
                 
      1. The issuance master key, denoted as
                     \(\mathsf{imk}\)
-                , is the key that is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
        2. 
+                , is the key used to authorize the issuance of Asset Identifiers by a given issuer, and is only used by that issuer.
                 
      2. The issuance validating key, denoted as
                     \(\mathsf{ik}\)
-                , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
        3. 
+                , is the key that is used to validate issuance transactions. This key is used to validate the issuance of Asset Identifiers by a given issuer, and is used by all blockchain users (specifically the owners of notes for that Asset, and consensus validators) to associate the Asset in question with the issuer.
             
      
             
      The relations between these keys are shown in the following diagram:
      
             
      
@@ -90,11 +90,13 @@
             
      Issuance Authorization Signature Scheme 
      
                 
      We instantiate the issuance authorization signature scheme
                     \(\mathsf{IssueAuthSig}\)
-                 as a Schnorr signature over the
-                    \(\mathtt{secp256k1}\)
-                 curve, as described in BIP-340 17. We define the constants as per the
-                    \(\mathtt{secp256k1}\)
-                 standard parameters, as described in BIP 340.
      
+                 as a BIP-340 Schnorr signature over the secp256k1 curve. The signing and validation algorithms, signature encoding, and public key encoding MUST follow BIP 340 17.
      
+                
      Batch verification MAY be used. Precomputation MAY be used if and only if it produces equivalent results; for example, for a given verification key
+                    \(pk\)
+                ,
+                    \(\mathit{lift\_x}(\mathit{int}(pk))\)
+                 MAY be precomputed.
      
+                
      We define the constants as per the secp256k1 standard parameters, as described in BIP 340.
      
                 
      The associated types of the
                     \(\mathsf{IssueAuthSig}\)
                  signature scheme are as follows:
      
@@ -119,7 +121,7 @@
                  bytes, and
                     \(\mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}\)
                  denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification 18.
      
-                
      The signing key generation algorithm and the validating key derivation algorithm are defined in the Issuance Key Derivation section, while the signing and validation algorithms are defined in the Issuance Authorization Signing and Validation section.
      
+                
      The issuance authorizing key generation algorithm and the issuance validating key derivation algorithm are defined in the Issuance Key Derivation section, while the corresponding signing and validation algorithms are defined in the Issuance Authorization Signing and Validation section.
      
             
      
             
      Issuance Key Derivation 
      
                 
      Issuance master key generation for hierarchical deterministic wallets 
      

From 0f639950e729648bac67896075324bb5ca513213 Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Tue, 31 Oct 2023 23:52:06 +0530
Subject: [PATCH 35/42] Apply suggestions from ZIP review

Co-authored-by: Daira Emma Hopwood 
---
 zip-0226.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/zip-0226.rst b/zip-0226.rst
index 9036be17a..9fb811c35 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -54,13 +54,13 @@ These terms are formally defined in ZIP 227 [#zip-0227]_.
 
 The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description [#protocol-actions]_ is preserved across Assets (see the Orchard Binding Signature [#protocol-binding]_), and by extension the balance of an Orchard transaction. That is, the sum of all the :math:`\mathsf{value^{net}}` from each Action Description, computed as :math:`\mathsf{value^{old}-value^{new}}`, must be balanced **only with respect to the same Asset Identifier**. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.
 
-As was initially proposed by Jack Grigg and Daira Hopwood [#initial-zsa-issue]_ [#generalized-value-commitments]_, we propose to make this happen by changing the value base point, :math:`\mathcal{V}^{\mathsf{Orchard}}`, in the Homomorphic Pedersen Commitment that derives the value commitment, :math:`\mathsf{cv^{net}}`, of the *net value* in an Orchard Action.
+As was initially proposed by Jack Grigg and Daira Emma Hopwood [#initial-zsa-issue]_ [#generalized-value-commitments]_, we propose to make this happen by changing the value base point, :math:`\mathcal{V}^{\mathsf{Orchard}}`, in the Homomorphic Pedersen Commitment that derives the value commitment, :math:`\mathsf{cv^{net}}`, of the *net value* in an Orchard Action.
 
 Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base an auxiliary input to the proof for each Action statement [#protocol-actionstatement]_, represented already as a point on the Pallas curve. The circuit then should check that the same Asset Base is used in the old note commitment and the new note commitment [#protocol-concretesinsemillacommit]_, **and** as the base point in the value commitment [#protocol-concretevaluecommit]_. This ensures (1) that the input and output notes are of the same Asset Base, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.
 
 In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-dummynotes]_ for Custom Assets, as we need to enforce that the :math:`\mathsf{AssetBase}` of the output note of that Split Action is the output of a valid :math:`\mathsf{ZSAValueBase}` computation defined in ZIP 227 [#zip-0227]_.
 
-We include the ability to pause the ZSA functionality, via a :math:`\mathsf{enableZSA}` boolean flag. When this flag is set to false, it is not possible to perform transactions involving Custom Assets (the circuit will fail).
+We include the ability to pause the ZSA functionality, via a :math:`\mathsf{enableZSA}` boolean flag. When this flag is set to false, it is not possible to perform transactions involving Custom Assets (the Action statement as modified for ZSAs will not be satisfied).
 
 Finally, in this ZIP we also describe the *burn* mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the :math:`\mathsf{valueBalance}` of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets.
 
@@ -85,20 +85,20 @@ Note Structure & Commitment
 ---------------------------
 
 Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e. 
-:math:`\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*`.
+: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 
 
-- :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 non-bottom group element that is not the identity. 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})`.
+- :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})`.
 
 Note that the above assumes a canonical encoding, which is true for the Pallas group, but may not hold for future shielded protocols.
 
 We define the note commitment scheme :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm}}` as follows:
 
-.. math:: \mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}
+.. math:: \mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}^* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}
 
-where :math:`\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, and :math:`\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}` are as defined in the Zcash protocol specification [#protocol-abstractcommit]_.
+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} 
@@ -113,7 +113,7 @@ 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}*} \,||\, \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{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""})
     \end{align}
 
@@ -169,7 +169,7 @@ Burn Mechanism
 The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Asset Identifier to be "destroyed". The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation at the consensus level. It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.
 Burning makes it globally provable that a given amount of an Asset has been destroyed.
 
-The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `Orchard-ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).
+The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `Orchard-ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (e.g. to Sapling or Transparent).
 
 For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` vector the tuple :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.
 
@@ -241,7 +241,7 @@ Wallets and other clients have to choose from the following to ensure the Asset
 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).
 
-For Split Notes, the nullifier is generated as follows
+For Split Notes, the nullifier is generated as follows:
 
 .. math:: \mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\rho^{\mathsf{old}}) + \psi') \bmod q_{\mathbb{P}}] \mathcal{K}^\mathsf{Orchard} + \mathsf{cm^{old}} + \mathcal{L}^\mathsf{Orchard})
 

From 19ef526a5df1a6ace44e0a8060563b72e4960dc9 Mon Sep 17 00:00:00 2001
From: Vivek Arte 
Date: Wed, 1 Nov 2023 08:26:39 +0530
Subject: [PATCH 36/42] accepting ZIP review suggestions, updating html files
 for deployment

---
 README.template |  2 +-
 zip-0226.html   | 30 +++++++++++++++++-------------
 zip-0226.rst    |  4 ++--
 3 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/README.template b/README.template
index 3ceeb8e47..f838ffac0 100644
--- a/README.template
+++ b/README.template
@@ -37,7 +37,7 @@ Use ``make`` to check that you are using correct
 `reStructuredText `__ or
 `Markdown `__ syntax,
 and double-check the generated ``draft-*.html`` file before filing a Pull Request.
-
+See `here `__ for the project dependencies.
 
 NU5 ZIPs
 --------
diff --git a/zip-0226.html b/zip-0226.html
index 708493766..a493ce8ac 100644
--- a/zip-0226.html
+++ b/zip-0226.html
@@ -53,7 +53,7 @@
              from each Action Description, computed as
                 \(\mathsf{value^{old}-value^{new}}\)
             , must be balanced only with respect to the same Asset Identifier. This is especially important since we will allow different Action Descriptions to transfer notes of different Asset Identifiers, where the overall balance is checked without revealing which (or how many distinct) Assets are being transferred.
      
-            
      As was initially proposed by Jack Grigg and Daira Hopwood 31 32, we propose to make this happen by changing the value base point,
+            
      As was initially proposed by Jack Grigg and Daira Emma Hopwood 31 32, we propose to make this happen by changing the value base point,
                 \(\mathcal{V}^{\mathsf{Orchard}}\)
             , in the Homomorphic Pedersen Commitment that derives the value commitment,
                 \(\mathsf{cv^{net}}\)
@@ -66,7 +66,7 @@
              computation defined in ZIP 227 6.
      
             
      We include the ability to pause the ZSA functionality, via a
                 \(\mathsf{enableZSA}\)
-             boolean flag. When this flag is set to false, it is not possible to perform transactions involving Custom Assets (the circuit will fail).
      
+             boolean flag. When this flag is set to false, it is not possible to perform transactions involving Custom Assets (the Action statement as modified for ZSAs will not be satisfied).
      
             
      Finally, in this ZIP we also describe the burn mechanism, which is a direct extension of the transfer mechanism. The burn process uses a similar mechanism to what is used in Orchard to unshield ZEC, by using the
                 \(\mathsf{valueBalance}\)
              of the Asset in question. Burning Assets is useful for many purposes, including bridging of Wrapped Assets and removing supply of Assets.
      
@@ -92,7 +92,7 @@
                 
      Let
                     \(\mathsf{Note^{OrchardZSA}}\)
                  be the type of a ZSA note, i.e.
-                    \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}*\)
+                    \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}^*\)
                 .
      
                 
      An Orchard ZSA note differs from an Orchard note 14 by additionally including the Asset Base,
                     \(\mathsf{AssetBase}\)
@@ -101,8 +101,10 @@
                 , where
      
                 
        
                     
      • 
-                        \(\mathsf{AssetBase} : \mathbb{P}*\)
-                     is the unique element of the Pallas group 22 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid non-bottom group element that is not the identity. The byte representation of the Asset Base is defined as
+                        \(\mathsf{AssetBase} : \mathbb{P}^*\)
+                     is the unique element of the Pallas group 22 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid group element that is not the identity and is not
+                        \(\bot\)
+                    . The byte representation of the Asset Base is defined as
                         \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase})\)
                     .
        • 
                 
      
@@ -110,23 +112,25 @@
                 
      We define the note commitment scheme
                     \(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}\)
                  as follows:
      
-                
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)
      
+                
      \(\mathsf{NoteCommit}^{\mathsf{OrchardZSA}} : \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \mathbb{B}^{[\ell_{\mathbb{P}}]} \times \{0 .. 2^{\ell_{\mathsf{value}}} - 1\} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{F}_{q_{\mathbb{P}}} \times \mathbb{P}^* \to \mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Output}\)
      
                 
      where
                     \(\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}\)
-                 are as defined for the Pallas curve 22, and
-                    \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}, \mathsf{Orchard}.\mathsf{Output}\)
+                 are as defined for the Pallas curve 22, and where
+                    \(\mathsf{NoteCommit}^{\mathsf{Orchard}}.\mathsf{Trapdoor}\)
+                 and
+                    \(\mathsf{Orchard}.\mathsf{Output}\)
                  are as defined in the Zcash protocol specification 17. This note commitment scheme is instantiated using the Sinsemilla Commitment 25 as follows:
      
                 
      \(\begin{align}
 \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})}
 :=\begin{cases}
-\mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\
+\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:
      
                 
      \(\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}*} \,||\, \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{rcm}] \mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"},\texttt{""})
 \end{align}\)
      
                 
      Note that
@@ -192,10 +196,10 @@
                     \(\mathsf{v_{AssetId}}\)
                  variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the Orchard-ZSA Transaction Structure, this is separate from the regular
                     \(\mathsf{valueBalance^Orchard}\)
-                 that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (eg: to Sapling or Transparent).
      
+                 that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (e.g. to Sapling or Transparent).
      
                 
      For every Custom Asset that is burnt, we add to the
                     \(\mathsf{assetBurn}\)
-                 vector the tuple
+                 set the tuple
                     \((\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})\)
                  such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.
      
                 
      \(\mathsf{assetBurn} = \{ (\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})\ |\ \forall\ \mathsf{AssetBase}_{\mathsf{AssetId}}\ \textit{s.t.}\ \mathsf{v_{AssetId}} \neq 0 \}\)
      
@@ -288,7 +292,7 @@
                     
    6. The Split Input note could be a different unspent note containing the same Asset Base (note that the note will not actually be spent).
      7. 
                     
    7. 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).
      8. 
                 
-                
      For Split Notes, the nullifier is generated as follows
      
+                
      For Split Notes, the nullifier is generated as follows:
      
                 
      \(\mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\rho^{\mathsf{old}}) + \psi') \bmod q_{\mathbb{P}}] \mathcal{K}^\mathsf{Orchard} + \mathsf{cm^{old}} + \mathcal{L}^\mathsf{Orchard})\)
      
                 
      where
                     \(\psi'\)
diff --git a/zip-0226.rst b/zip-0226.rst
index 9fb811c35..6ba33dfa3 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -104,7 +104,7 @@ This note commitment scheme is instantiated using the Sinsemilla Commitment [#pr
 .. math:: \begin{align} 
     \mathsf{NoteCommit^{OrchardZSA}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi, \mathsf{AssetBase})}
     :=\begin{cases} 
-    \mathsf{NoteCommit^{Orchard}_{rcm}(g_{d}*, pk_{d}*, v, \rho, \psi)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\ 
+    \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}
@@ -171,7 +171,7 @@ Burning makes it globally provable that a given amount of an Asset has been dest
 
 The sender includes a :math:`\mathsf{v_{AssetId}}` variable for every Asset Identifier that is being burnt, which represents the amount of that Asset being burnt. As described in the `Orchard-ZSA Transaction Structure`_, this is separate from the regular :math:`\mathsf{valueBalance^Orchard}` that is the default transparent value for the ZEC Asset, and represents either the transaction fee, or the amount of ZEC changing pools (e.g. to Sapling or Transparent).
 
-For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` vector the tuple :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.
+For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` set the tuple :math:`(\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})` such that the validator of the transaction can compute the value commitment with the corresponding value base point of that Asset. This ensures that the values are all balanced out with respect to the Asset Identifiers in the transfer.
 
 .. math:: \mathsf{assetBurn} = \{ (\mathsf{AssetBase}_{\mathsf{AssetId}},\mathsf{v_{AssetId}})\ |\ \forall\ \mathsf{AssetBase}_{\mathsf{AssetId}}\ \textit{s.t.}\ \mathsf{v_{AssetId}} \neq 0 \}
 

From 50e7958062f0c581f7fa4c7831479f1e8bf8c2bf Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Wed, 1 Nov 2023 14:30:06 +0530
Subject: [PATCH 37/42] Rename of Issuance Keys (#44)

This performs a rename of the Issuance keys as follows:

- `imk : Issuance master key` is renamed to `isk: Issuance authorizing
key`
---
 zip-0226.html                   |   2 +-
 zip-0226.rst                    |   2 +-
 zip-0227-key-components-zsa.png | Bin 44217 -> 45907 bytes
 zip-0227-key-components-zsa.svg |  10 ++++-----
 zip-0227.html                   |  36 ++++++++++++++++----------------
 zip-0227.rst                    |  30 +++++++++++++-------------
 6 files changed, 40 insertions(+), 40 deletions(-)

diff --git a/zip-0226.html b/zip-0226.html
index a493ce8ac..20ea7cbfa 100644
--- a/zip-0226.html
+++ b/zip-0226.html
@@ -76,7 +76,7 @@
             
      Asset Identifiers 
      
                 
      For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an Asset description,
                     \(\mathsf{asset\_desc}\)
-                , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier,
+                , which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance validating key of the issuer, the specific Asset Identifier,
                     \(\mathsf{AssetId}\)
                 , the Asset Digest, and the Asset Base (
                     \(\mathsf{AssetBase}\)
diff --git a/zip-0226.rst b/zip-0226.rst
index 6ba33dfa3..2eb6eb05f 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -72,7 +72,7 @@ Most of the protocol is kept the same as the Orchard protocol released with NU5,
 Asset Identifiers
 -----------------
 
-For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}`) are derived as defined in ZIP 227 [#zip-0227]_.
+For every new Asset, there must be a new and unique Asset Identifier. Every Asset is defined by an *Asset description*, :math:`\mathsf{asset\_desc}`, which is a global byte string (scoped across all future versions of Zcash). From this Asset description and the issuance validating key of the issuer, the specific Asset Identifier, :math:`\mathsf{AssetId}`, the Asset Digest, and the Asset Base (:math:`\mathsf{AssetBase}`) are derived as defined in ZIP 227 [#zip-0227]_.
 
 This Asset Base will be the base point of the value commitment for the specific Custom Asset. Note that the Asset Base of the ZEC Asset will be kept as the original value base point, :math:`\mathcal{V}^\mathsf{Orchard}`.
 
diff --git a/zip-0227-key-components-zsa.png b/zip-0227-key-components-zsa.png
index c7d2fd6fca1b4668436eb8412c5fc01a2c9f21b5..51269a6000df8b60cac9f6ea83988f0d53a6f843 100644
GIT binary patch
delta 28349
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
      ;?I*wu6#p1
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
b>4#^Pe=NL7mtE99k|0?3-redu51;=R^IV(Q

delta 26646
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

diff --git a/zip-0227-key-components-zsa.svg b/zip-0227-key-components-zsa.svg
index 96f39ad74..eb38e4dcb 100644
--- a/zip-0227-key-components-zsa.svg
+++ b/zip-0227-key-components-zsa.svg
@@ -31,10 +31,10 @@
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      showgrid="false"
-     inkscape:window-width="1158"
+     inkscape:window-width="1068"
      inkscape:window-height="916"
-     inkscape:window-x="381"
-     inkscape:window-y="81"
+     inkscape:window-x="222"
+     inkscape:window-y="102"
      inkscape:window-maximized="0"
      inkscape:showpageshadow="2"
      inkscape:pagecheckerboard="0"
@@ -203,7 +203,7 @@
          x="99.664932"
          id="tspan3757-7"
          sodipodi:role="line"
-         style="stroke-width:1.06667">imkiskIssuance master keyIssuance authorizing key
      Specification: Issuance Keys and Issuance Authorization Signature Scheme 
      
             
      The Orchard-ZSA Protocol adds the following keys to the key components 19:
      
             
        
-                
      1. The issuance master key, denoted as
-                    \(\mathsf{imk}\)
+                
      2. The issuance authorizing key, denoted as
+                    \(\mathsf{isk}\)
                 , is the key used to authorize the issuance of Asset Identifiers by a given issuer, and is only used by that issuer.
        3. 
                 
      3. The issuance validating key, denoted as
                     \(\mathsf{ik}\)
@@ -124,17 +124,17 @@
                 
        The issuance authorizing key generation algorithm and the issuance validating key derivation algorithm are defined in the Issuance Key Derivation section, while the corresponding signing and validation algorithms are defined in the Issuance Authorization Signing and Validation section.
        
             
      
             
      Issuance Key Derivation 
      
-                
      Issuance master key generation for hierarchical deterministic wallets 
      
-                    
      The issuance master key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.
      
+                
      Issuance authorizing key generation for hierarchical deterministic wallets 
      
+                    
      The issuance authorizing key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.
      
                     
      Let
                         \(S\)
                      be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key
                         \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\)
                     .
      
-                    
      As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the
+                    
      As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance authorizing key. We reuse the
                         \(\mathsf{CDKsk}\)
                      function for Orchard child key derivation from ZIP 32.
      
-                    
      We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as
+                    
      We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance authorizing key path as
                         \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\)
                     . We fix the path levels as follows:
      
                     
        
@@ -162,17 +162,17 @@
                     
      
                     
      From the generated
                         \((\mathsf{sk}, \mathsf{c})\)
-                    , we set the issuance master key to be
-                        \(\mathsf{imk} := \mathsf{sk}\)
+                    , we set the issuance authorizing key to be
+                        \(\mathsf{isk} := \mathsf{sk}\)
                     .
      
                 
      
                 
      Derivation of issuance validating key 
      
                     
      Define
-                        \(\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \to \mathsf{IssueAuthSig.Public}\)
+                        \(\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{isk}\: : \: \mathsf{IssueAuthSig.Private}) \to \mathsf{IssueAuthSig.Public}\)
                      as:
      
                     
        
                         
      • 
-                            \(\mathsf{ik} := \textit{PubKey}(\mathsf{imk})\)
+                            \(\mathsf{ik} := \textit{PubKey}(\mathsf{isk})\)
                         
        • 
                         
      • Return
                             \(\bot\)
@@ -192,21 +192,21 @@
                      could return
                         \(\bot\)
                      with very low probability. If this happens, discard the keys and repeat with a different
-                        \(\mathsf{imk}\)
+                        \(\mathsf{isk}\)
                     .
        
                     
        This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.
        
                 
      
             
      
             
      Issuance Authorization Signing and Validation 
      
                 
      Define
-                    \(\mathsf{IssueAuthSig.Sign}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \to \mathsf{IssueAuthSig.Signature}\)
+                    \(\mathsf{IssueAuthSig.Sign}\: : \: (\mathsf{isk}\: : \: \mathsf{IssueAuthSig.Private}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \to \mathsf{IssueAuthSig.Signature}\)
                  as:
      
                 
        
                     
      • Let the auxiliary data
                         \(a = \mathtt{[0x00]}^{32}\)
                     .
        • 
                     
      • Let
-                        \(\sigma = \mathsf{Sign}(\mathsf{imk},M)\)
+                        \(\sigma = \mathsf{Sign}(\mathsf{isk},M)\)
                     .
        • 
                     
      • Return
                         \(\bot\)
@@ -424,8 +424,8 @@
                     
      • vIssueActions: an array of issuance actions, of type IssueAction.
        • 
                     
      • 
                         \(\mathsf{issueAuthSig}\)
-                    : the signature of the transaction SIGHASH, signed by the issuance master key,
-                        \(\mathsf{imk}\)
+                    : the signature of the transaction SIGHASH, signed by the issuance authorizing key,
+                        \(\mathsf{isk}\)
                     , that validates the issuance .
        • 
                 
      
                 
      The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 26.
      
@@ -511,8 +511,8 @@
                     
    8. encode the
                         \(\mathsf{ik}\)
                      as 32 byte-string.
      9. 
-                    
    9. sign the SIGHASH transaction hash with the issuance master key,
-                        \(\mathsf{imk}\)
+                    
    10. sign the SIGHASH transaction hash with the issuance authorizing key,
+                        \(\mathsf{isk}\)
                     , using the
                         \(\mathsf{IssueAuthSig}\)
                      signature scheme. The signature is then added to the issuance bundle.
      11. 
@@ -763,7 +763,7 @@
                         \(\mathsf{finalize}\)
                      boolean for all the Assets issued with that key should be set to
                         \(1\)
-                     and the issuer should change to a new issuance master key, and issue new Assets, each with a new
+                     and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new
                         \(\mathsf{AssetId}\)
                     .
                 
diff --git a/zip-0227.rst b/zip-0227.rst
index 1501ac7d9..b12068e28 100644
--- a/zip-0227.rst
+++ b/zip-0227.rst
@@ -82,7 +82,7 @@ Specification: Issuance Keys and Issuance Authorization Signature Scheme
 
 The Orchard-ZSA Protocol adds the following keys to the key components [#protocol-addressesandkeys]_:
 
-1. The issuance master key, denoted as :math:`\mathsf{imk}`, is the key used to authorize the issuance of Asset Identifiers by a given issuer, and is only used by that issuer.
+1. The issuance authorizing key, denoted as :math:`\mathsf{isk}`, is the key used to authorize the issuance of Asset Identifiers by a given issuer, and is only used by that issuer.
 
 2. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate issuance transactions. This key is used to validate the issuance of Asset Identifiers by a given issuer, and is used by all blockchain users (specifically the owners of notes for that Asset, and consensus validators) to associate the Asset in question with the issuer.
 
@@ -119,47 +119,47 @@ The issuance authorizing key generation algorithm and the issuance validating ke
 Issuance Key Derivation
 -----------------------
 
-Issuance master key generation for hierarchical deterministic wallets
-`````````````````````````````````````````````````````````````````````
+Issuance authorizing key generation for hierarchical deterministic wallets
+``````````````````````````````````````````````````````````````````````````
 
-The issuance master key is generated using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section.
+The issuance authorizing key is generated using the Orchard master key derivation procedure defined in ZIP 32 [#zip-0032-orchard-master]_. We reuse the functions defined there in what follows in this section.
 
 Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes.
 We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)`.
 
-As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key. 
+As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance authorizing key. 
 We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32.
 
-We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows:
+We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance authorizing key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows:
 
 - :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}`). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation.
 - :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_.
 - :math:`account`: fixed to index :math:`0`.
 
-From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance master key to be :math:`\mathsf{imk} := \mathsf{sk}`.
+From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance authorizing key to be :math:`\mathsf{isk} := \mathsf{sk}`.
 
 Derivation of issuance validating key
 `````````````````````````````````````
 
-Define :math:`\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \to \mathsf{IssueAuthSig.Public}` as:
+Define :math:`\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{isk}\: : \: \mathsf{IssueAuthSig.Private}) \to \mathsf{IssueAuthSig.Public}` as:
 
-* :math:`\mathsf{ik} := \textit{PubKey}(\mathsf{imk})`
+* :math:`\mathsf{ik} := \textit{PubKey}(\mathsf{isk})`
 * Return :math:`\bot` if the :math:`\textit{PubKey}` algorithm invocation fails, otherwise return :math:`\mathsf{ik}`.
 
 where the :math:`\textit{PubKey}` algorithm is defined in BIP 340 [#bip-0340]_. 
 
 It is possible for the :math:`\textit{PubKey}` algorithm to fail with very low probability, which means that :math:`\mathsf{IssueAuthSig.DerivePublic}` could return :math:`\bot` with very low probability. 
-If this happens, discard the keys and repeat with a different :math:`\mathsf{imk}`.
+If this happens, discard the keys and repeat with a different :math:`\mathsf{isk}`.
 
 This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.
 
 Issuance Authorization Signing and Validation
 ---------------------------------------------
 
-Define :math:`\mathsf{IssueAuthSig.Sign}\: : \: (\mathsf{imk}\: : \: \mathsf{IssueAuthSig.Private}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \to \mathsf{IssueAuthSig.Signature}` as:
+Define :math:`\mathsf{IssueAuthSig.Sign}\: : \: (\mathsf{isk}\: : \: \mathsf{IssueAuthSig.Private}) \times (M\: : \: \mathsf{IssueAuthSig.Message}) \to \mathsf{IssueAuthSig.Signature}` as:
 
 * Let the auxiliary data :math:`a = \mathtt{[0x00]}^{32}`.
-* Let :math:`\sigma = \mathsf{Sign}(\mathsf{imk},M)`.
+* Let :math:`\sigma = \mathsf{Sign}(\mathsf{isk},M)`.
 * Return :math:`\bot` if the :math:`\mathsf{Sign}` algorithm fails in the previous step, otherwise return :math:`\sigma`.
 
 where the :math:`\mathsf{Sign}` algorithm is defined in BIP 340 and :math:`a` denotes the auxiliary data used in BIP 340 [#bip-0340]_.
@@ -268,7 +268,7 @@ It contains the following fields:
 
 - :math:`\mathsf{ik}`: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer.
 - ``vIssueActions``: an array of issuance actions, of type ``IssueAction``.
-- :math:`\mathsf{issueAuthSig}`: the signature of the transaction SIGHASH, signed by the issuance master key, :math:`\mathsf{imk}`, that validates the issuance .
+- :math:`\mathsf{issueAuthSig}`: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathsf{isk}`, that validates the issuance .
 
 The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_.
 
@@ -306,7 +306,7 @@ For the ``IssueBundle``:
 
 - encode the ``vIssueActions`` vector.
 - encode the :math:`\mathsf{ik}` as 32 byte-string.
-- sign the SIGHASH transaction hash with the issuance master key, :math:`\mathsf{imk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle.
+- sign the SIGHASH transaction hash with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle.
 
 
 **Note:** that the commitment is not included in the ``IssuanceAction`` itself. As explained below, it is computed later by the validators and added to the note commitment tree.
@@ -552,7 +552,7 @@ Issuance Key Compromise
 
 The design of this protocol does not currently allow for rotation of the issuance validating key that would allow for replacing the key of a specific Asset. In case of compromise, the following actions are recommended:
 
-- If an issuance validating key is compromised, the :math:`\mathsf{finalize}` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance master key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`.
+- If an issuance validating key is compromised, the :math:`\mathsf{finalize}` boolean for all the Assets issued with that key should be set to :math:`1` and the issuer should change to a new issuance authorizing key, and issue new Assets, each with a new :math:`\mathsf{AssetId}`.
 
 Bridging Assets
 ---------------

From 064257a8b41716f8b6994df174579ee22cf97525 Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Thu, 2 Nov 2023 16:36:05 +0530
Subject: [PATCH 38/42] Updates to Security and Privacy Considerations section
 (#45)

This adds some details to the ZIP 226 Security and Privacy
Considerations section to address this
[comment](https://github.com/zcash/zips/pull/680#discussion_r1377549364)
---
 zip-0226.html | 4 +++-
 zip-0226.rst  | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/zip-0226.html b/zip-0226.html
index 20ea7cbfa..a6feb98a5 100644
--- a/zip-0226.html
+++ b/zip-0226.html
@@ -503,7 +503,9 @@ 
      The
         
      
         
      Security and Privacy Considerations 
      
             
        
-                
      • The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility.
        • 
+                
      • After the protocol upgrade, the Orchard shielded pool will be shared by the Orchard protocol and the Orchard-ZSA protocol.
        • 
+                
      • Deploying the Orchard-ZSA protocol does not necessitate disabling the Orchard protocol. Both can co-exist and be addressed via different transaction versions (V5 for Orchard and V6 for Orchard-ZSA). Due to this, Orchard note commitments can be distinguished from Orchard-ZSA note commitments. This holds whether or not the two protocols are active simultaneously.
        • 
+                
      • Orchard-ZSA note commitments for the native asset (ZEC) are indistinguishable from Orchard-ZSA note commitments for non-native Assets.
        • 
                 
      • When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
        • 
                 
      • We prevent a potential malleability attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
        • 
             
      
diff --git a/zip-0226.rst b/zip-0226.rst
index 2eb6eb05f..7ed3617b6 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -409,7 +409,9 @@ The details of the changes to these algorithms are in ZIP 227 [#zip-0227-sigdige
 Security and Privacy Considerations
 ===================================
 
-- The notes generated via the ZSA protocol are different from those generated via the Orchard protocol. As with any protocol upgrade, it will be possible to distinguish between notes generated by each protocol. However, all ZEC notes will be fully spendable with the ZSA protocol transaction structure due to the built-in backward compatibility.
+- After the protocol upgrade, the Orchard shielded pool will be shared by the Orchard protocol and the Orchard-ZSA protocol.
+- Deploying the Orchard-ZSA protocol does not necessitate disabling the Orchard protocol. Both can co-exist and be addressed via different transaction versions (V5 for Orchard and V6 for Orchard-ZSA). Due to this, Orchard note commitments can be distinguished from Orchard-ZSA note commitments. This holds whether or not the two protocols are active simultaneously.
+- Orchard-ZSA note commitments for the native asset (ZEC) are indistinguishable from Orchard-ZSA note commitments for non-native Assets.
 - When including new Assets we would like to maintain the amount and identifiers of Assets private, which is achieved with the design.
 - We prevent a potential malleability attack on the Asset Identifier by ensuring the output notes receive an Asset Base that exists on the global state.
 

From 1b29061b4e68bf117cc8c5b7a106b2bb9893f659 Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Tue, 7 Nov 2023 15:53:58 +0530
Subject: [PATCH 39/42] Clarifying the encoding of `ik` (#46)

This makes it clear that the encoding of `ik` used in the Asset Base
derivation is big-endian, as in the case of the underlying BIP 340
Schnorr signature scheme.

It also adds a clarification about the version byte used in the Asset
Base derivation.
---
 zip-0227.html | 9 +++++++--
 zip-0227.rst  | 4 +++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/zip-0227.html b/zip-0227.html
index 4252b6425..a1f22d76d 100644
--- a/zip-0227.html
+++ b/zip-0227.html
@@ -184,7 +184,9 @@
                     
                     
      where the
                         \(\textit{PubKey}\)
-                     algorithm is defined in BIP 340 17.
      
+                     algorithm is defined in BIP 340 17. Note that the byte representation of
+                        \(\mathsf{ik}\)
+                     is in big-endian order as defined in BIP 340.
      
                     
      It is possible for the
                         \(\textit{PubKey}\)
                      algorithm to fail with very low probability, which means that
@@ -276,8 +278,11 @@
             , where
      
             
        
                 
      • 
-                    \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!\)
+                    \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{ik} || \mathsf{asset\_desc}\!\)
                 .
        • 
+                
      • Note that the initial
+                    \(\mathsf{0x00}\)
+                 byte is a version byte.
        • 
             
      
             
      Define
                 \(\mathsf{AssetBase_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\)
diff --git a/zip-0227.rst b/zip-0227.rst
index b12068e28..aec157ed4 100644
--- a/zip-0227.rst
+++ b/zip-0227.rst
@@ -147,6 +147,7 @@ Define :math:`\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{isk}\: : \: \ma
 * Return :math:`\bot` if the :math:`\textit{PubKey}` algorithm invocation fails, otherwise return :math:`\mathsf{ik}`.
 
 where the :math:`\textit{PubKey}` algorithm is defined in BIP 340 [#bip-0340]_. 
+Note that the byte representation of :math:`\mathsf{ik}` is in big-endian order as defined in BIP 340.
 
 It is possible for the :math:`\textit{PubKey}` algorithm to fail with very low probability, which means that :math:`\mathsf{IssueAuthSig.DerivePublic}` could return :math:`\bot` with very low probability. 
 If this happens, discard the keys and repeat with a different :math:`\mathsf{isk}`.
@@ -189,7 +190,8 @@ Let
 Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`,
 where
 
-- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`.
+- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{ik} || \mathsf{asset\_desc}\!`.
+- Note that the initial :math:`\mathsf{0x00}` byte is a version byte.
 
 Define :math:`\mathsf{AssetBase_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`
 

From 7346a0250a813edd3f864a2aaef5437cb8fece81 Mon Sep 17 00:00:00 2001
From: Daira Emma Hopwood 
Date: Mon, 13 Nov 2023 09:11:46 +0000
Subject: [PATCH 40/42] ZIPs 226 and 227: minor editorial changes (#47)

Signed-off-by: Daira Emma Hopwood 
---
 index.html    |  2 +-
 zip-0226.html |  4 ++--
 zip-0226.rst  | 48 ++++++++++++++++++++++++------------------------
 zip-0227.rst  | 48 ++++++++++++++++++++++++------------------------
 4 files changed, 51 insertions(+), 51 deletions(-)

diff --git a/index.html b/index.html
index 2b6f34e33..e4bbc69d1 100644
--- a/index.html
+++ b/index.html
@@ -22,7 +22,7 @@
             
      Participation in the Zcash project is subject to a Code of Conduct.
      
             
      The Zcash protocol is documented in its Protocol Specification.
      
             
      To start contributing, first read ZIP 0 which documents the ZIP process. Then clone this repo from GitHub, and start adding your draft ZIP, formatted either as reStructuredText or as Markdown.
      
-            
      For example, if using reStructuredText, use a filename matching draft-*.rst. Use make to check that you are using correct reStructuredText or Markdown syntax, and double-check the generated draft-*.html file before filing a Pull Request.
      
+            
      For example, if using reStructuredText, use a filename matching draft-*.rst. Use make to check that you are using correct reStructuredText or Markdown syntax, and double-check the generated draft-*.html file before filing a Pull Request. See here for the project dependencies.
      
         
      
         
      NU5 ZIPs 
      
             
      This is the list of ZIPs relevant to the NU5 Upgrade, which activated on 31st May 2022:
      
diff --git a/zip-0226.html b/zip-0226.html
index a6feb98a5..8d5d92e6a 100644
--- a/zip-0226.html
+++ b/zip-0226.html
@@ -121,7 +121,7 @@
                     \(\mathsf{Orchard}.\mathsf{Output}\)
                  are as defined in the Zcash protocol specification 17. This note commitment scheme is instantiated using the Sinsemilla Commitment 25 as follows:
      
                 
      \(\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)}, &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\
 \mathsf{cm}_{\mathsf{ZSA}} &\text{otherwise}
@@ -130,7 +130,7 @@
                 
      where:
      
                 
      \(\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}\)
      
                 
      Note that
diff --git a/zip-0226.rst b/zip-0226.rst
index 7ed3617b6..0eb9a75a1 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -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]_.
 
@@ -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})`.
 
@@ -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}
 
@@ -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
 ----------------
@@ -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.
@@ -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).
 
@@ -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
 -----------
@@ -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
diff --git a/zip-0227.rst b/zip-0227.rst
index aec157ed4..c538334bf 100644
--- a/zip-0227.rst
+++ b/zip-0227.rst
@@ -16,7 +16,7 @@
   License: MIT
   Discussions-To: 
   Pull-Request: 
- 
+
 Terminology
 ===========
 
@@ -50,7 +50,7 @@ Motivation
 
 This ZIP introduces the issuance mechanism for Custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 [#zip-0226]_) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 [#zip-0226]_.
 
-This ZIP only enables *transparent* issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked. 
+This ZIP only enables *transparent* issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.
 
 The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash blockchain), as well as for institutions to create bridges from other chains and import Wrapped Assets. This enables what we hope will be a useful set of applications.
 
@@ -103,7 +103,7 @@ We instantiate the issuance authorization signature scheme :math:`\mathsf{IssueA
 
 Batch verification MAY be used. Precomputation MAY be used if and only if it produces equivalent results; for example, for a given verification key :math:`pk`, :math:`\mathit{lift\_x}(\mathit{int}(pk))` MAY be precomputed.
 
-We define the constants as per the secp256k1 standard parameters, as described in BIP 340. 
+We define the constants as per the secp256k1 standard parameters, as described in BIP 340.
 
 The associated types of the :math:`\mathsf{IssueAuthSig}` signature scheme are as follows:
 
@@ -127,7 +127,7 @@ The issuance authorizing key is generated using the Orchard master key derivatio
 Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes.
 We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)`.
 
-As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance authorizing key. 
+As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance authorizing key.
 We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32.
 
 We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance authorizing key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows:
@@ -146,10 +146,10 @@ Define :math:`\mathsf{IssueAuthSig.DerivePublic}\: : \: (\mathsf{isk}\: : \: \ma
 * :math:`\mathsf{ik} := \textit{PubKey}(\mathsf{isk})`
 * Return :math:`\bot` if the :math:`\textit{PubKey}` algorithm invocation fails, otherwise return :math:`\mathsf{ik}`.
 
-where the :math:`\textit{PubKey}` algorithm is defined in BIP 340 [#bip-0340]_. 
+where the :math:`\textit{PubKey}` algorithm is defined in BIP 340 [#bip-0340]_.
 Note that the byte representation of :math:`\mathsf{ik}` is in big-endian order as defined in BIP 340.
 
-It is possible for the :math:`\textit{PubKey}` algorithm to fail with very low probability, which means that :math:`\mathsf{IssueAuthSig.DerivePublic}` could return :math:`\bot` with very low probability. 
+It is possible for the :math:`\textit{PubKey}` algorithm to fail with very low probability, which means that :math:`\mathsf{IssueAuthSig.DerivePublic}` could return :math:`\bot` with very low probability.
 If this happens, discard the keys and repeat with a different :math:`\mathsf{isk}`.
 
 This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 [#zip-0032]_. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.
@@ -182,7 +182,7 @@ For every new Asset, there must be a new and unique Asset Identifier, denoted :m
 A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier.
 From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.
 
-Let 
+Let
 
 - :math:`\mathsf{asset\_desc}` be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
 - :math:`\mathsf{ik}` be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
@@ -212,7 +212,7 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho
 
 Wallets MUST NOT display just the :math:`\mathsf{asset\_desc}` string to their users as the name of the Asset. Some possible alternatives include:
 
-- Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. 
+- Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
 - The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets.
 
 Specification: Global Issuance State
@@ -237,12 +237,12 @@ An issuance action, ``IssueAction``, is the instance of issuing a specific Custo
 - ``flagsIssuance``: a byte that stores the :math:`\mathsf{finalize}` boolean that defines whether the issuance of that specific Custom Asset is finalized or not.
 
 An asset's :math:`\mathsf{AssetDigest}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with :math:`\mathsf{finalize} = 1`. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetDigest} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetDigest} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain :math:`\mathsf{finalize} = 0` or change it to :math:`\mathsf{finalize} = 1`, denoting that this Custom Asset cannot be issued after the containing block.
-  
+
 
 +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+
 | Bytes                       | Name                     | Data Type                                 | Description                                                         |
 +=============================+==========================+===========================================+=====================================================================+
-|``2``                        |``assetDescSize``         |``byte``                                   |The length of the :math:`\mathsf{asset\_desc}` string in bytes.      |  
+|``2``                        |``assetDescSize``         |``byte``                                   |The length of the :math:`\mathsf{asset\_desc}` string in bytes.      |
 +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+
 |``assetDescSize``            |``asset_desc``            |``byte[assetDescSize]``                    |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a  |
 |                             |                          |                                           |well-formed UTF-8 code unit sequence according to Unicode 15.0.0     |
@@ -258,14 +258,14 @@ An asset's :math:`\mathsf{AssetDigest}` is added to the :math:`\mathsf{previousl
 |                             |                          |                                           | * The remaining bits are set to ``0``.                              |
 +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+
 
-We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note. 
+We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note.
 This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.
 
 Issuance Bundle
 ---------------
 
-An issuance bundle, ``IssueBundle``, is the aggregate of all the issuance-related information. 
-Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. 
+An issuance bundle, ``IssueBundle``, is the aggregate of all the issuance-related information.
+Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself.
 It contains the following fields:
 
 - :math:`\mathsf{ik}`: the issuance validating key, that allows the validators to verify that the :math:`\mathsf{AssetId}` is properly associated with the issuer.
@@ -353,7 +353,7 @@ The following is a list of rationale for different decisions made in the proposa
     - information to be committed by the issuer, though not enforceable by the protocol.
 
 - We require a check whether the :math:`\mathsf{finalize}` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the :math:`\mathsf{previously\_finalized}`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
-- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack. 
+- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack.
 
 Concrete Applications
 ---------------------
@@ -368,7 +368,7 @@ Concrete Applications
 
     - issuing a last set of tokens of that specific :math:`\mathsf{AssetId}`, for which :math:`\mathsf{finalize} = 1`, or by
     - issuing a transaction with a single note in the issuance action pertaining to that :math:`\mathsf{AssetId}`, where the note will contain a ``value = 0``. This can be used for application-specific purposes (NFT collections) or for security purposes to revoke the Asset issuance (see Security and Privacy Considerations).
-    - Note in the above cases, that the setting of the :math:`\mathsf{finalize}` flag will take effect at the block boundary, that is, after all the transactions in the block. 
+    - Note in the above cases, that the setting of the :math:`\mathsf{finalize}` flag will take effect at the block boundary, that is, after all the transactions in the block.
 
 - The issuance and burn mechanisms can be used in conjunction to determine the supply of Assets on the Zcash ecosystem. This allows for the bridging of Assets defined on other chains.
 
@@ -386,11 +386,11 @@ As in ZIP 244 [#zip-0244]_, the digests are all personalized BLAKE2b-256 hashes,
 A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below::
 
     issuance_digest
-    ├── issue_actions_digest                      
-    │   ├── issue_notes_digest                    
-    │   ├── assetDescription                     
-    │   └── flagsIssuance                        
-    └── issuanceValidatingKey  
+    ├── issue_actions_digest
+    │   ├── issue_notes_digest
+    │   ├── assetDescription
+    │   └── flagsIssuance
+    └── issuanceValidatingKey
 
 In the specification below, nodes of the tree are presented in depth-first order.
 
@@ -406,7 +406,7 @@ The personalization field of this hash is set to::
   "ZTxIdSAIssueHash"
 
 In case the transaction has no issuance components, ''issue_actions_digest'' is::
-    
+
     BLAKE2b-256("ZTxIdSAIssueHash", [])
 
 T.5a: issue_actions_digest
@@ -505,7 +505,7 @@ Identical to that specified for the transaction identifier.
 Authorizing Data Commitment
 ===========================
 
-The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the Orchard-ZSA protocol to have the following structure. 
+The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the Orchard-ZSA protocol to have the following structure.
 We highlight the changes for the Orchard-ZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol::
 
     auth_digest
@@ -547,7 +547,7 @@ Security and Privacy Considerations
 Displaying Asset Identifier information to users
 ------------------------------------------------
 
-Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are provided in the `Specification: Asset Identifier`_ section. 
+Wallets need to communicate the names of the Assets in a non-confusing way to users, since the byte representation of the Asset Identifier would be hard to read for an end user. Possible solutions are provided in the `Specification: Asset Identifier`_ section.
 
 Issuance Key Compromise
 -----------------------
@@ -619,4 +619,4 @@ References
 .. [#protocol-spendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard) `_
 .. [#protocol-concretespendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard) `_
 .. [#protocol-orchardpaymentaddrencoding] `Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses `_
-.. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)  `_
\ No newline at end of file
+.. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)  `_

From 668312d1f84a93c68982e6fe67e072568216cffd Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Tue, 2 Jan 2024 15:27:53 +0530
Subject: [PATCH 41/42] Fix typo in Orchard-ZSA Action Description. (#48)

This fixes a typo in the ZSA-Orchard Action Description table,
wherein one table entry was not updated from 580 to 612 bytes.
---
 zip-0230.html | 2 +-
 zip-0230.rst  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/zip-0230.html b/zip-0230.html
index c96bfd051..bd7ea0fba 100644
--- a/zip-0230.html
+++ b/zip-0230.html
@@ -453,7 +453,7 @@
                         
      
-                            
+                            
diff --git a/zip-0230.rst b/zip-0230.rst
index a894527dc..8f6c562f7 100644
--- a/zip-0230.rst
+++ b/zip-0230.rst
@@ -278,7 +278,7 @@ Orchard-ZSA Action Description (``OrchardZsaAction``)
 +-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+
 |``32``                       |``ephemeralKey``          |``byte[32]``                          |An encoding of an ephemeral Pallas public key               |
 +-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+
-|``612``                      |``encCiphertext``         |``byte[580]``                         |The encrypted contents of the note plaintext.               |
+|``612``                      |``encCiphertext``         |``byte[612]``                         |The encrypted contents of the note plaintext.               |
 +-----------------------------+--------------------------+--------------------------------------+------------------------------------------------------------+
 |``80``                       |``outCiphertext``         |``byte[80]``                          |The encrypted contents of the byte string created by        |
 |                             |                          |                                      |concatenation of the transmission key with the ephemeral    |

From ba1c185f8aab5dee034992bf35ca32b7c07d54b2 Mon Sep 17 00:00:00 2001
From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>
Date: Fri, 5 Jan 2024 15:23:18 +0530
Subject: [PATCH 42/42] Updates based on review comments (#49)

This updates the ZSA ZIPs based on the comments made on PR#680.
---
 zip-0226.html |   2 +-
 zip-0226.rst  |   2 +-
 zip-0227.html | 223 +++++++++++++++-----------------------------------
 zip-0227.rst  |  71 ++++++----------
 zip-0230.html |  32 +++++---
 zip-0230.rst  |  10 ++-
 6 files changed, 120 insertions(+), 220 deletions(-)

diff --git a/zip-0226.html b/zip-0226.html
index 8d5d92e6a..30d591a07 100644
--- a/zip-0226.html
+++ b/zip-0226.html
@@ -104,7 +104,7 @@
                         \(\mathsf{AssetBase} : \mathbb{P}^*\)
                      is the unique element of the Pallas group 22 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 6, a valid group element that is not the identity and is not
                         \(\bot\)
-                    . The byte representation of the Asset Base is defined as
+                    . The byte encoding of the Asset Base is defined as
                         \(\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase})\)
                     .
                 
diff --git a/zip-0226.rst b/zip-0226.rst
index 0eb9a75a1..2c9ad947a 100644
--- a/zip-0226.rst
+++ b/zip-0226.rst
@@ -90,7 +90,7 @@ Let :math:`\mathsf{Note^{OrchardZSA}}` be the type of a ZSA note, i.e.
 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
 
-- :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})`.
+- :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 encoding of the Asset Base is defined as :math:`\mathsf{asset\_base} : \mathbb{B}^{[\ell_{\mathbb{P}}]} := \mathsf{repr}_{\mathbb{P}}(\mathsf{AssetBase})`.
 
 Note that the above assumes a canonical encoding, which is true for the Pallas group, but may not hold for future shielded protocols.
 
diff --git a/zip-0227.html b/zip-0227.html
index a1f22d76d..77bf63bc0 100644
--- a/zip-0227.html
+++ b/zip-0227.html
@@ -73,7 +73,7 @@
             
         
         
      Specification: Issuance Keys and Issuance Authorization Signature Scheme 
      
-            
      The Orchard-ZSA Protocol adds the following keys to the key components 19:
      
+            
      The Orchard-ZSA Protocol adds the following keys to the key components 20:
      
             
        
                 
      1. The issuance authorizing key, denoted as
                     \(\mathsf{isk}\)
@@ -90,7 +90,7 @@
             
        Issuance Authorization Signature Scheme 
        
                 
        We instantiate the issuance authorization signature scheme
                     \(\mathsf{IssueAuthSig}\)
-                 as a BIP-340 Schnorr signature over the secp256k1 curve. The signing and validation algorithms, signature encoding, and public key encoding MUST follow BIP 340 17.
        
+                 as a BIP-340 Schnorr signature over the secp256k1 curve. The signing and validation algorithms, signature encoding, and public key encoding MUST follow BIP 340 18.
        
                 
        Batch verification MAY be used. Precomputation MAY be used if and only if it produces equivalent results; for example, for a given verification key
                     \(pk\)
                 ,
@@ -120,21 +120,21 @@
                     \(k\)
                  bytes, and
                     \(\mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}\)
-                 denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification 18.
        
+                 denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification 19.
        
                 
        The issuance authorizing key generation algorithm and the issuance validating key derivation algorithm are defined in the Issuance Key Derivation section, while the corresponding signing and validation algorithms are defined in the Issuance Authorization Signing and Validation section.
        
             
        
             
        Issuance Key Derivation 
        
                 
        Issuance authorizing key generation for hierarchical deterministic wallets 
        
-                    
        The issuance authorizing key is generated using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.
        
+                    
        The issuance authorizing key is generated using the Orchard master key derivation procedure defined in ZIP 32 13. We reuse the functions defined there in what follows in this section.
        
                     
        Let
                         \(S\)
                      be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key
                         \(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\)
                     .
        
-                    
        As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance authorizing key. We reuse the
+                    
        As in ZIP 32 for Orchard 14, we only use hardened child key derivation for the issuance authorizing key. We reuse the
                         \(\mathsf{CDKsk}\)
                      function for Orchard child key derivation from ZIP 32.
        
-                    
        We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance authorizing key path as
+                    
        We use the notation of ZIP 32 16 for shielded HD paths, and define the issuance authorizing key path as
                         \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\)
                     . We fix the path levels as follows:
        
                     
          
@@ -153,7 +153,7 @@
                         ) following the BIP 43 recommendation.
                         
        • 
                             \(coin\_type\)
-                        : Defined as in ZIP 32 14.
          • 
+                        : Defined as in ZIP 32 15.
                         
        • 
                             \(account\)
                         : fixed to index
@@ -165,6 +165,9 @@
                     , we set the issuance authorizing key to be
                         \(\mathsf{isk} := \mathsf{sk}\)
                     .
          
+                    
          Rationale for Issuance authorizing key generation 
          
+                        
          The issuance authorizing key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools.
          
+                    
          
                 
        
                 
        Derivation of issuance validating key 
        
                     
        Define
@@ -184,7 +187,7 @@
                     
                     
        where the
                         \(\textit{PubKey}\)
-                     algorithm is defined in BIP 340 17. Note that the byte representation of
+                     algorithm is defined in BIP 340 18. Note that the byte representation of
                         \(\mathsf{ik}\)
                      is in big-endian order as defined in BIP 340.
        
                     
        It is possible for the
@@ -196,7 +199,7 @@
                      with very low probability. If this happens, discard the keys and repeat with a different
                         \(\mathsf{isk}\)
                     .
        
-                    
        This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 11. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.
        
+                    
        This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 12. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.
        
                 
        
             
        
             
        Issuance Authorization Signing and Validation 
        
@@ -222,7 +225,7 @@
                     \(\mathsf{Sign}\)
                  algorithm is defined in BIP 340 and
                     \(a\)
-                 denotes the auxiliary data used in BIP 340 17. Note that
+                 denotes the auxiliary data used in BIP 340 18. Note that
                     \(\mathsf{IssueAuthSig.Sign}\)
                  could return
                     \(\bot\)
@@ -246,7 +249,7 @@
                 
                 
        where the
                     \(\mathsf{Verify}\)
-                 algorithm is defined in BIP 340 17.
        
+                 algorithm is defined in BIP 340 18.
        
             
        
         
      
         
      Specification: Asset Identifier 
      
@@ -291,24 +294,21 @@
                 \(\mathsf{ZSAValueBase}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\)
              where
                 \(\mathsf{GroupHash}^\mathbb{P}\)
-             is defined as in 20.
      
+             is defined as in 21.
      
             
      The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:
      
             
      
                 
-                
      Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol
      
+                
      Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the Orchard-ZSA Protocol
      
             
      
             
      Note: To keep notations light and concise, we may omit
                 \(\mathsf{AssetId}\)
-             (resp.
-                \(\mathsf{Protocol}\)
-            ) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.
      
-            
      Wallets MUST NOT display just the
+             in the subscript when the Asset Identifier is clear from the context.
      
+            
      The Asset Base is the unique identifier of the Asset in the Orchard-ZSA Protocol. Wallets MUST NOT display just the
                 \(\mathsf{asset\_desc}\)
-             string to their users as the name of the Asset. Some possible alternatives include:
      
-            
        
-                
      • Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
        • 
-                
      • The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets.
        • 
-            
      
+             string to their users as the name of the Asset. If the
+                \(\mathsf{asset\_desc}\)
+             string is not a well-formed UTF-8 code unit sequence, the wallet MUST provide a warning that the Asset description cannot be parsed as a UTF-8 encoded string, and SHOULD use the byte string as is in their method for displaying the Asset description.
      
+            
      Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Bases via an auxiliary naming system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
      
         
      
         
      Specification: Global Issuance State 
      
             
      Issuance requires the following additions to the global state defined at block boundaries:
      
@@ -338,7 +338,7 @@
                     
    11. 
                         \(\mathsf{asset\_desc}\)
                     : the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
      12. 
-                    
    12. vNotes: an array of Note containing the unencrypted output notes of the recipients of the Asset.
      13. 
+                    
    13. vNotes: an array of Note [#zip-0226-notestructure] containing the unencrypted output notes of the recipients of the Asset.
      14. 
                     
    14. flagsIssuance: a byte that stores the
                         \(\mathsf{finalize}\)
                      boolean that defines whether the issuance of that specific Custom Asset is finalized or not.
      15. 
@@ -360,62 +360,7 @@
                  or change it to
                     \(\mathsf{finalize} = 1\)
                 , denoting that this Custom Asset cannot be issued after the containing block.
      
-                
      
                 
                     
      2426
                         Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
                     
      
                 
      
                             612
                             encCiphertextbyte[580]byte[612]
                             The encrypted contents of the note plaintext.
                         
      
                         
      
-                    
-                        
-                            
-                            
-                            
-                            
-                        
-                    
-                    
-                        
-                            
-                            
-                            
-                            
-                        
-                        
-                            
-                            
-                            
-                            
-                        
-                        
-                            
-                            
-                            
-                            
-                        
-                        
-                            
-                            
-                            
-                            
-                        
-                        
-                            
-                            
-                            
-                            
-                        
-                    
-                
      BytesNameData TypeDescription
      2assetDescSizebyteThe length of the
-                                \(\mathsf{asset\_desc}\)
-                             string in bytes.
      assetDescSizeasset_descbyte[assetDescSize]A byte sequence of length assetDescSize bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
      variesnNotescompactSizeThe number of notes in the issuance action.
      noteSize * nNotesvNotesNote[nNotes]A sequence of note descriptions within the issuance action, where noteSize is the size, in bytes, of a Note.
      1flagsIssuancebyte
-                                
      
-                                    
      An 8-bit value representing a set of flags. Ordered from LSB to MSB:
      
-                                    
      
-                                        
        
-                                            
      • 
-                                                \(\mathsf{finalize}\)
-                                            
        • 
-                                            
      • The remaining bits are set to 0.
        • 
-                                        
      
-                                    
      
-                                
      
-                            
      
+                
      The detailed description of the fields in an Issue Action Description is provided in ZIP 230 7.
      
                 
      We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.

      Issuance Bundle

      @@ -433,43 +378,7 @@ \(\mathsf{isk}\) , that validates the issuance . -

      The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 26.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      BytesNameData TypeDescription
      variesnIssueActionscompactSizeThe number of issuance actions in the bundle.
      IssueActionSize * nIssueActionsvIssueActionsIssueAction[nIssueActions]A sequence of issuance action descriptions, where IssueActionSize is the size, in bytes, of an IssueAction description.
      32ikbyte[32]The issuance validating key of the issuer, used to validate the signature.
      64issueAuthSigbyte[64]The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme.
      +

      The issuance bundle is then added within the transaction format as a new bundle. The details of the information added to the transaction format are in ZIP 230 7.

      Issuance Protocol

      The issuer program performs the following operations:

      @@ -541,11 +450,6 @@
    15. check that \(0 < \mathtt{assetDescSize} <= 512\) .
      16. -
    16. check that - \(\mathsf{asset\_desc}\) - is a string of length - \(\mathtt{assetDescSize}\) - bytes.
    17. retrieve \(\mathsf{AssetBase}\) from the first note in the sequence and check that @@ -562,15 +466,13 @@ set in the global state.
    18. check that every note in the IssueAction contains the same \(\mathsf{AssetBase}\) - and is properly constructed as - \(\mathsf{note} = (\mathsf{g_d, pk_d, v, \rho, rseed, AssetBase})\) - .
      19. + and is an Orchard-ZSA Note 5.

      If all of the above checks pass, do the following:

      • For each note, compute the note commitment as \(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\) - as defined in the Note Structure and Commitment section of ZIP 226 5 and
        • + as defined in the Note Structure and Commitment section of ZIP 226 5 and
      • Add \(\mathsf{cm}\) to the Merkle tree of note commitments.
        • @@ -583,11 +485,13 @@ set immediately after the block in which this transaction occurs.
      • (Replay Protection) If issue bundle is present, the fees MUST be greater than zero.
      +

      Rationale for non-zero fees when an Issue Bundle is included

      +

      We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a replay attack. The replay attack can happen if a transaction containing only an issue bundle with no fees: in particular, if a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack.

      +

      Rationale

      The following is a list of rationale for different decisions made in the proposal:

        -
      • The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools.
      • The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”.
      • The \(\mathsf{asset\_desc}\) @@ -602,16 +506,15 @@
      • We require a check whether the \(\mathsf{finalize}\) flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the - \(\mathsf{previously\_finalized}`\) + \(\mathsf{previously\_finalized}\) set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve.
        • -
      • We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack.

      Concrete Applications

      Asset Features

      • By using the \(\mathsf{finalize}\) - boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example, + boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example,
        • by setting \(\mathsf{finalize} = 1\) @@ -643,7 +546,7 @@

      TxId Digest - Issuance

      -

      This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the Orchard-ZSA protocol can be found in ZIP 226 6. As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

      +

      This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the Orchard-ZSA protocol can be found in ZIP 226 6. As in ZIP 244 8, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

      A new issuance transaction digest algorithm is defined that constructs the subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

      issuance_digest
 ├── issue_actions_digest
@@ -677,7 +580,7 @@
                         
      The personalization field of this hash is set to:
      
                         
      "ZTxIdIAcNoteHash"
      
                         
      T.5a.i.1: recipient 
      
-                            
      This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 25.
      
+                            
      This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 26.
      
                         
      
                         
      T.5a.i.2: value 
      
                             
      Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
      
@@ -711,7 +614,7 @@

      Signature Digest

      -

      The per-input transaction digest algorithm to generate the signature digest in ZIP 244 8 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.

      +

      The per-input transaction digest algorithm to generate the signature digest in ZIP 244 9 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.

      The overall structure of the hash is as follows. We highlight the changes for the Orchard-ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol:

      signature_digest
 ├── header_digest
@@ -726,14 +629,14 @@
 S.3: sapling_digest         (32-byte hash output)
 S.4: orchard_digest         (32-byte hash output)
 S.5: issuance_digest        (32-byte hash output)  [ADDED FOR ZSA]
      -

      The personalization field remains the same as in ZIP 244 7.

      +

      The personalization field remains the same as in ZIP 244 8.

      S.5: issuance_digest

      Identical to that specified for the transaction identifier.

    Authorizing Data Commitment

    -

    The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the Orchard-ZSA protocol to have the following structure. We highlight the changes for the Orchard-ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol:

    +

    The transaction digest algorithm defined in ZIP 244 10 which commits to the authorizing data of a transaction is modified by the Orchard-ZSA protocol to have the following structure. We highlight the changes for the Orchard-ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the Orchard-ZSA protocol:

    auth_digest
 ├── transparent_scripts_digest
 ├── sapling_auth_digest
@@ -774,7 +677,7 @@

    Bridging Assets

    -

    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

    +

    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

    Other Considerations

    @@ -788,7 +691,7 @@ in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

    Fee Structures

    -

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317 10.

    +

    The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317 11.

    Test Vectors

    @@ -854,10 +757,18 @@ - +
    + + + +
    7ZIP 230: Version 6 Transaction Format
    + + + + @@ -865,7 +776,7 @@
    8 ZIP 244: Transaction Identifier Non-Malleability
    - + @@ -873,7 +784,7 @@
    89 ZIP 244: Transaction Identifier Non-Malleability: Signature Digest
    - + @@ -881,7 +792,7 @@
    910 ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment
    - + @@ -889,7 +800,7 @@
    1011 ZIP 317: Proportional Transfer Fee Mechanism
    - + @@ -897,7 +808,7 @@
    1112 ZIP 32: Shielded Hierarchical Deterministic Wallets
    - + @@ -905,7 +816,7 @@
    1213 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation
    - + @@ -913,7 +824,7 @@
    1314 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation
    - + @@ -921,7 +832,7 @@
    1415 ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels
    - + @@ -929,7 +840,7 @@
    1516 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path
    - + @@ -937,7 +848,7 @@
    1617 ZIP 316: Unified Addresses and Unified Viewing Keys
    - + @@ -945,7 +856,7 @@
    1718 BIP 340: Schnorr Signatures for secp256k1
    - + @@ -953,7 +864,7 @@
    1819 Zcash Protocol Specification, Version 2022.3.8. Section 2: Notation
    - + @@ -961,7 +872,7 @@
    1920 Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
    - + @@ -969,7 +880,7 @@
    2021 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
    - + @@ -977,7 +888,7 @@
    2122 Zcash Protocol Specification, Version 2022.3.8. Section 4.1.2: Pseudo Random Functions
    - + @@ -985,7 +896,7 @@
    2223 Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
    - + @@ -993,7 +904,7 @@
    2324 Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -1001,7 +912,7 @@
    2425 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
    - + @@ -1009,7 +920,7 @@
    2526 Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
    - + diff --git a/zip-0227.rst b/zip-0227.rst index c538334bf..47b0aa260 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -138,6 +138,11 @@ We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD path From the generated :math:`(\mathsf{sk}, \mathsf{c})`, we set the issuance authorizing key to be :math:`\mathsf{isk} := \mathsf{sk}`. +Rationale for Issuance authorizing key generation +''''''''''''''''''''''''''''''''''''''''''''''''' +The issuance authorizing key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools. + + Derivation of issuance validating key ````````````````````````````````````` @@ -205,15 +210,17 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho :align: center :figclass: align-center - Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol + Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the Orchard-ZSA Protocol -**Note:** To keep notations light and concise, we may omit :math:`\mathsf{AssetId}` (resp. :math:`\mathsf{Protocol}`) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context. +**Note:** To keep notations light and concise, we may omit :math:`\mathsf{AssetId}` in the subscript when the Asset Identifier is clear from the context. -Wallets MUST NOT display just the :math:`\mathsf{asset\_desc}` string to their users as the name of the Asset. Some possible alternatives include: +The Asset Base is the unique identifier of the Asset in the Orchard-ZSA Protocol. +Wallets MUST NOT display just the :math:`\mathsf{asset\_desc}` string to their users as the name of the Asset. +If the :math:`\mathsf{asset\_desc}` string is not a well-formed UTF-8 code unit sequence, the wallet MUST provide a warning that the Asset description cannot be parsed as a UTF-8 encoded string, and SHOULD use the byte string as is in their method for displaying the Asset description. + +Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Bases via an auxiliary naming system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. -- Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. -- The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets. Specification: Global Issuance State ==================================== @@ -233,30 +240,12 @@ An issuance action, ``IssueAction``, is the instance of issuing a specific Custo - :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes. - :math:`\mathsf{asset\_desc}`: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section. -- ``vNotes``: an array of ``Note`` containing the unencrypted output notes of the recipients of the Asset. +- ``vNotes``: an array of ``Note`` [#zip-0226-notestructure] containing the unencrypted output notes of the recipients of the Asset. - ``flagsIssuance``: a byte that stores the :math:`\mathsf{finalize}` boolean that defines whether the issuance of that specific Custom Asset is finalized or not. An asset's :math:`\mathsf{AssetDigest}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with :math:`\mathsf{finalize} = 1`. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetDigest} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetDigest} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain :math:`\mathsf{finalize} = 0` or change it to :math:`\mathsf{finalize} = 1`, denoting that this Custom Asset cannot be issued after the containing block. - -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -| Bytes | Name | Data Type | Description | -+=============================+==========================+===========================================+=====================================================================+ -|``2`` |``assetDescSize`` |``byte`` |The length of the :math:`\mathsf{asset\_desc}` string in bytes. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``assetDescSize`` |``asset_desc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | -| | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | -| | | |or later. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``varies`` |``nNotes`` |``compactSize`` |The number of notes in the issuance action. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``noteSize * nNotes`` |``vNotes`` |``Note[nNotes]`` |A sequence of note descriptions within the issuance action, | -| | | |where ``noteSize`` is the size, in bytes, of a Note. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``1`` |``flagsIssuance`` |``byte`` |An 8-bit value representing a set of flags. Ordered from LSB to MSB: | -| | | | * :math:`\mathsf{finalize}` | -| | | | * The remaining bits are set to ``0``. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ +The detailed description of the fields in an Issue Action Description is provided in ZIP 230 [#zip-0230]_. We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers. @@ -272,21 +261,8 @@ It contains the following fields: - ``vIssueActions``: an array of issuance actions, of type ``IssueAction``. - :math:`\mathsf{issueAuthSig}`: the signature of the transaction SIGHASH, signed by the issuance authorizing key, :math:`\mathsf{isk}`, that validates the issuance . -The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format [#protocol-transactionstructure]_. - -+------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ -| Bytes | Name | Data Type | Description | -+====================================+==========================+===========================================+===========================================================================+ -|``varies`` |``nIssueActions`` |``compactSize`` |The number of issuance actions in the bundle. | -+------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ -|``IssueActionSize * nIssueActions`` |``vIssueActions`` |``IssueAction[nIssueActions]`` |A sequence of issuance action descriptions, where IssueActionSize is | -| | | |the size, in bytes, of an IssueAction description. | -+------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ -|``32`` |``ik`` |``byte[32]`` |The issuance validating key of the issuer, used to validate the signature. | -+------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ -|``64`` |``issueAuthSig`` |``byte[64]`` |The signature of the transaction SIGHASH, signed by the issuer, | -| | | |validated as in `Issuance Authorization Signature Scheme`_. | -+------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ +The issuance bundle is then added within the transaction format as a new bundle. The details of the information added to the transaction format are in ZIP 230 [#zip-0230]_. + Issuance Protocol ----------------- @@ -324,11 +300,9 @@ For the ``IssueBundle``: For each ``IssueAction`` in ``IssueBundle``: - check that :math:`0 < \mathtt{assetDescSize} <= 512`. -- check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathtt{assetDescSize}` bytes. - - retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Specification: Asset Identifier`_ section. - check that the :math:`\mathsf{AssetDigest}` does not exist in the :math:`\mathsf{previously\_finalized}` set in the global state. -- check that every note in the ``IssueAction`` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`\mathsf{note} = (\mathsf{g_d, pk_d, v, \rho, rseed, AssetBase})`. +- check that every note in the ``IssueAction`` contains the same :math:`\mathsf{AssetBase}` and is an Orchard-ZSA Note [#zip-0226-notestructure]_. If all of the above checks pass, do the following: @@ -337,13 +311,18 @@ If all of the above checks pass, do the following: - If :math:`\mathsf{finalize} = 1`, add :math:`\mathsf{AssetDigest}` to the :math:`\mathsf{previously\_finalized}` set immediately after the block in which this transaction occurs. - (Replay Protection) If issue bundle is present, the fees MUST be greater than zero. +Rationale for non-zero fees when an Issue Bundle is included +------------------------------------------------------------ +We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a replay attack. +The replay attack can happen if a transaction containing only an issue bundle with no fees: in particular, if a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. +A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack. + Rationale ========= The following is a list of rationale for different decisions made in the proposal: -- The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools. - The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”. - The :math:`\mathsf{asset\_desc}` is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: @@ -352,8 +331,7 @@ The following is a list of rationale for different decisions made in the proposa - bridging information for Wrapped Assets (chain of origin, issuer name, etc) - information to be committed by the issuer, though not enforceable by the protocol. -- We require a check whether the :math:`\mathsf{finalize}` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the :math:`\mathsf{previously\_finalized}`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. -- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack. +- We require a check whether the :math:`\mathsf{finalize}` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the :math:`\mathsf{previously\_finalized}` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. Concrete Applications --------------------- @@ -600,6 +578,7 @@ References .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ .. [#zip-0226-txiddigest] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest `_ +.. [#zip-0230] `ZIP 230: Version 6 Transaction Format `_ .. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ .. [#zip-0244-sigdigest] `ZIP 244: Transaction Identifier Non-Malleability: Signature Digest `_ .. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment `_ diff --git a/zip-0230.html b/zip-0230.html index bd7ea0fba..23b13915f 100644 --- a/zip-0230.html +++ b/zip-0230.html @@ -28,7 +28,7 @@

    Abstract

    This proposal defines a new Zcash peer-to-peer transaction format, which includes data that supports the Orchard-ZSA protocol and all Zcash Shielded Assets (ZSAs) related operations. The new transaction format defines well-bounded regions of the serialized form to serve each of the existing pools of funds, and adds and describes a new elements containing ZSA-specific elements.

    -

    This ZIP also depends upon and defines modifications to the computation of the values TxId Digest, Signature Digest, and Authorizing Data Commitment defined by ZIP 244 9.

    +

    This ZIP also depends upon and defines modifications to the computation of the values TxId Digest, Signature Digest, and Authorizing Data Commitment defined by ZIP 244 10.

    Motivation

    The Orchard-ZSA protocol requires serialized data elements that are distinct from any previous Zcash transaction. Since ZIP 244 was activated in NU5, the v5 and later serialized transaction formats are not consensus-critical. Thus, this ZIP defines format that can easily accommodate future extensions, where elements or a given pool are kept separate.

    @@ -306,7 +306,7 @@
    - +
    2627 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    64 issueAuthSig byte[64]The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme 8.The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme 9.
    @@ -329,7 +329,7 @@
  • The proofs aggregated in proofsOrchardZSA, and the elements of vSpendAuthSigsOrchard, each have a 1:1 correspondence to the elements of vActionsOrchard and MUST be ordered such that the proof or signature at a given index corresponds to the OrchardZsaAction at the same index.
  • For coinbase transactions, the enableSpendsOrchard and enableZSAs bits MUST be set to 0.
    • -

    The encodings of tx_in, and tx_out are as in a version 4 transaction (i.e. unchanged from Canopy). The encodings of SpendDescriptionV6, OutputDescriptionV6 , OrchardZsaAction, AssetBurn and IssueAction are described below. The encoding of Sapling Spends and Outputs has changed relative to prior versions in order to better separate data that describe the effects of the transaction from the proofs of and commitments to those effects, and for symmetry with this separation in the Orchard-related parts of the transaction format.

    +

    The encodings of tx_in, and tx_out are as in a version 4 transaction. The encodings of SpendDescriptionV6, OutputDescriptionV6 , OrchardZsaAction, AssetBurn and IssueAction are described below. The encoding of Sapling Spends and Outputs has changed relative to prior versions in order to better separate data that describe the effects of the transaction from the proofs of and commitments to those effects, and for symmetry with this separation in the Orchard-related parts of the transaction format.

    Sapling Spend Description (SpendDescriptionV6)

    @@ -482,9 +482,9 @@ - + @@ -496,7 +496,7 @@
    32 AssetBase byte[32]For the Orchard-based ZSA protocol, this is the encoding of the Asset Base - \(\mathsf{AssetBase}^{\mathsf{Orchard}}\) - .For the Orchard-ZSA protocol, this is the byte encoding of the Asset Base + \(\mathsf{asset\_base}\) + defined in ZIP 226: Note Structure & Commitment 8.
    8
    -

    The encodings of each of these elements are defined in ZIP 226 7.

    +

    The encodings of each of these elements are defined in ZIP 226 7.

    Issuance Action Description (IssueAction)

    An issuance action, IssueAction, is the instance of issuing a specific Custom Asset, and contains the following fields:

    @@ -513,7 +513,7 @@ 2 assetDescSize - byte + compactSize The length of the asset description string in bytes. @@ -554,7 +554,7 @@ -

    The encodings of each of these elements are defined in ZIP 227 8.

    +

    The encodings of each of these elements are defined in ZIP 227 9.

    Reference implementation

    @@ -617,10 +617,18 @@ - +
    + + + +
    8ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment
    + + + + @@ -628,7 +636,7 @@
    9 ZIP 227: Issuance of Zcash Shielded Assets
    - + @@ -636,7 +644,7 @@
    910 ZIP 244: Transaction Identifier Non-Malleability
    - + diff --git a/zip-0230.rst b/zip-0230.rst index 8f6c562f7..4679a23ec 100644 --- a/zip-0230.rst +++ b/zip-0230.rst @@ -214,8 +214,8 @@ Transaction Format * For coinbase transactions, the ``enableSpendsOrchard`` and ``enableZSAs`` bits MUST be set to ``0``. -The encodings of ``tx_in``, and ``tx_out`` are as in a version 4 transaction (i.e. -unchanged from Canopy). The encodings of ``SpendDescriptionV6``, ``OutputDescriptionV6`` +The encodings of ``tx_in``, and ``tx_out`` are as in a version 4 transaction. +The encodings of ``SpendDescriptionV6``, ``OutputDescriptionV6`` , ``OrchardZsaAction``, ``AssetBurn`` and ``IssueAction`` are described below. The encoding of Sapling Spends and Outputs has changed relative to prior versions in order to better separate data that describe the effects of the transaction from the proofs of and commitments to those effects, and for @@ -296,7 +296,8 @@ An Orchard-ZSA Asset Burn description is encoded in a transaction as an instance +-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=======+===============+=============================+===========================================================================================================================+ -| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-based ZSA protocol, this is the encoding of the Asset Base :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}`. | +| 32 | ``AssetBase`` | ``byte[32]`` | For the Orchard-ZSA protocol, this is the byte encoding of the Asset Base :math:`\mathsf{asset\_base}` defined in | +| | | | ZIP 226: Note Structure & Commitment [#zip-0226-notestructure]_. | +-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ | 8 | ``valueBurn`` | :math:`\{1 .. 2^{64} - 1\}` | The amount being burnt. | +-------+---------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+ @@ -311,7 +312,7 @@ An issuance action, ``IssueAction``, is the instance of issuing a specific Custo +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=============================+==========================+===========================================+=====================================================================+ -|``2`` |``assetDescSize`` |``byte`` |The length of the asset description string in bytes. | +|``2`` |``assetDescSize`` |``compactSize`` |The length of the asset description string in bytes. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``assetDescSize`` |``asset_desc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | | | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | @@ -345,6 +346,7 @@ References .. [#protocol-actiondesc] `Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.6: Action Descriptions `_ .. [#zip-0222] `ZIP 222: Transparent Zcash Extensions `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ +.. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ .. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ .. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection `_
    1011 ZIP 307: Light Client Protocol for Payment Detection