# 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](#overview)
2. [Messages](#messages)
   * [MsgSetExchangeRate](#msgsetexchangerate)
   * [MsgUpdateParams](#msgupdateparams)
3. [Queries](#queries)
   * [Query Module Parameters](#query-module-parameters)
   * [Query Exchange Rate](#query-exchange-rate)
   * [Query Fee for Operation](#query-fee-for-operation)
4. [Events](#events)
5. [Parameters](#parameters)
6. [Genesis](#genesis)
7. [CLI Commands](#cli-commands)
8. [Simulation](#simulation)
9. [Additional Notes](#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:**

```go
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:**

```go
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:**

```proto
message QueryParamsRequest {}
```

**Response:**

```proto
message QueryParamsResponse {
  Params params = 1;
}
```

CLI Command:

```bash
emped query stablefee params
```

***

### Query Exchange Rate

Returns the current exchange rate (EMPE per base currency unit).

**Request:**

```proto
message QueryExchangeRateRequest {}
```

**Response:**

```proto
message QueryExchangeRateResponse {
  string exchange_rate = 1;
}
```

CLI Command:

```bash
emped query stablefee exchange-rate
```

***

### Query Fee for Operation

Calculates the fee in EMPE for a specific operation.

**Request:**

```proto
message QueryFeeRequest {
  string operation = 1;
}
```

**Response:**

```proto
message QueryFeeResponse {
  cosmos.base.v1beta1.Coin fee = 1;
}
```

CLI Command:

```bash
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:

  ```go
  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:

  ```go
  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:**

  ```bash
  emped tx stablefee set-exchange-rate 1.25 --from provider-key
  ```
* **Update Parameters (via governance proposal):**

  ```bash
  # Typically part of a governance proposal process
  ```

### Query Commands

* **Query Parameters:**

  ```bash
  emped query stablefee params
  ```
* **Query Exchange Rate:**

  ```bash
  emped query stablefee exchange-rate
  ```
* **Query Fee for Operation:**

  ```bash
  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.