zero2darkfi: 1st pass before test/client code

doc/src/SUMMARY.md

@@ -85,6 +85,6 @@
     - [Network Protocol](misc/event_graph/network_protocol.md)
   - [darkwiki](misc/darkwiki.md)
   - [dnetview](misc/dnetview.md)
-- [zero2darkfi](zero2dark/zero2darkfi.md)
-  - [smart contract](zero2darkfi/darkmap.md)
-  - [terminology](zero2darkfi/terminology.md)
+- [Zero2darkfi](zero2darkfi/zero2darkfi.md)
+  - [darkmap](zero2darkfi/darkmap.md)
+- [Glossary](glossary/glossary.md)

doc/src/glossary/glossary.md

@@ -0,0 +1,13 @@
+# Glossary
+
+* Pedersen commitment: a hiding and binding commitment scheme that takes a value and produces an elliptic curve point representing the commitment
+	* Explainer: https://medium.com/coinmonks/zero-knowledge-proofs-um-what-a092f0ee9f28
+* zkas: the programming language in which you can write zk circuits
+	* zkas compiler: https://github.com/darkrenaissance/darkfi/tree/ae9801fce10c1403ac293303b75a15db115b4da6/src/zkas
+        * an example circuit written in zkas:  https://github.com/darkrenaissance/darkfi/blob/ae9801fce10c1403ac293303b75a15db115b4da6/example/simple.zk
+* zkvm: the virtual machine in which zkas circuit binary is run
+	* it runs during proof generation
+		* rust example: https://github.com/darkrenaissance/darkfi/blob/ae9801fce10c1403ac293303b75a15db115b4da6/tests/zkvm_opcodes.rs
+		* python example: https://github.com/darkrenaissance/darkfi/blob/ae9801fce10c1403ac293303b75a15db115b4da6/bin/zkrunner/zkrunner.py#L141-L160
+* zkrunner: a Python script which allows you, instead of providing circuit, witness, public inputs and code to generate/verify proof, you provide circuit, witness
+		* example: https://github.com/darkrenaissance/darkfi/blob/master/bin/zkrunner/zkrunner.py#L180

doc/src/zero2dark/zero2darkfi.md

@@ -1 +0,0 @@
-# zero2darkfi

doc/src/zero2darkfi/darkmap.md

@@ -66,82 +66,42 @@ darkrenaissance:darkfi.master
 > But you would still be able to follow along even if you aren't, by inferring from the context.
 
 ```
-# Repository
-git clone https://github.com/darkrenaissance/darkmap
-```
-
-### Tool 1: wasm contract
-
-In Darkfi, a contract is deployed as a wasm module. 
-Rust has one of the best wasm support, so Darkmap is implemented in Rust.
-In theory, any language that compiles to wasm can be used make a contract e.g. Zig.
+# Build the zkas compiler
+cd $HOME && git clone https://github.com/darkrenaissance/darkfi darkfi-master
+cd darkfi && make zkas
+PATH="$PATH:$PWD"
 
-### Tool 2: zk proofs
-
-You can make a ZK scheme where:
-* a user computes a ZK proof locally and submit along the transaction.
-* the contract grants access to change a key-value mapping that user **owns** when received a valid proof.
-
-## wasm contract: `entrypoint.rs`
+cd $HOME && git clone https://github.com/darkrenaissance/darkmap
+cd darkmap && make
+```
 
-There is a macro defining 4 entrypoints the contract runtime calls.
-They are called in order:
-1. init
-1. metadata
-1. exec
-1. apply
+## Tool 1: zkas, zkvm
 
-```
-darkfi_sdk::define_contract!(
-    init:     init_contract,
-    exec:     process_instruction,
-    apply:    process_update,
-    metadata: get_metadata
-);
-```
+We want a way for someone to control an account. You could use public key 
+crytography. But in here, we will use zk to accomplish the same thing.
 
-## Init
+In Darkfi, circuits are programmed in `zkas` (ZK ASsembly) and later run in zkvm to generate proofs.
 
-Init is responsible for 2 tasks:
-1. from the zkas binary, compute and store the corresponding verifying key 
-2. initialize any number of databases (e.g. for the contract's business logic)
+There is one circuit that Darkmap uses, which is the set circuit for gating the `set` function. Let's see what it does and
+start reading `<darkmap>/proof/set_v1.zk`.
 
-```
-fn init_contract(cid: ContractId, ix: &[u8]) -> ContractResult {
-    
-    // The way to load zkas binary as native contracts, it will probably be different regular contracts
-    let set_v1_bincode = include_bytes!("../proof/set_v1.zk.bin");
-
-    // Compute and store verifying key if it's not already stored
-    zkas_db_set(&set_v1_bincode[..])?;
-
-    // Check if a db is already initialized
-    if db_lookup(cid, MAP_CONTRACT_ENTRIES_TREE).is_err() {
-	// db for business logic
-        db_init(cid, MAP_CONTRACT_ENTRIES_TREE)?;
-    }
-
-    Ok(())
-}
-```
+## Tool 2: zkrunner, darkfi-sdk-py
 
-### Under the hood
+We mentioned zkas circuits are "run inside" zkvm. How?
 
-```
-// https://github.com/darkrenaissance/darkfi/blob/85c53aa7b086652ed6d2428bf748f841485ee0e2/src/runtime/import/db.rs#L522
+There is a developer facing cli `zkrunner`. The cli allows you to interact with zkvm in Python.
 
-/// Only `deploy()` can call this. Given a zkas circuit, create a VerifyingKey and insert
-/// them both into the db.
-pub(crate) fn zkas_db_set(ctx: FunctionEnvMut<Env>, ptr: WasmPtr<u8>, len: u32) -> i32 {
-```
+Let's see how to run the `set_v1.zk` by reading `<darkfi>/bin/zkrunner/README.md`.
 
-## Metadata
+## Tool 3: wasm contract
 
-## Exec
+In Darkfi, a contract is deployed as a wasm module. 
+Rust has one of the best wasm support, so Darkmap is implemented in Rust.
+In theory, any language that compiles to wasm can be used make a contract e.g. Zig.
 
-## Apply
+Let's read `<darkmap>/src/entrypoints.rs`.
 
-## Others
+## Notes
 
 * Where are the states stored?
 	* There is no memory, there is calldata
@@ -149,13 +109,12 @@ pub(crate) fn zkas_db_set(ctx: FunctionEnvMut<Env>, ptr: WasmPtr<u8>, len: u32)
 	* db_init
 	* db_lookup
 	* zkas_db_set
-
-
-## Outline of book
-
-* What is the problem?
 * What are the tools?
-	* zkbincode
-	* wasm crate
-	* transaction builder
+	* zkas
+        * zkvm
+        	* the runtime imports
+	* wasm
+	* client
+		* transaction builder
 	* test facility
+

doc/src/zero2darkfi/zero2darkfi.md

@@ -1,2 +1,8 @@
-TODO
+In this series, you will learn
 
+* How to create Darkfi contracts, only assuming a little background with contracts and blockchains
+	* How does a contract interact with the host?
+	* How does a client interact with a contract?
+	* How to test?
+* Rationale for some design decisions and further reading material
+* Precise terminology