172 improve documentation add readme files

contracts/factory/README.md

@@ -0,0 +1,88 @@
+# Dex Factory
+
+## Main functionality
+
+The main purpose of the factory contract is to provide the tooling required for managing, creating, querying of liquidity pools.
+
+## Messages
+
+`initialize`
+
+Params:
+- `admin`: `Address` of the contract administrator to be
+- `multihop_wasm_hash`: `BytesN<32>` hash of the multihop contract to be deployed initially
+
+<hr>
+
+`create_liquidity_pool`
+
+Params:
+- `lp_init_info`: `LiquidityPoolInitInfo` struct representing information for the new liquidity pool
+
+Return type:
+`Address` of the newly created liquidity pool
+
+Description:
+
+Creates a new liquidity pool with 'LiquidityPoolInitInfo'. After deployment of the liquidity pool it updates the liquidity pool list.
+
+<hr>
+
+`query_pools`
+
+Return type:
+`Vec<Address>` of all the liquidity pools created by the factory
+
+Description:
+Queries for a list of all the liquidity pool addresses that have been created by the called factory contract.
+
+<hr>
+
+`query_pool_details`
+
+Params:
+- `pool_address`: `Address` of the liquidity pool we search for
+
+Return type:
+Struct `LiquidityPoolInfo` containing the information about a given liquidity pool.
+
+Description:
+Queries for specific liquidity pool information that has been created by the called factory contract.
+
+<hr>
+
+`query_all_pools_details`
+
+Return type:
+`Vec<LiquidityPoolInfo>` list of structs containing the information about all liquidity pools created by the factory.
+
+Description:
+Queries for all liquidity pools information that have been created by the called factory contract.
+
+<hr>
+
+`query_for_pool_by_token_pair(env: Env, token_a: Address, token_b: Address)`;
+
+Params:
+- token_a: `Address` of the first token in the pool
+- token_b: `Address` of the second token in the pool
+
+Return type:
+`Address` of the found liquidity pool that holds the given token pair.
+
+Description:
+Queries for a liquidity pool address by the tokens of that pool.
+
+<hr>
+
+`get_admin`
+
+Return type:
+`Address` of the admin for the called factory.
+
+<hr>
+
+`get_config`
+
+Return type:
+Struct `Config` of the called factory.

contracts/multihop/README.md

@@ -0,0 +1,81 @@
+# Dex Multihop
+
+## Main functionality
+The main purpose of the multihop contract is to provide the ability of the users to swap tokens between multiple liquidity pools.
+
+
+
+## Messages:
+`initialize`
+
+Params:
+
+- `admin`: `Address` of the contract administrator to be
+- `factory`: `Address` of the factory contract to be deployed initially
+
+Return type:
+void
+
+Description:
+Used for the initialization of the multihop contract - this sets the multihop contract as initialized, stores the admin and factory address in the Config struct
+
+<hr>
+
+`swap`
+
+Params:
+
+- `recipient`: `Address` of the contract that will receive the amount swapped.
+- `referral`: `Option<Address>` of the referral, that will get a referral commission bonus for the swap.
+- `operations`: `Vec<Swap>` that holds both the addresses of the asked and offer assets.
+- `max_belief_price`: `Option<i64>` value for the maximum believe price that will be used for the swaps.
+- `max_spread_bps`: `Option<i64>` maximum permitted difference between the asked and offered price in BPS.
+- `amount`: `i128` value representing the amount offered for swap
+
+Return type:
+void
+
+Description:
+Takes a list of `Swap` operations between the different pools and iterates over them, swapping the tokens in question by calling the pool contract.
+
+<hr>
+
+`simulate_swap`
+Params:
+
+- `operations`: `Vec<Swap>`holding the addresses of the asked and offer assets
+- `amount`: `i128` value representing the amount that should be swapped
+
+Return type:
+`SimulateSwapResponse` containing the details of the swap
+
+Description:
+Dry runs a swap operation. This is useful when we want to display some additional information such as pool commission fee, slippage tolerance and expected returned values from the swap in question.
+
+<hr>
+
+`simulate_reverse_swap`
+
+Params:
+
+- `operations`: `Vec<Swap>` holding the addresses of the asked and offer assets
+- `amount`: `i128` value representing the amount that should be swapped
+
+Return type:
+`SimulateReverseSwapResponse` containing the details of the same swap but in reverse
+
+Description:
+Dry runs a swap operation but in reverse. This is useful when we want to display some additional information such as pool commission fee, slippage tolerance and expected returned values from the reversed swap in question.
+
+<hr>
+
+`get_admin`
+Params:
+
+* None
+
+Return type:
+`Address` of the admin for the current Multihop contract.
+
+Description:
+Queries for the admin address of the current multihop contract.

contracts/pool/README.md

@@ -0,0 +1,201 @@
+# Dex Pool
+
+## Main functionality
+This is one of the DEX's core contracts. It's main purpose is to facilitate the provision and withdrawal of liquidity, swapping assets and simulating assets swap, all this by using the XYK model.
+
+## Messages:
+`initialize`
+
+Params:
+- `admin`: `Address` of the contract administrator to be.
+- `share_token_decimals`: `u32` value for the number of decimals to be used for the given contract.
+- `swap_fee_bps`: `i64` value for the comission fee for the network in the given liquidity pool.
+- `fee_recipient`: `Address` that will receive the aforementioned fee.
+- `max_allowed_slippage_bps`: `i64` value for the maximum allowed slippage for a swap, set in BPS.
+- `max_allowed_spread_bps`: `i64` value for the maximum allowed difference between the price at the current moment and the price on which the users agree to sell. Measured in BPS.
+- `max_referral_bps`: `i64` value for maximum allowed referral commission measured in BPS.
+- `token_init_info`: `TokenInitInfo` struct containing information for the initialization of one of the two tokens in the pool.
+- `stake_contract_info`: `StakeInitInfo` struct containing information for the initialization of the stake contract for the given liquidity pool.
+
+Return type:
+void
+
+Description:
+Used for the initialization of the liquidity pool contract - this sets the admin in Config, initializes both token contracts, that will be in the pool and also initializes the staking contract needed for providing liquidity.
+
+<hr>
+
+`provide_liquidity`
+
+Params:
+- `depositor`: `Address` of the ledger calling the current method and providing liqudity for the pool
+- `desired_a`: Optional `i128` value for amount of the first asset that the depositor wants to provide in the pool.
+- `min_a`: Optional `i128` value for minimum amount of the first asset that the depositor wants to provide in the pool.
+- `desired_b`: Optional `i128` value for amount of the second asset that the depositor wants to provide in the pool.
+- `min_b`: Optional `i128` value for minimum amount of the second asset that the depositor wants to provide in the pool.
+- `custom_slippage_bps`: Optional `i64` value for amount measured in BPS for the slippage tolerance.
+
+Return type:
+void
+
+Description:
+Allows the users to deposit optional pairs of tokens in the pool and receive awards in return. The awards are calculated based on the amount of assets deposited in the pool.
+
+<hr>
+
+`swap`
+
+Params:
+- `sender`: `Address` of the user that requests the swap.
+- `referral`: Optional value for a Struct `Referral` for the ledger that will receive commission from this swap. `Referral` contains from an address of the referral and its commission fee.
+- `offer_asset`: `Address` for the asset the user wants to swap.
+- `offer_amount`: `i128` amount that the user wants to swap.
+- `belief_price`: Optional `i64` value that represents that users belived/expected price per token.
+- `max_spread_bps`: Optional `i64` value representing maximum allowed spread/slippage for the swap.
+
+Return type:
+i128
+
+Description:
+Changes one asset for another in the pool.
+
+<hr>
+
+`withdraw_liquidity`
+
+Params:
+- `recipient`: `Address` that will receive the withdrawn liquidity.
+- `share_amount`: `i128` amount of shares that the user will remove from the liquidity pool.
+- `min_a`: `i128` amount of the first token.
+- `min_b`: `i128` amount of the second token.
+
+Return type:
+(i128, i128) tuple of the amount of the first and second token to be sent back to the user.
+
+Description:
+Allows for users to withdraw their liquidity out of a pool, forcing them to burn their share tokens in the given pool, before they can get the assets back.
+
+<hr>
+
+`update_config`
+
+Params:
+- `sender`: `Address` of sender that wants to update the `Config`
+- `new_admin`: Optional `Address` of the new admin for liquidity pool
+- `total_fee_bps`: Optional `i64` value for the total fees (in bps) charged by the pool
+- `fee_recipient`: Optional `Address` for the recipient of the swap commission fee
+- `max_allowed_slippage_bps`: Optional `i64` value the maximum allowed slippage for a swap, set in BPS.
+- `max_allowed_spread_bps`: Optional `i64` value for maximum allowed difference between the price at the current moment and the price on which the users agree to sell. Measured in BPS.
+
+Return type:
+void
+
+Description:
+Updates the liquidity pool `Config` information with new one.
+
+<hr>
+
+`upgrade`
+
+Params:
+- `new_wasm_hash`: `WASM hash` of the new liquidity pool contract
+
+Return type:
+void
+
+Description:
+Migration entrypoint
+
+<hr>
+
+## Queries:
+`query_config`
+
+Params:
+`None`
+
+Return type:
+`Config` struct.
+
+Description:
+Queries the contract `Config` 
+
+<hr>
+
+`query_share_token_address`
+
+Params:
+`None`
+
+Return type:`
+`Address` of the pool's share token.
+
+Description:
+Returns the address for the pool share token.
+
+<hr>
+
+`query_stake_contract_address`
+
+Params:
+`None`
+
+Return type:
+`Address` of the pool's stake contract.
+
+Description:
+Returns the address for the pool stake contract. 
+
+<hr>
+
+`query_pool_info`
+
+Params
+`None`
+
+Return type:
+`PoolResponse` struct represented by two token assets and share token.
+
+Description:
+Returns  the total amount of LP tokens and assets in a specific pool. 
+
+<hr>
+
+`query_pool_info_for_factory`
+
+Params:
+`None`
+
+Return type:
+`LiquidityPoolInfo` struct representing information relevant for the liquidity pool.
+
+Description:
+Returns all the required information for a liquidity pool that is called by the factory contract. 
+
+<hr>
+
+
+`simulate_swap`
+
+Params:
+- `offer_asset`: `Address` of the token that the user wants to sell.
+- `sell_amount`: `i128` value for the total amount that the user wants to sell.
+
+Return type:
+`SimulateSwapResponse` struct represented by `ask_amount: i128`, `commission_amount: i128`, `spread_amount: i128` and `total_return: i128`.
+
+Description:
+Simulate swap transaction. 
+<hr>
+
+`simulate_reverse_swap`
+
+Params:
+- `ask_asset`: `Address` of the token that the user wants to buy.
+- `ask_amount`: `i128` value for the total amount that the user wants to buy.
+
+Return type:
+`SimulateReverseSwapResponse` struct represented by `offer_amount: i128`, `commission_amount: i128` and `spread_amount: i128`.
+
+Description:
+Simulate reverse swap transaction.