[dao/architecture] add dao spec WIP

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                       |

doc/src/architecture/dao/dao.md

@@ -0,0 +1,6 @@
+# Dao contract functions
+
+- Mint (0x00)
+- Propose (0x01)
+- Vote (0x02)
+- Exec (0x03)

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} *

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} $

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                           |

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                       |

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              |

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                        |

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                           |