This page is the Simplified Technical English version of ZIP 250. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 250: Deployment of the Heartwood Network Upgrade
ZIP: 250 Title: Deployment of the Heartwood 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].
These terms have the definitions that follow:
- Heartwood
- The code-name of the fourth Zcash network upgrade. This network upgrade also has the name Network Upgrade 3.
- Testnet
- The Zcash test network. Its definition is in [protocol].
- Mainnet
- The Zcash production network. Its definition is in [protocol].
Abstract
This ZIP contains the definition of the deployment of the Heartwood network upgrade.
Specification
Heartwood deployment
The primary sources of information about the consensus protocol changes for Heartwood are:
- The Zcash Protocol Specification [protocol]
- ZIP 200: Network Upgrade Mechanism [zip-0200]
- ZIP 213: Shielded Coinbase [zip-0213]
- ZIP 221: FlyClient - Consensus-Layer Changes [zip-0221].
The network handshake and peer management mechanisms in ZIP 201 [zip-0201] also apply to this network upgrade.
These are the network upgrade constants [zip-0200] for the Heartwood network upgrade:
- CONSENSUS_BRANCH_ID
0xF5B9230B- ACTIVATION_HEIGHT (Heartwood)
-
Testnet: 903800
Mainnet: 903000
Nodes that are compatible with Heartwood activation on testnet must advertise protocol version 170010 or later. Nodes that are compatible with Heartwood activation on mainnet must advertise protocol version 170011 or later. The minimum peer protocol version that Heartwood-compatible nodes connect to is 170002.
Pre-Heartwood testnet nodes are nodes on testnet that advertise a protocol version less than 170010. Pre-Heartwood mainnet nodes are nodes on mainnet that advertise a protocol version less than 170011.
For each network (testnet and mainnet), nodes that are compatible with Heartwood activation on that network change the behaviour of their peer connection logic. The nodes make this change approximately 1.5 days before the Heartwood activation height of that network. (The 1.5 days are defined in terms of block height.) With this change, the nodes prefer pre-Heartwood 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 Overwinter implementation is in [zip-0201].
After Heartwood activation on testnet or mainnet, we recommend that Heartwood nodes take steps to do these two things:
- Reject new connections from pre-Heartwood nodes on that network.
- Disconnect all existing connections to pre-Heartwood nodes on that network.
Backward compatibility
Before the activation of the network upgrade on each network, Heartwood nodes and pre-Heartwood nodes are compatible and can connect to each other. But Heartwood nodes prefer to connect to other Heartwood nodes. Thus pre-Heartwood nodes are gradually disconnected in the period before activation.
After the activation of the network upgrade, pre-Heartwood nodes can still accept the numerically larger protocol version of Heartwood as valid. But after that activation, Heartwood nodes always disconnect peers that use lower protocol versions.
There is no new transaction version for Heartwood. In this, Heartwood is different from Overwinter and Sapling, and the same as Blossom. Thus Heartwood transactions are in the same v4 format as Sapling transactions. Heartwood transactions also have the same version group ID as Sapling transactions. That is, the version group ID is 0x892F2085, as defined in section 7.1 of [protocol]. The transaction digest algorithm for Heartwood transactions is also the same as for Sapling transactions, as defined in [zip-0243].
This does not mean that transactions are valid across the Heartwood activation, because the applicable consensus branch ID must be used for signatures [zip-0243].
Support in zcashd
The support for Heartwood on testnet is in zcashd version 2.1.2. That zcashd version advertises protocol version 170010. The support for Heartwood on mainnet is in zcashd version 3.0.0. That zcashd version advertises protocol version 170011.
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
- [zip-0200]
- ZIP 200: Network Upgrade Mechanism
- [zip-0201]
- ZIP 201: Network Peer Management for Overwinter
- [zip-0213]
- ZIP 213: Shielded Coinbase
- [zip-0221]
- ZIP 221: FlyClient - Consensus-Layer Changes
- [zip-0243]
- ZIP 243: Transaction Signature Validation for Sapling