restructure

README.md

@@ -5,23 +5,13 @@ This document is intended to be a technical overview of [Sapling](https://z.cash
 
 ------------------------------------------------
 
-# Introduction
+# Background
 
-Zcash is a cryptocurrency which uses cutting-edge cryptography to provide users with strong privacy guarantees. Over time, the Zcash network will undergo **network upgrades** in order to add features and improve the network. We like to use codenames to describe our major releases and network upgrades:
+Zcash is a cryptocurrency which uses cutting-edge cryptography to provide users with strong financial privacy. Zcash users send money to and from **payment addresses**. Zcash includes two kinds of payment addresses:
 
-### Sprout
+* **Transparent addresses** are similar to the traditional Bitcoin-style addresses. Payments to and from transparent addresses publicly reveal the contents of your transaction, such as the value, origin and destination of funds. There is a `t` at the beginning of all transparent addresses, so we sometimes call them "t-addresses."
+* **Shielded addresses** are payment addresses which use a variant of the [Zerocash protocol](http://zerocash-project.org/) to allow users to keep the value, origin and destination of funds completely private. There is a `z` at the beginning of all shielded addresses, so we sometimes call them "z-addresses."
 
-**Sprout** was the initial release of Zcash in 2016. Zcash's protocol is built on top of a fork of Bitcoin's code. Just as in Bitcoin, users typically send and receive money with **payment addresses**. The original release of Zcash included two kinds of payment addresses:
+**Sapling** is a [network upgrade](background/network_upgrades.md) which introduces a new z-address which is faster to send and receive shielded payments with. It is the first step toward (eventually) removing transparent addresses from Zcash completely.
 
-* **Transparent addresses** are identical to the traditional Bitcoin-style addresses. Payments to and from transparent addresses publicly reveal the contents of your transaction, such as the value, origin and destination of funds.
-* **Shielded addresses** are payment addresses which use a variant of the [Zerocash protocol](http://zerocash-project.org/) to allow users to keep the value, origin and destination of funds completely private.
-
-### Overwinter
-
-**Overwinter** is Zcash's first network upgrade. It makes some changes to the protocol which make future network upgrades simpler. It is slated to activate in June 2018.
-
-### Sapling
-
-**Sapling** is a major network upgrade that is expected to activate in November 2018. The primary goal of this upgrade is to improve the performance of shielded addresses so that they can become ubiquitous in the ecosystem. In order to do this, we need to make payments involving these addresses much more efficient. This requires using some improved cryptographic tools and a new kind of shielded address.
-
-Sapling is one step toward removing transparent addresses from the protocol entirely, although that will not take place in the Sapling upgrade.
+The Sapling network upgrade has required more than a year of careful design and optimization. This document is intended to give a technical and cryptographic overview of the Sapling upgrade so that it can be more broadly analyzed by the community.

SUMMARY.md

@@ -1,5 +1,12 @@
 # Summary
 
-* [Introduction](README.md)
-* [Zerocash](zerocash/README.md)
-     * [sdfgsdfgsdfg](zerocash/something.md)
+* [Background](README.md)
+    * [Network Upgrades](background/network_upgrades.md)
+    * [Zerocash](background/zerocash.md)
+* [Transaction Design](http)
+* [Payment Addresses](http)
+* [Notes](http)
+* [Nullifiers](http)
+* [Jubjub](http)
+* [Groth16](http)
+* [BLS12-381](http)

background/network_upgrades.md

@@ -0,0 +1,30 @@
+Over time, the Zcash network will undergo **network upgrades** in order to add features and improve the network. We like to use codenames to describe our major releases and network upgrades:
+
+### Sprout
+
+**Sprout** was the initial release of Zcash in 2016. Zcash's protocol is built on top of a fork of Bitcoin's code, with an integration of the Zerocash protocol and some other adjustments:
+
+* The maximum block size was increased to 2MB.
+* The interval between blocks targets 2.5 minutes. (Corresponding changes to the block reward ensure that the supply schedule approximates Bitcoin's.)
+* The proof-of-work algorithm was changed to Equihash.
+* The difficulty adjustment algorithm was modified to react more quickly to changes in hashrate.
+* A 32-byte `reserved` field was added to the block header.
+
+### Overwinter
+
+**Overwinter** is Zcash's first network upgrade. Overwinter's main goal is to introduce changes which make future network upgrades simpler. The most important is the introduction of bilateral replay protection: transactions on a different chain that did not follow the network upgrade should not be valid on the new chain, and vice-versa.
+
+Overwinter also had some other changes to consensus rules:
+
+* The quadratic cost of validating (transparent payment) signatures was fixed.
+* Transactions now have an expiry height which allows transactions to expire from being mined.
+
+### Sapling
+
+**Sapling** is a major network upgrade that is expected to activate in November 2018. The primary goal of this upgrade is to improve the performance of shielded addresses so that they can become ubiquitous in the ecosystem.
+
+The Sapling upgrade includes:
+
+* A new z-address that is significantly faster to send and receive payments with, with less memory consumption.
+* Old z-addresses are still valid, but transactions involving them are doubled in performance.
+* Block headers are required to contain (in the previously `reserved` field) the Merkle tree root of the new z-address accumulator.

background/zerocash.md

@@ -1,6 +1,8 @@
 # Zerocash
 
-Zcash's shielded transactions implement a variant of the [Zerocash protocol](http://zerocash-project.org/). Although we made some changes to terminology and fixed some security bugs, the construction still centers around three basic principles:
+Zcash's shielded transactions implement a variant of the [Zerocash protocol](http://zerocash-project.org/). Zcash's implementation differs greatly from the Zerocash paper: we made changes to terminology, fixed some security bugs, and (in the case of Sapling) have begun to make significant modifications for performance.
+
+Shielded transactions still center around three basic principles:
 
 1. **Notes** consist of some value and an address that is allowed to spend it.
 2. Cryptographic commitments to all notes that are created are placed in an **accumulator** -- in our case, a Merkle tree. This tree is maintained by all full nodes on the network.
@@ -10,16 +12,18 @@ In order to support large accumulators like deep Merkle trees -- thereby maximiz
 
 Creating new notes is straightforward: you reveal a note commitment and a proof that the commitment is correctly structured. The value of the new note needs to be compared with the rest of the transaction somehow to ensure that money isn't being created or destroyed.
 
-Spending is a little more complicated. In addition to revealing a nullifier and a proof that it was correctly calculated, you must also prove the note you're spending exists at all, and that you're authorized to spend it. Your proof will witness a path to your note in a merkle tree, and the merkle tree root must be revealed alongside the proof. This root (referred to as an **anchor**) is typically constrained to be some Merkle tree root at a previous block boundary.
+Spending is a little more complicated. In addition to revealing a nullifier and a proof that it was correctly calculated, you must also prove the note you're spending exists at all, and that you're authorized to spend it. Your proof will witness a path to your note in a merkle tree, and the merkle tree root must be revealed alongside the proof. This root (referred to as an **anchor**) is typically constrained by the outside consensus rules to be some Merkle tree root at a previous block boundary.
 
-Making a payment using this protocol requires some way to send the commitment randomness, value and other information to the recipient, so that they are aware they can spend the note. Zcash uses in-band secret distribution to do this; the address contains an asymmetric key which can be used for a half-ephemeral Diffie-Hellman key exchange, and a ciphertext is placed alongside the new note commitment.
+Making a payment using this protocol requires some way to send the commitment randomness, value and other information to the recipient, so that they are aware they can spend the note. Zcash uses in-band secret distribution to do this: the address contains an asymmetric key which can be used for a half-ephemeral Diffie-Hellman key exchange, and a ciphertext is placed alongside the new note commitment.
+
+## Important Considerations
 
 Most of the mistakes surrounding concrete instantiations of Zerocash-like protocols involve nullifiers:
 
 1. Nullifiers need to be fully determined by the note. If any of the inputs to the nullifier computation can be substituted at proving time, an adversary could spend the same note multiple times. (One example of this is the [InternalH collision attack](https://blog.z.cash/fixing-zcash-vulns/) discovered by Taylor Hornby.)
-2. Nullifiers must be computed using a PRF, so that they are indistinguishable from each other.
+2. Nullifiers must be computed [using a PRF](https://en.wikipedia.org/wiki/Pseudorandom_function_family), so that they are indistinguishable from each other.
 3. The PRF for computing the nullifier must be keyed on secrets only the spender knows. Otherwise, the original creator of the note can compute the nullifier and see when it is spent.
-4. The PRF must also be collision-resistant. Otherwise, an adversary could create multiple notes with the same nullifier, spending one to ensure the others cannot be spent. This is referred to as a sniping attack.
-5. The inputs to the nullifier computation should be unique to each note, so that the final nullifier is different for every note in the tree. This prevents a *Faerie gold attack* (discovered by Zooko Wilcox) which would allow an adversary to send two payments to a recipient, of which only one can be spent.
+4. The PRF must also be [collision-resistant](https://en.wikipedia.org/wiki/Collision_resistance). Otherwise, an adversary could create multiple notes with the same nullifier, spending one to ensure the others cannot be spent. This is referred to as a sniping attack.
+5. The inputs to the nullifier computation should be unique to each note, so that the final nullifier is different for every note in the tree. This prevents the "Faerie gold attack" (discovered by Zooko Wilcox) which would allow an adversary to send two payments to a recipient, of which only one can be spent.
 
-It's also necessary to defend against malleability attacks where parts of the shielded components of transactions are relocated into other transactions, which would allow for theft. We solve this using digital signatures with ephemeral keys that are bound to the proofs.
+It's also necessary to defend against malleability attacks where parts of the shielded components of transactions are relocated into other transactions, which would allow for theft. We solve this using digital signatures with ephemeral keys that are bound to the proofs. It is also problematic if the zk-SNARK proofs themselves are malleable; either we must use simulation-extractable proofs, or we must design the construction to mitigate the problem.