# Cfedistributor

# Abstract

Chain4Energy distributor module provides functionality of tokens distribution mechanism. Tokens distribution mechanism sends tokens from source accounts to destination accounts according to configuration.

# Contents

  1. Concept
  2. Params
  3. State
  4. Events
  5. Queries
  6. Invariants
  7. Genesis validations

# Concepts

The purpose of cfedistributor module is to provide functionality of flexible token distribution mechanism.

# Tokens distribition mechanism

Tokens distribution mechanism is based on the list of configured subdistributors. Tokens distribution mechanism iterates through all subdistributors in predefined order and executes each subdistributor per each block.

# Subdistributor

Subdistributor is responsible for sending coins from its source accounts to its destination accounts or for burning tokens accordingly to configured share percentage.

See the grapical represenation of subdistributor.

Subdistributor

Subdistributors are executed in predefined order so destinations of one subdistributor can become sources of another subdistributor.

# Subdistributor sources and destinations

Subdistributor supports several types of sources:

  • main module account
  • base account
  • module account
  • internal account

Subdistributor supports several types of destinations:

  • main module account
  • base account
  • module account
  • internal account
  • Burn destination

where:

  • Main module account - Chain4Energy distributor module account. Some other modules can send tokens directly to Chain4Energy distributor module. It is required to define one subdistributor where main module account is the source to prevent token accumulation.
  • Base account - Standard Cosmos SDK account configured as account address.
  • Module account - Cosmos SDK module account configured as module account name.
  • Internal account - helper virtual account internal to Chain4Energy distributor module. Useful in case of designing more complicated token flow.
  • Burn destination - tokens burner.

# Example

Let's consider an example of tokens distribution. In our example we have following token sources:

  • inflation
  • transaction fees
  • some module functionality fees. Our fictional module provides some functionality for which user is required to pay some fee and part of this fee is shared with the blockchain.

Inflation distribution:

  • 60% to distribution module for standard validators rewarding functionality
  • 5% to development fund
  • 35% to incentive booster pools

Transaction fees distribution:

  • 80% to distribution module for standard validators rewarding functionality
  • 5% to burn
  • 15% to incentive booster pools

Fictional module functionality fees distribution:

  • 50% to distribution module for standard validators rewarding functionality
  • 30% to development fund
  • 20% to incentive booster pools

We also have following incentive booster pools distribution:

  • 65% to governance booster pool
  • 35% to weekend booster pool

See the graphical representation of this distribution.

ExampleDistribution

Let's also assume that:

  • inflation is minted directly to cfedistributor module account
  • cosmos sdk distribution module fetches tokens from module account named "validators_rewards"
  • development fund is base account with address "c4edwijhdhwqu43efvc3543ec34c2erc342dw"
  • governance booster pool is module account named "governance_booster"
  • weekend booster pool is module account named "weekend_booster"
  • fictional module fees are stored in module account named "fictional_module_fee_collector"

Then we can model our distribution flow with following subdistributors:

  • inflation subdistributor

inflation subdistributor

  • transaction fees subdistributor

transaction fees subdistributor

  • module fees subdistributor

module fees subdistributor

  • incentive boosters subdistributor

incentive boosters subdistributor

# Parameters

The Chain4Energy distributor module contains the following configurations parameters:

Key Type Description
sub_distributors List of Subdistributor type list of defined subdistributors

# Subdistributor type

Param Type Description
name string unique name of the subdistributor
sources List of Account type list of source accounts
destinations Destinations type destinations definition

# Destinations type

Param Type Description
primary_share Account type primary destination - all remaining tokens from others shares are sent here
burn_share sdk.Dec type share to burn (0-1)
shares List of DestinationShare type List of destination accounts with share percentage

# DestinationShare type

Param Type Description
name string unique name of the share
destination Account type destination account
share sdk.Dec share percentage (0-1)

# Account type

Param Type Description
type enum string account type:
- MAIN - main module account
- MODULE_ACCOUNT - module account
- BASE_ACCOUNT - base account
- INTERNAL_ACCOUNT - cfedistributor internal account
id string account identifier dependant on the type::
- MAIN - empty
- MODULE_ACCOUNT - module account name
- BASE_ACCOUNT - base account address
- INTERNAL_ACCOUNT - cfedistributor internal account name

# Example params

See the configuration params for example from Concept section

Copy { "sub_distributors": [ { "name": "inflation_subdistributor", "sources": [ { "id": "", "type": "MAIN" } ], "destinations": { "primary_share": { "id": "validators_rewards", "type": "MODULE_ACCOUNT" }, "shares": [ { "destination": { "id": "c4edwijhdhwqu43efvc3543ec34c2erc342dw", "type": "BASE_ACCOUNT" }, "name": "inflation_development_fund_share", "share": "0.05" }, { "destination": { "id": "incentive_boosters", "type": "INTERNAL_ACCOUNT" }, "name": "inflation_incentive_boosters_share", "share": "0.35" } ], "burn_share": "0.0" } }, { "name": "transaction fees subdistributor", "sources": [ { "id": "fee_collector", "type": "MODULE_ACCOUNT" } ], "destinations": { "primary_share": { "id": "validators_rewards", "type": "MODULE_ACCOUNT" }, "shares": [ { "destination": { "id": "incentive_boosters", "type": "INTERNAL_ACCOUNT" }, "name": "txs_incentive_boosters_share", "share": "0.15" } ], "burn_share": "0.05" } }, { "name": "module_fees_subdistributor", "sources": [ { "id": "fictional_module_fee_collector", "type": "MODULE_ACCOUNT" } ], "destinations": { "primary_share": { "id": "validators_rewards", "type": "MODULE_ACCOUNT" }, "shares": [ { "destination": { "id": "c4edwijhdhwqu43efvc3543ec34c2erc342dw", "type": "BASE_ACCOUNT" }, "name": "module_development_fund_share", "share": "0.3" }, { "destination": { "id": "incentive_boosters", "type": "INTERNAL_ACCOUNT" }, "name": "module_incentive_boosters_share", "share": "0.2" } ], "burn_share": "0.0" } }, { "name": "incentive boosters subdistributor", "sources": [ { "id": "incentive_boosters", "type": "INTERNAL_ACCOUNT" } ], "destinations": { "primary_share": { "id": "governance_booster", "type": "MODULE_ACCOUNT" }, "shares": [ { "destination": { "id": "weekend_boosters", "type": "INTERNAL_ACCOUNT" }, "name": "weekend_boosters_share", "share": "0.35" } ], "burn_share": "0.0" } } ] }

# State

Chain4Energy distributor module state contains decimal amounts left from previous block that were impossible to send due value less than 1 token. Module state contains following data:

Key Type Description
states List of State type list of states for burn and per each destination account in all subdistributors (except main distributor)

# State type

Param Type Description
account Account type (see Account type) destination account or empty in case of burn flag set to true
burn bool specifies if this is burn destination state
remains DecCoin list of coins to distribute left by previous block

# Example state

See the state for example from Concept section

Copy [ { "account": { "id": "validators_rewards", "type": "MODULE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.900000000000000000" } ] }, { "account": { "id": "c4edwijhdhwqu43efvc3543ec34c2erc342dw", "type": "BASE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.359000000000000000" } ] }, { "account": { "id": "incentive_boosters", "type": "INTERNAL_ACCOUNT" }, "burn": false, "remains": [] }, { "account": { "id": "governance_booster", "type": "MODULE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.582000000000000000" } ] }, { "account": { "id": "weekend_booster", "type": "MODULE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.359000000000000000" } ] }, { "burn": true, "remains": [ { "denom": "uc4e", "amount": "0.800000000000000000" } ] } ]

# Events

Chain4Energy distributor module emits the following events:

# BeginBlockers

# Tokens distribution

Type Attribute Key Description
EventDistribution Distribution type Distribution data
EventDistributionBurn DistributionBurn type Burn data
# EventDistribution type

Distribution type represents one send operation to one destination in one block

Param Type Description
subdistributor string Name of the subdisributor
share_name string Name of the DestinationShare (see DestinationShare type)
sources list of Account type (see Account type) list of sources
destination Account type (see Account type) destination
amount DecCoins coins sent to destination
# EventDistributionBurn type

DistributionBurn type represents one burn operation

Param Type Description
subdistributor string Name of the subdisributor
sources list of Account type (see Account type) list of sources
amount DecCoins coins burned

# Queries

# Params query

Queries the module params.

See example response:

Copy { "params": { "sub_distributors": [ { "name": "tx_fee_distributor", "sources": [ { "id": "fee_collector", "type": "MODULE_ACCOUNT" } ], "destinations": { "primary_share": { "id": "c4e_distributor", "type": "MAIN" }, "shares": [], "burn_share": "0.000000000000000000" } }, { "name": "inflation_and_fee_distributor", "sources": [ { "id": "c4e_distributor", "type": "MAIN" } ], "destinations": { "primary_share": { "id": "validators_rewards_collector", "type": "MODULE_ACCOUNT" }, "shares": [ { "name": "development_fund", "share": "0.050000000000000000", "destination": { "id": "c4e10ep2sxpf2kj6jsdcs234edkuf9sf9xqq3sl", "type": "BASE_ACCOUNT" } }, { "name": "usage_incentives", "share": "0.350000000000000000", "destination": { "id": "usage_incentives_collector", "type": "INTERNAL_ACCOUNT" } } ], "burn_share": "0.000000000000000000" } }, { "name": "usage_incentives_distributor", "sources": [ { "id": "usage_incentives_collector", "type": "INTERNAL_ACCOUNT" } ], "destinations": { "primary_share": { "id": "c4e1q5vgy0r3scsdc32dcewkl8nwmfe2mgr6g0jlph", "type": "BASE_ACCOUNT" }, "shares": [ { "name": "green_energy_booster", "share": "0.340000000000000000", "destination": { "id": "green_energy_booster_collector", "type": "MODULE_ACCOUNT" } }, { "name": "governance_booster", "share": "0.330000000000000000", "destination": { "id": "governance_booster_collector", "type": "MODULE_ACCOUNT" } } ], "burn_share": "0.000000000000000000" } } ] } }

# States query

Queries the module state.

See example response:

Copy { "states": [ { "account": { "id": "c4e10ep2ssdfwefcscaewdedscs9xqqqdwqee3sl", "type": "BASE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.900000000000000000" } ] }, { "account": { "id": "c4e1q5vgy0r3w9q4ccsdcds23422mgr6g0jlph", "type": "BASE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.359000000000000000" } ] }, { "account": { "id": "governance_booster_collector", "type": "MODULE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.359000000000000000" } ] }, { "account": { "id": "green_energy_booster_collector", "type": "MODULE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.582000000000000000" } ] }, { "account": { "id": "usage_incentives_collector", "type": "INTERNAL_ACCOUNT" }, "burn": false, "remains": [] }, { "account": { "id": "validators_rewards_collector", "type": "MODULE_ACCOUNT" }, "burn": false, "remains": [ { "denom": "uc4e", "amount": "0.800000000000000000" } ] } ], "coins_on_distributor_account": [ { "denom": "uc4e", "amount": "3" } ] }

# Invariants

# Non-Negative Coin State Invariant

Invariant validates module state. Checks if all coins states of all destinations are non-negative

# State Sum Balance Check Invariant

Invariant validates module state. Checks sum of all coins states of one denom of all destinations is always integer value and is equal to cfedistributor module account balance

# Genesis validations