spec: money xfer params

doc/src/SUMMARY.md

@@ -83,7 +83,7 @@
     - [Concepts](spec/contract/dao/concepts.md)
     - [Model](spec/contract/dao/model.md)
     - [Scheme](spec/contract/dao/scheme.md)
-  - [Money]()
+  - [Money](spec/contract/money/money.md)
     - [Model](spec/contract/money/model.md)
     - [Scheme](spec/contract/money/scheme.md)
 

doc/src/spec/contract/money/model.md

@@ -39,3 +39,53 @@ $$ \begin{aligned}
 $$ \t{Coin} : \t{Attrs}_\t{Coin} → 𝔽ₚ $$
 $$ \t{Coin}(p) = \t{Bulla}(\mathcal{X}(p.\t{PK}), \mathcal{Y}(p.\t{PK}), ℕ₆₄2𝔽ₚ(p.v), p.τ, p.ζ, p.\t{SH}, p.\t{UD}) $$
 
+## Inputs and Outputs
+
+### Clear Input
+
+Define the clear input attributes
+$$ \begin{aligned}
+  \t{MoneyClearInput}.v &∈ ℕ₆₄ \\
+  \t{MoneyClearInput}.T &∈ ℙₚ \\
+  \t{MoneyClearInput}.v_\t{blind} &∈ 𝔽_q \\
+  \t{MoneyClearInput}.t_\t{blind} &∈ 𝔽ₚ \\
+  \t{MoneyClearInput}.Z &∈ ℙₚ \\
+\end{aligned} $$
+
+```rust
+{{#include ../../../../../src/contract/money/src/model.rs:money-clear-input}}
+```
+
+### Input
+
+Define the input attributes
+$$ \begin{aligned}
+  \t{MoneyInput}.V &∈ ℙₚ \\
+  \t{MoneyInput}.T &∈ 𝔽ₚ \\
+  \t{MoneyInput}.N &∈ 𝔽ₚ \\
+  \t{MoneyInput}.R &∈ 𝔽ₚ \\
+  \t{MoneyInput}.h &∈ 𝔽ₚ \\
+  \t{MoneyInput}.U &∈ 𝔽ₚ \\
+  \t{MoneyInput}.Z &∈ ℙₚ \\
+\end{aligned} $$
+
+```rust
+{{#include ../../../../../src/contract/money/src/model.rs:money-input}}
+```
+
+### Output
+
+Let $\t{AeadEncNote}$ be defined as in [In-band Secret Distribution](../../crypto-schemes.md#in-band-secret-distribution).
+
+Define the output attributes
+$$ \begin{aligned}
+  \t{MoneyOutput}.V &∈ ℙₚ \\
+  \t{MoneyOutput}.T &∈ 𝔽ₚ \\
+  \t{MoneyOutput}.C &∈ 𝔽ₚ \\
+  \t{MoneyOutput}.\t{note} &∈ \t{AeadEncNote} \\
+\end{aligned} $$
+
+```rust
+{{#include ../../../../../src/contract/money/src/model.rs:money-output}}
+```
+

doc/src/spec/contract/money/money.md

@@ -0,0 +1,16 @@
+# DAO
+
+## Abstract
+
+The _Money_ contract implements network fees, token transfers,
+atomic swaps, token minting and freezing, and staking/unstaking of
+PoS consensus tokens.
+
+The functions/entrypoints provided by this smart contract are:
+```rust
+{{#include ../../../../../src/contract/money/src/lib.rs:money-function}}
+```
+
+- [Model](model.md)
+- [Scheme](scheme.md)
+

doc/src/spec/contract/money/scheme.md

@@ -1,19 +1,42 @@
-# Money Contract Specification
-
-The _Money_ contract implements network fees, token transfers,
-atomic swaps, token minting and freezing, and staking/unstaking of
-PoS consensus tokens.
-
-The functions/entrypoints provided by this smart contract are:
-```rust
-{{#include ../../../../../src/contract/money/src/lib.rs:money-function}}
-```
-
-## `MoneyFunction::TransferV1`
+# Scheme
 
 Let $\t{PoseidonHash}$ be defined as in the section [PoseidonHash Function](../../crypto-schemes.md#poseidonhash-function).
 
-### ZK proofs
+## Transfer
+
+This function transfers value by burning a set of coins $𝐂$, and minting a
+set of coins, such that the value spent and created are equal.
+
+* Wallet:
+  * Builder: `src/contract/money/src/client/transfer_v1/builder.rs`
+  * Convenience methods: `src/contract/money/src/client/transfer_v1/mod.rs`
+  * Build proofs: `src/contract/money/src/client/transfer_v1/proof.rs`
+* WASM VM code: `src/contract/money/src/entrypoint/transfer_v1.rs`
+* ZK proofs:
+  * `src/contract/money/proof/burn_v1.zk`
+  * `src/contract/money/proof/mint_v1.zk`
+
+### Function Params
+
+Let $\t{MoneyClearInput}, \t{MoneyInput}, \t{MoneyOutput}$
+be defined as in [Inputs and Outputs](model.md#inputs-and-outputs).
+
+Define the Money transfer function params
+$$ \begin{aligned}
+  𝐣 &∈ \t{MoneyClearInput}^* \\
+  𝐢 &∈ \t{MoneyInput}^* \\
+  𝐨 &∈ \t{MoneyOutput}^*
+\end{aligned} $$
+
+```rust
+{{#include ../../../../../src/contract/money/src/model.rs:money-params}}
+```
+
+### Contract Statement
+
+Let $π_\t{mint}, π_\t{burn}$ be defined as in [ZK Proofs](#zk-proofs).
+
+### ZK Proofs
 
 #### `Mint_V1`
 
@@ -22,6 +45,8 @@ in our UTXO set. It is used along with the `Burn_V1` circuit in
 `MoneyFunction::TransferV1` where we perform a payment to some address
 on the network.
 
+Denote this proof by $π_\t{mint}$.
+
 **Circuit witnesses:**
 
 * $P$ - Public key of the recipient which goes into the coin commitment (pallas curve point)
@@ -30,8 +55,8 @@ on the network.
 * $s$ - Unique serial number of the coin commitment (pallas base field element)
 * $h$ - Spend hook, allows composing this ZK proof to invoke other contracts (pallas base field element)
 * $u$ - Data passed from this coin to the invoked contract (pallas base field element)
-* $v_{\text{blind}}$ - Random blinding factor for a Pedersen commitment to $v$ (pallas scalar field element)
-* $t_{\text{blind}}$ - Random blinding factor for a commitment to $t$ (pallas base field element)
+* $v_\t{blind}$ - Random blinding factor for a Pedersen commitment to $v$ (pallas scalar field element)
+* $t_\t{blind}$ - Random blinding factor for a commitment to $t$ (pallas base field element)
 
 **Circuit public inputs:**
 
@@ -60,6 +85,8 @@ our UTXO set. It is used along with the `Mint_V1` circuit in
 `MoneyFunction::TransferV1` where we perform a payment to some address
 on the network.
 
+Denote this proof by $π_\t{burn}$.
+
 **Circuit witnesses:**
 
 * $v$ - Value of the coin being spent (unsigned 64-bit integer)
@@ -106,7 +133,7 @@ generator in the codebase known as `NULLIFIER_K`:
 We use this because the Merkle tree is instantiated with a fake coin of
 value 0 and so we're able to produce dummy inputs of value 0.
 
-## Contract call creation
+### Contract call creation
 
 Assuming a coin $C$ exists on the blockchain on leaf position $l$ and
 does not have a corresponding published nullifier $N$, it can be spent.
@@ -151,7 +178,7 @@ This gets encoded into the `Transaction` format and the transaction is
 signed with a Schnorr signature scheme using the $z$ secret key chosen
 in `Burn_V1`.
 
-## Contract call execution
+### Contract call execution
 
 For `MoneyFunction::TransferV1`, we have the following functions, in
 order:

doc/src/spec/notation.md

@@ -1,5 +1,8 @@
 # Notation
 
+We use superscript$^*$ to denote an arbitrary length ordered array, usually
+corresponding to the `Vec` type in Rust.
+
 $ℕ$ denotes the non-negative integers. $ℕ₆₄$ denotes $ℕ$ restricted to the range
 corresponding to `u64` in Rust of $[0, 2⁶⁴)$.
 

src/contract/money/src/model.rs

@@ -106,8 +106,9 @@ impl NullifierAttributes {
     }
 }
 
-/// A contract call's clear input
 #[derive(Clone, Debug, SerialEncodable, SerialDecodable)]
+// ANCHOR: money-clear-input
+/// A contract call's clear input
 pub struct ClearInput {
     /// Input's value (amount)
     pub value: u64,
@@ -120,9 +121,11 @@ pub struct ClearInput {
     /// Public key for the signature
     pub signature_public: PublicKey,
 }
+// ANCHOR_END: money-clear-input
 
-/// A contract call's anonymous input
 #[derive(Clone, Debug, PartialEq, SerialEncodable, SerialDecodable)]
+// ANCHOR: money-input
+/// A contract call's anonymous input
 pub struct Input {
     /// Pedersen commitment for the input's value
     pub value_commit: pallas::Point,
@@ -143,6 +146,22 @@ pub struct Input {
     /// Public key for the signature
     pub signature_public: PublicKey,
 }
+// ANCHOR_END: money-input
+
+#[derive(Clone, Debug, PartialEq, SerialEncodable, SerialDecodable)]
+// ANCHOR: money-output
+/// A contract call's anonymous output
+pub struct Output {
+    /// Pedersen commitment for the output's value
+    pub value_commit: pallas::Point,
+    /// Commitment for the output's token ID
+    pub token_commit: pallas::Base,
+    /// Minted coin
+    pub coin: Coin,
+    /// AEAD encrypted note
+    pub note: AeadEncryptedNote,
+}
+// ANCHOR_END: money-output
 
 /// Anonymous input for consensus contract calls
 #[derive(Clone, Debug, PartialEq, SerialEncodable, SerialDecodable)]
@@ -159,19 +178,6 @@ pub struct ConsensusInput {
     pub signature_public: PublicKey,
 }
 
-/// A contract call's anonymous output
-#[derive(Clone, Debug, PartialEq, SerialEncodable, SerialDecodable)]
-pub struct Output {
-    /// Pedersen commitment for the output's value
-    pub value_commit: pallas::Point,
-    /// Commitment for the output's token ID
-    pub token_commit: pallas::Base,
-    /// Minted coin
-    pub coin: Coin,
-    /// AEAD encrypted note
-    pub note: AeadEncryptedNote,
-}
-
 /// A consensus contract call's anonymous output
 #[derive(Clone, Debug, PartialEq, SerialEncodable, SerialDecodable)]
 pub struct ConsensusOutput {