zero2darkfi: Added more context

doc/src/SUMMARY.md

@@ -87,3 +87,4 @@
   - [dnetview](misc/dnetview.md)
 - [zero2darkfi](zero2dark/zero2darkfi.md)
   - [smart contract](zero2darkfi/darkmap.md)
+  - [terminology](zero2darkfi/terminology.md)

doc/src/zero2dark/zero2darkfi.md

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

doc/src/zero2darkfi/darkmap.md

@@ -1,21 +1,52 @@
-## Darkmap
+We are going to walk through a simple (1 private field) contract that uses ZK.
 
-An immutable name registry. The important feature is that names can be
-immutable.
-From an end user perspective, they provide a dpath and get a value back.
+## Problem
+
+Suppose you want a name registry.
+
+You want this to be:
+* resistant to any coercion
+* leaving no trace who owns a name
+
+Because the users intend to use it for very critical things that they like privacy for.
+Say naming their wallet address e.g. anon42's wallet address -> 0x696969696969.
+
+Getting a wrong wallet address means, you pay a bad person instead of anon42.
+Revealing who owns the name reveals information who might own the wallet.
+Both are unacceptable to users.
+
+The users might also want to use it for software releases e.g. declaring that this is a URL for Darkfi's v1.0.
+
+We see there can be backdoor in many solutions. So they don't work for mission critical things.
+
+1. If you run a database on a "cloud", the provider has physical access to the machine.
+1. Domain owners can change what the domain name resolves to.
+1. PKI is backdoored and there is man in the middle attack if you don't use https.
+
+## Solution: Darkmap
+
+An immutable name registry deployed on Darkfi.
+
+The two features: 
+* names can be immutable
+* there is no trace who owns the name
+
+### API: Get
+
+From an end user perspective, they provide a dpath (i.e. a name) and get a value back.
 
-For example:
 ```
 provide: darkrenaissance::darkfi::v0_4_1
 get:     0766e910aae7af482885d0a5b05ccb61ae7c1af4 (which is the commit for Darkfi v0.4.1, https://github.com/darkrenaissance/darkfi/commit/0766e910aae7af482885d0a5b05ccb61ae7c1af4)
 ```
 
-Syntax:
+### Syntax: Dpath
+
 ```
   Colon means the key is locked to particular value.
   For example, the key v0_4_1 is locked to 0766e910aae7af482885d0a5b05ccb61ae7c1af4
   in the name registry that darkrenaissance:darkfi points to.
-  It's helpful to know a tag always means the same commit.
+  Helpful to that a tag always means the same commit.
 	              v
 darkrenaissance:darkfi:v0_4_1
 
@@ -23,45 +54,37 @@ darkrenaissance:darkfi:v0_4_1
   Dot means the key is not locked to a value. 
   It can be locked to a value later or be changed to a different value.
   For example, master (HEAD) currently maps to 85c53aa7b086652ed6d2428bf748f841485ee0e2,
-  It's helpful because HEAD needs to change.
+  Helpful that master (HEAD) can change.
 	              v
 darkrenaissance:darkfi.master
 ```
 
-Beyond the usual things one can do with a name registry e.g. naming website,
-an immutable name provides strong security.
-If the contract and blockchain are secure, the name doesn't change, not even the owner.
-
-Being deployed on Darkfi also means there is no trace you own a name because gas payment
-is anonymous.
+## Implementation
 
-## Contract implementation
-
-> Note: This book assumes basic familiarity with smart contracts and blockchain. 
-> It's good if you are familiar with Rust. You'd still be able to follow along
-> even if you aren't by inferring from the context.
+> Note: This book assumes basic familiarity with contracts and blockchain. 
+> It is good if you are familiar with Rust.
+> 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: wasm contract
+### 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.
 
-### Tool: zkvm and zkas
+### 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 certain features only when it receives a valid proof
-
-## entrypoint.rs
+* 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.
 
-Take a look at `Cargo.toml`, the package's configurations.
+## wasm contract: `entrypoint.rs`
 
-There is macro defining 4 entrypoints the contract runtime calls.
+There is a macro defining 4 entrypoints the contract runtime calls.
 They are called in order:
 1. init
 1. metadata

doc/src/zero2darkfi/terminology.md

@@ -0,0 +1 @@
+# terminology