Skip to content

Commit 06f63ca

Browse files
vivek-artevivek-arte
authored
Adding specification of derivation of the rho value in Issue Notes (#90)
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.
1 parent e8f628a commit 06f63ca

File tree

2 files changed

+89
-38
lines changed

2 files changed

+89
-38
lines changed

‎rendered/zip-0227.html

+55-21
Original file line numberDiff line numberDiff line change
@@ -359,9 +359,6 @@
359359
MUST be sampled uniformly at random by the issuer.</li>
360360
</ul>
361361
<p>The complete encoding of these fields into an <code>IssueNote</code> is defined in ZIP 230 <a id="footnote-reference-24" class="footnote_reference" href="#zip-0230-issue-note">16</a>.</p>
362-
<section id="computation-of"><h4><span class="section-heading">Computation of ρ</span><span class="section-anchor"> <a rel="bookmark" href="#computation-of"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h4>
363-
<p>TO BE FILLED</p>
364-
</section>
365362
</section>
366363
<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>
367364
<p>An issuance action, <code>IssueAction</code>, is the instance of issuing a specific Custom Asset, and contains the following fields:</p>
@@ -372,7 +369,7 @@
372369
<span class="math">\(512\!\)</span>
373370
.</li>
374371
<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">Specification: Asset Identifier</a> section.</li>
375-
<li><code>vNotes</code>: an array of <code>Note</code> containing the unencrypted output notes of the recipients of the Asset.</li>
372+
<li><code>vNotes</code>: an array of Issue Notes containing the unencrypted output notes to the recipients of the Asset.</li>
376373
<li><code>flagsIssuance</code>: a byte that stores the
377374
<span class="math">\(\mathsf{finalize}\)</span>
378375
boolean that defines whether the issuance of that specific Custom Asset is finalized or not.</li>
@@ -381,7 +378,7 @@
381378
<span class="math">\(\mathsf{finalize}\)</span>
382379
boolean is set by the Issuer to signal that there will be no further issuance of the specific Custom Asset. As we will see in <a href="#specification-consensus-rule-changes">Specification: Consensus Rule Changes</a>, transactions that attempt to issue further amounts of a Custom Asset that has previously been finalized will be rejected.</p>
383380
<p>The complete encoding of these fields into an <code>IssueAction</code> is defined in ZIP 230 <a id="footnote-reference-25" class="footnote_reference" href="#zip-0230-issuance-action-description">15</a>.</p>
384-
<p>We note that the output note commitment of the recipient's notes are not included in the actual transaction, but when added to the global state of the chain, they will be added to the note commitment tree as a shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.</p>
381+
<p>We note that when the issued note commitments are added to the global state of the chain, they will be added to the note commitment tree as any other shielded note. This prevents future usage of the note from being linked to the issuance transaction, as the nullifier key is not known to the validators and chain observers.</p>
385382
</section>
386383
<section id="issuance-bundle"><h3><span class="section-heading">Issuance Bundle</span><span class="section-anchor"> <a rel="bookmark" href="#issuance-bundle"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
387384
<p>An issuance bundle is the aggregate of all the issuance-related information. Specifically, contains all the issuance actions and the issuer signature on the transaction SIGHASH that validates the issuance itself. It contains the following fields:</p>
@@ -400,6 +397,36 @@
400397
</ul>
401398
<p>The issuance bundle is added within the transaction format as a new bundle. The detailed encoding of the issuance bundle as a part of the V6 transaction format is defined in ZIP 230 <a id="footnote-reference-26" class="footnote_reference" href="#zip-0230-transaction-format">17</a>.</p>
402399
</section>
400+
<section id="computation-of"><h3><span class="section-heading">Computation of ρ</span><span class="section-anchor"> <a rel="bookmark" href="#computation-of"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
401+
<p>We define a function
402+
<span class="math">\(\mathsf{DeriveIssuedRho} : \mathbb{F}_{q_{\mathbb{P}}} \times \{0 .. 2^{32} - 1\} \times \{0 .. 2^{32} - 1\} \to \mathbb{F}_{q_{\mathbb{P}}}\)</span>
403+
as follows:</p>
404+
<div class="math">\(\mathsf{DeriveIssuedRho}(\mathsf{nf}, \mathsf{i_{A}}, \mathsf{i_{N}}) := \mathsf{ToBase}^{\mathsf{Rho}}(\mathsf{PRF}^{\mathsf{Rho}}(\mathsf{I2LEOSP}_{256}(\mathsf{nf}), [\mathtt{0x84}] \| \mathsf{I2LEOSP}_{32}(\mathsf{i_{A}}) \| \mathsf{I2LEOSP}_{32}(\mathsf{i_{N}}))),\)</div>
405+
<p>where</p>
406+
<ul>
407+
<li>
408+
<span class="math">\(\mathsf{ToBase}^{\mathsf{Rho}} : \mathbb{B}^{512} \to \mathbb{F}_{q_{\mathbb{P}}}\)</span>
409+
is defined as
410+
<span class="math">\(\mathsf{ToBase}^{\mathsf{Rho}}(x) := \mathsf{LEOS2IP}_{512}(x) \mod q_{\mathbb{P}}\)</span>
411+
</li>
412+
<li>
413+
<span class="math">\(\mathsf{PRF}^{\mathsf{Rho}} : \mathbb{B}^{256} \times \mathbb{B}^{\mathbb{Y}^{[\mathbb{N}]}} \to \mathbb{B}^{512}\)</span>
414+
is defined as
415+
<span class="math">\(\mathsf{PRF}^{\mathsf{Rho}}(\mathsf{k},t) := \textsf{BLAKE2b-512}(\mathtt{"ZSA\_IssueNoteRho"}, \mathsf{LEBS2OSP}_{256}(\mathsf{k}) \| t)\)</span>
416+
</li>
417+
</ul>
418+
<p>The
419+
<span class="math">\(\text{ρ}\)</span>
420+
field of an Issue Note is computed as</p>
421+
<div class="math">\(\text{ρ} := \mathsf{DeriveIssuedRho}(\mathsf{nf}_{1,1}, \mathsf{index_{Action}}, \mathsf{index_{Note}}),\)</div>
422+
<p>where
423+
<span class="math">\(\mathsf{nf}_{1,1}\)</span>
424+
is the nullifier of the first Note in the first Action of the OrchardZSA Bundle of the transaction,
425+
<span class="math">\(\mathsf{index_{Action}}\)</span>
426+
is the index of the Issuance Action in the Issuance Bundle, and
427+
<span class="math">\(\mathsf{index_{Note}}\)</span>
428+
is the index of the Issue Note in the Issuance Action.</p>
429+
</section>
403430
<section id="issuance-protocol"><h3><span class="section-heading">Issuance Protocol</span><span class="section-anchor"> <a rel="bookmark" href="#issuance-protocol"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
404431
<p>The issuer program performs the following operations:</p>
405432
<p>For all actions <code>IssueAction</code>:</p>
@@ -432,9 +459,12 @@
432459
<span class="math">\(i\!\)</span>
433460
:
434461
<ul>
435-
<li>generate a ZSA output note that includes the Asset Base. For an OrchardZSA note this is
436-
<span class="math">\(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \text{ρ}_i, \mathsf{rseed}_i, \mathsf{AssetBase}, \mathsf{rcm}_i)\!\)</span>
462+
<li>generate an Issue Note,
463+
<span class="math">\(\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d}_i}, \mathsf{v}_i, \mathsf{AssetBase}, \text{ρ}_i, \mathsf{rseed}_i)\!\)</span>
437464
.</li>
465+
<li>encode the
466+
<span class="math">\(\mathsf{note}_i\)</span>
467+
into the vector <code>vNotes</code> of the <code>IssueAction</code>.</li>
438468
</ul>
439469
</li>
440470
<li>encode the <code>IssueAction</code> into the vector <code>vIssueActions</code> of the bundle.</li>
@@ -463,33 +493,33 @@
463493
, to a tuple
464494
<span class="math">\((\mathsf{balance}, \mathsf{final})\!\)</span>
465495
, for every Asset that has been issued. We use the notation
466-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{balance}\)</span>
496+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{balance}\)</span>
467497
and
468-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{final}\)</span>
498+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{final}\)</span>
469499
to access, respectively, the elements of the tuple stored in the global state for a given
470500
<span class="math">\(\mathsf{AssetBase}\!\)</span>
471501
. If
472502
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}) = \bot\!\)</span>
473503
, it is assumed that
474-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{balance} = 0\)</span>
504+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{balance} = 0\)</span>
475505
and
476-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{final} = 0\!\)</span>
506+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{final} = 0\!\)</span>
477507
.</p>
478508
<p>For any Asset represented by
479509
<span class="math">\(\mathsf{AssetBase}\!\)</span>
480510
:</p>
481511
<ul>
482512
<li>
483-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{balance} \in \{0 .. \mathsf{MAX\_ISSUE}\}\)</span>
513+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{balance} \in \{0 .. \mathsf{MAX\_ISSUE}\}\)</span>
484514
stores the amount of the Asset in circulation, computed as the amount of the Asset that has been issued less the amount of the Asset that has been burnt.</li>
485515
<li>
486-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{final} : \mathbb{B}\)</span>
516+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{final} : \mathbb{B}\)</span>
487517
is a Boolean that stores the finalization status of the Asset (i.e.: whether the
488518
<span class="math">\(\mathsf{finalize}\)</span>
489519
flag has been set to
490520
<span class="math">\(1\)</span>
491521
in any preceding issuance transaction for the Asset). The value of
492-
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\!\mathsf{final}\)</span>
522+
<span class="math">\(\mathsf{issued\_assets}(\mathsf{AssetBase}).\mathsf{final}\)</span>
493523
for any
494524
<span class="math">\(\mathsf{AssetBase}\)</span>
495525
cannot be changed from
@@ -530,19 +560,20 @@
530560
<li>It MUST be the case that for all
531561
<span class="math">\((\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}\!\)</span>
532562
,
533-
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\!\mathsf{balance} \geq \mathsf{v}\!\)</span>
563+
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\mathsf{balance} \geq \mathsf{v}\!\)</span>
534564
. The node then MUST update
535565
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase})\)</span>
536566
prior to processing the issuance bundle in the following manner. For every
537567
<span class="math">\((\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{AssetBurn}\!\)</span>
538568
,
539-
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\!\mathsf{balance} = \mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\!\mathsf{balance} - \mathsf{v}\!\)</span>
569+
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\mathsf{balance} = \mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\mathsf{balance} - \mathsf{v}\!\)</span>
540570
.</li>
541571
<li>Let
542572
<span class="math">\(\mathsf{SigHash}\)</span>
543573
be the SIGHASH transaction hash of this transaction, as defined in §4.10 of the protocol specification <a id="footnote-reference-28" class="footnote_reference" href="#protocol-sighash">28</a> with the modifications described in ZIP 226 <a id="footnote-reference-29" class="footnote_reference" href="#zip-0226-txiddigest">13</a>, using
544574
<span class="math">\(\mathsf{SIGHASH\_ALL}\!\)</span>
545575
.</li>
576+
<li>If the transaction contains an Issuance Bundle, it MUST also contain at least one OrchardZSA Action.</li>
546577
<li>The issuance authorization signature,
547578
<span class="math">\(\mathsf{issueAuthSig}\!\)</span>
548579
, MUST be a valid
@@ -564,27 +595,30 @@
564595
is a string of length
565596
<span class="math">\(\mathtt{assetDescSize}\)</span>
566597
bytes.</li>
567-
<li>Elements of every issue note description in <code>IssueAction</code> MUST be valid encodings of the types given in <a href="#issue-note">Issue Note</a>, and MUST encode the same
598+
<li>Elements of every Issue Note in <code>IssueAction</code> MUST be valid encodings of the types given in the <a href="#issue-note">Issue Note</a> section, and MUST encode the same
568599
<span class="math">\(\mathsf{AssetBase}\!\)</span>
569600
.</li>
570601
<li>This
571602
<span class="math">\(\mathsf{AssetBase}\)</span>
572603
MUST satisfy the derivation from the issuance validating key and asset description described in the <a href="#specification-asset-identifier">Specification: Asset Identifier</a> section.</li>
573604
<li>It MUST be the case that
574-
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\!\mathsf{final} \neq 1\!\)</span>
605+
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\mathsf{final} \neq 1\!\)</span>
575606
.</li>
576607
<li>For every issue note description (
577608
<span class="math">\(\mathsf{note}_{\mathsf{j}},\ 1 \leq j \leq \mathtt{nNotes}\!\)</span>
578609
) in <code>IssueAction</code>:
579610
<ul>
611+
<li>The
612+
<span class="math">\(\text{ρ}\)</span>
613+
field of the issue note MUST have been computed as described in the <a href="#computation-of">Computation of ρ</a> section.</li>
580614
<li>It MUST be the case that
581-
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}.\!\mathsf{balance} + \mathsf{v} \leq \mathsf{MAX\_ISSUE}\!\)</span>
615+
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}.\mathsf{balance} + \mathsf{v} \leq \mathsf{MAX\_ISSUE}\!\)</span>
582616
, where
583617
<span class="math">\(\mathsf{v}\)</span>
584618
is the value of
585619
<span class="math">\(\mathsf{note}_{\mathsf{j}}\!\)</span>
586620
. The node then MUST update
587-
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}.\!\mathsf{balance} = \mathsf{issued\_assets}_{\mathsf{OUT}}.\!\mathsf{balance} + \mathsf{v}\!\)</span>
621+
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}.\mathsf{balance} = \mathsf{issued\_assets}_{\mathsf{OUT}}.\mathsf{balance} + \mathsf{v}\!\)</span>
588622
.</li>
589623
<li>The node MUST compute the note commitment,
590624
<span class="math">\(\mathsf{cm}_{\mathsf{i,j}}\!\)</span>
@@ -594,7 +628,7 @@
594628
<li>If
595629
<span class="math">\(\mathsf{finalize} = 1\)</span>
596630
within the <code>flagsIssuance</code> field of <code>IssueAction</code>, the node MUST set
597-
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\!\mathsf{final} = 1\!\)</span>
631+
<span class="math">\(\mathsf{issued\_assets}_{\mathsf{OUT}}(\mathsf{AssetBase}).\mathsf{final} = 1\!\)</span>
598632
.</li>
599633
</ul>
600634
</li>

0 commit comments

Comments
 (0)