From d06082b308650eb7af7e2e82f083bfd039a9b5d0 Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Mon, 6 Jan 2025 18:43:03 +0100 Subject: [PATCH] Mina-poseidon: top-level documentation to ues the library The interface to instantiate a sponge is not straightforward to use. This commit adds an example at the top-level of the library to guide the users. --- poseidon/src/lib.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/poseidon/src/lib.rs b/poseidon/src/lib.rs index e2ff0f1e60..5b023d0ba2 100644 --- a/poseidon/src/lib.rs +++ b/poseidon/src/lib.rs @@ -1,3 +1,28 @@ +//! This crate provides a generic implementation of the Poseidon hash function. +//! It provides a [Sponge](crate::sponge::FqSponge) trait that can be +//! implemented for any field. +//! +//! Some parameters for the Pasta fields are provided in the sub-crate +//! [crate::pasta]. +//! +//! To instantiate an object that can be used to generate challenges for the +//! Fiat-Shamir transformation, use the +//! [DefaultFqSponge](crate::sponge::DefaultFqSponge) struct. For instance, to +//! instantiate with the parameters used by the Mina hard-fork called Berkeley, +//! use: +//! ```rust +//! use mina_curves::pasta::{VestaParameters}; +//! use mina_poseidon::sponge::DefaultFqSponge; +//! use mina_poseidon::FqSponge; +//! use mina_poseidon::constants::PlonkSpongeConstantsKimchi; +//! use mina_poseidon::pasta::fq_kimchi; +//! +//! let mut sponge = DefaultFqSponge::::new( +//! fq_kimchi::static_params(), +//! ); +//! let challenge = sponge.challenge(); +//! ``` + pub mod constants; pub mod dummy_values; pub mod pasta;