docs: add documentation to the store's State (0xPolygonMiden#180)

store/src/config.rs

@@ -10,7 +10,7 @@ pub const CONFIG_FILENAME: &str = "miden-store.toml";
 
 #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Serialize, Deserialize)]
 pub struct StoreConfig {
-    /// Defines the lisening socket.
+    /// Defines the listening socket.
     pub endpoint: Endpoint,
     /// SQLite database file
     pub database_filepath: PathBuf,

store/src/state.rs

@@ -134,6 +134,7 @@ impl From<NullifierStateForTransactionInput> for NullifierTransactionInputRecord
 }
 
 impl State {
+    /// Loads the state from the `db`.
     #[instrument(skip(db))]
     pub async fn load(mut db: Db) -> Result<Self, anyhow::Error> {
         let nullifier_tree = load_nullifier_tree(&mut db).await?;
@@ -320,13 +321,20 @@ impl State {
         Ok(())
     }
 
+    /// Queries a [BlockHeader] from the database.
+    ///
+    /// If [None] is given as the value of `block_num`, the latest [BlockHeader] is returned.
     pub async fn get_block_header(
         &self,
         block_num: Option<BlockNumber>,
     ) -> Result<Option<block_header::BlockHeader>, anyhow::Error> {
         self.db.select_block_header_by_block_num(block_num).await
     }
 
+    /// Generates membership proofs for each one of the `nullifiers` against the latest nullifier
+    /// tree.
+    ///
+    /// Note: these proofs are invalidated once the nullifier tree is modified, i.e. on a new block.
     pub async fn check_nullifiers(
         &self,
         nullifiers: &[RpoDigest],
@@ -335,6 +343,22 @@ impl State {
         nullifiers.iter().map(|n| inner.nullifier_tree.prove(*n)).collect()
     }
 
+    /// Loads data to synchronize a client.
+    ///
+    /// The client's request contains a list of tag prefixes, this method will return the first
+    /// block with a matching tag, or the chain tip. All the other values are filter based on this
+    /// block range.
+    ///
+    /// # Arguments
+    ///
+    /// - `block_num`: The last block *know* by the client, updates start from the next block.
+    /// - `account_ids`: Include the account's hash if their _last change_ was in the result's block
+    ///   range.
+    /// - `note_tag_prefixes`: Only the 16 high bits of the tags the client is interested in, result
+    ///   will include notes with matching prefixes, the first block with a matching note determines
+    ///   the block range.
+    /// - `nullifier_prefixes`: Only the 16 high bits of the nullifiers the client is intersted in,
+    ///   results will cinlude nullifiers matching prefixes produced in the given block range.
     pub async fn sync_state(
         &self,
         block_num: BlockNumber,
@@ -411,6 +435,7 @@ impl State {
         Ok((latest, peaks, account_states))
     }
 
+    /// Returns data needed by the block producer to verify transactions validity.
     pub async fn get_transaction_inputs(
         &self,
         account_id: AccountId,
@@ -444,16 +469,20 @@ impl State {
         Ok((account, nullifier_blocks))
     }
 
+    /// Lists all known nullifiers with their inclusion blocks, intended for testing.
     pub async fn list_nullifiers(&self) -> Result<Vec<(RpoDigest, u32)>, anyhow::Error> {
         let nullifiers = self.db.select_nullifiers().await?;
         Ok(nullifiers)
     }
 
+    /// Lists all known accounts, with their ids, latest state hash, and block at which the account was last
+    /// modified, intended for testing.
     pub async fn list_accounts(&self) -> Result<Vec<AccountInfo>, anyhow::Error> {
         let accounts = self.db.select_accounts().await?;
         Ok(accounts)
     }
 
+    /// Lists all known notes, intended for testing.
     pub async fn list_notes(&self) -> Result<Vec<Note>, anyhow::Error> {
         let notes = self.db.select_notes().await?;
         Ok(notes)