spec2: sections on concepts, notation, pallas/vesta

doc/latex-macros.txt

@@ -1,2 +1,5 @@
 \DFT:{\textrm{DFT}}
 \hash:{\textrm{hash}}
+\t:{\textrm{#1}}
+\~:{\sim}
+

doc/src/SUMMARY.md

@@ -110,11 +110,13 @@
 
 # Specs
 
+- [Notation](spec2/notation.md)
 - [Concepts](spec2/concepts.md)
 - [Cryptographic Schemes](spec2/crypto-schemes.md)
 - [Contracts]()
   - [DAO](spec2/contracts/dao/dao.md)
-    - [DAO](spec2/contracts/dao/concepts.md)
+    - [Concepts](spec2/contracts/dao/concepts.md)
+    - [State](spec2/contracts/dao/state.md)
 
 # P2P API Tutorial
 

doc/src/spec2/contracts/dao/concepts.md

@@ -1,2 +1,56 @@
 # Concepts
 
+The governance process is divided in a few steps that are outlined below:
+
+* **Propose:** a proposal is submitted to the blockchain.
+* **Vote:** governance token holdens can vote on the proposal.
+* **Exec:** if the proposal passes within the time limit then the proposal is
+  executed.
+
+## Propose
+
+To prevent spam, proposals must be submitted by holders with a certain number
+of governance tokens. Several members of the DAO can add inputs separately to
+a proposal before it is posted on chain so that their combined inputs meet the
+proposal governance token limit.
+
+Once proposals are posted on chain, they are immediately active.
+
+### Proposal States
+
+* *Active*: the proposal is open to voting.
+* *Expired*: the proposal passed its duration and can no longer be voted on.
+* *Accepted*: the proposal gained sufficient votes but is not yet executed.
+* *Executed*: the proposal was accepted and has been finalized on chain.
+
+## Vote
+
+### Participants
+
+*Participants* are users that have the right to vote on proposals. Participants
+are holders of governance tokens specified in the DAO.
+
+Note that only participants from before the proposal is submitted on chain
+are eligible to vote. That means receivers of governance tokens after a proposal is
+submitted will *not* be eligible to vote.
+
+There are currently two voting options:
+
+* Yes
+* No
+
+### Voting Period
+
+Once a proposal passes its duration, which is measured in days, participants can
+no longer vote on the proposal, and it is considered *expired*.
+
+### Quorum
+
+Quorum is defined as the minimum absolute number of governance tokens voting
+yes required for a proposal to become accepted.
+
+### Approval Ratio
+
+The approval ratio is defined as the minimum proportion of yes votes for the
+proposal to be accepted.
+

doc/src/spec2/contracts/dao/dao.md

@@ -2,10 +2,11 @@
 
 ## Abstract
 
-This contract enables on chain DAOs which can make arbitrary contract calls.
+This contract enables anonymous on chain DAOs which can make arbitrary contract calls.
 In this system, holders of the governance token specified by the DAO can
 make proposals which are then voted on. When proposals pass a specified
 threshold they are finalized, then the proposal can be executed.
 
 - [Concepts](concepts.md)
+- [State](state.md)
 

doc/src/spec2/contracts/dao/state.md

@@ -0,0 +1,21 @@
+# State
+
+## DAO
+
+Let $ℙₚ, 𝔽ₚ$ be defined as in the section [Pallas and Vesta](../../crypto-schemes.md#pallas-and-vesta).
+
+Define the DAO params
+$$ \begin{aligned}
+  \t{Params}_\t{DAO}.\t{L} &∈ ℕ₆₄ \\
+  \t{Params}_\t{DAO}.\t{Q} &∈ ℕ₆₄ \\
+  \t{Params}_\t{DAO}.\t{R}^\% &∈ ℕ₆₄ × ℕ₆₄ \\
+  \t{Params}_\t{DAO}.\t{T} &∈ 𝔽ₚ \\
+  \t{Params}_\t{DAO}.\t{PK} &∈ ℙₚ
+\end{aligned} $$
+where the approval ratio $\t{R}^\% = (q, d)$ is defines the equivalence
+class $[\frac{q}{d}]$ of fractions defined by $q₁d₂ = q₂d₁ ⟺  [\frac{q₁}{d₁}] \~ [\frac{q₂}{d₂}]$.
+
+```rust
+{{#include ../../../../../src/contract/dao/src/model.rs:dao}}
+```
+

doc/src/spec2/crypto-schemes.md

@@ -30,3 +30,29 @@ where $r ∈ 𝔽ₚ$ is a random blinding factor.
 Then the bulla (on chain anonymized representation) can be used in contracts
 with ZK proofs to construct statements on $\textrm{Params}$.
 
+## Pallas and Vesta
+
+DarkFi uses the elliptic curves Pallas and Vesta that form a 2-cycle.
+We denote Pallas by $ₚ$ and Vesta by $ᵥ$. Set the following values:
+
+$$ p = 0x40000000000000000000000000000000224698fc094cf91b992d30ed00000001 $$
+$$ q = 0x40000000000000000000000000000000224698fc0994a8dd8c46eb2100000001 $$
+
+We now construct the base field for each curve $Kₚ$ and $Kᵥ$ as
+$Kₚ = 𝔽ₚ$ and $Kᵥ = 𝔽_q$.
+Let $f = y² - (x² + 5) ∈ ℤ[x, y]$ be the Weierstrauss normal form of an elliptic curve.
+We define $fₚ = f \mod{Kₚ}$ and $fᵥ = f \mod{Kᵥ}$.
+Then we instantiate Pallas as $Eₚ = V(fₚ)$ and $Eᵥ = V(fᵥ)$. Now we note the
+2-cycle behaviour as
+
+$$ \#V(fₚ) = q $$
+$$ \#V(fᵥ) = p $$
+
+An additional projective point at infinity $∞$ is added to the curve.
+
+Let $ℙₚ$ be the group of points with $∞$ on $Eₚ$.
+
+Let $ℙᵥ$ be the group of points with $∞$ on $Eᵥ$.
+
+Arithmetic is mainly done in circuits with $𝔽ₚ$ and $Eₚ$.
+

doc/src/spec2/notation.md

@@ -0,0 +1,5 @@
+# Notation
+
+$ℕ$ denotes the non-negative integers. $ℕ₆₄$ denotes $ℕ$ restricted to the range
+corresponding to `u64` in Rust of $[0, 2⁶⁴)$.
+

src/contract/dao/src/model.rs

@@ -33,6 +33,7 @@ use darkfi_serial::async_trait;
 
 use darkfi_sdk::crypto::{ShareAddress, ShareAddressType};
 
+// ANCHOR: dao
 /// DAOs are represented on chain as a commitment to this object
 #[derive(Debug, Clone, SerialEncodable, SerialDecodable)]
 pub struct Dao {
@@ -44,6 +45,7 @@ pub struct Dao {
     pub public_key: PublicKey,
     pub bulla_blind: pallas::Base,
 }
+// ANCHOR_END: dao
 
 impl Dao {
     pub fn to_bulla(&self) -> DaoBulla {