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

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

Closed
wants to merge 2 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc5b418
Moving the Burn information into the Action Group (#97)
vivek-arte Feb 4, 2025
fbd0566
Upstream merge (#98)
vivek-arte Feb 6, 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
44 changes: 19 additions & 25 deletions rendered/zip-0226.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -474,20 +474,20 @@ <h4>The
<section id="t-4-orchard-digest"><h4><span class="section-heading">T.4: orchard_digest</span><span class="section-anchor"> <a rel="bookmark" href="#t-4-orchard-digest"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h4>
<p>When OrchardZSA Actions Groups are present in the transaction, this digest is a BLAKE2b-256 hash of the following values:</p>
<pre>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)</pre>
<p>The personalization field of this hash is the same as in ZIP 244 <a id="footnote-reference-55" class="footnote_reference" href="#zip-0244">15</a></p>
<pre>"ZTxIdOrchardHash"</pre>
<p>In the case that the transaction has no OrchardZSA Action Groups, <code>orchard_digest</code> is</p>
<pre>BLAKE2b-256("ZTxIdOrchardHash", [])</pre>
<section id="t-4a-orchard-action-groups-digest"><h5><span class="section-heading">T.4a: orchard_action_groups_digest</span><span class="section-anchor"> <a rel="bookmark" href="#t-4a-orchard-action-groups-digest"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h5>
<p>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:</p>
<pre>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)</pre>
<pre>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 : 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)</pre>
<p>The personalization field of this hash is set to:</p>
<pre>"ZTxIdOrcActGHash"</pre>
<section id="t-4a-i-orchard-actions-compact-digest"><h6><span class="section-heading">T.4a.i: orchard_actions_compact_digest</span><span class="section-anchor"> <a rel="bookmark" href="#t-4a-i-orchard-actions-compact-digest"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h6>
Expand All @@ -514,24 +514,18 @@ <h4>The
<p>The personalization field of this hash is defined identically to ZIP 244:</p>
<pre>"ZTxIdOrcActNHash"</pre>
</section>
</section>
<section id="t-4b-orchard-zsa-burn-digest"><h5><span class="section-heading">T.4b: orchard_zsa_burn_digest</span><span class="section-anchor"> <a rel="bookmark" href="#t-4b-orchard-zsa-burn-digest"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h5>
<p>A BLAKE2b-256 hash of the data from the burn fields of the transaction. For each tuple in the
<span class="math">\(\mathsf{assetBurn}\)</span>
set, the following elements are included in the hash:</p>
<pre>T.4b.i : assetBase (field encoding bytes)
T.4b.ii: valueBurn (field encoding bytes)</pre>
<p>The personalization field of this hash is set to:</p>
<pre>"ZTxIdOrcBurnHash"</pre>
<p>In case the transaction does not perform the burning of any Assets (i.e. the
<span class="math">\(\mathsf{assetBurn}\)</span>
set is empty), the ''orchard_zsa_burn_digest'' is:</p>
<pre>BLAKE2b-256("ZTxIdOrcBurnHash", [])</pre>
<section id="t-4b-i-assetbase"><h6><span class="section-heading">T.4b.i: assetBase</span><span class="section-anchor"> <a rel="bookmark" href="#t-4b-i-assetbase"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h6>
<p>The Asset Base being burnt encoded as the 32-byte representation of a point on the Pallas curve.</p>
</section>
<section id="t-4b-ii-valueburn"><h6><span class="section-heading">T.4b.ii: valueBurn</span><span class="section-anchor"> <a rel="bookmark" href="#t-4b-ii-valueburn"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h6>
<p>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.</p>
<section id="t-4a-iv-orchard-zsa-burn-digest"><h6><span class="section-heading">T.4a.iv: orchard_zsa_burn_digest</span><span class="section-anchor"> <a rel="bookmark" href="#t-4a-iv-orchard-zsa-burn-digest"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h6>
<p>A BLAKE2b-256 hash of the data from the burn fields of the transaction. For each tuple in the
<span class="math">\(\mathsf{assetBurn}\)</span>
set, the following elements are included in the hash:</p>
<pre>T.4a.iv.1 : assetBase (field encoding bytes)
T.4a.iv.2 : valueBurn (field encoding bytes)</pre>
<p>The personalization field of this hash is set to:</p>
<pre>"ZTxIdOrcBurnHash"</pre>
<p>In case the transaction does not perform the burning of any Assets (i.e. the
<span class="math">\(\mathsf{assetBurn}\)</span>
set is empty), the ''orchard_zsa_burn_digest'' is:</p>
<pre>BLAKE2b-256("ZTxIdOrcBurnHash", [])</pre>
</section>
</section>
</section>
Expand Down
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
32 changes: 11 additions & 21 deletions zips/zip-0226.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,6 @@ T.4: orchard_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)

The personalization field of this hash is the same as in ZIP 244 [#zip-0244]_ ::
Expand All @@ -385,12 +384,13 @@ T.4a: orchard_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_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 : 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::

Expand Down Expand Up @@ -447,14 +447,14 @@ The personalization field of this hash is defined identically to 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::

Expand All @@ -465,16 +465,6 @@ $\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 Down
12 changes: 6 additions & 6 deletions zips/zip-0230.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,11 +178,6 @@ Transaction Format
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------+
|``8`` |``valueBalanceOrchard`` |``int64`` |The net value of Orchard spends minus outputs. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------+
| ``varies`` | ``nAssetBurn`` | ``compactSize`` | The number of Assets burnt. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------+
| ``40 * nAssetBurn`` | ``vAssetBurn`` | ``AssetBurn[nAssetBurn]`` | A sequence of Asset Burn descriptions, |
| | | | encoded per `OrchardZSA Asset Burn Description`_. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------+
|``64`` |``bindingSigOrchard`` |``byte[64]`` |An OrchardZSA binding signature on the SIGHASH transaction hash. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------+
| **OrchardZSA Issuance Fields** |
Expand Down Expand Up @@ -300,8 +295,13 @@ The OrchardZSA Action Group Description is encoded in a transaction as an instan
|``64 * nActionsOrchard`` |``vSpendAuthSigsOrchard`` |``byte[64 * nActionsOrchard]`` |Authorizing signatures for each Action of the Action Group in a |
| | | |transaction. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------+
| ``varies`` | ``nAssetBurn`` | ``compactSize`` | The number of Assets burnt. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------+
| ``40 * nAssetBurn`` | ``vAssetBurn`` | ``AssetBurn[nAssetBurn]`` | A sequence of Asset Burn descriptions, encoded per |
| | | | `OrchardZSA Asset Burn Description`_. |
+------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------+

The encoding of ``OrchardZSAAction`` is described below.
The encodings of ``OrchardZSAAction`` and ``AssetBurn`` are described below.

* The proofs aggregated in ``proofsOrchardZSA``, and the elements of
``vSpendAuthSigsOrchard``, each have a 1:1 correspondence to the elements of
Expand Down