Zcash in Simplified Technical English

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

ZIP 201: Network Peer Management for Overwinter

ZIP: 201
Title: Network Peer Management for Overwinter
Owners: Daira-Emma Hopwood <daira@jacaranda.org>
Original-Authors: Simon Liu
Status: Final
Category: Network
Created: 2018-01-15
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 same meanings as in ZIP 200. [zip-0200]

In this document, this term has the meaning that follows:

Overwinter
The code-name for the first Zcash network upgrade. Another name for this network upgrade is Network Upgrade Zero.

Abstract

This ZIP contains the definition of a change to the network handshake and to peer management. This change is necessary for network upgrades that are in accordance with the Network Upgrade Mechanism [zip-0200].

This ZIP is related to these ZIPs:

Motivation

When network upgrades are scheduled, we recommend that nodes on each consensus branch disconnect from nodes on other consensus branches at the activation height. At that height, we recommend that these nodes also accept new inbound connections only from nodes on the same consensus branch.

Specification

A node instantiates a CNode object when it receives a new inbound connection or creates an outbound connection. The node sets the version field of this object to INIT_PROTO_VERSION. The value of INIT_PROTO_VERSION is 209. Nodes do not transmit this value across the network. But this value stays the same, because of legacy reasons and technical debt that are not in the scope of this ZIP.

After the two nodes connect and start the handshake to negotiate the protocol version, each node updates the version field of CNode. In the handshake [bitcoin-version-handshake], the nodes exchange "version" and "verack" messages.

L -> R: Send version message with the local peer's version
R -> L: Send version message back
R -> L: Send verack message
R:      Sets version to the minimum of the 2 versions
L -> R: Send verack message after receiving version message from R
L:      Sets version to the minimum of the 2 versions

To send a version message, the node invokes PushVersion():

void CNode::PushVersion() {
    ...
    PushMessage("version", PROTOCOL_VERSION, nLocalServices, nTime, addrYou, addrMe, ...);
    ...
}

PROTOCOL_VERSION is the highest protocol version that the node supports.

Rejecting Pre-Overwinter Connections

At this time, a node rejects a connection from a peer in this condition: the advertised protocol version of the peer is lower than the minimum protocol version that the node supports.

This is the definition of that minimum value:

//! disconnect from peers older than this proto version
static const int MIN_PEER_PROTO_VERSION = 170002;

This is the implementation of the rejection:

if (pfrom->nVersion < MIN_PEER_PROTO_VERSION)
{
    // disconnect from old peers running protocol version we don't support.

Activation of Overwinter occurs first on testnet. If that activation is successful, activation on mainnet follows.

To prepare for testnet activation, Overwinter nodes contain these constants:

static const int PROTOCOL_VERSION = 170003;
static const int MIN_PEER_PROTO_VERSION = 170002;

A testnet activation height is set in nodes that run protocol version 170003, but a mainnet activation height is not set in these nodes.

On testnet, a node is a pre-Overwinter node if its highest supported protocol version is <= 170002.

With these constants, pre-Overwinter nodes that support protocol version 170002, and Overwinter nodes, can stay connected until the activation. (Before Overwinter activation, Overwinter nodes support the two protocol versions 170002 and 170003.)

To prepare for mainnet activation, Overwinter nodes contain these constants:

static const int PROTOCOL_VERSION = 170005;
static const int MIN_PEER_PROTO_VERSION = 170002;

On mainnet, a node is a pre-Overwinter node if its highest supported protocol version is <= 170004. (A mainnet activation height is not set in nodes that run protocol version 170003 or 170004. The intermediate protocol version 170004 is used to show support for the NODE_BLOOM service bit. The definition of this service bit is in [bip-0111].)

With these constants, pre-Overwinter nodes that support protocol versions 170002 to 170004 inclusive, and Overwinter nodes, can stay connected until the activation. (Before Overwinter activation, Overwinter nodes support protocol versions 170002 to 170005 inclusive.)

It is not possible to change these constants at run-time. Thus, after Overwinter activation on testnet or mainnet, we recommend that Overwinter nodes do these two things:

  • Reject new connections from pre-Overwinter nodes.
  • Disconnect all existing connections to pre-Overwinter nodes.

Network Coalescence

Before the activation of Overwinter, two groups of nodes stay connected with the same consensus rules. The nodes of one group run a pre-Overwinter protocol version (for example, 170002). The nodes of the other group run the Overwinter protocol version (170003 for testnet; 170005 for mainnet). But it is better if nodes that support Overwinter give priority to connections to other nodes that support Overwinter.

The purpose is a smooth partition of the network. The reason is that nodes are then already connected to (a majority of) peers that run the same protocol version. If not, an Overwinter node can lose its connections to Sprout nodes suddenly at the activation height. Then that node can be isolated and susceptible to eclipse attacks. [eclipse-attack]

To help network coalescence before the activation height, we change the eviction process. In the changed process, the eviction of Sprout nodes has a higher priority.

At this time, an eviction process occurs when new inbound connections arrive but the node already has the maximum number of inbound peers:

if (nInbound >= nMaxInbound)
{
    if (!AttemptToEvictConnection(whitelisted)) {
        // No connection to evict, disconnect the new connection
        LogPrint("net", "failed to find an eviction candidate - connection dropped (full)\n");
        CloseSocket(hSocket);
        return;
    }
}

We add behaviour to this process. With this behaviour, pre-Overwinter nodes are the preferred members of the set of eviction candidates. This preference applies when the chain tip is in a period of N blocks before the activation height. This is the definition of N:

/** 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 eviction candidates can be changed as follows:

static bool AttemptToEvictConnection(bool fPreferNewConnection) {
...
// Protect connections with certain characteristics
...
// Check version of eviction candidates...
// If we are connected to any pre-Overwinter nodes, keep them in the eviction set and remove any Overwinter nodes
// If we are only connected to Overwinter nodes, continue with existing behaviour.
if (nActivationHeight > 0 &&
    height < nActivationHeight &&
    height >= nActivationHeight - NETWORK_UPGRADE_PEER_PREFERENCE_BLOCK_PERIOD)
{
    // Find any nodes which don't support Overwinter protocol version
    BOOST_FOREACH(const CNodeRef &node, vEvictionCandidates) {
        if (node->nVersion < params.vUpgrades[Consensus::UPGRADE_OVERWINTER].nProtocolVersion) {
            vTmpEvictionCandidates.push_back(node);
        }
    }

    // Prioritize these nodes by replacing eviction set with them
    if (vTmpEvictionCandidates.size() > 0) {
        vEvictionCandidates = vTmpEvictionCandidates;
    }
}

The existing method to disconnect a candidate stays the same:

vEvictionCandidates[0]->fDisconnect = true;

In the existing eviction process, the node classifies the eviction candidates and divides them into buckets. The name of such a bucket is a netgroup. If a netgroup has only one peer, the node does not evict that peer. Thus a minimum of one pre-Overwinter node stays connected until the activation height, unless there are network problems or a high ban score.

Disconnecting Existing Connections

At the activation height, an Overwinter node can still be connected to pre-Overwinter nodes. At this time, a node can do the network handshake only one time, when it connects. In this handshake, the node sends the version message before other messages are processed.

To disconnect existing pre-Overwinter connections, ProcessMessage is changed. With this change, after Overwinter activation, the protocol version of an existing peer is validated, if necessary, when inbound messages arrive.

Example code:

bool static ProcessMessage(CNode* pfrom, string strCommand, CDataStream& vRecv, int64_t nTimeReceived)
    ...
    else if (pfrom->nVersion == 0)
    {
        // Must have a version message before anything else
        Misbehaving(pfrom->GetId(), 1);
        return false;
    }
    else if (strCommand == "verack")
    {
        ...
    }

    // Disconnect existing peer connection when:
    // 1. The version message has been received
    // 2. Overwinter is active
    // 3. Peer version is pre-Overwinter
    else if (NetworkUpgradeActive(GetHeight(), chainparams.GetConsensus(), Consensus::UPGRADE_OVERWINTER)
            && (pfrom->nVersion < chainparams.GetConsensus().vUpgrades[Consensus::UPGRADE_OVERWINTER].nProtocolVersion))
    {
        LogPrintf("peer=%d using obsolete version %i; disconnecting\n", pfrom->id, pfrom->nVersion);
        pfrom->PushMessage("reject", strCommand, REJECT_OBSOLETE,
                            strprintf("Version must be %d or greater",
                            chainparams.GetConsensus().vUpgrades[Consensus::UPGRADE_OVERWINTER].nProtocolVersion));
        pfrom->fDisconnect = true;
        return false;
    }

Deployment of Overwinter

The Overwinter network upgrade has these network upgrade constants [zip-0200]:

CONSENSUS_BRANCH_ID
0x5ba81b19
ACTIVATION_HEIGHT

Testnet: 207500

Mainnet: 347500

These ZIPs are deployed with Overwinter:

Backward compatibility

Before the activation of the network upgrade, Overwinter nodes and pre-Overwinter nodes are compatible and can connect to each other. But Overwinter nodes have a preference for connections to other Overwinter nodes. Thus Overwinter nodes gradually disconnect pre-Overwinter nodes in the time before activation.

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

Reference Implementation

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

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"
[zip-0143]
ZIP 143: Transaction Signature Validation for Overwinter
[zip-0200]
ZIP 200: Network Upgrade Mechanism
[zip-0202]
ZIP 202: Version 3 Transaction Format for Overwinter
[zip-0203]
ZIP 203: Transaction Expiry
[bip-0111]
BIP 111: NODE_BLOOM service bit
[bitcoin-verson]
https://en.bitcoin.it/wiki/Protocol_documentation#version
[bitcoin-version-handshake]
https://en.bitcoin.it/wiki/Version_Handshake
[eclipse-attack]
Eclipse Attacks on Bitcoin’s Peer-to-Peer Network
[partition-discussion]
Partition nodes with old protocol version from network in advance of hard fork