docs: Enhance Zerokit Utils README with comprehensive documentation

- Add detailed overview of Merkle tree and Poseidon hash implementations
- Include installation instructions and crate version badge
- Provide performance considerations and build/test guidance
- Update acknowledgements with source references
- Improve markdown formatting and readability

utils/README.md

@@ -1,15 +1,73 @@
-# Utils crate
+# Zerokit Utils Crate
 
-## Building
+[![Crates.io](https://img.shields.io/crates/v/zerokit_utils.svg)](https://crates.io/crates/zerokit_utils)
 
-1. `cargo build`
+Cryptographic primitives for zero-knowledge applications, featuring efficient Merkle tree implementations and a Poseidon hash function.
 
-## Testing
+## Overview
 
-1. `cargo test`
+This crate provides core cryptographic components optimized for zero-knowledge proof systems:
 
-## Benchmarking
+1. Multiple Merkle tree implementations with different space/time tradeoffs
+2. A Poseidon hash implementation
 
-1. `cargo bench`
+## Merkle Tree Implementations
+
+The crate supports two interchangeable Merkle tree implementations:
+
+- **FullMerkleTree**
+  - Stores each tree node in memory
+- **OptimalMerkleTree**
+  - Only stores nodes used to prove accumulation of set leaves
+
+## Poseidon Hash Implementation
+
+This crate provides an implementation to compute the Poseidon hash round constants and MDS matrices:
+
+- **Customizable parameters**: Supports different security levels and input sizes
+- **Arkworks-friendly**: Adapted to work over arkworks field traits and custom data structures
+
+### Security Note
+
+The MDS matrices are generated iteratively using the Grain LFSR until certain criteria are met. According to the paper, such matrices must respect specific conditions which are checked by 3 different algorithms in the reference implementation.
+
+These validation algorithms are not currently implemented in this crate. For the hardcoded parameters, the first random matrix generated satisfies these conditions. If using different parameters, you should check against the reference implementation how many matrices are generated before outputting the correct one, and pass this number to the `skip_matrices` parameter of the `find_poseidon_ark_and_mds` function.
+
+## Installation
+
+Add Zerokit Utils to your Rust project:
+
+```toml
+[dependencies]
+zerokit-utils = "0.5.1"
+```
+
+## Performance Considerations
+
+- **FullMerkleTree**: Use when memory is abundant and operation speed is critical
+- **OptimalMerkleTree**: Use when memory efficiency is more important than raw speed
+- **Poseidon**: Offers a good balance between security and performance for ZK applications
+
+## Building and Testing
+
+```bash
+# Build the crate
+cargo build
+
+# Run tests
+cargo test
+
+# Run benchmarks
+cargo bench
+```
 
 To view the results of the benchmark, open the `target/criterion/report/index.html` file generated after the bench
+
+## Acknowledgements
+
+- The Merkle tree implementations are adapted from:
+  - [kilic/rln](https://github.com/kilic/rln/blob/master/src/merkle.rs)
+  - [worldcoin/semaphore-rs](https://github.com/worldcoin/semaphore-rs/blob/d462a4372f1fd9c27610f2acfe4841fab1d396aa/src/merkle_tree.rs)
+
+- The Poseidon implementation references:
+  - [Poseidon reference implementation](https://extgit.iaik.tugraz.at/krypto/hadeshash/-/blob/master/code/generate_parameters_grain.sage)