cfedistributor

Chain4Energy distributor module - 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.

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.

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

• transaction fees subdistributor

• module fees subdistributor

• incentive boosters subdistributor

Parameters

The Chain4Energy distributor module contains the following configurations parameters:

Subdistributor type

Destinations type

DestinationShare type

Account type

Example params

See the configuration params for example from Concept section

{
    "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:

State type

Example state

See the state for example from Concept section

[
    {
        "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

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

DistributionBurn type represents one burn operation

Queries

Params query

Queries the module params.

See example response:

{
  "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:

{
  "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