Network Upgrade Guide
Last updated: February 20th, 2018
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 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 through a push message or their next log in after the network transition.
Overwinter 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 five 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.
- 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.
- 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.
- 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.
- 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.
This isn't an exhaustive list of the changes. Look at the Overwinter Zcash Improvement Proposals (ZIPs) 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.