Looking for minimal Heartwood upgrade instructions


I read the changes for the ZCash Heartwood upgrade, and my current understanding is that there are no changes required to mine blocks due to the “shielded coinbase transaction” upgrade, but that there are major breaking changes required to support the new merkle tree. This understanding may be incorrect.

I have not been able to find any mining software code to determine if all the changes are already handled in the ZCash daemon before getblocktemplate is called, or whether the data that is sent to miners and submitted to the network actually needs to change. It seems to me that the miners won’t know the difference, because the documentation states that an existing field is used for the new merkle root, and that that was done on purpose. But it’s not clear to me from those documents whether any work needs to be done in the mining server to compute this different data, or whether the existing RPC calls perform this work in the daemon code with zero or minor changes required in the mining server.

Has anyone created a step-by-step “absolute minimum work” instruction manual, for pools that cannot afford to implement the shielded coinbase outputs and which are having trouble understanding what needs to be done with the merkle tree changes? It would be great if someone could weigh in on the minimal upgrade path here, so that we can decide whether to pay to upgrade or to discontinue ZCash mining.


-Steve Sokolowski


Hey Steve, is it possible for you to mine a couple of blocks on testnet? All changes for heartwood are active on testnet.

1 Like

This is a great idea. I’ll try this first thing in the morning and will report back then.


The only change from Heartwood activation that requires mining pool attention is the interpretation of the RESERVED field of the Stratum protocol (and the corresponding value in the block header).

  • At Zcash launch this was reserved as all-zeroes, and the block header field was named hashReserved.
  • From Sapling activation it was set to the root of the Sapling commitment tree, and the field was renamed hashFinalSaplingRoot.
  • From Heartwood activation, it instead is set to the root of the FlyClient history tree (which internally commits to the Sapling commitment tree); as such, the field has been renamed to hashLightClientRoot, to cover both Sapling and Heartwood usage.

The short answer is that if you are using the getblocktemplate RPC method, then you shouldn’t need to do anything. zcashd will handle the FlyClient history tree creation and management, and it will place the value that should go in the RESERVED field of the Stratum protocol (and the corresponding position in the block header) into the finalsaplingroothash field in the output of getblocktemplate. As long as your mining pool software is not expecting this value to specifically be the Sapling root hash, and instead is treating it opaquely and passing it through to miners, then everything should continue to function correctly.

You should however migrate your mining pool software to use the lightclientroothash field wherever you were previously using finalsaplingroothash; the latter is deprecated and will be removed at some point, as it no longer actually contains the Sapling root hash.


Could you clarify whether the finalsaplingroothash field will automatically change between the block before the fork and the block after the fork, such that it is possible to upgrade before the fork and the client will determine when to switch the meaning of the field?

1 Like

That is indeed the case:


Great - thanks! Then I’ll just have an employee upgrade to the latest version of ZCash, and we’ll be all set.

I want to thank the people in charge here for their forward thinking. Some coins push thousands of dollars of development work off onto pools and miners every time there is an upgrade, much of which is unnecessary with proper design. An example is Ravencoin, which we discontinued recently because in the process of changing algorithms, they also changed the stratum protocol because someone felt the halving of bandwidth was worth the labor cost of having to retest everything.

Here, you came up with a design that requires minimal changes, will not cause critical bugs, and which will not cause anyone to have to make a business decision of whether it makes sense to perform the upgrade or not. Thanks again!