spec2: concepts page

doc/src/SUMMARY.md

@@ -108,6 +108,10 @@
   - [vrf](spec/crypto/vrf.md)
   - [nullifier](spec/crypto/nullifier.md)
 
+# Specs
+
+- [Concepts](spec2/concepts.md)
+
 # P2P API Tutorial
 
 - [P2P API Tutorial](learn/dchat/dchat.md)

doc/src/spec2/concepts.md

@@ -0,0 +1,57 @@
+# Concepts
+
+## Transactions
+
+Each *transaction* is an atomic state update containing several *contract calls*
+organized in a tree.
+
+A *contract call* is the call data and function ID that calls a specific
+*contract function*.
+Additionally associated with each call are proofs and signatures that
+can be verified in any order.
+
+```rust
+{{#include ../../../src/tx/mod.rs:transaction}}
+```
+
+```rust
+{{#include ../../../src/sdk/src/tx.rs:contractcall}}
+```
+
+The tree of structure for contract calls corresponds to invocation semantics,
+but with the entire callgraph unrolled ahead of time.
+
+## WASM VM
+
+*Host* refers to the context which loads and calls the WASM contract code.
+
+Contracts are compiled WASM binary code. The WASM engine is a sandboxed
+environment with limited access to the host.
+
+*WASM exports* are functions exported from WASM and callable by the WASM engine.
+
+## Contract Sections
+
+Contract operation is defined by *sections*. Each contract section is only
+allowed to call certain host functions.
+
+**Example:** `exec()` may call `db_get()` but not `db_set()`, while `update()`
+cannot call `db_get()`, but may call `db_set()`.
+
+```rust
+{{#include ../../../src/runtime/vm_runtime.rs:contract-section}}
+```
+
+| Host function     | Permission                     | Description                         |
+|-------------------|--------------------------------|-------------------------------------|
+| `db_init`         | Deploy                         | Create a new database               |
+| `db_lookup`       | Deploy, Exec, Metadata, Update | Lookup a database handle by name    |
+| `db_set`          | Deploy, Update                 | Set a value                         |
+| `db_del`          | Deploy, Update                 | Remove a key                        |
+| `db_get`          | Deploy, Exec, Metadata         | Read a value from a key             |
+| `db_contains_key` | Deploy, Exec, Metadata, Update | Check if a given key exists         |
+| `zkas_db_set`     | Deploy                         | Insert a new ZK circuit             |
+| `merkle_add`      | Update                         | Add a leaf to a merkle tree         |
+| `set_return_data` | Exec, Metadata                 | Used for returning data to the host |
+| `get_slot`        | Deploy, Exec, Metadata         | Get the current slot                |
+

src/runtime/import/db.rs

@@ -446,7 +446,7 @@ pub(crate) fn db_del(ctx: FunctionEnvMut<Env>, ptr: WasmPtr<u8>, ptr_len: u32) -
     DB_SUCCESS
 }
 
-/// Reads a key from the key-value store.
+/// Reads a value by key from the key-value store.
 /// Thie function can be called from the Deploy, Exec, or Metadata [`ContractSection`].
 /// On success, returns the length of the `objects` Vector in the environment.
 /// Otherwise, returns a negative error code.

src/runtime/vm_runtime.rs

@@ -47,6 +47,7 @@ const MEMORY: &str = "memory";
 /// Gas limit for a contract
 const GAS_LIMIT: u64 = 400_000_000;
 
+// ANCHOR: contract-section
 #[derive(Clone, Copy, PartialEq)]
 pub enum ContractSection {
     /// Setup function of a contract
@@ -60,6 +61,7 @@ pub enum ContractSection {
     /// Placeholder state before any initialization
     Null,
 }
+// ANCHOR_END: contract-section
 
 impl ContractSection {
     pub const fn name(&self) -> &str {