Zcash in Simplified Technical English

This page is the Simplified Technical English version of ZIP 252. The source ZIP is the normative text. Read the writing rules to understand the marked words.

ZIP 252: Deployment of the NU5 Network Upgrade

ZIP: 252
Title: Deployment of the NU5 Network Upgrade
Owners: Daira-Emma Hopwood <daira@jacaranda.org>
Original-Authors: Teor
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

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].

In this document, the terms "Testnet" and "Mainnet" have the definitions in section 3.12 of the Zcash Protocol Specification [protocol-networks].

Abstract

This ZIP contains the definition of the deployment of the NU5 network upgrade.

Specification

NU5 deployment

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

The network handshake mechanism and the peer management mechanism in ZIP 201 [zip-0201] also apply to this network upgrade.

The description of unified addresses and viewing keys is in ZIP 316 [zip-0316].

The ZIPs that follow have updates for Orchard. The quantity of change is different for each ZIP:

  • ZIP 32: Shielded Hierarchical Deterministic Wallets [zip-0032]
  • ZIP 203: Transaction Expiry [zip-0203]
  • ZIP 209: Prohibit Out-of-Range Chain Value Pool Balances [zip-0209]
  • ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext [zip-0212]
  • ZIP 213: Shielded Coinbase [zip-0213]
  • ZIP 221: FlyClient - Consensus-Layer Changes [zip-0221]
  • ZIP 401: Addressing Mempool Denial-of-Service [zip-0401]

These are the network upgrade constants [zip-0200] for the NU5 network 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 occurred on Testnet at block height 1599200. That activation had a previous version of the Orchard circuit and other NU5 consensus rules. It had the consensus branch ID 0x37519621 and the peer protocol version 170015.

With the release of zcashd v4.7.0, Testnet is rolled back to another chain. The fork point of this chain is the block immediately before that activation, at block height 1599199. zcashd v4.0.0 nodes mined this chain continuously. These nodes were modified to disable the End-of-Service halt.

For each network (Testnet and Mainnet), this requirement applies to the nodes compatible with NU5 activation on that network. These nodes 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 nodes that advertise a protocol version less than the MIN_NETWORK_PROTOCOL_VERSION (NU5) of that network.

After NU5 activates on Testnet or Mainnet, we recommend that NU5 nodes take steps to do these two things:

  • Reject new connections from pre-NU5 nodes on that network.
  • Disconnect all existing connections to pre-NU5 nodes on that network.

The change to the peer-to-peer protocol in ZIP 239 started at peer protocol version 170014, on both Testnet and Mainnet. The change applies to all later versions also. [zip-0239]

Backward compatibility

Before the network upgrade activates on each network, NU5 nodes and pre-NU5 nodes are compatible and can connect to each other. (On Testnet, there was a long period of network fracturing because of a consensus bug. This problem is expected to be solved with the release of zcashd v4.7.0.)

After the network upgrade activates, pre-NU5 nodes can still accept the numerically larger protocol version of NU5 as valid. But NU5 nodes always disconnect peers that use lower protocol versions.

NU5 has a new transaction version. In this, NU5 is the same as Overwinter and Sapling. In this, NU5 is different from these network upgrades:

Because of the new transaction version, NU5 transactions can be in the new v5 format of [zip-0225]. After NU5 activation, the existing v4 transaction format stays valid. This is different from previous transaction version updates. NU5 nodes must accept both transaction formats.

The new MSG_WTX inv type is for inv and getdata messages. The discussion of its backward compatibility is in [zip-0239].

Support in zcashd

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

zcashd version 5.0.0 implements support for NU5 on Mainnet. This version advertises protocol version 170100.

Backward compatibility in zcashd

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

NU5 deployment for zcashd

For each network, nodes that are compatible with NU5 activation on that network change the behaviour of their peer connection logic. The nodes make this change approximately 1.5 days before the NU5 activation height of that network. (The 1.5 days are defined in terms of block height.) With this change, the nodes 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 the implementation for Overwinter. The description of the Overwinter implementation is in [zip-0201].

But NU5 nodes prefer to connect to other NU5 nodes. Thus pre-NU5 nodes are gradually disconnected in the period before activation.

Support in Zebra

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

zebrad version v1.0.0-beta.10 implements support for NU5 on Mainnet. This version advertises protocol version 170100.

Backward compatibility in Zebra

The minimum peer protocol version that NU5-compatible Zebra nodes connect to is 170002. These nodes immediately disconnect from nodes that advertise a peer protocol version less than these values:

  • 170040 on Testnet.
  • 170013 on Mainnet.

NU5 deployment for Zebra

For each network, nodes that are compatible with NU5 activation on that network do two things at the NU5 activation height of that network:

  • They close existing connections with pre-NU5 peers.
  • They reject new connections from pre-NU5 peers.

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 [NU5 proposal]. Section 3.12: Mainnet and Testnet
[protocol-txnencoding]
Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 7.1: Transaction Encoding and Consensus
[zip-0032]
ZIP 32: Shielded Hierarchical Deterministic Wallets
[zip-0200]
ZIP 200: Network Upgrade Mechanism
[zip-0201]
ZIP 201: Network Peer Management for Overwinter
[zip-0203]
ZIP 203: Transaction Expiry
[zip-0209]
ZIP 209: Prohibit Out-of-Range Chain Value Pool Balances
[zip-0212]
ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext
[zip-0213]
ZIP 213: Shielded Coinbase
[zip-0216]
ZIP 216: Require Canonical Point Encodings
[zip-0221]
ZIP 221: FlyClient - Consensus-Layer Changes
[zip-0224]
ZIP 224: Orchard Shielded Protocol
[zip-0225]
ZIP 225: Version 5 Transaction Format
[zip-0239]
ZIP 239: Relay of Version 5 Transactions
[zip-0244]
ZIP 244: Transaction Identifier Non-Malleability
[zip-0316]
ZIP 316: Unified Addresses and Unified Viewing Keys
[zip-0401]
ZIP 401: Addressing Mempool Denial-of-Service
[orchard-book]
The Orchard Book
[halo2-book]
The halo2 Book