The key word "MUST" in this document is to be interpreted as described in RFC 2119 1.
The term "network upgrade" in this document is to be interpreted as described in ZIP 200 2.
-
The term "Orchard" in this document is to be interpreted as described in ZIP 224 3.
-
The terms "Asset", "custom Asset", and "Wrapped Asset" in this document are to be interpreted as described in ZIP 226 4.
+
The terms "Orchard" and "Action" in this document are to be interpreted as described in ZIP 224 3.
We define the following additional terms:
+
Asset: A type of note that can be transferred on the Zcash blockchain. Each Asset is identified by an Asset Identifier Specification: Asset Identifier.
+
+
ZEC is the default (and currently the only defined) Asset for the Zcash mainnet.
+
TAZ is the default (and currently the only defined) Asset for the Zcash testnet.
+
We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ.
+
+
+
Native Asset: a Custom Asset with issuance defined on the Zcash blockchain.
+
Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash blockchain.
Issuance Action: an instance of a single issuance of a Zcash Shielded Asset. It defines the issuance of a single Asset Identifier.
Issuance Bundle: the bundle in the transaction that contains all the issuance actions of that transaction.
Abstract
-
ZIP 226 4 and ZIP 227 7 propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 7. The transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
+
This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 4. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 4. This ZIP must only be implemented in conjuction with ZIP 226 4. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
Motivation
-
This ZIP is a supporting ZIP for ZIP 226 4, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function.
-
This ZIP enables only transparent issuance, since as a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.
-
The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash block chain), as well as for institutions to create bridges from other chains and import "wrapped" Assets. This enables what we hope will be a useful set of applications.
+
This ZIP introduces the issuance mechanism for custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 4) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 4.
+
This ZIP only enables transparent issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.
+
The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash blockchain), as well as for institutions to create bridges from other chains and import Wrapped Assets. This enables what we hope will be a useful set of applications.
Use Cases
The design presented in this ZIP enables issuance of shielded Assets in various modes:
@@ -54,8 +62,8 @@
Requirements
-
Any user of the Zcash block chain can issue custom Assets on chain.
-
The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain.
+
Any user of the Zcash blockchain can issue custom Assets on chain.
+
The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash blockchain.
Issuing or changing the attributes of a specific Asset should require cryptographic authorization.
The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier.
An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets.
@@ -63,7 +71,7 @@
Specification: Issuance Keys and Issuance Authorization Signature Scheme
-
The ZSA Protocol adds the following three keys to the key components 18:
+
The ZSA Protocol adds the following three keys to the key components 17:
The issuance master key, denoted as
\(\mathsf{sk}_{\mathsf{iss}}\)
@@ -73,7 +81,7 @@
. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
The issuance validating key, denoted as
\(\mathsf{ik}\)
- , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
+ , is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
The relations between these keys are shown in the following diagram:
@@ -85,7 +93,7 @@
\(\mathsf{IssueAuthSig}\)
similar to
\(\mathsf{SpendAuthSig}^{\mathsf{Orchard}}\)
- , the Orchard spend authorization signature scheme 22. Specifically, we instantiate
+ , the Orchard spend authorization signature scheme 21. Specifically, we instantiate
\(\mathsf{IssueAuthSig}\)
as
\(\mathsf{RedPallas}\)
@@ -93,36 +101,40 @@
\(\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 19.
+ is defined as in the Zcash protocol specification 18.
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 20.
Issuance master key derivation for hierarchical deterministic wallets
-
The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 13. We reuse the functions defined there in what follows in this section.
+
The issuance master key is derived using the Orchard master key derivation procedure defined in ZIP 32 12. We reuse the functions defined there in what follows in this section.
Let
\(S\)
be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. We define the master extended issuance key
\(m_{\mathsf{Issuance}} := \mathsf{MasterKeyGen}(\texttt{"ZIP32ZSAIssue_V1"}, S)\)
.
-
As in ZIP 32 for Orchard 14, we only use hardened child key derivation for the issuance master key. We reuse the
+
As in ZIP 32 for Orchard 13, we only use hardened child key derivation for the issuance master key. We reuse the
\(\mathsf{CDKsk}\)
function for Orchard child key derivation from ZIP 32.
-
We use the notation of ZIP 32 16 for shielded HD paths, and define the issuance master key path as
- \(m_\mathsf{Issuance} / purpose / coin\_type' / account'\)
+
We use the notation of ZIP 32 15 for shielded HD paths, and define the issuance master key path as
+ \(m_\mathsf{Issuance} / purpose' / coin\_type' / account'\)
. We fix the path levels as follows:
\(purpose\)
: a constant set to
+ \(227\)
+ (i.e.
+ \(\texttt{0xe3}). :math:`purpose'\)
+ is thus
\(227'\)
(or
\(\texttt{0x800000e3}\)
) following the BIP 43 recommendation.
\(account\)
: fixed to index
@@ -136,7 +148,7 @@
.
Derivation of issuance authorizing key and issuance validating key
-
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 20, 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 19, as described below.
The issuance authorizing key is derived from the issuance master key,
\(\mathsf{sk}_{\mathsf{iss}}\)
@@ -149,13 +161,15 @@
, as a public verification key:
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 12. 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 11. 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.
Specification: Asset Identifier
-
For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair
- \((\mathsf{ik}, \mathsf{asset\_desc})\)
+
For every new Asset, there must be a new and unique Asset Identifier, denoted
+ \(\mathsf{AssetId}\)
+ . We define this to be a globally unique pair
+ \(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})\)
, where
\(\mathsf{ik}\)
is the issuance key and
@@ -182,22 +196,27 @@
, where
Define
\(\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})\)
, where
In the case of Orchard, we define
- \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})\)
+ \(\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})\)
where
\(\mathsf{GroupHash}^\mathbb{P}\)
- is defined as in 19.
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 ZSA Protocol
+
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.
Specification: Global Issuance State
Issuance requires the following additions to the global state defined at block boundaries:
@@ -223,7 +242,7 @@
\(\mathsf{asset\_desc}\)
: the Asset description, a byte string of up to 512 bytes as defined in the Specification: Asset Identifier section.
-
notes: an array containing the unencrypted output notes of the recipients of the Asset, of type Note
+
notes: an array of Note containing the unencrypted output notes of the recipients of the Asset.
finalize: a boolean that defines whether the issuance of that specific custom Asset is finalized or not
An asset's
@@ -240,7 +259,7 @@
-
Size
+
Bytes
Name
Data Type
Description
@@ -248,24 +267,16 @@
-
2 bytes
-
- \(\mathsf{assetDescSize}\)
-
+
2
+
assetDescSize
byte
-
The length of the
- \(\mathsf{asset\_desc}\)
- string in bytes
+
The length of the asset_desc string in bytes
Varies
-
- \(\mathsf{asset\_desc}\)
-
+
asset_desc
byte
-
UTF-8 encoded string, of size
- \(\mathsf{assetDescSize}\)
- bytes
+
UTF-8 encoded string, of size assetDescSize bytes
Varies
@@ -280,13 +291,14 @@
A sequence of note descriptions within the issuance action
-
1 byte
-
flagsIssuance
+
1
+
flagsIssuance
byte
-
An 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0.
+
An 8-bit value with the finalize boolean value as the LSB, and the other bits set to 0. (See: T.5a.iii: flagsIssuance)
+
, where noteSize is the size, in bytes, of a Note.
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.
Issuance Bundle
@@ -302,7 +314,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 24.
+
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 23.
@@ -320,16 +332,14 @@
The number of issuance actions in the bundle
-
Varies
+
IssueActionSize * nIssueActions
vIssueActions
IssueAction[nIssueActions]
A sequence of issuance actions descriptions
32
-
- \(\mathsf{ik}\)
-
+
ik
byte[32]
The issuance validating key of the issuer, used to validate the signature
@@ -341,6 +351,7 @@
+
, where IssueActionSize is the size, in bytes, of an IssueAction description.
Issuance Protocol
The issuer program performs the following operations
set the finalize boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
+
set the finalize boolean as desired (if more issuance actions are to be created for this Asset Identifier, set finalize = 0, otherwise set finalize = 1)
For each recipient
\(i\)
:
@@ -385,7 +396,7 @@
\(\mathsf{IssueAuthSig}\)
signature scheme. The signature is then added to the issuance bundle.
-
NOTE that the commitment is not included in the IssuanceAction itself. As explained below, it is later computed by the validators and added to the NoteCommitmentTree.
+
Note: that the commitment is not included in the IssuanceAction itself. As explained below, it is computed later by the validators and added to the NoteCommitmentTree.
Specification: Consensus Rule Changes
@@ -425,7 +436,7 @@
For each note, compute the note commitment as
\(\mathsf{cm} = \mathsf{NoteCommit^{OrchardZSA}_{rcm}(repr_{\mathbb{P}}(g_d), repr_{\mathbb{P}}(pk_d), v, \rho, \psi, AssetBase)}\)
- as defined in the Note Structure and Commitment section of ZIP 226 5 and
+ as defined in the Note Structure and Commitment section of ZIP 226 5 and
add
\(\mathsf{cm}\)
to the Merkle tree of note commitments, NoteCommitmentTree.
@@ -456,7 +467,7 @@
Concrete Applications
Asset Features
-
By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example,
+
By using the finalize boolean and the burning mechanism defined in 4, issuers can control the supply production of any Asset associated to their issuer keys. For example,
by setting finalize = 1 from the first issuance action for that Asset Identifier, the issuer is in essence creating a one-time issuance transaction. This is useful when the max supply is capped from the beginning and the distribution is known in advance. All tokens are issued at once and distributed as needed.
@@ -480,7 +491,7 @@
TxId Digest - Issuance
-
This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. As in ZIP 244 8, 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.
+
This section details the construction of the subtree of hashes in the transaction digest that corresponds to issuance transaction data. Details of the overall changes to the transaction digest due to the ZSA protocol can be found in ZIP 226 6. 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 subtree of the transaction digest tree of hashes for the issuance portion of a transaction. Each branch of the subtree 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:
This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 23.
+
This is the raw encoding of an Orchard shielded payment address as defined in the protocol specification 22.
T.5a.i.2: value
-
Note value encoded as little-endian 8-byte representation of u64 raw value.
+
Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
T.5a.i.3: assetBase
Asset Base encoded as the 32-byte representation of a point on the Pallas curve.
@@ -546,7 +557,7 @@
Signature Digest
-
The per-input transaction digest algorithm to generate the signature digest in ZIP 244 9 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.
+
The per-input transaction digest algorithm to generate the signature digest in ZIP 244 8 is modified so that a signature digest is produced for each transparent input, each Sapling input, each Orchard action, and additionally for each Issuance Action. For Issuance Actions, this algorithm has the exact same output as the transaction digest algorithm, thus the txid may be signed directly.
The overall structure of the hash is as follows. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:
The personalization field remains the same as in ZIP 244 8.
+
The personalization field remains the same as in ZIP 244 7.
S.5: issuance_digest
Identical to that specified for the transaction identifier.
Authorizing Data Commitment
-
The transaction digest algorithm defined in ZIP 244 10 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:
+
The transaction digest algorithm defined in ZIP 244 9 which commits to the authorizing data of a transaction is modified by the ZSA protocol to have the following structure. We highlight the changes for the ZSA protocol via the [ADDED FOR ZSA] text label, and we omit the descriptions of the sections that do not change for the ZSA protocol:
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.
+
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
@@ -616,7 +627,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 11.
+
The fee mechanism described in this ZIP will follow the mechanism described in ZIP 317b 10.
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
@@ -687,18 +698,10 @@
-
diff --git a/zip-0227.rst b/zip-0227.rst
index de7e9a4f4..110af801d 100644
--- a/zip-0227.rst
+++ b/zip-0227.rst
@@ -24,29 +24,35 @@ The key word "MUST" in this document is to be interpreted as described in RFC 21
The term "network upgrade" in this document is to be interpreted as described in ZIP 200 [#zip-0200]_.
-The term "Orchard" in this document is to be interpreted as described in ZIP 224 [#zip-0224]_.
-
-The terms "Asset", "custom Asset", and "Wrapped Asset" in this document are to be interpreted as described in ZIP 226 [#zip-0226]_.
+The terms "Orchard" and "Action" in this document are to be interpreted as described in
+ZIP 224 [#zip-0224]_.
We define the following additional terms:
+- Asset: A type of note that can be transferred on the Zcash blockchain. Each Asset is identified by an Asset Identifier `Specification: Asset Identifier`_.
+
+ - ZEC is the default (and currently the only defined) Asset for the Zcash mainnet.
+ - TAZ is the default (and currently the only defined) Asset for the Zcash testnet.
+ - We use the term "Custom Asset" to refer to any Asset other than ZEC and TAZ.
+
+- Native Asset: a Custom Asset with issuance defined on the Zcash blockchain.
+- Wrapped Asset: a Custom Asset with native issuance defined outside the Zcash blockchain.
- Issuance Action: an instance of a single issuance of a Zcash Shielded Asset. It defines the issuance of a single Asset Identifier.
- Issuance Bundle: the bundle in the transaction that contains all the issuance actions of that transaction.
Abstract
========
-ZIP 226 [#zip-0226]_ and ZIP 227 [#zip-0227]_ propose in conjunction the Zcash Shielded Assets (ZSA) protocol, which is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in ZIP 227 [#zip-0227]_. The transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_, as the issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
+This ZIP (ZIP 227) proposes the Zcash Shielded Assets (ZSA) protocol, in conjunction with ZIP 226 [#zip-0226]_. This protocol is an extension of the Orchard protocol that enables the creation, transfer and burn of custom Assets on the Zcash chain. The creation of such Assets is defined in this ZIP (ZIP 227), while the transfer and burn of such Assets is defined in ZIP 226 [#zip-0226]_. This ZIP must only be implemented in conjuction with ZIP 226 [#zip-0226]_. The proposed issuance mechanism is only valid for the ZSA transfer protocol, because it produces notes that can only be transferred under ZSA.
Motivation
==========
-This ZIP is a supporting ZIP for ZIP 226 [#zip-0226]_, which lays out its motivations, but requires an issuance mechanism to be defined (which is substantial enough to stand on its own) in order to function.
-
-This ZIP enables only *transparent* issuance, since as a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.
+This ZIP introduces the issuance mechanism for custom Assets on the Zcash chain. While originally part of a same ZSA ZIP (ZIP 226 [#zip-0226]_) the issuance mechanism turned out to be substantial enough to stand on its own and justify the creation of this supporting ZIP for ZIP 226 [#zip-0226]_.
-The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash block chain), as well as for institutions to create bridges from other chains and import "wrapped" Assets. This enables what we hope will be a useful set of applications.
+This ZIP only enables *transparent* issuance. As a first step, transparency will allow for proper testing of the applications that will be most used in the Zcash ecosystem, and will enable the supply of Assets to be tracked.
+The issuance mechanism described in this ZIP is broad enough for issuers to either create Assets on Zcash (i.e. Assets that originate on the Zcash blockchain), as well as for institutions to create bridges from other chains and import Wrapped Assets. This enables what we hope will be a useful set of applications.
Use Cases
=========
@@ -63,8 +69,8 @@ See the `Concrete Applications`_ section for more details.
Requirements
============
-- Any user of the Zcash block chain can issue custom Assets on chain.
-- The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash block chain.
+- Any user of the Zcash blockchain can issue custom Assets on chain.
+- The issuance mechanism should enable public tracking of the supply of the Assets on the Zcash blockchain.
- Issuing or changing the attributes of a specific Asset should require cryptographic authorization.
- The Asset identification should be unique (among all shielded pools) and different issuer public keys should not be able to generate the same Asset Identifier.
- An issuer should be able to issue different Assets in the same transaction. In other words, in a single "issuance bundle", the issuer should be able publish many "issuance actions", potentially creating multiple Custom Assets.
@@ -80,7 +86,7 @@ The ZSA Protocol adds the following three keys to the key components [#protocol-
2. The issuance authorizing key is the key that is used to sign the issuance transaction, and is denoted as :math:`\mathsf{isk}`. This key is used to authorize the issuance of a specific Asset Identifier, and is only used by the issuer.
-3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all block chain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
+3. The issuance validating key, denoted as :math:`\mathsf{ik}`, is the key that is used to validate the issuance transaction. This key is used to validate the issuance of a specific Asset Identifier, and is used by all blockchain users (specifically the Asset owners and consensus validators) to associate the Asset in question with the issuer.
The relations between these keys are shown in the following diagram:
@@ -114,9 +120,9 @@ We define the master extended issuance key :math:`m_{\mathsf{Issuance}} := \math
As in ZIP 32 for Orchard [#zip-0032-orchard-child-key-derivation]_, we only use hardened child key derivation for the issuance master key.
We reuse the :math:`\mathsf{CDKsk}` function for Orchard child key derivation from ZIP 32.
-We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose / coin\_type' / account'`. We fix the path levels as follows:
+We use the notation of ZIP 32 [#zip-0032-orchard-key-path]_ for shielded HD paths, and define the issuance master key path as :math:`m_\mathsf{Issuance} / purpose' / coin\_type' / account'`. We fix the path levels as follows:
-- :math:`purpose`: a constant set to :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation.
+- :math:`purpose`: a constant set to :math:`227` (i.e. :math:`\texttt{0xe3}). :math:`purpose'` is thus :math:`227'` (or :math:`\texttt{0x800000e3}`) following the BIP 43 recommendation.
- :math:`coin\_type`: Defined as in ZIP 32 [#zip-0032-key-path-levels]_.
- :math:`account`: fixed to index :math:`0`.
@@ -140,7 +146,7 @@ This allows the issuer to use the same wallet it usually uses to transfer Assets
Specification: Asset Identifier
===============================
-For every new Asset, there must be a new and unique Asset Identifier. We define this to be a globally unique pair :math:`(\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string.
+For every new Asset, there must be a new and unique Asset Identifier, denoted :math:`\mathsf{AssetId}`. We define this to be a globally unique pair :math:`\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})`, where :math:`\mathsf{ik}` is the issuance key and :math:`\mathsf{asset\_desc}` is a byte string.
A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the Orchard-based ZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, :math:`\mathsf{AssetDigest}`, which is simply is a :math:`\textsf{BLAKE2b-512}` hash of the Asset Identifier.
From the Asset Digest, we derive a specific Asset Base within each such shielded protocol (for example :math:`\mathsf{AssetBase}^{\mathsf{Orchard}}_{\mathsf{AssetId}}` for the Orchard-based ZSA protocol), using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.
@@ -153,12 +159,12 @@ Let
Define :math:`\mathsf{AssetDigest_{\mathsf{AssetId}}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))`,
where
-- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}(\mathsf{ik}, \mathsf{asset\_desc}) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`.
+- :math:`\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathsf{0x00} || \mathsf{repr}_{\mathbb{P}}(\mathsf{ik}) || \mathsf{asset\_desc}\!`.
Define :math:`\mathsf{AssetBase^{Protocol}_{\mathsf{AssetId}}} := \mathsf{ZSAValueBase^{Protocol}}(\mathsf{AssetDigest}_{\mathsf{AssetId}})`,
where
-In the case of Orchard, we define :math:`\mathsf{ZSAValueBase^{Orchard}}(\mathsf{asset\_digest}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{asset\_digest})`
+In the case of Orchard, we define :math:`\mathsf{ZSAValueBase^{Orchard}}(\mathsf{AssetDigest}_{\mathsf{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest}_{\mathsf{AssetId}})`
where :math:`\mathsf{GroupHash}^\mathbb{P}` is defined as in [#protocol-concretegrouphashpallasandvesta]_.
The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:
@@ -171,6 +177,8 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho
Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol
+**Note:** To keep notations light and concise, we may omit :math:`\mathsf{AssetId}` (resp. :math:`\mathsf{Protocol}`) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.
+
Specification: Global Issuance State
====================================
@@ -189,20 +197,22 @@ An issuance action, `IssueAction`, is the instance of issuing a specific custom
- :math:`\mathsf{assetDescSize}`: the size of the Asset description, a number between :math:`0` and :math:`512`, stored in two bytes.
- :math:`\mathsf{asset\_desc}`: the Asset description, a byte string of up to 512 bytes as defined in the `Specification: Asset Identifier`_ section.
-- `notes`: an array containing the unencrypted output notes of the recipients of the Asset, of type `Note`
+- `notes`: an array of `Note` containing the unencrypted output notes of the recipients of the Asset.
- ``finalize``: a boolean that defines whether the issuance of that specific custom Asset is finalized or not
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
-================= =============================== ========================== ===========================================================================================
-2 bytes :math:`\mathsf{assetDescSize}` byte The length of the :math:`\mathsf{asset\_desc}` string in bytes
-Varies :math:`\mathsf{asset\_desc}` byte UTF-8 encoded string, of size :math:`\mathsf{assetDescSize}` 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 byte ``flagsIssuance`` byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0.
-================= =============================== ========================== ===========================================================================================
+==================== ===================== ======================= ===========================================================================================
+Bytes Name Data Type Description
+==================== ===================== ======================= ===========================================================================================
+2 assetDescSize byte The length of the asset\_desc string in bytes
+Varies asset\_desc byte UTF-8 encoded string, of size assetDescSize 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 flagsIssuance byte An 8-bit value with the ``finalize`` boolean value as the LSB, and the other bits set to 0. (See: `T.5a.iii: flagsIssuance`_)
+==================== ===================== ======================= ===========================================================================================
+
+, where noteSize is the size, in bytes, of a Note.
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.
@@ -217,14 +227,16 @@ An issuance bundle, `IssueBundle`, is the aggregate of all the issuance-related
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 [#protocol-transactionstructure]_.
-======= ==================== ========================== ==========================================================================================================================
-Bytes Name Data Type Description
-======= ==================== ========================== ==========================================================================================================================
-Varies nIssueActions compactSize The number of issuance actions in the bundle
-Varies vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions
-32 :math:`\mathsf{ik}` byte[32] The issuance validating key of the issuer, used to validate the signature
-64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer, validated as in `Issuance Authorization Signature Scheme`_
-======= ==================== ========================== ==========================================================================================================================
+================================= ===================== ========================== ===============================================================================
+Bytes Name Data Type Description
+================================= ===================== ========================== ===============================================================================
+Varies nIssueActions compactSize The number of issuance actions in the bundle
+IssueActionSize * nIssueActions vIssueActions IssueAction[nIssueActions] A sequence of issuance actions descriptions
+32 ik byte[32] The issuance validating key of the issuer, used to validate the signature
+64 issueAuthSig byte[64] The signature of the transaction SIGHASH, signed by the issuer, validated as in `Issuance Authorization Signature Scheme`_
+================================= ===================== ========================== ===============================================================================
+
+, where IssueActionSize is the size, in bytes, of an IssueAction description.
Issuance Protocol
-----------------
@@ -235,7 +247,7 @@ For all actions `IssueAction`:
- encode :math:`\mathsf{asset\_desc}` as a UTF-8 byte string of size up to 512.
- compute :math:`\mathsf{AssetDigest}` from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as decribed in the `Specification: Asset Identifier`_ section.
- compute :math:`\mathsf{AssetBase^{Protocol}}` from :math:`\mathsf{AssetDigest}` as decribed in the `Specification: Asset Identifier`_ section.
-- set the ``finalize`` boolean as desired (if more more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``)
+- set the ``finalize`` boolean as desired (if more issuance actions are to be created for this Asset Identifier, set ``finalize = 0``, otherwise set ``finalize = 1``)
- For each recipient :math:`i`:
- generate a ZSA output note that includes the Asset Base. For an Orchard-based ZSA note this is :math:`\mathsf{note}_i = (\mathsf{d}_i, \mathsf{pk}_{\mathsf{d},i}, \mathsf{v}_i, \rho_i, \psi_i, \mathsf{AssetBase^{Orchard}}, \mathsf{rcm}_i)\!`.
@@ -249,7 +261,7 @@ For the `IssueBundle`:
- sign the `SIGHASH` of the transaction with the issuance authorizing key, :math:`\mathsf{isk}`, using the :math:`\mathsf{IssueAuthSig}` signature scheme. The signature is then added to the issuance bundle.
-NOTE that the commitment is not included in the `IssuanceAction` itself. As explained below, it is later computed by the validators and added to the `NoteCommitmentTree`.
+**Note:** that the commitment is not included in the `IssuanceAction` itself. As explained below, it is computed later by the validators and added to the `NoteCommitmentTree`.
Specification: Consensus Rule Changes
@@ -263,6 +275,7 @@ For each `IssueAction` in `IssueBundle`:
- check that :math:`0 < \mathsf{assetDescSize} <= 512`.
- check that :math:`\mathsf{asset\_desc}` is a string of length :math:`\mathsf{assetDescSize}` bytes.
+
- retrieve :math:`\mathsf{AssetBase}` from the first note in the sequence and check that :math:`\mathsf{AssetBase}` is derived from the issuance validating key :math:`\mathsf{ik}` and :math:`\mathsf{asset\_desc}` as described in the `Specification: Asset Identifier`_ section.
- check that the :math:`\mathsf{AssetId}` does not exist in the ``previously_finalized`` set in the global state.
- check that every note in the `IssueAction` contains the same :math:`\mathsf{AssetBase}` and is properly constructed as :math:`note = (\mathsf{g_d, pk_d, v, \rho, \psi, AssetBase})`.
@@ -378,7 +391,7 @@ This is the raw encoding of an Orchard shielded payment address as defined in th
T.5a.i.2: value
...............
-Note value encoded as little-endian 8-byte representation of u64 raw value.
+Note value encoded as little-endian 8-byte representation of 64-bit unsigned integer (e.g. u64 in Rust) raw value.
T.5a.i.3: assetBase
...................
@@ -536,7 +549,6 @@ 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-0226-txiddigest] `ZIP 226: Transfer and Burn of Zcash Shielded Assets - TxId Digest `_
-.. [#zip-0227] `ZIP 227: Issuance of Zcash Shielded Assets `_
.. [#zip-0244] `ZIP 244: Transaction Identifier Non-Malleability `_
.. [#zip-0244-sigdigest] `ZIP 244: Transaction Identifier Non-Malleability: Signature Digest `_
.. [#zip-0244-authcommitment] `ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment `_
