diff --git a/zip-0252.rst b/zip-0252.rst index e3f4f65a..ed9db095 100644 --- a/zip-0252.rst +++ b/zip-0252.rst @@ -5,4 +5,138 @@ Owners: Daira Hopwood Status: Draft Category: Consensus / Network - Discussions-To: + Created: 2020-02-28 + License: MIT + + +Terminology +=========== + +The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be +interpreted as described in RFC 2119. [#RFC2119]_ + +The term "network upgrade" in this document is to be interpreted as described in +ZIP 200. [#zip-0200]_ + +The terms "Testnet" and "Mainnet" are to be interpreted as described in +section 3.11 of the Zcash Protocol Specification [#protocol-networks]_. + +"Canopy" is the code-name for the fifth Zcash network upgrade, also known as +Network Upgrade 4. + + +Abstract +======== + +This proposal defines the deployment of the Canopy network upgrade. + + +Specification +============= + +Canopy deployment +----------------- + +The primary sources of information about Canopy consensus protocol changes 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 and peer management mechanisms defined in ZIP 201 [#zip-0201]_ +also apply to this upgrade. + + +The following network upgrade constants [#zip-0200]_ are defined for the Canopy +upgrade: + +CONSENSUS_BRANCH_ID + ``0xE9FF75A6`` + + +ACTIVATION_HEIGHT (Canopy) + Testnet: 1028500 + + Mainnet: 1046400 + + +Nodes compatible with Canopy activation on testnet MUST advertise protocol version +170012 or later. Nodes compatible with Canopy activation on mainnet MUST advertise +protocol version 170013 or later. The minimum peer protocol version that +Canopy-compatible nodes will connect to is 170002. + +Pre-Canopy testnet nodes are defined as nodes on testnet advertising a protocol +version less than 170012. Pre-Canopy mainnet nodes are defined as nodes on mainnet +advertising a protocol version less than 170013. + +For each network (testnet and mainnet), approximately 1.5 days (defined in terms of +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 +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 that for Overwinter which was described in +[#zip-0201]_. + +Once Canopy activates on testnet or mainnet, Canopy nodes SHOULD take steps to: + +- reject new connections from pre-Canopy nodes on that network; +- disconnect any existing connections to pre-Canopy nodes on that network. + + +Backward compatibility +====================== + +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 +gradually be disconnected in the run up to activation. + +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 +will always disconnect peers using lower protocol versions. + +Unlike Overwinter and Sapling, and like Blossom and Heartwood, Canopy does not +define a new transaction version. Canopy transactions are therefore in the same +v4 format as Sapling transactions; use the same version group ID, i.e. 0x892F2085 +as defined in [#protocol-txnencodingandconsensus]_; and use the same transaction digest +algorithm as defined in [#zip-0243]_. This does not imply that transactions are +valid across the Canopy activation, since signatures MUST use the appropriate +consensus branch ID. [#zip-0243]_ + + +Support in zcashd +================= + +Support for Canopy on testnet will be implemented in ``zcashd`` version 3.1.0, which +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. + + +References +========== + +.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ +.. [#protocol] `Zcash Protocol Specification, Version 2020.1.15 or later `_ +.. [#protocol-networks] `Zcash Protocol Specification, Version 2020.1.15. Section 3.11: Mainnet and Testnet `_ +.. [#protocol-txnencodingandconsensus] `Zcash Protocol Specification, Version 2020.1.15. Section 7.1: Transaction Encoding and Consensus `_ +.. [#zip-0200] `ZIP 200: Network Upgrade Activation 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 `_