2020-03-10 14:49:50 -07:00
::
ZIP: 251
2020-05-26 15:05:21 -07:00
Title: Deployment of the Canopy Network Upgrade
2023-03-02 04:13:07 -08:00
Owners: Daira Emma Hopwood <daira@electriccoin.co>
2022-06-22 14:35:03 -07:00
Status: Final
2020-11-14 14:06:46 -08:00
Category: Consensus / Network
2020-03-10 14:49:50 -07:00
Created: 2020-02-28
License: MIT
Terminology
===========
The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be
2023-10-28 07:34:22 -07:00
interpreted as described in BCP 14 [#BCP14]_ when, and only when, they appear in
all capitals.
2020-03-10 14:49:50 -07:00
The term "network upgrade" in this document is to be interpreted as described in
ZIP 200. [#zip-0200]_
2020-07-05 09:17:59 -07:00
The terms "Testnet" and "Mainnet" are to be interpreted as described in
2021-10-01 16:44:09 -07:00
section 3.12 of the Zcash Protocol Specification [#protocol-networks]_ .
2020-03-10 14:49:50 -07:00
2020-07-05 09:17:59 -07:00
"Canopy" is the code-name for the fifth Zcash network upgrade, also known as
Network Upgrade 4.
2020-03-10 14:49:50 -07:00
Abstract
========
2020-05-26 15:05:21 -07:00
This proposal defines the deployment of the Canopy network upgrade.
2020-03-10 14:49:50 -07:00
Specification
=============
2020-05-26 15:05:21 -07:00
Canopy deployment
2020-03-10 14:49:50 -07:00
-----------------
2020-05-26 15:05:21 -07:00
The primary sources of information about Canopy consensus protocol changes are:
2020-03-10 14:49:50 -07:00
- The Zcash Protocol Specification [#protocol]_
- ZIP 200: Network Upgrade Mechanism [#zip-0200]_
- ZIP 207: Funding Streams [#zip-0207]_
2020-06-02 10:34:35 -07:00
- 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]_
2020-03-10 14:49:50 -07:00
- ZIP 214: Consensus rules for a Zcash Development Fund [#zip-0214]_
2020-06-09 04:56:33 -07:00
- ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules [#zip-0215]_
2020-06-02 10:34:35 -07:00
- ZIP 1014: Establishing a Dev Fund for ECC, ZF, and Major Grants [#zip-1014]_ .
2020-03-10 14:49:50 -07:00
The network handshake and peer management mechanisms defined in ZIP 201 [#zip-0201]_
also apply to this upgrade.
2020-05-26 15:05:21 -07:00
The following network upgrade constants [#zip-0200]_ are defined for the Canopy
2020-03-10 14:49:50 -07:00
upgrade:
2020-03-16 12:52:48 -07:00
CONSENSUS_BRANCH_ID
2020-06-02 10:34:35 -07:00
`` 0xE9FF75A6 ``
2020-03-10 14:49:50 -07:00
2020-05-26 15:05:21 -07:00
ACTIVATION_HEIGHT (Canopy)
2020-07-24 17:59:04 -07:00
Testnet: 1028500
2020-03-10 14:49:50 -07:00
Mainnet: 1046400
2020-05-26 15:05:21 -07:00
Nodes compatible with Canopy activation on testnet MUST advertise protocol version
2020-06-02 10:34:35 -07:00
170012 or later. Nodes compatible with Canopy activation on mainnet MUST advertise
protocol version 170013 or later. The minimum peer protocol version that
2020-05-26 15:05:21 -07:00
Canopy-compatible nodes will connect to is 170002.
2020-03-10 14:49:50 -07:00
2020-05-26 15:05:21 -07:00
Pre-Canopy testnet nodes are defined as nodes on testnet advertising a protocol
2020-06-02 10:34:35 -07:00
version less than 170012. Pre-Canopy mainnet nodes are defined as nodes on mainnet
advertising a protocol version less than 170013.
2020-03-10 14:49:50 -07:00
2020-03-26 17:33:21 -07:00
For each network (testnet and mainnet), approximately 1.5 days (defined in terms of
2020-05-26 15:05:21 -07:00
block height) before the corresponding Canopy activation height, nodes compatible
with Canopy activation on that network will change the behaviour of their peer
connection logic in order to prefer pre-Canopy peers on that network for eviction
2020-03-10 14:49:50 -07:00
from the set of peer connections::
2020-03-26 17:33:21 -07:00
/**
* 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;
2020-03-10 14:49:50 -07:00
2020-03-11 09:45:43 -07:00
The implementation is similar to that for Overwinter which was described in
2020-03-10 14:49:50 -07:00
[#zip-0201]_ .
2020-05-26 15:05:21 -07:00
Once Canopy activates on testnet or mainnet, Canopy nodes SHOULD take steps to:
2020-03-10 14:49:50 -07:00
2020-05-26 15:05:21 -07:00
- reject new connections from pre-Canopy nodes on that network;
- disconnect any existing connections to pre-Canopy nodes on that network.
2020-03-10 14:49:50 -07:00
Backward compatibility
======================
2020-05-26 15:05:21 -07:00
Prior to the network upgrade activating on each network, Canopy and pre-Canopy
nodes are compatible and can connect to each other. However, Canopy nodes will
have a preference for connecting to other Canopy nodes, so pre-Canopy nodes will
2020-03-10 14:49:50 -07:00
gradually be disconnected in the run up to activation.
2020-05-26 15:05:21 -07:00
Once the network upgrades, even though pre-Canopy nodes can still accept the
numerically larger protocol version used by Canopy as being valid, Canopy nodes
2020-03-10 14:49:50 -07:00
will always disconnect peers using lower protocol versions.
2020-05-26 15:05:21 -07:00
Unlike Overwinter and Sapling, and like Blossom and Heartwood, Canopy does not
define a new transaction version. Canopy transactions are therefore in the same
2020-03-10 16:18:37 -07:00
v4 format as Sapling transactions; use the same version group ID, i.e. 0x892F2085
2021-10-01 16:44:09 -07:00
as defined in [#protocol-txnencoding]_ ; and use the same transaction digest
2020-03-10 16:18:37 -07:00
algorithm as defined in [#zip-0243]_ . This does not imply that transactions are
2020-05-26 15:05:21 -07:00
valid across the Canopy activation, since signatures MUST use the appropriate
2020-03-10 16:18:37 -07:00
consensus branch ID. [#zip-0243]_
2020-03-10 14:49:50 -07:00
Support in zcashd
=================
2020-05-26 15:05:21 -07:00
Support for Canopy on testnet will be implemented in `` zcashd `` version 3.1.0, which
2020-06-02 10:34:35 -07:00
will advertise protocol version 170012. Support for Canopy on mainnet will be implemented
in `` zcashd `` version 4.0.0, which will advertise protocol version 170013.
2020-03-10 14:49:50 -07:00
References
==========
2023-10-28 07:34:22 -07:00
.. [#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" <https://www.rfc-editor.org/info/bcp14> `_
2021-10-01 16:44:09 -07:00
.. [#protocol] `Zcash Protocol Specification, Version 2021.2.16 or later <protocol/protocol.pdf> `_
.. [#protocol-networks] `Zcash Protocol Specification, Version 2021.2.16. Section 3.12: Mainnet and Testnet <protocol/protocol.pdf#networks> `_
.. [#protocol-txnencoding] `Zcash Protocol Specification, Version 2021.2.16. Section 7.1: Transaction Encoding and Consensus <protocol/protocol.pdf#txnencoding> `_
2021-08-15 15:47:48 -07:00
.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <zip-0200.rst> `_
2020-03-10 14:49:50 -07:00
.. [#zip-0201] `ZIP 201: Network Peer Management for Overwinter <zip-0201.rst> `_
2020-06-09 04:57:46 -07:00
.. [#zip-0207] `ZIP 207: Funding Streams <zip-0207.rst> `_
2020-06-02 10:34:35 -07:00
.. [#zip-0211] `ZIP 211: Disabling Addition of New Value to the Sprout Value Pool <zip-0211.rst> `_
.. [#zip-0212] `ZIP 212: Allow Recipient to Derive Sapling Ephemeral Secret from Note Plaintext <zip-0212.rst> `_
2020-03-10 14:49:50 -07:00
.. [#zip-0214] `ZIP 214: Consensus rules for a Zcash Development Fund <zip-0214.rst> `_
2020-06-09 04:56:33 -07:00
.. [#zip-0215] `ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules <zip-0215.rst> `_
2020-06-09 05:19:59 -07:00
.. [#zip-0243] `ZIP 243: Transaction Signature Validation for Sapling <zip-0243.rst> `_
2020-03-10 14:49:50 -07:00
.. [#zip-1014] `ZIP 1014: Establishing a Dev Fund for ECC, ZF, and Major Grants <zip-1014.rst> `_