cover dex stargate helpers with comments

packages/neutron-sdk/src/stargate/dex/msg.rs

@@ -16,29 +16,43 @@ const WITHDRAW_FILLED_LIMIT_ORDER_MSG_PATH: &str = "/neutron.dex.MsgWithdrawFill
 const CANCEL_LIMIT_ORDER_MSG_PATH: &str = "/neutron.dex.MsgCancelLimitOrder";
 const MULTI_HOP_SWAP_MSG_PATH: &str = "/neutron.dex.MsgMultiHopSwap";
 
+/// Provides liquidity to a specific trading pair by depositing tokens at a specific price into one
+/// or both sides of the pair in “a liquidity pool”.
 pub fn msg_deposit(req: DepositRequest) -> CosmosMsg {
     create_stargate_msg(MsgDeposit::from(req), DEPOSIT_MSG_PATH)
 }
 
+/// Redeems PoolShares for the user’s pro-rata portion of tokens within a liquidity pool. When
+/// withdrawing from a pool they will receive token_a and token_b in the same ratio as what is
+/// currently present in the pool.
 pub fn msg_withdrawal(req: WithdrawalRequest) -> CosmosMsg {
     create_stargate_msg(MsgWithdrawal::from(req), WITHDRAWAL_MSG_PATH)
 }
 
+/// Provides new liquidity to the dex that can be swapped through by other traders.
 pub fn msg_place_limit_order(req: PlaceLimitOrderRequest) -> CosmosMsg {
     create_stargate_msg(MsgPlaceLimitOrder::from(req), PLACE_LIMIT_ORDER_MSG_PATH)
 }
 
+/// Withdraws all available credits from an either partially or entirely fulfilled limit order.
 pub fn msg_withdraw_filled_limit_order(req: WithdrawFilledLimitOrderRequest) -> CosmosMsg {
     create_stargate_msg(
         MsgWithdrawFilledLimitOrder::from(req),
         WITHDRAW_FILLED_LIMIT_ORDER_MSG_PATH,
     )
 }
 
+/// Cancels a standard taker limit order (Good-til-cancelled | Good-til-time) if it has not been
+/// completely filled. Once a limit order is canceled any remaining “TokenIn” liquidity is returned
+/// to the user.
+///
+/// NOTE: Cancelling a partially filled limit order does not withdraw the traded portion. A separate
+/// call must be made to `WithdrawFilledLimitOrder` to withdraw any proceeds from the limit order.
 pub fn msg_cancel_limit_order(req: CancelLimitOrderRequest) -> CosmosMsg {
     create_stargate_msg(MsgCancelLimitOrder::from(req), CANCEL_LIMIT_ORDER_MSG_PATH)
 }
 
+/// Swaps by routing through a series of pools to achieve better prices.
 pub fn msg_multi_hop_swap(req: MultiHopSwapRequest) -> CosmosMsg {
     create_stargate_msg(MsgMultiHopSwap::from(req), MULTI_HOP_SWAP_MSG_PATH)
 }

packages/neutron-sdk/src/stargate/dex/query.rs

@@ -46,10 +46,12 @@ const POOL_BY_ID_QUERY_PATH: &str = "/neutron.dex.Query/PoolByID";
 const POOL_METADATA_QUERY_PATH: &str = "/neutron.dex.Query/PoolMetadata";
 const POOL_METADATA_ALL_QUERY_PATH: &str = "/neutron.dex.Query/PoolMetadataAll";
 
+/// Queries the parameters of the module.
 pub fn get_params(deps: Deps, req: ParamsRequest) -> StdResult<ParamsResponse> {
     make_stargate_query(deps, QueryParamsRequest::from(req), PARAMS_QUERY_PATH)
 }
 
+/// Retrieves a `LimitOrderTrancheUser` by user address and tranche key.
 pub fn get_limit_order_tranche_user(
     deps: Deps,
     req: LimitOrderTrancheUserRequest,
@@ -61,6 +63,7 @@ pub fn get_limit_order_tranche_user(
     )
 }
 
+/// Retrieves a list of `LimitOrderTrancheUser` items.
 pub fn get_limit_order_tranche_user_all(
     deps: Deps,
     req: LimitOrderTrancheUserAllRequest,
@@ -72,6 +75,7 @@ pub fn get_limit_order_tranche_user_all(
     )
 }
 
+/// Retrieves a list of `LimitOrderTrancheUser` items by user address.
 pub fn get_limit_order_tranche_user_all_by_address(
     deps: Deps,
     req: AllUserLimitOrdersRequest,
@@ -83,6 +87,7 @@ pub fn get_limit_order_tranche_user_all_by_address(
     )
 }
 
+/// Retrieves a `LimitOrderTranche` by index.
 pub fn get_limit_order_tranche(
     deps: Deps,
     req: GetLimitOrderTrancheRequest,
@@ -94,6 +99,7 @@ pub fn get_limit_order_tranche(
     )
 }
 
+/// Retrieves a list of `LimitOrderTranche` items for a given pair_id / token_in combination.
 pub fn get_limit_order_tranche_all(
     deps: Deps,
     req: AllLimitOrderTrancheRequest,
@@ -105,6 +111,7 @@ pub fn get_limit_order_tranche_all(
     )
 }
 
+/// Retrieves a list of `DepositRecord` items by user address.
 pub fn get_user_deposits_all(
     deps: Deps,
     req: AllUserDepositsRequest,
@@ -116,6 +123,7 @@ pub fn get_user_deposits_all(
     )
 }
 
+/// Retrieves a list of `TickLiquidity` items for a given pair_id / token_in combination.
 pub fn get_tick_liquidity_all(
     deps: Deps,
     req: AllTickLiquidityRequest,
@@ -127,6 +135,7 @@ pub fn get_tick_liquidity_all(
     )
 }
 
+/// Retrieves an inactive `LimitOrderTranche` by index.
 pub fn get_inactive_limit_order_tranche(
     deps: Deps,
     req: GetInactiveLimitOrderTrancheRequest,
@@ -138,6 +147,7 @@ pub fn get_inactive_limit_order_tranche(
     )
 }
 
+/// Retrieves a list of inactive `LimitOrderTranche` items.
 pub fn get_inactive_limit_order_tranche_all(
     deps: Deps,
     req: AllInactiveLimitOrderTrancheRequest,
@@ -149,6 +159,7 @@ pub fn get_inactive_limit_order_tranche_all(
     )
 }
 
+/// Retrieves a list of `PoolReserves` items for a given pair_id / token_in combination.
 pub fn get_pool_reserves_all(
     deps: Deps,
     req: AllPoolReservesRequest,
@@ -160,6 +171,7 @@ pub fn get_pool_reserves_all(
     )
 }
 
+/// Retrieves a `PoolReserves` by index.
 pub fn get_pool_reserves(
     deps: Deps,
     req: GetPoolReservesRequest,
@@ -171,6 +183,7 @@ pub fn get_pool_reserves(
     )
 }
 
+/// Queries the simulated result of a multihop swap.
 pub fn get_estimate_multi_hop_swap(
     deps: Deps,
     req: EstimateMultiHopSwapRequest,
@@ -197,10 +210,12 @@ pub fn get_pool(deps: Deps, req: PoolRequest) -> StdResult<PoolResponse> {
     make_stargate_query(deps, QueryPoolRequest::from(req), POOL_QUERY_PATH)
 }
 
+/// Queries a pool by ID.
 pub fn get_pool_by_id(deps: Deps, req: PoolByIdRequest) -> StdResult<PoolResponse> {
     make_stargate_query(deps, QueryPoolByIdRequest::from(req), POOL_BY_ID_QUERY_PATH)
 }
 
+/// Queries a `PoolMetadata` by ID.
 pub fn get_pool_metadata(
     deps: Deps,
     req: GetPoolMetadataRequest,
@@ -212,6 +227,7 @@ pub fn get_pool_metadata(
     )
 }
 
+/// Queries a list of `PoolMetadata` items.
 pub fn get_pool_metadata_all(
     deps: Deps,
     req: AllPoolMetadataRequest,

packages/neutron-sdk/src/stargate/dex/types.rs

@@ -28,14 +28,23 @@ pub const JIT_LIMIT_ORDER_TYPE_EXP_TIMESTAMP: i64 = 0;
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct DepositRequest {
+    /// The account from which deposit Tokens will be debited.
     pub sender: String,
+    /// The account to which PoolShares will be issued.
     pub receiver: String,
+    /// Denom for one side of the deposit.
     pub token_a: String,
+    /// Denom for the opposing side of the deposit.
     pub token_b: String,
+    /// Amounts of token_a to deposit.
     pub amounts_a: Vec<String>,
+    /// Amounts of token_b to deposit.
     pub amounts_b: Vec<String>,
+    /// Tick indexes to deposit at defined in terms of token_a to token_b (i.e. token_a is on the left).
     pub tick_indexes_a_to_b: Vec<i64>,
+    /// Fees to use for each deposit.
     pub fees: Vec<u64>,
+    /// Additional deposit options.
     pub options: Vec<DepositOptions>,
 }
 
@@ -59,12 +68,20 @@ impl From<DepositRequest> for MsgDeposit {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct WithdrawalRequest {
+    /// The account from which the PoolShares are removed.
     pub sender: String,
+    /// The account to which the tokens are credited.
     pub receiver: String,
+    /// Denom for one side of the deposit.
     pub token_a: String,
+    /// Denom for the opposing side of the deposit.
     pub token_b: String,
+    /// Amount of shares to remove from each pool.
     pub shares_to_remove: Vec<String>,
+    /// Tick indexes of the target LiquidityPools defined in terms of tokan_a to token_b (i.e.
+    /// token_a is on the left).
     pub tick_indexes_a_to_b: Vec<i64>,
+    /// Fee for the target LiquidityPools.
     pub fees: Vec<u64>,
 }
 
@@ -86,13 +103,22 @@ impl From<WithdrawalRequest> for MsgWithdrawal {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct PlaceLimitOrderRequest {
+    /// Account from which token_in is debited.
     pub sender: String,
+    /// Account to which token_out is credited or that will be allowed to withdraw or cancel a
+    /// maker order.
     pub receiver: String,
+    /// Token being “sold”.
     pub token_in: String,
+    /// Token being “bought”.
     pub token_out: String,
+    /// Limit tick for a limit order, specified in terms of token_in to token_out.
     pub tick_index_in_to_out: i64,
+    /// Amount of TokenIn to be traded.
     pub amount_in: String,
+    /// Type of limit order to be used.
     pub order_type: LimitOrderType,
+    /// Expiration time for order. Only valid for GoodTilTime limit orders.
     pub expiration_time: Option<i64>,
     pub max_amount_out: Option<String>,
 }
@@ -117,7 +143,9 @@ impl From<PlaceLimitOrderRequest> for MsgPlaceLimitOrder {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct WithdrawFilledLimitOrderRequest {
+    /// Account which controls the limit order and to which proceeds are credited.
     pub sender: String,
+    /// Tranche key for the target limit order.
     pub tranche_key: String,
 }
 
@@ -134,7 +162,9 @@ impl From<WithdrawFilledLimitOrderRequest> for MsgWithdrawFilledLimitOrder {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct CancelLimitOrderRequest {
+    /// Account which controls the limit order and to which any untraded amount is credited.
     pub sender: String,
+    /// Tranche key for the target limit order.
     pub tranche_key: String,
 }
 
@@ -151,11 +181,20 @@ impl From<CancelLimitOrderRequest> for MsgCancelLimitOrder {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct MultiHopSwapRequest {
+    /// Account from which token_in is debited.
     pub sender: String,
+    /// Account to which token_out is credited.
     pub receiver: String,
+    /// Array of possible routes. E.g. [[“token_a”, “token_c”, “token_d”, “token_b”]]. The complete
+    /// amount of specified by `amount_in` will always be used. If there is insufficient liquidity
+    /// in a route to swap 100% of the `amount_in` the route will fail. The first route that does
+    /// not run out of liquidity, hit the `exit_limit_price` or return an error will be used.
     pub routes: Vec<Vec<String>>,
+    /// Amount of token_in to swap.
     pub amount_in: String,
+    /// Minimum price that that must be satisfied for a route to succeed.
     pub exit_limit_price: String,
+    /// If true all routes are run and the route with the best price is used.
     pub pick_best_route: bool,
 }
 
@@ -343,7 +382,7 @@ pub struct AllTickLiquidityRequest {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct AllTickLiquidityResponse {
-    pub tick_liquidity: Vec<Liquidity>,
+    pub tick_liquidity: Vec<TickLiquidity>,
     pub pagination: Option<PageResponse>,
 }
 
@@ -613,6 +652,8 @@ impl From<AllPoolMetadataRequest> for QueryAllPoolMetadataRequest {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct DepositOptions {
+    /// Autoswap provides a mechanism for users to deposit the entirety of their specified deposit
+    /// amounts by paying a small fee. By default the `autoswap` option is enabled.
     pub disable_autoswap: bool,
 }
 
@@ -685,6 +726,7 @@ pub struct LimitOrderTranche {
     pub reserves_taker_denom: Int128,
     pub total_maker_denom: Int128,
     pub total_taker_denom: Int128,
+    /// unix timestamp in seconds;
     #[serde(deserialize_with = "deserialize_expiration_time")]
     pub expiration_time: Option<Int64>,
     /// a decimal with precision equal to 26
@@ -709,7 +751,7 @@ pub struct PairID {
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "snake_case")]
-pub enum Liquidity {
+pub enum TickLiquidity {
     PoolReserves(PoolReserves),
     LimitOrderTranche(LimitOrderTranche),
 }