From 9b08ac731d314b944a3d547f6dc267c90eba076e Mon Sep 17 00:00:00 2001
From: Bobbin Threadbare <bobbinth@protonmail.com>
Date: Thu, 1 Dec 2022 18:08:10 -0800
Subject: [PATCH] docs: update main README file

---
 README.md           | 29 +++++++++++++++++++++++++++--
 src/hash/rpo/mod.rs |  2 +-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d5fe9a0..b2edddd 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,27 @@
-# crypto
-Cryptographic primitives used in Polygon Miden rollup
+# Miden Crypto
+This crate contains cryptographic primitives used in Polygon Miden.
+
+## Hash
+[Hash module](./src/hash) provides a set of cryptographic hash functions which are used by Miden VM and Miden Rollup. Currently, these functions are:
+
+* [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) hash function with 256-bit, 192-bit, or 160-bit output. The 192-bit and 160-bit outputs are obtained by truncating the 256-bit output of the standard BLAKE3.
+* [RPO](https://eprint.iacr.org/2022/1577) hash function with 256-bit output. This hash function is an algebraic hash function suitable for recursive STARKs.
+
+## Merkle
+[Merkle module](./src/merkle/) provides a set of data structures related to Merkle tree. All these data structures are implemented using RPO hash function described above. The data structure are:
+
+* `MerkleTree`: a regular fully-balanced binary Merkle tree. The depth of this tree can be at most 64.
+* `MerklePathSet`: a collection of Merkle authentication paths all resolving to the same root. The length of the paths can be at most 64.
+
+## Crate features
+This carate can be compiled with the following features:
+
+* `std` - enabled by default and relies on the Rust standard library.
+* `no_std` does not rely on the Rust standard library and enables compilation to WebAssembly.
+
+Both of these features imply use of [alloc](https://doc.rust-lang.org/alloc/) to support heap-allocated collections.
+
+To compile with `no_std`, disable default features via `--no-default-features` flag.
+
+## License
+This project is [MIT licensed](./LICENSE).
diff --git a/src/hash/rpo/mod.rs b/src/hash/rpo/mod.rs
index 4ccd5b7..735461b 100644
--- a/src/hash/rpo/mod.rs
+++ b/src/hash/rpo/mod.rs
@@ -55,7 +55,7 @@ const INV_ALPHA: u64 = 10540996611094048183;
 /// Implementation of the Rescue Prime Optimized hash function with 256-bit output.
 ///
 /// The hash function is implemented according to the Rescue Prime Optimized
-/// [specifications](https://github.com/ASDiscreteMathematics/rpo)
+/// [specifications](https://eprint.iacr.org/2022/1577)
 ///
 /// The parameters used to instantiate the function are:
 /// * Field: 64-bit prime field with modulus 2^64 - 2^32 + 1.