Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

ZIPs 226, 227, and 230: ZSA Transfer, Issuance and Burn #976

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

ZIPs 226, 227, and 230: ZSA Transfer, Issuance and Burn #976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cc5b418
Moving the Burn information into the Action Group (#97)
vivek-arte Feb 4, 2025
fbd0566
Upstream merge (#98)
vivek-arte Feb 6, 2025
8662fd6
Updating digest names (#95)
vivek-arte Feb 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 85 additions & 67 deletions rendered/zip-0226.html
View file
Open in desktop

Large diffs are not rendered by default.

71 changes: 26 additions & 45 deletions rendered/zip-0227.html
View file
Open in desktop

Large diffs are not rendered by default.

26 changes: 13 additions & 13 deletions rendered/zip-0230.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,18 +232,6 @@
<td><code>int64</code></td>
<td>The net value of Orchard spends minus outputs.</td>
</tr>
<tr>
<td><code>varies</code></td>
<td><code>nAssetBurn</code></td>
<td><code>compactSize</code></td>
<td>The number of Assets burnt.</td>
</tr>
<tr>
<td><code>40 * nAssetBurn</code></td>
<td><code>vAssetBurn</code></td>
<td><code>AssetBurn[nAssetBurn]</code></td>
<td>A sequence of Asset Burn descriptions, encoded per <a href="#orchardzsa-asset-burn-description">OrchardZSA Asset Burn Description</a>.</td>
</tr>
<tr>
<td><code>64</code></td>
<td><code>bindingSigOrchard</code></td>
Expand Down Expand Up @@ -448,9 +436,21 @@
<td><code>byte[64 * nActionsOrchard]</code></td>
<td>Authorizing signatures for each Action of the Action Group in a transaction.</td>
</tr>
<tr>
<td><code>varies</code></td>
<td><code>nAssetBurn</code></td>
<td><code>compactSize</code></td>
<td>The number of Assets burnt.</td>
</tr>
<tr>
<td><code>40 * nAssetBurn</code></td>
<td><code>vAssetBurn</code></td>
<td><code>AssetBurn[nAssetBurn]</code></td>
<td>A sequence of Asset Burn descriptions, encoded per <a href="#orchardzsa-asset-burn-description">OrchardZSA Asset Burn Description</a>.</td>
</tr>
</tbody>
</table>
<p>The encoding of <code>OrchardZSAAction</code> is described below.</p>
<p>The encodings of <code>OrchardZSAAction</code> and <code>AssetBurn</code> are described below.</p>
<ul>
<li>The proofs aggregated in <code>proofsOrchardZSA</code>, and the elements of <code>vSpendAuthSigsOrchard</code>, each have a 1:1 correspondence to the elements of <code>vActionsOrchard</code> and MUST be ordered such that the proof or signature at a given index corresponds to the <code>OrchardZSAAction</code> at the same index.</li>
</ul>
Expand Down
143 changes: 84 additions & 59 deletions zips/zip-0226.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,8 +348,8 @@ The transaction format for v6 transactions is described in ZIP 230 [#zip-0230]_.
TxId Digest
===========

The transaction digest algorithm defined in ZIP 244 [#zip-0244]_ is modified by the OrchardZSA 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 OrchardZSA protocol.
The transaction digest algorithm defined in ZIP 244 [#zip-0244]_ is modified by the OrchardZSA protocol to add a new branch for issuance information, along with replacement of the ``orchard_digest`` with a new ``orchard_zsa_digest`` to account for the inclusion of the Asset Base and the updated transaction format.
The details of these changes are described in this section, and highlighted using the ``[ADDED FOR ZSA]`` text label. We omit the details of the sections that do not change for the OrchardZSA protocol.

txid_digest
-----------
Expand All @@ -358,47 +358,47 @@ A BLAKE2b-256 hash of the following values::
T.1: header_digest (32-byte hash output)
T.2: transparent_digest (32-byte hash output)
T.3: sapling_digest (32-byte hash output)
T.4: orchard_digest (32-byte hash output) [UPDATED FOR ZSA]
T.4: orchard_zsa_digest (32-byte hash output) [ADDED FOR ZSA]
T.5: issuance_digest (32-byte hash output) [ADDED FOR ZSA]

The personalization field remains the same as in ZIP 244 [#zip-0244]_.

T.4: orchard_digest
```````````````````
T.4: orchard_zsa_digest
```````````````````````
When OrchardZSA Actions Groups are present in the transaction, this digest is a BLAKE2b-256 hash of the following values::

T.4a: orchard_action_groups_digest (32-byte hash output) [ADDED FOR ZSA]
T.4b: orchard_zsa_burn_digest (32-byte hash output) [ADDED FOR ZSA]
T.4c: valueBalanceOrchard (64-bit signed little-endian)
T.4a: orchard_zsa_action_groups_digest (32-byte hash output)
T.4b: valueBalanceOrchard (64-bit signed little-endian)

The personalization field of this hash is the same as in ZIP 244 [#zip-0244]_ ::
The personalization field of this hash is the same as for ``orchard_digest`` in ZIP 244 [#zip-0244]_ ::

"ZTxIdOrchardHash"

In the case that the transaction has no OrchardZSA Action Groups, ``orchard_digest`` is ::
In the case that the transaction has no OrchardZSA Action Groups, ``orchard_zsa_digest`` is ::

BLAKE2b-256("ZTxIdOrchardHash", [])

T.4a: orchard_action_groups_digest
''''''''''''''''''''''''''''''''''
T.4a: orchard_zsa_action_groups_digest
''''''''''''''''''''''''''''''''''''''

A BLAKE2b-256 hash of the subset of OrchardZSA Action Groups information for all OrchardZSA Action Groups belonging to the transaction.
For each Action Group, the following elements are included in the hash::

T.4a.i : orchard_actions_compact_digest (32-byte hash output)
T.4a.ii : orchard_actions_memos_digest (32-byte hash output)
T.4a.iii: orchard_actions_noncompact_digest (32-byte hash output)
T.4a.iv : flagsOrchard (1 byte)
T.4a.v : anchorOrchard (32 bytes)
T.4a.vi : nAGExpiryHeight (4 bytes)
T.4a.i : orchard_zsa_actions_compact_digest (32-byte hash output)
T.4a.ii : orchard_zsa_actions_memos_digest (32-byte hash output)
T.4a.iii : orchard_zsa_actions_noncompact_digest (32-byte hash output)
T.4a.iv : orchard_zsa_burn_digest (32-byte hash output)
T.4a.v : flagsOrchard (1 byte)
T.4a.vi : anchorOrchard (32 bytes)
T.4a.vii : nAGExpiryHeight (4 bytes)

The personalization field of this hash is set to::

"ZTxIdOrcActGHash"


T.4a.i: orchard_actions_compact_digest
......................................
T.4a.i: orchard_zsa_actions_compact_digest
..........................................

A BLAKE2b-256 hash of the subset of OrchardZSA Action information intended to be included in
an updated version of the ZIP-307 [#zip-0307]_ ``CompactBlock`` format for all OrchardZSA
Expand All @@ -408,29 +408,29 @@ in the hash::
T.4a.i.1 : nullifier (field encoding bytes)
T.4a.i.2 : cmx (field encoding bytes)
T.4a.i.3 : ephemeralKey (field encoding bytes)
T.4a.i.4 : encCiphertext[..84] (First 84 bytes of field encoding) [UPDATED FOR ZSA]
T.4a.i.4 : encCiphertext[..84] (First 84 bytes of field encoding)

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

"ZTxIdOrcActCHash"


T.4a.ii: orchard_actions_memos_digest
.....................................
T.4a.ii: orchard_zsa_actions_memos_digest
.........................................

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

T.4a.ii.1: encCiphertext[84..596] (contents of the encrypted memo field) [UPDATED FOR ZSA]
T.4a.ii.1: encCiphertext[84..596] (contents of the encrypted memo field)

The personalization field of this hash remains identical to ZIP 244::
The personalization field of this hash is identical to that for ``orchard_actions_memos_digest`` in ZIP 244::

"ZTxIdOrcActMHash"


T.4a.iii: orchard_actions_noncompact_digest
...........................................
T.4a.iii: orchard_zsa_actions_noncompact_digest
...............................................

A BLAKE2b-256 hash of the remaining subset of OrchardZSA Action information **not** intended
for inclusion in an updated version of the the ZIP 307 [#zip-0307]_ ``CompactBlock``
Expand All @@ -439,42 +439,32 @@ the following elements are included in the hash::

T.4a.iii.1 : cv (field encoding bytes)
T.4a.iii.2 : rk (field encoding bytes)
T.4a.iii.3 : encCiphertext[596..] (post-memo suffix of field encoding) [UPDATED FOR ZSA]
T.4a.iii.3 : encCiphertext[596..] (post-memo suffix of field encoding)
T.4a.iii.4 : outCiphertext (field encoding bytes)

The personalization field of this hash is defined identically to ZIP 244::
The personalization field of this hash is defined just as for ``orchard_actions_noncompact_digest`` in ZIP 244::

"ZTxIdOrcActNHash"


T.4b: orchard_zsa_burn_digest
'''''''''''''''''''''''''''''
T.4a.iv: 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.4b.i : assetBase (field encoding bytes)
T.4b.ii: valueBurn (field encoding bytes)
T.4a.iv.1 : assetBase (field encoding bytes)
T.4a.iv.2 : 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::
$\mathsf{assetBurn}$ set is empty), the ``orchard_zsa_burn_digest`` is::

BLAKE2b-256("ZTxIdOrcBurnHash", [])

T.4b.i: assetBase
.................
The Asset Base being burnt encoded as the 32-byte representation of a point on the
Pallas curve.

T.4b.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
````````````````````
Expand All @@ -483,20 +473,55 @@ The details of the computation of this value are in ZIP 227 [#zip-0227-txiddiges
Signature Digest
================

The details of the changes to this algorithm are in ZIP 227 [#zip-0227-sigdigest]_.
The per-input transaction digest algorithm to generate the signature digest in ZIP 244 [#zip-0244-sigdigest]_ is modified so that a signature digest is produced for each transparent input, each Sapling input, each OrchardZSA Action, and additionally for each Issuance Action.
The modifications replace the ``orchard_digest`` in ZIP 244 with a new ``orchard_zsa_digest``, and add a new branch, ``issuance_digest``, for the Issuance Action information.

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

signature_digest
├── header_digest
├── transparent_sig_digest
├── sapling_digest
├── orchard_zsa_digest [ADDED FOR ZSA]
└── issuance_digest [ADDED FOR ZSA]

signature_digest
----------------
A BLAKE2b-256 hash of the following values ::

S.1: header_digest (32-byte hash output)
S.2: transparent_sig_digest (32-byte hash output)
S.3: sapling_digest (32-byte hash output)
S.4: orchard_zsa_digest (32-byte hash output) [ADDED FOR ZSA]
S.5: issuance_digest (32-byte hash output) [ADDED FOR ZSA]

The personalization field remains the same as in ZIP 244 [#zip-0244]_, namely::

"ZcashTxHash_" || CONSENSUS_BRANCH_ID

``ZcashTxHash_`` has 1 underscore character.

S.4: orchard_zsa_digest
```````````````````````
Identical to that specified for the transaction identifier.

S.5: issuance_digest
````````````````````
Identical to the ``issuance_digest`` specified for the transaction identifier in ZIP 227 [zip-0227-txiddigest]_.


Authorizing Data Commitment
===========================

The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the OrchardZSA protocol to have the structure specified in this section.
There is a new branch added for issuance information, along with modifications within the ``orchard_auth_digest`` to account for the presence of Action Groups.
There is a new branch added for issuance information, and the ``orchard_auth_digest`` in ZIP 244 is replaced with ``orchard_zsa_auth_digest`` to account for the presence of Action Groups.

We highlight the changes for the OrchardZSA protocol via the ``[UPDATED FOR ZSA]`` or ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the OrchardZSA protocol::
We highlight the changes for the OrchardZSA protocol via the ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the OrchardZSA protocol::

auth_digest
├── transparent_scripts_digest
├── sapling_auth_digest
├── orchard_auth_digest [UPDATED FOR ZSA]
├── orchard_zsa_auth_digest [ADDED FOR ZSA]
└── issuance_auth_digest [ADDED FOR ZSA]

The pair (Transaction Identifier, Auth Commitment) constitutes a commitment to all the data of a serialized transaction that may be included in a block.
Expand All @@ -507,32 +532,32 @@ A BLAKE2b-256 hash of the following values ::

A.1: transparent_scripts_digest (32-byte hash output)
A.2: sapling_auth_digest (32-byte hash output)
A.3: orchard_auth_digest (32-byte hash output) [UPDATED FOR ZSA]
A.3: orchard_zsa_auth_digest (32-byte hash output) [ADDED FOR ZSA]
A.4: issuance_auth_digest (32-byte hash output) [ADDED FOR ZSA]

The personalization field of this hash remains the same as in ZIP 244.


A.3: orchard_auth_digest
````````````````````````
A.3: orchard_zsa_auth_digest
````````````````````````````

In the case that OrchardZSA Action Groups are present, this is a BLAKE2b-256 hash of the following values::

A.3a: orchard_action_groups_auth_digest (32-byte hash output) [ADDED FOR ZSA]
A.3b: bindingSigOrchard (field encoding bytes)
A.3a: orchard_zsa_action_groups_auth_digest (32-byte hash output)
A.3b: bindingSigOrchard (field encoding bytes)

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

"ZTxAuthOrchaHash"

In case that the transaction has no OrchardZSA Action Groups, ``orchard_auth_digest`` is::
In case that the transaction has no OrchardZSA Action Groups, ``orchard_zsa_auth_digest`` is::

BLAKE2b-256("ZTxAuthOrchaHash", [])

A.3a: orchard_action_groups_auth_digest
'''''''''''''''''''''''''''''''''''''''
A.3a: orchard_zsa_action_groups_auth_digest
'''''''''''''''''''''''''''''''''''''''''''

This is a BLAKE2b-256 hash of the ``proofsOrchard`` and ``spendAuthSigsOrchard`` fields of all OrchardZSA Action Groups belonging to the transaction::
This is a BLAKE2b-256 hash of the ``proofsOrchard`` field of all OrchardZSA Action Groups belonging to the transaction; followed by the ``spendAuthSigsOrchard`` fields corresponding to every OrchardZSA Action in the OrchardZSA Action Group, for all OrchardZSA Action Groups belonging to the transaction::

A.3a.i: proofsOrchard (field encoding bytes)
A.3a.ii: spendAuthSigsOrchard (field encoding bytes)
Expand Down Expand Up @@ -604,11 +629,11 @@ References
.. [#zip-0227-consensus] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Consensus Rule Changes <zip-0227.html#specification-consensus-rule-changes>`_
.. [#zip-0227-note-commitment-order] `ZIP 227: Issuance of Zcash Shielded Assets: Addition to the Note Commitment Tree <zip-0227.html#addition-to-the-note-commitment-tree>`_
.. [#zip-0227-txiddigest] `ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance <zip-0227.html#txid-digest-issuance>`_
.. [#zip-0227-sigdigest] `ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest <zip-0227.html#signature-digest>`_
.. [#zip-0227-authcommitment] `ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment <zip-0227.html#authorizing-data-commitment-issuance>`_
.. [#zip-0227-orchardzsa-fee-calculation] `ZIP 227: Issuance of Zcash Shielded Assets: OrchardZSA Fee Calculation <zip-0227.html#orchardzsa-fee-calculation>`_
.. [#zip-0230] `ZIP 230: Version 6 Transaction Format <zip-0230.html>`_
.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability <zip-0244.html>`_
.. [#zip-0244-sigdigest] `ZIP 244: Transaction Identifier Non-Malleability: Signature Digest <zip-0244.html#signature-digest>`_
.. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment <zip-0244.html#authorizing-data-commitment>`_
.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection <zip-0307.rst>`_
.. [#protocol-notes] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.2: Notes <protocol/protocol.pdf#notes>`_
Expand Down
Loading