zec
/
zips
mirror of https://github.com/zcash/zips.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add ZIP 250: Deployment of the Heartwood Network Upgrade. 

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
This commit is contained in:
Daira Hopwood 2020-02-29 16:13:52 +00:00
parent 1aa17db44e
commit 94f8cdcae5
8 changed files with 316 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.rst
View File

@ -64,6 +64,7 @@ Index of ZIPs
<tr> <td>213</td> <td class="left"><a href="zip-0213.rst">Shielded Coinbase</a></td> <td>Implemented (zcashd)</td>
<tr> <td>221</td> <td class="left"><a href="zip-0221.rst">FlyClient - Consensus-Layer Changes</a></td> <td>Proposed</td>
<tr> <td>243</td> <td class="left"><a href="zip-0243.rst">Transaction Signature Verification for Sapling</a></td> <td>Final</td>
<tr> <td>250</td> <td class="left"><a href="zip-0250.rst">Deployment of the Heartwood Network Upgrade</a></td> <td>Draft</td>
<tr> <td>308</td> <td class="left"><a href="zip-0308.rst">Sprout to Sapling Migration</a></td> <td>Final</td>
<tr> <td>401</td> <td class="left"><a href="zip-0401.rst">Addressing mempool denial-of-service</a></td> <td>Final</td>
<tr> <td><strike>1001</strike></td> <td class="left"><strike><a href="zip-1001.rst">Keep the Block Distribution as Initially Defined — 90% to Miners</a></strike></td> <td>Obsolete</td>

1
index.html
View File

@ -43,6 +43,7 @@
<tr> <td>213</td> <td class="left"><a href="zip-0213">Shielded Coinbase</a></td> <td>Implemented (zcashd)</td>
<tr> <td>221</td> <td class="left"><a href="zip-0221">FlyClient - Consensus-Layer Changes</a></td> <td>Proposed</td>
<tr> <td>243</td> <td class="left"><a href="zip-0243">Transaction Signature Verification for Sapling</a></td> <td>Final</td>
<tr> <td>250</td> <td class="left"><a href="zip-0250">Deployment of the Heartwood Network Upgrade</a></td> <td>Draft</td>
<tr> <td>308</td> <td class="left"><a href="zip-0308">Sprout to Sapling Migration</a></td> <td>Final</td>
<tr> <td>401</td> <td class="left"><a href="zip-0401">Addressing mempool denial-of-service</a></td> <td>Final</td>
<tr> <td><strike>1001</strike></td> <td class="left"><strike><a href="zip-1001">Keep the Block Distribution as Initially Defined — 90% to Miners</a></strike></td> <td>Obsolete</td>

10
zip-0213.html
View File

@ -66,7 +66,7 @@ License: MIT</pre>
<p>Revealing the coinbase output notes does not enable anyone else to detect when the note is spent, which removes the need for a separate shielding step like is enforced for transparent coinbase outputs.</p>
</section>
<section id="deployment"><h2><span class="section-heading">Deployment</span><span class="section-anchor"> <a href="#deployment"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This proposal will be deployed with the Heartwood network upgrade.</p>
<p>This proposal will be deployed with the Heartwood network upgrade. <a id="id7" class="footnote_reference" href="#zip-0250">5</a></p>
</section>
<section id="reference-implementation"><h2><span class="section-heading">Reference Implementation</span><span class="section-anchor"> <a href="#reference-implementation"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p><a href="https://github.com/zcash/zcash/pull/4256">https://github.com/zcash/zcash/pull/4256</a></p>
@ -104,6 +104,14 @@ License: MIT</pre>
</tr>
</tbody>
</table>
<table id="zip-0250" class="footnote">
<tbody>
<tr>
<th>5</th>
<td><a href="https://github.com/zcash/zips/blob/master/zip-0250.rst">ZIP 250: Deployment of the Heartwood Network Upgrade</a></td>
</tr>
</tbody>
</table>
</section>
</section>
</body>

3
zip-0213.rst
View File

@ -177,7 +177,7 @@ transparent coinbase outputs.
Deployment
==========
This proposal will be deployed with the Heartwood network upgrade.
This proposal will be deployed with the Heartwood network upgrade. [#zip-0250]_
Reference Implementation
@ -193,3 +193,4 @@ References
.. [#zip-0200] `ZIP 200: Network Upgrade Activation Mechanism <https://github.com/zcash/zips/blob/master/zip-0200.rst>`_
.. [#zip-0205] `ZIP 205: Deployment of the Sapling Network Upgrade <https://github.com/zcash/zips/blob/master/zip-0205.rst>`_
.. [#zip-0207] `ZIP 207: Split Founders' Reward <https://github.com/zcash/zips/blob/master/zip-0207.rst>`_
.. [#zip-0250] `ZIP 250: Deployment of the Heartwood Network Upgrade <https://github.com/zcash/zips/blob/master/zip-0250.rst>`_

55
zip-0221.html
View File

@ -19,7 +19,7 @@ Created: 2019-03-30
License: MIT</pre>
<section id="terminology"><h2><span class="section-heading">Terminology</span><span class="section-anchor"> <a href="#terminology"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>The key words "<strong>MUST</strong>", "<strong>SHOULD</strong>", and "<strong>MAY</strong>" 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 "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">2</a></p>
<p>The terms "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">8</a></p>
<dl>
<dt><em>Light client</em></dt>
<dd>A client that is not a full participant in the network of Zcash peers. It can send and receive payments, but does not store or validate a copy of the block chain.</dd>
@ -40,7 +40,7 @@ License: MIT</pre>
</dl>
</section>
<section id="abstract"><h2><span class="section-heading">Abstract</span><span class="section-anchor"> <a href="#abstract"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This ZIP specifies modifications to the Zcash block header semantics and consensus rules in order to support the probabilistic verification FlyClient protocol <a id="id3" class="footnote_reference" href="#flyclient">7</a>. The <code>hashFinalSaplingRoot</code> commitment in the block header is replaced with a commitment to the root of a Merkle Mountain Range (MMR), that in turn commits to various features of the chain's history, including the Sapling commitment tree.</p>
<p>This ZIP specifies modifications to the Zcash block header semantics and consensus rules in order to support the probabilistic verification FlyClient protocol <a id="id3" class="footnote_reference" href="#flyclient">2</a>. The <code>hashFinalSaplingRoot</code> commitment in the block header is replaced with a commitment to the root of a Merkle Mountain Range (MMR), that in turn commits to various features of the chain's history, including the Sapling commitment tree.</p>
</section>
<section id="background"><h2><span class="section-heading">Background</span><span class="section-anchor"> <a href="#background"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>An MMR is a Merkle tree which allows for efficient appends, proofs, and verifications. Informally, appending data to an MMR consists of creating a new leaf and then iteratively merging neighboring subtrees with the same size. This takes at most
@ -151,7 +151,7 @@ License: MIT</pre>
<p>MMR trees allow for efficient incremental set update operations (push, pop, prune). In addition, MMR update operations and Merkle proofs for recent additions to the leaf set are more efficient than other incremental Merkle tree implementations (e.g. Bitcoin's padded leafset, sparse Merkle trees, and Zcash's incremental note commitment trees).</p>
</section>
<section id="motivation"><h2><span class="section-heading">Motivation</span><span class="section-anchor"> <a href="#motivation"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>MMR proofs are used in the FlyClient protocol <a id="id5" class="footnote_reference" href="#flyclient">7</a>, to reduce the proof size needed for light clients to verify:</p>
<p>MMR proofs are used in the FlyClient protocol <a id="id5" class="footnote_reference" href="#flyclient">2</a>, to reduce the proof size needed for light clients to verify:</p>
<ul>
<li>the validity of a block chain received from a full node, and</li>
<li>the inclusion of a block
@ -171,7 +171,7 @@ License: MIT</pre>
<p>(
<span class="math">\(x\)</span>
is the activation height of the most recent upgrade network upgrade.)</p>
<p>FlyClient reduces the number of block headers needed for light client verification of a valid chain, from linear (as in the current reference protocol) to logarithmic in block chain length. This verification is correct with high probability. It also allows creation of subtree proofs, so light clients need only check blocks later than the most recently verified block index. Following that, verification of a transaction inclusion within that block follows the usual reference protocol <a id="id6" class="footnote_reference" href="#zip-0307">5</a>.</p>
<p>FlyClient reduces the number of block headers needed for light client verification of a valid chain, from linear (as in the current reference protocol) to logarithmic in block chain length. This verification is correct with high probability. It also allows creation of subtree proofs, so light clients need only check blocks later than the most recently verified block index. Following that, verification of a transaction inclusion within that block follows the usual reference protocol <a id="id6" class="footnote_reference" href="#zip-0307">11</a>.</p>
<p>A smaller proof size could enable the verification of Zcash SPV Proofs in block-chain protocols such as Ethereum, enabling efficient cross-chain communication and pegs. It also reduces bandwidth and storage requirements for resource-limited clients like mobile or IoT devices.</p>
</section>
<section id="specification"><h2><span class="section-heading">Specification</span><span class="section-anchor"> <a href="#specification"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
@ -183,7 +183,7 @@ License: MIT</pre>
<span class="math">\(x\)</span>
is the block height of the most recent network upgrade. We extend the standard MMR to allow metadata to propagate upwards through the tree by either summing the metadata of both children, or inheriting the metadata of a specific child as necessary. This allows us to create efficient proofs of selected properties of a range of blocks without transmitting the entire range of blocks or headers.</p>
<section id="tree-node-specification"><h3><span class="section-heading">Tree Node specification</span><span class="section-anchor"> <a href="#tree-node-specification"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Unless otherwise noted, all hashes use BLAKE2b-256 with the personalization field set to <code>'ZcashHistory' || CONSENSUS_BRANCH_ID</code>. <code>CONSENSUS_BRANCH_ID</code> is the little-endian encoding of <code>BRANCH_ID</code> for the epoch of the block containing the commitment. <a id="id7" class="footnote_reference" href="#zip-0200">2</a> Which is to say, each node in the tree commits to the consensus branch that produced it.</p>
<p>Unless otherwise noted, all hashes use BLAKE2b-256 with the personalization field set to <code>'ZcashHistory' || CONSENSUS_BRANCH_ID</code>. <code>CONSENSUS_BRANCH_ID</code> is the little-endian encoding of <code>BRANCH_ID</code> for the epoch of the block containing the commitment. <a id="id7" class="footnote_reference" href="#zip-0200">8</a> Which is to say, each node in the tree commits to the consensus branch that produced it.</p>
<p>Each MMR node is defined as follows:</p>
<ol type="1">
<li><code>hashSubtreeCommitment</code>
@ -405,7 +405,7 @@ License: MIT</pre>
<span class="math">\(B_n\)</span>
, we append a new MMR leaf node corresponding to block
<span class="math">\(B_{n-1}\)</span>
. The <code>append</code> operation is detailed below in pseudocode (adapted from <a id="id9" class="footnote_reference" href="#flyclient">7</a>):</p>
. The <code>append</code> operation is detailed below in pseudocode (adapted from <a id="id9" class="footnote_reference" href="#flyclient">2</a>):</p>
<pre data-language="python"><span class="k">def</span> <span class="nf">get_peaks</span><span class="p">(</span><span class="n">node</span><span class="p">:</span> <span class="n">ZcashMMRNode</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">ZcashMMRNode</span><span class="p">]:</span>
<span class="n">peaks</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">ZcashMMRNode</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
@ -494,7 +494,7 @@ License: MIT</pre>
</section>
<section id="block-header-semantics-and-consensus-rules"><h3><span class="section-heading">Block header semantics and consensus rules</span><span class="section-anchor"> <a href="#block-header-semantics-and-consensus-rules"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The <code>hashFinalSaplingRoot</code> block header field (which was named <code>hashReserved</code> prior to the Sapling network upgrade) is renamed to <code>hashLightClientRoot</code>, to reflect its usage by light clients.</p>
<p>Prior to activation of the Heartwood network upgrade, this existing consensus rule on block headers (adjusted for the renamed field) is enforced: <a id="id10" class="footnote_reference" href="#block-header">8</a></p>
<p>Prior to activation of the Heartwood network upgrade, this existing consensus rule on block headers (adjusted for the renamed field) is enforced: <a id="id10" class="footnote_reference" href="#block-header">4</a></p>
<blockquote>
<p>[Sapling onward] <code>hashLightClientRoot</code> MUST be
<span class="math">\(\mathsf{LEBS2OSP}_{256}(\mathsf{rt})\)</span>
@ -557,7 +557,7 @@ License: MIT</pre>
</section>
<section id="header-format-change"><h3><span class="section-heading">Header Format Change</span><span class="section-anchor"> <a href="#header-format-change"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The primary goal of the original authors was to minimize header changes; in particular, they preferred not to introduce changes that could affect mining hardware or embedded software. Altering the block header format would require changes throughout the ecosystem, so we decided against adding <code>hashChainHistoryRoot</code> to the header as a new field.</p>
<p>ZIP 301 states that "[Miner client software] SHOULD alert the user upon receiving jobs containing block header versions they do not know about or support, and MUST ignore such jobs." <a id="id11" class="footnote_reference" href="#zip-0301">9</a> As the only formally defined block header version is 4, any header version change requires changes to miner client software in order for miners to handle new jobs from mining pools. We therefore do not alter the block version for this semantic change. This does not make block headers ambiguous to interpret, because blocks commit to their block height inside their coinbase transaction, <a id="id12" class="footnote_reference" href="#bip-0034">10</a> and they are never handled in a standalone context (unlike transactions, which exist in the mempool outside of blocks).</p>
<p>ZIP 301 states that "[Miner client software] SHOULD alert the user upon receiving jobs containing block header versions they do not know about or support, and MUST ignore such jobs." <a id="id11" class="footnote_reference" href="#zip-0301">10</a> As the only formally defined block header version is 4, any header version change requires changes to miner client software in order for miners to handle new jobs from mining pools. We therefore do not alter the block version for this semantic change. This does not make block headers ambiguous to interpret, because blocks commit to their block height inside their coinbase transaction, <a id="id12" class="footnote_reference" href="#bip-0034">7</a> and they are never handled in a standalone context (unlike transactions, which exist in the mempool outside of blocks).</p>
<p>Replacing <code>hashFinalSaplingRoot</code> with <code>hashChainHistoryRoot</code> does introduce the theoretical possibility of an attack where a miner constructs a Sapling commitment tree update that results in the same 32-byte value as the MMR root. We don't consider this a realistic attack, both because the adversary would need to find a preimage over 32 layers of Pedersen hash, and because light clients already need to update their code to include the consensus branch ID for the Heartwood network upgrade, and can simultaneously make changes to not rely on the value of this header field being the Sapling tree root.</p>
<p>We also considered putting <code>hashChainHistoryRoot</code> in the <code>hashPrevBlock</code> field as it commits to the entire chain history, but quickly realized it would require massive refactoring of the existing code base and would negatively impact performance. Reorgs in particular are fragile, performance-critical, and rely on backwards iteration over the chain history. If a chain were to be designed from scratch there may be some efficient implementation that would join these commitments, but it is clearly not appropriate for Zcash as it exists.</p>
</section>
@ -569,6 +569,9 @@ License: MIT</pre>
<p>FlyClient, like all light clients, requires a connection to a light client server. That server may collect information about client requests, and may use that information to attempt to deanonymize clients. However, because FlyClient proofs are non-interactive and publicly verifiable, they could be shared among many light clients after the initial server interaction.</p>
<p>FlyClient proofs are probabilistic. When properly constructed, there is negligible probability that a dishonest chain commitment will be accepted by the verifier. The security analysis assumes adversary mining power is bounded by a known fraction of combined mining power of honest nodes, and cannot drop or tamper with messages between client and full nodes. It also assumes the client is connected to at least one full node and knows the genesis block. However, these security properties have not been examined closely in chain models with rapidly adjusting difficulty.</p>
</section>
<section id="deployment"><h2><span class="section-heading">Deployment</span><span class="section-anchor"> <a href="#deployment"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This proposal will be deployed with the Heartwood network upgrade. <a id="id13" class="footnote_reference" href="#zip-0250">9</a></p>
</section>
<section id="additional-reading"><h2><span class="section-heading">Additional Reading</span><span class="section-anchor"> <a href="#additional-reading"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<ul>
<li><a href="https://github.com/mahdiz/flyeth">Flyclient enabled geth fork by FlyClient authors</a></li>
@ -592,11 +595,11 @@ License: MIT</pre>
</tr>
</tbody>
</table>
<table id="zip-0200" class="footnote">
<table id="flyclient" class="footnote">
<tbody>
<tr>
<th>2</th>
<td><a href="https://github.com/zcash/zips/blob/master/zip-0200.rst">ZIP 200: Network Upgrade Mechanism</a></td>
<td><a href="https://eprint.iacr.org/2019/226.pdf">FlyClient protocol</a></td>
</tr>
</tbody>
</table>
@ -608,19 +611,19 @@ License: MIT</pre>
</tr>
</tbody>
</table>
<table id="zcashblock" class="footnote">
<table id="block-header" class="footnote">
<tbody>
<tr>
<th>4</th>
<td><a href="https://github.com/zcash/zcash/blob/master/src/primitives/block.h">Zcash block primitive</a></td>
<td><a href="https://zips.z.cash/protocol/protocol.pdf#blockheader">Section 7.5: Block Header. Zcash Protocol Specification, Version 2020.1.1 [Overwinter+Sapling+Blossom] or later</a></td>
</tr>
</tbody>
</table>
<table id="zip-0307" class="footnote">
<table id="zcashblock" class="footnote">
<tbody>
<tr>
<th>5</th>
<td><a href="https://github.com/zcash/zips/pull/226">ZIP 307: Light Client Protocol for Payment Detection</a></td>
<td><a href="https://github.com/zcash/zcash/blob/master/src/primitives/block.h">Zcash block primitive</a></td>
</tr>
</tbody>
</table>
@ -632,35 +635,43 @@ License: MIT</pre>
</tr>
</tbody>
</table>
<table id="flyclient" class="footnote">
<table id="bip-0034" class="footnote">
<tbody>
<tr>
<th>7</th>
<td><a href="https://eprint.iacr.org/2019/226.pdf">FlyClient protocol</a></td>
<td><a href="https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki">BIP 34: Block v2, Height in Coinbase</a></td>
</tr>
</tbody>
</table>
<table id="block-header" class="footnote">
<table id="zip-0200" class="footnote">
<tbody>
<tr>
<th>8</th>
<td><a href="https://zips.z.cash/protocol/protocol.pdf#blockheader">Section 7.5: Block Header. Zcash Protocol Specification, Version 2020.1.1 [Overwinter+Sapling+Blossom] or later</a></td>
<td><a href="https://github.com/zcash/zips/blob/master/zip-0200.rst">ZIP 200: Network Upgrade Mechanism</a></td>
</tr>
</tbody>
</table>
<table id="zip-0250" class="footnote">
<tbody>
<tr>
<th>9</th>
<td><a href="https://github.com/zcash/zips/blob/master/zip-0250.rst">ZIP 250: Deployment of the Heartwood Network Upgrade</a></td>
</tr>
</tbody>
</table>
<table id="zip-0301" class="footnote">
<tbody>
<tr>
<th>9</th>
<th>10</th>
<td><a href="https://github.com/zcash/zips/pull/78">ZIP 301: Zcash Stratum Protocol</a></td>
</tr>
</tbody>
</table>
<table id="bip-0034" class="footnote">
<table id="zip-0307" class="footnote">
<tbody>
<tr>
<th>10</th>
<td><a href="https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki">BIP 34: Block v2, Height in Coinbase</a></td>
<th>11</th>
<td><a href="https://github.com/zcash/zips/pull/226">ZIP 307: Light Client Protocol for Payment Detection</a></td>
</tr>
</tbody>
</table>

20
zip-0221.rst
View File

@ -698,6 +698,12 @@ and knows the genesis block. However, these security properties have not been ex
closely in chain models with rapidly adjusting difficulty.
Deployment
==========
This proposal will be deployed with the Heartwood network upgrade. [#zip-0250]_
Additional Reading
==================
@ -717,12 +723,14 @@ References
==========
.. [#RFC2119] `Key words for use in RFCs to Indicate Requirement Levels <https://tools.ietf.org/html/rfc2119>`_
.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <https://github.com/zcash/zips/blob/master/zip-0200.rst>`_
.. [#block-work] `Section 7.6.5: Definition of Work. Zcash Protocol Specification, Version 2020.1.1 [Overwinter+Sapling+Blossom] or later <https://zips.z.cash/protocol/protocol.pdf#workdef>`_
.. [#zcashBlock] `Zcash block primitive <https://github.com/zcash/zcash/blob/master/src/primitives/block.h>`_
.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection <https://github.com/zcash/zips/pull/226>`_
.. [#mimblewimble] `MimbleWimble Grin MMR implementation <https://github.com/mimblewimble/grin/blob/aedac483f5a116b91a8baf6acffd70e5f980b8cc/core/src/core/pmmr/pmmr.rs>`_
.. [#FlyClient] `FlyClient protocol <https://eprint.iacr.org/2019/226.pdf>`_
.. [#block-work] `Section 7.6.5: Definition of Work. Zcash Protocol Specification, Version 2020.1.1 [Overwinter+Sapling+Blossom] or later <https://zips.z.cash/protocol/protocol.pdf#workdef>`_
.. [#block-header] `Section 7.5: Block Header. Zcash Protocol Specification, Version 2020.1.1 [Overwinter+Sapling+Blossom] or later <https://zips.z.cash/protocol/protocol.pdf#blockheader>`_
.. [#zip-0301] `ZIP 301: Zcash Stratum Protocol <https://github.com/zcash/zips/pull/78>`_
.. [#zcashBlock] `Zcash block primitive <https://github.com/zcash/zcash/blob/master/src/primitives/block.h>`_
.. [#mimblewimble] `MimbleWimble Grin MMR implementation <https://github.com/mimblewimble/grin/blob/aedac483f5a116b91a8baf6acffd70e5f980b8cc/core/src/core/pmmr/pmmr.rs>`_
.. [#bip-0034] `BIP 34: Block v2, Height in Coinbase <https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki>`_
.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <https://github.com/zcash/zips/blob/master/zip-0200.rst>`_
.. [#zip-0250] `ZIP 250: Deployment of the Heartwood Network Upgrade <https://github.com/zcash/zips/blob/master/zip-0250.rst>`_
.. [#zip-0301] `ZIP 301: Zcash Stratum Protocol <https://github.com/zcash/zips/pull/78>`_
.. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection <https://github.com/zcash/zips/pull/226>`_

125
zip-0250.html Normal file
View File

@ -0,0 +1,125 @@
<!DOCTYPE html>
<html>
<head>
<title>ZIP 250: Deployment of the Heartwood Network Upgrade</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="css/style.css"></head>
<body>
<section>
<pre>ZIP: 250
Title: Deployment of the Heartwood Network Upgrade
Owners: Daira Hopwood &lt;daira@electriccoin.co&gt;
Status: Draft
Category: Consensus
Created: 2020-02-28
License: MIT</pre>
<section id="terminology"><h2><span class="section-heading">Terminology</span><span class="section-anchor"> <a 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 term "network upgrade" in this document is to be interpreted as described in ZIP 200. <a id="id2" class="footnote_reference" href="#zip-0200">3</a></p>
<p>The terms below are to be interpreted as follows:</p>
<dl>
<dt>Heartwood</dt>
<dd>Code-name for the fourth Zcash network upgrade, also known as Network Upgrade 3.</dd>
<dt>Testnet</dt>
<dd>The Zcash test network, as defined in <a id="id3" class="footnote_reference" href="#protocol">2</a>.</dd>
<dt>Mainnet</dt>
<dd>The Zcash production network, as defined in <a id="id4" class="footnote_reference" href="#protocol">2</a>.</dd>
</dl>
</section>
<section id="abstract"><h2><span class="section-heading">Abstract</span><span class="section-anchor"> <a 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 Heartwood network upgrade.</p>
</section>
<section id="specification"><h2><span class="section-heading">Specification</span><span class="section-anchor"> <a href="#specification"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="heartwood-deployment"><h3><span class="section-heading">Heartwood deployment</span><span class="section-anchor"> <a href="#heartwood-deployment"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The primary sources of information about Heartwood consensus protocol changes are:</p>
<ul>
<li>The Zcash Protocol Specification <a id="id5" class="footnote_reference" href="#protocol">2</a></li>
<li>ZIP 200: Network Upgrade Mechanism <a id="id6" class="footnote_reference" href="#zip-0200">3</a></li>
<li>ZIP 213: Shielded Coinbase <a id="id7" class="footnote_reference" href="#zip-0213">5</a></li>
<li>ZIP 221: FlyClient - Consensus-Layer Changes <a id="id8" class="footnote_reference" href="#zip-0221">6</a>.</li>
</ul>
<p>The network handshake and peer management mechanisms defined in ZIP 201 <a id="id9" class="footnote_reference" href="#zip-0201">4</a> also apply to this upgrade.</p>
<p>The following network upgrade constants <a id="id10" class="footnote_reference" href="#zip-0200">3</a> are defined for the Heartwood upgrade:</p>
<dl>
<dt>BRANCH_ID</dt>
<dd><code>0xTODO</code></dd>
<dt>ACTIVATION_HEIGHT (Heartwood)</dt>
<dd>
<p>Testnet: TODO</p>
<p>Mainnet: TODO</p>
</dd>
</dl>
<p>Nodes compatible with Heartwood activation on testnet MUST advertise protocol version 170010 or later. Nodes compatible with Heartwood activation on mainnet MUST advertise protocol version 170011 or later. The minimum peer protocol version that Heartwood-compatible nodes will connect to is 170002.</p>
<p>Pre-Heartwood testnet nodes are defined as nodes on testnet advertising a protocol version less than 170010. Pre-Heartwood mainnet nodes are defined as nodes on mainnet advertising a protocol version less than 170011.</p>
<p>For each network (testnet and mainnet), approximately three days (defined in terms of block height) before the corresponding Heartwood activation height, nodes compatible with Heartwood activation on that network will change the behaviour of their peer connection logic in order to prefer pre-Heartwood peers on that network 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="id11" class="footnote_reference" href="#zip-0201">4</a>.</p>
<p>Once Heartwood activates on testnet or mainnet, Heartwood nodes SHOULD take steps to:</p>
<ul>
<li>reject new connections from pre-Heartwood nodes on that network;</li>
<li>disconnect any existing connections to pre-Heartwood nodes on that network.</li>
</ul>
</section>
</section>
<section id="backward-compatibility"><h2><span class="section-heading">Backward compatibility</span><span class="section-anchor"> <a href="#backward-compatibility"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>Prior to the network upgrade activating on each network, Heartwood and pre-Heartwood nodes are compatible and can connect to each other. However, Heartwood nodes will have a preference for connecting to other Heartwood nodes, so pre-Heartwood nodes will gradually be disconnected in the run up to activation.</p>
<p>Once the network upgrades, even though pre-Heartwood nodes can still accept the numerically larger protocol version used by Heartwood as being valid, Heartwood nodes will always disconnect peers using lower protocol versions.</p>
<p>Unlike Overwinter and Sapling, and like Blossom, Heartwood does not define a new transaction version. Heartwood transactions are therefore in the same v4 format as Sapling transactions, and use the same version group ID, i.e. 0x892F2085 as defined in <a id="id12" class="footnote_reference" href="#protocol">2</a> section 7.1. This does not imply that transactions are valid across the Heartwood activation, since signatures MUST use the appropriate consensus branch ID.</p>
</section>
<section id="support-in-zcashd"><h2><span class="section-heading">Support in zcashd</span><span class="section-anchor"> <a href="#support-in-zcashd"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>Support for Heartwood on testnet will be implemented in <code>zcashd</code> version 2.1.3, which will advertise protocol version 170010. Support for Heartwood on mainnet will be implemented in <code>zcashd</code> version 2.2.0, which will advertise protocol version 170011.</p>
</section>
<section id="references"><h2><span class="section-heading">References</span><span class="section-anchor"> <a href="#references"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<table id="rfc2119" class="footnote">
<tbody>
<tr>
<th>1</th>
<td><a href="https://www.rfc-editor.org/rfc/rfc2119.html">Key words for use in RFCs to Indicate Requirement Levels</a></td>
</tr>
</tbody>
</table>
<table id="protocol" class="footnote">
<tbody>
<tr>
<th>2</th>
<td><a href="protocol/protocol.pdf">Zcash Protocol Specification, Version 2019.0.4 or later [Overwinter+Sapling+Blossom]</a></td>
</tr>
</tbody>
</table>
<table id="zip-0200" class="footnote">
<tbody>
<tr>
<th>3</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>
<td><a href="zip-0201">ZIP 201: Network Peer Management for Overwinter</a></td>
</tr>
</tbody>
</table>
<table id="zip-0213" class="footnote">
<tbody>
<tr>
<th>5</th>
<td><a href="zip-0213">ZIP 213: Shielded Coinbase</a></td>
</tr>
</tbody>
</table>
<table id="zip-0221" class="footnote">
<tbody>
<tr>
<th>6</th>
<td><a href="zip-0221">ZIP 221: FlyClient - Consensus-Layer Changes</a></td>
</tr>
</tbody>
</table>
</section>
</section>
</body>
</html>

131
zip-0250.rst Normal file
View File

@ -0,0 +1,131 @@
::
ZIP: 250
Title: Deployment of the Heartwood Network Upgrade
Owners: Daira Hopwood <daira@electriccoin.co>
Status: Draft
Category: Consensus
Created: 2020-02-28
License: MIT
Terminology
===========
The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be
interpreted as described in RFC 2119. [#RFC2119]_
The term "network upgrade" in this document is to be interpreted as described in
ZIP 200. [#zip-0200]_
The terms below are to be interpreted as follows:
Heartwood
Code-name for the fourth Zcash network upgrade, also known as Network Upgrade 3.
Testnet
The Zcash test network, as defined in [#protocol]_.
Mainnet
The Zcash production network, as defined in [#protocol]_.
Abstract
========
This proposal defines the deployment of the Heartwood network upgrade.
Specification
=============
Heartwood deployment
--------------------
The primary sources of information about Heartwood consensus protocol changes are:
- The Zcash Protocol Specification [#protocol]_
- ZIP 200: Network Upgrade Mechanism [#zip-0200]_
- ZIP 213: Shielded Coinbase [#zip-0213]_
- ZIP 221: FlyClient - Consensus-Layer Changes [#zip-0221]_.
The network handshake and peer management mechanisms defined in ZIP 201 [#zip-0201]_
also apply to this upgrade.
The following network upgrade constants [#zip-0200]_ are defined for the Heartwood
upgrade:
BRANCH_ID
``0xTODO``
ACTIVATION_HEIGHT (Heartwood)
Testnet: TODO
Mainnet: TODO
Nodes compatible with Heartwood activation on testnet MUST advertise protocol version
170010 or later. Nodes compatible with Heartwood activation on mainnet MUST advertise
protocol version 170011 or later. The minimum peer protocol version that
Heartwood-compatible nodes will connect to is 170002.
Pre-Heartwood testnet nodes are defined as nodes on testnet advertising a protocol
version less than 170010. Pre-Heartwood mainnet nodes are defined as nodes on mainnet
advertising a protocol version less than 170011.
For each network (testnet and mainnet), approximately three days (defined in terms of
block height) before the corresponding Heartwood activation height, nodes compatible
with Heartwood activation on that network will change the behaviour of their peer
connection logic in order to prefer pre-Heartwood peers on that network for eviction
from the set of peer connections::
/** 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;
The implementation is similar to that for Overwinter which was described in
[#zip-0201]_.
Once Heartwood activates on testnet or mainnet, Heartwood nodes SHOULD take steps to:
- reject new connections from pre-Heartwood nodes on that network;
- disconnect any existing connections to pre-Heartwood nodes on that network.
Backward compatibility
======================
Prior to the network upgrade activating on each network, Heartwood and pre-Heartwood
nodes are compatible and can connect to each other. However, Heartwood nodes will
have a preference for connecting to other Heartwood nodes, so pre-Heartwood nodes will
gradually be disconnected in the run up to activation.
Once the network upgrades, even though pre-Heartwood nodes can still accept the
numerically larger protocol version used by Heartwood as being valid, Heartwood nodes
will always disconnect peers using lower protocol versions.
Unlike Overwinter and Sapling, and like Blossom, Heartwood does not define a new
transaction version. Heartwood transactions are therefore in the same v4 format as
Sapling transactions, and use the same version group ID, i.e. 0x892F2085 as
defined in [#protocol]_ section 7.1. This does not imply that transactions are
valid across the Heartwood activation, since signatures MUST use the appropriate
consensus branch ID.
Support in zcashd
=================
Support for Heartwood on testnet will be implemented in ``zcashd`` version 2.1.3,
which will advertise protocol version 170010. Support for Heartwood on mainnet will
be implemented in ``zcashd`` version 2.2.0, which will advertise protocol version
170011.
References
==========
.. [#RFC2119] `Key words for use in RFCs to Indicate Requirement Levels <https://www.rfc-editor.org/rfc/rfc2119.html>`_
.. [#protocol] `Zcash Protocol Specification, Version 2019.0.4 or later [Overwinter+Sapling+Blossom] <protocol/protocol.pdf>`_
.. [#zip-0200] `ZIP 200: Network Upgrade Activation Mechanism <zip-0200.rst>`_
.. [#zip-0201] `ZIP 201: Network Peer Management for Overwinter <zip-0201.rst>`_
.. [#zip-0213] `ZIP 213: Shielded Coinbase <zip-0213.rst>`_
.. [#zip-0221] `ZIP 221: FlyClient - Consensus-Layer Changes <zip-0221.rst>`_