diff --git a/README.md b/README.md index c668d5c..319fdb6 100644 --- a/README.md +++ b/README.md @@ -8,29 +8,53 @@ <br /> -## Dependencies +## Introduction +This repository contains the Cosmwasm implementation of **Webb Protocol**, which would be used for *Cosmos SDK* blockchains. + +## Contracts layout +``` +contracts/ + |___anchor/ # Anchor(FixedDepositAnchor) contract + |___anchor-handler/ # Contract for executing the creation & modification of anchor + |___mixer/ # Mixer contract + |___signature-bridge/ # Contract for managing voting, resource, and maintainer composition through signature verification + |___tokenwrapper/ # Contract for wrapping pooled assets and minting pool share tokens + |___tokenwrapper-handler/ # Contract for executing the creation & modification of token-wrapper + |___vanchor/ # Variable Anchor contract +``` + +## Building the contracts(wasm) + +### Prerequisites +#### Install Rust & dependency +Install the latest version of Rust by following the instructions [here](https://www.rust-lang.org/tools/install). Add the compilation target. ``` +rustup default stable rustup target add wasm32-unknown-unknown ``` -## Building +### Building To build the contract, run the following command. ``` cargo wasm ``` -You can see the output wasm file in the "target/wasm32-unknown-unknown/release" dir. +You can see the output wasm file in the **target/wasm32-unknown-unknown/release** directory. -For the optimization, run the following command. +For the optimization, run the following command. +**Important**: You will need [docker](https://www.docker.com/) installed to run this command. ``` -cargo run-script optimize +docker run --rm -v "$(pwd)":/code \ + --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ + --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ + cosmwasm/workspace-optimizer:0.12.5 ``` -Then, you can see the output wasm file in the "artifacts" directory. +Then, you can see the output wasm file in the **artifacts** directory. ## Testing -For running the unit tests(written on "src/contract.rs"), run the following command. +Run the following command to run the unit tests. ``` -cargo test +cargo test --release ``` ## License diff --git a/contracts/anchor-handler/README.md b/contracts/anchor-handler/README.md index 8492626..e73a760 100644 --- a/contracts/anchor-handler/README.md +++ b/contracts/anchor-handler/README.md @@ -1,3 +1,6 @@ # cosmwasm-anchor-handler This is the cosmwasm implementation of "anchor-handler" contract. + +This contract handles **Anchor edge list** & **merkle root updates**. +This contract is intended to be used with the **Bridge** contract. diff --git a/contracts/anchor-handler/rustfmt.toml b/contracts/anchor-handler/rustfmt.toml index 11a85e6..cbe6cbe 100644 --- a/contracts/anchor-handler/rustfmt.toml +++ b/contracts/anchor-handler/rustfmt.toml @@ -2,14 +2,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 - -# unstable... should we require `rustup run nightly cargo fmt` ? -# or just update the style guide when they are stable? -#fn_single_line = true -#format_code_in_doc_comments = true -#overflow_delimited_expr = true -#reorder_impl_items = true -#struct_field_align_threshold = 20 -#struct_lit_single_line = true -#report_todo = "Always" - diff --git a/contracts/anchor/README.md b/contracts/anchor/README.md index 55233ff..691eef9 100644 --- a/contracts/anchor/README.md +++ b/contracts/anchor/README.md @@ -1,3 +1,38 @@ -# cosmwasm-anchor +# comswasm_anchor(FixedDepositAnchor) -This is the cosmwasm implementation of "anchor" contract. \ No newline at end of file +This is the cosmwasm implementation of "anchor" contract. + +The **FixedDepositAnchor** system is an interoperable shielded pool supporting +fixed denomination deposits of CW20 tokens. + +The system is to be linked to other *FixedDepositAnchor*s through a simple +graph-like interface where anchors maintain edges of their neighboring anchors. + +The system requires users to both deposit a fixed denomination of CW20 assets +into the smart contract and insert a commitment into the underlying merkle tree +of the form: +``` +commitment = Poseidon(destinationChainId, nullifier, secret) +``` + +Commitments adhering to different hash functions and formats will invalidate +any attempt at withdrawal. + +Information regarding the commitments: + - **Poseidon** is a zkSNARK friendly hash function + - **destinationChainId** is the chainId of the destination chain, where + the withdrawal is intended to be made + - **nullifier** is a random field element and identifier for the deposit + that will be used to withdraw the deposit and ensure that the deposit + is not double withdrawn. + - **secret** is a random field element that will remain secret throughout + the lifetime of the deposit and withdrawal. + +Using the preimage of the commitment, users can generate a zkSNARK proof that +the deposit is located in one-of-many anchor merkle trees and that the commitment's +destination chain id matches the underlying chain id of the anchor where the +withdrawal is taking place. The chain id opcode is leveraged to prevent any +tampering of this data. + + +**NOTE**: For more information, please check the **Webb Protocol** documentation. diff --git a/contracts/anchor/rustfmt.toml b/contracts/anchor/rustfmt.toml index 11a85e6..d589bb2 100644 --- a/contracts/anchor/rustfmt.toml +++ b/contracts/anchor/rustfmt.toml @@ -3,13 +3,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 -# unstable... should we require `rustup run nightly cargo fmt` ? -# or just update the style guide when they are stable? -#fn_single_line = true -#format_code_in_doc_comments = true -#overflow_delimited_expr = true -#reorder_impl_items = true -#struct_field_align_threshold = 20 -#struct_lit_single_line = true -#report_todo = "Always" - diff --git a/contracts/mixer/rustfmt.toml b/contracts/mixer/rustfmt.toml index 11a85e6..cbe6cbe 100644 --- a/contracts/mixer/rustfmt.toml +++ b/contracts/mixer/rustfmt.toml @@ -2,14 +2,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 - -# unstable... should we require `rustup run nightly cargo fmt` ? -# or just update the style guide when they are stable? -#fn_single_line = true -#format_code_in_doc_comments = true -#overflow_delimited_expr = true -#reorder_impl_items = true -#struct_field_align_threshold = 20 -#struct_lit_single_line = true -#report_todo = "Always" - diff --git a/contracts/mixer/src/test_util.rs b/contracts/mixer/src/test_util.rs index 7840515..f24ef8a 100644 --- a/contracts/mixer/src/test_util.rs +++ b/contracts/mixer/src/test_util.rs @@ -1,6 +1,5 @@ use ark_bn254::Bn254; -use arkworks_native_gadgets::poseidon::Poseidon; -use arkworks_setups::common::{setup_params, Leaf, MixerProof}; +use arkworks_setups::common::Leaf; use arkworks_setups::r1cs::mixer::MixerR1CSProver; use arkworks_setups::Curve; use arkworks_setups::MixerProver; diff --git a/contracts/signature-bridge/README.md b/contracts/signature-bridge/README.md index 04fa6b1..69de19a 100644 --- a/contracts/signature-bridge/README.md +++ b/contracts/signature-bridge/README.md @@ -2,6 +2,4 @@ This is the cosmwasm implementation of "signature-bridge" contract. -Facilitates deposits, creation and voting of deposit proposals, and deposit executions. - -Author: ChainSafe Systems & Webb Technologies. \ No newline at end of file +This contract facilitates **deposits**, **creation and voting of deposit proposals**, and **deposit executions**. diff --git a/contracts/signature-bridge/rustfmt.toml b/contracts/signature-bridge/rustfmt.toml index 11a85e6..cbe6cbe 100644 --- a/contracts/signature-bridge/rustfmt.toml +++ b/contracts/signature-bridge/rustfmt.toml @@ -2,14 +2,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 - -# unstable... should we require `rustup run nightly cargo fmt` ? -# or just update the style guide when they are stable? -#fn_single_line = true -#format_code_in_doc_comments = true -#overflow_delimited_expr = true -#reorder_impl_items = true -#struct_field_align_threshold = 20 -#struct_lit_single_line = true -#report_todo = "Always" - diff --git a/contracts/tokenwrapper-handler/README.md b/contracts/tokenwrapper-handler/README.md index f542622..1287b60 100644 --- a/contracts/tokenwrapper-handler/README.md +++ b/contracts/tokenwrapper-handler/README.md @@ -1,3 +1,6 @@ # cosmwasm-tokenwrapper-handler This is the cosmwasm implementation of "tokenwrapper-handler" contract. + +This contract handles **GovernedTokenWrapper** **fee** and **token updates**. +This contract is intended to be used with the **Bridge** and **SignatureBridge** contracts. \ No newline at end of file diff --git a/contracts/tokenwrapper-handler/rustfmt.toml b/contracts/tokenwrapper-handler/rustfmt.toml index d589bb2..cbe6cbe 100644 --- a/contracts/tokenwrapper-handler/rustfmt.toml +++ b/contracts/tokenwrapper-handler/rustfmt.toml @@ -2,4 +2,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 - diff --git a/contracts/tokenwrapper/README.md b/contracts/tokenwrapper/README.md index 5523157..837b459 100644 --- a/contracts/tokenwrapper/README.md +++ b/contracts/tokenwrapper/README.md @@ -2,8 +2,13 @@ This is the cosmwasm implementation of "GovernedTokenWrapper" contract. -- A governed TokenWrapper system using an external `governor` address +Basically, this contract is a CW20 token that allows other CW20s to wrap into and mint it. -- Governs allowable CW20s to deposit using a governable wrapping limit and - sets fees for wrapping into itself. This contract is intended to be used with - TokenHandler contract. \ No newline at end of file +This contract is intended to be used with **TokenHandler** contract. + +This contract also has a **governance** functionality. + +- **Governed TokenWrapper** system using an external `governor` address + +- Governs allowable CW20s to deposit using a *governable wrapping limit* and + sets *fee*s for wrapping into itself. \ No newline at end of file diff --git a/contracts/tokenwrapper/rustfmt.toml b/contracts/tokenwrapper/rustfmt.toml index d589bb2..cbe6cbe 100644 --- a/contracts/tokenwrapper/rustfmt.toml +++ b/contracts/tokenwrapper/rustfmt.toml @@ -2,4 +2,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 - diff --git a/contracts/vanchor/README.md b/contracts/vanchor/README.md index 817dcba..2f99de7 100644 --- a/contracts/vanchor/README.md +++ b/contracts/vanchor/README.md @@ -2,33 +2,37 @@ ## Variable Anchor contract -The Variable Anchor is a variable-denominated shielded pool system -derived from Tornado Nova (tornado-pool). This system extends the shielded +The **Variable Anchor** is a variable-denominated shielded pool system +derived from *Tornado Nova (tornado-pool)*. This system extends the shielded pool system into a bridged system and allows for join/split transactions. -The system is built on top the Anchor/LinkableTree system which allows -it to be linked to other VAnchor contracts through a simple graph-like +The system is built on top the **Anchor/LinkableTree** system which allows +it to be linked to other **VAnchor** contracts through a simple graph-like interface where anchors maintain edges of their neighboring anchors. The system requires users to create and deposit UTXOs for the supported CW20 asset into the smart contract and insert a commitment into the underlying -merkle tree of the form: commitment = Poseidon(chainID, amount, pubKey, blinding). +merkle tree of the form: +``` +commitment = Poseidon(chainID, amount, pubKey, blinding) +``` + The hash input is the UTXO data. All deposits/withdrawals are unified under a common `transact` function which requires a zkSNARK proof that the UTXO commitments are well-formed (i.e. that the deposit amount matches the sum of new UTXOs' amounts). -Information regarding the commitments: -- Poseidon is a zkSNARK friendly hash function -- destinationChainID is the chainId of the destination chain, where the withdrawal +Information regarding the commitments: +- **Poseidon** is a zkSNARK friendly hash function +- **destinationChainID** is the chainId of the destination chain, where the withdrawal is intended to be made - Details of the UTXO and hashes are below -UTXO = { destinationChainID, amount, pubkey, blinding } -commitment = Poseidon(destinationChainID, amount, pubKey, blinding) -nullifier = Poseidon(commitment, merklePath, sign(privKey, commitment, merklePath)) +*UTXO* = { destinationChainID, amount, pubkey, blinding } +*commitment* = Poseidon(destinationChainID, amount, pubKey, blinding) +*nullifier* = Poseidon(commitment, merklePath, sign(privKey, commitment, merklePath)) Commitments adhering to different hash functions and formats will invalidate any attempt at withdrawal. Using the preimage / UTXO of the commitment, users can generate a zkSNARK proof that -the UTXO is located in one-of-many VAnchor merkle trees and that the commitment's -destination chain id matches the underlying chain id of the VAnchor where the +the UTXO is located in one-of-many **VAnchor merkle trees** and that the commitment's +*destination chain id* matches the underlying chain id of the **VAnchor** where the transaction is taking place. The chain id opcode is leveraged to prevent any tampering of this data. @@ -48,4 +52,4 @@ since it needs the `cw20` token transfer first & tx execution next. But, `transact-withdraw` does not need to be using `Send/Receive` mechanism, since there is no `cw20` token transfer before tx execution. Also, if we use `Send/Receive` mechanism for `transact-withdraw`, it always runs into error, since `amount` is always zero. -Reference: `https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md#messages` \ No newline at end of file +**Reference**: `https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md#messages` \ No newline at end of file diff --git a/contracts/vanchor/rustfmt.toml b/contracts/vanchor/rustfmt.toml index 11a85e6..cbe6cbe 100644 --- a/contracts/vanchor/rustfmt.toml +++ b/contracts/vanchor/rustfmt.toml @@ -2,14 +2,3 @@ newline_style = "unix" hard_tabs = false tab_spaces = 4 - -# unstable... should we require `rustup run nightly cargo fmt` ? -# or just update the style guide when they are stable? -#fn_single_line = true -#format_code_in_doc_comments = true -#overflow_delimited_expr = true -#reorder_impl_items = true -#struct_field_align_threshold = 20 -#struct_lit_single_line = true -#report_todo = "Always" - diff --git a/packages/README.md b/packages/README.md index f6d897e..95de4c5 100644 --- a/packages/README.md +++ b/packages/README.md @@ -1,6 +1,6 @@ # Protocol-cosmwasm types -This is a collection of common types that are used in "protocol-cosmwasm" contracts. -They include the InstantiateMsg, ExecuteMsg, and QueryMsg Api definitions for each contract, +This is a collection of common types that are used in **protocol-cosmwasm** contracts. +They include the *InstantiateMsg*, *ExecuteMsg*, and *QueryMsg* *Api definition*s for each contract, which are used to communicate among contracts. -They also include the common utils, which are used in many contracts. \ No newline at end of file +They also include the common utils, which are used among the contracts. \ No newline at end of file