runtime/merkle: db_roots store key=blockhash, value=blockheight (before value=[])

src/runtime/import/merkle.rs

@@ -45,6 +45,7 @@ pub(crate) fn merkle_add(mut ctx: FunctionEnvMut<Env>, ptr: WasmPtr<u8>, len: u3
     }
 
     // Subtract used gas. Here we count the length read from the memory slice.
+    // This makes calling the function which returns early have some (small) cost.
     env.subtract_gas(&mut store, len as u64);
 
     let memory_view = env.memory_view(&store);
@@ -278,8 +279,10 @@ pub(crate) fn merkle_add(mut ctx: FunctionEnvMut<Env>, ptr: WasmPtr<u8>, len: u3
     );
     let latest_root_data = serialize(latest_root);
     assert_eq!(latest_root_data.len(), 32);
+    let blockheight_data = serialize(&env.verifying_block_height);
+    assert_eq!(blockheight_data.len(), 8);
 
-    if overlay.insert(&db_roots.tree, &latest_root_data, &[]).is_err() {
+    if overlay.insert(&db_roots.tree, &latest_root_data, &blockheight_data).is_err() {
         error!(
             target: "runtime::merkle::merkle_add",
             "[WASM] [{}] merkle_add(): Couldn't insert to db_roots tree", cid,

src/runtime/import/smt.rs

@@ -89,6 +89,7 @@ pub(crate) fn sparse_merkle_insert_batch(
     }
 
     // Subtract used gas. Here we count the length read from the memory slice.
+    // This makes calling the function which returns early have some (small) cost.
     env.subtract_gas(&mut store, len as u64);
 
     let memory_view = env.memory_view(&store);

src/sdk/src/merkle.rs

@@ -31,6 +31,22 @@ use super::{
 /// * `root_key` is the serialized key pointing to the latest Merkle root in `db_info`
 /// * `tree_key` is the serialized key pointing to the Merkle tree in `db_info`.
 /// * `elements` are the items we want to add to the Merkle 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`.
+/// * The incremental merkle tree under `tree_key`.
+///
+/// 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.
 pub fn merkle_add(
     db_info: DbHandle,
     db_roots: DbHandle,