chore: rename uibc quota params

CHANGELOG.md

@@ -55,6 +55,10 @@ Ref: https://keepachangelog.com/en/1.0.0/
 - [2299](https://github.com/umee-network/umee/pull/2299) Upgrade Cosmos SDK to v0.47.
 - [2301](https://github.com/umee-network/umee/pull/2301) use gov/v1 MinInitialDepositRatio and set it to 0.1.
 
+### Breaking Changes
+
+- [2332](https://github.com/umee-network/umee/pull/2332) Rename: `TotalOutflowSum` to `OutflowSum`, `TotalInflowSum` to `InflowSum`.
+
 ## v6.1.0 - 2023-10-17
 
 ### Improvements

app/upgrades.go

@@ -124,7 +124,7 @@ func (app *UmeeApp) registerUpgrade6_2(upgradeInfo upgradetypes.Plan) {
 
 			// uibc migrations
 			uIBCKeeper := app.UIbcQuotaKeeperB.Keeper(&ctx)
-			uIBCKeeper.MigrateTotalOutflowSum()
+			uIBCKeeper.MigrateOutflowSum()
 			err = uIBCKeeper.SetParams(uibc.DefaultParams())
 			return fromVM, err
 		},

proto/umee/uibc/v1/genesis.proto

@@ -17,8 +17,8 @@ message GenesisState {
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins",
     (gogoproto.nullable)     = false
   ];
-  // total_outflow_sum defines the total outflow sum of ibc-transfer in USD.
-  string total_outflow_sum = 3 [
+  // outflow_sum defines the total outflow sum of ibc-transfer in USD.
+  string outflow_sum = 3 [
     (cosmos_proto.scalar)  = "cosmos.Dec",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false
@@ -35,8 +35,8 @@ message GenesisState {
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins",
     (gogoproto.nullable)     = false
   ];
-  // total_inflow_sum defines tracks total sum of IBC inflow transfers (in USD) during quota period.
-  string total_inflow_sum = 6 [
+  // inflow_sum defines tracks total sum of IBC inflow transfers (in USD) during quota period.
+  string inflow_sum = 6 [
     (cosmos_proto.scalar)  = "cosmos.Dec",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false

proto/umee/uibc/v1/quota.proto

@@ -42,8 +42,8 @@ message Params {
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false
   ];
-  // inflow_outflow_quota_token_base defines the inflow outflow quota base for token
-  string inflow_outflow_quota_token_base = 7 [
+  // inflow_outflow_token_quota_base defines the inflow outflow quota base for token
+  string inflow_outflow_token_quota_base = 7 [
     (cosmos_proto.scalar)  = "cosmos.Dec",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false

swagger/swagger.yaml

@@ -2534,10 +2534,10 @@ paths:
                     title: >-
                       inflow_outflow_quota_rate defines the rate of total
                       inflows
-                  inflow_outflow_quota_token_base:
+                  inflow_outflow_token_quota_base:
                     type: string
                     title: >-
-                      inflow_outflow_quota_token_base defines the inflow outflow
+                      inflow_outflow_token_quota_base defines the inflow outflow
                       quota base for token
                 title: Params of x/uibc module
             description: >-
@@ -6496,10 +6496,10 @@ definitions:
       inflow_outflow_quota_rate:
         type: string
         title: inflow_outflow_quota_rate defines the rate of total inflows
-      inflow_outflow_quota_token_base:
+      inflow_outflow_token_quota_base:
         type: string
         title: >-
-          inflow_outflow_quota_token_base defines the inflow outflow quota base
+          inflow_outflow_token_quota_base defines the inflow outflow quota base
           for token
     title: Params of x/uibc module
   umee.uibc.v1.QueryAllOutflowsResponse:
@@ -6567,10 +6567,10 @@ definitions:
           inflow_outflow_quota_rate:
             type: string
             title: inflow_outflow_quota_rate defines the rate of total inflows
-          inflow_outflow_quota_token_base:
+          inflow_outflow_token_quota_base:
             type: string
             title: >-
-              inflow_outflow_quota_token_base defines the inflow outflow quota
+              inflow_outflow_token_quota_base defines the inflow outflow quota
               base for token
         title: Params of x/uibc module
     description: |-

x/uibc/README.md

@@ -25,28 +25,37 @@ IBC Quota is an upper limit in USD amount.
 
 All inflows and outflows are measured in token average USD value using our x/oracle `AvgKeeper`. The `AvgKeeper` aggregates TVWAP prices over 16h window.
 
-We are only tracking inflows for tokens which are registered in x/leverage Token Registry.
+We are tracking inflows and outflows for tokens which are registered in x/leverage Token Registry.
+NOTE: we measure per token as defined in the x/leverage, not the IBC Denom Path (there can be multiple paths). Since creating a channel is permission less, we want to use the same quota token.
+For inflows:
 
-#### Inflow
+- `inflows`: metric per token.
+- `inflow_sum` : sum of all `inflows` from the previous point.
 
-- `Inflows`: metric per token.
-- `TotalInflowSum` : Sum of all `Inflows` from the previous point.
+Similarly to inflows, we measure outflows per token and aggregates (sum):
 
-#### Outflows
+- `outflows`: metric per token.
+- `outflow_sum`: sum of `outflows` from the previous point.
 
-All outflows are measured in token average USD value using our x/oracle `AvgKeeper`. The `AvgKeeper` aggregates TVWAP prices over 16h window.
+The metrics above are reset every `params.quota_duration` in Begin Blocker.
+Example: if the reset was done at 14:00 UTC, then the next reset will be done `quota_duration` later. You can observe the reset with `/umee/uibc/v1/EventQuotaReset` event, which will contain `next_expire` attribute.
 
-We define 2 Quotas for ICS-20 transfers. Each quota only tracks tokens x/leverage Token Registry.
+#### Outflow Quota
 
-- `Params.TokenQuota`: upper limit of a sum of all outflows per token. It's set to 1.2M USD per token. It limits the outflows value for each token.
-  NOTE: we measure per token as defined in the x/leverage, not the IBC Denom Path (there can be multiple paths). Since creating a channel is permission less, we want to use same quota token.
-- `Params.TotalQuota`: upper limit of a sum of all token outflows combined. For example if it's set to 1.6M USD then IBC outflows reaching the total quota will be 600k USD worth of ATOM, 500k USD worth of STATOM, 250k USD worth of UMEE and 250k USD worth JUNO.
+Inflows and outflows metrics above are used to **limit ICS-20 transfers** of tokens in the x/leverage Token Registry. The outflow transfer of token `X` is possible when:
 
-If a quota parameter is set to zero then we consider it as unlimited.
+1. Outflow quota after the transfer is not suppressed:
+1. `outflow_sum <= params.total_quota`. For example if it's set to 1.6M USD then IBC outflows reaching the total quota will be 600k USD worth of ATOM, 500k USD worth of STATOM, 250k USD worth of UMEE and 250k USD worth JUNO.
+1. `token_quota[X] <= params.token_quota` - the token X quota is not suppressed.
+1. OR Outflow quota lifted by inflows is not reached:
+1. `outflow_sum <= params.inflow_outflow_quota_base + params.inflow_outflow_quota_rate * inflow_sum`
+1. `token_quota[X] <= params.inflow_outflow_token_quota_base + params.inflow_outflow_token_quota_rate * inflows[X]`
 
-All quotas are reset in `BeginBlocker` whenever a time difference between the new block, and the previous reset is more than `Params.QuotaDuration` in seconds (initially set to 24h).
+See `../../proto/umee/uibc/v1/quota.proto` for the list of all params.
 
-Transfer is reverted whenever it breaks any quota.
+If a any `total_quota` or `token_quota` parameter is set to zero then we consider it as unlimited.
+
+Transfer is **reverted** whenever it breaks any quota.
 
 Transfer of tokens, which are not registered in the x/leverage Token Registry are not subject to the quota limit.
 

x/uibc/client/tests/cli_test.go

@@ -22,7 +22,7 @@ func TestIntegrationSuite(t *testing.T) {
 	var uibcGenState uibc.GenesisState
 	assert.NilError(t, cfg.Codec.UnmarshalJSON(cfg.GenesisState[uibc.ModuleName], &uibcGenState))
 	uibcGenState.Outflows = sdk.DecCoins{sdk.NewInt64DecCoin("uumee", 0)}
-	uibcGenState.TotalOutflowSum = sdk.NewDec(10)
+	uibcGenState.OutflowSum = sdk.NewDec(10)
 
 	bz, err := cfg.Codec.MarshalJSON(&uibcGenState)
 	assert.NilError(t, err)

x/uibc/genesis.go

@@ -9,19 +9,19 @@ import (
 
 func NewGenesisState(params Params, outflows sdk.DecCoins, outflowSum sdk.Dec) *GenesisState {
 	return &GenesisState{
-		Params:          params,
-		Outflows:        outflows,
-		TotalOutflowSum: outflowSum,
+		Params:     params,
+		Outflows:   outflows,
+		OutflowSum: outflowSum,
 	}
 }
 
 func DefaultGenesisState() *GenesisState {
 	return &GenesisState{
-		Params:          DefaultParams(),
-		Inflows:         nil,
-		Outflows:        nil,
-		TotalOutflowSum: sdk.NewDec(0),
-		TotalInflowSum:  sdk.NewDec(0),
+		Params:     DefaultParams(),
+		Inflows:    nil,
+		Outflows:   nil,
+		OutflowSum: sdk.NewDec(0),
+		InflowSum:  sdk.NewDec(0),
 	}
 }
 
@@ -49,12 +49,12 @@ func (gs GenesisState) Validate() error {
 		}
 	}
 
-	if gs.TotalOutflowSum.IsNegative() {
-		return fmt.Errorf("total outflow sum cannot be negative : %s ", gs.TotalOutflowSum.String())
+	if gs.OutflowSum.IsNegative() {
+		return fmt.Errorf("outflow sum cannot be negative : %s ", gs.OutflowSum.String())
 	}
 
-	if gs.TotalInflowSum.IsNegative() {
-		return fmt.Errorf("total inflow sum cannot be negative : %s ", gs.TotalInflowSum.String())
+	if gs.InflowSum.IsNegative() {
+		return fmt.Errorf("inflow sum cannot be negative : %s ", gs.InflowSum.String())
 	}
 
 	return nil