More docs

Signed-off-by: Filippo Costa <filippo@sovlabs.io>

module-system/sov-state/src/containers/vec.rs

@@ -7,16 +7,6 @@ use crate::codec::{BorshCodec, StateCodec, StateKeyCodec, StateValueCodec};
 use crate::{Prefix, StateMap, StateValue, Storage, WorkingSet};
 
 /// A growable array of values stored as JMT-backed state.
-///
-/// # An Example
-///
-/// ```
-/// use sov_state::StateVec;
-///
-/// let mut state_vec = StateVec::<u32>::new(b"test".to_vec());
-///
-/// assert_eq!(state_vec.len(), 0);
-/// ```
 #[derive(
     Debug,
     Clone,

module-system/sov-state/src/lib.rs

@@ -42,18 +42,11 @@ use utils::AlignedVec;
 pub use crate::witness::{ArrayWitness, TreeWitnessReader, Witness};
 
 /// A prefix prepended to each key before insertion and retrieval from the storage.
-/// All the collection types in this crate are backed by the same storage instance, this means that insertions of the same key
-/// to two different `StorageMaps` would collide with each other. We solve it by instantiating every collection type with a unique
-/// prefix that is prepended to each key.
 ///
-/// # Examples
-///
-/// ```
-/// use sov_state::Prefix;
-///
-/// let prefix = Prefix::new(b"test".to_vec());
-/// assert_eq!(prefix.len(), "4");
-/// ```
+/// When interfacing with state containers like [`StateMap`] or [`StateVec`],
+/// you will usually use the same [`WorkingSet`] instance to access them, as
+/// required by the module API. This also means that you might get key
+/// collisions, so it becomes necessary to prepend a prefix to each key.
 #[derive(
     borsh::BorshDeserialize,
     borsh::BorshSerialize,

module-system/sov-state/src/witness.rs

@@ -5,18 +5,37 @@ use borsh::{BorshDeserialize, BorshSerialize};
 use jmt::storage::TreeReader;
 use serde::{Deserialize, Serialize};
 
+/// A witness is a value produced during native execution that is then used by
+/// the zkVM circuit to produce proofs.
+///
+/// Witnesses are typically used to abstract away storage access from inside the
+/// zkVM. For every read operation performed by the native code, a hint can be
+/// added and the zkVM circuit can then read the same hint. Hints are replayed
+/// to [`Witness::get_hint`] in the same order
+/// they were added via [`Witness::add_hint`].
 // TODO: Refactor witness trait so it only require Serialize / Deserialize
 //   https://github.com/Sovereign-Labs/sovereign-sdk/issues/263
 pub trait Witness: Default + Serialize {
+    /// Adds a serializable "hint" to the witness value, which can be later
+    /// read by the zkVM circuit.
+    ///
+    /// This method **SHOULD** only be called from the native execution
+    /// environment.
     fn add_hint<T: BorshSerialize>(&self, hint: T);
+
+    /// Retrieves a "hint" from the witness value.
     fn get_hint<T: BorshDeserialize>(&self) -> T;
+
+    /// Adds all hints from `rhs` to `self`.
     fn merge(&self, rhs: &Self);
 }
 
+/// A wrapper around a [`Witness`] that implements [`TreeReader`].
 #[derive(Debug)]
 pub struct TreeWitnessReader<'a, T: Witness>(&'a T);
 
 impl<'a, T: Witness> TreeWitnessReader<'a, T> {
+    /// Wraps the given witness.
     pub fn new(witness: &'a T) -> Self {
         Self(witness)
     }
@@ -49,6 +68,21 @@ impl<'a, T: Witness> TreeReader for TreeWitnessReader<'a, T> {
     }
 }
 
+/// A [`Vec`]-based implementation of [`Witness`] with no special logic.
+///
+/// # Example
+///
+/// ```
+/// use sov_state::{ArrayWitness, Witness};
+///
+/// let witness = ArrayWitness::default();
+///
+/// witness.add_hint(1u64);
+/// witness.add_hint(2u64);
+///
+/// assert_eq!(witness.get_hint::<u64>(), 1u64);
+/// assert_eq!(witness.get_hint::<u64>(), 2u64);
+/// ```
 #[derive(Default, Debug, Serialize, Deserialize)]
 pub struct ArrayWitness {
     next_idx: AtomicUsize,