Zcash in Simplified Technical English

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

ZIP 200: Network Upgrade Mechanism

ZIP: 200
Title: Network Upgrade Mechanism
Owners: Jack Grigg <thestr4d@gmail.com>
Status: Final
Category: Consensus
Created: 2018-01-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.

The terms below have these meanings:

Block chain
A sequence of blocks that starts at the genesis block. The header of each block contains a reference to the previous block in the sequence.
Consensus rule set
A set of validation rules. The validity of each block chain depends on these rules.
Consensus rule change
A change in the consensus rule set of the network that has this result: nodes that do not recognize the new rules follow a different block chain.
Consensus branch
A block chain that has a common consensus rule set. The first block in the chain is one of these: the genesis block, or the child of a parent block that was created in accordance with an older set of consensus rules. (That is, the parent block is a member of a different consensus branch.) By definition, each block is a member of a maximum of one consensus branch.
Network upgrade
An intentional consensus rule change that the community makes to improve the network.

Abstract

This ZIP contains the definition of a mechanism to coordinate network upgrades of Zcash. The mechanism has these purposes:

Motivation

Zcash is a consensual currency: nobody will ever force a person to use a specific implementation or a specific consensus branch of Zcash. [consensual-currency] Thus different sub-communities will always have the freedom to select different variants or branches. These variants and branches have different design trade-offs.

The current Zcash software includes an End-of-Service halt feature. With this feature, nodes that run a given version automatically shut down approximately 16 weeks after the release of that version. (Specifically, they shut down at the block height DEPRECATION_HEIGHT that is defined in the source code for that version.) This feature was implemented for these reasons: [release-lifecycle]

Developers can depend on this cadence to coordinate network upgrades. After the last pre-upgrade software version is deprecated, they can reasonably assume this about all node operators on the network: each one supports the upgraded rules, or explicitly decided not to follow them.

But this behavior is not sufficient to do network upgrades. A globally-understood on-chain activation mechanism is necessary. With this mechanism, nodes can know unambiguously when the changes from a network upgrade become effective. (For example, nodes can then enforce consensus rule changes.)

Specification

Each network upgrade has these constants:

CONSENSUS_BRANCH_ID

A globally-unique non-zero 32-bit identifier.

Implementations can use a value of zero in consensus branch ID fields to show the absence of any network upgrade. (That is, the Sprout consensus rules apply.)

ACTIVATION_HEIGHT

A non-zero block height. At this block height, the rules of the network upgrade become effective and are enforced as part of the block chain consensus.

To remove ambiguity: the pre-upgrade consensus rules apply to the block at height ACTIVATION_HEIGHT - 1. If a pre-upgrade consensus branch persists, this block is the last common block.

ACTIVATION_HEIGHT must be greater than the value of DEPRECATION_HEIGHT in the last software version that does not contain support for the network upgrade. We recommend that the selected height is reached approximately three months after the release of the first software version that supports the network upgrade. This recommendation has this reason:

  • At the time of writing (the 1.0.15 release), the release cycle is six weeks long. The End-of-Service halt of a node occurs 16 weeks after release. Thus, if version X contains support for a network upgrade, version X-1 is deprecated 10 weeks after the release of version X. This is approximately 2.3 months. With a three-month window, users have sufficient time to upgrade their nodes after End-of-Service halt. They also have sufficient time to become part of the network again before activation of the network upgrade.

The relationship between CONSENSUS_BRANCH_ID and ACTIVATION_HEIGHT is many-to-one: many different consensus branches can descend from the same parent block (and thus have the same ACTIVATION_HEIGHT). But a specific consensus branch can have only one parent block. Thus, if the ACTIVATION_HEIGHT of a network upgrade is changed for any reason, the CONSENSUS_BRANCH_ID must also be changed. (An example of a reason is the discovery of security vulnerabilities or consensus bugs.)

Activation mechanism

The Zcash block chain is divided into "epochs". Each epoch is a block height interval [ACTIVATION_HEIGHT_N, ACTIVATION_HEIGHT_{N+1}). (That is, the interval includes ACTIVATION_HEIGHT_N and does not include ACTIVATION_HEIGHT_{N+1}.) Consensus rule sets are defined on these intervals.

When a consensus rule depends on activation of a specific network upgrade, the implementation of that rule must be gated by a block height check. The implementation of any network behavior or surrounding code that depends on the rule must also be gated by a block height check. For example:

if (CurrentEpoch(chainActive.Height(), Params().GetConsensus()) == Consensus::UPGRADE_OVERWINTER) {
    // Overwinter-specific logic
} else {
    // Non-Overwinter logic
}

// ...

if (NetworkUpgradeActive(pindex->nHeight, Params().GetConsensus(), Consensus::UPGRADE_OVERWINTER)) {
    // Overwinter consensus rules applied to block
} else {
    // Pre-Overwinter consensus rules applied to block
}

Block validation

Some incoming blocks have a known height, because their parent chain is fully known. These blocks must be validated in accordance with the consensus rules that correspond to the expected consensus branch ID for that height.

Other incoming blocks have unknown heights, because a minimum of one block header in their parent chain is unknown. These blocks can be cached, so that they can be considered again in the future after all their parents are received.

Chain reorganization

A rollback from after the activation height to before that height is possible in a reorganization. Such a reorganization can be handled in the same way as any regular chain orphaning or reorganization, if the new chain is valid.

Post-activation upgrading

This case can occur: a user does not upgrade their node to a compatible software version before the chain is at ACTIVATION_HEIGHT, and the node continues to run. (Usually, this can occur only if the End-of-Service halt is bypassed.) In this case, the node follows any pre-upgrade consensus branch that persists. The node can then download blocks that are incompatible with the post-upgrade consensus branch.

If the user later upgrades their node to a compatible software version, the node considers these blocks to be invalid. If there is a significant number of invalid blocks, we recommend that the node shuts down and tells the user about the issue.

Memory pool

Some transactions are valid only on the post-upgrade consensus branch. While the current chain tip height is less than ACTIVATION_HEIGHT, we recommend that nodes do not accept these transactions.

Some transactions are never valid on the post-upgrade consensus branch. When the current chain tip height becomes equal to ACTIVATION_HEIGHT, we recommend that the node removes these transactions from its local transaction memory pool.

Two-way replay protection

Before the Overwinter network upgrade, two-way replay protection comes from a rule that is enforced post-upgrade. The rule is that the most significant bit of the transaction version is set to 1. [zip-0202] To old nodes, these transactions have a negative version number. A negative version number is invalid in accordance with the old consensus rules. When this rule is enforced, old transactions are trivially invalid on the Overwinter consensus branch.

After the Overwinter network upgrade, two-way replay protection comes from transaction signatures that commit to a specific CONSENSUS_BRANCH_ID. [zip-0143]

Wipe-out protection

Nodes enforce the upgraded consensus rules from ACTIVATION_HEIGHT if they run upgrade-aware software versions. These nodes do not reorganize the chain from that height to a pre-upgrade consensus branch that contains a block that violates the new consensus rules.

But it is necessary to consider the possible edge cases where the old consensus rules and the new consensus rules are not different. For example, a wipe-out can occur if these two conditions are true:

  • The non-upgraded chain contains only empty blocks from ACTIVATION_HEIGHT.
  • The coinbase transactions are valid in accordance with the old consensus rules and the new consensus rules.

The Overwinter network upgrade does not have this issue, because all previous transaction versions become invalid. Thus the coinbase transactions must have the newer transaction version. More generally, this issue can be addressed in a future network upgrade. The method is to change the block header to include a commitment to the CONSENSUS_BRANCH_ID.

Deployment

This ZIP is deployed with the Overwinter network upgrade. [zip-0201]

Backward compatibility

The intentional result of this ZIP is a change that has the name "bilateral consensus rule change". When this mechanism is used, it is necessary that all network participants upgrade their software to a compatible version during the upgrade window. Older software treats post-upgrade blocks as invalid, and follows any pre-upgrade consensus branch that persists.

Reference Implementation

https://github.com/zcash/zcash/pull/2898

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"
[consensual-currency]
Consensual Currency. Electric Coin Company blog
[release-lifecycle]
Release Cycle and Lifetimes. Electric Coin Company blog
Release Cycle Update. Electric Coin Company blog
[zip-0143]
ZIP 143: Transaction Signature Validation for Overwinter
[zip-0201]
ZIP 201: Network Peer Management for Overwinter
[zip-0202]
ZIP 202: Version 3 Transaction Format for Overwinter