From b5b545f088d36edebd57bda8076aa08983521d58 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Fri, 28 Feb 2020 09:52:27 +1300 Subject: [PATCH] Use header characters consistent with other ZIPs --- zip-0221.rst | 43 +++++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/zip-0221.rst b/zip-0221.rst index 4b86dbbc..668fc048 100644 --- a/zip-0221.rst +++ b/zip-0221.rst @@ -12,7 +12,8 @@ License: MIT Terminology ------------ +=========== + The key words "**MUST**", "**SHOULD**", and "**MAY**" in this document are to be interpreted as described in RFC 2119. [#RFC2119]_ @@ -37,7 +38,8 @@ described in ZIP 200. [#zip-0200]_ Abstract ---------- +======== + This ZIP specifies modifications to be made to the Zcash block header format to include Merkle Mountain Range (MMR) commitments. Sapling (NU2) introduced the ``hashFinalSaplingRoot`` field to Zcash headers. This ZIP replaces the @@ -50,8 +52,9 @@ future specification of the FlyClient protocol [#FlyClient]_. This ZIP specifies consensus-layer changes. It does not provide any specification about the FlyClient protocol's operation. + Background ------------ +========== 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 @@ -133,8 +136,10 @@ addition, MMR update operations and Merkle proofs for recent additions to the le more efficient than other incremental Merkle tree implementations (e.g. Bitcoin's padded leafset, sparse Merkle trees, and Zcash's incremental note commitment trees). + Motivation ----------- +========== + MMR proofs are used in the FlyClient protocol to reduce the proof size needed for light clients to verify @@ -162,7 +167,8 @@ devices. Security and Privacy Considerations ------------------------------------- +=================================== + This ZIP imposes an additional validation cost on new blocks. While this validation cost is small, it may exacerbate any existing DoS opportunities, particularly during abnormal events like long reorgs. Fortunately, these costs are logarithmic in the number of delete @@ -198,7 +204,8 @@ closely in chain models with rapidly-adjusting difficulty. Specification --------------- +============= + .. image:: https://i.imgur.com/hhRyI99.png :alt: zcash_MMR @@ -213,7 +220,7 @@ of selected properties of a range of blocks without transmitting the entire rang blocks or headers. Tree Node specification -~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- Unless otherwise noted, all hashes use BLAKE2b-256 with the personalization field set to ``'ZcashHistory' || CONSENSUS_BRANCH_ID``. ``CONSENSUS_BRANCH_ID`` is the little-endian @@ -380,7 +387,7 @@ the BLAKE2b-256 digest of the serialization of the root node. Tree nodes and hashing (pseudocode) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------- .. code-block:: python @@ -465,7 +472,7 @@ Tree nodes and hashing (pseudocode) return H(root.serialize()) Incremental push and pop (pseudocode) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- With each new block ``B_n``, we append a new MMR leaf node corresponding to block ``B_(n-1)``. The ``append`` operation is detailed below in pseudocode (adapted from @@ -562,7 +569,7 @@ in the right subtree of the MMR root. return root Header modifications specification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------- This ZIP introduces a new header version. It is identical to the current v4 header [#zcashBlock]_, except for the following changes: @@ -593,10 +600,10 @@ The new block header format is: Rationale ------------ +========= Tree nodes -~~~~~~~~~~~ +---------- Nodes in the commitment tree are canonical and immutable. They are cheap to generate, as (with the exception of ``nShieldedTxCount``) all metadata is already generated during @@ -624,7 +631,7 @@ consensus branch ID to the hash personalization string ensures that valid nodes branch cannot be used to make false statements about parallel consensus branches. FlyClient Requirements and Recommendations -=============================================== +`````````````````````````````````````````` These commitments enable FlyClient in the variable-difficulty model. Specifically, they allow light clients to reason about application of the difficulty adjustment algorithm over a range of blocks. They were chosen via discussion with an author of the FlyClient @@ -639,8 +646,7 @@ paper. - ``nSubTreeTotalWork`` Non-FlyClient Commitments -========================== - +````````````````````````` Additional metadata commitments were chosen primarily to improve light client security guarantees. We specified commitments where we could see an obvious security benefit, but there may be other useful metadata that we missed. We're interested in feedback and @@ -682,7 +688,7 @@ the proper serialization and commitment format for the nullifier vector. would significantly decrease the bandwidth requirements of light clients. Header Format Change -~~~~~~~~~~~~~~~~~~~~~~ +-------------------- Our primary goal was to minimize header changes. The version number is incremented to signify the change in field semantics. This is not strictly necessary. Old light client @@ -706,7 +712,7 @@ Zcash as it exists. Additional Reading -------------------- +================== - `Bitcoin difficulty calculation `_ - `Flyclient enabled geth fork by FlyClient authors `_ @@ -720,8 +726,9 @@ Additional Reading - `Zcash Protocol Specification, Version 2018.0-beta-37 [Overwinter+Sapling] `_ - `opentimestamps-server Merkle Mountain Range documentation `_ + References ------------ +========== .. [#RFC2119] `Key words for use in RFCs to Indicate Requirement Levels `_ .. [#zip-0200] `ZIP 200: Network Upgrade Mechanism `_