[doc/spec] iteration of dao spec WIP

doc/src/spec/dao/bulla.md

@@ -1,14 +1,14 @@
-# bulla
+# 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}$
+Similar to the payment [coin](../payment/coin.md), bulla is EC field element [commitment](../crypto/commitment.md) to: (proposerLimit, quorum, $approvalRatio_{quot}$, $approvalRatio_{base}$, tokenId, $pub_x$, $pub_y$) with blinding factor  $blind^{bulla}$
 
-| bulla                  | Description                                            |
+| 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                       |
+| quorum                 | minimum number of votes necessary to pass the [proposal](proposal.md) |
+| $approvalRatio_{quot}$ | [proposal](proposal.md) approval ratio quotient                       |
+| $approvalRatio_{base}$ | [proposal](proposal.md) approval ratio base                           |
+| tokenId                | governance [token id](../payment/token_id.md)                                    |
+| $pub_x$                | dao [public key](../crypto/keypair.md) x coordinate                            |
+| $pub_y$                | dao [public key](../crypto/keypair.md) y coordinate                            |
+| $blind^{bulla}$        | bulla [commitment](../crypto/commitment.md) blinding factor                       |

doc/src/spec/dao/dao_propose.md

@@ -1,42 +1,49 @@
-# dao propose
+# Dao propose
 
-$$ X = (cm^{token}, root^{bulla}, proposal, value^{total}_x, value^{total}_y) $$
+$$ X = (cm^{token}, root^{bulla}, proposal, cm^{value^{total}}_x, cm^{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}\} $$
+$$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
 
-| public input               |                                               |
+## Create dao proposal
+
+- Calculate, and reveal [token](../payment/tokne_id.md) [commitment](../crypto/commitment.md)
+- Calculate, and reveal [bulla](bulla.md)
+- Calculate, and reveal [proposal](proposal.md)
+- Calculate, and reveal total proposers funds [commitment](../crypto/commitment.md)
+
+| Public input               | Description                                  |
 |----------------------------|-----------------------------------------------|
-| $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                      |
+| $cm^{token}$               | [proposal](proposal.md) [token](../payment/token_id.md) [commitment](../crypto/commitment.md) as field element    |
+| $root^{bulla}$             | root of [bulla](bulla.md) in [merkle tree](../crypto/merkletree.md)                  |
+| proposal                   | dao proposer [proposal](proposal.md)                         |
+| $cm^{value^{total}}_x$          | total funds [commitment](../crypto/commitment.md)'s x coordinate          |
+| $cm^{value^{total}}_y$          | total funds [commitment](../crypto/commitment.md)'s y coordinate          |
+
+| Witnesses                | Description                                               |
+|--------------------------|-----------------------------------------------------------|
+| $value^{total}$          | total [proposal](proposal.md) funds value                 |
+| $blind^{value^{total}}$  | blinding value for $value^{total}$ [commitment](../crypto/commitment.md)  |
+| $blind^{token}$          | token [commitment](../crypto/commitment.md) blinding factor  |
+|$proposal^{destination}_x$| destination [public key](../crypto/keypair.md) x coordinate           |
+|$proposal^{destination}_y$| destination [public key](../crypto/keypair.md) y coordinate           |
+| $proposal^{amount}$      | amount in [proposal](proposal.md) token                      |
+| $proposal^{tokenId}$     | [proposal](proposal.md) [token id](../payment/token_id.md)   |
+| $blind^{proposal}$       | [proposal](proposal.md) [commitment](../crypto/commitment.md) 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`
+| quorum                   | minimum number of votes necessary to pass the [proposal](proposal.md) |
+| $approvalRatio_{quot}$   | [proposal](proposal.md) approval ratio quotient                       |
+| $approvalRatio_{base}$   | [proposal](proposal.md) approval ratio base                           |
+| tokenId                  | governance [token id](../payment/token_id.md)                                    |
+| $pub_x$                  | [proposal](proposal.md) [public key](../crypto/keypair.md) x coordinate                       |
+| $pub_y$                  | [proposal](proposal.md) [public key](../crypto/keypair.md) y coordinate                       |
+| $blind^{bulla}$          | [bulla](bulla.md) [commitment](../crypto/commitment.md) blinding factor                       |
+| pos                      | [bulla](bulla.md) leaf position in the [merkle tree](../crypto/merkletree.md)                 |
+| path                     | path of the [bulla](bulla.md) leaf at position `pos`
     |
 
-# circuit checks
+# Circuit checks
 
 - $proposal^{amount} > 0$
 - $proposerLimit <= value^{total}$

doc/src/spec/dao/dao_propose_burn.md

@@ -1,35 +1,43 @@
-# dao propose burn
+# Dao propose burn
 
 $$ X = (nullifier, cm^{value}_x, cm^{value}_y, cm^{token}, root,  signature^{public}_x, signature^{public}_y)$$
 
-$$ W = (sk, sn, spendHook[^1], data, value, tokenId, blind^{value}, blind^{token}, pos, path, signature^{secret}) $$
+$$ W = (sk, sn, spendHook, data, value, tokenId, blind^{value}, blind^{token}, pos, path, signature^{secret}) $$
 
-$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+$$ \mathcal{L}= \{X:(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                           |
+## Burn dao proposal
+- Derive, and reveal [nullifier](../crypto/nullifier.md)
+- Calculate, and reveal value [commitment](../crypto/commitment.md)
+- Calculate, and reveal [token](../payment/token_id.md) [commitment](../crypto/commitment.md)
+- Add input [coin](../payment/coin.md) to [merkle tree](../crypto/merkletree.md), and reveal it's root.
+- Reveal associated spendHook contract.
+- Derive, and reveal [signature](../crypto/signature.md) public key [$signature^{public}$](../crypto/keypair.md)
 
-| witnesses            | Description                                          |
+
+| Public Input         | Description                                                                                 |
+|----------------------|---------------------------------------------------------------------------------------------|
+| nullifier            | dao's proposal [coin](../payment/coin.md) [nullifier](../crypto/nullifier.md)                                             |
+| $cm^{value}_x$       | x coordinate of value point [commitment](../crypto/commitment.md)                           |
+| $cm^{value}_y$       | y coordinate of value point [commitment](../crypto/commitment.md)                           |
+| $cm^{token}$         | [commitment](../crypto/commitment.md) of [tokenId](../payment/token_id.md) as field element |
+| root                 | root of commitments [merkle tree](../crypto/merkletree.md) of [coin](../payment/coin.md)s   |
+| data                 | data read during execution of burn spendHook contract                                       |
+| spendHook            | propose burn related contract                                                               |
+|$signature^{public}_x$| [signature](../crypto/signature.md) [public key](../crypto/keypair.md) x coordinate         |
+|$signature^{public}_y$| [signature](../crypto/signature.md) [public key](../crypto/keypair.md) y coordinate         |
+
+
+| Witnesses            | Description                                          |
 |----------------------|------------------------------------------------------|
-| sk                   | proposal coin secret key                             |
-| sn                   | proposal coin serial number                          |
-| spendHook            | burnt coin spendHook                                 |
+| sk                   | [proposal](proposal.md) [coin](../payment/coin.md) [secret key](../crypto/keypair.md     |
+| sn                   | [proposal](proposal.md) [coin](../payment/coin.md) serial number                          |
+| spendHook            | burn spendHook contract                                |
 | data                 | spendHook contract input data                        |
-| value                | proposal coin value                                  |
-| tokenId              | proposal token id                                    |
-| $blind^{value}$      | proposal value commitment blinding term              |
-| $blind^{token}$      | token commitment blinding term                       |
-| pos                  | proposal coin leaf position in merkle tree           |
-| path                 | proposal coin path in merkle tree                    |
-| $signature^{secret}$ | proposal signature secret                            |
-
-[^1]: why spend hook, and data aren't constrained here?
+| value                | [proposal](proposal.md) [coin](../payment/coin.md) value                                  |
+| tokenId              | [proposal](proposal.md) [coin](../payment/coin.md) [token id](../payment/token_id.md)                                    |
+| $blind^{value}$      | [proposal](proposal.md) value [commitment](../crypto/commitment.md) blinding term              |
+| $blind^{token}$      | [token](../payment/token_id.md) [commitment](../crypto/commitment.md) blinding term                       |
+| pos                  | [proposal](proposal.md) [coin](../payment/coin.md) leaf position in [merkle tree](../crypto/merkletree.md)           |
+| path                 | [proposal](proposal.md) [coin](../payment/coin.md) path in [merkle tree](../crypto/merkletree.md)                    |
+| $signature^{secret}$ | [proposal](proposal.md) [signature](../crypto/signature.md) [secret key](../crypto/keypair.md)                            |

doc/src/spec/dao/mint.md

@@ -1,23 +1,30 @@
 # Mint contract
 
+Mint a new dao [bulla](bulla.md).
+
 $$ X = (pub_x, pub_y, bulla) $$
 
 $$ W = (proposerLimit, quorum, approvalRatio_{quot}, approvalRatio_{base}, tokenId, sk, blind^{bulla}) $$
 
-$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+$$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
+
+## Mint bulla
+
+- Derive, and reveal dao authority [public key](../crypto/keypair.md).
+- Calculate, and reveal [bulla](bulla.md).
 
-| public input | Description                          |
+| 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       |
+| $pub_x$      | dao [public key](../crypto/keypair.md) EC point x coordinate |
+| $pub_y$      | dao [public key](../crypto/keypair.md) EC point y coordinate |
+| bulla        | [bulla](bulla.md) field element [commitment](../crypto/commitment.md)       |
 
-| witnesses              | Description                                            |
+| 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                       |
+| quorum                 | minimum number of votes necessary to pass the [proposal](proposal.md) |
+| $approvalRatio_{quot}$ | [proposal](proposal.md) approval ratio quotient                       |
+| $approvalRatio_{base}$ | [proposal](proposal.md) approval ratio base                           |
+| tokenId                | governance [token id](../payment/token_id.md)                                    |
+| sk                     | dao [secret key](../crypto/keypair.md)                                         |
+| $blind^{bulla}$        | [bulla](bulla.md) [commitment](../crypto/commitment.md) blinding factor                       |

doc/src/spec/dao/proposal.md

@@ -1,11 +1,12 @@
-# proposal
-EC field element commitment to: $(proposal^{destination}_x, proposal^{destination}_y, proposal^{amount}, proposal^{tokenId}, bulla)$ with blinding factor $blind^{proposal}$
+# Proposal
 
-| proposal                   | Destination                                   |
+EC field element [commitment](../crypto/commitment.md) 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^{destination}_x$ | proposal destination [public key](../crypto/keypair.md) x coordinate  |
+| $proposal^{destination}_y$ | proposal destination [public key](../crypto/keypair.md) y coordinate  |
 | $proposal^{amount}$        | proposal amount in proposal token             |
-| $proposal^{tokenId}$       | proposal token id                             |
-| bulla                      | dao bulla                                     |
-| $blind^{proposal}$         | proposal commitment blind factor              |
+| $proposal^{tokenId}$       | proposal [token id](../payment/token_id.md)                             |
+| bulla                      | dao [bulla](bulla.md)                                     |
+| $blind^{proposal}$         | proposal [commitment](../crypto/commitment.md) blind factor              |

doc/src/spec/dao/vote.md

@@ -1,14 +1,19 @@
-# vote
+# 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}\} $$
+$$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
 
-| public inputs       | Description                                |
+## Dao vote proof
+
+- Calculate, and reveal proposal token commitment
+-
+
+| Public inputs       | Description                                |
 |---------------------|--------------------------------------------|
-| $cm^{token}$        | proposal token commitment as field element |
+| $cm^{token}$        | [proposal](proposal.md) token [commitment](../crypto/commitment.md) 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           |
@@ -36,6 +41,6 @@ $$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
 | $blind^{vote^{all}_{value}}$| blinding term for all votes commitments               |
 | $blind^{token}$             | governance token blinding term                        |
 
-# circuit checks
+# Circuit checks
 
-- validate that $vote^{yes}$ is either 0, or 1.
+- Validate that $vote^{yes}$ is either 0, or 1.