Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change the specification of minimum-difficulty blocks to reflect the zcashd implementation #417

Merged
merged 4 commits into from
Nov 13, 2020
Merged

Change the specification of minimum-difficulty blocks to reflect the zcashd implementation #417

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8c28907
Change the specification of minimum-difficulty blocks to reflect the …
daira Nov 11, 2020
9a4ebc9
ZIP 208: "at least" -> "greater than". refs https://github.com/ZcashF…
daira Nov 12, 2020
1ea9859
ZIPs 205 and 208: conformance language.
daira Nov 12, 2020
ec045af
ZIPs 205 and 208: wording tweak.
daira Nov 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 53 additions & 20 deletions zip-0205.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,27 +15,28 @@
Created: 2018-10-08
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 key words "MUST" and "SHOULD" 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">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 MUST be 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 modified 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
48 changes: 28 additions & 20 deletions zip-0205.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,15 @@
Terminology
===========

The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be
interpreted as described in RFC 2119. [#RFC2119]_
The key words "MUST" and "SHOULD" in this document are to be 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 MUST be 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 modified 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