This page is the Simplified Technical English version of ZIP 251. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 251: Deployment of the Canopy Network Upgrade
ZIP: 251 Title: Deployment of the Canopy Network Upgrade Owners: Daira-Emma Hopwood <daira@jacaranda.org> Status: Final Category: Consensus / Network Created: 2020-02-28 License: MIT
Terminology
On this page, STE words are in the place of the BCP 14 key words of the source. Refer to the key word table.
In this document, the term "network upgrade" has the definition in ZIP 200 [zip-0200].
In this document, the terms "Testnet" and "Mainnet" have the definitions in section 3.12 of the Zcash Protocol Specification [protocol-networks].
"Canopy" is the code-name of the fifth Zcash network upgrade. This network upgrade also has the name Network Upgrade 4.
Abstract
This ZIP contains the definition of the deployment of the Canopy network upgrade.
Specification
Canopy deployment
The primary sources of information about the consensus protocol changes for Canopy are:
- The Zcash Protocol Specification [protocol]
- ZIP 200: Network Upgrade Mechanism [zip-0200]
- ZIP 207: Funding Streams [zip-0207]
- ZIP 211: Disabling Addition of New Value to the Sprout Value Pool [zip-0211]
- ZIP 212: Allow Recipient to Derive Sapling Ephemeral Secret from Note Plaintext [zip-0212]
- ZIP 214: Consensus rules for a Zcash Development Fund [zip-0214]
- ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules [zip-0215]
- ZIP 1014: Establishing a Dev Fund for ECC, ZF, and Major Grants [zip-1014].
The network handshake mechanism and the peer management mechanism in ZIP 201 [zip-0201] also apply to this network upgrade.
These are the network upgrade constants [zip-0200] for the Canopy network upgrade:
- CONSENSUS_BRANCH_ID
0xE9FF75A6- ACTIVATION_HEIGHT (Canopy)
-
Testnet: 1028500
Mainnet: 1046400
Nodes that are compatible with Canopy activation on testnet must advertise protocol version 170012 or later. Nodes that are compatible with Canopy activation on mainnet must advertise protocol version 170013 or later. The minimum peer protocol version that Canopy-compatible nodes connect to is 170002.
Pre-Canopy testnet nodes are nodes on testnet that advertise a protocol version less than 170012. Pre-Canopy mainnet nodes are nodes on mainnet that advertise a protocol version less than 170013.
For each network (testnet and mainnet), nodes that are compatible with Canopy activation on that network change the behaviour of their peer connection logic. The nodes make this change approximately 1.5 days before the Canopy activation height of that network. (The 1.5 days are defined in terms of block height.) With this change, the nodes prefer pre-Canopy peers on that network for eviction from the set of peer connections:
/** * The period before a network upgrade activates, where connections to upgrading peers are preferred (in blocks). * This was three days for upgrades up to and including Blossom, and is 1.5 days from Heartwood onward. */ static const int NETWORK_UPGRADE_PEER_PREFERENCE_BLOCK_PERIOD = 1728;
The implementation is similar to the implementation for Overwinter. The description of the implementation for Overwinter is in [zip-0201].
After Canopy activation on testnet or mainnet, we recommend that Canopy nodes take steps to do these two things:
- Reject new connections from pre-Canopy nodes on that network.
- Disconnect all existing connections to pre-Canopy nodes on that network.
Backward compatibility
Before the activation of the network upgrade on each network, Canopy nodes and pre-Canopy nodes are compatible and can connect to each other. But Canopy nodes prefer to connect to other Canopy nodes. Thus Canopy nodes gradually disconnect pre-Canopy nodes in the period before activation.
After the activation of the network upgrade, pre-Canopy nodes can still accept the numerically larger protocol version of Canopy as valid. But after that activation, Canopy nodes always disconnect peers that use lower protocol versions.
There is no new transaction version for Canopy. This is different from Overwinter and Sapling, and the same as Blossom and Heartwood. Thus Canopy transactions are in the same v4 format as Sapling transactions. Canopy transactions also have the same version group ID, that is 0x892F2085, as defined in [protocol-txnencoding]. The transaction digest algorithm for Canopy transactions is also the same, as defined in [zip-0243].
This does not mean that transactions are valid across the Canopy activation, because the applicable consensus branch ID must be used for signatures [zip-0243].
Support in zcashd
zcashd version 3.1.0 has support for Canopy on testnet. That zcashd version advertises protocol version 170012. zcashd version 4.0.0 has support for Canopy on mainnet. That zcashd version advertises protocol version 170013.
References
- [BCP14]
- Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
- [protocol]
- Zcash Protocol Specification, Version 2021.2.16 or later
- [protocol-networks]
- Zcash Protocol Specification, Version 2021.2.16. Section 3.12: Mainnet and Testnet
- [protocol-txnencoding]
- Zcash Protocol Specification, Version 2021.2.16. Section 7.1: Transaction Encoding and Consensus
- [zip-0200]
- ZIP 200: Network Upgrade Mechanism
- [zip-0201]
- ZIP 201: Network Peer Management for Overwinter
- [zip-0207]
- ZIP 207: Funding Streams
- [zip-0211]
- ZIP 211: Disabling Addition of New Value to the Sprout Value Pool
- [zip-0212]
- ZIP 212: Allow Recipient to Derive Sapling Ephemeral Secret from Note Plaintext
- [zip-0214]
- ZIP 214: Consensus rules for a Zcash Development Fund
- [zip-0215]
- ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules
- [zip-0243]
- ZIP 243: Transaction Signature Validation for Sapling
- [zip-1014]
- ZIP 1014: Establishing a Dev Fund for ECC, ZF, and Major Grants