Stablefee
The stablefee module manages the configuration and calculation of fees in a stable currency, converting them to the native chain currency (EMPE) using an exchange rate. It allows authorized providers to set the exchange rate and governance to update module parameters. Fees for operations are charged based on predefined rates and distributed to specified recipients, with any remainder sent to the module account.
Contents
Overview
The stablefee module provides the following key functionalities:
Exchange Rate Management: Authorized providers can update the exchange rate between the stable base currency (e.g., USD) and the native chain currency (EMPE).
Fee Calculation: Fees for operations (e.g., swaps, transfers) are defined in the stable currency and converted to EMPE using the current exchange rate.
Fee Distribution: Collected fees are distributed to predefined recipients with configurable fractions, with any remainder sent to the module account.
Parameter Updates: Governance can update module parameters, including fee pairs, distributions, and authorized exchange rate providers.
Messages
MsgSetExchangeRate
This message updates the exchange rate (EMPE per unit of base currency). Only authorized providers can execute this.
Definition:
type MsgSetExchangeRate struct {
// Address of the authorized provider
Sender string `json:"sender" yaml:"sender"`
// New exchange rate value (positive decimal)
NewRate *sdk.Dec `json:"new_rate" yaml:"new_rate"`
}
Validation and Processing:
Sender
must be a valid Bech32 address and listed inExchangeRateProviders
module parameters.NewRate
must be a positive decimal value.Upon success:
The exchange rate is updated in the module's state.
Emits an
EventSetExchangeRate
event.
MsgUpdateParams
This message updates the module parameters via governance proposal.
Definition:
type MsgUpdateParams struct {
// Governance authority address
Authority string `json:"authority" yaml:"authority"`
// New parameters
Params Params `json:"params" yaml:"params"`
}
Validation and Processing:
Authority
must match the chain's governance address.Params
are validated (e.g., base currency non-empty, valid distributions).Upon success:
Module parameters are updated.
Emits an
EventUpdateParams
event.
Queries
Query Module Parameters
Returns the current module parameters, including base currency, fee pairs, and distributions.
Request:
message QueryParamsRequest {}
Response:
message QueryParamsResponse {
Params params = 1;
}
CLI Command:
emped query stablefee params
Query Exchange Rate
Returns the current exchange rate (EMPE per base currency unit).
Request:
message QueryExchangeRateRequest {}
Response:
message QueryExchangeRateResponse {
string exchange_rate = 1;
}
CLI Command:
emped query stablefee exchange-rate
Query Fee for Operation
Calculates the fee in EMPE for a specific operation.
Request:
message QueryFeeRequest {
string operation = 1;
}
Response:
message QueryFeeResponse {
cosmos.base.v1beta1.Coin fee = 1;
}
CLI Command:
emped query stablefee fee [operation-name]
Events
EventSetExchangeRate
Emitted when the exchange rate is updated.
Attributes:
sender
: Address of the provider who set the rate.new_rate
: New exchange rate value.
EventUpdateParams
Emitted when module parameters are updated.
Attributes:
authority
: Governance address that authorized the update.params
: New parameters.
Parameters
The module's parameters include:
BaseCurrency: Stable currency identifier (e.g., "USD").
Fees: List of
FeePair
objects mapping operations to stable currency fees:type FeePair struct { Operation string // Name of operation (e.g., "swap") Amount sdk.Dec // Fee in stable currency }
Distributions: List of
FeeDistribution
recipients and fractions:type FeeDistribution struct { Recipient string // Bech32 address Fraction sdk.Dec // Share of fees (0 < fraction ≤ 1) }
ExchangeRateProviders: Authorized addresses allowed to set exchange rates.
Parameters are updatable via governance using MsgUpdateParams
.
Genesis
The genesis state includes:
Params: Initial module parameters.
ExchangeRate: Initial exchange rate (EMPE per base currency unit).
Genesis validation ensures:
Parameters are valid (non-empty base currency, valid distributions).
Exchange rate is positive.
CLI Commands
Transaction Commands
Set Exchange Rate:
emped tx stablefee set-exchange-rate 1.25 --from provider-key
Update Parameters (via governance proposal):
# Typically part of a governance proposal process
Query Commands
Query Parameters:
emped query stablefee params
Query Exchange Rate:
emped query stablefee exchange-rate
Query Fee for Operation:
emped query stablefee fee swap
Simulation
The module includes simulation operations to test:
SimulateMsgSetExchangeRate: Generates random exchange rate updates from authorized providers.
Parameter Updates: Tests governance proposals with valid/invalid parameters.
Simulations validate fee distributions, exchange rate effects, and error handling.
Additional Notes
Fee Conversion: Fees are calculated as
(StableFee * ExchangeRate)
in EMPE, rounded down to the nearest integer.Distribution Logic:
Fees are split proportionally to distribution fractions.
Remainder (after distributions) is sent to the module account.
Security:
Only governance can update parameters.
Exchange rate providers are explicitly whitelisted.
Last updated