[doc/spec] iterate over dao spec

doc/src/spec/dao/dao_exec.md

@@ -1,60 +1,71 @@
-# dao execution
+# DAO execution
 
-$$ X = (bulla, coin^{proposal}, coin^{dao}, cm^{vote^{yes}}_x, cm^{vote^{yes}}_y, cm^{vote^{all}}_x, cm^{vote^{all}}_y, cm^{value^{proposal}}_x, cm^{value^{prososal}}_y, spendHook^{dao}[^1], spendHook^{proposal}, data^{proposal}) $$
+DAO execution proof once quorum, and yes vote required have been met.
+
+$$ X = (bulla, coin^{proposal}, coin^{dao}, cm^{vote^{yes}}_x, cm^{vote^{yes}}_y, cm^{vote^{all}}_x, cm^{vote^{all}}_y, cm^{value^{proposal}}_x, cm^{value^{prososal}}_y, spendHook^{dao}, spendHook^{proposal}, data^{proposal}) $$
 
 $$ W = (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}, vote^{yes}, vote^{all}, blind^{vote^{yes}}, blind^{vote^{all}}, sn^{proposal}, sn^{dao}, value^{dao}, blind^{value^{dao}}, spendHook^{dao}, spendHook^{proposal}, data^{proposal}) $$
 
-$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+$$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
 
+## Execution proof.
 
-| public inputs              | Description                                            |
-|----------------------------|--------------------------------------------------------|
-| bulla                      | dao bulla                                              |
-| $coin^{proposal}$          | proposal coin                                          |
-| $coin^{dao}$               | dao coin                                               |
-| $cm^{vote^{yes}}_x$        | x-coordinate of commitment to $vote^{yes}$ value       |
-| $cm^{vote^{yes}}_y$        | y-coordinate of commitment to $vote^{yes}$ value       |
-| $cm^{vote^{all}}_x$        | x-coordinate of commitment to $vote^{all}$ value       |
-| $cm^{vote^{all}}_y$        | y-coordinate of commitment to $vote^{all}$ value       |
-| $cm^{value^{proposal}}_x$  | x-coordinate of commitment to $value^{proposal}$       |
-| $cm^{value^{proposal}}_y$  | y-coordinate of commitment to $value^{proposal}$       |
-| $spendHook^{dao}$          | dao spendhook                                          |
-| $spendHook^{proposal}$     | proposal spendhook                                     |
-| $data^{proposal}$          | input data for $spendhook^{proposal}$ contract         |
-
-
-
-| witnesses                  | Destination                                            |
+- Derive, and reveal [bulla](bulla.md)
+- Derive, and reveal [proposal](proposal.md) input [coin](../payment/coin.md)
+- Calculate, and  Reveal yes-vote 0/1 for no/yes [commitment](../crypto/commitment.md) $=vote^{yes}vote^{all^}$
+- Reveal all-vote value [commitment](../crypto/commitment.md)
+- Calculate, and reveal [proposal](proposal.md) coin value [commitment](../crypto/commitment.md)
+- Reveal dao execution spendHook
+- Reveal proposal spendHook
+- Reveal proposal spendHook input data
+- Reveal dao spendHook input data: [bulla](bulla.md) [commitment](../crypto/commitment.md)
+
+| Public inputs              | Description                                                          |
+|----------------------------|----------------------------------------------------------------------|
+| bulla                      | dao [bulla](bulla.md)                                                |
+| $coin^{proposal}$          | [proposal](proposal.md) input [coin](../payment/coin.md)             |
+| $coin^{dao}$               | dao [coin](../payment/coin.md)                                       |
+| $cm^{vote^{yes}}_x$        |  yes vote [commitment](../crypto/commitment.md) x coordinate          |
+| $cm^{vote^{yes}}_y$        | yes vote [commitment](../crypto/commitment.md) y coordinate           |
+| $cm^{vote^{all}}_x$        | all votes [commitment](../crypto/commitment.md) x coordinate          |
+| $cm^{vote^{all}}_y$        | all votes [commitment](../crypto/commitment.md) y coordinate          |
+| $cm^{value^{proposal}}_x$  | x-coordinate of [commitment](../crypto/commitment.md) to $value^{proposal}$                      |
+| $cm^{value^{proposal}}_y$  | y-coordinate of [commitment](../crypto/commitment.md) to $value^{proposal}$                      |
+| $spendHook^{dao}$          | dao spendhook                                                        |
+| $spendHook^{proposal}$     | [proposal](proposal.md) spendhook                                                   |
+| $data^{proposal}$          | input data for $spendhook^{proposal}$ contract                       |
+| $data^{dao}$               | input data for $spendhook^{proposal}$ contract                       |
+
+
+| Witnesses                  | 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                                      |
-| $blind^{proposal}$         | proposal commitment blind 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 a boolean as either 0, or 1                   |
-| $vote^{all}$               | all votes value                                        |
-| $blind^{vote^{yes}}$       | yes vote commitment blinding factor                    |
-| $blind^{vote^{all}}$       | blinding term for all votes commitments                |
-| $sn^{proposal}$            | serial number for proposal coin                        |
-| $sn^{dao}$                 | dao coin serial number                                 |
-| $value^{dao}$              | dao coin input value                                   |
-| $blind^{value^{dao}}$       | dao coin  value blinding term                         |
-| $spendHook^{dao}$          | dao spendhook                                          |
-| $spendHook^{proposal}$     | proposal spendhook                                     |
-| $data^{proposal}$          | input data for $spendhook^{proposal}$ contract         |
-
-
-# circuit checks
+| $proposal^{destination}_x$ | [proposal](proposal.md) destination [public key](../payment/keypair.md) x coordinate           |
+| $proposal^{destination}_y$ | [proposal](proposal.md) destination [public key](../payment/keypair.md) y coordinate           |
+| $proposal^{amount}$        | [proposal](proposal.md) amount in proposal token                      |
+| $proposal^{tokenId}$       | [proposal](proposal.md) [token id](../payment/token_id.md)            |
+| $blind^{proposal}$         | [proposal](proposal.md) [commitment](../crypto/commitment.md) blind factor|
+| proposerLimit              | governance token necessary for the vote to be valid                   |
+| 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](../payment/keypair.md) x coordinate                  |
+| $pub_y$                    | dao [public key](../payment/keypair.md) y coordinate                  |
+| $blind^{bulla}$            | [bulla](bulla.md) [commitment](../crypto/commitment.md) blinding factor|
+| $vote^{yes}$               | yes vote a boolean as either 0, or 1                                  |
+| $vote^{all}$               | all votes value                                                       |
+| $blind^{vote^{yes}}$       | yes vote [commitment](../crypto/commitment.md) blinding factor        |
+| $blind^{vote^{all}}$       | blinding term for all votes [commitment](../crypto/commitment.md)s    |
+| $sn^{proposal}$            | serial number for [proposal](proposal.md) [coin](../payment/coin.md)  |
+| $sn^{dao}$                 | dao input [coin](../payment/coin.md) serial number                    |
+| $value^{dao}$              | dao input [coin](../payment/coin.md) value                            |
+| $blind^{value^{dao}}$       | dao [coin](../payment/coin.md)  value blinding term                  |
+| $spendHook^{dao}$          | dao spendhook                                                         |
+| $spendHook^{proposal}$     | [proposal](proposal.md) spendhook                                                    |
+| $data^{proposal}$          | input data for $spendhook^{proposal}$ contract                        |
+
+
+# Circuit checks
 
 - $ quorum <= vote^{all}$
 - $ \frac{approvalRatio^{quot}}{approvalRatio^{base}} <= \frac{vote^{yes}}{vote^{all}} $
-
-[^1]:  why dao exec contract spend hook doesn't have data? although it's public input.

doc/src/spec/dao/dao_propose_burn.md

@@ -22,8 +22,6 @@ $$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
 | $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         |
 

doc/src/spec/dao/vote.md

@@ -1,45 +1,51 @@
 # Vote
 
+Vote on [proposal](proposal.md) by yes, or no by $proposal^{amount}$ of dao tokens.
+
 $$ 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}) $$
+$$ 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^{yes}, vote^{all}, blind^{vote^{all}}, blind^{token}) $$
 
 $$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
 
 ## Dao vote proof
 
-- Calculate, and reveal proposal token commitment
--
+- Calculate, and reveal [proposal](proposal.md) [token](../payment/token_id.md) [commitment](../crypto/commitment.md) to vote on
+- Derive, and reveal [proposal](proposal.md)
+- Calculate, and  Reveal yes-vote 0/1 for no/yes [commitment](../crypto/commitment.md) $=vote^{yes}vote^{all^}$
+- Reveal all-vote value [commitment](../crypto/commitment.md)
+
 
 | Public inputs       | Description                                |
 |---------------------|--------------------------------------------|
 | $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           |
-| $cm^{vote^{all}}_x$ | all votes commitment x coordinate          |
-| $cm^{vote^{all}}_y$ | all votes commitment y coordinate          |
+| proposal            | [proposal](proposal.md) [commitment](../crypto/commitment.md) as field element       |
+| $cm^{vote^{yes}}_x$ |  yes vote [commitment](../crypto/commitment.md) x coordinate            |
+| $cm^{vote^{yes}}_y$ | yes vote [commitment](../crypto/commitment.md) y coordinate           |
+| $cm^{vote^{all}}_x$ | all votes [commitment](../crypto/commitment.md) x coordinate          |
+| $cm^{vote^{all}}_y$ | all votes [commitment](../crypto/commitment.md) 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                    |
+| $proposal^{destination}_x$ | [proposal](proposal.md) destination [public key](../crypto/keypair.md) x coordinate           |
+| $proposal^{destination}_y$ | [proposal](proposal.md) destination [public key](../crypto/keypair.md) y coordinate           |
+| $proposal^{amount}$        |  amount in [proposal](proposal.md) token                      |
+| tokenId                    | [proposal](proposal.md) token id                                      |
+| $blind^{proposal}$         | [proposal](proposal.md) [commitment](../crypto/commitment.md) 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 a boolean as either 0, or 1                   |
-| $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                        |
+| 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](bulla.md) [commitment](../crypto/commitment.md) blinding factor                       |
+| $vote^{yes}$               | yes vote direction a boolean as either 0/1 for no/yes  |
+| $blind^{vote^{yes}}$       | yes vote [commitment](../crypto/commitment.md) blinding factor                    |
+| $vote^{all}$               | all votes value                                       |
+| $blind^{vote^{all}}$       | blinding term for all votes [commitment](../crypto/commitment.md)s                |
+| $blind^{token}$            | governance token blinding term                        |
 
 # Circuit checks
 

doc/src/spec/dao/vote_burn.md

@@ -1,35 +1,41 @@
-# vote burn
+# Vote burn
+
+Burn proposal vote.
 
 $$ 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:(X,W)\in \mathcal{R}\} $$
 
-$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+## Vote Burn proof
+
+- 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.
+- Derive, and reveal [signature](../crypto/signature.md) public key [$signature^{public}$](../crypto/keypair.md)
 
 | 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 governancetokenId 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                           |
-
-| witnesses            | 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   |
+|$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}$      | governance 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)                            |