This page is the Simplified Technical English version of ZIP 205. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 205: Deployment of the Sapling Network Upgrade
ZIP: 205 Title: Deployment of the Sapling Network Upgrade Owners: Daira-Emma Hopwood <daira@jacaranda.org> Credits: Simon Liu Status: Final Category: Consensus / Network Created: 2018-10-08 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 terms "consensus branch" and "network upgrade" have the definitions in ZIP 200 [zip-0200].
The terms "Testnet" and "Mainnet" have the definitions in section 3.12 of the Zcash Protocol Specification [protocol-networks].
The term that follows has this definition:
- Sapling
- The code name for the second Zcash network upgrade. Another name for this network upgrade is Network Upgrade 1.
Abstract
This ZIP contains the definition of the deployment of the Sapling network upgrade. It also contains the description of a hard fork that occurred on Testnet. The purpose of that hard fork was to make "minimum-difficulty" blocks possible.
Specification
Sapling deployment
These documents are the primary sources of information about the changes to the consensus protocol for Sapling:
- The Zcash Protocol Specification [protocol].
- Transaction Signature Validation for Sapling [zip-0243].
- Network Upgrade Mechanism [zip-0200].
The mechanisms for the network handshake and for peer management in [zip-0201] also apply to this network upgrade.
The Sapling network upgrade has these network upgrade constants [zip-0200]:
- CONSENSUS_BRANCH_ID
0x76b809bb- ACTIVATION_HEIGHT (Sapling)
Testnet: 280000
Mainnet: 419200
On Testnet, Sapling activated before this block height, but that consensus branch was rolled back. A hard fork occurred on Testnet after that. In this hard fork, the difficulty algorithm changed. From block height 299188, "minimum-difficulty" blocks are accepted in some conditions.
On Mainnet and on Testnet, Sapling-compatible nodes must advertise protocol version 170007 or later. The minimum peer protocol version that Sapling-compatible nodes connect to stays 170002.
Pre-Sapling nodes are nodes that advertise a protocol version less than 170007.
Approximately three days before the Sapling activation height, Sapling-compatible nodes change the behavior of their peer connection logic. (This period is defined in terms of block height.) After the change, these nodes prefer pre-Sapling peers for eviction from the set of peer connections.
/** The period before a network upgrade activates, where connections to upgrading peers are preferred (in blocks). */ static const int NETWORK_UPGRADE_PEER_PREFERENCE_BLOCK_PERIOD = 24 * 24 * 3;
The implementation is almost the same as the implementation for Overwinter. The description of the Overwinter implementation is in [zip-0201].
After the activation of Sapling on Testnet or Mainnet, we recommend that Sapling nodes take steps to do these two tasks:
- Reject new connections from pre-Sapling nodes.
- Disconnect all existing connections to pre-Sapling nodes.
Change to difficulty adjustment on Testnet
Section 7.6.3 of the Zcash Protocol Specification [protocol-diffadjustment] contains the description of the difficulty adjustment algorithm for a block. (The difficulty is defined in terms of a "target threshold".) The adjustment depends on the nTime and nBits fields of previous blocks.
On Testnet, this algorithm changed from block 299188, to make "minimum-difficulty" blocks possible. The definition that follows applies to a block at this block height or at a higher block height. The block is a minimum-difficulty block if its block time is more than 15 minutes after the block time of the previous block. In that case, the nBits field of the block must be equal to ToCompact(PoWLimit).
PoWLimit is the value that is defined for Testnet in section 5.3 of the Zcash Protocol Specification [protocol-constants]. The definition of ToCompact is in section 7.7.4 of that specification [protocol-nbits].
Note: An earlier revision of this ZIP contained an incorrect statement. The statement was that the change has an effect only on the target threshold of minimum-difficulty blocks. In fact, the nBits field also changes. This changed nBits field has an effect on the difficulty adjustment for later blocks.
This change does not have an effect on Mainnet.
Backward compatibility
Before the activation of the network upgrade, Sapling nodes and pre-Sapling nodes are compatible and can connect to each other. But Sapling nodes prefer to connect to other Sapling nodes. Thus Sapling nodes gradually disconnect pre-Sapling nodes in the period before activation.
After the activation of the network upgrade, pre-Sapling nodes can continue to accept the numerically larger protocol version of Sapling as valid. But after activation, Sapling nodes always disconnect peers that use lower protocol versions.
Support in zcashd
Support for the Sapling consensus rules was implemented in zcashd version 2.0.0. Most of the support for RPC calls and persistence of Sapling z-addresses was implemented in version 2.0.1. These two versions advertise protocol version 170007.
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-constants]
- Zcash Protocol Specification, Version 2021.2.16. Section 5.3: Constants
- [protocol-diffadjustment]
- Zcash Protocol Specification, Version 2021.2.16. Section 7.7.3: Difficulty adjustment
- [protocol-nbits]
- Zcash Protocol Specification, Version 2021.2.16. Section 7.7.4: nBits conversion
- [zip-0200]
- ZIP 200: Network Upgrade Mechanism
- [zip-0201]
- ZIP 201: Network Peer Management for Overwinter
- [zip-0243]
- ZIP 243: Transaction Signature Validation for Sapling