package
5.2.0
Repository: https://github.com/umee-network/umee.git
Documentation: pkg.go.dev

# README

IBC Transfer and Rate Limits for IBC Denoms

Abstract

The x/uibc is a Cosmos Module providing:

  • IBC Denom Metadata Tracker for ICS-20 transferred tokens to backfill denom metadata into the x/bank standard Cosmos SDK module.
  • IBC Quota is an ICS-4 middleware for the ICS-20 token transfer app to apply quota mechanism.

Content

IBC Denom Metadata Tracker

x/bank.types.Metadata is a structure which provides essential information about denom, such as display denom name, description, symbol, list of units (unit name and decimal exponent), and the default unit (Base).

ICS-20 is a x/bank token transfer protocol over IBC. The core implementation doesn't create bank Metadata when a new token is transferred for the very first time. It's worth to note that token received through IBC is identified by the port ID, channel ID and the source denom ID. The purpose of the x/uibc/ics20 module is to wrap the core IBC module and create a denom Metadata whenever it is missing. Look at the TrackDenomMetadata function for more details.

Considerations

The IBC ICS-20 doesn't carry any metadata information, so we only fill up the base denom. Importantly, we don't know about the Exponent, and we set Exponent := 0. In many cases this is wrong, and should be overwritten by chain governance.

IBC Quota

Hack or lending abuse is impossible to stop once the funds leave the chain. One mitigation is to limit the IBC inflows and outflows and be able to stop a chain and recover the funds with a migration.

Concepts

Inflow is an ICS-20 transaction of sending tokens to the Umee chain. Outflow is an ICS-20 transaction sending tokens out of the Umee chain.

IBC Quota is an upper limit in USD amount.

Design

Outflows

All outflows are measured in token average USD value using our x/oracle AvgKeeper. The AvgKeeper aggregates TVWAP prices over 16h window.

We define 2 Quotas for ICS-20 transfers. Each quota only tracks tokens x/leverage Token Registry.

  • Params.TokenQuota: upper limit of a sum of all outflows per token. Initially it's set to 0.6m 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. Initially it's set to 1m USD. Example of IBC outflows reaching the total quota: 300k USD worth of ATOM, 200k USD worth of STATOM, 250k USD worth of UMEE and 250k USD worth JUNO.

If a quota parameter is set to zero then we consider it as unlimited.

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).

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.

Inflows

We only allow inflows of tokens registered in x/leverage Token Registry. Other inflow transfers will be rejected.

ICS-20 Quota control

The ICS-20 quota mechanism is controlled by the Params.IbcStatus, which can have the following values:

  • DISABLED: inflow and quota outflow checks are disabled, essentially allowing all ics-20 transfers.
  • ENABLED: inflow and quota outflow checks are enabled (default value).
  • TRANSFERS_PAUSED: all ICS-20 transfers are disabled.

State

In the state we store:

  • Module parameters.
  • Running sum of total outflow values, serialized as sdk.Dec.
  • Running sum of per token outflow values, serialized as sdk.Dec.
  • Next quota expire time (after which the quota reset happens).

Messages

The RPC Messages provide an access to the x/gov to change the module parameters.

Queries

The RPC Queries allow to query module parameters and current outflow sums.

Events

All events with description are listed in the events.proto file.

# Packages

No description provided by the author
Package mocks is a generated GoMock package.
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

No description provided by the author
DefaultParams returns default genesis params.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
RegisterLegacyAminoCodec registers the necessary x/uibc interfaces and concrete types on the provided LegacyAmino codec.
No description provided by the author
RegisterQueryHandler registers the http handlers for service Query to "mux".
RegisterQueryHandlerClient registers the http handlers for service Query to "mux".
RegisterQueryHandlerFromEndpoint is same as RegisterQueryHandler but automatically dials to "endpoint" and closes the connection when "ctx" gets done.
RegisterQueryHandlerServer registers the http handlers for service Query to "mux".
No description provided by the author

# Constants

DISABLED: all inflow and outflow quota checks are disabled.
ENABLED: all inflow and outflow quota checks are enabled.
DISABLED IN: inflow quota check is disabled, while the outflow quota check is enabled.
DISABLED OUT: outflow quota check is disabled, while the inflow quota check is enabled.
PAUSED: all IBC transfers are paused.
UNSPECIFIED defines a no-op status.
ModuleName defines the module name.
StoreKey defines the primary module store key.

# Variables

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
ModuleCdc references the global x/uibc module codec.

# Structs

EventBadRevert is emitted on failure of ibc-transfer quota.
EventIBCTransferStatus is emitted on quota tracking pause status change.
GenesisState defines the uibc module's genesis state.
MsgGovSetIBCStatus defines the request type for setting the IBC quota status.
MsgGovSetIBCStatusResponse define the response type for Msg/MsgGovSetIBCStatus with x/gov proposals.
MsgGovUpdateQuota defines the Msg/GovUpdateQuota request type.
MsgGovUpdateQuotaResponse defines response type for the Msg/GovUpdateQuota for with x/gov proposals.
Params of x/uibc module.
QueryOutflow defines request type for query the quota of denoms.
QueryOutflowResponse defines response type of Query/Outflow.
QueryOutflow defines request type for query the quota of denoms.
QueryOutflowResponse defines response type of Query/Outflow.
QueryParams defines the request structure for the Params gRPC service handler.
QueryParamsResponse defines the response structure for the Params gRPC service handler.
UnimplementedMsgServer can be embedded to have forward compatible implementations.
UnimplementedQueryServer can be embedded to have forward compatible implementations.

# Interfaces

BankKeeper defines the expected x/bank keeper interface.
No description provided by the author
MsgClient is the client API for Msg service.
MsgServer is the server API for Msg service.
Oracle interface for price feed.
QueryClient is the client API for Query service.
QueryServer is the server API for Query service.

# Type aliases

IBCTransferStatus status of ibc-transfer quota check for inflow and outflow.