ZSA Protocol: Transfer, Issuance and Burn: ZIPs 226, 227, and 230 #960
Conversation
This merges in the changes from upstream post the merging of our PR#854 to upstream.
This makes a few changes to the usage of terminology such as the use of the capital MUST terms in the specification.
This removes the tables with the encoding of the issuance action description and issuance bundle from ZIP 227. This same material has been included in ZIP 230 as part of the V6 transaction format, and thus it is simpler to have it defined in a single place. ZIP 227 has been updated with references to the relevant sections of ZIP 230 where necessary.
This changes the encoding of the transaction format to add Action Groups to TxV6. The motivation is to avoid the need of a further transaction format upgrade while introducing Asset Swaps for ZSAs in a subsequent upgrade. It also makes some consistency improvements to the ZIPs, and updates outdated references.
This PR adds an explicit upper bound of $$2^{64} - 1$$ to the total
supply of issued assets in the specification of ZIP 227.
It also does a major rewrite of the consensus rule changes, bringing
them more in line with the protocol specification, and using MUST
terminology where necessary.
Furthermore, these changes make explicit the order of processing fields
within a transaction, and the order of updates to the issuance state.
This PR moves the description of the fees required for OrchardZSA issuance and transfer to ZIP 227. This is a more contextual place to have the material, compared to ZIP 230, which specifies the V6 transaction format.
This updates the `zsa1` branch with the changes from upstream, and resolves conflicts.
This adds the explicit specification (with types) for the Issue Note.
This defines a new function and uses it to derive the value of the $\rho$ field in Issue Notes. It also updates the consensus rules accordingly and makes some typographical improvements.
This simplifies the encoding of the $\mathsf{nf}$ argument in the
computation of $\rho$, so that it avoids the double use of
$\mathsf{LEBS2OSP(I2LEOSP(...))}$.
This adjusts the type and specification of the notes to mirror the implementation, specifically that the Asset Base occurs in the middle of the tuple, and not at the end.
This adds the specification of reference notes, which are to be created at the time of first issuance of a Custom Asset. Alongside, we also update the issuance state and consensus rules to account for these changes.
There was a problem hiding this comment.
Reviewed 2ef0f1a in ZIP Sync with @nuttycom, @arya2, @conradoplg, @daira, and @SamHSmith. The "Note to ZIP Editors" comments are not blocking and should not be addressed in this PR.
| | **OrchardZSA Transaction Fields** | | ||
| +------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------+ | ||
| |``varies`` |``nActionGroupsOrchard`` |``compactSize`` |The number of Action Group descriptions in ``vActionGroupsOrchard``. | | ||
| | | | |This MUST have a value of either ``0`` or ``1``. | |
There was a problem hiding this comment.
This MUST should be a consensus rule (that can be lifted in a later NU when Atomic Swaps are introduced) instead of a parser rule (which could only be changed in a format change, which is the opposite of what is desired here).
| The encoding of Sapling Spends and Outputs has changed relative to prior versions in order | ||
| to better separate data that describe the effects of the transaction from the proofs of and | ||
| commitments to those effects, and for symmetry with this separation in the Orchard-related parts | ||
| of the transaction format. |
There was a problem hiding this comment.
Note to ZIP Editors: this paragraph is copy-pasta-ed from the v5 tx format ZIP where this change occurred; it isn't relevant here, and we will reword it when we start defining the final v6 tx format.
| | Bytes | Name | Data Type | Description | | ||
| +====================================+==========================+==================================================+=====================================================================+ | ||
| |``varies`` |``nActionsOrchard`` |``compactSize`` |The number of Action descriptions in ``vActionsOrchard``. | | ||
| | | | |This MUST have a value strictly greater than ``0``. | |
There was a problem hiding this comment.
This is correct to have as a parser rule (c/f the previous comment), as it ensures implementers can use a NonEmptyVec-style type here.
| +------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------+ | ||
| |``sizeProofsOrchard`` |``proofsOrchard`` |``byte[sizeProofsOrchard]`` |The aggregated zk-SNARK proof for all Actions in the Action Group. | | ||
| +------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------+ | ||
| |``4`` |``nAGExpiryHeight`` |``uint32`` |A block height (in the future) after which the Actions of the | |
There was a problem hiding this comment.
Note to ZIP Editors: this is effecting data, not authorizing data, so it will be moved to earlier in the ActionGroup format.
| +------------------------------------+--------------------------+--------------------------------------------------+---------------------------------------------------------------------+ | ||
| |``4`` |``nAGExpiryHeight`` |``uint32`` |A block height (in the future) after which the Actions of the | | ||
| | | | |Action Group become invalid and should be rejected by consensus. | | ||
| | | | |This MUST have a value of ``0``. | |
There was a problem hiding this comment.
This should also be a consensus rule, not a parser rule.
| - It MUST be the case that $0 < \mathtt{assetDescSize} \leq 512$. | ||
| - It MUST be the case that $\mathsf{asset\_desc}$ is a string of length $\mathtt{assetDescSize}$ bytes. | ||
| - Every Issue Note in ``IssueAction`` MUST be a valid encoding of the $\mathsf{Note^{Issue}}$ type, and MUST encode the same $\mathsf{AssetBase}$. | ||
| - This $\mathsf{AssetBase}$ MUST satisfy the derivation from the issuance validating key and asset description described in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. |
There was a problem hiding this comment.
Note to ZIP Editors: we will remove the explicit AssetBase from the v6 tx format, along with this consensus rule and the MUST encode from the previous rule.
Issuance bundles include both ik and asset_desc, meaning that AssetBase can always be derived. No computation is saved in consensus rules from encoding it due to the need to check the validity, so we may as well just use the output of the computation directly.
|
|
||
| - For every issue note description ($\mathsf{note}_{\mathsf{j}},\ 1 \leq j \leq \mathtt{nNotes}$) in ``IssueAction``: | ||
|
|
||
| - The $\text{ρ}$ field of the issue note MUST have been computed as described in the `Computation of ρ`_ section. |
There was a problem hiding this comment.
Note to ZIP Editors: consider whether rho should just be derived instead of encoded and checked (like will be done for AssetBase).
In general, the places we have regretted not explicitly encoding something is where the ability to derive it depends on non-local information (e.g. fees depend on looking up prior transparent transaction outputs). Here, both assetBase and rho can be computed solely from information present in the transaction. (There might however be a question wrt compact blocks as to whether there is sufficient information; consider this when deciding the final v6 tx format.)
| - The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This is in order to keep the issuance details and the Asset Identifiers consistent across multiple shielded pools. | ||
| - The design decision is not to have a chosen name to describe the Custom Asset, but to delegate it to an off-chain mapping, as this would imply a land-grab “war”. | ||
| - The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This keeps the issuance details and the Asset Identifiers consistent across multiple shielded pools. It also separates the issuance authority from the spend authority, allowing for the potential transfer of issuance authority without compromising the spend authority. | ||
| - The Custom Asset is described via a combination of the issuance validating key and an asset description string, to preclude the possibility of two different issuers creating colliding Custom Assets. |
There was a problem hiding this comment.
Probably want to mention wallet-level considerations here (e.g. problems with an issue issuing two assets that only differ in JSON whitespace in asset_desc), as well as maybe allude to future issuance designs where collision / sharing of an asset ID is desired.
TODO for @daira to write a Security Considerations / Rationale section for how asset_desc is included.
This PR continues the discussion on the ZSA ZIPs from the merged #854.
It contains any recent changes to the following ZIPs:
Note that the target issue for the ZSA ZIPs is #618.
This pull request contains changes that resolve the following issues related to ZSAs: