🛠️
Technical Documentation
  • Introduction
    • About Empeiria
  • Empe Blockchain
    • Overview
    • Chain Architecture
      • Auth
      • Authz
      • Bank
      • Distribution
      • Governance
      • Staking
      • IBC
      • DidDoc
      • Vesting
      • Minter
      • Stablefee
      • LinkedResources
  • EVDI
    • EVDI Architecture
    • Self-Sovereign Identity
      • Technical Foundations
      • Roles in the SSI framework
      • Protocols and Standards
  • User Guide
    • Empe DID Wallet
      • Intro
      • Download and first launch
      • Create or import did
      • Main screen overview
      • How to claim credential from issuer
      • How to use credential with verifier
      • Settings and other options
    • Keplr Wallet and Blockchain Operations
      • How to Connect Keplr Wallet
    • Ping Pub operation
    • Staking Tokens Guide
    • Voting on Governance Proposals Guide
    • Sending Tokens Guide
  • Developer Guide
    • Tutorial: Credential Issuance & Verification
      • Overview
      • Understanding Key Concepts
      • Project Setup
      • Deploying the Issuer
      • Uploading the Credential Schema
      • Issuing Credentials
      • Frontend for Credential Issuance
      • Testing Credential Issuance
      • Deploying the Verifier
      • Setting Up the Verification Flow
      • Creating a Verification Endpoint
      • Creating a Protected Dashboard
      • Testing the Verification Flow
      • Summary & Next Steps
    • One-click deployment
      • Introduction
      • Registration
      • Login
      • Creating an Issuer
      • Issuer Data Description
      • Creating a Verifier
      • Verifier Data Description
    • Verifier
      • Terminology and Concepts
      • Architecture Overview
      • Core Responsibilities
      • Query Language
      • Frontend Integration
      • Client Configuration
      • Security Considerations
      • Error Handling and Troubleshooting
      • Future Enhancements
      • References and Standards
      • FAQ
    • Issuer
      • Terminology and Concepts
      • Architecture Overview
      • Core Responsibilities
      • DID Document Management
      • Schemas Management
      • Issuing Credentials
      • Interacting with Wallets
      • Security Considerations
      • Error Handling and Troubleshooting
      • Future Enhancements
      • References and Standards
      • FAQ
    • Wallet SDK (Coming soon)
    • Introduction to cosmwasm
  • Validator Guide
    • Important links
    • Validators Guide
      • New validator
      • Hardware requirements
      • Required software installation
      • Go installation
      • Install prebuild binary
      • Install binary from source code (option B)
      • Configure a node
      • Cosmovisor setup
      • Sync with state-sync
      • Full state sync from archive snapshot
      • Latest snapshot
      • Run a Validator
      • Migration to v0.2.2
      • Migration to v0.3.0
      • Migration to v0.4.0
    • FAQ
  • Airdrop
    • On-Chain Testnet Airdrop
    • Faucet Guide: How to Claim Testnet Tokens?
  • Appendix
    • Glossary
Powered by GitBook
On this page
  • Contents
  • Overview
  • Messages
  • MsgSetExchangeRate
  • MsgUpdateParams
  • Queries
  • Query Module Parameters
  • Query Exchange Rate
  • Query Fee for Operation
  • Events
  • EventSetExchangeRate
  • EventUpdateParams
  • Parameters
  • Genesis
  • CLI Commands
  • Transaction Commands
  • Query Commands
  • Simulation
  • Additional Notes
  1. Empe Blockchain
  2. Chain Architecture

Stablefee

PreviousMinterNextLinkedResources

Last updated 2 days ago

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

Overview
Messages
MsgSetExchangeRate
MsgUpdateParams
Queries
Query Module Parameters
Query Exchange Rate
Query Fee for Operation
Events
Parameters
Genesis
CLI Commands
Simulation
Additional Notes