Network Upgrade Guide
Last updated: May 25th, 2018
Next Upgrade: Overwinter
- Activation Block Height: 347500
- 2018-06-25 12:00 assuming 150 seconds/block
This page serves as a place to disseminate information critical for supporting Zcash through network upgrades. We will update this page with each network upgrade to show relevant advice, so check back periodically. We recommend all wallets, exchanges, and clients that accept/support Zcash to follow these guidelines to prepare for the upcoming network upgrade.
We regularly perform network upgrades on a bi-annual basis to maintain the Zcash network. You can see a countdown to the next one here. For additional user support, please link to our regularly maintained network upgrade FAQ.
This is general advice that applies to all network upgrades.
- Keep your zcashd node updated: Check that you are running the latest stable version of zcashd.
- Version verifiability: Clearly state the version of Zcash in a place users can find it. Somewhere inside the client’s user interface, state the protocol name and version number (available from the getblockchaininfo method). This allows users to check what version of Zcash their client is running.
- Pre-upgrade notification: Inform users that a network upgrade is happening before it happens. 4000 blocks (approximately a week) in advance, tell users a network upgrade is happening soon, and that transactions will be unavailable for about an hour at the activation block height. Since the exact date of a block height can vary you can give an approximate date, and you can link to our countdown timer.
- Defensive transition: Disable the initiation of new transactions starting 24 blocks (approximately one hour) before the activation block-height. If a user sends a transaction right before the upgrade, it is likely to not make it onto the chain. This can cause user confusion and frustration.
- Post-upgrade notification: Tell users when the upgrade has finished and re-enable initiation of transactions. Notify users with a message or at their next login after the network transition.
Overwinter is set to activate at block 347500 and is the first network upgrade for Zcash so that future network upgrades go smoothly. We introduce replay protection of network upgrades, mask version numbers, and more.
Some Overwinter specific changes are required for forward compatibility only if you don't use our zcashd client and instead parse and sign Zcash transactions yourself. We would like to especially highlight the following points:
- Transaction formatting: All transactions must use the new transaction format from Overwinter and onwards. Make sure that you can parse these “v3” transactions (write a parser for them if you aren’t using our code). Previous formats will not be valid after the Overwinter upgrade, so if you create transactions, the “v3” format must be used after the upgrade has activated (but not until then). Hardware wallets and SPV clients are particularly affected here. See ZIPs 202 and 203.
- Transaction version number: The 4-byte transaction version will have its most significant bit set from Overwinter and onwards, for two-way replay protection of Overwinter and unambiguous transaction parsing of all current and future formats. For example, existing “v1” and “v2” transactions use version numbers “1” and “2”, but “v3” Overwinter transactions will use the unsigned version number “(1 << 31) | 3” in the transaction serialization format. See ZIP 202.
- Version group IDs: A transaction version will be uniquely paired with a version group ID to ensure unambiguous transaction parsing. For example, a “v3” transaction will always have the version group ID "0x03C48270" in its serialization format, even after future network upgrades. See ZIP 202.
- Branch IDs: Each network upgrade has an associated branch ID that identifies its consensus rules. For two-way replay protection, creating transactions will require the branch ID of the current chain tip when signing a transaction (in the BLAKE2b personalization field.) You can obtain the branch ID of any block height from the getblock API. See ZIP 200.
- Signature hashing: There are new SegWit-like features in this upgrade, such as transaction signatures committing to values of the inputs. We suggest reusing code from SegWit (e.g. for hashing transparent outputs) when implementing the new SignatureHash function. See ZIP 143.
- Transaction expiry: We recommend that you do use the default expiry height (20 blocks/~1 hours) and follow these UX guidelines so that Zcash users can develop a consistent expectation of when Zcash transactions expire and what happens. Zee ZIP 203.
This isn't an exhaustive list of the changes. Look at the Overwinter Zcash Improvement Proposals (ZIPs) below for complete details on the changes that will be made. The five ZIPs cover network handshaking, transaction format, transaction expiry, signature hashing, and network upgrade mechanisms.
The network upgrade is coordinated via an on-chain activation mechanism.
Zcashd v1.1.0 (and future releases) running protocol version 170005 will activate Overwinter at block 347500 at which point only v3 transactions are processed. Older versions of Zcashd <= 1.0.14, running protocol versions <= 170004, will partition themselves away from the main network into a legacy chain.
Wipeout protection is provided by the new transaction format and signature hashing scheme. Blocks from the legacy chain will not be accepted by the upgraded network. That is, the upgraded network is permanent, and Zcashd v1.1.0 (and future releases) can not reorganize back to the older non-upgraded chain.