Update the whole documentation (#49)

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

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.

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"
-

contracts/anchor/README.md

@@ -1,3 +1,38 @@
-# cosmwasm-anchor
+# comswasm_anchor(FixedDepositAnchor)
 
-This is the cosmwasm implementation of "anchor" contract.
+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.    

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"
-

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"
-

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;

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.
+This contract facilitates **deposits**, **creation and voting of deposit proposals**, and **deposit executions**.

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"
-

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.  

contracts/tokenwrapper-handler/rustfmt.toml

@@ -2,4 +2,3 @@
 newline_style = "unix"
 hard_tabs = false
 tab_spaces = 4
-

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.
+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.

contracts/tokenwrapper/rustfmt.toml

@@ -2,4 +2,3 @@
 newline_style = "unix"
 hard_tabs = false
 tab_spaces = 4
-

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`
+**Reference**: `https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md#messages`

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"
-

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.
+They also include the common utils, which are used among the contracts.