ZIP: 252
Title: Deployment of the NU5 Network Upgrade
Owners: teor <teor@zfnd.org>
        Daira-Emma Hopwood <daira-emma@electriccoin.co>
Status: Final
Category: Consensus / Network
Created: 2021-02-23
License: MIT
Discussions-To: <https://github.com/zcash/zips/issues/440>
Pull-Request: <https://github.com/zcash/zips/pull/446>

Terminology

The key words "MUST" and "SHOULD" in this document are to be interpreted as described in BCP 14 1 when, and only when, they appear in all capitals.

The term "network upgrade" in this document is to be interpreted as described in ZIP 200. 6

The terms "Testnet" and "Mainnet" are to be interpreted as described in section 3.12 of the Zcash Protocol Specification 3.

Abstract

This proposal defines the deployment of the NU5 network upgrade.

Specification

NU5 deployment

The primary sources of information about NU5 consensus and peer-to-peer protocol changes are:

  • The Zcash Protocol Specification 2 4
  • ZIP 200: Network Upgrade Mechanism 6
  • ZIP 216: Require Canonical Point Encodings 12
  • ZIP 224: Orchard Shielded Protocol 14
  • ZIP 225: Version 5 Transaction Format 15
  • ZIP 239: Relay of Version 5 Transactions 16
  • ZIP 244: Transaction Identifier Non-Malleability 17
  • The Orchard Book 20
  • The halo2 Book 21

The network handshake and peer management mechanisms defined in ZIP 201 7 also apply to this upgrade.

Unified addresses and viewing keys are described in ZIP 316 18.

The following ZIPs have been updated in varying degrees to take into account Orchard:

  • ZIP 32: Shielded Hierarchical Deterministic Wallets 5
  • ZIP 203: Transaction Expiry 8
  • ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances 9
  • ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext 10
  • ZIP 213: Shielded Coinbase 11
  • ZIP 221: FlyClient - Consensus-Layer Changes 13
  • ZIP 401: Addressing Mempool Denial-of-Service 19

The following network upgrade constants 6 are defined for the NU5 upgrade:

CONSENSUS_BRANCH_ID
0xc2d6d0b4
ACTIVATION_HEIGHT (NU5)

Testnet (second activation): 1842420

Mainnet: 1687104

MIN_NETWORK_PROTOCOL_VERSION (NU5)

Testnet (second activation): 170050

Mainnet: 170100

Note: A first activation of NU5, with a previous version of the Orchard circuit and other NU5 consensus rules, occurred on Testnet at block height 1599200 with consensus branch ID 0x37519621 and peer protocol version 170015. With the release of zcashd v4.7.0, Testnet is being rolled back to another chain that forks from the block immediately preceding that activation, at height 1599199. This chain had been continuously mined by zcashd v4.0.0 nodes modified to disable End-of-Service halt.

For each network (Testnet and Mainnet), nodes compatible with NU5 activation on that network MUST advertise a network protocol version that is greater than or equal to the MIN_NETWORK_PROTOCOL_VERSION (NU5) for that activation.

For each network, pre-NU5 nodes are defined as nodes advertising a protocol version less than that network's MIN_NETWORK_PROTOCOL_VERSION (NU5).

Once NU5 activates on Testnet or Mainnet, NU5 nodes SHOULD take steps to:

  • reject new connections from pre-NU5 nodes on that network;
  • disconnect any existing connections to pre-NU5 nodes on that network.

The change to the peer-to-peer protocol described in ZIP 239 took effect from peer protocol version 170014 onward, on both Testnet and Mainnet. 16

Backward compatibility

Prior to the network upgrade activating on each network, NU5 and pre-NU5 nodes are compatible and can connect to each other. (In the case of Testnet, there was a prolonged period of network fracturing due to a consensus bug, but this is expected to be resolved with the release of zcashd v4.7.0.)

Once the network upgrades, even though pre-NU5 nodes can still accept the numerically larger protocol version used by NU5 as being valid, NU5 nodes will always disconnect peers using lower protocol versions.

Unlike Blossom, Heartwood, and Canopy, and like Overwinter and Sapling, NU5 defines a new transaction version. Therefore, NU5 transactions MAY be in the new v5 format specified by 15. Unlike previous transaction version updates, the existing v4 transaction format remains valid after NU5 activation. Both transaction formats MUST be accepted by NU5 nodes.

Backward compatibility of the new MSG_WTX inv type introduced for inv and getdata messages is discussed in 16.

Support in zcashd

Several versions of zcashd have implemented versions of the NU5 consensus rules on Testnet:

Support for NU5 on Mainnet will be implemented in zcashd version 5.0.0, which will advertise protocol version 170100.

Backward compatibility in zcashd

The minimum peer protocol version that NU5-compatible zcashd nodes will connect to is 170002. On Testnet, they will immediately disconnect from nodes advertising a peer protocol version less than 170040.

NU5 deployment for zcashd

For each network, approximately 1.5 days (defined in terms of block height) before the corresponding NU5 activation height, nodes compatible with NU5 activation on that network will change the behaviour of their peer connection logic in order to prefer pre-NU5 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 7.

However, NU5 nodes will have a preference for connecting to other NU5 nodes, so pre-NU5 nodes will gradually be disconnected in the run up to activation.

Support in Zebra

Several versions of Zebra have implemented versions of the NU5 consensus rules on Testnet:

Support for NU5 on Mainnet will be implemented in zebrad version v1.0.0-beta.10, which will advertise protocol version 170100.

Backward compatibility in Zebra

The minimum peer protocol version that NU5-compatible Zebra nodes will connect to is 170002. They will immediately disconnect from nodes advertising a peer protocol version less than:

  • 170040 on Testnet, or
  • 170013 on Mainnet.

NU5 deployment for Zebra

For each network, at the corresponding NU5 activation height, nodes compatible with NU5 activation on that network will close existing connections with pre-NU5 peers, and reject new connections from pre-NU5 peers.

References

1 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"
2 Zcash Protocol Specification, Version 2021.2.16 or later
3 Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 3.12: Mainnet and Testnet
4 Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 7.1: Transaction Encoding and Consensus
5 ZIP 32: Shielded Hierarchical Deterministic Wallets
6 ZIP 200: Network Upgrade Mechanism
7 ZIP 201: Network Peer Management for Overwinter
8 ZIP 203: Transaction Expiry
9 ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances
10 ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext
11 ZIP 213: Shielded Coinbase
12 ZIP 216: Require Canonical Point Encodings
13 ZIP 221: FlyClient - Consensus-Layer Changes
14 ZIP 224: Orchard Shielded Protocol
15 ZIP 225: Version 5 Transaction Format
16 ZIP 239: Relay of Version 5 Transactions
17 ZIP 244: Transaction Identifier Non-Malleability
18 ZIP 316: Unified Addresses and Unified Viewing Keys
19 ZIP 401: Addressing Mempool Denial-of-Service
20 The Orchard Book
21 The halo2 Book