From 472ebe7784f46601b433b49b1e3ce7f3175770a0 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:12:05 +0530 Subject: [PATCH 01/17] Adding the `orchard_zsa_burn_digest` to the TxId digest. (#53) This adds a field to the TxId digest to include the burn fields of the transaction to the SIGHASH. --- zip-0226.html | 26 +++++++++++++++++++++++--- zip-0226.rst | 37 ++++++++++++++++++++++++++++++++++--- 2 files changed, 57 insertions(+), 6 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 4ebbc36b4..2eaebee0a 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -467,9 +467,10 @@

The 
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.4d: orchard_zsa_burn_digest (32-byte hash output) [ADDED FOR ZSA] +T.4e: flagsOrchard (1 byte) +T.4f: valueBalanceOrchard (64-bit signed little-endian) +T.4g: 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)
@@ -494,6 +495,25 @@ 
The
                         
The personalization field of this hash is defined identically to ZIP 244:

                         
"ZTxIdOrcActNHash"
+
T.4d: orchard_zsa_burn_digest
+

A BLAKE2b-256 hash of the data from the burn fields of the transaction. For each tuple in the + \(\mathsf{assetBurn}\) + set, the following elements are included in the hash:

+ 
T.4d.i : assetBase    (field encoding bytes)
+T.4d.ii: valueBurn    (field encoding bytes)
+

The personalization field of this hash is set to:

+ 
"ZTxIdOrcBurnHash"
+

In case the transaction does not perform the burning of any Assets (i.e. the + \(\mathsf{assetBurn}\) + set is empty), the ''orchard_zsa_burn_digest'' is:

+ 
BLAKE2b-256("ZTxIdOrcBurnHash", [])
+
T.4d.i: assetBase
+

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

+
+
T.4d.ii: valueBurn
+

Value of the Asset Base being burnt encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.

+
+

T.5: issuance_digest

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

diff --git a/zip-0226.rst b/zip-0226.rst index 4d0e1c2f3..826cf6342 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -344,9 +344,10 @@ When Orchard Actions are present in the transaction, this digest is a BLAKE2b-25 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.4d: orchard_zsa_burn_digest (32-byte hash output) [ADDED FOR ZSA] + T.4e: flagsOrchard (1 byte) + T.4f: valueBalanceOrchard (64-bit signed little-endian) + T.4g: anchorOrchard (32 bytes) T.4a: orchard_actions_compact_digest '''''''''''''''''''''''''''''''''''' @@ -397,6 +398,36 @@ The personalization field of this hash is defined identically to ZIP 244:: "ZTxIdOrcActNHash" + +T.4d: orchard_zsa_burn_digest +''''''''''''''''''''''''''''' + +A BLAKE2b-256 hash of the data from the burn fields of the transaction. For each tuple in +the :math:`\mathsf{assetBurn}` set, the following elements are included in the hash:: + + T.4d.i : assetBase (field encoding bytes) + T.4d.ii: valueBurn (field encoding bytes) + +The personalization field of this hash is set to:: + + "ZTxIdOrcBurnHash" + +In case the transaction does not perform the burning of any Assets (i.e. the +:math:`\mathsf{assetBurn}` set is empty), the ''orchard_zsa_burn_digest'' is:: + + BLAKE2b-256("ZTxIdOrcBurnHash", []) + +T.4d.i: assetBase +................. +The Asset Base being burnt encoded as the 32-byte representation of a point on the +Pallas curve. + +T.4d.ii: valueBurn +.................. +Value of the Asset Base being burnt encoded as little-endian 8-byte representation +of 64-bit unsigned integer (e.g. u64 in Rust) raw value. + + T.5: issuance_digest ```````````````````` The details of the computation of this value are in ZIP 227 [#zip-0227-txiddigest]_. From be397c7c88d7bdaa2ca0a5a71161a557d10f2b0b Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Fri, 17 May 2024 10:31:52 +0530 Subject: [PATCH 02/17] Setting transaction to contain issuance fields if and only if a non-zero number of issuance actions are present. (#54) As described in the title, this adds to the transaction format to require that the `ik` and `issueAuthSig` fields be present in the transaction format if and only if there are a non-zero number of issuance actions. --- zip-0227.html | 4 +++- zip-0227.rst | 6 +++++- zip-0230.html | 9 ++++++--- zip-0230.rst | 14 +++++++++----- 4 files changed, 23 insertions(+), 10 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 86a06c336..bcd47cb5a 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -658,7 +658,7 @@ 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:

+

In case the transaction has no issuance components, ''issuance_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:

@@ -676,6 +676,8 @@ T.5a.i.5: rseed (field encoding bytes)

The personalization field of this hash is set to:

"ZTxIdIAcNoteHash"
+

In case the transaction has no Issue Notes, ''issue_notes_digest'' is:

+ 
BLAKE2b-256("ZTxIdIAcNoteHash", [])
T.5a.i.1: recipient

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

diff --git a/zip-0227.rst b/zip-0227.rst index 89e837f4a..95708a8f3 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -406,7 +406,7 @@ The personalization field of this hash is set to:: "ZTxIdSAIssueHash" -In case the transaction has no issuance components, ''issue_actions_digest'' is:: +In case the transaction has no issuance components, ''issuance_digest'' is:: BLAKE2b-256("ZTxIdSAIssueHash", []) @@ -436,6 +436,10 @@ The personalization field of this hash is set to:: "ZTxIdIAcNoteHash" +In case the transaction has no Issue Notes, ''issue_notes_digest'' is:: + + BLAKE2b-256("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]_. diff --git a/zip-0230.html b/zip-0230.html index dc1547dcd..0453fb38e 100644 --- a/zip-0230.html +++ b/zip-0230.html @@ -324,6 +324,8 @@
  • The field anchorSapling is present if and only if \(\mathtt{nSpendsSapling} > 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 fields flagsOrchard, valueBalanceOrchard, anchorOrchard, sizeProofsOrchardZSA, proofsOrchardZSA, and bindingSigOrchard are present if and only if \(\mathtt{nActionsOrchard} > 0\!\) . If valueBalanceOrchard is not present, then @@ -331,9 +333,10 @@ 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.
    • +
  • The fields ik and issueAuthSig are present if and only if + \(\mathtt{nIssueActions} > 0\!\) + .
  • For coinbase transactions, the enableSpendsOrchard and enableZSAs bits MUST be set to \(0\!\) .
    • @@ -569,7 +572,7 @@ -

    The encodings of each of these elements are defined in ZIP 227 7.

    +

    The encodings of each of these elements are defined in ZIP 227 7. Note that we allow the number of notes (represented by nNotes) to be zero. This allows for issuers to create Issuance Actions to only finalize an issued Asset, without needing them to simultaneously issue more of that Asset.

    Reference implementation

    diff --git a/zip-0230.rst b/zip-0230.rst index e807d6140..8ed76751c 100644 --- a/zip-0230.rst +++ b/zip-0230.rst @@ -195,11 +195,6 @@ Transaction Format * 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 @@ -209,11 +204,18 @@ Transaction Format ``vOutputsSapling`` and MUST be ordered such that the proof at a given index corresponds to the ``OutputDescriptionV6`` at the same index. +* 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 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. +* The fields ``ik`` and ``issueAuthSig`` are present if and only if :math:`\mathtt{nIssueActions} > 0\!`. + * 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. @@ -332,6 +334,8 @@ An issuance action, ``IssueAction``, is the instance of issuing a specific Custo +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ The encodings of each of these elements are defined in ZIP 227 [#zip-0227]_. +Note that we allow the number of notes (represented by ``nNotes``) to be zero. +This allows for issuers to create Issuance Actions to only finalize an issued Asset, without needing them to simultaneously issue more of that Asset. Reference implementation ======================== From d8fba699840c821066ca4a42ee4df43ebe4dc1d5 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Fri, 19 Jul 2024 22:40:39 +0530 Subject: [PATCH 03/17] Updating the spec for clarity and parity with the implementation of the V7 transaction details (#55) A quick summary of the changes here: - The `assetDescSize` field in the issuance action description is encoded as a `compactSize` type, as is standard across the specification (and also allows for the use of the existing methods in the implementation). - The description of the notes used inside the issuance bundle were explicitly serialized to remove ambiguity. - The type of the `valueBurn` field was set to the standard `uint64` type. - The order of the Orchard bundle fields was adjusted to have the binding signature after the burn fields. --- zip-0230.html | 82 ++++++++++++++++++++++++++++++++++++++------------- zip-0230.rst | 41 +++++++++++++++++++------- 2 files changed, 93 insertions(+), 30 deletions(-) diff --git a/zip-0230.html b/zip-0230.html index 0453fb38e..4b7648efd 100644 --- a/zip-0230.html +++ b/zip-0230.html @@ -263,15 +263,6 @@ 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 @@ -284,6 +275,12 @@ AssetBurn[nAssetBurn] A sequence of Asset Burn descriptions, encoded per Orchard-ZSA Asset Burn Description. + + 64 + bindingSigOrchard + byte[64] + An Orchard-ZSA binding signature on the SIGHASH transaction hash. + Orchard-ZSA Issuance Fields @@ -505,10 +502,8 @@ 8 valueBurn - - \(\{1 .. 2^{64} - 1\}\) - - The amount being burnt. + uint64 + The amount being burnt. The value is checked by consensus to be non-zero. @@ -527,9 +522,9 @@ - 2 + varies assetDescSize - byte + compactSize The length of the asset description string in bytes. @@ -542,13 +537,13 @@ varies nNotes compactSize - The number of notes in the issuance action. + The number of notes in the Issuance Action. - noteSize * nNotes + 147 * nNotes vNotes - Note[nNotes] - A sequence of note descriptions within the issuance action, where noteSize is the size, in bytes, of a Note. + IssueNote[nNotes] + A sequence of note descriptions within the Issuance Action. 1 @@ -572,7 +567,54 @@ -

    The encodings of each of these elements are defined in ZIP 227 7. Note that we allow the number of notes (represented by nNotes) to be zero. This allows for issuers to create Issuance Actions to only finalize an issued Asset, without needing them to simultaneously issue more of that Asset.

    +

    The encoding of IssueNote is described below. Note that we allow the number of notes (represented by nNotes) to be zero. This allows for issuers to create Issuance Actions to only finalize an issued Asset, without needing them to simultaneously issue more of that Asset.

    +
    +

    Issue Note Description (IssueNote)

    +

    An issuance note, IssueNote contains the following fields:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    BytesNameData TypeDescription
    43recipientbyte[43]The raw encoding of an Orchard Raw Payment Address, as per protocol §5.6.4.2 ‘Orchard Raw Payment Addresses’.
    8valueuint64The amount being issued in this note.
    32assetBasebyte[32]The encoding of the Asset Base + \(\mathsf{AssetBase^{Orchard}}\!\) + , as defined in 'ZIP 227'.
    32rhobyte[32]This is defined and encoded in the same manner as for Orchard notes in protocol §3.2 'Notes'.
    32rseedbyte[32]The rseed field of the note, encoded as for Orchard notes in protocol §3.2 'Notes'.

    Reference implementation

    diff --git a/zip-0230.rst b/zip-0230.rst index 8ed76751c..3629a0357 100644 --- a/zip-0230.rst +++ b/zip-0230.rst @@ -166,15 +166,13 @@ Transaction Format +------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ |``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`_. | +------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ +|``64`` |``bindingSigOrchard`` |``byte[64]`` |An Orchard-ZSA binding signature on the SIGHASH transaction hash. | ++------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ | **Orchard-ZSA Issuance Fields** | +------------------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------------+ |``varies`` |``nIssueActions`` |``compactSize`` |The number of issuance actions in the bundle. | @@ -304,7 +302,7 @@ An Orchard-ZSA Asset Burn description is encoded in a transaction as an instance +=======+===============+=============================+====================================================================================================================+ | 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. | +| 8 | ``valueBurn`` | ``uint64`` | The amount being burnt. The value is checked by consensus to be non-zero. | +-------+---------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ The encodings of each of these elements are defined in ZIP 226 [#zip-0226]_. @@ -317,26 +315,49 @@ An issuance action, ``IssueAction``, is the instance of issuing a specific Custo +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=============================+==========================+===========================================+=====================================================================+ -|``2`` |``assetDescSize`` |``byte`` |The length of the asset description string in bytes. | +|``varies`` |``assetDescSize`` |``compactSize`` |The length of the asset description string in bytes. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``assetDescSize`` |``asset_desc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | | | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | | | | |or later. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``varies`` |``nNotes`` |``compactSize`` |The number of notes in the issuance action. | +|``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. | +|``147 * nNotes`` |``vNotes`` |``IssueNote[nNotes]`` |A sequence of note descriptions within the Issuance Action. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``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]_. +The encoding of ``IssueNote`` is described below. Note that we allow the number of notes (represented by ``nNotes``) to be zero. This allows for issuers to create Issuance Actions to only finalize an issued Asset, without needing them to simultaneously issue more of that Asset. +Issue Note Description (``IssueNote``) +-------------------------------------- + +An issuance note, ``IssueNote`` contains the following fields: + ++-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ +| Bytes | Name | Data Type | Description | ++=============================+==========================+======================================+====================================================================+ +|``43`` |``recipient`` |``byte[43]`` |The raw encoding of an Orchard Raw Payment Address, as | +| | | |per protocol §5.6.4.2 ‘Orchard Raw Payment Addresses’. | ++-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ +|``8`` |``value`` |``uint64`` |The amount being issued in this note. | ++-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ +|``32`` |``assetBase`` |``byte[32]`` |The encoding of the Asset Base | +| | | |:math:`\mathsf{AssetBase^{Orchard}}\!`, as defined in 'ZIP 227'. | ++-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ +|``32`` |``rho`` |``byte[32]`` |This is defined and encoded in the same manner as for Orchard | +| | | |notes in protocol §3.2 'Notes'. | ++-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ +|``32`` |``rseed`` |``byte[32]`` |The ``rseed`` field of the note, encoded as for Orchard notes in | +| | | |protocol §3.2 'Notes'. | ++-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ + + Reference implementation ======================== From 92691d9b001bb18f84e53f37556ab906c57af937 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Mon, 5 Aug 2024 23:30:46 +0530 Subject: [PATCH 04/17] Renaming psi' to psi^{nf} in ZIP 226 (#56) This resolves https://github.com/zcash/zips/issues/752 --- zip-0226.html | 4 ++-- zip-0226.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index 2eaebee0a..a1b8fe8ee 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -293,9 +293,9 @@
  • The Split Input note could be an already spent note containing the same Asset Base (note that by zeroing the value in the circuit, we prevent double spending).

    • For Split Notes, the nullifier is generated as follows:

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

    where - \(\text{ψ}'\) + \(\text{ψ}^{\mathsf{nf}}\) is sampled uniformly at random on \(\mathbb{F}_{q_{\mathbb{P}}}\!\) , diff --git a/zip-0226.rst b/zip-0226.rst index 826cf6342..d00e83216 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -243,9 +243,9 @@ Wallets and other clients have to choose from the following to ensure the Asset 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}) +.. math:: \mathsf{nf_{old}} = \mathsf{Extract}_{\mathbb{P}} ([(\mathsf{PRF^{nfOrchard}_{nk}} (\text{ρ}^{\mathsf{old}}) + \text{ψ}^{\mathsf{nf}}) \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"})\!`. +where :math:`\text{ψ}^{\mathsf{nf}}` 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 ````````````````````````` From be9d90c89f5e7bd0266aeea3f1bd1458f720a933 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Sun, 11 Aug 2024 20:25:05 +0530 Subject: [PATCH 05/17] Clarification about protocol behaviour when enableZSAs is set to true. (#57) This resolves https://github.com/zcash/zips/issues/846 --- zip-0226.html | 6 +++++- zip-0226.rst | 4 +++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/zip-0226.html b/zip-0226.html index a1b8fe8ee..df2f822d8 100644 --- a/zip-0226.html +++ b/zip-0226.html @@ -66,7 +66,11 @@ 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).

    + boolean flag. When this flag is set to false, the proof will fail for any non-native Asset, making it impossible to perform transactions involving Custom Assets. When this flag is set to true, the circuit will allow transactions involving Custom Assets subject to the values of the + \(\mathsf{enableSpendsOrchard}\) + and + \(\mathsf{enableOutputsOrchard}\) + flags, similar to the vanilla Orchard setting.

    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.

    diff --git a/zip-0226.rst b/zip-0226.rst index d00e83216..0e5e833a4 100644 --- a/zip-0226.rst +++ b/zip-0226.rst @@ -60,7 +60,9 @@ Because in a single transaction all value commitments are balanced, there must b In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes [#protocol-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). +We include the ability to pause the ZSA functionality, via a :math:`\mathsf{enableZSA}` boolean flag. +When this flag is set to false, the proof will fail for any non-native Asset, making it impossible to perform transactions involving Custom Assets. +When this flag is set to true, the circuit will allow transactions involving Custom Assets subject to the values of the :math:`\mathsf{enableSpendsOrchard}` and :math:`\mathsf{enableOutputsOrchard}` flags, similar to the vanilla Orchard setting. 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. From c0c2600b34e36879843935cd1da04a9550be4c1d Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 15 Aug 2024 14:52:23 +0530 Subject: [PATCH 06/17] Updating specification of the global issuance state, the issued_assets map (#59) This adds a map called `issued_assets` to the global state. This is used to track ZSA balances in the shielded pool along the lines of ZIP 209. This should resolve https://github.com/zcash/zips/issues/844. --- rendered/zip-0226.html | 154 +++++++++++++++++++++++----------------- rendered/zip-0227.html | 156 ++++++++++++++++++++++++++--------------- zips/zip-0226.rst | 10 ++- zips/zip-0227.rst | 34 +++++++-- 4 files changed, 221 insertions(+), 133 deletions(-) diff --git a/rendered/zip-0226.html b/rendered/zip-0226.html index c54818e33..5fdacb6ce 100644 --- a/rendered/zip-0226.html +++ b/rendered/zip-0226.html @@ -32,7 +32,7 @@
    @@ -48,18 +48,18 @@ . This Asset Identifier maps to an Asset Base \(\mathsf{AssetBase}\) that is stored in Orchard-based ZSA notes. These terms are formally defined in ZIP 227 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 +

    The Asset Identifier (via means of the Asset Digest and Asset Base) will be used to enforce that the balance of an Action Description 16 29 is preserved across Assets (see the Orchard Binding Signature 19), 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, +

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

    -

    Because in a single transaction all value commitments are balanced, there must be as many different value base points as there are Asset Identifiers for a given shielded protocol used in a transaction. We propose to make the Asset Base 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 +

    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 21, 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 26, and as the base point in the value commitment 25. This ensures (1) that the input and output notes are of the same Asset Base, and (2) that only Actions with the same Asset Base will balance out in the Orchard binding signature.

    +

    In order to ensure the security of the transfers, and as we will explain below, we are redefining input dummy notes 18 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}\) @@ -98,7 +98,7 @@ be the type of a ZSA note, i.e. \(\mathsf{Note^{OrchardZSA}} := \mathsf{Note^{Orchard}} \times \mathbb{P}^*\!\) .

    -

    An Orchard ZSA note differs from an Orchard note 14 by additionally including the Asset Base, +

    An Orchard ZSA note differs from an Orchard note 15 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})\!\) @@ -106,7 +106,7 @@

    Backwards Compatibility with ZEC Notes

    -

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

    +

    The input note in the old note commitment integrity check must either include an Asset Base (ZSA note) or not (pre-ZSA Orchard note). If the note is a pre-ZSA Orchard note, the note commitment is computed in the original Orchard fashion 17. 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.

    +

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

    TxId Digest

    -

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

    +

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

    txid_digest

    A BLAKE2b-256 hash of the following values

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

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

    +

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

    T.4: orchard_digest

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

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

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

    +

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

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

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

    +

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

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

    T.5: issuance_digest

    -

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

    +

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

    Signature Digest and Authorizing Data Commitment

    -

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

    +

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

    Security and Privacy Considerations

    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.

    +

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

    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:

    @@ -609,10 +623,18 @@

    The - +
    + + + +
    6ZIP 227: Issuance of Zcash Shielded Assets: Specification: Global Issuance State
    + + + + @@ -620,7 +642,7 @@

    The

    7 ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier
    - + @@ -628,7 +650,7 @@

    The

    78 ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance
    - + @@ -636,7 +658,7 @@

    The

    89 ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest
    - + @@ -644,7 +666,7 @@

    The

    910 ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment
    - + @@ -652,7 +674,7 @@

    The

    1011 ZIP 230: Version 6 Transaction Format
    - + @@ -660,7 +682,7 @@

    The

    1112 ZIP 244: Transaction Identifier Non-Malleability
    - + @@ -668,7 +690,7 @@

    The

    1213 ZIP 307: Light Client Protocol for Payment Detection
    - + @@ -676,7 +698,7 @@

    The

    1314 ZIP 317: Proportional Transfer Fee Mechanism - Pull Request #667 for ZSA Protocol ZIPs
    - + @@ -684,7 +706,7 @@

    The

    1415 Zcash Protocol Specification, Version 2023.4.0. Section 3.2: Notes
    - + @@ -692,7 +714,7 @@

    The

    1516 Zcash Protocol Specification, Version 2023.4.0. Section 3.7: Action Transfers and their Descriptions
    - + @@ -700,7 +722,7 @@

    The

    1617 Zcash Protocol Specification, Version 2023.4.0. Section 4.1.8: Commitment
    - + @@ -708,7 +730,7 @@

    The

    1718 Zcash Protocol Specification, Version 2023.4.0. Section 4.8.3: Dummy Notes (Orchard)
    - + @@ -716,7 +738,7 @@

    The

    1819 Zcash Protocol Specification, Version 2023.4.0. Section 4.14: Balance and Binding Signature (Orchard)
    - + @@ -724,7 +746,7 @@

    The

    1920 Zcash Protocol Specification, Version 2023.4.0. Section 4.16: Note Commitments and Nullifiers
    - + @@ -732,7 +754,7 @@

    The

    2021 Zcash Protocol Specification, Version 2023.4.0. Section 4.17.4: Action Statement (Orchard)
    - + @@ -740,7 +762,7 @@

    The

    2122 Zcash Protocol Specification, Version 2023.4.0. Section 5.1: Integers, Bit Sequences, and Endianness
    - + @@ -748,7 +770,7 @@

    The

    2223 Zcash Protocol Specification, Version 2023.4.0. Section 5.3: Constants
    - + @@ -756,7 +778,7 @@

    The

    2324 Zcash Protocol Specification, Version 2023.4.0. Section 5.4.1.9: Sinsemilla hash function
    - + @@ -764,7 +786,7 @@

    The

    2425 Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard)
    - + @@ -772,7 +794,7 @@

    The

    2526 Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.4: Sinsemilla commitments
    - + @@ -780,7 +802,7 @@

    The

    2627 Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.6: Pallas and Vesta
    - + @@ -788,7 +810,7 @@

    The

    2728 Zcash Protocol Specification, Version 2023.4.0. Section 5.5: Encodings of Note Plaintexts and Memo Fields
    - + @@ -796,7 +818,7 @@

    The

    2829 Zcash Protocol Specification, Version 2023.4.0. Section 7.5: Action Description Encoding and Consensus
    - + @@ -804,7 +826,7 @@

    The

    2930 User-Defined Assets and Wrapped Assets
    - + @@ -812,7 +834,7 @@

    The

    3031 Comment on Generalized Value Commitments
    - + diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index 3b313b876..89513e33c 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -26,7 +26,7 @@

    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.

    +

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

    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. @@ -43,10 +43,10 @@

    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.

    +

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

    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.

    @@ -73,7 +73,7 @@

    Specification: Issuance Keys and Issuance Authorization Signature Scheme

    -

    The Orchard-ZSA Protocol adds the following keys to the key components 18 19:

    +

    The Orchard-ZSA Protocol adds the following keys to the key components 19 20:

    1. The issuance authorizing key, denoted as \(\mathsf{isk}\!\) @@ -90,7 +90,7 @@

      Issuance Authorization Signature Scheme

      We instantiate the issuance authorization signature scheme \(\mathsf{IssueAuthSig}\) - as a BIP-340 Schnorr signature over the secp256k1 curve. The signing and validation algorithms, signature encoding, and public key encoding MUST follow BIP 340 16.

      + as a BIP-340 Schnorr signature over the secp256k1 curve. The signing and validation algorithms, signature encoding, and public key encoding MUST follow BIP 340 17.

      Batch verification MAY be used. Precomputation MAY be used if and only if it produces equivalent results; for example, for a given verification key \(pk\) and @@ -120,7 +120,7 @@ \(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.

      + denotes the type of byte sequences of arbitrary length, as defined in the Zcash protocol specification 18.

      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

      @@ -184,7 +184,7 @@

      where the \(\textit{PubKey}\) - algorithm is defined in BIP 340 16. Note that the byte representation of + algorithm is defined in BIP 340 17. Note that the byte representation of \(\mathsf{ik}\) is in big-endian order as defined in BIP 340.

      It is possible for the @@ -222,7 +222,7 @@ \(\mathsf{Sign}\) algorithm is defined in BIP 340 and \(a\) - denotes the auxiliary data used in BIP 340 16. Note that + denotes the auxiliary data used in BIP 340 17. Note that \(\mathsf{IssueAuthSig}.\!\mathsf{Sign}\) could return \(\bot\) @@ -246,7 +246,7 @@

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

      + algorithm is defined in BIP 340 17.

    Specification: Asset Identifier

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

    + is defined as in 21.

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

    @@ -312,17 +312,42 @@

    Specification: Global Issuance State

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

    +

    A map, + \(\mathsf{issued\_assets}\!\) + , from the Asset Base, + \(\mathsf{AssetBase}\) + , to a tuple + \((\mathsf{balance}, \mathsf{final})\!\) + , for every Asset that has been issued up until the block boundary. For each Asset:

      -
    • - \(\mathsf{previously\_finalized}\!\) - , a set of - \(\mathsf{AssetId}\) - that have been finalized (i.e.: the +
    • The amount of the Asset in circulation, computed as the amount of the Asset that has been issued less the amount of the Asset that has been burnt, is stored in + \(\mathsf{balance}\!\) + .
      • +
    • The boolean + \(\mathsf{final}\) + stores the finalization status of the Asset (i.e.: whether the \(\mathsf{finalize}\) flag has been set to \(1\) - in some issuance transaction preceding the block boundary).
      • + in some issuance transaction for the Asset preceding the block boundary). The value of + \(\mathsf{final}\) + for any Asset cannot be changed from + \(1\) + to + \(0\) + .
    +

    We use the notation + \(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{balance}\) + and + \(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{final}\) + to access, respectively, the balance and finalization status of the Asset stored in the global state.

    +

    Rationale for Global Issuance State

    +

    It is necessary to ensure that the balance of any issued Custom Asset never becomes negative within a shielded pool, along the lines of ZIP 209 8. However, unlike for the shielded ZEC pools, there is no individual transaction field that directly corresponds to both the issued and burnt amounts for a given Asset. Therefore, we require that all nodes maintain a record of the current amount in circulation for every issued Custom Asset, and update this record at the block boundary based on the issuance and burn transactions within the block. This allows for efficient detection of balance violations for any Asset, in which scenario we specify a consensus rule to reject the block.

    +

    Nodes also need to ensure the rejection of blocks in which issuance of Custom Assets that have been previously finalized. The + \(\mathsf{issued\_assets}\) + map allows nodes to store whether or not a given Asset has been finalized.

    +

    Specification: Issuance Action, Issuance Bundle and Issuance Protocol

    Issuance Action Description

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

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

    +

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

    3132 Modifications to the Orchard circuit for the ZSA Protocol
    @@ -551,11 +576,9 @@ 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 + \(\mathsf{issued\_assets(AssetBase).final} \neq 1\) + in the global state.
  • check that every note in the IssueAction contains the same \(\mathsf{AssetBase}\) and is properly constructed as @@ -564,19 +587,28 @@

    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.
      • +
    • 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 11.
        • +
      • Add + \(\mathsf{cm}\) + to the Merkle tree of note commitments.
        • +
      • Increase the value of + \(\mathsf{issued\_assets(AssetBase).balance}\) + by the value of the note, + \(\mathsf{v}\) + .
        • +
      +
    • If \(\mathsf{finalize} = 1\!\) - , add - \(\mathsf{AssetDigest}\) - to the - \(\mathsf{previously\_finalized}\) - set immediately after the block in which this transaction occurs.
      • + , set + \(\mathsf{issued\_assets(AssetBase).final}\) + to + \(1\) + in the global state immediately after the block in which this transaction occurs.
    • (Replay Protection) If issue bundle is present, the fees MUST be greater than zero.
    @@ -598,8 +630,8 @@
  • 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.
    • + \(\mathsf{issued\_assets}\) + map 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

    @@ -607,7 +639,7 @@
    • 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, + boolean and the burning mechanism defined in 10, issuers can control the supply production of any Asset associated to their issuer keys. For example,
      • by setting \(\mathsf{finalize} = 1\) @@ -643,7 +675,7 @@

    TxId Digest - Issuance

    -

    This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the Orchard-ZSA protocol can be found in ZIP 226 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.

    +

    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 12. As in ZIP 244 13, 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
@@ -679,7 +711,7 @@
                         
    In case the transaction has no Issue Notes, ''issue_notes_digest'' is:
    
                         
    BLAKE2b-256("ZTxIdIAcNoteHash", [])
    
                         
    T.5a.i.1: recipient 
    
-                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 21.
    
+                            
    This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 22.
    
                         
    
                         
    T.5a.i.2: value 
    
                             
    Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
    
@@ -713,7 +745,7 @@

    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 per-input transaction digest algorithm to generate the signature digest in ZIP 244 14 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
@@ -728,14 +760,14 @@
 S.3: sapling_digest         (32-byte hash output)
 S.4: orchard_digest         (32-byte hash output)
 S.5: issuance_digest        (32-byte hash output)  [ADDED FOR ZSA]
    -

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

    +

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

    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:

    +

    The transaction digest algorithm defined in ZIP 244 15 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
@@ -776,7 +808,7 @@

    Bridging Assets

    -

    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 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.

    +

    For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 10. 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

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

    Fee Structures

    -

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

    +

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

    Test Vectors

    @@ -864,10 +896,18 @@
    - +
    + + + +
    8ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances
    + + + + @@ -875,7 +915,7 @@
    9 ZIP 224: Orchard
    - + @@ -883,7 +923,7 @@
    910 ZIP 226: Transfer and Burn of Zcash Shielded Assets
    - + @@ -891,7 +931,7 @@
    1011 ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment
    - + @@ -899,7 +939,7 @@
    1112 ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest
    - + @@ -907,7 +947,7 @@
    1213 ZIP 244: Transaction Identifier Non-Malleability
    - + @@ -915,7 +955,7 @@
    1314 ZIP 244: Transaction Identifier Non-Malleability: Signature Digest
    - + @@ -923,7 +963,7 @@
    1415 ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment
    - + @@ -931,7 +971,7 @@
    1516 ZIP 317: Proportional Transfer Fee Mechanism
    - + @@ -939,7 +979,7 @@
    1617 BIP 340: Schnorr Signatures for secp256k1
    - + @@ -947,7 +987,7 @@
    1718 Zcash Protocol Specification, Version 2023.4.0. Section 2: Notation
    - + @@ -955,7 +995,7 @@
    1819 Zcash Protocol Specification, Version 2023.4.0. Section 3.1: Payment Addresses and Keys
    - + @@ -963,7 +1003,7 @@
    1920 Zcash Protocol Specification, Version 2023.4.0. Section 4.2.3: Orchard Key Components
    - + @@ -971,7 +1011,7 @@
    2021 Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.8: Group Hash into Pallas and Vesta
    - + @@ -979,7 +1019,7 @@
    2122 Zcash Protocol Specification, Version 2023.4.0. Section 5.6.4.2: Orchard Raw Payment Addresses
    - + diff --git a/zips/zip-0226.rst b/zips/zip-0226.rst index a498db3cb..34341c0bd 100644 --- a/zips/zip-0226.rst +++ b/zips/zip-0226.rst @@ -182,9 +182,12 @@ 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}\!`. +1. Check that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}, \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}\!`. That is, ZEC or TAZ is not allowed to be burnt by this mechanism. +2. Check that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}, \mathsf{v} \neq 0\!`. +3. Check that there is no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}` has at most one entry in :math:`\mathsf{assetBurn}\!`. +4. Check that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}\!`, :math:`\mathsf{v} \leq \mathsf{issued\_assets(AssetBase).balance}\!`, where the map :math:`\mathsf{issued\_assets}` is defined in ZIP 227 [#zip-0227-specification-global-issuance-state]_. That is, it is not possible to burn more of an Asset than is currently in circulation. + +If all these checks pass, then for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}\!`, reduce the value of :math:`\mathsf{issued\_assets(AssetBase).balance}` in the global state by :math:`\mathsf{v}\!`. **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. @@ -491,6 +494,7 @@ References .. [#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-specification-global-issuance-state] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Global Issuance State `_ .. [#zip-0227-assetidentifier] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier `_ .. [#zip-0227-txiddigest] `ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance `_ .. [#zip-0227-sigdigest] `ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest `_ diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index 7aed636a5..3da87f248 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -221,8 +221,24 @@ 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). +A map, :math:`\mathsf{issued\_assets}\!`, from the Asset Base, :math:`\mathsf{AssetBase}`, to a tuple :math:`(\mathsf{balance}, \mathsf{final})\!`, for every Asset that has been issued up until the block boundary. For each Asset: +- The amount of the Asset in circulation, computed as the amount of the Asset that has been issued less the amount of the Asset that has been burnt, is stored in :math:`\mathsf{balance}\!`. +- The boolean :math:`\mathsf{final}` stores the finalization status of the Asset (i.e.: whether the :math:`\mathsf{finalize}` flag has been set to :math:`1` in some issuance transaction for the Asset preceding the block boundary). The value of :math:`\mathsf{final}` for any Asset cannot be changed from :math:`1` to :math:`0`. + + +We use the notation :math:`\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{balance}` and :math:`\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{final}` to access, respectively, the balance and finalization status of the Asset stored in the global state. + +Rationale for Global Issuance State +----------------------------------- + +It is necessary to ensure that the balance of any issued Custom Asset never becomes negative within a shielded pool, along the lines of ZIP 209 [#zip-0209]_. +However, unlike for the shielded ZEC pools, there is no individual transaction field that directly corresponds to both the issued and burnt amounts for a given Asset. +Therefore, we require that all nodes maintain a record of the current amount in circulation for every issued Custom Asset, and update this record at the block boundary based on the issuance and burn transactions within the block. +This allows for efficient detection of balance violations for any Asset, in which scenario we specify a consensus rule to reject the block. + +Nodes also need to ensure the rejection of blocks in which issuance of Custom Assets that have been previously finalized. +The :math:`\mathsf{issued\_assets}` map allows nodes to store whether or not a given Asset has been finalized. Specification: Issuance Action, Issuance Bundle and Issuance Protocol ===================================================================== @@ -328,14 +344,19 @@ For each ``IssueAction`` in ``IssueBundle``: - 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 :math:`\mathsf{issued\_assets(AssetBase).final} \neq 1` 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. +- 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]_. + - Add :math:`\mathsf{cm}` to the Merkle tree of note commitments. + - Increase the value of :math:`\mathsf{issued\_assets(AssetBase).balance}` by the value of the note, :math:`\mathsf{v}`. + +- If :math:`\mathsf{finalize} = 1\!`, set :math:`\mathsf{issued\_assets(AssetBase).final}` to :math:`1` in the global state immediately after the block in which this transaction occurs. + - (Replay Protection) If issue bundle is present, the fees MUST be greater than zero. @@ -353,7 +374,7 @@ The following is a list of rationale for different decisions made in the proposa - bridging information for Wrapped Assets (chain of origin, issuer name, etc) - information to be committed by the issuer, though not enforceable by the protocol. -- We require a check whether the :math:`\mathsf{finalize}` flag only has been set in a previous block rather than a previous transaction in the same block. In other words, we only update the :math:`\mathsf{previously\_finalized}`` set at the block boundary. This is in keeping with the current property which allows for a miner to reorder transactions in a block without changing the meaning, which we aim to preserve. +- We require 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{issued\_assets}` map 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 @@ -606,6 +627,7 @@ References .. [#zip-0032-key-path-levels] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Key path levels `_ .. [#zip-0032-orchard-key-path] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard key path `_ .. [#zip-0200] `ZIP 200: Network Upgrade Mechanism `_ +.. [#zip-0209] `ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances `_ .. [#zip-0224] `ZIP 224: Orchard `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ From 4003a8faf4651f7172c6236544a3f7205fae48d6 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 20 Aug 2024 14:35:22 +0530 Subject: [PATCH 07/17] Adding symbolic link from the rendered folder to the docs folder (#60) This adds the symbolic link above in order to allow the [qed-it.github.io/zips](qed-it.github.io/zips) website to work correctly post the upstream repository restructure. --- docs | 1 + 1 file changed, 1 insertion(+) create mode 120000 docs diff --git a/docs b/docs new file mode 120000 index 000000000..f91481461 --- /dev/null +++ b/docs @@ -0,0 +1 @@ +rendered \ No newline at end of file From 32516a46929e56ed1d9eb0021dbd69a96cd9df87 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Wed, 25 Sep 2024 14:54:48 +0530 Subject: [PATCH 08/17] Improved description of the burn mechanism, and rationale for asset description string size (#61) This rewrites the burn mechanism description in ZIP 226 in order to remove some ambiguously defined terms, and improve the clarity of the specification. It also adds the rationale for the choice of 512 bytes for the maximum length of the asset description string in ZIP 227, which resolves #843 (along with the additions in the already merged #59) --- rendered/zip-0226.html | 26 +++++++++++++------------- rendered/zip-0227.html | 3 +++ zips/zip-0226.rst | 22 ++++++++++++---------- zips/zip-0227.rst | 1 + 4 files changed, 29 insertions(+), 23 deletions(-) diff --git a/rendered/zip-0226.html b/rendered/zip-0226.html index 5fdacb6ce..ff107ee92 100644 --- a/rendered/zip-0226.html +++ b/rendered/zip-0226.html @@ -195,23 +195,23 @@

    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 +

    The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Custom Asset to be "destroyed" by the holder. 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. 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 a Custom Asset has been destroyed. Note that the OrchardZSA Protocol does not allow for the burning of ZEC (or TAZ).

    +

    In the Orchard-ZSA Transaction Structure, there is now an \(\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 + set. For every Custom Asset (represented by its + \(\mathsf{AssetBase}\!\) + ) that is burnt in the transaction, the sender adds to + \(\mathsf{assetBurn}\) + the tuple + \((\mathsf{AssetBase}, \mathsf{v})\) + , where + \(\mathsf{v}\) + is the amount of the Custom Asset the sender wants to burn. We denote by \(L\) the cardinality of the \(\mathsf{assetBurn}\) - set.

    + set in a transaction.

    +

    As described in Value Balance Verification, this provides the information for the validator of the transaction to compute the value commitment with the corresponding Asset Base. This ensures that the values are all balanced out on a per-Asset basis in the transaction.

    Additional Consensus Rules

    1. Check that for every diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index 89513e33c..7b82fb909 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -627,6 +627,9 @@
    2. information to be committed by the issuer, though not enforceable by the protocol.
      3. +
    3. We limit the size of the + \(\mathsf{asset\_desc}\) + string to 512 bytes as it is a reasonable size to store metadata about the Asset, for example in JSON format.
    4. 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 diff --git a/zips/zip-0226.rst b/zips/zip-0226.rst index 34341c0bd..bc59c942f 100644 --- a/zips/zip-0226.rst +++ b/zips/zip-0226.rst @@ -168,16 +168,18 @@ The use of different value base points for different Assets enables the final ba 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. +The burn mechanism is a transparent extension to the transfer protocol that enables a specific amount of any Custom Asset to be "destroyed" by the holder. +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. +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 a Custom Asset has been destroyed. +Note that the OrchardZSA Protocol does not allow for the burning of ZEC (or TAZ). + +In the `Orchard-ZSA Transaction Structure`_, there is now an :math:`\mathsf{assetBurn}` set. +For every Custom Asset (represented by its :math:`\mathsf{AssetBase}\!`) that is burnt in the transaction, the sender adds to :math:`\mathsf{assetBurn}` the tuple :math:`(\mathsf{AssetBase}, \mathsf{v})`, where :math:`\mathsf{v}` is the amount of the Custom Asset the sender wants to burn. +We denote by :math:`L` the cardinality of the :math:`\mathsf{assetBurn}` set in a transaction. + +As described in `Value Balance Verification`_, this provides the information for the validator of the transaction to compute the value commitment with the corresponding Asset Base. +This ensures that the values are all balanced out on a per-Asset basis in the transaction. Additional Consensus Rules `````````````````````````` diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index 3da87f248..175415391 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -374,6 +374,7 @@ The following is a list of rationale for different decisions made in the proposa - bridging information for Wrapped Assets (chain of origin, issuer name, etc) - information to be committed by the issuer, though not enforceable by the protocol. +- We limit the size of the :math:`\mathsf{asset\_desc}` string to 512 bytes as it is a reasonable size to store metadata about the Asset, for example in JSON format. - 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{issued\_assets}` map 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. From f5a6dd7f400cb5479f6a9d00e0fa72fdaf33e627 Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Wed, 25 Sep 2024 15:03:24 +0530 Subject: [PATCH 09/17] commenting out CI token lines to allow CI to build --- .github/workflows/render.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/render.yml b/.github/workflows/render.yml index 11fbb8ccc..817429aaa 100644 --- a/.github/workflows/render.yml +++ b/.github/workflows/render.yml @@ -13,8 +13,8 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4.1.7 - with: - token: ${{ secrets.CI_TOKEN }} + # with: + # token: ${{ secrets.CI_TOKEN }} - name: Compile ZIPs and Zcash Protocol Specification uses: ./.github/actions/render From 0da1b348ea5991cf0ad9d0486207dd84aba2c095 Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Wed, 25 Sep 2024 15:03:24 +0530 Subject: [PATCH 10/17] commenting out CI token lines to allow CI to build --- .github/workflows/render.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/render.yml b/.github/workflows/render.yml index 11fbb8ccc..817429aaa 100644 --- a/.github/workflows/render.yml +++ b/.github/workflows/render.yml @@ -13,8 +13,8 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4.1.7 - with: - token: ${{ secrets.CI_TOKEN }} + # with: + # token: ${{ secrets.CI_TOKEN }} - name: Compile ZIPs and Zcash Protocol Specification uses: ./.github/actions/render From d517f5d8a7058b116034a4e034058483ea5a5133 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Sun, 29 Sep 2024 16:00:48 +0530 Subject: [PATCH 11/17] Updating references to protocol spec, and fixing some old links (#70) This updates the protocol spec references from 2023.4.0 [NU5] to 2024.5.1 [NU6], along with some minor section changes and renumbering. It also fixes some old links in favour of updated ones. This resolves https://github.com/zcash/zips/issues/751 for the present. --- rendered/zip-0226.html | 32 ++++++++++++++++---------------- rendered/zip-0227.html | 14 +++++++------- rendered/zip-0230.html | 8 ++++---- zips/zip-0226.rst | 32 ++++++++++++++++---------------- zips/zip-0227.rst | 14 +++++++------- zips/zip-0230.rst | 8 ++++---- 6 files changed, 54 insertions(+), 54 deletions(-) diff --git a/rendered/zip-0226.html b/rendered/zip-0226.html index ff107ee92..7482eed04 100644 --- a/rendered/zip-0226.html +++ b/rendered/zip-0226.html @@ -667,7 +667,7 @@

      The

    - +
    2223 Zcash Protocol Specification, Version 2023.4.0. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
    11ZIP 230: Version 6 Transaction FormatZIP 230: Version 6 Transaction Format
    @@ -699,7 +699,7 @@

    The 15 - Zcash Protocol Specification, Version 2023.4.0. Section 3.2: Notes + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.2: Notes @@ -707,7 +707,7 @@

    The 16 - Zcash Protocol Specification, Version 2023.4.0. Section 3.7: Action Transfers and their Descriptions + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.7: Action Transfers and their Descriptions @@ -715,7 +715,7 @@

    The 17 - Zcash Protocol Specification, Version 2023.4.0. Section 4.1.8: Commitment + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.1.8: Commitment @@ -723,7 +723,7 @@

    The 18 - Zcash Protocol Specification, Version 2023.4.0. Section 4.8.3: Dummy Notes (Orchard) + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.8.3: Dummy Notes (Orchard) @@ -731,7 +731,7 @@

    The 19 - Zcash Protocol Specification, Version 2023.4.0. Section 4.14: Balance and Binding Signature (Orchard) + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.14: Balance and Binding Signature (Orchard) @@ -739,7 +739,7 @@

    The 20 - Zcash Protocol Specification, Version 2023.4.0. Section 4.16: Note Commitments and Nullifiers + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.16: Computing ρ values and Nullifiers @@ -747,7 +747,7 @@

    The 21 - Zcash Protocol Specification, Version 2023.4.0. Section 4.17.4: Action Statement (Orchard) + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.18.4: Action Statement (Orchard) @@ -755,7 +755,7 @@

    The 22 - Zcash Protocol Specification, Version 2023.4.0. Section 5.1: Integers, Bit Sequences, and Endianness + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.1: Integers, Bit Sequences, and Endianness @@ -763,7 +763,7 @@

    The 23 - Zcash Protocol Specification, Version 2023.4.0. Section 5.3: Constants + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.3: Constants @@ -771,7 +771,7 @@

    The 24 - Zcash Protocol Specification, Version 2023.4.0. Section 5.4.1.9: Sinsemilla hash function + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.1.9: Sinsemilla hash function @@ -779,7 +779,7 @@

    The 25 - Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard) + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard) @@ -787,7 +787,7 @@

    The 26 - Zcash Protocol Specification, Version 2023.4.0. Section 5.4.8.4: Sinsemilla commitments + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.8.4: Sinsemilla commitments @@ -795,7 +795,7 @@

    The 27 - Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.6: Pallas and Vesta + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.9.6: Pallas and Vesta @@ -803,7 +803,7 @@

    The 28 - Zcash Protocol Specification, Version 2023.4.0. Section 5.5: Encodings of Note Plaintexts and Memo Fields + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.5: Encodings of Note Plaintexts and Memo Fields @@ -811,7 +811,7 @@

    The 29 - Zcash Protocol Specification, Version 2023.4.0. Section 7.5: Action Description Encoding and Consensus + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 7.5: Action Description Encoding and Consensus diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index e5650ee1f..31b0cb569 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -975,7 +975,7 @@ 17 - BIP 340: Schnorr Signatures for secp256k1 + BIP 340: Schnorr Signatures for secp256k1 @@ -983,7 +983,7 @@ 18 - Zcash Protocol Specification, Version 2023.4.0. Section 2: Notation + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 2: Notation @@ -991,7 +991,7 @@ 19 - Zcash Protocol Specification, Version 2023.4.0. Section 3.1: Payment Addresses and Keys + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.1: Payment Addresses and Keys @@ -999,7 +999,7 @@ 20 - Zcash Protocol Specification, Version 2023.4.0. Section 4.2.3: Orchard Key Components + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.2.3: Orchard Key Components @@ -1007,7 +1007,7 @@ 21 - Zcash Protocol Specification, Version 2023.4.0. Section 5.4.9.8: Group Hash into Pallas and Vesta + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.9.8: Group Hash into Pallas and Vesta @@ -1015,7 +1015,7 @@ 22 - Zcash Protocol Specification, Version 2023.4.0. Section 5.6.4.2: Orchard Raw Payment Addresses + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.6.4.2: Orchard Raw Payment Addresses @@ -1023,7 +1023,7 @@ 23 - Zcash Protocol Specification, Version 2023.4.0. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 7.1: Transaction Encoding and Consensus diff --git a/rendered/zip-0230.html b/rendered/zip-0230.html index 1857d1e9a..7ad57529f 100644 --- a/rendered/zip-0230.html +++ b/rendered/zip-0230.html @@ -633,7 +633,7 @@ 2 - Zcash Protocol Specification, Version 2023.4.0 or later [NU5 proposal] + Zcash Protocol Specification, Version 2024.5.1 or later [NU6] @@ -641,7 +641,7 @@ 3 - Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.4: Spend Descriptions + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.4: Spend Descriptions @@ -649,7 +649,7 @@ 4 - Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.5: Output Descriptions + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.5: Output Descriptions @@ -657,7 +657,7 @@ 5 - Zcash Protocol Specification, Version 2023.4.0 [NU5 proposal]. Section 4.6: Action Descriptions + Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.6: Action Descriptions diff --git a/zips/zip-0226.rst b/zips/zip-0226.rst index bc59c942f..5eb080069 100644 --- a/zips/zip-0226.rst +++ b/zips/zip-0226.rst @@ -501,25 +501,25 @@ References .. [#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-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 `_ +.. [#protocol-notes] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.2: Notes `_ +.. [#protocol-actions] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.7: Action Transfers and their Descriptions `_ +.. [#protocol-abstractcommit] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.1.8: Commitment `_ +.. [#protocol-orcharddummynotes] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.8.3: Dummy Notes (Orchard) `_ +.. [#protocol-orchardbalance] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.14: Balance and Binding Signature (Orchard) `_ +.. [#protocol-commitmentsandnullifiers] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.16: Computing ρ values and Nullifiers `_ +.. [#protocol-actionstatement] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.18.4: Action Statement (Orchard) `_ +.. [#protocol-endian] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.1: Integers, Bit Sequences, and Endianness `_ +.. [#protocol-constants] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.3: Constants `_ +.. [#protocol-concretesinsemillahash] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.1.9: Sinsemilla hash function `_ +.. [#protocol-concretehomomorphiccommit] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.8.3: Homomorphic Pedersen commitments (Sapling and Orchard) `_ +.. [#protocol-concretesinsemillacommit] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.8.4: Sinsemilla commitments `_ +.. [#protocol-pallasandvesta] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.9.6: Pallas and Vesta `_ +.. [#protocol-notept] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.5: Encodings of Note Plaintexts and Memo Fields `_ +.. [#protocol-actionencodingandconsensus] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. 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/zips/zip-0227.rst b/zips/zip-0227.rst index ba15f2035..5f3b1f382 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -638,10 +638,10 @@ References .. [#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) `_ +.. [#bip-0340] `BIP 340: Schnorr Signatures for secp256k1 `_ +.. [#protocol-notation] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 2: Notation `_ +.. [#protocol-addressesandkeys] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.1: Payment Addresses and Keys `_ +.. [#protocol-orchardkeycomponents] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.2.3: Orchard Key Components `_ +.. [#protocol-concretegrouphashpallasandvesta] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.4.9.8: Group Hash into Pallas and Vesta `_ +.. [#protocol-orchardpaymentaddrencoding] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 5.6.4.2: Orchard Raw Payment Addresses `_ +.. [#protocol-txnencoding] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 7.1: Transaction Encoding and Consensus `_ diff --git a/zips/zip-0230.rst b/zips/zip-0230.rst index 69dd034d2..7052c38e6 100644 --- a/zips/zip-0230.rst +++ b/zips/zip-0230.rst @@ -368,10 +368,10 @@ 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 `_ +.. [#protocol] `Zcash Protocol Specification, Version 2024.5.1 or later [NU6] `_ +.. [#protocol-spenddesc] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.4: Spend Descriptions `_ +.. [#protocol-outputdesc] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.5: Output Descriptions `_ +.. [#protocol-actiondesc] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. 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 `_ From 993e6dc9fc33825c465b810e3847eb118ea09d52 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 8 Oct 2024 11:13:46 +0530 Subject: [PATCH 12/17] [ZSA] Issuance Key Derivation update to match with ZIP 32 (#72) This makes the changes to align with the change in notation for ZIP 32 done in #908. --- rendered/zip-0227.html | 34 +++++++++++++++++++++++++--------- zips/zip-0227.rst | 19 +++++++++++++------ 2 files changed, 38 insertions(+), 15 deletions(-) diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index 31b0cb569..05a765567 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -125,15 +125,31 @@

    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.

    +

    The issuance authorizing key is generated using the Hardened-only key derivation process defined in ZIP 32 3. For the + \(\mathsf{Issuance}\) + context, we define the following constants:

    +
      +
    • + \(\mathsf{Issuance.\!MKGDomain} := \texttt{"ZIP32ZSAIssue_V1"}\) +
      • +
    • + \(\mathsf{Issuance.\!CKDDomain} := \mathtt{0x81}\!\) +
      • +

    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)\!\) + \(m_{\mathsf{Issuance}} := \mathsf{MKGh}^{\mathsf{Issuance}}(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 hardened-only child key derivation as defined in ZIP 32 4 for the issuance authorizing key.

    +

    + \(\mathsf{CDKsk}((\mathsf{sk}_{par},\mathsf{c}_{par}), i) \rightarrow (\mathsf{sk}_{i}, \mathsf{c}_{i})\) +

    +
      +
    • Return + \(\mathsf{CKDh}^{\mathsf{Issuance}}((\mathsf{sk}_{par},\mathsf{c}_{par}), i)\!\) +
      • +

    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:

    @@ -859,19 +875,19 @@ - +
    - +
    3ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generationZIP 32: Shielded Hierarchical Deterministic Wallets - Specification: Hardened-only key derivation
    - +
    - +
    4ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard child key derivationZIP 32: Shielded Hierarchical Deterministic Wallets - Hardened-only child key derivation
    diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index 5f3b1f382..e27784e29 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -123,13 +123,20 @@ 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. +The issuance authorizing key is generated using the Hardened-only key derivation process defined in ZIP 32 [#zip-0032-hardened-only-key-derivation]_. +For the :math:`\mathsf{Issuance}` context, we define the following constants: + +- :math:`\mathsf{Issuance.\!MKGDomain} := \texttt{"ZIP32ZSAIssue_V1"}` +- :math:`\mathsf{Issuance.\!CKDDomain} := \mathtt{0x81}\!` 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)\!`. +We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \mathsf{MKGh}^{\mathsf{Issuance}}(S)\!`. + +We use hardened-only child key derivation as defined in ZIP 32 [#zip-0032-hardened-only-child-key-derivation]_ for the issuance authorizing key. + +:math:`\mathsf{CDKsk}((\mathsf{sk}_{par},\mathsf{c}_{par}), i) \rightarrow (\mathsf{sk}_{i}, \mathsf{c}_{i})` -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. +- Return :math:`\mathsf{CKDh}^{\mathsf{Issuance}}((\mathsf{sk}_{par},\mathsf{c}_{par}), i)\!` 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: @@ -624,8 +631,8 @@ 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-hardened-only-key-derivation] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Specification: Hardened-only key derivation `_ +.. [#zip-0032-hardened-only-child-key-derivation] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Hardened-only 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 `_ From 20ef938ec2f3cd6cb83719217b66196fa46c95e6 Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Thu, 31 Oct 2024 15:03:54 +0530 Subject: [PATCH 13/17] Applying suggestions from ZIP review Co-authored-by: Daira-Emma Hopwood --- zips/zip-0227.rst | 4 ++-- zips/zip-0230.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index e27784e29..9dac2581d 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -126,7 +126,7 @@ Issuance authorizing key generation for hierarchical deterministic wallets The issuance authorizing key is generated using the Hardened-only key derivation process defined in ZIP 32 [#zip-0032-hardened-only-key-derivation]_. For the :math:`\mathsf{Issuance}` context, we define the following constants: -- :math:`\mathsf{Issuance.\!MKGDomain} := \texttt{"ZIP32ZSAIssue_V1"}` +- :math:`\mathsf{Issuance.\!MKGDomain} := \texttt{"ZcashSA_Issue_V1"}` - :math:`\mathsf{Issuance.\!CKDDomain} := \mathtt{0x81}\!` Let :math:`S` be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. @@ -134,7 +134,7 @@ We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \math We use hardened-only child key derivation as defined in ZIP 32 [#zip-0032-hardened-only-child-key-derivation]_ for the issuance authorizing key. -:math:`\mathsf{CDKsk}((\mathsf{sk}_{par},\mathsf{c}_{par}), i) \rightarrow (\mathsf{sk}_{i}, \mathsf{c}_{i})` +:math:`\mathsf{CKDsk}((\mathsf{sk}_{par},\mathsf{c}_{par}), i) \rightarrow (\mathsf{sk}_{i}, \mathsf{c}_{i})` - Return :math:`\mathsf{CKDh}^{\mathsf{Issuance}}((\mathsf{sk}_{par},\mathsf{c}_{par}), i)\!` diff --git a/zips/zip-0230.rst b/zips/zip-0230.rst index 7052c38e6..77eac1422 100644 --- a/zips/zip-0230.rst +++ b/zips/zip-0230.rst @@ -351,10 +351,10 @@ An issuance note, ``IssueNote`` contains the following fields: | | | |:math:`\mathsf{AssetBase^{Orchard}}\!`, as defined in 'ZIP 227'. | +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ |``32`` |``rho`` |``byte[32]`` |This is defined and encoded in the same manner as for Orchard | -| | | |notes in protocol §3.2 'Notes'. | +| | | |notes in protocol §3.2.1 'Note Plaintexts and Memo Fields'. | +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ |``32`` |``rseed`` |``byte[32]`` |The ``rseed`` field of the note, encoded as for Orchard notes in | -| | | |protocol §3.2 'Notes'. | +| | | |protocol §3.2.1 'Note Plaintexts and Memo Fields'. | +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ From 61d4e20301ca4d23e0608f26271731679e18a45f Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Tue, 5 Nov 2024 17:52:20 +0530 Subject: [PATCH 14/17] updating HTML files based on ZIP review --- rendered/zip-0230.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rendered/zip-0230.html b/rendered/zip-0230.html index 7ad57529f..3b2eeec36 100644 --- a/rendered/zip-0230.html +++ b/rendered/zip-0230.html @@ -605,13 +605,13 @@ 32 rho byte[32] - This is defined and encoded in the same manner as for Orchard notes in protocol §3.2 'Notes'. + This is defined and encoded in the same manner as for Orchard notes in protocol §3.2.1 'Note Plaintexts and Memo Fields'. 32 rseed byte[32] - The rseed field of the note, encoded as for Orchard notes in protocol §3.2 'Notes'. + The rseed field of the note, encoded as for Orchard notes in protocol §3.2.1 'Note Plaintexts and Memo Fields'. From edc4c98d6462a8f051a627b645fc7c1bc079529c Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Tue, 5 Nov 2024 18:01:47 +0530 Subject: [PATCH 15/17] further html change --- rendered/zip-0227.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index 05a765567..09a3cd179 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -130,7 +130,7 @@ context, we define the following constants:

    • - \(\mathsf{Issuance.\!MKGDomain} := \texttt{"ZIP32ZSAIssue_V1"}\) + \(\mathsf{Issuance.\!MKGDomain} := \texttt{"ZcashSA_Issue_V1"}\)
    • \(\mathsf{Issuance.\!CKDDomain} := \mathtt{0x81}\!\) @@ -143,7 +143,7 @@ .

      We use hardened-only child key derivation as defined in ZIP 32 4 for the issuance authorizing key.

      - \(\mathsf{CDKsk}((\mathsf{sk}_{par},\mathsf{c}_{par}), i) \rightarrow (\mathsf{sk}_{i}, \mathsf{c}_{i})\) + \(\mathsf{CKDsk}((\mathsf{sk}_{par},\mathsf{c}_{par}), i) \rightarrow (\mathsf{sk}_{i}, \mathsf{c}_{i})\)

      • Return From 2e8876c96b7afa5dc98d337170806fb9fb5fc68a Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 5 Nov 2024 19:13:14 +0530 Subject: [PATCH 16/17] [ZSA] Applying suggestions from ZIP Review (#75) This makes changes from the review made on #854. --- rendered/zip-0227.html | 7 +------ rendered/zip-0230.html | 10 +++++++++- zips/zip-0227.rst | 3 +-- zips/zip-0230.rst | 10 ++++++++-- 4 files changed, 19 insertions(+), 11 deletions(-) diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index 09a3cd179..1231e710a 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -624,7 +624,7 @@ \(\mathsf{issued\_assets(AssetBase).final}\) to \(1\) - in the global state immediately after the block in which this transaction occurs.
        • + in the global state.
      • (Replay Protection) If issue bundle is present, the fees MUST be greater than zero.
    @@ -646,11 +646,6 @@
  • We limit the size of the \(\mathsf{asset\_desc}\) string to 512 bytes as it is a reasonable size to store metadata about the Asset, for example in JSON format.
    • -
  • 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{issued\_assets}\) - map 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

    diff --git a/rendered/zip-0230.html b/rendered/zip-0230.html index 3b2eeec36..1ef67e07e 100644 --- a/rendered/zip-0230.html +++ b/rendered/zip-0230.html @@ -585,7 +585,15 @@ 43 recipient byte[43] - The raw encoding of an Orchard Raw Payment Address, as per protocol §5.6.4.2 ‘Orchard Raw Payment Addresses’. + The encoding of a recipient's diversified payment address, as + \(\mathsf{LEBS2OSP}_{88}(\mathsf{d})\| +\mathsf{LEBS2OSP}_{256}(\mathsf{repr}_{\mathbb{P}} +(\mathsf{pk}_\mathsf{d}))\!\) + , where + \(\mathsf{d}\) + is the diversifier and + \(\mathsf{pk_d}\) + is the diversified transmission key. Non Normative Note: This is the same as the encoding of an Orchard Raw Payment Address, as defined in the protocol specification §5.6.4.2 ‘Orchard Raw Payment Addresses’. 8 diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index 9dac2581d..4a981f2c8 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -362,7 +362,7 @@ If all of the above checks pass, do the following: - Add :math:`\mathsf{cm}` to the Merkle tree of note commitments. - Increase the value of :math:`\mathsf{issued\_assets(AssetBase).balance}` by the value of the note, :math:`\mathsf{v}`. -- If :math:`\mathsf{finalize} = 1\!`, set :math:`\mathsf{issued\_assets(AssetBase).final}` to :math:`1` in the global state immediately after the block in which this transaction occurs. +- If :math:`\mathsf{finalize} = 1\!`, set :math:`\mathsf{issued\_assets(AssetBase).final}` to :math:`1` in the global state. - (Replay Protection) If issue bundle is present, the fees MUST be greater than zero. @@ -382,7 +382,6 @@ The following is a list of rationale for different decisions made in the proposa - information to be committed by the issuer, though not enforceable by the protocol. - We limit the size of the :math:`\mathsf{asset\_desc}` string to 512 bytes as it is a reasonable size to store metadata about the Asset, for example in JSON format. -- 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{issued\_assets}` map 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 diff --git a/zips/zip-0230.rst b/zips/zip-0230.rst index 77eac1422..2bed2e300 100644 --- a/zips/zip-0230.rst +++ b/zips/zip-0230.rst @@ -342,8 +342,14 @@ An issuance note, ``IssueNote`` contains the following fields: +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=============================+==========================+======================================+====================================================================+ -|``43`` |``recipient`` |``byte[43]`` |The raw encoding of an Orchard Raw Payment Address, as | -| | | |per protocol §5.6.4.2 ‘Orchard Raw Payment Addresses’. | +|``43`` |``recipient`` |``byte[43]`` |The encoding of a recipient's diversified payment address, as | +| | | |:math:`\mathsf{LEBS2OSP}_{88}(\mathsf{d})\| | +| | | |\mathsf{LEBS2OSP}_{256}(\mathsf{repr}_{\mathbb{P}} | +| | | |(\mathsf{pk}_\mathsf{d}))\!`, where :math:`\mathsf{d}` is the | +| | | |diversifier and :math:`\mathsf{pk_d}` is the diversified | +| | | |transmission key. **Non Normative Note**: This is the same as the | +| | | |encoding of an Orchard Raw Payment Address, as defined in the | +| | | |protocol specification §5.6.4.2 ‘Orchard Raw Payment Addresses’. | +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ |``8`` |``value`` |``uint64`` |The amount being issued in this note. | +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ From aa0de9b1834033e21b74bae1d8ad8b48c41aff9b Mon Sep 17 00:00:00 2001 From: Vivek Arte <46618816+vivek-arte@users.noreply.github.com> Date: Tue, 5 Nov 2024 19:13:39 +0530 Subject: [PATCH 17/17] [ZSA] Adding fees details to ZIP 230 (#76) This is done in response to https://github.com/zcash/zips/pull/667#discussion_r1828285036 --- rendered/zip-0230.html | 140 ++++++++++++++++++++++++++++++++++++++--- zips/zip-0230.rst | 96 ++++++++++++++++++++++++++++ 2 files changed, 226 insertions(+), 10 deletions(-) diff --git a/rendered/zip-0230.html b/rendered/zip-0230.html index 1ef67e07e..6f12ff6a4 100644 --- a/rendered/zip-0230.html +++ b/rendered/zip-0230.html @@ -25,20 +25,33 @@ 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.

    +

    The terms "Zcash Shielded Asset", "ZSA" and "Asset" in this document are to be interpreted as described in ZIP 226 7.

    +

    The term "Issuance" and "Issuance Action" in this document are to be interpreted as described in ZIP 227 8.

    +

    We define the following additional terms:

    +
      +
    • Issuance Fee: This is the specific fixed fee that has to be paid to the network for every given issuance action.
      • +
    +

    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.

    +

    This ZIP also depends upon and defines modifications to the computation of the values TxId Digest, Signature Digest, and Authorizing Data Commitment defined by ZIP 244 9.

    +

    This ZIP additionally defines the fee mechanism associated with the Orchard Zcash Shielded Assets (OrchardZSA) protocol as described in ZIP 226 7 and ZIP 227 8. The fee mechanism is defined in terms of modifications to the Proportionak Transfer Fee Mechanism 10.

    Motivation

    The Orchard-ZSA protocol requires serialized data elements that are distinct from any previous Zcash transaction. Since ZIP 244 was activated in NU5, the v5 and later serialized transaction formats are not consensus-critical. Thus, this ZIP defines format that can easily accommodate future extensions, where elements or a given pool are kept separate.

    +

    The upgrade to the OrchardZSA protocol will also need to define a fee structure consistent with the objectives of ZIP 317 10. This involves adaptation for the transfer protocol 7, as well as additional considerations for the issuance protocol 8 such as fees for asset issuance. Specifically, the OrchardZSA Transfer and Burn mechanism should follow the same fee mechanism in order to not discriminate between transfer bundle types. When it comes to Issuance of ZSA, however, there should be a disincentive that will stop users from flooding the chain with useless asset identifiers. In the case of Issuance, the computational power needed to verify the bundle is not large. The transaction size, however, can be an issue as the number of output notes can be large. Furthermore, as defined in ZIP 227 8, there is an additional data structure in the global state that needs to be maintained as part of the consensus. This motivates further the addition of an Issuance-specific fee.

    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.

    +

    In addition to the requirements of ZIP 317 10, the fee mechanism for the OrchardZSA protocol should satisfy the following requirements:

    +
      +
    • The conventional fee should not leak private information used in constructing the transaction; that is, it should be computable from only the public data of the transaction.
      • +
    • Users should be discouraged from issuing new “garbage” custom Assets. The fee should reflect the cost of adding new data to the global state.
      • +

    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.

    @@ -306,7 +319,7 @@ 64 issueAuthSig byte[64] - The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme 7. + The signature of the transaction SIGHASH, signed by the issuer, validated as in Issuance Authorization Signature Scheme 8. @@ -371,7 +384,7 @@ -

    The encodings of each of these elements are defined in §7.3 ‘Spend Description Encoding and Consensus’ of the Zcash Protocol Specification 3.

    +

    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)

    @@ -418,7 +431,7 @@
    -

    The encodings of each of these elements are defined in §7.4 ‘Output Description Encoding and Consensus’ of the Zcash Protocol Specification 4.

    +

    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)

    @@ -477,7 +490,7 @@
    -

    The encodings of each of these elements are defined in §7.5 ‘Action Description Encoding and Consensus’ of the Zcash Protocol Specification 5.

    +

    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:

    @@ -507,7 +520,7 @@ -

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

    +

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

    Issuance Action Description (IssueAction)

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

    @@ -625,6 +638,89 @@
    +

    OrchardZSA Fee Calculation

    +

    In addition to the parameters defined in the Fee calculation section of ZIP 317 11, the OrchardZSA protocol upgrade defines the following additional parameters:

    + + + + + + + + + + + + + +
    ParameterValue
    + \(issuance\_fee\) + + \(100 \cdot marginal\_fee\) + per issuance action (as defined below)
    +

    Wallets implementing this specification SHOULD use a conventional fee, viz. + \(zsa\_conventional\_fee\) + , that is calculated in zatoshis. Additional definitions that are used in the formula for the calculation are in the table below:

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    InputUnitsDescription
    + \(nOrchardActions\) + numberthe number of OrchardZSA transfer actions (including ZEC actions)
    + \(nTotalOutputsZsaIssuance\) + numberthe total number of OrchardZSA issuance outputs (added across issuance actions)
    + \(nCreateActions\) + numberthe number of OrchardZSA issuance actions that issue a Custom Asset that is not present in the Global Issuance State
    +

    The other inputs to this formula are taken from transaction fields defined in the Zcash protocol specification 6 and the global state. They are defined in the Fee calculation section of ZIP 317 11. Note that + \(nOrchardActions\) + , that is used in the computation of + \(logical\_actions\) + , is redefined in the above table, and now combines the actions for native ZEC as well as OrchardZSA transfer actions for Custom Assets.

    +

    The formula for the computation of the + \(zsa\_logical\_actions\) + (with the updated computation of + \(logical\_actions\) + as described above) is:

    +
    \(zsa\_logical\_actions = logical\_actions \;+ nTotalOutputsZsaIssuance\)
    +

    The formula for the computation of the + \(zsa\_conventional\_fee\) + is:

    +
    \(\begin{array}{rcl} + zsa\_conventional\_fee &=& marginal\_fee \cdot \mathsf{max}(grace\_actions, zsa\_logical\_actions) \;+ \\ + & & issuance\_fee \cdot nCreateActions +\end{array}\)
    +

    It is not a consensus requirement that fees follow this formula; however, wallets SHOULD create transactions that pay this fee, in order to reduce information leakage, unless overridden by the user.

    +

    Rationale for OrchardZSA Fee calculation

    +

    The OrchardZSA fee calculation accounts for the additions to the Global Issuance State that are required for the OrchardZSA protocol. Every newly created Custom Asset adds a new row to the Global Issuance State. Subsequent issuance, finalization, or burn of existing Custom Assets only changes the values in the corresponding row.

    +

    This explains the need for a higher fee for the creation of entirely new Custom Assets, in order to disincentivize the creation of "junk" assets.

    +
    +

    OrchardZSA Fee Considerations

    +

    We choose to maintain the native ZEC Asset as the primary token for the Zcash blockchain, similar to how ETH is needed for ERC20 transactions to the benefit of the Ethereum ecosystem.

    +

    An alternative proposal for the OrchardZSA fee mechanism that was not adopted was to adopt a new type of fee, denominated in the custom Asset being issued or transferred. In the context of transparent transactions, such a fee allows miners to “tap into” the ZSA value of the transactions, rather than the ZEC value of transactions. However when transactions are shielded, any design that lifts value from the transaction would also leak information about it.

    +
    +

    Reference implementation

    TODO

    @@ -669,10 +765,18 @@ - +
    + + + +
    6Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus
    + + + + @@ -680,7 +784,7 @@
    7 ZIP 226: Transfer and Burn of Zcash Shielded Assets
    - + @@ -688,11 +792,27 @@
    78 ZIP 227: Issuance of Zcash Shielded Assets
    - +
    89 ZIP 244: Transaction Identifier Non-Malleability
    + + + + + + + +
    10ZIP 317: Proportional Transfer Fee Mechanism
    + + + + + + + +
    11ZIP 317: Proportional Transfer Fee Mechanism, Fee calculation
    diff --git a/zips/zip-0230.rst b/zips/zip-0230.rst index 2bed2e300..90199da29 100644 --- a/zips/zip-0230.rst +++ b/zips/zip-0230.rst @@ -24,6 +24,14 @@ 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 terms "Zcash Shielded Asset", "ZSA" and "Asset" in this document are to be interpreted as described in ZIP 226 [#zip-0226]_. + +The term "Issuance" and "Issuance Action" in this document are to be interpreted as described in ZIP 227 [#zip-0227]_. + +We define the following additional terms: + +- Issuance Fee: This is the specific fixed fee that has to be paid to the network for every given issuance action. + The character § is used when referring to sections of the Zcash Protocol Specification [#protocol]_. @@ -41,6 +49,10 @@ This ZIP also depends upon and defines modifications to the computation of the v **TxId Digest**, **Signature Digest**, and **Authorizing Data Commitment** defined by ZIP 244 [#zip-0244]_. +This ZIP additionally defines the fee mechanism associated with the Orchard Zcash Shielded Assets (OrchardZSA) protocol +as described in ZIP 226 [#zip-0226]_ and ZIP 227 [#zip-0227]_. +The fee mechanism is defined in terms of modifications to the Proportionak Transfer Fee Mechanism [#zip-0317]_. + Motivation ========== @@ -51,6 +63,15 @@ 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. +The upgrade to the OrchardZSA protocol will also need to define a fee structure consistent with the objectives of ZIP 317 [#zip-0317]_. +This involves adaptation for the transfer protocol [#zip-0226]_, as well as additional considerations for the issuance protocol [#zip-0227]_ such as fees for asset issuance. +Specifically, the OrchardZSA Transfer and Burn mechanism should follow the same fee mechanism in order to not discriminate between transfer bundle types. +When it comes to Issuance of ZSA, however, there should be a disincentive that will stop users from flooding the chain with useless asset identifiers. +In the case of Issuance, the computational power needed to verify the bundle is not large. +The transaction size, however, can be an issue as the number of output notes can be large. +Furthermore, as defined in ZIP 227 [#zip-0227]_, there is an additional data structure in the global state that needs to be maintained as part of the consensus. +This motivates further the addition of an Issuance-specific fee. + Requirements ============ @@ -66,6 +87,14 @@ 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. +In addition to the requirements of ZIP 317 [#zip-0317]_, the fee mechanism for the OrchardZSA protocol should satisfy the following requirements: + +* The conventional fee should not leak private information used in + constructing the transaction; that is, it should be computable from only + the public data of the transaction. +* Users should be discouraged from issuing new “garbage” custom Assets. + The fee should reflect the cost of adding new data to the global state. + Non-requirements ================ @@ -363,6 +392,70 @@ An issuance note, ``IssueNote`` contains the following fields: | | | |protocol §3.2.1 'Note Plaintexts and Memo Fields'. | +-----------------------------+--------------------------+--------------------------------------+--------------------------------------------------------------------+ +OrchardZSA Fee Calculation +========================== + +In addition to the parameters defined in the Fee calculation section of ZIP 317 [#zip-0317-fee-calc]_, the OrchardZSA protocol upgrade defines the following additional parameters: + +===================================== ========================================================================== +Parameter Value +===================================== ========================================================================== +:math:`issuance\_fee` :math:`100 \cdot marginal\_fee` per issuance action (as defined below) +===================================== ========================================================================== + +Wallets implementing this specification SHOULD use a conventional fee, viz. :math:`zsa\_conventional\_fee`, that is +calculated in zatoshis. Additional definitions that are used in the formula for the calculation are in the table below: + +================================ ====== ==================================================================================================================== +Input Units Description +================================ ====== ==================================================================================================================== +:math:`nOrchardActions` number the number of OrchardZSA transfer actions (including ZEC actions) +:math:`nTotalOutputsZsaIssuance` number the total number of OrchardZSA issuance outputs (added across issuance actions) +:math:`nCreateActions` number the number of OrchardZSA issuance actions that issue a Custom Asset that is not present in the Global Issuance State +================================ ====== ==================================================================================================================== + +The other inputs to this formula are taken from transaction fields defined in the Zcash protocol specification [#protocol-txnencoding]_ and the global state. +They are defined in the Fee calculation section of ZIP 317 [#zip-0317-fee-calc]_. +Note that :math:`nOrchardActions`, that is used in the computation of :math:`logical\_actions`, is redefined in the above table, and now combines the actions for native ZEC as well as OrchardZSA transfer actions for Custom Assets. + +The formula for the computation of the :math:`zsa\_logical\_actions` (with the updated computation of :math:`logical\_actions` as described above) is: + +.. math:: + zsa\_logical\_actions = logical\_actions \;+ nTotalOutputsZsaIssuance + +The formula for the computation of the :math:`zsa\_conventional\_fee` is: + +.. math:: + \begin{array}{rcl} + zsa\_conventional\_fee &=& marginal\_fee \cdot \mathsf{max}(grace\_actions, zsa\_logical\_actions) \;+ \\ + & & issuance\_fee \cdot nCreateActions + \end{array} + + + + +It is not a consensus requirement that fees follow this formula; however, +wallets SHOULD create transactions that pay this fee, in order to reduce +information leakage, unless overridden by the user. + +Rationale for OrchardZSA Fee calculation +---------------------------------------- + +The OrchardZSA fee calculation accounts for the additions to the Global Issuance State that are required for the OrchardZSA protocol. +Every newly created Custom Asset adds a new row to the Global Issuance State. +Subsequent issuance, finalization, or burn of existing Custom Assets only changes the values in the corresponding row. + +This explains the need for a higher fee for the creation of entirely new Custom Assets, in order to disincentivize the creation of "junk" assets. + +OrchardZSA Fee Considerations +----------------------------- + +We choose to maintain the native ZEC Asset as the primary token for the Zcash blockchain, similar to how ETH is needed for ERC20 transactions to the benefit of the Ethereum ecosystem. + +An alternative proposal for the OrchardZSA fee mechanism that was not adopted was to adopt a new type of fee, denominated in the custom Asset being issued or transferred. +In the context of transparent transactions, such a fee allows miners to “tap into” the ZSA value of the transactions, rather than the ZEC value of transactions. +However when transactions are shielded, any design that lifts value from the transaction would also leak information about it. + Reference implementation ======================== @@ -378,6 +471,9 @@ References .. [#protocol-spenddesc] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.4: Spend Descriptions `_ .. [#protocol-outputdesc] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.5: Output Descriptions `_ .. [#protocol-actiondesc] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.6: Action Descriptions `_ +.. [#protocol-txnencoding] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus `_ .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ .. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0317] `ZIP 317: Proportional Transfer Fee Mechanism `_ +.. [#zip-0317-fee-calc] `ZIP 317: Proportional Transfer Fee Mechanism, Fee calculation `_