readme draft and benchmark

3 files changed, 45 insertions, 8 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a2b32f8..ea22973 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,12 +1,5 @@
 # Contributing
 
-BLAKE3 is 
-
-* [@oconnor63 ](https://github.com/daeMOn63) (Jack O'Connor)
-* [@sneves](https://github.com/sneves) (Samuel Neves)
-* [@veorq](https://github.com/veorq) (Jean-Philippe Aumasson)
-* [@zookozcash](https://github.com/zookocash) (Zooko)
-
 We welcome and encourage third-party contributions to BLAKE3, be it reports of issues encountered while using the software, suggestions of new features, or proposals of patches.
 
 ## Bug reports
diff --git a/README.md b/README.md
index a654390..3c88f68 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,45 @@
-The Rust implementation of BLAKE3.
+# BLAKE3
+
+BLAKE3 is a cryptographic hash function that is
+
+1. Much faster than MD5, SHA1, SHA2, SHA3, and even BLAKE2
+1. Highly parallelizable: The more data and the more cores, the faster it
+goes. (For you specialists reading this: this is because it is actually a
+MerkleTree under the hood.)
+1. Capable of streaming and random-access verification. (Again: the magic of Merkle Trees.)
+1. Carefully engineered to be simple and safe to use, with no "modes" or tweaks required.
+
+![benchmarks](media/speed.png)
+
+The complete specifications are available as a
+[PDF](https://github.com/BLAKE3/BLAKE3-specs/raw/master/blake3.pdf) and its
+[LaTeX source](https://github.com/veorq/BLAKE3-specs/raw/master/blake3.pdf).
+
+BLAKE3 was designed by:
+
+* [@oconnor63 ](https://github.com/daeMOn63) (Jack O'Connor)
+* [@sneves](https://github.com/sneves) (Samuel Neves)
+* [@veorq](https://github.com/veorq) (Jean-Philippe Aumasson)
+* [@zookozcash](https://github.com/zookocash) (Zooko)
+
+*WARNING*: BLAKE3 is not a password-hash function, because it's designed
+to be fast, whereas password hashing should not be fast.
+If you hash passwords to store the hashes or if you derive keys from password, we recommend
+[Argon2](https://github.com/P-H-C/phc-winner-argon2).
+
+## Usage
+
+TODO
+
+## History
+
+TODO: BLAKE, BLAKE3, Bao
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Licensing
+
+TODO: Apache 2 and CC0
+
diff --git a/media/speed.png b/media/speed.png
new file mode 100644
index 0000000..2205fee
--- /dev/null
+++ b/media/speed.png