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

Updating the spec for clarity and parity with the implementation of the V7 transaction details #55

Merged
merged 5 commits into from
Jul 19, 2024
Merged

Updating the spec for clarity and parity with the implementation of the V7 transaction details #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
544716a
changing data type of assetDescSize to compactSize
vivek-arte Jul 9, 2024
3abe648
adding the specification of the IssueNote data type, along with relat…
vivek-arte Jul 9, 2024
bc4ffb0
rearranging transaction format to place the Orchard binding signature…
vivek-arte Jul 9, 2024
d6b9f39
updating valueBurn data type to be uint64
vivek-arte Jul 9, 2024
6683c1c
making editorial changes
vivek-arte Jul 19, 2024
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
82 changes: 62 additions & 20 deletions zip-0230.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,15 +263,6 @@
<td><code>byte[64 * nActionsOrchard]</code></td>
<td>Authorizing signatures for each Orchard-ZSA Action.</td>
</tr>
<tr>
<td><code>64</code></td>
<td><code>bindingSigOrchard</code></td>
<td><code>byte[64]</code></td>
<td>An Orchard binding signature on the SIGHASH transaction hash.</td>
</tr>
<tr>
<td colspan="4"><strong>Orchard-ZSA Burn Fields</strong></td>
</tr>
<tr>
<td><code>varies</code></td>
<td><code>nAssetBurn</code></td>
Expand All @@ -284,6 +275,12 @@
<td><code>AssetBurn[nAssetBurn]</code></td>
<td>A sequence of Asset Burn descriptions, encoded per <a href="#orchard-zsa-asset-burn-description">Orchard-ZSA Asset Burn Description</a>.</td>
</tr>
<tr>
<td><code>64</code></td>
<td><code>bindingSigOrchard</code></td>
<td><code>byte[64]</code></td>
<td>An Orchard-ZSA binding signature on the SIGHASH transaction hash.</td>
</tr>
<tr>
<td colspan="4"><strong>Orchard-ZSA Issuance Fields</strong></td>
</tr>
Expand Down Expand Up @@ -505,10 +502,8 @@
<tr>
<td>8</td>
<td><code>valueBurn</code></td>
<td>
<span class="math">\(\{1 .. 2^{64} - 1\}\)</span>
</td>
<td>The amount being burnt.</td>
<td><code>uint64</code></td>
<td>The amount being burnt. The value is checked by consensus to be non-zero.</td>
</tr>
</tbody>
</table>
Expand All @@ -527,9 +522,9 @@
</thead>
<tbody>
<tr>
<td><code>2</code></td>
<td><code>varies</code></td>
<td><code>assetDescSize</code></td>
<td><code>byte</code></td>
<td><code>compactSize</code></td>
<td>The length of the asset description string in bytes.</td>
</tr>
<tr>
Expand All @@ -542,13 +537,13 @@
<td><code>varies</code></td>
<td><code>nNotes</code></td>
<td><code>compactSize</code></td>
<td>The number of notes in the issuance action.</td>
<td>The number of notes in the Issuance Action.</td>
</tr>
<tr>
<td><code>noteSize * nNotes</code></td>
<td><code>147 * nNotes</code></td>
<td><code>vNotes</code></td>
<td><code>Note[nNotes]</code></td>
<td>A sequence of note descriptions within the issuance action, where <code>noteSize</code> is the size, in bytes, of a Note.</td>
<td><code>IssueNote[nNotes]</code></td>
<td>A sequence of note descriptions within the Issuance Action.</td>
</tr>
<tr>
<td><code>1</code></td>
Expand All @@ -572,7 +567,54 @@
</tr>
</tbody>
</table>
<p>The encodings of each of these elements are defined in ZIP 227 <a id="footnote-reference-9" class="footnote_reference" href="#zip-0227">7</a>. Note that we allow the number of notes (represented by <code>nNotes</code>) 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.</p>
<p>The encoding of <code>IssueNote</code> is described below. Note that we allow the number of notes (represented by <code>nNotes</code>) 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.</p>
</section>
<section id="issue-note-description-issuenote"><h3><span class="section-heading">Issue Note Description (<code>IssueNote</code>)</span><span class="section-anchor"> <a rel="bookmark" href="#issue-note-description-issuenote"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>An issuance note, <code>IssueNote</code> contains the following fields:</p>
<table>
<thead>
<tr>
<th>Bytes</th>
<th>Name</th>
<th>Data Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>43</code></td>
<td><code>recipient</code></td>
<td><code>byte[43]</code></td>
<td>The raw encoding of an Orchard Raw Payment Address, as per protocol §5.6.4.2 ‘Orchard Raw Payment Addresses’.</td>
</tr>
<tr>
<td><code>8</code></td>
<td><code>value</code></td>
<td><code>uint64</code></td>
<td>The amount being issued in this note.</td>
</tr>
<tr>
<td><code>32</code></td>
<td><code>assetBase</code></td>
<td><code>byte[32]</code></td>
<td>The encoding of the Asset Base
<span class="math">\(\mathsf{AssetBase^{Orchard}}\!\)</span>
, as defined in 'ZIP 227'.</td>
</tr>
<tr>
<td><code>32</code></td>
<td><code>rho</code></td>
<td><code>byte[32]</code></td>
<td>This is defined and encoded in the same manner as for Orchard notes in protocol §3.2 'Notes'.</td>
</tr>
<tr>
<td><code>32</code></td>
<td><code>rseed</code></td>
<td><code>byte[32]</code></td>
<td>The <code>rseed</code> field of the note, encoded as for Orchard notes in protocol §3.2 'Notes'.</td>
</tr>
</tbody>
</table>
</section>
</section>
<section id="reference-implementation"><h2><span class="section-heading">Reference implementation</span><span class="section-anchor"> <a rel="bookmark" href="#reference-implementation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
Expand Down
41 changes: 31 additions & 10 deletions zip-0230.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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]_.
Expand All @@ -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
========================

Expand Down