spec2: add section on crypto schemes

doc/src/SUMMARY.md

@@ -111,6 +111,10 @@
 # Specs
 
 - [Concepts](spec2/concepts.md)
+- [Cryptographic Schemes](spec2/crypto-schemes.md)
+- [Contracts]()
+  - [DAO](spec2/contracts/dao/dao.md)
+    - [DAO](spec2/contracts/dao/concepts.md)
 
 # P2P API Tutorial
 

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

@@ -0,0 +1,2 @@
+# Concepts
+

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

@@ -0,0 +1,11 @@
+# DAO
+
+## Abstract
+
+This contract enables 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)
+

doc/src/spec2/crypto-schemes.md

@@ -0,0 +1,32 @@
+# Cryptographic Schemes
+
+## `PoseidonHash` Function
+
+Poseidon is a circuit friendly permutation hash function described in
+the paper GKRRS2019.
+
+| Parameter         | Setting                        |
+|-------------------|--------------------------------|
+| S-box             | $x → x⁵$                       |
+| Full rounds       | 8                              |
+| Partial rounds    | 56                             |
+
+Our usage matches that of the halo2 library. Namely using a sponge configuration
+with addition which defines the function
+$$\textrm{PoseidonHash} : 𝔽ₚ × ⋯ × 𝔽ₚ → 𝔽ₚ$$
+
+## Bulla Commitments
+
+Given an abstract hash function such as [`PoseidonHash`](#poseidonhash-function),
+we use a variant of the commit-and-reveal scheme to define anonymized
+representations of objects on chain. Contracts then operate with these anonymous
+representations which we call bullas.
+
+Let $\textrm{Params} ∈ 𝔽ₚⁿ$ represent object parameters, then we can define
+$$ \textrm{Bulla} : 𝔽ₚⁿ × 𝔽ₚ → 𝔽ₚ $$
+$$ \textrm{Bulla}(\textrm{Params}, r) = \textrm{PoseidonHash}(\textrm{Params}, r) $$
+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}$.
+

src/sdk/src/crypto/util.rs

@@ -42,6 +42,11 @@ pub fn mod_r_p(x: pallas::Base) -> pallas::Scalar {
 
 /// Wrapper around poseidon in `halo2_gadgets`
 pub fn poseidon_hash<const N: usize>(messages: [pallas::Base; N]) -> pallas::Base {
+    // TODO: it's possible to make this function simply take a slice, by using the lower level
+    // sponge defined in halo2 lib. Simply look how the function hash() is defined.
+    // Why is this needed? Simply put we are often working with dynamic data such as Python
+    // or with other interpreted environments. We don't always know the length of input data
+    // at compile time.
     poseidon::Hash::<_, poseidon::P128Pow5T3, poseidon::ConstantLength<N>, 3, 2>::init()
         .hash(messages)
 }