Skip to content

Rearrange the order of the Asset Identifier section in ZIP 227 #104

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

Merged
vivek-arte merged 5 commits into from
May 23, 2025
Merged

Rearrange the order of the Asset Identifier section in ZIP 227 #104

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
eb798a8
fixing some references to asset_desc that were not updated
vivek-arte Apr 22, 2025
10af615
adding RST and SVG files for rearrangement changes
vivek-arte Apr 22, 2025
a6790b3
adding sizes to the diagram in SVG
vivek-arte May 5, 2025
e060a23
adding PNG file
vivek-arte May 5, 2025
c3d0d07
adding HTML file
vivek-arte May 5, 2025
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
Binary file added rendered/assets/images/zip-0227-asset-identifier-relation-orchard-zsa.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
111 changes: 58 additions & 53 deletions rendered/zip-0227.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,58 +268,66 @@
</section>
</section>
<section id="specification-asset-identifier-asset-digest-and-asset-base"><h2><span class="section-heading">Specification: Asset Identifier, Asset Digest, and Asset Base</span><span class="section-anchor"> <a rel="bookmark" href="#specification-asset-identifier-asset-digest-and-asset-base"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>Every Asset has a globally-unique Asset Identifier, denoted
<span class="math">\(\mathsf{AssetId}\!\)</span>
. A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols.</p>
<p>From the Asset Identifier, we derive an Asset Digest</p>
<div class="math">\(\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})),\)</div>
<p>where
<span class="math">\(\mathsf{EncodeAssetId}(\mathsf{AssetId})\)</span>
is a canonical encoding scheme for the Asset Identifier.</p>
<p>From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset within each shielded protocol:</p>
<div class="math">\(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\)</div>
<p>This Asset Base is included in shielded notes within the shielded protocol.</p>
<p>The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:</p>
<p>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:</p>
<figure class="align-center" align="center">
<img width="600" src="assets/images/zip-0227-asset-identifier-relation.png" alt="" />
<figcaption>Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the OrchardZSA Protocol</figcaption>
<figcaption>Diagram relating the Asset Identifier, Asset Digest, and Asset Base.</figcaption>
</figure>
<p><strong>Note:</strong> To keep notations light and concise, we may omit
<span class="math">\(\mathsf{AssetId}\)</span>
(resp.
<span class="math">\(\mathsf{Protocol}\!\)</span>
) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.</p>
<section id="zip-227-asset-identifiers"><h3><span class="section-heading">ZIP 227 Asset Identifiers</span><span class="section-anchor"> <a rel="bookmark" href="#zip-227-asset-identifiers"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Assets issued using the protocol specified in this ZIP are scoped to the
<span class="math">\(\mathsf{ik}\)</span>
that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an asset description,
<span class="math">\(\mathsf{asset\_desc}\!\)</span>
, which includes any information pertaining to the issuance.
<span class="math">\(\mathsf{asset\_desc}\)</span>
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.</p>
<p>Define</p>
<div class="math">\(\mathsf{AssetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}),\)</div>
<p>We define Asset Identifiers for assets issued under this ZIP as</p>
<div class="math">\(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{AssetDescHash})\)</div>
<p>and define their canonical encoding as</p>
<div class="math">\(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{AssetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{AssetDescHash}\)</div>
<p>Note that the initial
<span class="math">\(\mathtt{0x00}\)</span>
byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers.</p>
<p>Wallets MUST NOT display just the
<span class="math">\(\mathsf{asset\_desc}\)</span>
string to their users as the name of the Asset. Some possible alternatives include:</p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
in the subscript when the Asset Identifier is clear from the context.</p>
<section id="asset-identifiers"><h3><span class="section-heading">Asset Identifiers</span><span class="section-anchor"> <a rel="bookmark" href="#asset-identifiers"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Every Asset has a globally-unique Asset Identifier, denoted
<span class="math">\(\mathsf{AssetId}\!\)</span>
. A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols.</p>
<section id="zip-227-asset-identifiers"><h4><span class="section-heading">ZIP 227 Asset Identifiers</span><span class="section-anchor"> <a rel="bookmark" href="#zip-227-asset-identifiers"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h4>
<p>Assets issued using the protocol specified in this ZIP are scoped to the
<span class="math">\(\mathsf{ik}\)</span>
that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an asset description,
<span class="math">\(\mathsf{asset\_desc}\!\)</span>
, which includes any information pertaining to the issuance.
<span class="math">\(\mathsf{asset\_desc}\)</span>
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.</p>
<p>Define</p>
<div class="math">\(\mathsf{assetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}),\)</div>
<p>We define Asset Identifiers for Assets issued under this ZIP as</p>
<div class="math">\(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{assetDescHash})\)</div>
<p>and define their canonical encoding as</p>
<div class="math">\(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{assetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{assetDescHash}\)</div>
<p>Note that the initial
<span class="math">\(\mathtt{0x00}\)</span>
byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers.</p>
<p>Wallets MUST NOT display just the
<span class="math">\(\mathsf{asset\_desc}\)</span>
string to their users as the name of the Asset. Some possible alternatives include:</p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
</section>
</section>
<section id="orchardzsa-custom-assets"><h3><span class="section-heading">OrchardZSA Custom Assets</span><span class="section-anchor"> <a rel="bookmark" href="#orchardzsa-custom-assets"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>In the case of the OrchardZSA protocol, we define</p>
<div class="math">\(\mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}})\)</div>
<section id="asset-digests"><h3><span class="section-heading">Asset Digests</span><span class="section-anchor"> <a rel="bookmark" href="#asset-digests"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>From the Asset Identifier, we derive an Asset Digest</p>
<div class="math">\(\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})),\)</div>
<p>where
<span class="math">\(\mathsf{GroupHash}^\mathbb{P}\)</span>
is defined as in <a id="footnote-reference-21" class="footnote_reference" href="#protocol-concretegrouphashpallasandvesta">31</a>.</p>
<span class="math">\(\mathsf{EncodeAssetId}(\mathsf{AssetId})\)</span>
is the canonical encoding scheme for the Asset Identifier.</p>
</section>
<section id="asset-bases"><h3><span class="section-heading">Asset Bases</span><span class="section-anchor"> <a rel="bookmark" href="#asset-bases"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset within each shielded protocol:</p>
<div class="math">\(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\)</div>
<p>This Asset Base is included in shielded notes within the shielded protocol.</p>
<section id="orchardzsa-asset-bases"><h4><span class="section-heading">OrchardZSA Asset Bases</span><span class="section-anchor"> <a rel="bookmark" href="#orchardzsa-asset-bases"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h4>
<p>In the case of the OrchardZSA protocol, we define</p>
<div class="math">\(\mathsf{ZSAValueBase}(\mathsf{AssetDigest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest})\)</div>
<p>where
<span class="math">\(\mathsf{GroupHash}^\mathbb{P}\)</span>
is defined as in <a id="footnote-reference-21" class="footnote_reference" href="#protocol-concretegrouphashpallasandvesta">31</a>.</p>
<figure class="align-center" align="center">
<img width="800" src="assets/images/zip-0227-asset-identifier-relation-orchard-zsa.png" alt="" />
<figcaption>Diagram relating the Issuance validating key, asset description, asset description hash, Asset Identifier, Asset Digest, and Asset Base for the OrchardZSA Protocol.</figcaption>
</figure>
</section>
</section>
</section>
<section id="specification-issue-note-issuance-action-issuance-bundle-and-issuance-protocol"><h2><span class="section-heading">Specification: Issue Note, Issuance Action, Issuance Bundle and Issuance Protocol</span><span class="section-anchor"> <a rel="bookmark" href="#specification-issue-note-issuance-action-issuance-bundle-and-issuance-protocol"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
Expand Down Expand Up @@ -361,10 +369,7 @@
<section id="issuance-action"><h3><span class="section-heading">Issuance Action</span><span class="section-anchor"> <a rel="bookmark" href="#issuance-action"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>An issuance action, <code>IssueAction</code>, is the instance of issuing a specific Custom Asset, and contains the following fields:</p>
<ul>
<li><code>assetDescSize</code>: the size of the Asset description, a non-zero number that is at most
<span class="math">\(512\!\)</span>
.</li>
<li><code>asset_desc</code>: the Asset description, a byte string of up to 512 bytes as defined in the <a href="#specification-asset-identifier-asset-digest-and-asset-base">Specification: Asset Identifier, Asset Digest, and Asset Base</a> section.</li>
<li><code>assetDescHash</code>: the hash of the Asset description, as defined in the <a href="#zip-227-asset-identifiers">ZIP 227 Asset Identifiers</a> section.</li>
<li><code>vNotes</code>: an array of Issue Notes containing the unencrypted output notes to the recipients of the Asset.</li>
<li><code>flagsIssuance</code>: a byte that stores the
<span class="math">\(\mathsf{finalize}\)</span>
Expand Down Expand Up @@ -423,14 +428,14 @@
<span class="math">\(\mathsf{asset\_desc}\)</span>
as a UTF-8 byte string.</li>
<li>compute
<span class="math">\(\mathsf{AssetDescHash}\)</span>
<span class="math">\(\mathsf{assetDescHash}\)</span>
</li>
<li>compute
<span class="math">\(\mathsf{AssetDigest}\)</span>
from the issuance validating key
<span class="math">\(\mathsf{ik}\)</span>
and
<span class="math">\(\mathsf{AssetDescHash}\)</span>
<span class="math">\(\mathsf{assetDescHash}\)</span>
as decribed in the <a href="#specification-asset-identifier-asset-digest-and-asset-base">Specification: Asset Identifier, Asset Digest, and Asset Base</a> section.</li>
<li>compute
<span class="math">\(\mathsf{AssetBase}\)</span>
Expand Down Expand Up @@ -762,7 +767,7 @@
<pre>issuance_digest
├── issue_actions_digest
│   ├── issue_notes_digest
│   ├── assetDescription
│   ├── assetDescHash
│   └── flagsIssuance
└── issuanceValidatingKey</pre>
<p>In the specification below, nodes of the tree are presented in depth-first order.</p>
Expand All @@ -777,7 +782,7 @@
<section id="t-5a-issue-actions-digest"><h4><span class="section-heading">T.5a: issue_actions_digest</span><span class="section-anchor"> <a rel="bookmark" href="#t-5a-issue-actions-digest"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h4>
<p>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:</p>
<pre>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)</pre>
<p>The personalization field of this hash is set to:</p>
<pre>"ZTxIdIssuActHash"</pre>
Expand Down
Loading