From ff385b89956f9f659990ff694e9adcb89498bc9f Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Tue, 7 Mar 2023 12:27:47 +0530 Subject: [PATCH 1/3] changes to issuance_txid_digest to align with ZIP 244 --- zip-0227.html | 103 +++++++++++++++++++++++++++++++------------------- zip-0227.rst | 60 +++++++++++++++++++---------- 2 files changed, 104 insertions(+), 59 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 2c42ecc04..09a82a88e 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -64,7 +64,7 @@

Specification

As explained, the issuance protocol allows for a single issuance action to be sent to many receivers, by generating as many output notes as distinct recipients. Furthermore, every bundle can contain many issuance actions.

Issuance Keys and Issuance Authorization Signature Scheme

-

The ZSA Protocol adds the following three keys to the key components 11:

+

The ZSA Protocol adds the following three keys to the key components 12:

  1. The issuance master key, denoted as \(\mathsf{sk}_{\mathsf{iss}}\) @@ -81,7 +81,7 @@ \(\mathsf{IssueAuthSig}\) similar to \(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\) - , the Orchard spend authorization signature scheme 15. Specifically, we instantiate + , the Orchard spend authorization signature scheme 16. Specifically, we instantiate \(\mathsf{IssueAuthSig}\) as \(\mathsf{RedPallas}\) @@ -89,18 +89,18 @@ \(\mathcal{P}_{\mathbb{G}} = \mathcal{G}^{\mathsf{Issuance}} := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:ZSA"}, \texttt{"Issuance"})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in the Zcash protocol specification 12.

    + is defined as in the Zcash protocol specification 13.

Issuance Key Derivation

The issuance master key is generated by choosing a bit sequence uniformly at random from \(\mathbb{B}^{\mathbb{Y}[32]}\) - , like the Orchard spending key 13. In + , like the Orchard spending key 14. In \(\mathsf{zcashd}\) - , this key is derived in a manner similar to the generation of the Orchard master key in ZIP 32 9, as detailed below:

+ , this key is derived in a manner similar to the generation of the Orchard master key in ZIP 32 10, as detailed below:

  • Details TBD
-

The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 13, as described below.

+

The issuance authorizing key and issuance validating key are derived from the issuance master key in an analogous manner to the derivation of the Orchard spend authorizing key and Orchard spend validating key from the Orchard spending key 14, as described below.

  • The issuance authorizing key is derived from the issuance master key, \(\mathsf{sk}_{\mathsf{iss}}\) @@ -113,7 +113,7 @@ , as a public verification key:
\(\mathsf{ik} := \mathsf{IssueAuthSig}.\mathsf{DerivePublic}(\mathsf{isk})\)
-

This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 8. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

+

This allows the issuer to use the same wallet it usually uses to transfer Assets, while keeping a disconnect from the other keys. Specifically, this method is aligned with the requirements and motivation of ZIP 32 9. It provides further anonymity and the ability to delegate issuance of an Asset (or in the future, generate a multi-signature protocol) while the rest of the keys remain in the wallet safe.

The derivation of these keys are shown in the following diagram:

@@ -160,7 +160,7 @@ \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\) where \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 12.

+ is defined as in 13.

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

@@ -250,7 +250,7 @@ \(\mathsf{isk}\) , that validates the issuance . -

The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 16.

+

The issuance bundle is then added within the transaction format as a new bundle. That is, issuance requires the addition of the following information to the transaction format 18.

@@ -419,31 +419,38 @@

TxId Digest

-

A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

+

As in ZIP 244 7, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used.

+

A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

issuance_txid_digest
-├── issueActions
+├── issue_actions_digest
 └── issuerVerificationKey

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

issuance_txid_digest

A BLAKE2b-256 hash of the following values

- 
T.1: issueActions            (field encoding bytes)
-T.2: issuerVerificationKey   (field encoding bytes)
+ 
T.1: issue_actions_digest    (32-byte hash output)
+T.2: issuanceValidatingKey   (32 bytes)

The personalization field of this hash is set to:

- 
"ZTxIdOrcZSAIssue"
-

T.1 issueActions

-

A byte encoding of Issue Action information for all Issue Actions belonging to the transaction. For each Action, the following elements are included in the hash:

- 
T.1a: notes                   (field encoding bytes)
+                
"ZTxIdSAIssueHash"

+                
In case the transaction has no issuance components, ''issue_actions_digest'' is:

+                
BLAKE2b-256("ZTxIdSAIssueHash", [])

+                
T.1: 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.1a: notes_digest            (32-byte hash output)
 T.1b: assetDescription        (field encoding bytes)
-T.1c: isFinalized             (1 bit)

-                    
T.1a: notes 

-                        
A byte encoding of Note information for all Notes belonging to the Action. For each Note, the following elements are included in the hash:

+T.1c: flagsIssuance           (1 byte)
+

The personalization field of this hash is set to:

+ 
"ZTxIdIssActHash"
+
T.1a: notes_digest
+

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

T.1a.1: recipient                    (field encoding bytes)
 T.1a.2: value                        (field encoding bytes)
 T.1a.3: asset                        (field encoding bytes)
 T.1a.4: rho                          (field encoding bytes)
 T.1a.5: rseed                        (field encoding bytes)
+

The personalization field of this hash is set to:

+ 
"ZTxIdIANoteHash"
T.1a.1: recipient
-

Raw Address encoded as specified in [Zcash Protocol Spec § 5.6.4.2: Orchard Raw Payment Addresses].

+

This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 17.

T.1a.2: value

Note value encoded as little-endian 8-byte representation of u64 raw value.

@@ -461,12 +468,16 @@
T.1b: assetDescription

UTF-8 encoding of the Asset description string.

-
T.1c: isFinalized
-

1-bit representation of a boolean flag that is set to 'true' if the Asset Identifier was finalized in this action and 'false' otherwise. 'True' is represented as 1, 'false' as 0.

+
T.1c: flagsIssuance
+

An 8-bit value representing a set of flags. Ordered from LSB to MSB:

+
    +
  • finalize
    • +
  • The remaining bits are set to 0.
    • +
-

T.2 issuerVerificationKey

-

A byte encoding of issuer validating key for the bundle as defined in [Zcash Protocol Spec § 4.2.3: Orchard Key Components].

+

T.2: issuanceValidatingKey

+

A byte encoding of issuance validating key for the bundle as defined in the Issuance Key Derivation section.

@@ -478,7 +489,7 @@ \(\mathsf{AssetId}\) . -

Bridging Assets For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

+

Bridging Assets For bridging purposes, the secure method of off-boarding Assets is to burn an Asset with the burning mechanism in ZIP 226 4. Users should be aware of issuers that demand the Assets be sent to a specific address on the Zcash chain to be redeemed elsewhere, as this may not reflect the real reserve value of the specific Wrapped Asset.

Other Considerations

Implementing Zcash Nodes

@@ -489,7 +500,7 @@ in order to properly keep track of the total supply for different Asset Identifiers. This is useful for wallets and other applications that need to keep track of the total supply of Assets.

Fee Structures

-

The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 7.

+

The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 8.

Future Work

In future versions of this ZIP, the protocol may also include a "key rotation" mechanism. This would allow an issuer to change the underlying @@ -560,18 +571,26 @@

- +
- +
7ZIP 317: Proportional Fee MechanismZIP 244: Transaction Identifier Non-Malleability
- +
+ + + +
8ZIP 317b: ZSA Extension Proportional Fee Mechanism
+ + + + @@ -579,7 +598,7 @@
9 ZIP 32: Shielded Hierarchical Deterministic Wallets
- + @@ -587,7 +606,7 @@
910 ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation
- + @@ -595,7 +614,7 @@
1011 ZIP 316: Unified Addresses and Unified Viewing Keys
- + @@ -603,7 +622,7 @@
1112 Zcash Protocol Specification, Version 2022.3.8. Section 3.1: Payment Addresses and Keys
- + @@ -611,7 +630,7 @@
1213 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.9.8: Group Hash into Pallas and Vesta
- + @@ -619,7 +638,7 @@
1314 Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components
- + @@ -627,15 +646,23 @@
1415 Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
- +
1516 Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard)
+ + + + + + + +
17Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses
- + diff --git a/zip-0227.rst b/zip-0227.rst index f68f953b5..cf64a1302 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -291,10 +291,13 @@ The following is a list of rationale for different decisions made in the proposa TxId Digest =========== -A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:: + +As in ZIP 244 [#zip-0244]_, the digests are all personalized BLAKE2b-256 hashes, and in cases where no elements are available for hashing, a personalized hash of the empty byte array is used. + +A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:: issuance_txid_digest - ├── issueActions + ├── issue_actions_digest └── issuerVerificationKey In the specification below, nodes of the tree are presented in depth-first order. @@ -303,25 +306,32 @@ issuance_txid_digest -------------------- A BLAKE2b-256 hash of the following values :: - T.1: issueActions (field encoding bytes) - T.2: issuerVerificationKey (field encoding bytes) + T.1: issue_actions_digest (32-byte hash output) + T.2: issuanceValidatingKey (32 bytes) The personalization field of this hash is set to:: - "ZTxIdOrcZSAIssue" + "ZTxIdSAIssueHash" -T.1 issueActions -```````````````` -A byte encoding of Issue Action information for all Issue Actions belonging to the transaction. For each Action, the following elements are included in the hash:: +In case the transaction has no issuance components, ''issue_actions_digest'' is:: + + BLAKE2b-256("ZTxIdSAIssueHash", []) - T.1a: notes (field encoding bytes) +T.1: 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.1a: notes_digest (32-byte hash output) T.1b: assetDescription (field encoding bytes) - T.1c: isFinalized (1 bit) + T.1c: flagsIssuance (1 byte) + +The personalization field of this hash is set to:: + "ZTxIdIssActHash" -T.1a: notes -''''''''''' -A byte encoding of Note information for all Notes belonging to the Action. For each Note, the following elements are included in the hash:: +T.1a: notes_digest +'''''''''''''''''' +A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:: T.1a.1: recipient (field encoding bytes) T.1a.2: value (field encoding bytes) @@ -329,10 +339,13 @@ A byte encoding of Note information for all Notes belonging to the Action. For e T.1a.4: rho (field encoding bytes) T.1a.5: rseed (field encoding bytes) +The personalization field of this hash is set to:: + + "ZTxIdIANoteHash" T.1a.1: recipient ................. -Raw Address encoded as specified in [Zcash Protocol Spec § 5.6.4.2: Orchard Raw Payment Addresses]. +This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification [#protocol-orchardpaymentaddrencoding]_. T.1a.2: value ............. @@ -354,14 +367,17 @@ T.1b: assetDescription '''''''''''''''''''''' UTF-8 encoding of the Asset description string. -T.1c: isFinalized -''''''''''''''''' -1-bit representation of a boolean flag that is set to 'true' if the Asset Identifier was finalized in this action and 'false' otherwise. 'True' is represented as 1, 'false' as 0. +T.1c: flagsIssuance +''''''''''''''''''' +An 8-bit value representing a set of flags. Ordered from LSB to MSB: +- ``finalize`` +- The remaining bits are set to `0`. -T.2 issuerVerificationKey -````````````````````````` -A byte encoding of issuer validating key for the bundle as defined in [Zcash Protocol Spec § 4.2.3: Orchard Key Components]. + +T.2: issuanceValidatingKey +`````````````````````````` +A byte encoding of issuance validating key for the bundle as defined in the `Issuance Key Derivation`_ section. Security and Privacy Considerations @@ -419,7 +435,8 @@ References .. [#zip-0226] `ZIP 226: Transfer and Burn of Zcash Shielded Assets `_ .. [#zip-0226-notestructure] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - Note Structure & Commitment `_ .. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_ -.. [#zip-0317b] `ZIP 317: Proportional Fee Mechanism `_ +.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_ +.. [#zip-0317b] `ZIP 317b: ZSA Extension Proportional Fee Mechanism `_ .. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ .. [#zip-0032-orchard-master] `ZIP 32: Shielded Hierarchical Deterministic Wallets - Orchard master key generation `_ .. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ @@ -428,4 +445,5 @@ References .. [#protocol-orchardkeycomponents] `Zcash Protocol Specification, Version 2022.3.8. Section 4.2.3: Orchard Key Components `_ .. [#protocol-spendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 4.15: Spend Authorization Signature (Sapling and Orchard) `_ .. [#protocol-concretespendauthsig] `Zcash Protocol Specification, Version 2022.3.8. Section 5.4.7.1: Spend Authorization Signature (Sapling and Orchard) `_ +.. [#protocol-orchardpaymentaddrencoding] `Zcash Protocol Specification, Version 2022.3.8. Section 5.6.4.2: Orchard Raw Payment Addresses `_ .. [#protocol-transactionstructure] `Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5) `_ \ No newline at end of file From 8351cde209242e1bf903f8a1db641aa2bc043b90 Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Tue, 7 Mar 2023 14:43:47 +0530 Subject: [PATCH 2/3] using flagsIssuance in place of a single bit boolean for the issue actions as well --- zip-0227.html | 8 ++++---- zip-0227.rst | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 09a82a88e..98f20673f 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -228,10 +228,10 @@ - - - - + + + +
1618 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus (Transaction Version 5)
A sequence of note descriptions within the issuance action
1 bitfinalizebooleanThe boolean that determines the finality of the issuance of that Asset1 byteflagsIssuancebyteAn 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0.
diff --git a/zip-0227.rst b/zip-0227.rst index cf64a1302..3b2e40ccb 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -174,14 +174,14 @@ An issuance action, `IssueAction`, is the instance of issuing a specific custom An asset's :math:`\mathsf{AssetId}` is added to the :math:`\mathsf{previously\_finalized}` set after a block that contains any issuance transaction for that asset with ``finalize = 1``. It then cannot be removed from this set. For Assets with :math:`\mathsf{AssetId} \in \mathsf{previously\_finalized}`, no further tokens can be issued, so as seen below, the validators will reject the transaction. For Assets with :math:`\mathsf{AssetId} \not\in \mathsf{previously\_finalized}`, new issuance actions can be issued in future transactions. These must use the same Asset description, :math:`\mathsf{asset\_desc}`, and can either maintain ``finalize = 0`` or change it to ``finalize = 1``, denoting that this custom Asset cannot be issued after the containing block. -================= =============================== ========================== ======================================================================== +================= =============================== ========================== =========================================================================================== Size Name Data Type Description -================= =============================== ========================== ======================================================================== +================= =============================== ========================== =========================================================================================== Varies :math:`\mathsf{asset\_desc}` byte UTF-8 encoded string of varied size, up to 512 bytes Varies nNotes compactSize The number of notes in the issuance action noteSize * nNotes vNotes Note[nNotes] A sequence of note descriptions within the issuance action -1 bit ``finalize`` boolean The boolean that determines the finality of the issuance of that Asset -================= =============================== ========================== ======================================================================== +1 byte ``flagsIssuance`` byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0. +================= =============================== ========================== =========================================================================================== 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 `NoteCommitmentTree` 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. From dd3eaaf9ff2da1a7374b502b49f855a1185ff38a Mon Sep 17 00:00:00 2001 From: Vivek Arte Date: Tue, 14 Mar 2023 01:08:47 +0530 Subject: [PATCH 3/3] fixing small typo --- zip-0227.html | 2 +- zip-0227.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/zip-0227.html b/zip-0227.html index 98f20673f..fff6683a4 100644 --- a/zip-0227.html +++ b/zip-0227.html @@ -423,7 +423,7 @@

A new issuance transaction digest algorithm is defined that constructs the identifier for an issuance transaction. Each branch of the tree of hashes will correspond to a specific subset of issuance transaction data. The overall structure of the hash is as follows; each name referenced here will be described in detail below:

issuance_txid_digest
 ├── issue_actions_digest
-└── issuerVerificationKey
+└── issuanceValidatingKey

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

issuance_txid_digest

A BLAKE2b-256 hash of the following values

diff --git a/zip-0227.rst b/zip-0227.rst index 3b2e40ccb..695bf0086 100644 --- a/zip-0227.rst +++ b/zip-0227.rst @@ -298,7 +298,7 @@ A new issuance transaction digest algorithm is defined that constructs the ident issuance_txid_digest ├── issue_actions_digest - └── issuerVerificationKey + └── issuanceValidatingKey In the specification below, nodes of the tree are presented in depth-first order.