diff --git a/rendered/assets/images/zip-0227-asset-identifier-relation-orchard-zsa.png b/rendered/assets/images/zip-0227-asset-identifier-relation-orchard-zsa.png new file mode 100644 index 000000000..aa12e678f Binary files /dev/null and b/rendered/assets/images/zip-0227-asset-identifier-relation-orchard-zsa.png differ diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index d98cd8d05..dc8409574 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -268,58 +268,66 @@

Specification: Asset Identifier, Asset Digest, and Asset Base

-

Every Asset has a globally-unique Asset Identifier, denoted - \(\mathsf{AssetId}\!\) - . A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols.

-

From the Asset Identifier, we derive an Asset Digest

-
\(\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})),\)
-

where - \(\mathsf{EncodeAssetId}(\mathsf{AssetId})\) - is a canonical encoding scheme for the Asset Identifier.

-

From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset within each shielded protocol:

-
\(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\)
-

This Asset Base is included in shielded notes within the shielded protocol.

-

The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

+

The definition of the Asset Identifier, and that of the Asset Digest and Asset Base for a given Asset Identifier, will be described in this section. For context, the relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

-
Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the OrchardZSA Protocol
+
Diagram relating the Asset Identifier, Asset Digest, and Asset Base.

Note: To keep notations light and concise, we may omit \(\mathsf{AssetId}\) - (resp. - \(\mathsf{Protocol}\!\) - ) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.

-

ZIP 227 Asset Identifiers

-

Assets issued using the protocol specified in this ZIP are scoped to the - \(\mathsf{ik}\) - that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an asset description, - \(\mathsf{asset\_desc}\!\) - , which includes any information pertaining to the issuance. - \(\mathsf{asset\_desc}\) - is a non-empty byte sequence which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.

-

Define

-
\(\mathsf{AssetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}),\)
-

We define Asset Identifiers for assets issued under this ZIP as

-
\(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{AssetDescHash})\)
-

and define their canonical encoding as

-
\(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{AssetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{AssetDescHash}\)
-

Note that the initial - \(\mathtt{0x00}\) - byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers.

-

Wallets MUST NOT display just the - \(\mathsf{asset\_desc}\) - string to their users as the name of the Asset. Some possible alternatives include:

- + in the subscript when the Asset Identifier is clear from the context.

+

Asset Identifiers

+

Every Asset has a globally-unique Asset Identifier, denoted + \(\mathsf{AssetId}\!\) + . A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols.

+

ZIP 227 Asset Identifiers

+

Assets issued using the protocol specified in this ZIP are scoped to the + \(\mathsf{ik}\) + that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an asset description, + \(\mathsf{asset\_desc}\!\) + , which includes any information pertaining to the issuance. + \(\mathsf{asset\_desc}\) + is a non-empty byte sequence which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.

+

Define

+
\(\mathsf{assetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}),\)
+

We define Asset Identifiers for Assets issued under this ZIP as

+
\(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{assetDescHash})\)
+

and define their canonical encoding as

+
\(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{assetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{assetDescHash}\)
+

Note that the initial + \(\mathtt{0x00}\) + byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers.

+

Wallets MUST NOT display just the + \(\mathsf{asset\_desc}\) + string to their users as the name of the Asset. Some possible alternatives include:

+
    +
  • Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
    • +
  • The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets.
    • +
+
-

OrchardZSA Custom Assets

-

In the case of the OrchardZSA protocol, we define

-
\(\mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}})\)
+

Asset Digests

+

From the Asset Identifier, we derive an Asset Digest

+
\(\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})),\)

where - \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 31.

+ \(\mathsf{EncodeAssetId}(\mathsf{AssetId})\) + is the canonical encoding scheme for the Asset Identifier.

+
+

Asset Bases

+

From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset within each shielded protocol:

+
\(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\)
+

This Asset Base is included in shielded notes within the shielded protocol.

+

OrchardZSA Asset Bases

+

In the case of the OrchardZSA protocol, we define

+
\(\mathsf{ZSAValueBase}(\mathsf{AssetDigest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest})\)
+

where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in 31.

+
+ +
Diagram relating the Issuance validating key, asset description, asset description hash, Asset Identifier, Asset Digest, and Asset Base for the OrchardZSA Protocol.
+
+

Specification: Issue Note, Issuance Action, Issuance Bundle and Issuance Protocol

@@ -361,10 +369,7 @@

Issuance Action

An issuance action, IssueAction, is the instance of issuing a specific Custom Asset, and contains the following fields:

    -
  • assetDescSize: the size of the Asset description, a non-zero number that is at most - \(512\!\) - .
    • -
  • asset_desc: the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier, Asset Digest, and Asset Base section.
    • +
  • assetDescHash: the hash of the Asset description, as defined in the ZIP 227 Asset Identifiers section.
  • vNotes: an array of Issue Notes containing the unencrypted output notes to the recipients of the Asset.
  • flagsIssuance: a byte that stores the \(\mathsf{finalize}\) @@ -423,14 +428,14 @@ \(\mathsf{asset\_desc}\) as a UTF-8 byte string.
  • compute - \(\mathsf{AssetDescHash}\) + \(\mathsf{assetDescHash}\)
  • compute \(\mathsf{AssetDigest}\) from the issuance validating key \(\mathsf{ik}\) and - \(\mathsf{AssetDescHash}\) + \(\mathsf{assetDescHash}\) as decribed in the Specification: Asset Identifier, Asset Digest, and Asset Base section.
  • compute \(\mathsf{AssetBase}\) @@ -762,7 +767,7 @@ 
    issuance_digest
 ├── issue_actions_digest
 │   ├── issue_notes_digest
-│   ├── assetDescription
+│   ├── assetDescHash
 │   └── flagsIssuance
 └── issuanceValidatingKey

    In the specification below, nodes of the tree are presented in depth-first order.

    @@ -777,7 +782,7 @@

    T.5a: issue_actions_digest

    A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:

    T.5a.i  : notes_digest            (32-byte hash output)
-T.5a.ii : assetDescription        (field encoding bytes)
+T.5a.ii : assetDescHash           (32-byte hash output)
 T.5a.iii: flagsIssuance           (1 byte)

    The personalization field of this hash is set to:

    "ZTxIdIssuActHash"
    diff --git a/zips/zip-0227-asset-identifier-relation-orchard-zsa.svg b/zips/zip-0227-asset-identifier-relation-orchard-zsa.svg new file mode 100644 index 000000000..200c2be19 --- /dev/null +++ b/zips/zip-0227-asset-identifier-relation-orchard-zsa.svg @@ -0,0 +1,471 @@ + + + +image/svg+xmlassetDescHashAssetDigestAssetIdasset_descAssetBaseAssetIdik[32 bytes]AssetId[32 bytes][64 bytes][32 bytes][65 bytes] diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index 0947971ba..36315685a 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -185,38 +185,28 @@ where the $\mathsf{Verify}$ algorithm is defined in BIP 340 [#bip-0340]_. Specification: Asset Identifier, Asset Digest, and Asset Base ============================================================= -Every Asset has a globally-unique Asset Identifier, denoted $\mathsf{AssetId}$. A given -Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the -OrchardZSA protocol and potentially future Zcash shielded protocols. - -From the Asset Identifier, we derive an Asset Digest - -.. math:: \mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})), - -where $\mathsf{EncodeAssetId}(\mathsf{AssetId})$ is a canonical encoding scheme for the -Asset Identifier. - -From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset -within each shielded protocol: - -.. math:: \mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) - -This Asset Base is included in shielded notes within the shielded protocol. - -The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram: +The definition of the Asset Identifier, and that of the Asset Digest and Asset Base for a given Asset Identifier, will be described in this section. +For context, the relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram: .. figure:: ../rendered/assets/images/zip-0227-asset-identifier-relation.png :width: 600px :align: center :figclass: align-center - Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the OrchardZSA Protocol + Diagram relating the Asset Identifier, Asset Digest, and Asset Base. -**Note:** To keep notations light and concise, we may omit $\mathsf{AssetId}$ (resp. $\mathsf{Protocol}$) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context. +**Note:** To keep notations light and concise, we may omit $\mathsf{AssetId}$ in the subscript when the Asset Identifier is clear from the context. + +Asset Identifiers +----------------- + +Every Asset has a globally-unique Asset Identifier, denoted $\mathsf{AssetId}$. A given +Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the +OrchardZSA protocol and potentially future Zcash shielded protocols. ZIP 227 Asset Identifiers -------------------------- +````````````````````````` Assets issued using the protocol specified in this ZIP are scoped to the $\mathsf{ik}$ that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an @@ -226,15 +216,15 @@ well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. Define -.. math:: \mathsf{AssetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}), +.. math:: \mathsf{assetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}), -We define Asset Identifiers for assets issued under this ZIP as +We define Asset Identifiers for Assets issued under this ZIP as -.. math:: \mathsf{AssetId} := (\mathsf{ik}, \mathsf{AssetDescHash}) +.. math:: \mathsf{AssetId} := (\mathsf{ik}, \mathsf{assetDescHash}) and define their canonical encoding as -.. math:: \mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{AssetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{AssetDescHash} +.. math:: \mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{assetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{assetDescHash} Note that the initial $\mathtt{0x00}$ byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers. @@ -244,15 +234,42 @@ Wallets MUST NOT display just the $\mathsf{asset\_desc}$ string to their users a - Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. - The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets. -OrchardZSA Custom Assets ------------------------- +Asset Digests +------------- + +From the Asset Identifier, we derive an Asset Digest + +.. math:: \mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})), + +where $\mathsf{EncodeAssetId}(\mathsf{AssetId})$ is the canonical encoding scheme for the +Asset Identifier. + +Asset Bases +----------- + +From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset +within each shielded protocol: + +.. math:: \mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) + +This Asset Base is included in shielded notes within the shielded protocol. + +OrchardZSA Asset Bases +`````````````````````` In the case of the OrchardZSA protocol, we define -.. math:: \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}}) +.. math:: \mathsf{ZSAValueBase}(\mathsf{AssetDigest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}) where $\mathsf{GroupHash}^\mathbb{P}$ is defined as in [#protocol-concretegrouphashpallasandvesta]_. +.. figure:: ../rendered/assets/images/zip-0227-asset-identifier-relation-orchard-zsa.png + :width: 800px + :align: center + :figclass: align-center + + Diagram relating the Issuance validating key, asset description, asset description hash, Asset Identifier, Asset Digest, and Asset Base for the OrchardZSA Protocol. + Specification: Issue Note, Issuance Action, Issuance Bundle and Issuance Protocol ================================================================================= @@ -287,8 +304,7 @@ Issuance Action An issuance action, ``IssueAction``, is the instance of issuing a specific Custom Asset, and contains the following fields: -- ``assetDescSize``: the size of the Asset description, a non-zero number that is at most $512$. -- ``asset_desc``: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. +- ``assetDescHash``: the hash of the Asset description, as defined in the `ZIP 227 Asset Identifiers`_ section. - ``vNotes``: an array of Issue Notes containing the unencrypted output notes to the recipients of the Asset. - ``flagsIssuance``: a byte that stores the $\mathsf{finalize}$ boolean that defines whether the issuance of that specific Custom Asset is finalized or not. @@ -337,8 +353,8 @@ The issuer program performs the following operations: For all actions ``IssueAction``: - encode $\mathsf{asset\_desc}$ as a UTF-8 byte string. -- compute $\mathsf{AssetDescHash}$ -- compute $\mathsf{AssetDigest}$ from the issuance validating key $\mathsf{ik}$ and $\mathsf{AssetDescHash}$ as decribed in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. +- compute $\mathsf{assetDescHash}$ +- compute $\mathsf{AssetDigest}$ from the issuance validating key $\mathsf{ik}$ and $\mathsf{assetDescHash}$ as decribed in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. - compute $\mathsf{AssetBase}$ from $\mathsf{AssetDigest}$ as decribed in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. - set the $\mathsf{finalize}$ boolean as desired (if more issuance actions are to be created for this $\mathsf{AssetBase}$, set $\mathsf{finalize} = 0$, otherwise set $\mathsf{finalize} = 1$). - for each recipient $i$: @@ -541,7 +557,7 @@ A new issuance transaction digest algorithm is defined that constructs the subtr issuance_digest ├── issue_actions_digest │   ├── issue_notes_digest - │   ├── assetDescription + │   ├── assetDescHash │   └── flagsIssuance └── issuanceValidatingKey @@ -567,7 +583,7 @@ T.5a: issue_actions_digest A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:: T.5a.i : notes_digest (32-byte hash output) - T.5a.ii : assetDescription (field encoding bytes) + T.5a.ii : assetDescHash (32-byte hash output) T.5a.iii: flagsIssuance (1 byte) The personalization field of this hash is set to::