Skip to content

Commit

Permalink
Updating the spec for clarity and parity with the implementation of t…
Browse files Browse the repository at this point in the history 
…he 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.
  • Loading branch information
@vivek-arte
vivek-arte authored Jul 19, 2024
1 parent be397c7 commit d8fba69
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 30 deletions.
82 changes: 62 additions & 20 deletions zip-0230.html
View file
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
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

0 comments on commit d8fba69

Please sign in to comment.