diff --git a/README.rst b/README.rst index e5ff03941..292f69850 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 -------- @@ -107,10 +107,10 @@ 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 228 Asset Swaps for Zcash Shielded Assets Reserved - 230 Version 6 Transaction Format Reserved + 230 Version 6 Transaction Format Draft 231 Decouple Memos from Transaction Outputs Reserved 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final 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/css/style.css b/css/style.css index 692e988e3..1eee84aa0 100644 --- a/css/style.css +++ b/css/style.css @@ -186,17 +186,28 @@ h1 { margin-bottom: 1.5rem; } +h1 code { + font-size: 2.25rem; + font-weight: 300; +} + h2 { font-size: 2.125rem; margin-bottom: 1.125rem; } +h2 code { + font-size: 1.9rem; + font-weight: 300; +} + h3 { font-size: 1.85rem; } h3 code { - font-size: 1.5rem; + font-size: 1.65rem; + font-weight: 300; } h4 { @@ -205,6 +216,7 @@ h4 { h4 code { font-size: 1.35rem; + font-weight: 200; } h5 { diff --git a/index.html b/index.html index 885fe2608..f2f0bafe0 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:

@@ -81,10 +81,10 @@ 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 228 Asset Swaps for Zcash Shielded Assets Reserved - 230 Version 6 Transaction Format Reserved + 230 Version 6 Transaction Format Draft 231 Decouple Memos from Transaction Outputs Reserved 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final diff --git a/zip-0226.html b/zip-0226.html index 3c6fca54b..4ebbc36b4 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,784 @@ Credits: Daniel Benarroch Aurelien Nicolas Deirdre Connolly -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/680> +

Terminology

+

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

+

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

+

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

+

We define the following additional terms:

+
    +
  • Split Input: an Action input used to ensure that the output note of that Action is of a validly issued + \(\mathsf{AssetBase}\) + (see 6) 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

+

This ZIP (ZIP 226) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 227 5. 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 5, 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 5.

+
+

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}\) + 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 15 28 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}} - \mathsf{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-Emma 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}}\!\) + , 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 20, 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 24. 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 17 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}\) + computation defined in ZIP 227 5.

+

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

+
+

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 validating key of the issuer, the specific Asset Identifier, + \(\mathsf{AssetId}\!\) + , the Asset Digest, and the Asset Base ( + \(\mathsf{AssetBase}\!\) + ) are derived as defined in ZIP 227 5.

+

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

+

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 + \(\mathsf{Note^{OrchardZSA}}\) + 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 14 by additionally including the Asset Base, + \(\mathsf{AssetBase}\!\) + . So a ZSA note is a tuple + \((\mathsf{g_d}, \mathsf{pk_d}, \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{AssetBase})\!\) + , where

+
    +
  • + \(\mathsf{AssetBase} : \mathbb{P}^*\) + is the unique element of the Pallas group 26 that identifies each Asset in the Orchard protocol, defined as the Asset Base in ZIP 227 5, 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})\!\) + .
    • +
+

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}\)
+

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

+
\(\begin{align} +\mathsf{NoteCommit^{OrchardZSA}_{rcm}}(\mathsf{g_d}\star, \mathsf{pk_d}\star, \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{AssetBase}) +:= \begin{cases} + \mathsf{NoteCommit^{Orchard}_{rcm}}(\mathsf{g_d}\star, \mathsf{pk_d}\star, \mathsf{v}, \text{ρ}, \text{ψ}), &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\ + \mathsf{cm_{ZSA}} &\text{otherwise} + \end{cases} +\end{align}\)
+

where:

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

Note that + \(\mathsf{repr}_{\mathbb{P}}\) + and + \(\mathsf{GroupHash}^{\mathbb{P}}\) + are as defined for the Pallas curve 26, + \(\ell^{\mathsf{Orchard}}_{\mathsf{base}}\) + is as defined in §5.3 22, and + \(\mathsf{I2LEBSP}\) + is as defined in §5.1 21 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 27. 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 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 23. ZSA note commitments will therefore be added to the same Orchard Note Commitment Tree. In essence, we have:

+
\(\mathsf{NoteCommit^{OrchardZSA}_{rcm}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d}), \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{AssetBase}) \in \mathsf{NoteCommit^{Orchard}}.\!\mathsf{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 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}} := \mathsf{ValueCommit^{OrchardZSA}_{rcv}}(\mathsf{AssetBase_{AssetId}}, \mathsf{v^{net}_{AssetId}}) = [\mathsf{v^{net}_{AssetId}}]\,\mathsf{AssetBase_{AssetId}} + [\mathsf{rcv}]\,\mathcal{R}^{\mathsf{Orchard}}\)
+

where + \(\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId}} - \mathsf{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_{AssetId}}\) + is defined in ZIP 227 5, and

+

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

+

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}}(\mathsf{v})\) + as defined in 4 is used as + \(\mathsf{ValueCommit^{OrchardZSA}_{rcv}}(\mathcal{V}^{\mathsf{Orchard}}, \mathsf{v})\) + here.

+

Rationale for Value Commitment

+

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}}\) + 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.

+
+
+

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 + \(\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 (e.g. to Sapling or Transparent).

+

For every Custom Asset that is burnt, we add to the + \(\mathsf{assetBurn}\) + set the tuple + \((\mathsf{AssetBase_{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}} : \mathbb{P}^*, \mathsf{v_{AssetId}} : \{1 .. 2^{\ell_{\mathsf{value}}} - 1\}) \,|\, \mathsf{AssetId} \in \mathsf{AssetIdsToBurn} \}\)
+

We denote by + \(L\) + the cardinality of the + \(\mathsf{assetBurn}\) + set.

+

Additional Consensus Rules

+
    +
  1. We require that for every + \((\mathsf{AssetBase_{AssetId}}, \mathsf{v_{AssetId}}) \in \mathsf{assetBurn}, \mathsf{AssetBase_{AssetId}} \neq \mathcal{V}^{\mathsf{Orchard}}\!\) + . That is, ZEC or TAZ is not allowed to be burnt by this mechanism.
    2. +
  2. We require that for every + \((\mathsf{AssetBase_{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_{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 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 + \(\mathsf{bsk} = \sum_{i=1}^{n} \mathsf{rcv}_i\!\) + .

+

The verifier MUST compute the value balance verification equation:

+
\(\mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv}^{\mathsf{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.

+

Rationale for Value Balance Verification

+

We assume + \(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 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}^{\mathsf{net}}_i) + (\sum_{j \in S_{\mathsf{CA}}} \mathsf{cv}^{\mathsf{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 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}^{\mathsf{net}}_j - \sum_{(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}} [\mathsf{v}]\,\mathsf{AssetBase} = \sum_{j \in S_{\mathsf{CA}}} [\mathsf{rcv}^{\mathsf{net}}_j]\,\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}}\) + 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 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

+

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 + \(\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.

+

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

For Split Notes, the nullifier is generated as follows:

+
\(\mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\text{ρ}^{\mathsf{old}}) + \text{ψ}') \bmod q_{\mathbb{P}}]\,\mathcal{K}^\mathsf{Orchard} + \mathsf{cm^{old}} + \mathcal{L}^\mathsf{Orchard})\)
+

where + \(\text{ψ}'\) + is sampled uniformly at random on + \(\mathbb{F}_{q_{\mathbb{P}}}\!\) + , + \(\mathcal{K}^{\mathsf{Orchard}}\) + is the Orchard Nullifier Base as defined in 19, and + \(\mathcal{L}^{\mathsf{Orchard}} := \mathsf{GroupHash^{\mathbb{P}}}(\texttt{"z.cash:Orchard"}, \texttt{"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 17 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 just 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}\) + 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 20, 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 31.

+

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_{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}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{old}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{old}}), \mathsf{v^{old}}, \text{ρ}^{\mathsf{old}}, \text{ψ}^{\mathsf{old}})\) + is replaced with + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{old}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{old}}), \mathsf{v^{old}}, \text{ρ}^{\mathsf{old}}, \text{ψ}^{\mathsf{old}}, \mathsf{AssetBase_{AssetId}})\!\) + .
    • +
  • In the New note commitment integrity constraint in the Orchard Action statement 20, + \(\mathsf{NoteCommit^{Orchard}_{rcm^{new}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{new}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{new}}), \mathsf{v^{new}}, \text{ρ}^{\mathsf{new}}, \text{ψ}^{\mathsf{new}})\) + is replaced with + \(\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{new}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{new}}), \mathsf{v^{new}}, \text{ρ}^{\mathsf{new}}, \text{ψ}^{\mathsf{new}}, \mathsf{AssetBase_{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}}\!\) + .

+
+
+

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:

+
    +
  • The fixed-base multiplication constraint 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_{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:

+
    +
  • +
    +
    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}}(\mathsf{AssetBase_{AssetId}}, \mathsf{v}' - \mathsf{v^{new}})\) +
      • +
    +
    +
    +
    • +
  • +
    +
    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 + \(\mathsf{split\_flag} = 1\) + then constrain + \(\mathsf{v}' = 0\) + otherwise constrain + \(\mathsf{v}' = \mathsf{v^{old}}\) + from the auxiliary input.
      • +
    • If + \(\mathsf{split\_flag} = 1\) + then constrain + \(\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 for all notes except dummy notes that + \((\mathsf{path}, \mathsf{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 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.

+
+
+
+

Orchard-ZSA Transaction Structure

+

The transaction format for v6 transactions is described in ZIP 230 10.

+
+

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.

+

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

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

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

+
+

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 + \(\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 split input notes and will not include dummy input notes.
    • +
+
+

Deployment

+

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

+
+
+

Test Vectors

+ +
+

Reference Implementation

+ +
+

References

+ + + + + + + +
1Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
+ + + + + + + +
2ZIP 200: Network Upgrade Mechanism
+ + + + + + + +
3ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances
+ + + + + + + +
4ZIP 224: Orchard
+ + + + + + + +
5ZIP 227: Issuance of Zcash Shielded Assets
+ + + + + + + +
6ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier
+ + + + + + + +
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 230: Version 6 Transaction Format
+ + + + + + + +
11ZIP 244: Transaction Identifier Non-Malleability
+ + + + + + + +
12ZIP 307: Light Client Protocol for Payment Detection
+ + + + + + + +
13ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
+ + + + + + + +
14Zcash Protocol Specification, Version 2023.4.0. Section 3.2: Notes
+ + + + + + + +
15Zcash Protocol Specification, Version 2023.4.0. Section 3.7: Action Transfers and their Descriptions
+ + + + + + + +
16Zcash Protocol Specification, Version 2023.4.0. Section 4.1.8: Commitment
+ + + + + + + +
17Zcash Protocol Specification, Version 2023.4.0. Section 4.8.3: Dummy Notes (Orchard)
+ + + + + + + +
18Zcash Protocol Specification, Version 2023.4.0. Section 4.14: Balance and Binding Signature (Orchard)
+ + + + + + + +
19Zcash Protocol Specification, Version 2023.4.0. Section 4.16: Note Commitments and Nullifiers
+ + + + + + + +
20Zcash Protocol Specification, Version 2023.4.0. Section 4.17.4: Action Statement (Orchard)
+ + + + + + + +
21Zcash Protocol Specification, Version 2023.4.0. Section 5.1: Integers, Bit Sequences, and Endianness
+ + + + + + + +
22Zcash Protocol Specification, Version 2023.4.0. Section 5.3: Constants
+ + + + + + + +
23Zcash Protocol Specification, Version 2023.4.0. Section 5.4.1.9: Sinsemilla hash function
+ + + + + + + +
24Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
+ + + + + + + +
25Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.4: Sinsemilla commitments
+ + + + + + + +
26Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.6: Pallas and Vesta
+ + + + + + + +
27Zcash Protocol Specification, Version 2023.4.0. Section 5.5: Encodings of Note Plaintexts and Memo Fields
+ + + + + + + +
28Zcash Protocol Specification, Version 2023.4.0. Section 7.5: Action Description Encoding and Consensus
+ + + + + + + +
29User-Defined Assets and Wrapped Assets
+ + + + + + + +
30Comment on Generalized Value Commitments
+ + + + + + + +
31Modifications to the Orchard circuit for the ZSA Protocol
+
\ No newline at end of file diff --git a/zip-0226.rst b/zip-0226.rst index 98fdb79a6..4d0e1c2f3 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -9,7 +9,478 @@ Credits: Daniel Benarroch Aurelien Nicolas Deirdre Connolly - 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 BCP 14 [#BCP14]_ when, and only when, it appears in all capitals. + +The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. + +The terms "Orchard" and "Action" in this document are 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 227 [#zip-0227]_. + +We define the following additional terms: + +- 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 +======== + +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. +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}` 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]_ [#protocol-actionencodingandconsensus]_ is preserved across Assets (see the Orchard Binding Signature [#protocol-orchardbalance]_), 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}} - \mathsf{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-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-concretehomomorphiccommit]_. 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-orcharddummynotes]_ 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 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. + +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 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}}\!`. + +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 +--------------------------- + +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}, \mathsf{pk_d}, \mathsf{v}, \text{ρ}, \text{ψ}, \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})\!`. + +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} + +where :math:`\mathbb{P}, \ell_{\mathbb{P}}, q_{\mathbb{P}}` are as defined for the Pallas curve [#protocol-pallasandvesta]_, and where :math:`\mathsf{NoteCommit^{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}}(\mathsf{g_d}\star, \mathsf{pk_d}\star, \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{AssetBase}) + := \begin{cases} + \mathsf{NoteCommit^{Orchard}_{rcm}}(\mathsf{g_d}\star, \mathsf{pk_d}\star, \mathsf{v}, \text{ρ}, \text{ψ}), &\text{if } \mathsf{AssetBase} = \mathcal{V}^{\mathsf{Orchard}} \\ + \mathsf{cm_{ZSA}} &\text{otherwise} + \end{cases} + \end{align} + +where: + +.. math:: \begin{align} + \mathsf{cm_{ZSA}} :=&\;\;\mathsf{SinsemillaHashToPoint}(\texttt{"z.cash:ZSA-NoteCommit-M"}, \\ + &\;\;\;\;\;\mathsf{g_{d}\star} \,||\, \mathsf{pk_{d}\star} \,||\, \mathsf{I2LEBSP_{64}(v)} \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\text{ρ}) \,||\, \mathsf{I2LEBSP}_{\ell^{\mathsf{Orchard}}_{\mathsf{base}}}(\text{ψ}) \,||\, \mathsf{asset\_base}) \\ + &\;\;+\;\;[\mathsf{rcm}]\,\mathsf{GroupHash}^{\mathbb{P}}(\texttt{"z.cash:Orchard-NoteCommit-r"}, \texttt{""}) + \end{align} + +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}^{[\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. +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}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d}), \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{AssetBase}) \in \mathsf{NoteCommit^{Orchard}}.\!\mathsf{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 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}} := \mathsf{ValueCommit^{OrchardZSA}_{rcv}}(\mathsf{AssetBase_{AssetId}}, \mathsf{v^{net}_{AssetId}}) = [\mathsf{v^{net}_{AssetId}}]\,\mathsf{AssetBase_{AssetId}} + [\mathsf{rcv}]\,\mathcal{R}^{\mathsf{Orchard}} + +where :math:`\mathsf{v^{net}_{AssetId}} = \mathsf{v^{old}_{AssetId}} - \mathsf{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_{AssetId}}` is defined in ZIP 227 [#zip-0227]_, and + +:math:`\mathcal{R}^{\mathsf{Orchard}} := \mathsf{GroupHash^{\mathbb{P}}}(\texttt{"z.cash:Orchard-cv"}, \texttt{"r"})\!`, as in the Orchard protocol. + +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}}(\mathsf{v})` as defined in [#zip-0224]_ is used as :math:`\mathsf{ValueCommit^{OrchardZSA}_{rcv}}(\mathcal{V}^{\mathsf{Orchard}}, \mathsf{v})` here. + +Rationale for Value Commitment +`````````````````````````````` + +The Orchard Protocol uses a Homomorphic Pedersen Commitment [#protocol-concretehomomorphiccommit]_ 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. + +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 (e.g. to Sapling or Transparent). + +For every Custom Asset that is burnt, we add to the :math:`\mathsf{assetBurn}` set the tuple :math:`(\mathsf{AssetBase_{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}} : \mathbb{P}^*, \mathsf{v_{AssetId}} : \{1 .. 2^{\ell_{\mathsf{value}}} - 1\}) \,|\, \mathsf{AssetId} \in \mathsf{AssetIdsToBurn} \} + +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_{AssetId}}, \mathsf{v_{AssetId}}) \in \mathsf{assetBurn}, \mathsf{AssetBase_{AssetId}} \neq \mathcal{V}^{\mathsf{Orchard}}\!`. That is, ZEC or TAZ is not allowed to be burnt by this mechanism. +2. We require that for every :math:`(\mathsf{AssetBase_{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_{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 a similar process as for the Orchard protocol [#protocol-orchardbalance]_, 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 value balance verification equation: + +.. math:: \mathsf{bvk} = (\sum_{i=1}^{n} \mathsf{cv}^{\mathsf{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 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}^{\mathsf{net}}_i) + (\sum_{j \in S_{\mathsf{CA}}} \mathsf{cv}^{\mathsf{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-orchardbalance]_. +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}^{\mathsf{net}}_j - \sum_{(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}} [\mathsf{v}]\,\mathsf{AssetBase} = \sum_{j \in S_{\mathsf{CA}}} [\mathsf{rcv}^{\mathsf{net}}_j]\,\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. +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. + + +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 :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. + +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). + +For Split Notes, the nullifier is generated as follows: + +.. math:: \mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\text{ρ}^{\mathsf{old}}) + \text{ψ}') \bmod q_{\mathbb{P}}]\,\mathcal{K}^\mathsf{Orchard} + \mathsf{cm^{old}} + \mathcal{L}^\mathsf{Orchard}) + +where :math:`\text{ψ}'` 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"}, \texttt{"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* [#protocol-orcharddummynotes]_ 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 *just 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 :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. + + +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 +``````````````````` + +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_{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}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{old}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{old}}), \mathsf{v^{old}}, \text{ρ}^{\mathsf{old}}, \text{ψ}^{\mathsf{old}})` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{old}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{old}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{old}}), \mathsf{v^{old}}, \text{ρ}^{\mathsf{old}}, \text{ψ}^{\mathsf{old}}, \mathsf{AssetBase_{AssetId}})\!`. +- In the New note commitment integrity constraint in the Orchard Action statement [#protocol-actionstatement]_, :math:`\mathsf{NoteCommit^{Orchard}_{rcm^{new}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{new}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{new}}), \mathsf{v^{new}}, \text{ρ}^{\mathsf{new}}, \text{ψ}^{\mathsf{new}})` is replaced with :math:`\mathsf{NoteCommit^{OrchardZSA}_{rcm^{new}}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d^{new}}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d^{new}}), \mathsf{v^{new}}, \text{ρ}^{\mathsf{new}}, \text{ψ}^{\mathsf{new}}, \mathsf{AssetBase_{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}}\!`. + +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 +```````````````````````````` + +The following constraints must be added to ensure that the value commitment is computed using the witnessed Asset Base: + +- The fixed-base multiplication constraint 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_{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: + +- 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}}(\mathsf{AssetBase_{AssetId}}, \mathsf{v}' - \mathsf{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. +- The Merkle Path Validity should check the existence of the note commitment as usual (and not like with dummy notes): + - Check for all notes except dummy notes that :math:`(\mathsf{path}, \mathsf{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 +`````````````````````````````````````` + +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. + +Orchard-ZSA Transaction Structure +================================= + +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. + +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 +=================================== + +- 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. + +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]_. + +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:`\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 split input notes and will not include dummy input notes. + +Deployment +----------- +The Zcash Shielded Assets protocol will be deployed in a subsequent Network Upgrade. + +Test Vectors +============ + +- https://github.com/QED-it/zcash-test-vectors + +Reference Implementation +======================== + +- 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 +========== + +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ +.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism `_ +.. [#zip-0209] `ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances `_ +.. [#zip-0224] `ZIP 224: Orchard `_ +.. [#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 `_ +.. [#zip-0230] `ZIP 230: Version 6 Transaction Format `_ +.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection `_ +.. [#zip-0317b] `ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs `_ +.. [#protocol-notes] `Zcash Protocol Specification, Version 2023.4.0. Section 3.2: Notes `_ +.. [#protocol-actions] `Zcash Protocol Specification, Version 2023.4.0. Section 3.7: Action Transfers and their Descriptions `_ +.. [#protocol-abstractcommit] `Zcash Protocol Specification, Version 2023.4.0. Section 4.1.8: Commitment `_ +.. [#protocol-orcharddummynotes] `Zcash Protocol Specification, Version 2023.4.0. Section 4.8.3: Dummy Notes (Orchard) `_ +.. [#protocol-orchardbalance] `Zcash Protocol Specification, Version 2023.4.0. Section 4.14: Balance and Binding Signature (Orchard) `_ +.. [#protocol-commitmentsandnullifiers] `Zcash Protocol Specification, Version 2023.4.0. Section 4.16: Note Commitments and Nullifiers `_ +.. [#protocol-actionstatement] `Zcash Protocol Specification, Version 2023.4.0. Section 4.17.4: Action Statement (Orchard) `_ +.. [#protocol-endian] `Zcash Protocol Specification, Version 2023.4.0. Section 5.1: Integers, Bit Sequences, and Endianness `_ +.. [#protocol-constants] `Zcash Protocol Specification, Version 2023.4.0. Section 5.3: Constants `_ +.. [#protocol-concretesinsemillahash] `Zcash Protocol Specification, Version 2023.4.0. Section 5.4.1.9: Sinsemilla hash function `_ +.. [#protocol-concretehomomorphiccommit] `Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard) `_ +.. [#protocol-concretesinsemillacommit] `Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.4: Sinsemilla commitments `_ +.. [#protocol-pallasandvesta] `Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.6: Pallas and Vesta `_ +.. [#protocol-notept] `Zcash Protocol Specification, Version 2023.4.0. Section 5.5: Encodings of Note Plaintexts and Memo Fields `_ +.. [#protocol-actionencodingandconsensus] `Zcash Protocol Specification, Version 2023.4.0. 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 `_ +.. [#circuit-modifications] `Modifications to the Orchard circuit for the ZSA Protocol `_ diff --git a/zip-0227-asset-identifier-relation.png b/zip-0227-asset-identifier-relation.png new file mode 100644 index 000000000..064e51960 Binary files /dev/null and b/zip-0227-asset-identifier-relation.png differ diff --git a/zip-0227-asset-identifier-relation.svg b/zip-0227-asset-identifier-relation.svg new file mode 100644 index 000000000..670ed1784 --- /dev/null +++ b/zip-0227-asset-identifier-relation.svg @@ -0,0 +1,296 @@ + + + +image/svg+xmlAssetDigestAssetIdAssetBaseAssetIdAssetIdAsset Digest diff --git a/zip-0227-key-components-zsa.png b/zip-0227-key-components-zsa.png new file mode 100644 index 000000000..51269a600 Binary files /dev/null and b/zip-0227-key-components-zsa.png differ diff --git a/zip-0227-key-components-zsa.svg b/zip-0227-key-components-zsa.svg new file mode 100644 index 000000000..eb38e4dcb --- /dev/null +++ b/zip-0227-key-components-zsa.svg @@ -0,0 +1,231 @@ + + + +image/svg+xmlIssuance validating keyZSA Key ComponentsiskikIssuance authorizing key diff --git a/zip-0227.html b/zip-0227.html index 9db3dcd41..86a06c336 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -3,6 +3,7 @@ ZIP 227: Issuance of Zcash Shielded Assets +
@@ -15,10 +16,973 @@ Credits: Daniel Benarroch Aurelien Nicolas Deirdre Connolly -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/680> +

Terminology

+

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

+

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

+

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

+

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

+

This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 9. 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 9. This ZIP must only be implemented in conjunction with ZIP 226 9. 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 single ZSA ZIP, 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 9.

+

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:

+
    +
  • 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 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 + \(\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 Orchard-ZSA Protocol adds the following keys to the key components 18 19:

+
    +
  1. 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.
    2. +
  2. The issuance validating key, denoted as + \(\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.
    3. +
+

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

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

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

+

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\) + and + \(\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:

+
    +
  • + \(\mathsf{IssueAuthSig}.\!\mathsf{Message} = \mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}\) +
    • +
  • + \(\mathsf{IssueAuthSig}.\!\mathsf{Signature} = \mathbb{B}^{\mathbb{Y}^{[64]}} \cup \{\bot\}\) +
    • +
  • + \(\mathsf{IssueAuthSig}.\!\mathsf{Public} = \mathbb{B}^{\mathbb{Y}^{[32]}} \cup \{\bot\}\) +
    • +
  • + \(\mathsf{IssueAuthSig}.\!\mathsf{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 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 authorizing key generation for hierarchical deterministic wallets

+

The issuance authorizing key is generated using the Orchard master key derivation procedure defined in ZIP 32 3. 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 4, 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 6 for shielded HD paths, and define the issuance authorizing key path as + \(m_{\mathsf{Issuance}} / \mathit{purpose}' / \mathit{coin\_type}' / \mathit{account}'\!\) + . We fix the path levels as follows:

+
    +
  • + \(\mathit{purpose}\) + : a constant set to + \(227\) + (i.e. + \(\mathtt{0xe3}\!\) + ). + \(\mathit{purpose}'\) + is thus + \(227'\) + (or + \(\mathtt{0x800000e3}\!\) + ) following the BIP 43 recommendation.
    • +
  • + \(\mathit{coin\_type}\) + : Defined as in ZIP 32 5.
    • +
  • + \(\mathit{account}\) + : fixed to index + \(0\!\) + .
    • +
+

From the generated + \((\mathsf{sk}, \mathsf{c})\!\) + , we set the issuance authorizing key to be + \(\mathsf{isk} := \mathsf{sk}\!\) + .

+
+

Derivation of issuance validating key

+

Define + \(\mathsf{IssueAuthSig}.\!\mathsf{DerivePublic}\; : \; (\mathsf{isk}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Private}) \to \mathsf{IssueAuthSig}.\!\mathsf{Public}\) + as:

+
    +
  • + \(\mathsf{ik} := \textit{PubKey}(\mathsf{isk})\) +
    • +
  • Return + \(\bot\) + if the + \(\textit{PubKey}\) + algorithm invocation fails, otherwise return + \(\mathsf{ik}\!\) + .
    • +
+

where the + \(\textit{PubKey}\) + algorithm is defined in BIP 340 16. 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 + \(\mathsf{IssueAuthSig}.\!\mathsf{DerivePublic}\) + could return + \(\bot\) + 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 2. 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}.\!\mathsf{Sign}\; : \; (\mathsf{isk}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Private}) \times (M\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Message}) \to \mathsf{IssueAuthSig}.\!\mathsf{Signature}\) + as:

+
    +
  • Let the auxiliary data + \(a = [\mathtt{0x00}]^{32}\!\) + .
    • +
  • Let + \(\text{σ} = \mathsf{Sign}(\mathsf{isk}, M)\!\) + .
    • +
  • Return + \(\bot\) + if the + \(\mathsf{Sign}\) + algorithm fails in the previous step, otherwise return + \(\text{σ}\!\) + .
    • +
+

where the + \(\mathsf{Sign}\) + algorithm is defined in BIP 340 and + \(a\) + denotes the auxiliary data used in BIP 340 16. Note that + \(\mathsf{IssueAuthSig}.\!\mathsf{Sign}\) + could return + \(\bot\) + with very low probability.

+

Define + \(\mathsf{IssueAuthSig}.\!\mathsf{Validate}\; : \; (\mathsf{ik}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Public}) \times (M\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Message}) \times (\text{σ}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Signature}) \to \mathbb{B}\) + as:

+
    +
  • Return + \(0\) + if + \(\text{σ} = \bot\!\) + .
    • +
  • Return + \(1\) + if + \(\mathsf{Verify}(\mathsf{ik}, M, \text{σ})\) + succeeds, otherwise + \(0\!\) + .
    • +
+

where the + \(\mathsf{Verify}\) + algorithm is defined in BIP 340 16.

+
+
+

Specification: Asset Identifier

+

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.

+

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}\) + 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

+
    +
  • + \(\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_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\!\) + , where

+
    +
  • + \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{asset\_desc}\!\!\) + .
    • +
  • Note that the initial + \(\mathtt{0x00}\) + byte is a version byte.
    • +
+

Define + \(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\) +

+

In the case of the Orchard-ZSA protocol, we define + \(\mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}})\) + where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in 20.

+

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.

+

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:

+
    +
  • + \(\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:

+
    +
  • assetDescSize: the size of the Asset description, a number between + \(0\) + and + \(512\!\) + , stored in two bytes.
    • +
  • 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 + \(\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 + \(\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 \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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BytesNameData TypeDescription
2assetDescSizebyteThe length of the 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\!\) + .
    • +
+
+
+
+

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:

+
    +
  • + \(\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.
    • +
  • + \(\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 22.

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

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 Specification: Asset Identifier section.
    • +
  • compute + \(\mathsf{AssetBase}\) + from + \(\mathsf{AssetDigest}\) + 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 + \(\mathsf{AssetBase}\!\) + , set + \(\mathsf{finalize} = 0\!\) + , otherwise set + \(\mathsf{finalize} = 1\!\) + ).
    • +
  • for each recipient + \(i\) + : +
      +
    • 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, \text{ρ}_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 + \(\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.
    • +
+

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:

+
    +
  • Validate the issuance authorization signature, + \(\mathsf{issueAuthSig}\!\) + , on the SIGHASH transaction hash, + \(\mathsf{SigHash}\!\) + , by invoking + \(\mathsf{IssueAuthSig}.\!\mathsf{Validate}(\mathsf{ik}, \mathsf{SigHash}, \mathsf{issueAuthSig})\!\) + .
    • +
+

For each IssueAction in IssueBundle:

+
    +
  • check that + \(0 < \mathtt{assetDescSize} \leq 512\!\) + .
    • +
  • check that + \(\mathsf{asset\_desc}\) + is a string of length + \(\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.
    • +
  • check that the + \(\mathsf{AssetDigest}\) + 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 + \(\mathsf{note} = (\mathsf{g_d}, \mathsf{pk_d}, \mathsf{v}, \text{ρ}, \mathsf{rseed}, \mathsf{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}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d}), \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{AssetBase})\) + as defined in the Note Structure and Commitment section of ZIP 226 10 and
    • +
  • Add + \(\mathsf{cm}\) + to the Merkle tree of note commitments.
    • +
  • If + \(\mathsf{finalize} = 1\!\) + , add + \(\mathsf{AssetDigest}\) + 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.
    • +
+
+

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 + \(\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 + \(\mathsf{finalize}\) + boolean and the burning mechanism defined in 9, issuers can control the supply production of any Asset associated to their issuer keys. For example, +
      +
    • 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 + \(\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 + \(\mathsf{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 + \(\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 + \(\mathsf{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 Orchard-ZSA protocol can be found in ZIP 226 11. As in ZIP 244 12, 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.

+

T.5: issuance_digest

+

A BLAKE2b-256 hash of the following values

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

+ 
"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)
+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:

+ 
"ZTxIdIAcNoteHash"
+
T.5a.i.1: recipient
+

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

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

+
+
T.5a.i.3: assetBase
+

Asset Base encoded as the 32-byte representation of a point on the Pallas curve.

+
+
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.5a.ii: assetDescription
+

The Asset description byte string.

+
+
T.5a.iii: flagsIssuance
+

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

+
    +
  • + \(\mathsf{finalize}\) +
    • +
  • The remaining bits are set to 0!.
    • +
+
+
+

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 13 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
+├── 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 12.

+

S.5: issuance_digest

+

Identical to that specified for the transaction identifier.

+
+
+
+

Authorizing Data Commitment

+

The transaction digest algorithm defined in ZIP 244 14 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
+├── 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

+

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:

+
    +
  • 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}\!\) + .
    • +
+
+

Bridging Assets

+

For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 9. 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 + \(\mathsf{issuanceSupplyInfoMap}\) + from + \(\mathsf{AssetId}\) + to + \((\mathsf{totalSupply}, \mathsf{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 317 15.

+
+
+

Test Vectors

+
    +
  • LINK TBD
    • +
+
+

Reference Implementation

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

Deployment

+

This ZIP is proposed to activate with Network Upgrade 6.

+
+

References

+ + + + + + + +
1Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
+ + + + + + + +
2ZIP 32: Shielded Hierarchical Deterministic Wallets
+ + + + + + + +
3ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation
+ + + + + + + +
4ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivation
+ + + + + + + +
5ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels
+ + + + + + + +
6ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path
+ + + + + + + +
7ZIP 200: Network Upgrade Mechanism
+ + + + + + + +
8ZIP 224: Orchard
+ + + + + + + +
9ZIP 226: Transfer and Burn of Zcash Shielded Assets
+ + + + + + + +
10ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment
+ + + + + + + +
11ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest
+ + + + + + + +
12ZIP 244: Transaction Identifier Non-Malleability
+ + + + + + + +
13ZIP 244: Transaction Identifier Non-Malleability: Signature Digest
+ + + + + + + +
14ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment
+ + + + + + + +
15ZIP 317: Proportional Transfer Fee Mechanism
+ + + + + + + +
16BIP 340: Schnorr Signatures for secp256k1
+ + + + + + + +
17Zcash Protocol Specification, Version 2023.4.0. Section 2: Notation
+ + + + + + + +
18Zcash Protocol Specification, Version 2023.4.0. Section 3.1: Payment Addresses and Keys
+ + + + + + + +
19Zcash Protocol Specification, Version 2023.4.0. Section 4.2.3: Orchard Key Components
+ + + + + + + +
20Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.8: Group Hash into Pallas and Vesta
+ + + + + + + +
21Zcash Protocol Specification, Version 2023.4.0. Section 5.6.4.2: Orchard Raw Payment Addresses
+ + + + + + + +
22Zcash Protocol Specification, Version 2023.4.0. 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 ed5d8d322..89e837f4a 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -9,7 +9,611 @@ Credits: Daniel Benarroch Aurelien Nicolas Deirdre Connolly - Status: Reserved + Teor + Status: Draft Category: Consensus + Created: 2022-05-01 + License: MIT Discussions-To: - Pull-Request: + Pull-Request: + + +Terminology +=========== + +The key words "MUST", "MUST NOT", "SHOULD", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in BCP 14 [#BCP14]_ when, and only when, they appear in all capitals. + +The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_. + +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 +======== + +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 +========== + +This ZIP introduces the issuance mechanism for Custom Assets on the Zcash chain. While originally part of a single ZSA ZIP, 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. + +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: + +- 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 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 :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 +======================================================================== + +The Orchard-ZSA Protocol adds the following keys to the key components [#protocol-addressesandkeys]_ [#protocol-orchardkeycomponents]_: + +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. + +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 Orchard-ZSA Protocol + + +Issuance Authorization Signature Scheme +--------------------------------------- + +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` and :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: + +* :math:`\mathsf{IssueAuthSig}.\!\mathsf{Message} = \mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}}` +* :math:`\mathsf{IssueAuthSig}.\!\mathsf{Signature} = \mathbb{B}^{\mathbb{Y}^{[64]}} \cup \{\bot\}` +* :math:`\mathsf{IssueAuthSig}.\!\mathsf{Public} = \mathbb{B}^{\mathbb{Y}^{[32]}} \cup \{\bot\}` +* :math:`\mathsf{IssueAuthSig}.\!\mathsf{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 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 [#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 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}} / \mathit{purpose}' / \mathit{coin\_type}' / \mathit{account}'\!`. We fix the path levels as follows: + +- :math:`\mathit{purpose}`: a constant set to :math:`227` (i.e. :math:`\mathtt{0xe3}\!`). :math:`\mathit{purpose}'` is thus :math:`227'` (or :math:`\mathtt{0x800000e3}\!`) following the BIP 43 recommendation. +- :math:`\mathit{coin\_type}`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_. +- :math:`\mathit{account}`: fixed to index :math:`0\!`. + +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}.\!\mathsf{DerivePublic}\; : \; (\mathsf{isk}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Private}) \to \mathsf{IssueAuthSig}.\!\mathsf{Public}` as: + +* :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]_. +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}.\!\mathsf{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. + +Issuance Authorization Signing and Validation +--------------------------------------------- + +Define :math:`\mathsf{IssueAuthSig}.\!\mathsf{Sign}\; : \; (\mathsf{isk}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Private}) \times (M\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Message}) \to \mathsf{IssueAuthSig}.\!\mathsf{Signature}` as: + +* Let the auxiliary data :math:`a = [\mathtt{0x00}]^{32}\!`. +* Let :math:`\text{σ} = \mathsf{Sign}(\mathsf{isk}, M)\!`. +* Return :math:`\bot` if the :math:`\mathsf{Sign}` algorithm fails in the previous step, otherwise return :math:`\text{σ}\!`. + +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}.\!\mathsf{Sign}` could return :math:`\bot` with very low probability. + + +Define :math:`\mathsf{IssueAuthSig}.\!\mathsf{Validate}\; : \; (\mathsf{ik}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Public}) \times (M\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Message}) \times (\text{σ}\; : \; \mathsf{IssueAuthSig}.\!\mathsf{Signature}) \to \mathbb{B}` as: + +* Return :math:`0` if :math:`\text{σ} = \bot\!`. +* Return :math:`1` if :math:`\mathsf{Verify}(\mathsf{ik}, M, \text{σ})` 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-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 + +- :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_{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})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{asset\_desc}\!\!`. +- Note that the initial :math:`\mathtt{0x00}` byte is a version byte. + +Define :math:`\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})` + +In the case of the Orchard-ZSA protocol, we define :math:`\mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{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: + +.. 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 + + +**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 +==================================== + +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 :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 +===================================================================== + +Issuance Action Description +--------------------------- + +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. +- ``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 :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 ``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 :math:`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: + +- :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-txnencoding]_. + ++------------------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------------+ +| 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``: + +- 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 :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-ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \text{ρ}_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. + + +**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``: + +- Validate the issuance authorization signature, :math:`\mathsf{issueAuthSig}\!`, on the SIGHASH transaction hash, :math:`\mathsf{SigHash}\!`, by invoking :math:`\mathsf{IssueAuthSig}.\!\mathsf{Validate}(\mathsf{ik}, \mathsf{SigHash}, \mathsf{issueAuthSig})\!`. + +For each ``IssueAction`` in ``IssueBundle``: + +- check that :math:`0 < \mathtt{assetDescSize} \leq 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}, \mathsf{pk_d}, \mathsf{v}, \text{ρ}, \mathsf{rseed}, \mathsf{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}}(\mathsf{repr}_{\mathbb{P}}(\mathsf{g_d}), \mathsf{repr}_{\mathbb{P}}(\mathsf{pk_d}), \mathsf{v}, \text{ρ}, \text{ψ}, \mathsf{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 :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 +========= +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 :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 :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 :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 :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 :math:`\mathsf{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. + +- 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 :math:`\mathsf{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. + + + +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 [#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:: + + 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. + +T.5: issuance_digest +-------------------- +A BLAKE2b-256 hash of the following values :: + + 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.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.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:: + + "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) + 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:: + + "ZTxIdIAcNoteHash" + +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.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. + +T.5a.i.3: assetBase +................... +Asset Base encoded as the 32-byte representation of a point on the Pallas curve. + +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.5a.ii: assetDescription +''''''''''''''''''''''''' +The Asset description byte string. + +T.5a.iii: flagsIssuance +''''''''''''''''''''''' +An 8-bit value representing a set of flags. Ordered from LSB to MSB: + +- :math:`\mathsf{finalize}` +- The remaining bits are set to `0\!`. + + +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 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 + ├── 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 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 + ├── 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 +=================================== + +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: + +- 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 +--------------- + +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 :math:`\mathsf{issuanceSupplyInfoMap}` from :math:`\mathsf{AssetId}` to :math:`(\mathsf{totalSupply}, \mathsf{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 317 [#zip-0317b]_. + + +Test Vectors +============ + +- LINK TBD + +Reference Implementation +======================== + +- LINK TBD +- LINK TBD + +Deployment +========== + +This ZIP is proposed to activate with Network Upgrade 6. + +References +========== + +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ +.. [#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-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-0226-txiddigest] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest `_ +.. [#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 317: Proportional Transfer Fee Mechanism `_ +.. [#bip-0340] `BIP 340: Schnorr Signatures for secp256k1 `_ +.. [#protocol-notation] `Zcash Protocol Specification, Version 2023.4.0. Section 2: Notation `_ +.. [#protocol-addressesandkeys] `Zcash Protocol Specification, Version 2023.4.0. Section 3.1: Payment Addresses and Keys `_ +.. [#protocol-orchardkeycomponents] `Zcash Protocol Specification, Version 2023.4.0. Section 4.2.3: Orchard Key Components `_ +.. [#protocol-concretegrouphashpallasandvesta] `Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.8: Group Hash into Pallas and Vesta `_ +.. [#protocol-orchardpaymentaddrencoding] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6.4.2: Orchard Raw Payment Addresses `_ +.. [#protocol-txnencoding] `Zcash Protocol Specification, Version 2023.4.0. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) `_ diff --git a/zip-0230.html b/zip-0230.html index 130594ab9..dc1547dcd 100644 --- a/zip-0230.html +++ b/zip-0230.html @@ -3,21 +3,644 @@ ZIP 230: Version 6 Transaction Format + 
ZIP: 230
 Title: Version 6 Transaction Format
-Owners: Daira Emma Hopwood <daira@electriccoin.co>
+Owners: Daira-Emma Hopwood <daira@electriccoin.co>
         Jack Grigg <jack@electriccoin.co>
         Sean Bowe <sean@electriccoin.co>
         Kris Nuttycombe <kris@electriccoin.co>
+        Pablo Kogan <pablo@qed-it.com>
+        Vivek Arte <vivek@qed-it.com>
 Original-Authors: Greg Pfeil
                   Deirdre Connolly
 Credits: Ying Tong Lai
-Status: Reserved
+Status: Draft
 Category: Consensus
+Created: 2023-04-18
+License: MIT
 Discussions-To: <https://github.com/zcash/zips/issues/686>
+

Terminology

+

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

+

The 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 operations related to Zcash Shielded Assets (ZSAs). The new format adds and describes new fields containing ZSA-specific elements. Like the existing v5 transaction format, it keeps well-bounded regions of the serialized form to serve each pool of funds.

+

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

+
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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 7.
+
    +
  • 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^{Orchard}}\!\) + .
8valueBurn + \(\{1 .. 2^{64} - 1\}\) + The amount being burnt.
+

The encodings of each of these elements are defined in ZIP 226 6.

+
+

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

+
+
+

Reference implementation

+

TODO

+
+

References

+ + + + + + + +
1Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
+ + + + + + + +
2Zcash Protocol Specification, Version 2023.4.0 or later [NU5 proposal]
+ + + + + + + +
3Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.4: Spend Descriptions
+ + + + + + + +
4Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.5: Output Descriptions
+ + + + + + + +
5Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.6: Action Descriptions
+ + + + + + + +
6ZIP 226: Transfer and Burn of Zcash Shielded Assets
+ + + + + + + +
7ZIP 227: Issuance of Zcash Shielded Assets
+ + + + + + + +
8ZIP 244: Transaction Identifier Non-Malleability
+
\ No newline at end of file diff --git a/zip-0230.rst b/zip-0230.rst index 068267498..e807d6140 100644 --- a/zip-0230.rst +++ b/zip-0230.rst @@ -2,13 +2,351 @@ ZIP: 230 Title: Version 6 Transaction Format - Owners: Daira Emma Hopwood + Owners: Daira-Emma Hopwood Jack Grigg Sean Bowe Kris Nuttycombe + Pablo Kogan + Vivek Arte Original-Authors: Greg Pfeil Deirdre Connolly Credits: Ying Tong Lai - Status: Reserved + Status: Draft Category: Consensus + Created: 2023-04-18 + License: MIT Discussions-To: + + +Terminology +=========== + +The key words "MUST", "SHOULD", and "MAY" in this document are to be interpreted as +described in BCP 14 [#BCP14]_ when, and only when, they appear in all capitals. + +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 operations related to Zcash +Shielded Assets (ZSAs). The new format adds and describes new fields containing +ZSA-specific elements. Like the existing v5 transaction format, it keeps well-bounded +regions of the serialized form to serve each pool of funds. + +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 :math:`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 :math:`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 :math:`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 :math:`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 :math:`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 :math:`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^{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 :math:`0\!`. | ++-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ + +The encodings of each of these elements are defined in ZIP 227 [#zip-0227]_. + +Reference implementation +======================== + +TODO + + +References +========== + +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ +.. [#protocol] `Zcash Protocol Specification, Version 2023.4.0 or later [NU5 proposal] `_ +.. [#protocol-spenddesc] `Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.4: Spend Descriptions `_ +.. [#protocol-outputdesc] `Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.5: Output Descriptions `_ +.. [#protocol-actiondesc] `Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.6: Action Descriptions `_ +.. [#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 `_