Module DB Interface

Coordinator interface

pub trait DbContext {
	type Value = Vec<u8>;
	type Key = AsRef<[u8]>;

	fn get(storage_id: u16, key: Key) -> Option<Value>;
	fn set(storage_id: u16, key: Key, value: Value);
	fn has(storage_id: u16, key: Key) -> bool;
	fn delete(storage_id: u16, key: Key);
	/// Create a recoverable checkpoint of this state
	fn create_checkpoint();
	/// Revert to the last checkpoint and discard it
	fn revert_to_the_checkpoint();
	/// Merge last checkpoint with previous
	fn discard_checkpoint();
}

• DB subspace can be generated with key-prefix when connecting modules
• get go through the following steps
  • Context resolves the DB subspace corresponding to the storage_id
  • If exists, fetch the byte expression of the corresponding value from DB subspace
• set go through the following steps
  • Context resolves the DB subspace corresponding to the storage_id
  • Set the value utilizing set method in the subspace
• Modules will execute transactions within a block following their own rules. Modules respond to the deliverBlock only once so the checkpoint and revert functionality cannot be provided by the coordinator automatically.
• create_checkpoint
  • It creates a top level db check point in case of a reversion
• revert_to_the_last_checkpoint
  • Revert a module state back to the last check point
  • Called when runtime errors occur during a transaction execution

SubStorageAccess (DB seen from Module)

• DB subspace for modules are created by key-prefixing in a merkle-trie
  • set and get calculate actual db key(address) by prefixing after hashing
  • Coordinator level StorageId will have a type of u16 and it is more convenient for applications to use String type for StorageId
  • Top-level database manages map from higher level ModuleIds to lower level ModuleIds
  • Module DB occupies ModuleId prefixed subspace out of the whole Trie
• check_point and revert
  • Making check points and reverting are required for runtime-failing transactions
• Cache layer
  • Before committing state transitions, the db operations are performed at the Cache layer
  • Cache layer support check_point and revert for tentative state transitions
• Commit
  • persist state transitions to disk
• application_state_root
  • Top Level state manages merkle root of each modules and renew the application merkle root to respond Commit in abci.