Skip to content
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

Shifting the OrchardZSA fee specification from ZIP 230 to ZIP 227 #86

Merged
merged 11 commits into from
Dec 17, 2024
Merged

Shifting the OrchardZSA fee specification from ZIP 230 to ZIP 227 #86

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b1e0d11
adding description of nAGExpiryHeight field
vivek-arte Nov 12, 2024
288c170
updates based on PR review
vivek-arte Nov 14, 2024
6537270
adding missing orchard_action_groups_digest personalization
vivek-arte Nov 19, 2024
bdda798
adding MAX_ISSUE constant and updating notation
vivek-arte Nov 14, 2024
12bf787
rearrange location of global issuance state specification
vivek-arte Nov 20, 2024
a792384
consensus rule section rewrite
vivek-arte Nov 21, 2024
4ce93d7
removing duplicate lines
vivek-arte Nov 28, 2024
bf7cde2
Fixing the specification of the digests due to the introduction of Ac…
vivek-arte Dec 2, 2024
076eb81
responding to review comments
vivek-arte Dec 11, 2024
b931b8d
shifting material on OrchardZSA fees from ZIP 230 to ZIP 227
vivek-arte Dec 12, 2024
5efcb5d
Merge branch 'zsa1' into move_fees_to_zip_227
vivek-arte Dec 17, 2024
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
206 changes: 123 additions & 83 deletions rendered/zip-0226.html
View file
Open in desktop

Large diffs are not rendered by default.

449 changes: 299 additions & 150 deletions rendered/zip-0227.html
View file
Open in desktop

Large diffs are not rendered by default.

83 changes: 0 additions & 83 deletions rendered/zip-0230.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -661,89 +661,6 @@
</table>
</section>
</section>
<section id="orchardzsa-fee-calculation"><h2><span class="section-heading">OrchardZSA Fee Calculation</span><span class="section-anchor"> <a rel="bookmark" href="#orchardzsa-fee-calculation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>In addition to the parameters defined in the Fee calculation section of ZIP 317 <a id="footnote-reference-23" class="footnote_reference" href="#zip-0317-fee-calc">13</a>, the OrchardZSA protocol upgrade defines the following additional parameters:</p>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<span class="math">\(issuance\_fee\)</span>
</td>
<td>
<span class="math">\(100 \cdot marginal\_fee\)</span>
per issuance action (as defined below)</td>
</tr>
</tbody>
</table>
<p>Wallets implementing this specification SHOULD use a conventional fee, viz.
<span class="math">\(zsa\_conventional\_fee\)</span>
, that is calculated in zatoshis. Additional definitions that are used in the formula for the calculation are in the table below:</p>
<table>
<thead>
<tr>
<th>Input</th>
<th>Units</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<span class="math">\(nOrchardActions\)</span>
</td>
<td>number</td>
<td>the number of OrchardZSA transfer actions (including ZEC actions)</td>
</tr>
<tr>
<td>
<span class="math">\(nTotalOutputsZSAIssuance\)</span>
</td>
<td>number</td>
<td>the total number of OrchardZSA issuance outputs (added across issuance actions)</td>
</tr>
<tr>
<td>
<span class="math">\(nCreateActions\)</span>
</td>
<td>number</td>
<td>the number of OrchardZSA issuance actions that issue a Custom Asset that is not present in the Global Issuance State</td>
</tr>
</tbody>
</table>
<p>The other inputs to this formula are taken from transaction fields defined in the Zcash protocol specification <a id="footnote-reference-24" class="footnote_reference" href="#protocol-txnencoding">6</a> and the global state. They are defined in the Fee calculation section of ZIP 317 <a id="footnote-reference-25" class="footnote_reference" href="#zip-0317-fee-calc">13</a>. Note that
<span class="math">\(nOrchardActions\)</span>
, that is used in the computation of
<span class="math">\(logical\_actions\)</span>
, is redefined in the above table, and now combines the actions for native ZEC as well as OrchardZSA transfer actions for Custom Assets.</p>
<p>The formula for the computation of the
<span class="math">\(zsa\_logical\_actions\)</span>
(with the updated computation of
<span class="math">\(logical\_actions\)</span>
as described above) is:</p>
<div class="math">\(zsa\_logical\_actions = logical\_actions \;+ nTotalOutputsZSAIssuance\)</div>
<p>The formula for the computation of the
<span class="math">\(zsa\_conventional\_fee\)</span>
is:</p>
<div class="math">\(\begin{array}{rcl}
zsa\_conventional\_fee &amp;=&amp; marginal\_fee \cdot \mathsf{max}(grace\_actions, zsa\_logical\_actions) \;+ \\
&amp; &amp; issuance\_fee \cdot nCreateActions
\end{array}\)</div>
<p>It is not a consensus requirement that fees follow this formula; however, wallets SHOULD create transactions that pay this fee, in order to reduce information leakage, unless overridden by the user.</p>
<section id="rationale-for-orchardzsa-fee-calculation"><h3><span class="section-heading">Rationale for OrchardZSA Fee calculation</span><span class="section-anchor"> <a rel="bookmark" href="#rationale-for-orchardzsa-fee-calculation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The OrchardZSA fee calculation accounts for the additions to the Global Issuance State that are required for the OrchardZSA protocol. Every newly created Custom Asset adds a new row to the Global Issuance State. Subsequent issuance, finalization, or burn of existing Custom Assets only changes the values in the corresponding row.</p>
<p>This explains the need for a higher fee for the creation of entirely new Custom Assets, in order to disincentivize the creation of "junk" assets.</p>
</section>
<section id="orchardzsa-fee-considerations"><h3><span class="section-heading">OrchardZSA Fee Considerations</span><span class="section-anchor"> <a rel="bookmark" href="#orchardzsa-fee-considerations"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>We choose to maintain the native ZEC Asset as the primary token for the Zcash blockchain, similar to how ETH is needed for ERC20 transactions to the benefit of the Ethereum ecosystem.</p>
<p>An alternative proposal for the OrchardZSA fee mechanism that was not adopted was to adopt a new type of fee, denominated in the custom Asset being issued or transferred. In the context of transparent transactions, such a fee allows miners to “tap into” the ZSA value of the transactions, rather than the ZEC value of transactions. However when transactions are shielded, any design that lifts value from the transaction would also leak information about it.</p>
</section>
</section>
<section id="reference-implementation"><h2><span class="section-heading">Reference implementation</span><span class="section-anchor"> <a rel="bookmark" href="#reference-implementation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>TODO</p>
</section>
Expand Down
96 changes: 80 additions & 16 deletions zips/zip-0226.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ The burn mechanism is a transparent extension to the transfer protocol that enab
The burn mechanism does NOT send Assets to a non-spendable address, it simply reduces the total number of units of a given Custom Asset in circulation.
It is enforced at the consensus level, by using an extension of the value balance mechanism used for ZEC Assets.
Burning makes it globally provable that a given amount of a Custom Asset has been destroyed.
Note that the OrchardZSA Protocol does not allow for the burning of ZEC (or TAZ).
Note that the OrchardZSA Protocol does not allow for the burning of the Native Asset (i.e. ZEC or TAZ).

In the `OrchardZSA Transaction Structure`_, there is now an :math:`\mathsf{assetBurn}` set.
For every Custom Asset (represented by its :math:`\mathsf{AssetBase}\!`) that is burnt in the transaction, the sender adds to :math:`\mathsf{assetBurn}` the tuple :math:`(\mathsf{AssetBase}, \mathsf{v})`, where :math:`\mathsf{v}` is the amount of the Custom Asset the sender wants to burn.
Expand All @@ -181,17 +181,17 @@ We denote by :math:`L` the cardinality of the :math:`\mathsf{assetBurn}` set in
As described in `Value Balance Verification`_, this provides the information for the validator of the transaction to compute the value commitment with the corresponding Asset Base.
This ensures that the values are all balanced out on a per-Asset basis in the transaction.

Additional Consensus Rules
``````````````````````````
Additional Consensus Rules for the assetBurn set
````````````````````````````````````````````````

1. Check that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}, \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}\!`. That is, ZEC or TAZ is not allowed to be burnt by this mechanism.
2. Check that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}, \mathsf{v} \neq 0\!`.
3. Check that there is no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}` has at most one entry in :math:`\mathsf{assetBurn}\!`.
4. Check that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}\!`, :math:`\mathsf{v} \leq \mathsf{issued\_assets(AssetBase).balance}\!`, where the map :math:`\mathsf{issued\_assets}` is defined in ZIP 227 [#zip-0227-specification-global-issuance-state]_. That is, it is not possible to burn more of an Asset than is currently in circulation.
1. It MUST be the case that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}, \mathsf{AssetBase} \neq \mathcal{V}^{\mathsf{Orchard}}\!`. That is, the Native Asset is not allowed to be burnt by this mechanism.
2. It MUST be that for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}, \mathsf{v} \neq 0\!`.
3. There MUST be no duplication of Custom Assets in the :math:`\mathsf{assetBurn}` set. That is, every :math:`\mathsf{AssetBase}` has at most one entry in :math:`\mathsf{assetBurn}\!`.

If all these checks pass, then for every :math:`(\mathsf{AssetBase}, \mathsf{v}) \in \mathsf{assetBurn}\!`, reduce the value of :math:`\mathsf{issued\_assets(AssetBase).balance}` in the global state by :math:`\mathsf{v}\!`.
The other consensus rule changes for the OrchardZSA protocol are specified in ZIP 227 [#zip-0227-consensus]_.

**Note:** Even if this mechanism allows having transparent ↔ shielded Asset transfers in theory, the transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure. This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.
**Note:** The transparent protocol will not be changed with this ZIP to adapt to a multiple Asset structure.
This means that unless future consensus rules changes do allow it, unshielding will not be possible for Custom Assets.

Value Balance Verification
--------------------------
Expand Down Expand Up @@ -383,7 +383,7 @@ T.4a.i: orchard_actions_compact_digest

A BLAKE2b-256 hash of the subset of OrchardZSA Action information intended to be included in
an updated version of the ZIP-307 [#zip-0307]_ ``CompactBlock`` format for all OrchardZSA
Actions belonging to the transaction. For each Action, the following elements are included
Actions belonging to the Action Group. For each Action, the following elements are included
in the hash::

T.4a.i.1 : nullifier (field encoding bytes)
Expand All @@ -400,7 +400,7 @@ T.4a.ii: orchard_actions_memos_digest
.....................................

A BLAKE2b-256 hash of the subset of Orchard shielded memo field data for all OrchardZSA
Actions belonging to the transaction. For each Action, the following elements are included
Actions belonging to the Action Group. For each Action, the following elements are included
in the hash::

T.4a.ii.1: encCiphertext[84..596] (contents of the encrypted memo field) [UPDATED FOR ZSA]
Expand All @@ -415,7 +415,7 @@ T.4a.iii: orchard_actions_noncompact_digest

A BLAKE2b-256 hash of the remaining subset of OrchardZSA Action information **not** intended
for inclusion in an updated version of the the ZIP 307 [#zip-0307]_ ``CompactBlock``
format, for all OrchardZSA Actions belonging to the transaction. For each Action,
format, for all OrchardZSA Actions belonging to the Action Group. For each Action,
the following elements are included in the hash::

T.4a.iii.1 : cv (field encoding bytes)
Expand Down Expand Up @@ -461,10 +461,72 @@ T.5: issuance_digest
````````````````````
The details of the computation of this value are in ZIP 227 [#zip-0227-txiddigest]_.

Signature Digest and Authorizing Data Commitment
================================================
Signature Digest
================

The details of the changes to this algorithm are in ZIP 227 [#zip-0227-sigdigest]_.

Authorizing Data Commitment
===========================

The transaction digest algorithm defined in ZIP 244 [#zip-0244-authcommitment]_ which commits to the authorizing data of a transaction is modified by the OrchardZSA protocol to have the structure specified in this section.
There is a new branch added for issuance information, along with modifications within the ``orchard_auth_digest`` to account for the presence of Action Groups.

We highlight the changes for the OrchardZSA protocol via the ``[UPDATED FOR ZSA]`` or ``[ADDED FOR ZSA]`` text label, and we omit the descriptions of the sections that do not change for the OrchardZSA protocol::

auth_digest
├── transparent_scripts_digest
├── sapling_auth_digest
├── orchard_auth_digest [UPDATED FOR ZSA]
└── issuance_auth_digest [ADDED FOR ZSA]

The pair (Transaction Identifier, Auth Commitment) constitutes a commitment to all the data of a serialized transaction that may be included in a block.

auth_digest
-----------
A BLAKE2b-256 hash of the following values ::

A.1: transparent_scripts_digest (32-byte hash output)
A.2: sapling_auth_digest (32-byte hash output)
A.3: orchard_auth_digest (32-byte hash output) [UPDATED FOR ZSA]
A.4: issuance_auth_digest (32-byte hash output) [ADDED FOR ZSA]

The personalization field of this hash remains the same as in ZIP 244.


A.3: orchard_auth_digest
````````````````````````

In the case that OrchardZSA Action Groups are present, this is a BLAKE2b-256 hash of the following values::

A.3a: orchard_action_groups_auth_digest (32-byte hash output) [ADDED FOR ZSA]
A.3b: bindingSigOrchard (field encoding bytes)

The personalization field of this hash is the same as in ZIP 244, that is::

"ZTxAuthOrchaHash"

In case that the transaction has no OrchardZSA Action Groups, ``orchard_auth_digest`` is::

BLAKE2b-256("ZTxAuthOrchaHash", [])

A.3a: orchard_action_groups_auth_digest
'''''''''''''''''''''''''''''''''''''''

This is a BLAKE2b-256 hash of the ``proofsOrchard`` and ``spendAuthSigsOrchard`` fields of all OrchardZSA Action Groups belonging to the transaction::

A.3a.i: proofsOrchard (field encoding bytes)
A.3a.ii: spendAuthSigsOrchard (field encoding bytes)

The personalization field of this hash is set to::

"ZTxAuthOrcAGHash"

A.4: issuance_auth_digest
`````````````````````````

The details of the computation of this value are in ZIP 227 [#zip-0227-authcommitment]_.

The details of the changes to these algorithms are in ZIP 227 [#zip-0227-sigdigest]_ [#zip-0227-authcommitment]_.

Security and Privacy Considerations
===================================
Expand Down Expand Up @@ -520,12 +582,14 @@ References
.. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets <zip-0227.html>`_
.. [#zip-0227-specification-global-issuance-state] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Global Issuance State <zip-0227.html#specification-global-issuance-state>`_
.. [#zip-0227-assetidentifier] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Asset Identifier <zip-0227.html#specification-asset-identifier>`_
.. [#zip-0227-consensus] `ZIP 227: Issuance of Zcash Shielded Assets: Specification: Consensus Rule Changes <zip-0227.html#specification-consensus-rule-changes>`_
.. [#zip-0227-txiddigest] `ZIP 227: Issuance of Zcash Shielded Assets: TxId Digest - Issuance <zip-0227.html#txid-digest-issuance>`_
.. [#zip-0227-sigdigest] `ZIP 227: Issuance of Zcash Shielded Assets: Signature Digest <zip-0227.html#signature-digest>`_
.. [#zip-0227-authcommitment] `ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment <zip-0227.html#authorizing-data-commitment>`_
.. [#zip-0227-authcommitment] `ZIP 227: Issuance of Zcash Shielded Assets: Authorizing Data Commitment <zip-0227.html#authorizing-data-commitment-issuance>`_
.. [#zip-0230] `ZIP 230: Version 6 Transaction Format <zip-0230.html>`_
.. [#zip-0230-orchardzsa-fee-calculation] `ZIP 230: Version 6 Transaction Format: OrchardZSA Fee Calculation <zip-0230.html#orchardzsa-fee-calculation>`_
.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability <zip-0244.html>`_
.. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment <zip-0244.html#authorizing-data-commitment>`_
.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection <zip-0307.rst>`_
.. [#protocol-notes] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.2: Notes <protocol/protocol.pdf#notes>`_
.. [#protocol-actions] `Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 3.7: Action Transfers and their Descriptions <protocol/protocol.pdf#actions>`_
Expand Down
Loading