From 90cdfabbf52fafc4309fd1f654401cb725fa6fe6 Mon Sep 17 00:00:00 2001
From: ertosns <mohab-metwally@riseup.net>
Date: Tue, 24 Oct 2023 14:06:50 +0300
Subject: [PATCH] [dao/architecture] add dao spec WIP

---
 doc/src/architecture/dao/bulla.md            | 14 +++++++
 doc/src/architecture/dao/dao.md              |  6 +++
 doc/src/architecture/dao/dao_exec.md         | 12 ++++++
 doc/src/architecture/dao/dao_propose.md      | 39 ++++++++++++++++++++
 doc/src/architecture/dao/dao_propose_burn.md | 21 +++++++++++
 doc/src/architecture/dao/mint.md             | 23 ++++++++++++
 doc/src/architecture/dao/proposal.md         | 11 ++++++
 doc/src/architecture/dao/vote.md             | 37 +++++++++++++++++++
 doc/src/architecture/dao/vote_burn.md        | 21 +++++++++++
 9 files changed, 184 insertions(+)
 create mode 100644 doc/src/architecture/dao/bulla.md
 create mode 100644 doc/src/architecture/dao/dao.md
 create mode 100644 doc/src/architecture/dao/dao_exec.md
 create mode 100644 doc/src/architecture/dao/dao_propose.md
 create mode 100644 doc/src/architecture/dao/dao_propose_burn.md
 create mode 100644 doc/src/architecture/dao/mint.md
 create mode 100644 doc/src/architecture/dao/proposal.md
 create mode 100644 doc/src/architecture/dao/vote.md
 create mode 100644 doc/src/architecture/dao/vote_burn.md

diff --git a/doc/src/architecture/dao/bulla.md b/doc/src/architecture/dao/bulla.md
new file mode 100644
index 000000000..fc46e079e
--- /dev/null
+++ b/doc/src/architecture/dao/bulla.md
@@ -0,0 +1,14 @@
+# bulla
+
+similar to the payment coin, bulla is EC field element commitment to: (proposerLimit, quorum, $approvalRatio_{quot}$, $approvalRatio_{base}$, tokenId, $pub_x$, $pub_y$) with blinding factor  $blind^{bulla}$
+
+| bulla                  | Description                                            |
+|------------------------|--------------------------------------------------------|
+| proposerLimit          | governance token necessary for the vote to be valid    |
+| quorum                 | minimum number of votes necessary to pass the proposal |
+| $approvalRatio_{quot}$ | proposal approval ratio quotient                       |
+| $approvalRatio_{base}$ | proposal approval ratio base                           |
+| tokenId                | governance token id                                    |
+| $pub_x$                | dao public key x coordinate                            |
+| $pub_y$                | dao public key y coordinate                            |
+| $blind^{bulla}$        | bulla commitment blinding factor                       |
diff --git a/doc/src/architecture/dao/dao.md b/doc/src/architecture/dao/dao.md
new file mode 100644
index 000000000..d46f1721d
--- /dev/null
+++ b/doc/src/architecture/dao/dao.md
@@ -0,0 +1,6 @@
+# Dao contract functions
+
+- Mint (0x00)
+- Propose (0x01)
+- Vote (0x02)
+- Exec (0x03)
diff --git a/doc/src/architecture/dao/dao_exec.md b/doc/src/architecture/dao/dao_exec.md
new file mode 100644
index 000000000..889eee34b
--- /dev/null
+++ b/doc/src/architecture/dao/dao_exec.md
@@ -0,0 +1,12 @@
+# dao execution
+
+
+$$ X = (bulla, coin^{in}, coin^{out}, cm^{vote^{yes}}_x, cm^{vote^{yes}}_y, cm^{vote^{all}}_x, cm^{vote^{all}}_y, cm^{value^{in}}_x, cm^{value^{in}}_y, spendHook^{dao}, spendHook^{user}, data, \dots) $$
+
+- (TODO) why dao exec contract spend hook doesn't have data? although it's public input.
+
+
+# circuit checks
+
+- $quorum <= vote^{all}$
+- $vote^{all} *
diff --git a/doc/src/architecture/dao/dao_propose.md b/doc/src/architecture/dao/dao_propose.md
new file mode 100644
index 000000000..c5311f298
--- /dev/null
+++ b/doc/src/architecture/dao/dao_propose.md
@@ -0,0 +1,39 @@
+# dao propose
+$$ X = (cm^{token}, root^{bulla}, proposal, value^{total}_x, value^{total}_y) $$
+$$ W = (value^{total}, blind^{value^{total}}, blind^{token}, proposal^{destination}_x, proposal^{destination}_y, proposal^{amount}, proposal^{tokenId}, blind^{proposal}, proposerLimit, quorum, approvalRatio_{quot}, approvalRatio_{base}, tokenId, pub_x, pub_y, blind^{bulla}, pos, path) $$
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| public input               |                                               |
+|----------------------------|-----------------------------------------------|
+| $cm^{token}$               | proposal token commitment as field element    |
+| $root^{bulla}$             | root of bulla in merkle tree                  |
+| proposal                   | dao proposer proposal                         |
+| $value^{total}_x$          | total fund commitment's x coordinate          |
+| $value^{total}_y$          | total fund commitment's y coordinate          |
+
+| witnesses                | Description                                            |
+|--------------------------|--------------------------------------------------------|
+| $value^{total}$          | total proposal funds value                             |
+| $blind^{value^{total}}$  | blinding value for $value^{total}$ commitment           |
+| $blind^{token}$          | proposal token commitment blinding factor              |
+|$proposal^{destination}_x$| proposal destination public key x coordinate           |
+|$proposal^{destination}_y$| proposal destination public key y coordinate           |
+| $proposal^{amount}$      | proposal amount in proposal token                      |
+| $proposal^{tokenId}$     | proposal token id                                      |
+| $blind^{proposal}$       | proposal commitment blinding term                      |
+| proposerLimit            | governance token necessary for the vote to be valid    |
+| quorum                   | minimum number of votes necessary to pass the proposal |
+| $approvalRatio_{quot}$   | proposal approval ratio quotient                       |
+| $approvalRatio_{base}$   | proposal approval ratio base                           |
+| tokenId                  | governance token id                                    |
+| $pub_x$                  | proposal public key x coordinate                       |
+| $pub_y$                  | proposal public key y coordinate                       |
+| $blind^{bulla}$          | bulla commitment blinding factor                       |
+| pos                      | bulla leaf position in the merkle tree                 |
+| path                     | path of the bulla leaf at position `pos`
+      |
+
+# circuit checks
+
+- $proposal^{amount} > 0 $
+- ${proposerLimit <= value^{total} $
diff --git a/doc/src/architecture/dao/dao_propose_burn.md b/doc/src/architecture/dao/dao_propose_burn.md
new file mode 100644
index 000000000..9e05b3064
--- /dev/null
+++ b/doc/src/architecture/dao/dao_propose_burn.md
@@ -0,0 +1,21 @@
+# dao propose burn
+
+- TODO why spend hook, and data aren't constrained here?
+
+$$ X = (nullifier, cm^{value}_x, cm^{value}_y, cm^{token}, root,  signature^{public}_x, signature^{public}_y)$$
+
+$$ W = (sk, sn, spendHook, data, value, tokenId, blind^{value}, blind^{token}, pos, path, signature^{secret}) $$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| Public Input         | Description                                             |
+|----------------------|---------------------------------------------------------|
+| nullifier            | hash of (sk||sn)                                        |
+| $cm^{value}_x$       | x coordinate of value point commitment                  |
+| $cm^{value}_y$       | y coordinate of value point commitment                  |
+| $cm^{token}$         | commitment of tokenId as field element                  |
+| root                 | root of commitments tree of coin commitments            |
+| data                 | data read during execution of burn spendHook contract   |
+| spendHook            | burn related contract                                   |
+|$signature^{public}_x$| signature public x coordinate                           |
+|$signature^{public}_y$| signature public y coordinate                           |
diff --git a/doc/src/architecture/dao/mint.md b/doc/src/architecture/dao/mint.md
new file mode 100644
index 000000000..3fe26f5fa
--- /dev/null
+++ b/doc/src/architecture/dao/mint.md
@@ -0,0 +1,23 @@
+# Mint contract
+
+$$ X = (pub_x, pub_y, bulla) $$
+
+$$ W = (proposerLimit, quorum, approvalRatio_{quot}, approvalRatio_{base}, tokenId, sk, blind^{bulla}) $$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| public input | Description                          |
+|--------------|--------------------------------------|
+| $pub_x$      | dao public key EC point x coordinate |
+| $pub_y$      | dao public key EC point y coordinate |
+| bulla        | bulla field element commitment       |
+
+| witnesses              | Description                                            |
+|------------------------|--------------------------------------------------------|
+| proposerLimit          | governance token necessary for the vote to be valid    |
+| quorum                 | minimum number of votes necessary to pass the proposal |
+| $approvalRatio_{quot}$ | proposal approval ratio quotient                       |
+| $approvalRatio_{base}$ | proposal approval ratio base                           |
+| tokenId                | governance token id                                    |
+| sk                     | dao secret key                                         |
+| $blind^{bulla}$        | bulla commitment blinding factor                       |
diff --git a/doc/src/architecture/dao/proposal.md b/doc/src/architecture/dao/proposal.md
new file mode 100644
index 000000000..eb5e0d6bf
--- /dev/null
+++ b/doc/src/architecture/dao/proposal.md
@@ -0,0 +1,11 @@
+# proposal
+EC field element commitment to: $(proposal^{destination}_x, proposal^{destination}_y, proposal^{amount}, proposal^{tokenId}, bulla)$ with blinding factor $blind^{proposal}$
+
+| proposal                   | Destination                                   |
+|----------------------------|-----------------------------------------------|
+| $proposal^{destination}_x$ | proposal destination public key x coordinate  |
+| $proposal^{destination}_y$ | proposal destination public key y coordinate  |
+| $proposal^{amount}$        | proposal amount in proposal token             |
+| $proposal^{tokenId}$       | proposal token id                             |
+| bulla                      | dao bulla                                     |
+| $blind^{proposal}$         | proposal commitment blind factor              |
diff --git a/doc/src/architecture/dao/vote.md b/doc/src/architecture/dao/vote.md
new file mode 100644
index 000000000..17dd4e87e
--- /dev/null
+++ b/doc/src/architecture/dao/vote.md
@@ -0,0 +1,37 @@
+# vote
+
+$$ X = (cm^{token}, proposal, cm^{vote^{yes}}_x, cm^{vote^{yes}}_y, cm^{vote^{all}}_x, cm^{vote^{all}}_y )$$
+
+$$ W = (proposal^{destination}_x, proposal^{destination}_y, proposal^{amount}, tokenId, blind^{proposal}, proposerLimit, quorum, approvalRatio_{quot}, approvalRatio_{base}, tokenId, pub_x, pub_y, blind^{bulla}, vote^{yes}, blind^{vote^{yes}}, vote^{value}, vote^{all}_{value}, blind^{vote^{all}_{value}}, blind^{token} )$$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| public inputs       | Description                                |
+|---------------------|--------------------------------------------|
+| $cm^{token}$        | proposal token commitment as field element |
+| proposal            | proposal commitment as field element       |
+| $cm^{vote^{yes}}_x$ | yes vote commitment x coordinate           |
+| $cm^{vote^{yes}}_y$ | yes vote commitment y coordinate           |
+| $cm^{vote^{all}}_x$ | all votes commitment x coordinate          |
+| $cm^{vote^{all}}_y$ | all votes commitment y coordinate          |
+
+| Witnesses                  | Description                                            |
+|----------------------------|--------------------------------------------------------|
+| $proposal^{destination}_x$ | proposal destination public key x coordinate           |
+| $proposal^{destination}_y$ | proposal destination public key y coordinate           |
+| $proposal^{amount}$        | proposal amount in proposal token                      |
+| tokenId                    | proposal token id                                      |
+| $blind^{proposal}$         | proposal commitment blinding factor                    |
+| proposerLimit              | governance token necessary for the vote to be valid    |
+| quorum                     | minimum number of votes necessary to pass the proposal |
+| $approvalRatio_{quot}$     | proposal approval ratio quotient                       |
+| $approvalRatio_{base}$     | proposal approval ratio base                           |
+| tokenId                    | governance token id                                    |
+| $pub_x$                    | dao public key x coordinate                            |
+| $pub_y$                    | dao public key y coordinate                            |
+| $blind^{bulla}$            | bulla commitment blinding factor                       |
+| $vote^{yes}$               | yes vote                                               |
+| $blind^{vote^{yes}}$        | yes vote commitment blinding factor                    |
+| $vote^{all}_{value}$        | all votes value                                       |
+| $blind^{vote^{all}_{value}}$| blinding term for all votes commitments                |
+| $blind^{token}$             | governance token blinding term                        |
diff --git a/doc/src/architecture/dao/vote_burn.md b/doc/src/architecture/dao/vote_burn.md
new file mode 100644
index 000000000..94cc1bf93
--- /dev/null
+++ b/doc/src/architecture/dao/vote_burn.md
@@ -0,0 +1,21 @@
+# vote burn
+
+- TODO why spend hook, and data aren't constrained here?
+
+$$ X = (nullifier, cm^{value}_x, cm^{value}_y, cm^{token}, root,  signature^{public}_x, signature^{public}_y)$$
+
+$$ W = (sk, sn, spendHook, data, value, tokenId, blind^{value}, blind^{token}, pos, path, signature^{secret})$$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| Public Input         | Description                                             |
+|----------------------|---------------------------------------------------------|
+| nullifier            | hash of (sk||sn)                                        |
+| $cm^{value}_x$       | x coordinate of value point commitment                  |
+| $cm^{value}_y$       | y coordinate of value point commitment                  |
+| $cm^{token}$         | commitment of tokenId as field element                  |
+| root                 | root of commitments tree of coin commitments            |
+| data                 | data read during execution of burn spendHook contract   |
+| spendHook            | burn related contract                                   |
+|$signature^{public}_x$| signature public x coordinate                           |
+|$signature^{public}_y$| signature public y coordinate                           |