zcash / zips

Zcash Improvement Proposals

What are ZIPs?

Zcash Improvement Proposals (ZIPs) are the way to:

• propose new features for the Zcash cryptocurrency and their rationale,
• specify the implementation details of the feature,
• collect community input on the proposal, and
• document design decisions.

Contributing

The authors of a ZIP are responsible for building consensus within the community and documenting / addressing dissenting opinions.

Anyone can write a ZIP! We encourage community contributions and decentralization of work on the Zcash protocol. If you’d like to bounce ideas off people before formally writing a ZIP, we encourage it! Visit the ZcashCommunity Discord chat to talk about your idea.

Participation in the Zcash project is subject to a Code of Conduct.

The Zcash protocol is documented in its Protocol Specification.

To start contributing, first read ZIP 0 which documents the ZIP process. Then clone this repo from GitHub, and start adding your draft ZIP, formatted either as reStructuredText or as Markdown.

For example, if using reStructuredText, use a filename matching draft-*.rst. Use make to check that you are using correct reStructuredText or Markdown syntax, and double-check the generated draft-*.html file before filing a Pull Request. See here for the project dependencies.

NU5 ZIPs

This is the list of ZIPs relevant to the NU5 Upgrade, which activated on 31st May 2022:

• ZIP 32: Shielded Hierarchical Deterministic Wallets (updated)
• ZIP 203: Transaction Expiry (updated)
• ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances (updated)
• ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext (updated)
• ZIP 213: Shielded Coinbase (updated)
• ZIP 216: Require Canonical Jubjub Point Encodings
• ZIP 221: FlyClient - Consensus-Layer Changes (updated)
• ZIP 224: Orchard Shielded Protocol
• ZIP 225: Version 5 Transaction Format
• ZIP 239: Relay of Version 5 Transactions
• ZIP 244: Transaction Identifier Non-Malleability
• ZIP 252: Deployment of the NU5 Network Upgrade
• ZIP 316: Unified Addresses and Unified Viewing Keys
• ZIP 401: Addressing Mempool Denial-of-Service (clarified)

License

Unless otherwise stated in this repository’s individual files, the contents of this repository are released under the terms of the MIT license. See COPYING for more information or see https://opensource.org/licenses/MIT .

Index of ZIPs

ZIP	Title	Status
0	ZIP Process	Active
1	Network Upgrade Policy and Scheduling	Reserved
2	Design Considerations for Network Upgrades	Reserved
32	Shielded Hierarchical Deterministic Wallets	Final
76	Transaction Signature Validation before Overwinter	Reserved
143	Transaction Signature Validation for Overwinter	Final
155	addrv2 message	Proposed
173	Bech32 Format	Final
200	Network Upgrade Mechanism	Final
201	Network Peer Management for Overwinter	Final
202	Version 3 Transaction Format for Overwinter	Final
203	Transaction Expiry	Final
204	Zcash P2P Network Protocol	Reserved
205	Deployment of the Sapling Network Upgrade	Final
206	Deployment of the Blossom Network Upgrade	Final
207	Funding Streams	Final
208	Shorter Block Target Spacing	Final
209	Prohibit Negative Shielded Chain Value Pool Balances	Final
210	Sapling Anchor Deduplication within Transactions	Withdrawn
211	Disabling Addition of New Value to the Sprout Chain Value Pool	Final
212	Allow Recipient to Derive Ephemeral Secret from Note Plaintext	Final
213	Shielded Coinbase	Final
214	Consensus rules for a Zcash Development Fund	Final
215	Explicitly Defining and Modifying Ed25519 Validation Rules	Final
216	Require Canonical Jubjub Point Encodings	Final
217	Aggregate Signatures	Reserved
219	Disabling Addition of New Value to the Sapling Chain Value Pool	Reserved
220	Zcash Shielded Assets	Withdrawn
221	FlyClient - Consensus-Layer Changes	Final
222	Transparent Zcash Extensions	Draft
224	Orchard Shielded Protocol	Final
225	Version 5 Transaction Format	Final
226	Transfer and Burn of Zcash Shielded Assets	Draft
227	Issuance of Zcash Shielded Assets	Draft
228	Asset Swaps for Zcash Shielded Assets	Reserved
230	Version 6 Transaction Format	Draft
231	Decouple Memos from Transaction Outputs	Reserved
239	Relay of Version 5 Transactions	Final
243	Transaction Signature Validation for Sapling	Final
244	Transaction Identifier Non-Malleability	Final
245	Transaction Identifier Digests & Signature Validation for Transparent Zcash Extensions	Draft
250	Deployment of the Heartwood Network Upgrade	Final
251	Deployment of the Canopy Network Upgrade	Final
252	Deployment of the NU5 Network Upgrade	Final
300	Cross-chain Atomic Transactions	Proposed
301	Zcash Stratum Protocol	Final
302	Standardized Memo Field Format	Draft
303	Sprout Payment Disclosure	Reserved
304	Sapling Address Signatures	Draft
305	Best Practices for Hardware Wallets supporting Sapling	Reserved
306	Security Considerations for Anchor Selection	Reserved
307	Light Client Protocol for Payment Detection	Draft
308	Sprout to Sapling Migration	Final
309	Blind Off-chain Lightweight Transactions (BOLT)	Reserved
310	Security Properties of Sapling Viewing Keys	Draft
311	Sapling Payment Disclosure	Reserved
312	Shielded Multisignatures using FROST	Reserved
313	Reduce Conventional Transaction Fee to 1000 zatoshis	Obsolete
314	Privacy upgrades to the Zcash light client protocol	Reserved
315	Best Practices for Wallet Handling of Multiple Pools	Reserved
316	Unified Addresses and Unified Viewing Keys	Revision 0: Final, Revision 1: Proposed
317	Proportional Transfer Fee Mechanism	Active
318	Associated Payload Encryption	Reserved
319	Options for Shielded Pool Retirement	Reserved
320	Defining an Address Type to which funds can only be sent from Transparent Addresses	Draft
321	Payment Request URIs	Proposed
322	Generic Signed Message Format	Reserved
323	Specification of getblocktemplate for Zcash	Reserved
332	Wallet Recovery from zcashd HD Seeds	Reserved
339	Wallet Recovery Words	Reserved
400	Wallet.dat format	Draft
401	Addressing Mempool Denial-of-Service	Active
402	New Wallet Database Format	Reserved
403	Verification Behaviour of zcashd	Reserved
416	Support for Unified Addresses in zcashd	Reserved
1001	Keep the Block Distribution as Initially Defined — 90% to Miners	Obsolete
1002	Opt-in Donation Feature	Obsolete
1003	20% Split Evenly Between the ECC and the Zcash Foundation, and a Voting System Mandate	Obsolete
1004	Miner-Directed Dev Fund	Obsolete
1005	Zcash Community Funding System	Obsolete
1006	Development Fund of 10% to a 2-of-3 Multisig with Community-Involved Third Entity	Obsolete
1007	Enforce Development Fund Commitments with a Legal Charter	Obsolete
1008	Fund ECC for Two More Years	Obsolete
1009	Five-Entity Strategic Council	Obsolete
1010	Compromise Dev Fund Proposal With Diverse Funding Streams	Obsolete
1011	Decentralize the Dev Fee	Obsolete
1012	Dev Fund to ECC + ZF + Major Grants	Obsolete
1013	Keep It Simple, Zcashers: 10% to ECC, 10% to ZF	Obsolete
1014	Establishing a Dev Fund for ECC, ZF, and Major Grants	Active
guide	{Something Short and To the Point}	Draft

zips's Issues

Naming

I suggest renaming some of the basic entities in protocol, to more accurately reflect what they really are:
owner - the tuple (a_{sk}) and all other keys derived from it
title - currently called "coin", defined as a pair (a, v) where a is an owner key, v a value. It means "a has a title to v units of zcash"
title destructor (or simply destructor) - currently called "serial number", is what destroys a previous title as part transaction
title destuctor seed (or destructor seed) - currently denoted "rho", the preimage of a destructor (s.n.)
title commitment - currently called "coin commitment", is the blinded version of (title,destructor seed). It has a blinding key/nonce, which should be called the (title) commitment blinder
title transfer transaction - or, simply, transaction, is the basic operation that destroys one or more titles and creates new titles (to the same amount as that destroyed)

I'll pause here to test the water. It's very different from the zerocash paper (and bitcoin nomenclature) but I think these names better describe what's going on (here and in other crypto-currencies)

Computation of hSig requires 1 byte more than a BLAKE2b input block

joinSplitPubKey is 33 bytes, so the input to BLAKE2b is 32+32+32+33 = 129 bytes. A BLAKE2b input block is 128 bytes. I believe it's secure, because we only need collision resistance — but it's untidy: if I were wrong about the h_Sig only needing collision resistance, this might unnecessarily complicate the security proof. So I intend to reduce randomSeed to 31 bytes, if no-one can think of an objection.

In the "Spend authority" property of the NP statement, computation of a_vk needs Trailing252

Undocumented difference between Zerocash and Zcash with Viewing Keys

I'm looking at: https://github.com/zcash/zips/blob/406.viewing-keys.2/protocol/protocol.pdf

In protocol.pdf addresses are malleable in a certain sense. For example, if the company puts up a donation address on their website, I can subtly replace it with a different address having the same pk_enc but a different a_pk (for my own a_sk). Assuming I somehow have the viewing key, the company will see all of the donations (they think everything is fine) but only I would be able to spend them. This is possible in protocol.pdf because in "Decryption by a recipient" the recipient trusts that the a_pk they extract from the note plaintext is theirs, the one corresponding to their pk_enc. The attack isn't possible in the Zerocash paper because a_pk is an input to Receive and that value is used in the commitment check.

ZIP: P2P network protocol differences from Bitcoin (version, magics, alerts, etc.)

Per zcash/zcash#1119

scriptSig and scriptPubKey are backwards

In "Pour Transfers and Descriptons" section, scriptPubKey has the description that should go on scriptSig and vice-versa.

ZIP 0: Standardize ZIP process

We need to standardize a "Zcash Improvement Proposals" process for making significant changes to Zcash's protocol or even minor changes to the zk-SNARK circuit.

Note: We should not adopt a ZIP process in our development efforts until a public beta.

Specify that vpub_in and vpub_out must not both be nonzero

See zcash/zcash#466

Change memo field size to 512 bytes

Per zcash/zcash#85 (comment)

Add versioning to the coin commitment.

Specify handling of zero-value note input slots

Moved from zcash/zcash#700.

This is an important security-critical change to the circuit and protocol. If we get the details wrong then it could allow attacks that violate balance or (less seriously, but still contrary to the intent) allow distinguishing transactions with different numbers of real input coins.

The circuit change was implemented in Electric-Coin-Company/libzerocash@ab777ba . More detail is on zcash/zcash#700 .

Add 8-bit 'Memo Type' to indicate type of data in Memo Field

Add an 8-bit field 'Memo Type' to:

• enable the 'Memo Field' to store 128 bytes of raw data, without the need for a 0xF5 start byte
• make it easier for applications to determine/hint at the type of data

Formally recognised values for 'Memo Type' could be:

• 0x00 = there is no memo field (thereby reducing size of note plaintext)
• 0x01 = raw data (arbitrary sequence of 128 bytes)
• 0x02 = UTF-8 encoded byte sequence (128 bytes, padded with trailing zero bytes)
• 0x03 - 0x1F = reserved for Zcash extensions or other memo types in the future
• 0x20 - 0xFF = free for community to use

The encoding of a note plaintext could look like:
[8-bit version] [8-bit memo type] [64-bit v] [256-bit p] [256-bit r] [memo 128 bytes]

The 'Memo Type' field is positioned after the version byte to keep subsequent fields on word boundaries.

ZIP: Specify Payment API

Placeholder. See https://zcash.slack.com/archives/paymentapi/p1468977244000002 for a discussion about how to represent amounts. (To do: that archive is not public, copy the relevant parts.)

KDF's Trailing_246(hSig) is wrong

The KDF is going to change when we switch to blake2, but right now it's wrong because it says Trailing246(hSig). I think it should be Trailing254(hSig) to leave two bytes for the i-1 bit and 0.

Switch to little-endian

The current spec uses big-endian encoding, but Bitcoin serialization uses little-endian (and so does Curve25519 / AEAD_CHACHA20_POLY1305).

Add "Procedure" section to protocol spec.

A Procedure section will specify "canonical" storage structures and algorithms which implement the protocol. For example, there should be an inductive procedure for "Verify Block".

Implementations may use different data structures/algorithms, and this section should strive to define the simplest to specify data structures and algorithms, rather than the most efficient. If there is a discrepency between an efficient real-world implementation and an algorithm here which affects the protocol, then we need to go through a rigorous process for altering the protocol if we deem it necessary. If there's a discrepency in implementation vs "canonical algorithm" that does not affect the protocol, then the canonical algorithm should either be simplified until there's no discrepency, or we add a footnote about the discrepency, or we change the canonical algorithm to be more complex.

Also, a given canonical algorithm/data-structures will imply a set of invariants / preconditions / postconditions. Those should be explicitly documented also in this spec.

Slack: add github notifications for zcash/zips

Cross-repo duplicate of:

zcash/zcash#923

I'm mainly testing out the slack integration with this ticket.

Distinguish between standard and consensus rules

Should KDF have a 1-byte prefix?

0xC2?

Document security issues around selection of commitment tree root for senders and receivers.

Address "intended usage" descriptions in the protocol

Eli noted a lot of "intended usage" in our protocol spec. Basically, the protocol.pdf is written from an implementers perspective where the reader is assumed to be the full node and we discuss what the reader should / shouldn't do given what it sees from other parties in the protocol. In order to do a proper security review, the reader needs to make a mental leap along the lines of "I'm like this, and there are a lot of other people like this, but they might not behave exactly like this, and some might behave nothing like this."

We can fix this by separating the protocol into three parts:

1. Define what a full node's state is. We have the blockchain, the nullifier set, a list of unspent notes, etc.
2. Define the types of messages full nodes receive. Blocks, which contain transactions, which contain JoinSplits.
3. Define how those messages affect the full node's state. For example a new block will cause all of its transactions to get "executed" and upon execution a transaction can cause..., and so on.

This is sort of like what the Zerocash paper does, except (1) and (2) aren't separated in the Zerocash paper. An advantage is that there'll be a more 1:1 mapping between sections of the paper and parts of the code (e.g. in (1) we can list the files where those data structures are implemented). A disadvantage is that it would take me a lot longer to understand the protocol if I had to read it this way, which is why it took me so long to understand it from the Zerocash paper, but OTOH I would be able to implement it from the spec without even understanding it.

This is related to #32. I'm not sure if this would address Eli's comments, since transactions still have agency (they're seen as programs running on full node weird machines).

Specify the AEAD_CHACHA20_POLY1305 Key size in section 6.1 Encryption

We should mention that the key is 256-bits. I had to look up the RFC to make sure it was, since if it was only 128 bits keys could collide. I suppose this is implied by the output sizes of KDF and PRF^dk but I'm not that clever!

[protocol spec] Be explicit about the "Value pool" algorithm

The "Value pool" sentence is kind of vague, maybe we should specify the algorithm for it. It's important because it's how a pour's validity is bound to a transaction's validity.

Should the viewkey holder be able to recover the entire recipient address?

It would be nice for UX if the viewkey holder could see the full address the coin was sent to. I don't think there's a way to do that in the current design; I don't see a way to get the recipient's a_pk.

Specify moving ciphertexts to the end of a JoinSplit description

As suggested by @jl777 in zcash/zcash#991 (comment)

Add a version changelog appendix.

Let's add an appendix that is kind of a changelog of each version. Actually this might go up front as I've seen in other specs. We've already had some people asking about version 1, so this section would describe that as as an imprecisely specified predecessor design (and also version 0, which was the academic prototype).

Add explicit version to protocol spec

The versions need to be unambiguous between each other and they shouldn't be confused with Zcash code release versions.

Maybe for long-hand, spoken English "Zcash protocol v${NUMBER} aka $CODENAME" and for short hand: "zcp${NUMBER}", so for example: "Zcash protocol v2 aka Trafford" or "zcp2" for shorthand.

For our software releases we'll have "Zcash zc.v0.11.2.z7". (I'm not sure how to say that in English, which is a problem...) :-/

Is authenticated encryption for coins useful?

The holder of a_vk knows the symmetric keys used to encrypt the coins, and so they can modify them (potentially to make them unspendable). They can't actually do it, because the transaction non-malleability stops them from changing the ciphertexts.

So, if the coin is sent through a different channel, and still disclosed to the viewkey holder, there's an additional assumption that the viewkey holder didn't intercept the second channel and change the coin. We should document that.

Another question is: Assuming the coins are sent in-band, why do they need to be encrypted with an authenticated mode? Shouldn't the transaction non-malleability catch any changes? If we couldn't safely use a non-authenticated mode for coins in transactions, then the a_vk holder has some kind of extra power even in the in-band case.

Pours go in transactions inside blocks

"A Pour description is data included in a block that describes a Pour transfer..."

That's true, but maybe it's more accurate to say they're included in transactions, and transactions are included in blocks.

Address Eli's review comments about transactions

We confusingly attribute agency to transactions.

Improve pagination in spec

This should be done after other necessary edits.

Change JoinSplit signatures to use Ed25519

See zcash/zcash#977

Document changes to header format

See zcash/zcash#991 (comment)

Refactor spec to put instantiations in their own section

As requested by 7S. This would go just before the "Encoding" section.

Specify proof format

The current spec and the paper say 288 bytes (2304 bits), but the output of the prover says "Proof size in bits: 2294". I think the prover output is just not taking into account some padding up to byte boundaries, but it needs checking.

Add licence for zips.

This repo should also have a licence file.

Transaction fields need to be typed

The Bitcoin serialisation format depends on knowledge of the data types of fields, so these need to be specified. See https://bitcoin.org/en/developer-reference#raw-transaction-format and following for examples.

Specify how the Merkle tree is computed

It's not stated that the Merkle tree is computed using CRH. That should be mentioned since it could interact with the other uses of CRH.

SymEncrypt keystream reuse

"Let SymEncrypt_K(P) be ... with empty nonce, and key K"

Using an empty nonce is fine for most of the calls to SymEncrypt, because the ephemeral key pair will be different every time, and therefore the keys will be different every time. However, for the call:

C_i^disclose = SymEncrypt_{a_{vk}}(K^shared)

If an empty nonce is used there, then (according to my quick look at RFC7539) the keystream XORed into K^shared will get reused every time, which is really bad e.g. if I learn a single K^shared I'll be able to decrypt all future and past K^shared that were encrypted to the same a_vk.

There's a formatting issue where the index of the a_vk on the SymEncrypt in that line is at the same subscript level with the "a" in a_vk. It should be separated from the vk with a comma, or put in a subsubsubscript.

Also this sentence which references the nonce is out of date:

The nonce for each ciphertext component depends on the index i. The particular nonce construction is chosen so that a known-nonce distinguisher for Salsa20 would not directly lead to a break of the IK-CCA (key privacy) property.

Specify the Proof of Work

Restore bit/byte ordering examples

Specify constraints on values of a JoinSplit

Also document the difference from Zerocash in the maximum note value (MAX_MONEY, not 2⁶⁴ - 1).

Use HMAC for KDF and hSig

We want to prove that KDF and the way h_sig is computed are both PRFs seeded on dhsecret and randomSeed, respectively. If we move randomSeed to the same place as dhsecret is in the computation of KDF then one proof can cover both functions.

Comments on tech spec

Most comments here are minor, and can be ignored if they do not seem helpful.
Ones marked with ** should be addressed

Introduction:
You say only magneta is differences from zero-cash,
but could not find the concept of nullifier in zero-cash paper.
I think that it matches their serial number.
I would mention that notation and names of objects are different from zerocash paper
sometimes, even if not in magneta

In that context, it might even be good to have a `dictionary' of names here to names in zerocash paper

sec 3.2 :
I would mention that the `i-1' is mod 2

Page 5:
You say pk_{enc} is 256 bytes long,
but by looking at paper Daniel Bernstien paper on curve25519
,it outputs an integer in range {0,..,2^255-19-1}.
So, for example, last bit of pk_{enc} is always 0?

** section 4.2.1
You say earlier you will only apply sha-256 on 512 bit blocks,
but here you are using it on a string of length 840 that is not even a multiple of 512

sec 4.2.3 - add a (See Section 5) first time joinSplit is mentioned as it hasn't been defined yet

Sec 4.5 - say a word about what treestate is intuitively,
First thought that comes to mind is that it is like the merkle tree of all transactions in a block, but here you seem to mean something that describes the merkle tree of all transaction since beginning of time

Sec 5 -
You haven't defined transaction.
From what you write in sec 8.1,
seems a transaction is a union of regular bitcoin transactions,
and some joinSplit operations (i.e., Zcash anonymous transactions).
If this is the case, say it explicitly.
You alternately use the terms joinSplit operation and transaction.
and it can sound like they are two names for the same thing.

Page 10-11:

It's hard to understand without context, what is v^old_pub and v^new_pub.
I am guessing v^old_pub is coins from the non-private part of the chain that are used in the transaction?
This should be explained. I did not see any place where it is explained that we are talking about a chain with public and anonymous coins at the same time

** Page 14 value stored' ->a value stored' or `values stored'

Section 4.2 mentions a "COMM trapdoor" but COMM is not defined

NoteCommitment is defined directly, not in terms of COMM.

Display git revision in protocol.pdf somewhere

This would be helpful, I keep making the mistake of printing a dead-tree copy and then forgetting which version it is.

Eliminate or clarify references to "public" keys and address components

Addresses (and their components) are not inherently public. Limiting their distribution is a valid security decision, and important for anonymity in some use cases. The spec should use terminology that reflects this.

Review of protocol spec

1. In 2.2, Nathan's note could mention that output arity also affects the design there, due to PRF^ρ.
2. In 2.4.1, the text "Any ciphertext components that fail to decrypt with a given recipient's private key will be ignored" needs to be clarified with who, what and why.
3. In 2.4.2, "InternalH" needs a better name. I originally called it this probably as a placeholder. Does the zerocash paper not have a name for it?
4. In 2.7 our description of anchors can be simplified. "A pour description's anchor may reference an earlier block's treestate or the treestate of an earlier pour description." We could also clarify "The treestates of pour descriptions are their anchored trees appended with their commitments" or something, so people know what we mean by their treestates.
5. In 4.5 the text regarding s should be in magenta, and we should also be clear that we differ from zerocash in this respect because we can: a naked commitment is perfectly fine there.

Feel free to close this once you've considered or fixed everything in this ticket.

Complete the section on consensus changes from Bitcoin

See zcash/zcash#991 (comment)

ZIP: Design considerations for protocol upgrades.

What do protocol upgrades look like? Are there forwards compatibility features such as in the block header?