From 457b8623be746ef86df4f98c8fb53dbfb5c3738e Mon Sep 17 00:00:00 2001
From: Mark Spanbroek <mark@spanbroek.net>
Date: Thu, 9 Nov 2023 14:44:38 +0100
Subject: [PATCH] Add usage example to Readme

- unit test that example code works
- fixes for said unit test
---
 README.md                      | 23 +++++++++++++++++++++++
 poseidon2.nim                  |  1 +
 poseidon2/io.nim               |  3 +++
 poseidon2/sponge.nim           |  4 ++--
 tests/poseidon2/testReadme.nim | 14 ++++++++++++++
 tests/test.nim                 |  1 +
 6 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 tests/poseidon2/testReadme.nim

diff --git a/README.md b/README.md
index f812e9d..b81b175 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,29 @@ project. Add the following to its .nimble file:
 requires "poseidon2 >= 0.1.0 & < 0.2.0"
 ```
 
+Usage
+-----
+
+Hashing bytes into a field element with the sponge construction:
+```nim
+import poseidon2
+
+let input = [1'u8, 2'u8, 3'u8] # some bytes that you want to hash
+let digest: F = Sponge.digest(input) # a field element
+```
+
+Converting a field element into bytes:
+```nim
+let output: array[32, byte] = digest.toBytes
+```
+
+Combining field elements, useful for constructing a binary Merkle tree:
+```nim
+let left = Sponge.digest([1'u8, 2'u8, 3'u8])
+let right = Sponge.digest([4'u8, 5'u8, 6'u8])
+let combination = compress(left, right)
+```
+
 [1]: https://eprint.iacr.org/2023/323.pdf
 [2]: https://github.com/mratsim/constantine
 [3]: https://github.com/nim-lang/nimble
diff --git a/poseidon2.nim b/poseidon2.nim
index 7595af3..91342fd 100644
--- a/poseidon2.nim
+++ b/poseidon2.nim
@@ -9,6 +9,7 @@ import poseidon2/sponge
 export sponge
 export toBytes
 export elements
+export types
 
 #-------------------------------------------------------------------------------
 
diff --git a/poseidon2/io.nim b/poseidon2/io.nim
index ea83dbf..822c035 100644
--- a/poseidon2/io.nim
+++ b/poseidon2/io.nim
@@ -1,6 +1,9 @@
 import ./types
 import constantine/math/arithmetic
 import constantine/math/io/io_bigints
+import constantine/math/config/curves
+
+export curves
 
 func fromOpenArray(_: type F, bytes: openArray[byte]): F =
   F.fromBig(B.unmarshal(bytes, littleEndian))
diff --git a/poseidon2/sponge.nim b/poseidon2/sponge.nim
index 7da8851..e2bdfc8 100644
--- a/poseidon2/sponge.nim
+++ b/poseidon2/sponge.nim
@@ -60,13 +60,13 @@ func init*(_: type Sponge, rate: static int = 2): Sponge[rate] =
     {.error: "only rate 1 and 2 are supported".}
   result.init
 
-func digest*(_: type Sponge, elements: openArray[F], rate: static int): F =
+func digest*(_: type Sponge, elements: openArray[F], rate: static int = 2): F =
   var sponge = Sponge.init(rate)
   for element in elements:
     sponge.update(element)
   return sponge.finish()
 
-func digest*(_: type Sponge, bytes: openArray[byte], rate: static int): F =
+func digest*(_: type Sponge, bytes: openArray[byte], rate: static int = 2): F =
   var sponge = Sponge.init(rate)
   for element in bytes.elements(F):
     sponge.update(element)
diff --git a/tests/poseidon2/testReadme.nim b/tests/poseidon2/testReadme.nim
new file mode 100644
index 0000000..2de3e8e
--- /dev/null
+++ b/tests/poseidon2/testReadme.nim
@@ -0,0 +1,14 @@
+# Test that the example code from the Readme.md compiles
+
+{.hint[XDeclaredButNotUsed]: off.}
+
+import poseidon2
+
+let input = [1'u8, 2'u8, 3'u8] # some bytes that you want to hash
+let digest: F = Sponge.digest(input) # a field element
+
+let output: array[32, byte] = digest.toBytes
+
+let left = Sponge.digest([1'u8, 2'u8, 3'u8])
+let right = Sponge.digest([4'u8, 5'u8, 6'u8])
+let combination = compress(left, right)
diff --git a/tests/test.nim b/tests/test.nim
index 18adebc..2313cae 100644
--- a/tests/test.nim
+++ b/tests/test.nim
@@ -2,5 +2,6 @@ import ./poseidon2/testPermutation
 import ./poseidon2/testSponge
 import ./poseidon2/testPoseidon2
 import ./poseidon2/testIo
+import ./poseidon2/testReadme
 
 {.warning[UnusedImport]: off.}