From 43621729fe6eb730afd9495925c405e40ef3664e Mon Sep 17 00:00:00 2001 From: zero Date: Mon, 29 Jan 2024 11:10:50 +0100 Subject: [PATCH] spec: money xfer params --- doc/src/SUMMARY.md | 2 +- doc/src/spec/contract/money/model.md | 50 ++++++++++++++++++++++ doc/src/spec/contract/money/money.md | 16 +++++++ doc/src/spec/contract/money/scheme.md | 61 +++++++++++++++++++-------- doc/src/spec/notation.md | 3 ++ src/contract/money/src/model.rs | 36 +++++++++------- 6 files changed, 135 insertions(+), 33 deletions(-) create mode 100644 doc/src/spec/contract/money/money.md diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 5fa1d4b2c..bdc1f9c3b 100644 --- a/doc/src/SUMMARY.md +++ b/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) diff --git a/doc/src/spec/contract/money/model.md b/doc/src/spec/contract/money/model.md index 5cfb5a7cb..99f926851 100644 --- a/doc/src/spec/contract/money/model.md +++ b/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}} +``` + diff --git a/doc/src/spec/contract/money/money.md b/doc/src/spec/contract/money/money.md new file mode 100644 index 000000000..d9f794e43 --- /dev/null +++ b/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) + diff --git a/doc/src/spec/contract/money/scheme.md b/doc/src/spec/contract/money/scheme.md index baa01f309..d1cb95a5b 100644 --- a/doc/src/spec/contract/money/scheme.md +++ b/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: diff --git a/doc/src/spec/notation.md b/doc/src/spec/notation.md index 14a72ea8b..b40e25fce 100644 --- a/doc/src/spec/notation.md +++ b/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⁢⁴)$. diff --git a/src/contract/money/src/model.rs b/src/contract/money/src/model.rs index 3678403db..5619f844a 100644 --- a/src/contract/money/src/model.rs +++ b/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 {