smt: add docstrings for runtime/SDK fns

src/runtime/import/smt.rs

@@ -35,6 +35,7 @@ use wasmer::{FunctionEnvMut, WasmPtr};
 use super::acl::acl_allow;
 use crate::runtime::vm_runtime::{ContractSection, Env};
 
+/// An SMT adapter for sled overlay storage. Compatible with the WasmDb SMT adapter
 pub struct SledStorage<'a> {
     overlay: &'a mut sled_overlay::SledDbOverlay,
     tree_key: &'a [u8],
@@ -90,6 +91,13 @@ impl<'a> StorageAdapter for SledStorage<'a> {
     }
 }
 
+/// Adds data to sparse merkle tree. The tree, database connection, and new data to add is
+/// read from `ptr` at offset specified by `len`.
+/// Returns `0` on success; otherwise, returns an error-code corresponding to a
+/// [`ContractError`] (defined in the SDK).
+/// See also the method `merkle_add` in `sdk/src/merkle.rs`.
+///
+/// Permissions: update
 pub(crate) fn sparse_merkle_insert_batch(
     mut ctx: FunctionEnvMut<Env>,
     ptr: WasmPtr<u8>,

src/sdk/src/wasm/merkle.rs

@@ -25,7 +25,8 @@ use crate::{
     wasm::db::DbHandle,
 };
 
-/// Add given elements into a Merkle tree.
+/// Add given elements into a Merkle tree. Used for inclusion proofs.
+///
 /// * `db_info` is a handle for a database where the Merkle tree is stored.
 /// * `db_roots` is a handle for a database where all the new Merkle roots are stored.
 /// * `root_key` is the serialized key pointing to the latest Merkle root in `db_info`
@@ -44,9 +45,8 @@ use crate::{
 ///
 /// Inside `db_roots` we store:
 ///
-/// * All [merkle root:32]s as keys. The value is the current [blockheight:8].
-///   Every blockheight should have a unique merkle root associated with it
-///   although this index is not tracked.
+/// * All [merkle root:32]s as keys. The value is the current [tx_hash:32][call_idx:2].
+///   If no new values are added, then the root key is updated to the current (tx_hash, call_idx).
 pub fn merkle_add(
     db_info: DbHandle,
     db_roots: DbHandle,
@@ -70,6 +70,27 @@ pub fn merkle_add(
     }
 }
 
+/// Add given elements into a sparse Merkle tree. Used for exclusion proofs.
+///
+/// * `db_info` is a handle for a database where the latest root is stored.
+/// * `db_smt` is a handle for a database where all the actual tree is stored.
+/// * `db_roots` is a handle for a database where all the new roots are stored.
+/// * `root_key` is the serialized key pointing to the latest Merkle root in `db_info`
+/// * `elements` are the items we want to add to the tree.
+///
+/// There are 2 databases:
+///
+/// * `db_info` stores general metadata or info.
+/// * `db_roots` stores a log of all the merkle roots.
+///
+/// Inside `db_info` we store:
+///
+/// * The [latest root hash:32] under `root_key`.
+///
+/// Inside `db_roots` we store:
+///
+/// * All [merkle root:32]s as keys. The value is the current [tx_hash:32][call_idx:2].
+///   If no new values are added, then the root key is updated to the current (tx_hash, call_idx).
 pub fn sparse_merkle_insert_batch(
     db_info: DbHandle,
     db_smt: DbHandle,

src/sdk/src/wasm/util.rs

@@ -39,10 +39,12 @@ pub fn set_return_data(data: &[u8]) -> Result<(), ContractError> {
     }
 }
 
+/// Internal function, get raw bytes from the objects store
 pub fn get_object_bytes(data: &mut [u8], object_index: u32) -> i64 {
     unsafe { get_object_bytes_(data.as_mut_ptr(), object_index) }
 }
 
+/// Internal function, get bytes size for an object in the store
 pub fn get_object_size(object_index: u32) -> i64 {
     unsafe { get_object_size_(object_index) }
 }