v5.4.1

Notable changes

allowdeprecated in zcash.conf

In v5.0.0 a feature deprecation framework was released, to enable zcashd features to be formally deprecated and removed:

• In stage 1, a feature is marked as deprecated, but otherwise left as-is. It remains in this stage for at least 18 weeks.
• In stage 2, the feature is default-disabled, but can be re-enabled with the -allowdeprecated config option. It remains in this stage for at least 18 weeks.
• Finally, the feature is removed - either entirely, or (e.g. in the case of RPC methods that were inherited from Bitcoin Core) with a "tombstone" left to inform users of the removal (and what to use instead if applicable).

Config options can be specified either as a zcashd argument (-option=value) or in zcash.conf (as a option=value line). However, due to a bug in the implementation, allowdeprecated=feature lines in zcash.conf were ignored. The bug went unnoticed until v5.4.0, in which the first group of features moved from stage 1 to stage 2. This hotfix release fixes the bug.

Fixed RPC blocking and wallet view lag on reindex

The known issue reported in the v5.4.0 release notes has been fixed.

v5.4.0

Notable changes

Fixes

This release fixes an issue that could potentially cause a node to crash with the log message "The wallet's best block hash <hash> was not detected in restored chain state. Giving up; please restart with -rescan."

Additionally, a bug that could cause an assertion failure during reindexing has been fixed. See #6387 for details.

Known issues

• When zcashd is started with -reindex, until the node's chain tip catches back up to the main chain, RPC calls might block for long periods of time (or time out), and the wallet's view of the chain may lag significantly behind the node's chain tip. See #6406 for details and the fix (which will be included in the next release).

Transparent pool and chain supply tracking

Since v2.0.0, zcashd has tracked the change in value within the Sprout and Sapling shielded pools for each block; v5.0.0 added the Orchard pool. This release completes the set, by tracking the change in value within the "transparent" pool (more precisely, the value stored in Bitcoin-style UTXOs).

zcashd also now tracks the change in "chain supply" for each block, defined as the sum of coinbase output values, minus unclaimed fees. This is precisely equal to the sum of the value in the transparent and shielded pools, and equivalent to the sum of all unspent coins/notes on the chain. It is bounded above by the theoretical maximum supply, but in practice is lower due to, for example, miners not claiming transaction fees.

Bitcoin-style consensus rules implement fees as an imbalance between spent coins/notes and newly-created coins/notes. The consensus rules require that a coinbase transaction's outputs have a total value no greater than the sum of that block's subsidy and the fees made available by the transactions in the block. However, the consensus rules do not require that all of the available funds are claimed, and a miner can create coinbase transactions with lower value in the outputs (though in the case of Zcash, the consensus rules do require the transaction to include ZIP 1014 Funding Stream outputs).

After upgrading to v5.4.0, zcashd will start tracking changes in transparent pool value and chain supply from the height at which it is restarted. Block heights prior to this will not have any information recorded. To track changes from genesis, and thus monitor the total transparent pool size and chain supply, you would need to restart your node with the -reindex option.

Wallet Performance Fixes

The 100MiB memory limit for the batch scanner has been replaced by a 1000-block limit. This eliminates an expensive call to determine the current memory usage of the batch scanner.

The following associated metric has been removed from the set of metrics reported when -prometheusport is set:

• (gauge) zcashd.wallet.batchscanner.usage.bytes

RPC Changes

• z_sendmany will no longer select transparent coinbase when "ANY_TADDR" is used as the fromaddress. It was already documented to do this, but the previous behavior didn’t match. When coinbase notes were selected in this case, they would (properly) require that the transaction didn’t have any change, but this could be confusing, as the documentation stated that these two conditions (using "ANY_TADDR" and disallowing change) wouldn’t coincide.
• A new value pool object with "id": "transparent" has been added to the valuePools list in getblockchaininfo and getblock.
• A new chainSupply key has been added to getblockchaininfo and getblock to report the total chain supply as of that block height (if tracked), and the change in chain supply caused by the block (for getblock, if measured).

Mining

• Changes to getblocktemplate have been backported from upstream Bitcoin Core, to significantly improve its performance by doing more work ahead of time in the mempool (and reusing the work across multiple getblocktemplate calls).

Deprecations

The following features have been deprecated, but remain available by default. These features may be disabled by setting -allowdeprecated=none. 18 weeks after this release, these features will be disabled by default and the following flags to -allowdeprecated will be required to permit their continued use:

• gbt_oldhashes: the finalsaplingroothash, lightclientroothash, and blockcommitmentshash fields in the output of getblocktemplate have been replaced by the defaultroots field.

The following previously-deprecated features have been disabled by default, and will be removed in 18 weeks:

• legacy_privacy
• getnewaddress
• getrawchangeaddress
• z_getnewaddress
• z_listaddresses
• addrtype
• wallettxvjoinsplit

The following previously-deprecated features have been removed:

• dumpwallet
• zcrawreceive
• zcrawjoinsplit
• zcrawkeygen

Platform Support

• CentOS 8 has been removed from the list of supported platforms. It reached EoL on December 31st 2021, and does not satisfy our Tier 2 policy requirements.

v5.3.2

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.

v5.3.1

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.

v5.3.0

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.

v5.2.0

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.

v5.1.0

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.

v5.0.0

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.

v4.7.0

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 5990853.
• 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 zcash/halo2@247cd62.
• 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 repla...

v4.6.0-2

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.