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] 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 ========================