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

1. Overview

2. Messages

   • MsgSetExchangeRate

   • MsgUpdateParams

3. Queries

   • Query Module Parameters

   • Query Exchange Rate

   • Query Fee for Operation

4. Events

5. Parameters

6. Genesis

7. CLI Commands

8. Simulation

9. Additional Notes

---

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 in ExchangeRateProviders 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.