comments

README.md

@@ -1,24 +1,45 @@
 # Carrot App
 
-Carrot-App is a CosmWasm smart contract/module that demonstrates the use of the abstract stack. It allows users to autocompound rewards from providing to supercharged liquidity pools on Osmosis. The smart contract enables users to create a position in the liquidity pool, automatically withdraw rewards, and compound them.
+Carrot-App is a CosmWasm smart contract/module that demonstrates the use of the abstract stack.
+The carrot-app is useful because it allows investors to maximize the yield they earn from their assets. It should allow investors to make different strategies like creating USDC/USDT positions or lend stable coins and earn yield from that. Of course investors can do this manually, hence bypassing the need for such carrot-app contract, however using this contract allows a recurrent autocompounding handled by an external bot and, more importantly, from a developer perspective, it abstracts away the need to think about what underlying dex or lending platform the investor will be using.
+The current version V1 of the carrot-app allows users to autocompound rewards from providing to supercharged liquidity pools on Osmosis but more DEXes will be supported in the future. The smart contract enables users to create a position in the liquidity pool, automatically withdraw rewards, and compound them. In V2, the carrot-app will allow more yield strategies like lending.
+This contract does not hold custody of the funds, instead it gets the authz permissions from a user or an abstract account to act on their behalf.
+
+## Agents involved:
+
+- Carrot app developer: develops, maintains this contract and publishes it to Abstract [repo](https://github.com/AbstractSDK/abstract/tree/main/modules/contracts/apps)
+- Investor/user: Installs this app on their abstract account and deposit some funds that they want to get yield from.
+- Bot: Autcompounds the position of all investors to earn incentives.
+- Abstract developer: Develops the tooling that the carrot-app developer needs to make their life easier.
 
 ## Features
-* Create a position in the liquidity pool
-* Deposit funds into the pool
-* Withdraw a specified amount or all funds
-* Autocompound rewards
+
+- Create a position in the liquidity pool
+- Deposit funds into the pool
+- Withdraw a specified amount or all funds
+- Autocompound rewards
+
 ## Entrypoints
+
+### Instantiation
+
+During the contract
+
 ### Execute Messages
-* CreatePosition: Creates a position in the liquidity pool
-* Deposit: Deposits funds into the pool
-* Withdraw: Withdraws a specified amount of funds from the pool
-* WithdrawAll: Withdraws all funds from the pool
-* Autocompound: Autocompounds rewards
+
+- CreatePosition: Creates a position in the liquidity pool, the liquidity pool id is set during the contract instantiation.
+- Deposit: Deposits funds into the pool
+- Withdraw: Withdraws a specified amount of funds from the pool
+- WithdrawAll: Withdraws all funds from the pool
+- Autocompound: Autocompounds rewards
+
 ### Query Messages
-* Balance: Returns the current balance in the pool
-* AvailableRewards: Returns the available rewards to be claimed
-* Config: Returns the current configuration of the contract
-* Position: Returns information about the user's position in the pool
-* CompoundStatus: Returns the current autocompound status (cooldown or ready)
+
+- Balance: Returns the current balance in the pool
+- Config: Returns the current configuration of the contract
+- Position: Returns information about the user's position in the pool
+- CompoundStatus: Returns the current autocompound status (cooldown or ready) and available rewards to be claimed
+
 ## Bot
+
 The repository also includes a bot that interacts with the Carrot-App contract. The bot fetches contract instances, checks permissions, and autocompounds rewards.

contracts/carrot-app/src/msg.rs

@@ -10,7 +10,7 @@ use crate::{
 // This is used for type safety and re-exporting the contract endpoint structs.
 abstract_app::app_msg_types!(App, AppExecuteMsg, AppQueryMsg);
 
-/// App instantiate message
+/// Carrot app instantiate message
 #[cosmwasm_schema::cw_serde]
 pub struct AppInstantiateMsg {
     /// Id of the pool used to get rewards
@@ -39,29 +39,45 @@ pub struct CreatePositionMessage {
     pub belief_price1: Option<Decimal>,
 }
 
-/// App execute messages
+/// Carrot app execute messages
 #[cosmwasm_schema::cw_serde]
 #[cfg_attr(feature = "interface", derive(cw_orch::ExecuteFns))]
 #[cfg_attr(feature = "interface", impl_into(ExecuteMsg))]
 pub enum AppExecuteMsg {
-    /// Create the initial liquidity position
+    /// Create a position for a supercharged liquidity pool
+    /// Example: A user wants to create a liquidity position with 1000USDC and 1000USDT within a specifc range
+    /// This method is Permissioned
     CreatePosition(CreatePositionMessage),
-    /// Deposit funds onto the app
+    /// This adds funds to an already existing position
+    /// Example: A user who has already a position with 1000USDC and 1000USDT would like to add 200USDC and 200USDT
+    /// This method is Permissioned
     Deposit {
         funds: Vec<Coin>,
         max_spread: Option<Decimal>,
         belief_price0: Option<Decimal>,
         belief_price1: Option<Decimal>,
     },
-    /// Partial withdraw of the funds available on the app
+    /// Withdraw a share from the LP position
+    /// Example: A user who has already a position with 1000USDC and 1000USDT would like to withdraw 200USDC and 200USDT
+    /// Note: This will not claim the rewards earned from the swapping fees generated by the position
+    /// This method is Permissioned
     Withdraw { amount: Uint128 },
-    /// Withdraw everything that is on the app
+    /// Withdraw all the amount in the position
+    /// Example: A user who has already a position with 1000USDC and 1000USDT would like to withdraw all the funds
+    /// Note: This will claim the rewards earned from the swapping fees generated by the position
+    /// This function is Permissioned
     WithdrawAll {},
-    /// Auto-compounds the pool rewards into the pool
+    /// For a user who has already created a position, this function does two steps:
+    /// 1 - claims all the rewards generated by the position
+    /// 2 - adds/deposits the claimed spread rewards to that same position
+    /// This is meant to be called by a carrot-app bot, that receives rewards upon autocompounding.
+    /// Executor will receive rewards specified in [`CompoundStatusResponse::autocompound_reward`].
+    /// Rewards won't be sent in case [`CompoundStatus`] is not ready or executor is admin of the contract.
+    /// This function is not Permissioned
     Autocompound {},
 }
 
-/// App query messages
+/// Carrot app query messages
 #[cosmwasm_schema::cw_serde]
 #[cfg_attr(feature = "interface", derive(cw_orch::QueryFns))]
 #[cfg_attr(feature = "interface", impl_into(QueryMsg))]