Notable changes

Fixed

This is a hotfix release that fixes a regression in memory usage during Initial Block Download. The regression was indirectly caused by a change to prioritize downloading headers (PR #6231), introduced in release 5.3.1. It caused memory usage for new nodes to spike to roughly 11 GiB about an hour after starting Initial Block Download.

The issue fixed by this release does not affect nodes that start from a fully synced chain, or that had sufficient memory available to get past the memory usage spike.

Notable changes

Fixed

This release fixes an error "Assertion uResultHeight == rewindHeight failed" (#5958) that could sometimes happen when restarting a node.

Memory Usage Improvement

The memory usage of zcashd has been reduced by not keeping Equihash solutions for all block headers in memory.

RPC changes

The following RPC methods that query wallet state now support an optional asOfHeight parameter, to execute the query as if it were run when the blockchain was at the height specified by this argument:

• getbalance
• getreceivedbyaddress
• gettransaction (*)
• getwalletinfo
• listaddressgroupings
• listreceivedbyaddress (*)
• listsinceblock (*)
• listtransactions
• listunspent (*)
• z_getbalanceforaccount
• z_getbalanceforviewingkey
• z_getmigrationstatus
• z_getnotescount
• z_listreceivedbyaddress
• z_listunspent

(*) For these methods, additional parameters have been added to maintain compatibility of parameter lists with Bitcoin Core. Default values should be passed for these additional parameters in order to use asOfHeight. See the RPC documentation for details.

Notable changes

Wallet Performance Improvements

zcashd 5.2.0 improved the performance of wallet scanning with multithreaded batched trial decryption of Sapling outputs. However, for some nodes this resulted in growing memory usage that would eventually cause an OOM abort. We have identified the cause of the growth, and made significant improvements to reduce the memory usage of the batch scanner. In addition, the batch scanner now has a memory limit of 100 MiB.

zcashd now reports the following new metrics when -prometheusport is set:

• (counter) zcashd.wallet.batchscanner.outputs.scanned
• (gauge) zcashd.wallet.batchscanner.size.transactions
• (gauge) zcashd.wallet.batchscanner.usage.bytes
• (gauge) zcashd.wallet.synced.block.height

RPC Interface

• The finalorchardroot field in the getblock result and the orchard.commitments.finalRoot field in the z_gettreestate result have been changed to match the byte ordering used for the orchard.anchor field in the getrawtransaction result. These previously produced different hash values from the orchard.anchor field due to having been byte-flipped in their internal representation in zcashd.

Notable changes

Node Performance Improvements

This release makes several changes to improve the performance of node operations. These include:

• Backported CuckooCache from upstream to improve the performance of signature caching.
• Added caching of proof and signature validation results for Sapling and Orchard to eliminate redundant computation.
• Backported SHA-256 assembly optimizations from upstream.

Wallet Performance Improvements

This release makes several changes to improve the performance of wallet operations. These include:

• We now parallelize and batch trial decryption of Sapling outputs.
• We now prune witness data in the wallet for notes spent more than 100 blocks in the past, so that we can avoid unnecessarily updating those witnesses. In order to take advantage of this performance improvement, users will need to start their nodes with -rescan one time, in order to ensure that witnesses for spent notes are in the wallet are properly pruned.
• The process for incrementing the witnesses for notes the wallet is tracking has been optimized to avoid redundant passes over the wallet.
• Removed an assertion that was causing a slowdown in wallet scanning post-NU5.

RPC Interface Changes

• A version field was added to the result for the gettransaction RPC call to avoid the need to make an extra call to getrawtransaction just to retrieve the version.

Fixes

• Fixed a regression that caused an incorrect process name to appear in the process list.

Notable changes

Faster block validation for Sapling and Orchard transactions

Block validation in zcashd is a mostly single-threaded process, due to how the chain update logic inherited from Bitcoin Core is written. However, certain more computationally intensive checks are performed more efficiently than checking everything individually:

• ECDSA signatures on transparent inputs are checked via multithreading.
• RedPallas signatures on Orchard actions are checked via batch validation.

As of this release, zcashd applies these techniques to more Sapling and Orchard components:

• RedJubjub signatures on Sapling Spends are checked via batch validation.
• Groth16 proofs for Sapling Spends and Outputs are checked via batch validation and multithreading.
• Halo 2 proofs for Orchard Actions are checked via batch validation and multithreading.

This reduces worst-case block validation times for observed historic blocks by around 80% on a Ryzen 9 5950X CPU.

The number of threads used for checking Groth16 and Halo 2 proofs (as well as for creating them when spending funds) can be set via the RAYON_NUM_THREADS environment variable.

Option handling

• A new -preferredtxversion argument allows the node to preferentially create transactions of a specified version, if a transaction does not contain components that necessitate creation with a specific version. For example, setting -preferredtxversion=4 will cause the node to create V4 transactions whenever the transaction does not contain Orchard components. This can be helpful if recipients of transactions are likely to be using legacy wallets that have not yet been upgraded to support parsing V5 transactions.

RPC interface

• The getblocktemplate RPC method now skips proof and signature checks on templates it creates, as these templates only include transactions that have previously been checked when being added to the mempool.

• The getrawtransaction and decoderawtransaction RPC methods now include details about Orchard actions within transactions.

Wallet

• Rescan performance of post-NU5 blocks has been slightly improved (overall rescan time for a single-account wallet decreases by around 6% on a Ryzen 9 5950X). Further improvements will be implemented in future releases to help mitigate the effect of blocks full of shielded outputs.

• The CWallet::UpdatedTransaction signal is no longer called while holding the cs_main lock. This fixes an issue where RPCs could block for long periods of time on zcashd nodes with large wallets. Downstream code forks that have reconnected the NotifyTransactionChanged wallet signal should take note of this change, and not rely there on access to globals protected by cs_main.

• Some zcashd 5.0.0 nodes would shut down some time after start with the error ThreadNotifyWallets: Failed to read block X while notifying wallets of block disconnects. zcashd now attempts to rectify the situation, and otherwise will inform the user before shutting down that a reindex is required.

Deprecated

As of this release, the following previously deprecated features are disabled by default, but may be be reenabled using -allowdeprecated=<feature>.

• The dumpwallet RPC method is disabled. It may be reenabled with allowdeprecated=dumpwallet. dumpwallet should not be used; it is unsafe for backup purposes as it does not return any key information for keys used to derive shielded addresses. Use z_exportwallet instead.

As of this release, the following features are deprecated, but remain available by default. These features may be disabled by setting -allowdeprecated=none. After at least 3 minor-version releases, these features will be disabled by default and the following flags to -allowdeprecated will be required to permit their continued use:

• wallettxvjoinsplit - controls availability of the deprecated vjoinsplit attribute returned by the gettransaction RPC method.

Notable changes

The mainnet activation of the NU5 network upgrade is supported by the 5.0.0 release, with an activation height of 1687104, which should occur on approximately May 31, 2022. Please upgrade to this release, or any subsequent release, in order to follow the NU5 network upgrade.

The following ZIPs are being deployed, or have been updated, as part of this upgrade:

• ZIP 32 : Shielded Hierarchical Deterministic Wallets (updated)
• ZIP 203: Transaction Expiry (updated)
• ZIP 209: Prohibit Negative Shielded Chain Value Pool Balances (updated)
• ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext (updated)
• ZIP 213: Shielded Coinbase (updated)
• ZIP 216: Require Canonical Jubjub Point Encodings
• ZIP 221: FlyClient - Consensus-Layer Changes (updated)
• ZIP 224: Orchard Shielded Protocol
• ZIP 225: Version 5 Transaction Format
• ZIP 239: Relay of Version 5 Transactions
• ZIP 244: Transaction Identifier Non-Malleability
• ZIP 252: Deployment of the NU5 Network Upgrade
• ZIP 316: Unified Addresses and Unified Viewing Keys
• ZIP 401: Addressing Mempool Denial-of-Service (clarified)

Feature Deprecation and removal

zcashd now has a process for how features of the public API may be deprecated and removed. Feature deprecation follows a series of steps whereby, over a series of releases, features first remain enabled by default (but may be explicitly disabled), then switch to being disabled by default, and eventually are removed entirely.

A new string-valued option, -allowdeprecated has been introduced to allow a user to explicitly manage the availability of deprecated zcashd features. This flag makes it possible for users to reenable deprecated methods, features, and APIs that are currently disabled by default, or alternately to explicitly disable all deprecated features if they so choose. Multiple instances of this argument may be provided. A user may disable deprecated features entirely by providing the string none as the argument to this parameter. In the case that none is specified, multiple invocations of -allowdeprecated are not permitted.

Deprecated

As of this release, the following features are deprecated, but remain available by default. These features may be disabled by setting -allowdeprecated=none. After release 5.3.0, these features will be disabled by default and the following flags to -allowdeprecated will be required to permit their continued use:

• legacy_privacy - the default "legacy" privacy policy for z_sendmany is deprecated. When disabled, the default behavior of z_sendmany will conform to the FullPrivacy directive (introduced in 4.7.0) in all cases instead of just for transactions involving unified addresses.
• getnewaddress - controls availability of the getnewaddress RPC method.
• getrawchangeaddress - controls availability of the getrawchangeaddress RPC method.
• z_getbalance - controls availability of the z_getbalance RPC method.
• z_gettotalbalance - controls availability of the z_gettotalbalance RPC method.
• z_getnewaddress - controls availability of the z_getnewaddress RPC method.
• z_listaddresses - controls availability of the z_listaddresses RPC method.
• addrtype - controls availability of the deprecated type attribute returned by RPC methods that return address metadata.

As of this release, the following previously deprecated features are disabled by default, but may be be reenabled using -allowdeprecated=<feature>.

• The zcrawreceive RPC method is disabled. It may be reenabled with allowdeprecated=zcrawreceive
• The zcrawjoinsplit RPC method is disabled. It may be reenabled with allowdeprecated=zcrawjoinsplit
• The zcrawkeygen RPC method is disabled. It may be reenabled with allowdeprecated=zcrawkeygen

Option handling

• The -reindex and -reindex-chainstate options now imply -rescan (provided that the wallet is enabled and pruning is disabled, and unless -rescan=0 is specified explicitly).
• A new -anchorconfirmations argument has been added to allow the user to specify the number of blocks back from the chain tip that anchors will be selected from when spending notes. By default, anchors will now be selected to have 3 confirmations. Values greater than 100 are not supported.
• A new -orchardactionlimit option has been added to allow the user to override the default maximum of 50 Orchard actions per transaction. Transactions that contain large numbers of Orchard actions can use large amounts of memory for proving, so the 50-action default limit is imposed to guard against memory exhaustion. Systems with more than 16G of memory can safely set this parameter to allow 200 actions or more.

RPC Interface

• The default minconf value for z_sendmany is now 10 confirmations instead of 1. If minconf specifies a value less than that provided for -anchorconfirmations, it will also override that value as it is not possible to spend notes that are more recent than the anchor. Selecting minconf values less than 3 is not recommended, as it allows the transaction to be distinguished from transactions using the default for -anchorconfirmations.

RPC Changes

• The deprecated zcrawkeygen, zcrawreceive, and zcrawjoinsplit RPC methods are now disabled by default. Use -allowdeprecated=<feature> to select individual features if you wish to continue using these APIs.

Build system

• zcutil/build.sh now automatically runs zcutil/clean.sh to remove files created by previous builds. We previously recommended to do this manually.

Dependencies

• The boost and native_b2 dependencies have been updated to version 1.79.0

Tests

• The environment variable that allows users of the rpc (Python) tests to override the default path to the zcashd executable has been changed from BITCOIND to ZCASHD.

Changes to Testnet NU5 Consensus Rules

NOTE: All testnet nodes that have been running on testnet above height 1599200 will need to upgrade to v4.7.0 and then run with -reindex and -rescan.

• In order to better support hardware wallets, transparent signature hash construction as defined in ZIP 244 has been modified to include a hash of the serialization of the amounts of all outputs being spent, along with a hash of all spent outputs scriptPubKeys values, except in the case that the ANYONECANPAY flag is set. This allows hardware wallet devices to verify the UTXO amounts without having to stream all the previous transactions containing the outputs being spent to the device. Also as part of these changes, the transparent signature hash digest now commits directly, rather than implicitly, to the sighash type, and the sighash type is restricted to a fixed set of valid values. The change to ZIP 244 can be seen here.
• This release fixes a bug in v4.6.0 that caused a consensus failure on the Zcash testnet at height 1,779,200. For details see https://github.com/zcash/zcash/commit/5990853de3e9f04f28b7a4d59ef9e549eb4b4cca.
• There have been changes to the Halo2 proving system to improve consistency between the specification and the implementation, and these may break compatibility. See for example https://github.com/zcash/halo2/commit/247cd620eeb434e7f86dc8579774b30384ae02b2.
• There have been numerous changes to the Orchard circuit implementation since v4.6.0. See https://github.com/zcash/orchard/issues?q=label%3AM-consensus-change-since-0.1.0-beta-1 for a complete list.
• A potential Faerie Gold vulnerability affecting the previous activation of NU5 on testnet and existing since v4.6.0 has been mitigated.

NU5 Testnet Reactivation

To support the aforementioned testnet consensus changes, the following changes are made in zcashd v4.7.0:

• The consensus branch ID for NU5 is changed to 0xC2D6D0B4.
• The protocol version indicating NU5-aware testnet nodes is set to 170050.
• The testnet reactivation height for NU5 is set to 1,842,420.

As mentioned above, all testnet nodes that have been running on testnet above height 1,599,200 will need to upgrade to v4.7.0 and then run with -reindex and -rescan.

Emergency Recovery Phrases

The zcashd wallet has been modified to support BIP 39, which describes how to derive the wallet's HD seed from a mnemonic phrase, hereafter known as the wallet's "emergency recovery phrase". The emergency recovery phrase will be generated on load of the wallet, or the first time the wallet is unlocked, and is available via the z_exportwallet RPC call. All new addresses produced by the wallet are now derived from this seed using the HD wallet functionality described in ZIP 32 and ZIP 316. For users upgrading an existing Zcashd wallet, it is recommended that the wallet be backed up prior to upgrading to the 4.7.0 Zcashd release. In the remainder of this document, the HD seed derived from the emergency recovery phrase will be termed the wallet's "mnemonic seed".

Following the upgrade to 4.7.0, Zcashd will require that the user confirm that they have backed up their new emergency recovery phrase, which may be obtained from the output of the z_exportwallet RPC call. This confirmation can be performed manually using the zcashd-wallet-tool utility that is supplied with this release (built or installed in the same directory as zcashd). The wallet will not allow the generation of new addresses until this confirmation has been performed. It is recommended that after this upgrade, funds tied to preexisting addresses be migrated to newly generated addresses so that all wallet funds are recoverable using the emergency recovery phrase going forward. If you choose not to migrate funds in this fashion, you will continue to need to securely back up the entire wallet.dat file to ensure that you do not lose access to existing funds; EXISTING FUNDS WILL NOT BE RECOVERABLE USING THE EMERGENCY RECOVERY PHRASE UNLESS THEY HAVE BEEN MOVED TO A NEWLY GENERATED ADDRESS FOLLOWING THE 4.7.0 UPGRADE.

In the case that your wallet previously contained a Sapling HD seed, the emergency recovery phrase is constructed using the bytes of that seed, such that it is possible to reconstruct keys generated using that legacy seed if you know the emergency recovery phrase. HOWEVER, THIS RECONSTRUCTION DOES NOT FOLLOW THE NORMAL PROCESS OF DERIVATION FROM THE EMERGENCY RECOVERY PHRASE. Instead, to recover a legacy Sapling key from the emergency recovery phrase, it is necessary to reconstruct the bytes of the legacy seed by conversion of the phrase back to its source randomness instead of by hashing as is specified in BIP 39. Only keys and addresses produced after the upgrade can be obtained by normal derivation of a ZIP 32 or BIP 32 master seed using BIP 39.

Wallet Updates

The zcashd wallet now supports the Orchard shielded protocol.

The zcashd wallet has been modified to alter the way that change is handled. In the case that funds are being spent from a unified account, change is sent to a wallet-internal change address for that account instead of sending change amounts back to the original address where a note being spent was received. The rationale for this change is that it improves the security that is provided to the user of the wallet when supplying incoming viewing keys to third parties; previously, an incoming viewing key could effectively be used to detect when a note was spent (hence violating the "incoming" restriction) by observing change outputs that were sent back to the address where the spent note was originally received.

New RPC Methods

• walletconfirmbackup This newly created API checks a provided emergency recovery phrase against the wallet's emergency recovery phrase; if the phrases match then it updates the wallet state to allow the generation of new addresses. This backup confirmation workflow can be disabled by starting zcashd with -walletrequirebackup=false but this is not recommended unless you know what you're doing (and have otherwise backed up the wallet's emergency recovery phrase anyway). For security reasons, this RPC method is not intended for use via zcash-cli but is provided to enable zcashd-wallet-tool and other third-party wallet interfaces to satisfy the backup confirmation requirement. Use of the walletconfirmbackup API via zcash-cli would risk that the emergency recovery phrase being confirmed might be leaked via the user's shell history or the system process table; zcashd-wallet-tool is provided specifically to avoid this problem.
• z_getnewaccount This API allows for creation of new BIP 44 / ZIP 32 accounts using HD derivation from the wallet's mnemonic seed. Each account represents a separate spending authority and source of funds. A single account may contain funds in the Sapling and Orchard shielded pools, as well as funds held in transparent addresses.
• z_listaccounts This API returns the list of BIP 44 / ZIP 32 accounts that are being tracked by the wallet.
• z_getaddressforaccount This API allows for creation of diversified unified addresses under a single account. Each call to this API will, by default, create a new diversified unified address containing transparent p2pkh, Sapling, and Orchard receivers. Additional arguments to this API may be provided to request the address to be created with a user-specified set of receiver types and diversifier index.
• z_getbalanceforaccount This API makes it possible to obtain balance information on a per-account basis.
• z_getbalanceforviewingkey This API allows a user to obtain balance information for funds visible to a Sapling or Unified full viewing key; if a Sprout viewing key is provided, this method allows retrieval of the balance only in the case that the wallet controls the corresponding spending key. This API has been added to supplement (and largely supplant) z_getbalance. Querying for balance by a single address returns only the amount received by that address, and omits value sent to other diversified addresses derived from the same full viewing key; by using z_getbalanceforviewingkey it is possible to obtain a correct balance that includes all amounts controlled by a single spending key, including both those sent to external diversified addresses and to wallet-internal change addresses.
• z_listunifiedreceivers This API allows the caller to extract the individual component receivers from a unified address. This is useful if one needs to provide a bare Sapling or transparent p2pkh address to a service that does not yet support unified addresses.

RPC Changes

• The result type for the listaddresses endpoint has been modified:
  • The keypool source type has been removed; it was reserved but not used.
  • In the sapling address results, the zip32AccountId attribute has been removed in favor of zip32KeyPath. This is to allow distinct key paths to be reported for addresses derived from the legacy account under different child spending authorities, as are produced by z_getnewaddress.
  • Addresses derived from the wallet's mnemonic seed are now included in listaddresses output.
• The results of the dumpwallet and z_exportwallet RPC methods have been modified to now include the wallet's newly generated emergency recovery phrase as part of the exported data. Also, the seed fingerprint and HD keypath information are now included in the output of these methods for all HD-derived keys.
• The results of the getwalletinfo RPC have been modified to return two new fields: mnemonic_seedfp and legacy_seedfp, the latter of which replaces the field that was previously named seedfp.
• A new pool attribute has been added to each element returned by z_listunspent to indicate which value pool the unspent note controls funds in.
• z_listreceivedbyaddress
  • A pool attribute has been added to each result to indicate what pool the received funds are held in.
  • A boolean-valued change attribute has been added to indicate whether the output is change.
  • Block metadata attributes blockheight, blockindex, and blocktime have been added to the result.
• z_viewtransaction has been updated to include attributes that provide information about Orchard components of the transaction. Also, the type attribute for spend and output values has been deprecated and replaced by the pool attribute.
• z_getnotescount now also returns information for Orchard notes.
• The output format of z_exportwallet has been changed. The exported file now includes the mnemonic seed for the wallet, and HD keypaths are now exported for transparent addresses when available.
• The result value for z_importviewingkey now includes an address_type field that replaces the now-deprecated type key.
• z_listunspent has been updated to render unified addresses for Sapling and Orchard outputs when those outputs are controlled by unified spending keys. Outputs received by unified internal addresses do not include the address field.
• Legacy transparent address generation using getnewaddress no longer uses a preallocated keypool, but instead performs HD derivation from the wallet's mnemonic seed according to BIP 39 and BIP 44 under account ID 0x7FFFFFFF.
• z_gettreestate has been updated to include information about the Orchard note commitment tree.

'z_sendmany'

• The z_sendmany RPC call no longer permits Sprout recipients in the list of recipient addresses. Transactions spending Sprout funds will still result in change being sent back into the Sprout pool, but no other Sprout->Sprout transactions will be constructed by the Zcashd wallet.
• The restriction that prohibited Sprout->Sapling transactions has been lifted; however, since such transactions reveal the amount crossing pool boundaries, they must be explicitly enabled via a parameter to the z_sendmany call.
• A new string parameter, privacyPolicy, has been added to the list of arguments accepted by z_sendmany. This parameter enables the caller to control what kind of information they permit zcashd to reveal on-chain when creating the transaction. If the transaction can only be created by revealing more information than the given strategy permits, z_sendmany will return an error. The parameter defaults to LegacyCompat, which applies the most restrictive strategy FullPrivacy when a Unified Address is present as the sender or a recipient, and otherwise preserves existing behaviour (which corresponds to the AllowFullyTransparent policy). In cases where it is possible to do so without revealing additional information, and where it is permitted by the privacy policy, the wallet will now opportunistically shield funds to the most current pool.
• Since Sprout outputs are no longer created (with the exception of change) z_sendmany no longer generates payment disclosures (which were only available for Sprout outputs) when the -paymentdisclosure experimental feature flag is set.
• Outgoing viewing keys used for shielded outputs are now produced as described in ZIP 316
• When sending from or to one or more unified addresses, change outputs are now always sent to addresses controlled by the wallet's internal spending keys, as described in ZIP 316. These addresses are not returned by any RPC API, as they are intended to never be shared with any third party, and are for wallet-internal use only. This change improves the privacy properties that may be maintained when sharing a unified internal viewing key for an account in the wallet.
• In cases where z_sendmany might produce transparent change UTXOs, those UTXOs are sent to addresses derived from the wallet's mnemonic seed via the BIP 44 change derivation path.

RPC Deprecations

• z_getnewaddress has been deprecated in favor of z_getnewaccount and z_getaddressforaccount.
• z_listaddresses has been deprecated. Use listaddresses instead.
• z_getbalance has been deprecated. Use z_getbalanceforviewingkey instead. See the discussion of how change is now handled under the Wallet heading for additional background.
• z_gettotalbalance has been deprecated. Use z_getbalanceforaccount instead.
• dumpwallet has been deprecated. Use z_exportwallet instead.

Build System

• Clang has been updated to use LLVM 13.0.1.
• libc++ has been updated to use LLVM 13.0.1, except on Windows where it uses 13.0.0-3.
• The Rust toolchain dependency has been updated to version 1.59.0.

Platform Support

• Debian 9 has been removed from the list of supported platforms.
• Debian 11 (Bullseye) has been added to the list of supported platforms.
• A build issue (a missing header file) has been fixed for macOS targets.
• On Arch Linux only, a copy of Debian's libtinfo5_6.0 is used to fix a build regression.

Mining

• Mining to Orchard recipients is now supported on testnet.
• It is now possible to mine to a Sapling receiver of a unified address.
• Concurrency bugs related to getblocktemplate have been fixed via backports from Bitcoin Core.

Licenses

• License information in contrib/debian/copyright has been updated to be more accurate.

This is a bugfix release that also bumps the End-of-Support height to May 16th. It backports bugfixes from v4.7.0-rc1, including a getblocktemplate deadlock fix, and several portability fixes.

Debian 9 "Stretch" is no longer supported from v4.6.0-2, due to its end-of-life on June 30th, 2022. This will allow us to direct more resources to supporting Debian 11 Bullseye, other Linux distributions, and other platforms such as Windows and macOS.

getblocktemplate regression fix

We added support for the NU5 consensus rules in v4.5.0, which alters the block header to contain a hashBlockCommitments value instead of the chain history root. However, the output of getblocktemplate wasn't returning this value; once NU5 activated, the blockcommitmentshash field was being set to "null" (all-zeroes).

In v4.6.0 we added full NU5 support to getblocktemplate, by adding a defaultroots field that gave default values for hashBlockCommitments and the components required to derive it. However, in doing so we introduced a regression in the (now-deprecated) legacy fields, where prior to NU5 activation they contained nonsense.

This release fixes the output of getblocktemplate to have the intended semantics for all fields:

• The blockcommitmentshash and authdataroot fields in defaultroots are now omitted from block templates for heights before NU5 activation.
• The legacy fields now always contain the default value to be placed into the block header (regaining their previous semantics).

Notable changes

Wallet

From this release, newly-created wallets will save the chain name ("Zcash") and network identifier (e.g. "main") to the wallet.dat file. This will enable the zcashd node to check on subsequent starts that the wallet.dat file matches the node's configuration. Existing wallets will start saving this information in a later release.

libzcash_script

Two new APIs have been added to this library (zcash_script_legacy_sigop_count and zcash_script_legacy_sigop_count_precomputed), for counting the number of signature operations in the transparent inputs and outputs of a transaction. The presence of these APIs is indicated by a library API version of 2.

Updated RPCs

• The getblocktemplate RPC method output now includes a defaultroots field, which provides various tree roots and block commitments matching the contents of the block template. If any part of the block template marked as mutable in the RPC method output is mutated, these roots may need to be recomputed. For more information on the derivation process, see the block header changes in ZIP 244.

• Fixed an issue where ERROR: spent index not enabled would be logged unnecessarily on nodes that have either -insightexplorer or -lightwalletd configuration options enabled.

• The getmininginfo RPC now omits currentblocksize and currentblocktx when a block was never assembled via RPC on this node during its current process instantiation. (#5404)

Notable changes

Added v5 transactions to standard rules

In v4.5.0 we added the v5 transaction format to the NU5 consensus rules for testnet. However, it was omitted from the standard rules, which meant that zcashd testnet nodes would not accept v5 transactions into their mempools, causing them to not be propagated or mined. This release updates the zcashd standard rules to accept v5 transactions alongside v4 transactions.

New listaddresses RPC method

The listaddresses endpoint has been added to the RPC API. This method allows the caller to obtain addresses managed by the wallet, grouped by the source of the address, including both those addresses generated by the wallet and those associated with imported viewing or spending keys. This provides functionality that replaces and subsumes the previously removed getaddressesbyaccount method.

TL;DR: This is a required update for all testnet nodes, and is highly recommended for mainnet nodes if you are using the getbalance RPC method.

If you are running zcashd in Docker, you may need to upgrade Docker to a recent version. Version 19.03.12 is reported to work.

Notable changes

Fixed bugs in the testnet Orchard circuit

In the zcashd v4.5.0 release notes we indicated that a testnet rollback might occur to update the consensus rules, if we needed to make backwards-incompatible changes. Shortly after zcashd v4.5.0 was released, during another internal review of the Orchard circuit, we identified two bugs that would affect the upcoming testnet activation of NU5:

• The diversifier base g_d_old, for the note being spent, is required to be a non-identity point. A note created from a payment address with g_d set to the identity (via collaboration between sender and recipient) could be spent multiple times with different nullifiers (corresponding to different ivks). The code outside the circuit correctly enforced the non-identity requirement, but the circuit did not correctly constrain this, and allowed the prover to witness the identity.

• SinsemillaCommit can be modeled as a Pedersen commitment to an output of SinsemillaHash: SinsemillaCommit(r, M) = SinsemillaHashToPoint(M) + [r] R. The specification used incomplete addition here, matching its use inside SinsemillaHash. However, unlike in SinsemillaHash, an exceptional case can be produced here when r = 0. The derivations of rivk (for computing ivk) and rcm (for computing the note commitment) normally ensure that r = 0 can only occur with negligible probability, but these derivations are not checked by the circuit for efficiency; thus SinsemillaCommit needs to use complete addition.

These bugs do not affect mainnet, as zcashd v4.5.0 only set the activation height for NU5 on testnet for testing purposes. Nevertheless, in the interest of keeping the testnet environment as close to mainnet as possible, we are fixing these bugs immediately. This means a change to the NU5 consensus rules, and a new testnet activation height for NU5.

To this end, the following changes are made in zcashd v4.5.1:

• The consensus branch ID for NU5 is changed to 0x37519621.
• The protocol version indicating NU5-aware testnet nodes is set to 170015.
• The testnet activation height for NU5 is set to 1,599,200.

Testnet nodes that upgrade to zcashd v4.5.1 prior to block height 1,590,000 will follow the new testnet network upgrade. Testnet nodes that are running zcashd v4.5.0 at that height will need to upgrade to v4.5.1 and then run with -reindex.

As always, it is possible that further backwards incompatible changes might be made to the NU5 consensus rules in this testing phase, prior to setting the mainnet activation height, as we continue to conduct additional internal review. In the event that this happens, testnet will be rolled back in (or prior to) v5.0.0, and a new testnet activation will occur.

Fixed regression in getbalance RPC method

zcashd v4.5.0 removed the account API from the wallet, following its deprecation and removal in upstream Bitcoin Core. As part of the upstream changes, the getbalance RPC method was altered from using two custom balance computation methods, to instead relying on CWallet::GetBalance. This method internally relies on CWalletTx::IsFromMe as part of identifying "trusted" zero-confirmation transactions to include in the balance calculation.

There is an equivalent and closely-named CWallet::IsFromMe method, which is used throughout the wallet, and had been updated before Zcash launched to be aware of spent shielded notes. The change to getbalance exposed a bug: CWalletTx::IsFromMe had not been similarly updated, which caused getbalance to ignore wallet-internal (sent between two addresses in the node's wallet) unshielding transactions with zero confirmations. This release fixes the bug.

Notable changes

Network Upgrade 5

The code preparations for the Network Upgrade 5 consensus rules are finished and included in this release. The following ZIPs are being deployed:

• ZIP 216: Require Canonical Jubjub Point Encodings
• ZIP 224: Orchard Shielded Protocol
• ZIP 225: Version 5 Transaction Format
• ZIP 239: Relay of Version 5 Transactions
• ZIP 244: Transaction Identifier Non-Malleability

NU5 will activate on testnet at height 1,590,000, and can also be activated at a specific height in regtest mode by setting the config option -nuparams=f919a198:HEIGHT.

The testnet activation of NU5, and zcashd v4.5.0 itself, is aimed at enabling existing Zcash users to test their software and make the necessary changes to be compatible with the new consensus rules. In particular:

• Wallets should start adding support for v5 transactions.
• Miners and mining pools should ensure that their software is compatible with the semantic change to the block header specified in ZIP 244

A subsequent v4.5.1 release in the coming weeks will add support for generating and using Unified Addresses (ZIP 316), which will enable zcashd wallets to interact with the Orchard shielded pool.

As with previous network upgrades, it is possible that backwards-incompatible changes might be made to the consensus rules in this testing phase, prior to setting the mainnet activation height. In the event that this happens, testnet will be rolled back in v5.0.0 and a second testnet activation will occur.

See ZIP 252 for additional information about the deployment process for NU5.

Rejecting unknown CInv message types

Previously, if zcashd received an inv or getdata message containing unknown CInv message types, it would ignore them and process the remainder of the message. Starting with v4.5.0, zcashd will instead drop the entire inv or getdata message and reply with a reject message. This will enable node operators to discover whether their nodes are sending unexpected CInv types; in particular, node operators should ensure their software does not produce the MSG_WTX CInv message type intended for the Bitcoin network, which is incompatible with the MSG_WTX CInv message type defined in ZIP 239 (which will be used from NU5 activation for advertising v5 transactions).

Deprecated or removed RPCs

• The 'account' API inherited from Bitcoin Core has been disabled since the launch of Zcash. Following its deprecation in Bitcoin Core v0.17 and removal in Bitcoin Core v0.18, we have now removed the API from zcashd.

Notable changes

Fixed chain sync stall bug

The 4.3.0 release included a change to prevent redundant getheaders P2P requests, to reduce node bandwith usage. This behaviour could be disabled by setting the config option -nooptimize-getheaders.

It turns out that these redundant requests were masking an unrelated bug in the chain-rewinding logic that is used when the node detects a change to the consensus rules (for example, if a user forgets to upgrade their zcashd node before a network upgrade activates, and temporarily follows an un-upgraded chain before restarting with the latest version).

In certain uncommon scenarios, a node could end up in a situation where it would believe that the best header it knew about was more than 160 blocks behind its actual best-known block. The redundant getheaders requests meant that this did not cause an issue, because the node would continue requesting headers until it found new blocks. After the getheaders optimizations, if a peer returned a headers message that was entirely known to the node, it would stop requesting more headers from that peer; this eventually caused node synchronization to stall. Restarting with the -nooptimize-getheaders config option would enable the node to continue syncing.

This release fixes the bug at its source, but the -nooptimize-getheaders config option remains available if necessary.

Build system changes

• Cross-compilation support for Windows XP, Windows Vista, and 32-bit Windows binaries, has been removed. Cross-compiled Windows binaries are now 64-bit only, and target a minimum of Windows 7.

Notable changes

Prometheus metrics

zcashd can now be configured to optionally expose an HTTP server that acts as a Prometheus scrape endpoint. The server will respond to GET requests on any request path.

To enable the endpoint, add -prometheusport=<port> to your zcashd configuration (either in zcash.conf or on the command line). After restarting zcashd you can then test the endpoint by querying it with e.g. curl http://127.0.0.1:<port>.

The feature includes IP-level access control rules, the default being to allow connections only from localhost. Users of this feature should be aware of the threat from DNS rebinding attacks and not rely on these access control rules for security. The allowed IPs can be expanded with -metricsallowip=<ip>, which can specify IPs or subnets.

Note that HTTPS is not supported, and therefore connections to the endpoint are not encrypted or authenticated. Access to the endpoint, including through DNS rebinding attacks, should be assumed to compromise the privacy of node operations, by the provided metrics and/or by timing side channels and so for now: You should NOT use this feature while private keys are loaded in zcashd.

The specific metrics names may change in subsequent releases, in particular to improve interoperability with zebrad.

Notable changes

Reduce download traffic

We have made several changes to reduce the amount of data downloaded by zcashd during initial block download (IBD):

• Significant time and bandwidth is spent in issuing getheaders P2P requests. This results in noticeable bandwidth usage due to the large size of Zcash block headers.

  We now eliminate redundant requests in cases where we already know the last header in the message. This optimization is enabled by default, but can be disabled by setting the config option -nooptimize-getheaders.

• Transactions in the mempool are no longer downloaded during IBD (zcashd will only request block data).

Reduce upload traffic

A major part of the outbound traffic is caused by serving historic blocks to other nodes in initial block download state.

It is now possible to reduce the total upload traffic via the -maxuploadtarget parameter. This is not a hard limit but a threshold to minimize the outbound traffic. When the limit is about to be reached, the uploaded data is cut by not serving historic blocks (blocks older than one week). Moreover, any SPV peer is disconnected when they request a filtered block.

This option can be specified in MiB per day and is turned off by default (-maxuploadtarget=0). The recommended minimum is 1152 * MAX_BLOCK_SIZE (currently 2304MB) per day.

Whitelisted peers will never be disconnected, although their traffic counts for calculating the target.

A more detailed documentation about keeping traffic low can be found in /doc/reduce-traffic.md.

libzcashconsensus replaced by libzcash_script

The libzcashconsensus library inherited from upstream has been unusable since the Overwinter network upgrade in 2018. We made changes to signature digests similar to those made in Bitcoin's SegWit, which required additional per-input data that could not be added to the existing APIs without breaking backwards compatibility.

Additionally, it has become increasingly inaccurately named; it only covers (Zcash's subset of) the Bitcoin scripting system, and not the myriad of other consensus changes: in particular, Zcash's shielded pools.

We have now renamed the library to libzcash_script, and reworked it to instead focus on transparent script verification:

• The script verification APIs are altered to take consensusBranchId and amount fields.
• New precomputing APIs have been added that enable multiple transparent inputs on a single transaction to be verified more efficiently.
• Equihash has been removed from the compiled library. The canonical Equihash validator is the equihash Rust crate since v3.1.0.

The C++ library can be built by compiling zcashd with the environment variable CONFIGURE_FLAGS=--with-libs. It is also wrapped as the zcash_script Rust crate (maintained by the Zcash Foundation for use in zebrad).

Other P2P Changes

The list of banned peers is now stored on disk rather than in memory. Restarting zcashd will no longer clear out the list of banned peers; instead the clearbanned RPC method can be used to manually clear the list. The setban RPC method can also be used to manually ban or unban a peer.

Build system updates

• We now build with Clang 11 and Rust 1.49.
• We have downgraded Boost to 1.74 to mitigate statx-related breakage in some container environments.

Notable changes

Switch to ed25519-zebra for consensus signature checks

This removes the zcashd dependency upon libsodium for ed25519 signature checks and instead uses the Rust implementation in ed25519-zebra, which has been active for signature verification since the Canopy upgrade. For more information on the conditions that led to this change see https://hdevalence.ca/blog/2020-10-04-its-25519am.

Update default fees according to ZIP-313

Reduce default fees to 0.00001 ZEC as specified in ZIP-313 and ensure that transactions paying at least the new minimum fee meet the transaction relay threshold irrespective of transaction size.

Improve getblocktemplate rpc performance when using shielded coinbase

This change precomputes future block templates to permit miners to begin working atop newly arrived blocks as quickly as possible, rather than waiting for a new template to be generated after a block has arrived. It also reduces the initial wait time for incorporating new mempool transactions into a block from 1 minute to 10 seconds; the previous value was inherited from the upstream bitcoin codebase but is inappropriate for our block timing.

Migrate from rpc-tests.sh to rpc-tests.py

This unifies and simplifies the RPC testing framework, as has been done in the upstream Bitcoin codebase.

Notable changes

This release is a hotfix release that addresses a performance regression in v4.1.0. It is recommended that either v4.0.0 or this release, v4.1.1 be used for Canopy activation.

Optimize release build

The release build now sets CFLAGS/CXXFLAGS to use the -O3 optimization option, which turns on more optimization flags than the previously used -O1. This produces a faster build, addressing a performance regression in v4.1.0.

Correctly report Founders' Reward amount in getblocktemplate

This release correctly returns the foundersreward field from getblocktemplate output pre-Canopy and removes the field post-Canopy. (The Founders' Reward will expire exactly as Canopy activates, as specified in ZIP 207.) To obtain information about funding stream amounts, use getblocksubsidy HEIGHT, passing in the height returned by the getblocktemplate API.

Notable changes

Migration to Clang and static libc++

zcashd now builds its C++ (and C) dependencies entirely with a pinned version of Clang, and statically links libc++ instead of dynamically linking libstdc++. This migration enables us to reliably use newer C++ features while supporting older LTS platforms, be more confident in the compiler's optimisations, and leverage security features such as sanitisers and efficient fuzzing. In future, this will also allow optimizing across the boundary between Rust and C++.

The system compiler is still used to compile a few native dependencies (used by the build machine to then compile zcashd for the target machine). These will likely also be migrated to use the pinned Clang in a future release.

Fast sync for initial block download

The -ibdskiptxverification flag allows faster synchronization during initial block sync, by skipping transaction verification and instead verifying only PoW. Note that this mode requires checkpoints to be enabled, to make sure that each block under inspection is an ancestor of the latest checkpoint.

Convenient testing for invalid note plaintexts

After the mainnet activation of Canopy (block 1046400), correct wallet software will no longer produce v1 note plaintexts (with a lead byte of 0x01). However, v1 note plaintexts will continue to be accepted for a grace period of 32256 blocks (about 4 weeks), as specified in ZIP 212. The new receiveunsafe log category complains if an invalid note plaintext is received.

Additional lightwalletd and light client RPCs

• lightwalletd is now able to retrieve all UTXOs related to a t-address through the getaddressutxos RPC. (Previously, this was only available to the Insight Explorer.)
• The new z_gettreestate RPC returns the Sprout and Sapling treestate at a given block height or block hash. This makes it easier for light clients to generate checkpoints.

Update/removal of several cryptographic dependencies

This release updates secp256k1 to enable the GLV endomorphism optimisation by default, after the recent expiry of the GLV patents. It also removes OpenSSL, and replaces libsodium BLAKE2b usage with the blake2b_simd Rust crate.

Notable changes

The mainnet activation of the Canopy network upgrade is supported by the 4.0.0 release, with an activation height of 1046400, which should occur roughly in the middle of November — following the targeted EOS halt of our 3.1.0 release. Please upgrade to this release, or any subsequent release, in order to follow the Canopy network upgrade.

The following ZIPs are being deployed as part of this upgrade:

• ZIP 207: Funding Streams in conjunction with ZIP 214: Consensus rules for a Zcash Development Fund
• ZIP 211: Disabling Addition of New Value to the Sprout Value Pool
• ZIP 212: Allow Recipient to Derive Sapling Ephemeral Secret from Note Plaintext
• ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules

In order to help the ecosystem prepare for the mainnet activiation, Canopy has already been activated on the Zcash testnet. Any node version 3.1.0 or higher, including this release, supports the Canopy activation on testnet.

Disabling new value in the Sprout value pool

After the mainnet activation of Canopy, it will not be possible to send funds to Sprout z-addresses from any other kind of address, as described in ZIP 211. It will still be possible to send funds from a Sprout z-address and to send funds between Sprout addresses. Users of Sprout z-addresses are encouraged to use Sapling z-addresses instead, and to migrate their remaining Sprout funds into a Sapling z-address using the migration utility in zcashd: set migrate=1 in your zcash.conf file, or use the z_setmigration RPC.

New logging system

The zcashd logging system is now powered by the Rust tracing crate. This has two main benefits:

• tracing supports the concept of "spans", which represent periods of time with a beginning and end. These enable logging additional information about temporality and causality of events. (Regular log lines, which represent moments in time, are called events in tracing.)
• Spans and events are structured, and can record typed data in addition to text messages. This structure can then be filtered dynamically.

The existing -debug=target config flags are mapped to tracing log filters, and will continue to correctly enable additional logging when starting zcashd. A new setlogfilter RPC method has been introduced that enables reconfiguring the log filter at runtime. See zcash-cli help setlogfilter for its syntax.

As a minor note, zcashd no longer reopens the debug.log file on SIGHUP. This behaviour was originally introduced in upstream Bitcoin Core to support log rotation using external tools. tracing supports log rotation internally (which is currently disabled), as well as a variety of interesting backends (such as journald and OpenTelemetry integration); we are investigating how these might be exposed in future releases.

Compatibility

macOS versions earlier than 10.12 (Sierra) are no longer supported.

Notable changes

Network Upgrade 4: Canopy

The code preparations for the Canopy network upgrade are finished and included in this release. The following ZIPs are being deployed:

• ZIP 207: Funding Streams
• ZIP 211: Disabling Addition of New Value to the Sprout Value Pool
• ZIP 212: Allow Recipient to Derive Sapling Ephemeral Secret from Note Plaintext
• ZIP 214: Consensus rules for a Zcash Development Fund
• ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules

Canopy will activate on testnet at height 1028500, and can also be activated at a specific height in regtest mode by setting the config option -nuparams=0xe9ff75a6:HEIGHT. Note that v3.1.0 enables Canopy support on the testnet.

Canopy will activate on mainnet at height 1046400.

See ZIP 251 for additional information about the deployment process for Canopy.

Debian 8 "Jessie" will no longer be supported after v3.1.0, due to its end-of-life on June 30th, 2020. This will allow us to direct more resources to supporting Debian 10 Buster, other Linux distributions, and other platforms such as Windows and macOS.

Flush witness data to disk only when it's consistent

This fix prevents the wallet database from getting into an inconsistent state. By flushing witness data to disk from the wallet thread instead of the main thread, we ensure that the on-disk block height is always the same as the witness data height. Previously, the database occasionally got into a state where the latest block height was one ahead of the witness data. This then triggered an assertion failure in CWallet::IncrementNoteWitnesses() upon restarting after a zcashd shutdown.

Note that this code change will not automatically repair a data directory that has been affected by this problem; that requires starting zcashd with the -rescan or -reindex options.

New DNS seeders

DNS seeders hosted at "zfnd.org" and "yolo.money" have been added to the list in chainparams.cpp. They're running CoreDNS with a Zcash crawler plugin, the result of a Zcash Foundation in-house development effort to replace zcash-seeder with something memory-safe and easier to maintain.

These are validly operated seeders per the existing policy. For general questions related to either seeder, contact [email protected] or mention @gtank in the Zcash Foundation's Discord. For bug reports, open an issue on the dnsseeder repo.

Changed command-line options

• -debuglogfile=<file> can be used to specify an alternative debug logging file.

RPC methods

• joinSplitPubKey and joinSplitSig have been added to verbose transaction outputs. This enables the transaction's binary form to be fully reconstructed from the RPC output.
• The output of getblockchaininfo now includes an estimatedheight parameter. This can be shown in UIs as an indication of the current chain height while zcashd is syncing, but should not be relied upon when creating transactions.

Metrics screen

• A progress bar is now visible when in Initial Block Download mode, showing both the prefetched headers and validated blocks. It is only printed for TTY output. Additionally, the "not mining" message is no longer shown on mainnet, as the built-in CPU miner is not effective at the current network difficulty.
• The number of block headers prefetched during Initial Block Download is now displayed alongside the number of validated blocks. With current compile-time defaults, a Zcash node prefetches up to 160 block headers per request without a limit on how far it can prefetch, but only up to 16 full blocks at a time.

The mainnet activation of the Heartwood network upgrade is supported by this release, with an activation height of 903000, which should occur in the middle of July — following the targeted EOS halt of our 2.1.2-3 release. Please upgrade to this release, or any subsequent release, in order to follow the Heartwood network upgrade.

The following two ZIPs are being deployed as part of this upgrade:

• ZIP 213: Shielded Coinbase
• ZIP 221: FlyClient - Consensus-Layer Changes

In order to help the ecosystem prepare for the mainnet activiation, Heartwood has already been activated on the Zcash testnet. Any node version 2.1.2 or higher, including this release, supports the Heartwood activation on testnet.

Mining to Sapling addresses

After the mainnet activation of Heartwood, miners can mine directly into a Sapling shielded address. Miners should wait until after Heartwood activation before they make changes to their configuration to leverage this new feature. After activation of Heartwood, miners can add mineraddress=SAPLING_ADDRESS to their zcash.conf file, where SAPLING_ADDRESS represents a Sapling address that can be generated locally with the z_getnewaddress RPC command. Restart your node, and block templates produced by the getblocktemplate RPC command will now have coinbase transactions that mine directly into this shielded address.

This release fixes a crash on testnet that v2.1.2 nodes are likely to experience on startup. This release also allows nodes that did not follow the testnet activation of Heartwood to properly roll back and follow the Heartwood activation on testnet.

In addition, we have ensured that this release’s end-of-service halt is in the middle of July, just prior to our anticipated activation of Heartwood on mainnet.

We recommend that anyone testing their integration with Heartwood should upgrade to this release.

As a reminder, 2.1.2 included the following major changes:

• Support for Sapling viewing keys (specifically, Sapling extended full viewing keys, as described in ZIP 32), has been added to the wallet. Nodes will track both sent and received transactions for any Sapling addresses associated with the imported Sapling viewing keys.

• Removal of time adjustment and the -maxtimeadjustment= option. Prior to v2.1.1-1, zcashd would adjust the local time that it used by up to 70 minutes, according to a median of the times sent by the first 200 peers to connect to it. This mechanism was inherently insecure, since an adversary making multiple connections to the node could effectively control its time within that +/- 70 minute window (this is called a "timejacking attack"). As a simplification the time adjustment code has now been completely removed, together with -maxtimeadjustment=. Node operators should instead ensure that their local time is set reasonably accurately.

• View shielded information in wallet transactions. In previous zcashd versions, there were no RPC methods that directly returned details about spends, or anything equivalent to the gettransaction method (which returns transparent information about in-wallet transactions). This release introduces a new RPC method z_viewtransaction to fill that gap.

• Better error messages for rejected transactions after network upgrades. Starting from this release, zcashd nodes will re-verify invalid transparent and Sprout signatures against the consensus branch ID from before the most recent network upgrade. If the signature then becomes valid, the transaction will be rejected with the error message old-consensus-branch-id. This error can be handled specifically by wallet providers to inform the user that they need to upgrade their wallet software.

• A new config option -txexpirynotify has been added that will cause zcashd to execute a command when a transaction in the mempool expires.

• The z_importkey and z_importviewingkey RPC methods now return the type of the imported spending or viewing key (sprout or sapling), and the corresponding payment address.

• Negative heights are now permitted in getblock and getblockhash, to select blocks backwards from the chain tip. A height of -1 corresponds to the last known valid block on the main chain.

• A new RPC method getexperimentalfeatures returns the list of enabled experimental features.

• The --enable-lcov, --disable-tests, and --disable-mining flags for zcutil/build.sh have been removed. You can pass these flags instead by using the CONFIGURE_FLAGS environment variable. Also, the build system no longer defaults to verbose output.

Notable changes

Network Upgrade 3: Heartwood

The code preparations for the Heartwood network upgrade are finished and included in this release. The following ZIPs are being deployed:

• ZIP 213: Shielded Coinbase
• ZIP 221: FlyClient - Consensus-Layer Changes

Heartwood will activate on testnet at height 903800, and can also be activated at a specific height in regtest mode by setting the config option -nuparams=f5b9230b:HEIGHT.

As a reminder, because the Heartwood activation height is not yet specified for mainnet, version 2.1.2 will behave similarly as other pre-Heartwood releases even after a future activation of Heartwood on the network. Upgrading from 2.1.2 will be required in order to follow the Heartwood network upgrade on mainnet.

See ZIP 250 for additional information about the deployment process for Heartwood.

Mining to Sapling addresses

Miners and mining pools that wish to test the new "shielded coinbase" support on the Heartwood testnet can generate a new Sapling address with z_getnewaddress, add the config option mineraddress=SAPLING_ADDRESS to their zcash.conf file, and then restart their zcashd node. getblocktemplate will then return coinbase transactions containing a shielded miner output.

Note that mineraddress should only be set to a Sapling address after the Heartwood network upgrade has activated; setting a Sapling address prior to Heartwood activation will cause getblocktemplate to return block templates that cannot be mined.

Sapling viewing keys support

Support for Sapling viewing keys (specifically, Sapling extended full viewing keys, as described in ZIP 32), has been added to the wallet. Nodes will track both sent and received transactions for any Sapling addresses associated with the imported Sapling viewing keys.

• Use the z_exportviewingkey RPC method to obtain the viewing key for a shielded address in a node's wallet. For Sapling addresses, these always begin with "zxviews" (or "zxviewtestsapling" for testnet addresses).

• Use z_importviewingkey to import a viewing key into another node. Imported Sapling viewing keys will be stored in the wallet, and remembered across restarts.

• z_getbalance will show the balance of a Sapling address associated with an imported Sapling viewing key. Balances for Sapling viewing keys will be included in the output of z_gettotalbalance when the includeWatchonly parameter is set to true.

• RPC methods for viewing shielded transaction information (such as z_listreceivedbyaddress) will return information for Sapling addresses associated with imported Sapling viewing keys.

Details about what information can be viewed with these Sapling viewing keys, and what guarantees you have about that information, can be found in ZIP 310.

Removal of time adjustment and the -maxtimeadjustment= option

Prior to v2.1.1-1, zcashd would adjust the local time that it used by up to 70 minutes, according to a median of the times sent by the first 200 peers to connect to it. This mechanism was inherently insecure, since an adversary making multiple connections to the node could effectively control its time within that +/- 70 minute window (this is called a "timejacking attack").

In the v2.1.1-1 security release, in addition to other mitigations for timejacking attacks, the maximum time adjustment was set to zero by default. This effectively disabled time adjustment; however, a -maxtimeadjustment= option was provided to override this default.

As a simplification the time adjustment code has now been completely removed, together with -maxtimeadjustment=. Node operators should instead ensure that their local time is set reasonably accurately.

If it appears that the node has a significantly different time than its peers, a warning will still be logged and indicated on the metrics screen if enabled.

View shielded information in wallet transactions

In previous zcashd versions, to obtain information about shielded transactions you would use either the z_listreceivedbyaddress RPC method (which returns all notes received by an address) or z_listunspent (which returns unspent notes, optionally filtered by addresses). There were no RPC methods that directly returned details about spends, or anything equivalent to the gettransaction method (which returns transparent information about in-wallet transactions).

This release introduces a new RPC method z_viewtransaction to fill that gap. Given the ID of a transaction in the wallet, it decrypts the transaction and returns detailed shielded information for all decryptable new and spent notes, including:

• The address that each note belongs to.
• Values in both decimal ZEC/TAZ and zatoshis.
• The ID of the transaction that each spent note was received in.
• An outgoing flag on each new note, which will be true if the output is not for an address in the wallet.
• A memoStr field for each new note, containing its text memo (if its memo field contains a valid UTF-8 string).

Information will be shown for any address that appears in z_listaddresses; this includes watch-only addresses linked to viewing keys imported with z_importviewingkey, as well as addresses with spending keys (both generated with z_getnewaddress and imported with z_importkey).

Better error messages for rejected transactions after network upgrades

The Zcash network upgrade process includes several features designed to protect users. One of these is the "consensus branch ID", which prevents transactions created after a network upgrade has activated from being replayed on another chain (that might have occurred due to, for example, a friendly fork). This is known as "two-way replay protection", and is a core requirement by various members of the cryptocurrency ecosystem for supporting "hard fork"-style changes like our network upgrades.

One downside of the way replay protection is implemented in Zcash, is that there is no visible difference between a transaction being rejected by a zcashd node due to targeting a different branch, and being rejected due to an invalid signature. This has caused issues in the past when a user had not upgraded their wallet software, or when a wallet lacked support for the new network upgrade's consensus branch ID; the resulting error messages when users tried to create transactions were non-intuitive, and particularly cryptic for transparent transactions.

Starting from this release, zcashd nodes will re-verify invalid transparent and Sprout signatures against the consensus branch ID from before the most recent network upgrade. If the signature then becomes valid, the transaction will be rejected with the error message old-consensus-branch-id. This error can be handled specifically by wallet providers to inform the user that they need to upgrade their wallet software.

Wallet software can also automatically obtain the latest consensus branch ID from their (up-to-date) zcashd node, by calling getblockchaininfo and looking at {'consensus': {'nextblock': BRANCH_ID, ...}, ...} in the JSON output.

Expired transactions notifications

A new config option -txexpirynotify has been added that will cause zcashd to execute a command when a transaction in the mempool expires. This can be used to notify external systems about transaction expiry, similar to the existing -blocknotify config option that notifies when the chain tip changes.

RPC methods

• The z_importkey and z_importviewingkey RPC methods now return the type of the imported spending or viewing key (sprout or sapling), and the corresponding payment address.

• Negative heights are now permitted in getblock and getblockhash, to select blocks backwards from the chain tip. A height of -1 corresponds to the last known valid block on the main chain.

• A new RPC method getexperimentalfeatures returns the list of enabled experimental features.

Build system

• The --enable-lcov, --disable-tests, and --disable-mining flags for zcutil/build.sh have been removed. You can pass these flags instead by using the CONFIGURE_FLAGS environment variable. For example, to enable coverage instrumentation (thus enabling "make cov" to work), call:

  CONFIGURE_FLAGS="--enable-lcov --disable-hardening" ./zcutil/build.sh
  

• The build system no longer defaults to verbose output. You can re-enable verbose output with ./zcutil/build.sh V=1

This release fixes a security issue described at https://z.cash/support/security/announcements/security-announcement-2020-02-06/ .

This release also adds a -maxtimeadjustment option to set the maximum time, in seconds, by which the node's clock can be adjusted based on the clocks of its peer nodes. This option defaults to 0, meaning that no such adjustment is performed. This is a change from the previous behaviour, which was to adjust the clock by up to 70 minutes forward or backward. The maximum setting for this option is now 25 minutes (1500 seconds).

Fix for incorrect banning of nodes during syncing

After activation of the Blossom network upgrade, a node that is syncing the block chain from before Blossom would incorrectly ban peers that send it a Blossom transaction. This resulted in slower and less reliable syncing (#4283).

Notable changes

z_mergetoaddress promoted out of experimental status

The z_mergetoaddress API merges funds from t-addresses, z-addresses, or both, and sends them to a single t-address or z-address. It was added in v1.0.15 as an experimental feature, to simplify the process of combining many small UTXOs and notes into a few larger ones.

In this release we are promoting z_mergetoaddress out of experimental status. It is now a stable RPC, and any future changes to it will only be additive. See zcash-cli help z_mergetoaddress for API details and usage.

Unlike most other RPC methods, z_mergetoaddress operates over a particular quantity of UTXOs and notes, instead of a particular amount of ZEC. By default, it will merge 50 UTXOs and 10 notes at a time; these limits can be adjusted with the parameters transparent_limit and shielded_limit.

z_mergetoaddress also returns the number of UTXOs and notes remaining in the given addresses, which can be used to automate the merging process (for example, merging until the number of UTXOs falls below some value).

Option parsing behavior

Command line options are now parsed strictly in the order in which they are specified. It used to be the case that -X -noX ends up, unintuitively, with X set, as -X had precedence over -noX. This is no longer the case. Like for other software, the last specified value for an option will hold.

Low-level RPC changes

• Bare multisig outputs to our keys are no longer automatically treated as incoming payments. As this feature was only available for multisig outputs for which you had all private keys in your wallet, there was generally no use for them compared to single-key schemes. Furthermore, no address format for such outputs is defined, and wallet software can't easily send to it. These outputs will no longer show up in listtransactions, listunspent, or contribute to your balance, unless they are explicitly watched (using importaddress or importmulti with hex script argument). signrawtransaction* also still works for them.

Electric Coin Co. became aware of the following security announcement on the bitcoin-dev mailing list on 8th November: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2019-November/017453.html

Upon investigation, the team found that versions of zcashd prior to 2.1.0-1 suffered from the above bug, CVE-2017-18350. Nodes in the affected configuration (with a SOCKS proxy enabled) could be compromised by an attacker executing arbitrary code in the context of the zcashd daemon, allowing them to violate user privacy, steal user funds, or perform other unauthorized actions on the machine. The affected configuration is not the default.

zcashd version 2.1.0-1 contains a fix for this issue, and we recommend updating all affected nodes as soon as possible.

Blossom network upgrade

The mainnet activation of the Blossom network upgrade is supported by this release, with an activation height of 653600, which should occur in early December — roughly one day following the targeted EOS halt of our 2.0.7-3 release. Please upgrade to this release, or any subsequent release, in order to follow the Blossom network upgrade.

The Blossom network upgrade implements ZIP 208 which shortens block times from 150s to 75s.

DoS Mitigation: Mempool Size Limit and Random Drop

This release adds a mechanism for preventing nodes from running out of memory in the situation where an attacker is trying to overwhelm the network with transactions. This is achieved by keeping track of and limiting the total cost and evictionWeight of all transactions in the mempool. The cost of a transaction is determined by its size in bytes, and its evictionWeight is a function of the transaction's cost and its fee. The maximum total cost is configurable via the parameter mempooltxcostlimit which defaults to 80,000,000 (up to 20,000 txs). If a node's total mempool cost exceeds this limit the node will evict a random transaction, preferentially picking larger transactions and ones with below the standard fee. To prevent a node from re-accepting evicted transactions, it keeps track of ones that it has evicted recently. By default, a transaction will be considered recently evicted for 60 minutes, but this can be configured with the parameter mempoolevictionmemoryminutes.

For full details see ZIP 401.

Asynchronous Operations Incorrectly Reporting Success

We fixed an issue where asynchronous operations were sometimes reporting success when they had actually failed. One way this could occur was when trying to use z_sendmany to create a transaction spending coinbase funds in a way where change would be generated (not a valid use of z_sendmany). In this case the operation would erroneously report success, and the only way to see that the transaction had actually failed was to look in the debug.log file. Such operations will now correctly report that they have failed.

Fake chain detection during initial block download

One of the mechanisms that zcashd uses to detect whether it is in "initial block download" (IBD) mode is to compare the active chain's cumulative work against a hard-coded "minimum chain work" value. This mechanism (inherited from Bitcoin Core) means that once a node exits IBD mode, it is either on the main chain, or a fake alternate chain with similar amounts of work. In the latter case, the node has most likely become the victim of a 50% + 1 adversary.

Starting from this release, zcashd additionally hard-codes the block hashes for the activation blocks of each past network upgrade (NU). During initial chain synchronization, and after the active chain has reached "minimum chain work", the node checks the blocks at each NU activation height against the hard-coded hashes. If any of them do not match, the node will immediately alert the user and shut down for safety.

Disabling old Sprout proofs

As part of our ongoing work to clean up the codebase and minimise the security surface of zcashd, we are removing libsnark from the codebase, and dropping support for creating and verifying old Sprout proofs. Funds stored in Sprout addresses are not affected, as they are spent using the hybrid Sprout circuit (built using bellman) that was deployed during the Sapling network upgrade.

This change has several implications:

• zcashd no longer verifies old Sprout proofs, and will instead assume they are valid. This has a minor implication for nodes: during initial block download, an adversary could feed the node fake blocks containing invalid old Sprout proofs, and the node would accept the fake chain as valid. However, as soon as the active chain contains at least as much work as the hard-coded "minimum chain work" value, the node will detect this situation and shut down.

• Shielded transactions can no longer be created before Sapling has activated. This does not affect Zcash itself, but will affect downstream codebases that have not yet activated Sapling (or that start a new chain after this point and do not activate Sapling from launch). Note that the old Sprout circuit is vulnerable to counterfeiting and should not be used in current deployments.

• Starting from this release, the circuit parameters from the original Sprout MPC are no longer required to start zcashd, and will not be downloaded by fetch-params.sh. They are not being automatically deleted at this time.

We would like to take a moment to thank the libsnark authors and contributors. It was vital to the success of Zcash, and the development of zero-knowledge proofs in general, to have this code available and usable.

This release fixes a security issue described at https://z.cash/support/security/announcements/security-announcement-2019-09-24/ .

Users should upgrade their nodes to this version immediately and discontinue use of older versions.

Please note that the issue does not put funds at risk of theft or counterfeiting.

The service period of this release is shorter than normal due to the upcoming v2.1.0 Blossom release. The End-of-Service of v2.0.7-3 will occur at block height 653012, expected to be on 2019-12-10.

Shrinking of debug.log files is temporarily disabled

In previous versions, zcashd would shrink the debug.log file to 200 KB on startup if it was larger than 10 MB. This behaviour, and the -shrinkdebugfile option that controlled it, has been disabled.

Pre-Blossom EOS Halt

v2.0.7-2 contains a shortened EOS halt so that it is in alignment with v2.0.7.

Testnet Blossom Rewind

Testnet users needed to upgrade to 2.0.7 before Blossom activated. The amount of notice given to these users was brief, so many were not able to upgrade in time. These users may now be on the wrong branch. v2.0.7-2 adds an "intended rewind" to prevent having to manually reindex when reconnecting to the correct chain.

Insight Explorer Logging Fix

Fixed an issue where ERROR: spent index not enabled would be logged unnecessarily.