Skip to content

Commit

Permalink
Change the specification of minimum-difficulty blocks to reflect the …
Browse files Browse the repository at this point in the history 
…zcashd implementation

(which alters nBits rather than just the target threshold). fixes #416

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
  • Loading branch information
@daira
daira committed Nov 11, 2020
1 parent 806076c commit 8c28907
Show file tree
Hide file tree
Showing 4 changed files with 140 additions and 72 deletions.
71 changes: 52 additions & 19 deletions zip-0205.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +16,27 @@
License: MIT</pre>
<section id="terminology"><h2><span class="section-heading">Terminology</span><span class="section-anchor"> <a rel="bookmark" href="#terminology"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119. <a id="id1" class="footnote_reference" href="#rfc2119">1</a></p>
<p>The terms "consensus branch" and "network upgrade" in this document are to be interpreted as described in ZIP 200. <a id="id2" class="footnote_reference" href="#zip-0200">3</a></p>
<p>The terms "consensus branch" and "network upgrade" in this document are to be interpreted as described in ZIP 200. <a id="id2" class="footnote_reference" href="#zip-0200">7</a></p>
<p>The terms "Testnet" and "Mainnet" are to be interpreted as described in section 3.11 of the Zcash Protocol Specification <a id="id3" class="footnote_reference" href="#protocol-networks">3</a>.</p>
<p>The terms below are to be interpreted as follows:</p>
<dl>
<dt>Sapling</dt>
<dd>Code-name for the second Zcash network upgrade, also known as Network Upgrade 1.</dd>
</dl>
</section>
<section id="abstract"><h2><span class="section-heading">Abstract</span><span class="section-anchor"> <a rel="bookmark" href="#abstract"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This proposal defines the deployment of the Sapling network upgrade. In addition, it describes a hard fork that occurred on testnet to allow "minimum-difficulty" blocks.</p>
<p>This proposal defines the deployment of the Sapling network upgrade. In addition, it describes a hard fork that occurred on Testnet to allow "minimum-difficulty" blocks.</p>
</section>
<section id="specification"><h2><span class="section-heading">Specification</span><span class="section-anchor"> <a rel="bookmark" href="#specification"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="sapling-deployment"><h3><span class="section-heading">Sapling deployment</span><span class="section-anchor"> <a rel="bookmark" href="#sapling-deployment"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The primary sources of information about Sapling consensus protocol changes are:</p>
<ul>
<li>The Zcash Protocol Specification <a id="id3" class="footnote_reference" href="#protocol">2</a>.</li>
<li>Transaction Signature Validation for Sapling <a id="id4" class="footnote_reference" href="#zip-0243">5</a>.</li>
<li>Network Upgrade Activation Mechanism <a id="id5" class="footnote_reference" href="#zip-0200">3</a>.</li>
<li>The Zcash Protocol Specification <a id="id4" class="footnote_reference" href="#protocol">2</a>.</li>
<li>Transaction Signature Validation for Sapling <a id="id5" class="footnote_reference" href="#zip-0243">9</a>.</li>
<li>Network Upgrade Activation Mechanism <a id="id6" class="footnote_reference" href="#zip-0200">7</a>.</li>
</ul>
<p>The network handshake and peer management mechanisms defined in <a id="id6" class="footnote_reference" href="#zip-0201">4</a> also apply to this upgrade.</p>
<p>The following network upgrade constants <a id="id7" class="footnote_reference" href="#zip-0200">3</a> are defined for the Sapling upgrade:</p>
<p>The network handshake and peer management mechanisms defined in <a id="id7" class="footnote_reference" href="#zip-0201">8</a> also apply to this upgrade.</p>
<p>The following network upgrade constants <a id="id8" class="footnote_reference" href="#zip-0200">7</a> are defined for the Sapling upgrade:</p>
<dl>
<dt>CONSENSUS_BRANCH_ID</dt>
<dd><code>0x76b809bb</code></dd>
Expand All @@ -45,24 +46,24 @@
<p>Mainnet: 419200</p>
</dd>
</dl>
<p>On testnet, Sapling had activated prior to this height, but that consensus branch was rolled back. A subsequent hard fork occurred on testnet, changing the difficulty algorithm to accept "minimum-difficulty" blocks under certain conditions starting at block height 299188.</p>
<p>On both mainnet and testnet, Sapling-compatible nodes MUST advertise protocol version 170007 or later. The minimum peer protocol version that Sapling-compatible nodes will connect to, remains 170002.</p>
<p>On Testnet, Sapling had activated prior to this height, but that consensus branch was rolled back. A subsequent hard fork occurred on Testnet, changing the difficulty algorithm to accept "minimum-difficulty" blocks under certain conditions starting at block height 299188.</p>
<p>On both Mainnet and Testnet, Sapling-compatible nodes MUST advertise protocol version 170007 or later. The minimum peer protocol version that Sapling-compatible nodes will connect to, remains 170002.</p>
<p>Pre-Sapling nodes are defined as nodes advertising a protocol version less than 170007.</p>
<p>Approximately three days (defined in terms of block height) before the Sapling activation height, Sapling-compatible nodes will change the behaviour of their peer connection logic in order to prefer pre-Sapling peers for eviction from the set of peer connections.</p>
<pre>/** The period before a network upgrade activates, where connections to upgrading peers are preferred (in blocks). */
static const int NETWORK_UPGRADE_PEER_PREFERENCE_BLOCK_PERIOD = 24 * 24 * 3;</pre>
<p>The implementation is similar to that for Overwinter which was described in <a id="id8" class="footnote_reference" href="#zip-0201">4</a>.</p>
<p>Once Sapling activates on testnet or mainnet, Sapling nodes should take steps to:</p>
<p>The implementation is similar to that for Overwinter which was described in <a id="id9" class="footnote_reference" href="#zip-0201">8</a>.</p>
<p>Once Sapling activates on Testnet or Mainnet, Sapling nodes should take steps to:</p>
<ul>
<li>reject new connections from pre-Sapling nodes;</li>
<li>disconnect any existing connections to pre-Sapling nodes.</li>
</ul>
</section>
<section id="change-to-difficulty-adjustment-on-testnet"><h3><span class="section-heading">Change to difficulty adjustment on testnet</span><span class="section-anchor"> <a rel="bookmark" href="#change-to-difficulty-adjustment-on-testnet"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Section 7.6.3 of <a id="id9" class="footnote_reference" href="#protocol">2</a> describes the algorithm used to adjust the difficulty of a block (defined in terms of a "target threshold") based on the <code>nTime</code> and <code>nBits</code> fields of preceding blocks.</p>
<p>This algorithm changed on testnet, starting from block 299188, to allow "minimum-difficulty" blocks. If the block time of a block from this height onward is greater than 15 minutes after that of the preceding block, then the block is a minimum-difficulty block, and its target threshold is set to the value of PoWLimit for testnet (see <a id="id10" class="footnote_reference" href="#protocol">2</a> section 5.3). However, its <code>nBits</code> field is still computed according to the original difficulty adjustment algorithm.</p>
<p>This does not affect how the minimum-difficulty block is treated for subsequent difficulty adjustments. In particular, only the <code>nBits</code> field computed by the original algorithm is used for the purpose of computing the MeanTarget values from which subsequent difficulty changes are calculated.</p>
<p>This change does not affect mainnet.</p>
<section id="change-to-difficulty-adjustment-on-testnet"><h3><span class="section-heading">Change to difficulty adjustment on Testnet</span><span class="section-anchor"> <a rel="bookmark" href="#change-to-difficulty-adjustment-on-testnet"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Section 7.6.3 of the Zcash Protocol Specification <a id="id10" class="footnote_reference" href="#protocol-diffadjustment">5</a> describes the algorithm used to adjust the difficulty of a block (defined in terms of a "target threshold") based on the <code>nTime</code> and <code>nBits</code> fields of preceding blocks.</p>
<p>This algorithm changed on Testnet, starting from block 299188, to allow "minimum-difficulty" blocks. If the block time of a block from this height onward is greater than 15 minutes after that of the preceding block, then the block is a minimum-difficulty block. In that case its <code>nBits</code> field is set to ToCompact(PoWLimit), where PoWLimit is the value defined for Testnet in section 5.3 of the Zcash Protocol Specification <a id="id11" class="footnote_reference" href="#protocol-constants">4</a>, and ToCompact is as defined in section 7.6.4 of that specification <a id="id12" class="footnote_reference" href="#protocol-nbits">6</a>.</p>
<p>Note: a previous revision of this ZIP incorrectly said that only the target threshold of minimum-difficulty blocks is affected. In fact the <code>nBits</code> field is as well, and this affects difficulty adjustment for subsequent blocks.</p>
<p>This change does not affect Mainnet.</p>
</section>
</section>
<section id="backward-compatibility"><h2><span class="section-heading">Backward compatibility</span><span class="section-anchor"> <a rel="bookmark" href="#backward-compatibility"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
Expand All @@ -89,26 +90,58 @@
</tr>
</tbody>
</table>
<table id="zip-0200" class="footnote">
<table id="protocol-networks" class="footnote">
<tbody>
<tr>
<th>3</th>
<td><a href="protocol/protocol.pdf#networks">Zcash Protocol Specification, Version 2020.1.15. Section 3.11: Mainnet and Testnet</a></td>
</tr>
</tbody>
</table>
<table id="protocol-constants" class="footnote">
<tbody>
<tr>
<th>4</th>
<td><a href="protocol/protocol.pdf#constants">Zcash Protocol Specification, Version 2020.1.15. Section 5.3: Constants</a></td>
</tr>
</tbody>
</table>
<table id="protocol-diffadjustment" class="footnote">
<tbody>
<tr>
<th>5</th>
<td><a href="protocol/protocol.pdf#diffadjustment">Zcash Protocol Specification, Version 2020.1.15. Section 7.6.3: Difficulty adjustment</a></td>
</tr>
</tbody>
</table>
<table id="protocol-nbits" class="footnote">
<tbody>
<tr>
<th>6</th>
<td><a href="protocol/protocol.pdf#nbits">Zcash Protocol Specification, Version 2020.1.15. Section 7.6.4: nBits conversion</a></td>
</tr>
</tbody>
</table>
<table id="zip-0200" class="footnote">
<tbody>
<tr>
<th>7</th>
<td><a href="zip-0200">ZIP 200: Network Upgrade Activation Mechanism</a></td>
</tr>
</tbody>
</table>
<table id="zip-0201" class="footnote">
<tbody>
<tr>
<th>4</th>
<th>8</th>
<td><a href="zip-0201">ZIP 201: Network Peer Management for Overwinter</a></td>
</tr>
</tbody>
</table>
<table id="zip-0243" class="footnote">
<tbody>
<tr>
<th>5</th>
<th>9</th>
<td><a href="zip-0243">ZIP 243: Transaction Signature Validation for Sapling</a></td>
</tr>
</tbody>
Expand Down
44 changes: 26 additions & 18 deletions zip-0205.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ interpreted as described in RFC 2119. [#RFC2119]_
The terms "consensus branch" and "network upgrade" in this document are to be
interpreted as described in ZIP 200. [#zip-0200]_

The terms "Testnet" and "Mainnet" are to be interpreted as described in
section 3.11 of the Zcash Protocol Specification [#protocol-networks]_.

The terms below are to be interpreted as follows:

Sapling
Expand All @@ -29,7 +32,7 @@ Abstract
========

This proposal defines the deployment of the Sapling network upgrade. In addition,
it describes a hard fork that occurred on testnet to allow "minimum-difficulty"
it describes a hard fork that occurred on Testnet to allow "minimum-difficulty"
blocks.


Expand Down Expand Up @@ -61,12 +64,12 @@ ACTIVATION_HEIGHT (Sapling)
Mainnet: 419200


On testnet, Sapling had activated prior to this height, but that consensus branch
was rolled back. A subsequent hard fork occurred on testnet, changing the
On Testnet, Sapling had activated prior to this height, but that consensus branch
was rolled back. A subsequent hard fork occurred on Testnet, changing the
difficulty algorithm to accept "minimum-difficulty" blocks under certain
conditions starting at block height 299188.

On both mainnet and testnet, Sapling-compatible nodes MUST advertise protocol
On both Mainnet and Testnet, Sapling-compatible nodes MUST advertise protocol
version 170007 or later. The minimum peer protocol version that Sapling-compatible
nodes will connect to, remains 170002.

Expand All @@ -86,32 +89,33 @@ peer connections.
The implementation is similar to that for Overwinter which was described in
[#zip-0201]_.

Once Sapling activates on testnet or mainnet, Sapling nodes should take steps to:
Once Sapling activates on Testnet or Mainnet, Sapling nodes should take steps to:

- reject new connections from pre-Sapling nodes;
- disconnect any existing connections to pre-Sapling nodes.


Change to difficulty adjustment on testnet
Change to difficulty adjustment on Testnet
------------------------------------------

Section 7.6.3 of [#protocol]_ describes the algorithm used to adjust the difficulty
of a block (defined in terms of a "target threshold") based on the ``nTime`` and
``nBits`` fields of preceding blocks.
Section 7.6.3 of the Zcash Protocol Specification [#protocol-diffadjustment]_
describes the algorithm used to adjust the difficulty of a block (defined in terms
of a "target threshold") based on the ``nTime`` and ``nBits`` fields of preceding
blocks.

This algorithm changed on testnet, starting from block 299188, to allow
This algorithm changed on Testnet, starting from block 299188, to allow
"minimum-difficulty" blocks. If the block time of a block from this height onward
is greater than 15 minutes after that of the preceding block, then the block is a
minimum-difficulty block, and its target threshold is set to the value of
PoWLimit for testnet (see [#protocol]_ section 5.3). However, its ``nBits`` field
is still computed according to the original difficulty adjustment algorithm.
minimum-difficulty block. In that case its ``nBits`` field is set to
ToCompact(PoWLimit), where PoWLimit is the value defined for Testnet in section 5.3
of the Zcash Protocol Specification [#protocol-constants]_, and ToCompact is as
defined in section 7.6.4 of that specification [#protocol-nbits]_.

This does not affect how the minimum-difficulty block is treated for subsequent
difficulty adjustments. In particular, only the ``nBits`` field computed by the
original algorithm is used for the purpose of computing the MeanTarget values
from which subsequent difficulty changes are calculated.
Note: a previous revision of this ZIP incorrectly said that only the target
threshold of minimum-difficulty blocks is affected. In fact the ``nBits`` field
is as well, and this affects difficulty adjustment for subsequent blocks.

This change does not affect mainnet.
This change does not affect Mainnet.


Backward compatibility
Expand Down Expand Up @@ -141,6 +145,10 @@ References

.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels <https://www.rfc-editor.org/rfc/rfc2119.html>`_
.. [#protocol] `Zcash Protocol Specification, Version 2020.1.15 or later <protocol/protocol.pdf>`_
.. [#protocol-networks] `Zcash Protocol Specification, Version 2020.1.15. Section 3.11: Mainnet and Testnet <protocol/protocol.pdf#networks>`_
.. [#protocol-constants] `Zcash Protocol Specification, Version 2020.1.15. Section 5.3: Constants <protocol/protocol.pdf#constants>`_
.. [#protocol-diffadjustment] `Zcash Protocol Specification, Version 2020.1.15. Section 7.6.3: Difficulty adjustment <protocol/protocol.pdf#diffadjustment>`_
.. [#protocol-nbits] `Zcash Protocol Specification, Version 2020.1.15. Section 7.6.4: nBits conversion <protocol/protocol.pdf#nbits>`_
.. [#zip-0200] `ZIP 200: Network Upgrade Activation Mechanism <zip-0200.rst>`_
.. [#zip-0201] `ZIP 201: Network Peer Management for Overwinter <zip-0201.rst>`_
.. [#zip-0243] `ZIP 243: Transaction Signature Validation for Sapling <zip-0243.rst>`_
Loading

0 comments on commit 8c28907

Please sign in to comment.