update docs

x/auction/spec/concept.md

@@ -0,0 +1,119 @@
+## Concept
+
+- `auction module` is implementing the *Dutch Auction* method which mean the price are decrease until a user bid for that price or the price reach floor price. 
+
+### Initialization of an auction
+- At each begin block `auction module` check for auction periods, if reach a new auction period, auction module calls over `vault module` to check for any vault that are in debt and need to liquidate the assets. `vault module` returns information needed to create an auction.
+
+
+- An auction is defined as
+```
+type Auction struct {
+    // for simplicity, will use vault id that start the auction as auction id
+	AuctionId uint64 
+    
+	// starting price (currently only support usd stable token)
+	InitialPrice string 
+    
+	// items defines liquidate assets
+	Item types.Coin
+    
+	// current_rate defines the rate compare with the initial price
+	CurrentRate string 
+    
+	// last_discount_time defines the last time a discount has been apply
+	LastDiscountTime time.Time  
+    
+    // token amount raised from the auction
+	TokenRaised      types.Coin 
+    
+	// status defines auction current status
+	Status AuctionStatus 
+    
+	// target_goal defines the debt the auction is trying to recover
+	TargetGoal types.Coin 
+    
+	// vault_id defines id of auction vault
+	VaultId uint64 
+}
+```
+
+### Auction update per block
+- For each begin block, we update the auctions information accordingly, This includes:
+    - Check for auction start time to start the process and open for bidding.
+    - Check if auction reach next `reduce_step` to update the price based on `discount_rate`. If the price dips to `lowest_rate`, handle any bids left, after that update auction status `toAuctionStatus_AUCTION_STATUS_FINISHED` and closed for bidding.
+    - Check if there is any bid entry matches the current price. If there is, send the collatheral amount accordingly with the bid amount and the price its accepts. If auction out of collatheral then update auction status to `AuctionStatus_AUCTION_STATUS_OUT_OF_COLLATHERAL` and closed for bidding.
+    - Check if auction status is either `toAuctionStatus_AUCTION_STATUS_FINISHED` or `AuctionStatus_AUCTION_STATUS_OUT_OF_COLLATHERAL` to end the auction.
+
+:::info
+In the case where the bid amount cover a portion of the remain collatheral, we will send those remain to the bidder and refund the rest back to the user so that auction won't end with auction has some small amount that no one bid for.
+:::
+
+### Bidding process
+- Bidder can submit a transaction to participate in the auction.
+
+eg:
+```
+message MsgBid {
+    string auction_id = 1
+    string bidder = 2
+    sdk.Coin amount = 3
+}
+```
+
+A bid is defined as
+
+```
+type Bid struct {
+    // id of bid
+  uint64 bid_id = 1;
+  
+  // bidder address
+  string bidder = 2;
+
+  // bidding amount
+  sdk.Coin amount = 3;
+  
+  // recive_price defines the price that the bid is willing to pay
+  string recive_price = 4 
+
+  bool is_handle = 5;
+
+  // index in auction bid_queue
+  uint64 index = 6;
+}
+```
+
+- The bid amount denom must matches that of the vault debt denom.
+
+- The bidding process occur through out the auction process, users can submit an entry indicates the amount they are willing to pay for a certain price.
+
+- Auction keeper use a queue to store all bid entries for an auction. Bid will be handle by the order of time it got added in the queue.
+
+- To update the entry, user must cancel the current bid entry and resubmit
+
+eg:
+```
+message MsgCancelBid {
+    uint64 auction_id = 1
+    string bidder = 2
+    uint64 bid_id = 3
+}
+```
+
+- When the price is dropped to an amount that less than or equal the bid `recive_price` the amount of collatheral the bidder recieve = bid_amount / recieve_price
+
+### Auction end process
+- By the end of the auction ( either auction status updated to `AuctionStatus_AUCTION_STATUS_FINISHED` or `AuctionStatus_AUCTION_STATUS_OUT_OF_COLLATHERAL`), send token raised from auctions to `vault` module. 
+- Appends the liquidation result to a `liquidationMap`. If `liquidationMap` not empty notified `vault` module with the liquidation result through `vault keeper` interface `Liquidate` func. 
+- Refunds all unhandled bids to the corresponding bidder. Afterward, clear all state of the auction.
+
+Liquidation is defined as
+```
+type Liquidation struct {
+	Denom                  string                             
+	LiquidatingVaults      []*Vault                           
+	VaultLiquidationStatus map[uint64]*VaultLiquidationStatus 
+}
+
+```

x/auction/spec/msg.md

@@ -0,0 +1,34 @@
+
+### CLI
+
+A user can query and interact with the `auction` module using the CLI.
+
+### Tx
+
+#### Bid
+
+The `bid` command allows users submit a bid entry to an auction.
+
+```shell
+onomyd tx auction bid [auction-id] [amount] [recive_rate] [flags]
+```
+
+Example:
+
+```shell
+onomyd tx bid 0 1000nomUSD 0.8 --from mykey
+```
+
+#### Cancel bid
+
+The `cancel-bid` command allows users cancel their bid entry of an auction.
+
+```shell
+onomyd tx auction cancel-bid [bid-id] [auction_id] [flags]
+```
+
+Example:
+
+```shell
+onomyd tx cancel-bid 1 0 --from mykey
+```

x/auction/spec/params.md

@@ -0,0 +1,28 @@
+## Params
+- auction module will need to set these params:
+
+```
+type Params struct {
+    // defines how long (either in blocktime or blockheight)
+    // between each auction
+    auction_periods time.Time|uint64
+    
+    // defines how long the auction will takes
+    auction_durations time.Duration|uint64
+    
+    // period between each price reduction
+    reduce_step time.Time|uint64
+    
+    // rate compared with the collaterals price from the
+    // oracle at which the auction will start with
+    starting_rate float64
+    
+    // rate compared with the initial price that the price
+    // can drop to
+    lowest_rate float64
+    
+    // rate that are decrease every reduce_step
+    discount_rate float64
+    
+}
+```

x/auction/spec/query.md

@@ -0,0 +1,25 @@
+### Query
+
+#### Params
+
+The `params` command allows users to query auction module params
+
+```shell
+onomyd query auction params [flags]
+```
+
+#### All auctions
+
+The `all-auction` command allows users to query all auctions
+
+```shell
+onomyd query auction all-auction [flags]
+```
+
+#### All bids
+
+The `all-bids` command allows users to query all bid entries
+
+```shell
+onomyd query auction all-bids [flags]
+```

x/psm/spec/concept.md

@@ -0,0 +1,25 @@
+# PSM Module
+
+The PSM module is a stabilization mechanism for the nomUSD stablecoin, allowing users to swap approved stablecoins for nomUSD at a 1-1 ratio.
+
+## Contents
+- [Concept](#concept)
+- [State](#state)
+- [Messages](#messages)
+- [Events](#events)
+- [Params](#params)
+- [Keepers](#keepers)
+- [Hooks](#hooks)
+- [Future Improvements](#future-improvements)
+
+## Concept
+
+PSM issues nomUSD in exchange for approved stablecoins, with a maximum issuance limit set by governance. It also allows users to swap nomUSD for stablecoins at a 1-1 ratio.nomUSD is issued from PSM which is backed by stablecoins within it. Parameters such as limit per stablecoin, swap-in fees and swap-out fees are governed and can change based on economic conditions. PSM is an effective support module for Vaults module in case users need nomUSD to repay off debts and close vault (redeem collateral).
+
+### Key Features
+
+Key Features
+
+- **Swap to nomUSD**: Users can convert from stablecoin to nomUSD provided that the stablecoin has been added to the list of accepted stablecoins.
+- **Swap to Stablecoin**: Users can convert from nomUSD to stablecoin provided that the stablecoin has been added to the list of accepted stablecoins.
+

x/psm/spec/event.md

@@ -0,0 +1,41 @@
+
+## Events
+
+The PSM module emits events for various operations:
+- **AddStablecoin**: Emitted when a new stablecoin is added.
+- **UpdateStablecoin**: Emitted when a stablecoin is updates
+- **SwapToStablecoin**: Emitted when exchanging nomUSD for stablecoin
+- **SwapTonomUSD**: Emitted when exchanging stablecoin for nomUSD
+
+
+## ABCI
+
+### Fee recalculate
+To maintain the peg of 1 nomUSD = 1 USD, the swap fees need to be adjusted whenever the price of stablecoins fluctuates. This adjustment ensures that deviations from the target price of 1 USD per nomUSD are counterbalanced by the fees.
+
+Adjustment Logic:
+- If the stablecoin price is above 1, fee_out (the fee for converting from nomUSD to the stablecoin) will be higher, and fee_in (the fee for converting from the stablecoin to nomUSD) will be lower. This setup discourages swaps that would increase the stablecoin holdings when its value is above 1, helping to bring the price back down.
+- If the stablecoin price is below 1, fee_out will be lower, and fee_in will be higher. This makes it cheaper to convert nomUSD to the stablecoin and more costly to convert the stablecoin to nomUSD, which encourages activity that pushes the price back up toward the target.
+
+
+#### How to calculate fee:
+The fee adjustments are scaled using the `AdjustmentFee` parameter (k), which controls the responsiveness of the fee to price deviations.
+
+Suppose:
+- `newPrice`: new market price of stablecoin relative to nomUSD.
+- `feeIn`: inbound fee (to exchange stablecoin to nomUSD).
+- `feeOut`: outbound fee (to exchange nomUSD to stablecoin).
+- `maxFee`: maximum total fee for both directions (usually feeIn + feeOut).
+- `k`: adjustment factor (`AdjustmentFee`) that controls the sensitivity of the fee to price changes.
+
+Calculate new price ratio:`rate`= 1/`newPrice`
+​
+Fee adjustment:
+    - `rate` < 1: 
+        `newFeeOut` = `feeOut`/ `rate`^`k`
+        `newFeeIn`=`maxFee`−`newFeeOut`
+        `newFeeOut` will not exceed `maxFee`
+    - `rate` > 1: 
+        `newFeeIn` = `feeIn`*`rate`^`k`
+        `newFeeOut`=`maxFee`−`newFeeIn`
+        `newFeeIn` will not exceed `maxFee`