From 5a680a0c9a2985dbd4e098059d591c93e7061bd6 Mon Sep 17 00:00:00 2001 From: x Date: Fri, 28 Jul 2023 23:38:20 +0000 Subject: [PATCH] zero2darkfi: 1st pass before test/client code --- doc/src/SUMMARY.md | 6 +- doc/src/glossary/glossary.md | 13 ++++ doc/src/zero2dark/zero2darkfi.md | 1 - doc/src/zero2darkfi/darkmap.md | 111 +++++++++-------------------- doc/src/zero2darkfi/zero2darkfi.md | 8 ++- 5 files changed, 58 insertions(+), 81 deletions(-) create mode 100644 doc/src/glossary/glossary.md delete mode 100644 doc/src/zero2dark/zero2darkfi.md diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index dcf382027..a7480223c 100644 --- a/doc/src/SUMMARY.md +++ b/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) diff --git a/doc/src/glossary/glossary.md b/doc/src/glossary/glossary.md new file mode 100644 index 000000000..78f8a7e94 --- /dev/null +++ b/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 diff --git a/doc/src/zero2dark/zero2darkfi.md b/doc/src/zero2dark/zero2darkfi.md deleted file mode 100644 index 15f621658..000000000 --- a/doc/src/zero2dark/zero2darkfi.md +++ /dev/null @@ -1 +0,0 @@ -# zero2darkfi diff --git a/doc/src/zero2darkfi/darkmap.md b/doc/src/zero2darkfi/darkmap.md index 100974a4f..0af7fcc67 100644 --- a/doc/src/zero2darkfi/darkmap.md +++ b/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 +# Build the zkas compiler +cd $HOME && git clone https://github.com/darkrenaissance/darkfi darkfi-master +cd darkfi && make zkas +PATH="$PATH:$PWD" + +cd $HOME && git clone https://github.com/darkrenaissance/darkmap +cd darkmap && make ``` -### Tool 1: wasm contract +## Tool 1: zkas, zkvm + +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. + +In Darkfi, circuits are programmed in `zkas` (ZK ASsembly) and later run in zkvm to generate proofs. + +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 `/proof/set_v1.zk`. + +## Tool 2: zkrunner, darkfi-sdk-py + +We mentioned zkas circuits are "run inside" zkvm. How? + +There is a developer facing cli `zkrunner`. The cli allows you to interact with zkvm in Python. + +Let's see how to run the `set_v1.zk` by reading `/bin/zkrunner/README.md`. + +## Tool 3: 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 2: zk proofs +Let's read `/src/entrypoints.rs`. -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` - -There is a macro defining 4 entrypoints the contract runtime calls. -They are called in order: -1. init -1. metadata -1. exec -1. apply - -``` -darkfi_sdk::define_contract!( - init: init_contract, - exec: process_instruction, - apply: process_update, - metadata: get_metadata -); -``` - -## Init - -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) - -``` -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(()) -} -``` - -### Under the hood - -``` -// https://github.com/darkrenaissance/darkfi/blob/85c53aa7b086652ed6d2428bf748f841485ee0e2/src/runtime/import/db.rs#L522 - -/// 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, ptr: WasmPtr, len: u32) -> i32 { -``` - -## Metadata - -## Exec - -## Apply - -## 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, ptr: WasmPtr, 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 + diff --git a/doc/src/zero2darkfi/zero2darkfi.md b/doc/src/zero2darkfi/zero2darkfi.md index ccbf8103d..480d5d6ae 100644 --- a/doc/src/zero2darkfi/zero2darkfi.md +++ b/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 \ No newline at end of file