how about this!

README.md

@@ -5,13 +5,15 @@ This document is intended to be a technical overview of [Sapling](https://z.cash
 
 ------------------------------------------------
 
-# Background
+# Introduction
 
-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:
+Zcash is a cryptocurrency which uses advanced cryptography to provide strong financial privacy to its users. Zcash users send money to and from **payment addresses**. Zcash includes two kinds of payment addresses:
 
-* **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."
+* **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.
+* **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.
 
-**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.
+Transactions involving only shielded addresses have very strong privacy properties, but transactions that involve both transparent and shielded addresses have complicated privacy properties that are hard to articulate to users. Therefore, it would be nice to eventually remove transparent addresses from the protocol entirely.
 
-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.
+The original shielded addresses in Zcash typically require over 40 seconds and more than a gigabyte of memory to send and receive payments with. As a result, transparent addresses are ubiquitous in the ecosystem.
+
+**Sapling** is a Zcash network upgrade that introduces a new shielded address format that is vastly more efficient to send and receive payments with. Slated to activate in October 2018, it will be the product of over two years of cryptographic design, engineering and analysis.

SUMMARY.md

@@ -1,12 +1,19 @@
 # Summary
 
-* [Background](README.md)
-    * [Network Upgrades](background/network_upgrades.md)
-    * [Zerocash](background/zerocash.md)
-* [Transaction Design](transaction_design.md)
-* [Payment Addresses](http)
-* [Notes](http)
-* [Nullifiers](http)
-* [Jubjub](http)
-* [Groth16](http)
-* [BLS12-381](http)
+* [Introduction](README.md)
+* [zk-SNARKs](zksnarks/README.md)
+    * [BLS12-381](zksnarks/bls12_381.md)
+    * [Quadratic Arithmetic Programs](zksnarks/qaps.md)
+    * [Groth16](zksnarks/groth16.md)
+    * [Parameter Generation](zksnarks/paramgen.md)
+    * [Simulation Extractability](zksnarks/simulation_extractability.md)
+* [Jubjub](jubjub/README.md)
+    * [Pedersen commitments](jubjub/pedersen_commitments.md)
+    * [Pedersen hashes](jubjub/pedersen_hashes.md)
+    * [RedJubjub](jubjub/redjubjub.md)
+* [Zerocash](zerocash.md)
+* [Payment Addresses](payment_addresses.md)
+* [Notes](notes.md)
+* [Transaction design](transaction_design/README.md)
+    * [Spend](transaction_design/spend.md)
+    * [Output](transaction_design/output.md)

zksnarks/README.md

@@ -0,0 +1,14 @@
+# zk-SNARKs
+
+[Zero-knowledge proofs](https://en.wikipedia.org/wiki/Zero-knowledge_proof) allow you to demonstrate that you performed a computation correctly without revealing all of the inputs to that computation. We can think of the computation as some $$f(x, w)$$, where the **statement** $$x$$ is known to both the verifier and the prover, but the **witness** $$w$$ is known only to the prover.
+
+The fundamental tool underlying Zcash is an advanced zero-knowledge proof called a **zk-SNARK**. These proofs are only hundreds of bytes long and are inexpensive to verify, even if the underlying computation $$f(x, w)$$ is large in complexity. These proofs are also **non-interactive**, so the prover can publish the proof and anyone can verify it without interacting with the prover, making them very useful for cryptocurrencies.
+
+zk-SNARKs do come with some downsides, which are being addressed by the Sapling upgrade:
+
+* zk-SNARKs require a setup phase where, for a given computation $$f(x, w)$$, some **public parameters** are constructed. These parameters are needed to create and verify proofs, but if the creator of the parameters "remembers" how they were constructed, they can create false proofs.
+    * Sapling uses a gigantic and public [multi-party computation](https://en.wikipedia.org/wiki/Secure_multi-party_computation) (MPC) ceremony to construct the parameters. In order to corrupt the parameters, a large number of reputable individuals must *all* be colluding in secret or compromised.
+* [Pairing-friendly elliptic curves](https://en.wikipedia.org/wiki/Pairing-based_cryptography) are needed, and relatively strong cryptographic assumptions are made.
+    * Sapling switches to a more secure and more rigid pairing-friendly elliptic curve.
+* The proofs have a reputation for being expensive to create, both in terms of time and memory.
+    * Sapling uses a more efficient proving system and novel cryptographic primitives to improve performance. Proving time is reduced by 20x, and memory usage is reduced by orders of magnitude.

zksnarks/bls12_381.md

@@ -0,0 +1,65 @@
+# BLS12-381
+
+## Elliptic Curves
+
+[Elliptic curves](https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) are an important tool in modern cryptography. If we instantiate some (appropriately designed) elliptic curve over a [finite field](https://en.wikipedia.org/wiki/Finite_field) $$\mathbb{F}_p$$ of prime characteristic $$p$$, the points on this curve are elements of a [group](https://en.wikipedia.org/wiki/Group_(mathematics) $$\mathbb{G}$$ for which the [discrete logarithm problem](https://en.wikipedia.org/wiki/Discrete_logarithm) is believed to be difficult. In other words, given arbitrary $$g, h \in \mathbb{G}$$ it should be difficult to compute $$log_g(h)$$.
+
+We sometimes make stronger assumptions about elliptic curves in order to build useful tools. For instance, the [computational Diffie-Hellman assumption](https://en.wikipedia.org/wiki/Computational_Diffie%E2%80%93Hellman_assumption) implies that given arbitrary $$g, g^a, g^b$$, it should be difficult to find $$g^{ab}$$. Viewed another way, "multiplying" group elements together is conjectured to be infeasible. This assumption is fundamental to [Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange).
+
+Related is the [decisional Diffie-Hellman assumption](https://en.wikipedia.org/wiki/Decisional_Diffie%E2%80%93Hellman_assumption) which (roughly) implies that given arbitrary $$g, g^a, g^b, h$$ it should be difficult to determine if $$h = g^{ab}$$. zk-SNARKs require an elliptic curve for which this assumption does *not* hold, but the computational Diffie-Hellman assumption and many other assumptions do.
+
+## Pairing-friendly Elliptic Curves
+
+Elliptic curve groups have a property called an **embedding degree**. Consider an elliptic curve instantiated over $$\mathbb{F}_p$$ with a subgroup of large prime order $$q$$. The embedding degree is defined as the smallest $$k$$ such that $$q | (p^k - 1)$$. Most elliptic curve constructions have very large embedding degrees.
+
+**Pairing-friendly elliptic curve** constructions have an embedding degree that is still large enough that the curve is secure, but *just* small enough that an efficiently-computable [bilinear pairing function](https://en.wikipedia.org/wiki/Pairing-based_cryptography) $$e : \mathbb{G}_1 \times \mathbb{G}_2 \rightarrow \mathbb{G}_T$$ exists:
+
+$$
+e(a \cdot g_1, b \cdot g_2) = g_{T}^{ab}
+$$
+
+In other words, the pairing function allows us to effectively "multiply" group elements, though the result ends up in a different group $$\mathbb{G}_{T}$$, which we write multiplicatively. This allows us to break the decisional Diffie-Hellman assumption and reason about the multiplicative relationships between group elements.
+
+Notice that the pairing function takes two different group elements $$\mathbb{G}_1, \mathbb{G}_2$$ as input. This is because practical constructions instantiate $$\mathbb{G}_1$$ on a curve $$E$$ over the "base field" $$\mathbb{F}_p$$ and $$\mathbb{G}_2$$ on a twisted curve $$E'$$ over some [extension field](https://en.wikipedia.org/wiki/Field_extension) $$\mathbb{F}_{p^e}$$. We write elements of $$\mathbb{G}_{T}$$ multiplicatively because they are really elements of a $$q$$-order multiplicative subgroup of $$\mathbb{F}_{p^k}$$.
+
+## Curve Families
+
+There are many ways to build pairing-friendly elliptic curve constructions, such as the [Cocks-Pinch method](https://arxiv.org/abs/1211.0971). The most rigid and well-performing constructions are part of families of elliptic curves that have been discovered over the last two decades. Three of the most important families are:
+
+1. [Barreto-Naehrig](https://eprint.iacr.org/2005/133) (BN) curves have the distinct advantage that $$E(\mathbb{F}_p)$$ is of prime order, which reduces the cost of hashing to $$\mathbb{G}_1$$ and deserializing group elements. BN curves were once considered perfect for the 128-bit security level, and Zcash originally launched using a BN curve called "alt_bn128".
+2. [Barreto-Lynn-Scott](https://eprint.iacr.org/2002/088) (BLS) curves originally seemed useful for the 192-bit security level. There are several [subfamilies](https://eprint.iacr.org/2011/465) of BLS curves which submit very [rigid](https://safecurves.cr.yp.to/rigid.html) curves with immediately determined curve constants and efficient extension field and twist configurations.
+3. [Kachisa-Schaefer-Scott](https://eprint.iacr.org/2007/452) (KSS) curves appear to have some interesting [performance and security tradeoffs](https://eprint.iacr.org/2017/1174), but are underexplored in the literature.
+
+In 2016, Kim and Barbulescu [discovered](https://ellipticnews.wordpress.com/2016/05/02/kim-barbulescu-variant-of-the-number-field-sieve-to-compute-discrete-logarithms-in-finite-fields/) some optimizations to the Number Field Sieve (NFS) algorithm which reduced the conjectured security level of alt_bn128 to as little as 100-bits, under some conservative assumptions. Larger BN curves which target the 128-bit security level have much larger prime subgroup orders and relatively expensive pairings.
+
+BLS curves with embedding degree $$k = 12$$ have the interesting property that targeting closer to 128-bits of security tends toward ideal prime subgroup orders $$q \approx 2^{256}$$, making them much more attractive than BN curves at this security level. The rigidity and simplicity of their parameterization and implementation is also attractive.
+
+## BLS12 Curves
+
+BLS12 curves are parameterized by a value $$x$$ such that the base field modulus $$p$$ and prime subgroup order $$q$$ can be computed by:
+
+$$
+p(x) = (x - 1)^2 ((x^4 - x^2 + 1) / 3) + x
+$$
+
+$$
+q(x) = (x^4 - x^2 + 1)
+$$
+
+Given primes $$p$$ and $$q$$ parameterized as above, we can construct an elliptic curve $$E$$ over the prime field $$\mathbb{F}_p$$ which contains a subgroup of order $$q$$, and its sextic twist $$E'$$ over the extension field $$\mathbb{F}_{p^2}$$. The $$q$$-order subgroups of both elliptic curve groups give rise to an efficient pairing function.
+
+We can find an appropriate $$x$$ by applying some simple criteria:
+
+* We desire $$q < 2^{255}$$ both for cheap reductions and so that the scalar field of our elliptic curve can be used for keying material in our construction. This gives rise to curves that have approximately 120 bits of security under conservative assumptions.
+* We desire an $$\mathbb{F}_q$$ with a large $$2^n$$ root of unity for performing efficient fast-Fourier transforms, which is very useful for the intense polynomial arithmetic needed in zk-SNARKs.
+* We desire an efficient extension field tower and twisting isomorphism. Subfamilies of BLS12 curves (where $$x \textrm{ mod } 72 = \{16, 64\}$$ for our purposes) have such properties, along with immediately determined curve parameters.
+* We desire an $$x$$ of low Hamming weight, to ensure the pairing function is efficient.
+
+If we search for the largest curve that meets the above criteria, with the smallest Hamming weight, we discover `x = -0xd201000000010000`. We name this curve "BLS12-381" as it has a 381-bit base field prime $$p$$.
+
+## Implementations of BLS12-381
+
+BLS12-381 has been implemented in the following libraries:
+
+1. [ebfull/pairing](https://github.com/ebfull/pairing) is a pure-Rust implementation of the construction. It is undergoing [audits](https://blog.z.cash/2018-zcash-security-audit-details/) and will be used in the Sapling network upgrade.
+2. [RELIC](https://github.com/relic-toolkit/relic) contains a C implementation of the construction.