0g-chain/x/hard/spec/02_state.md
Kevin Davis c5fc1c6b4f
Add hard and incentive spec updates (#817)
* wip: update hard spec

* feat: updated hard spec

* feat: updated incentive spec
2021-02-19 17:14:48 +01:00

5.3 KiB

State

Parameters and Genesis State

Parameters define the governance parameters and default behavior of each money market.

// Params governance parameters for hard module
type Params struct {
  MoneyMarkets       MoneyMarkets `json:"money_markets" yaml:"money_markets"` // defines the parameters for each money market
  CheckLtvIndexCount int          `json:"check_ltv_index_count" yaml:"check_ltv_index_count"` // defines the number of positions that are checked for liquidation at the beginning of each block
}

// MoneyMarket is a money market for an individual asset
type MoneyMarket struct {
  Denom                  string            `json:"denom" yaml:"denom"` // the denomination of the token for this money market
  BorrowLimit            BorrowLimit       `json:"borrow_limit" yaml:"borrow_limit"` // the borrow limits, if any, applied to this money market
  SpotMarketID           string            `json:"spot_market_id" yaml:"spot_market_id"` // the pricefeed market where price data is fetched
  ConversionFactor       sdk.Int           `json:"conversion_factor" yaml:"conversion_factor"` //the internal conversion factor for going from the smallest unit of a token to a whole unit (ie. 8 for BTC, 6 for KAVA, 18 for ETH)
  InterestRateModel      InterestRateModel `json:"interest_rate_model" yaml:"interest_rate_model"` // the model that determines the prevailing interest rate at each block
  ReserveFactor          sdk.Dec           `json:"reserve_factor" yaml:"reserve_factor"` // the percentage of interest that is accumulated by the protocol as reserves
  AuctionSize            sdk.Int           `json:"auction_size" yaml:"auction_size"` // the maximum size of auction for this money market. Liquidations larger than this will be broken down into multiple auctions
  KeeperRewardPercentage sdk.Dec           `json:"keeper_reward_percentage" yaml:"keeper_reward_percentages"` // the percentage of a liquidation that is given to the keeper that liquidated the position
}

// MoneyMarkets slice of MoneyMarket
type MoneyMarkets []MoneyMarket

// InterestRateModel contains information about an asset's interest rate
type InterestRateModel struct {
  BaseRateAPY    sdk.Dec `json:"base_rate_apy" yaml:"base_rate_apy"` // the base rate of APY when borrows are zero. Ex. A value of "0.02" would signify an interest rate of 2% APY as the Y-intercept of the interest rate model for the money market. Note that internally, interest rates are stored as per-second interest.
  BaseMultiplier sdk.Dec `json:"base_multiplier" yaml:"base_multiplier"` // the percentage rate at which the interest rate APY increases for each percentage increase in borrow utilization. Ex. A value of "0.01" signifies that the APY interest rate increases by 1% for each additional percentage increase in borrow utilization.
  Kink           sdk.Dec `json:"kink" yaml:"kink"` // the inflection point at which the BaseMultiplier no longer applies and the JumpMultiplier does apply. For example, a value of "0.8" signifies that at 80% utilization, the JumpMultiplier applies
  JumpMultiplier sdk.Dec `json:"jump_multiplier" yaml:"jump_multiplier"` // same as BaseMultiplier, but only applied when utilization is above the Kink
}

// BorrowLimit enforces restrictions on a money market
type BorrowLimit struct {
  HasMaxLimit  bool    `json:"has_max_limit" yaml:"has_max_limit"` // boolean for if the money market has a max amount that can be borrowed, irrespective of utilization.
  MaximumLimit sdk.Dec `json:"maximum_limit" yaml:"maximum_limit"` // the maximum amount that can be borrowed for this money market, irrespective of utilization. Ignored if HasMaxLimit is false
  LoanToValue  sdk.Dec `json:"loan_to_value" yaml:"loan_to_value"` // the percentage amount of borrow power each unit of deposit accounts for. Ex. A value of "0.5" signifies that for $1 of supply of a particular asset, borrow limits will be increased by $0.5
}

GenesisState defines the state that must be persisted when the blockchain stops/restarts in order for normal function of the hard module to resume and all outstanding funds + interest to be accounted for.

// GenesisState is the state that must be provided at genesis.
type GenesisState struct {
  Params                    Params                   `json:"params" yaml:"params"` // governance parameters
  PreviousAccumulationTimes GenesisAccumulationTimes `json:"previous_accumulation_times"  yaml:"previous_accumulation_times"` // stores the last time interest was calculated for a particular money market
  Deposits                  Deposits                 `json:"deposits" yaml:"deposits"` // stores existing deposits when the chain starts, if any
  Borrows                   Borrows                  `json:"borrows" yaml:"borrows"` // stores existing borrows when the chain starts, if any
  TotalSupplied             sdk.Coins                `json:"total_supplied" yaml:"total_supplied"` // stores the running total of supplied (deposits + interest) coins when the chain starts, if any
  TotalBorrowed             sdk.Coins                `json:"total_borrowed" yaml:"total_borrowed"` // stores the running total of borrowed coins when the chain starts, if any
  TotalReserves             sdk.Coins                `json:"total_reserves" yaml:"total_reserves"` // stores the running total of reserves when the chain starts, if any
}