Skip to main content

distribution

Abstract​

This document specifies the additions by Guru to the existing x/distribution module of the Cosmos-sdk.

x/distribution describes the full documentation for the base version of distribution module. Everything defined on the cosmos-sdk documentation also apply to Guru with additions on fee distribution ratio.

We implemented Guru-specific wrapper on top of existing distribution module by keeping all the existing functionalities and use-cases. This page is dedicated to describe only the additions made by Guru team.

The x/distribution module enables the Guru to support a customizable fee distribution over different parties and allow to control inflation by burning the fees partially.

Contents​

  1. Concepts
  2. State
  3. Begin Block
  4. Events
  5. Clients

Concepts​

Fee Ratio​

Fee ratio defines the distribution ratio for the collected fee for each begin-block. There are three ratio options as follows:

  • burn
  • base
  • staking rewards

Burn Fee​

The x/distribution module allows to burn a portion of collected fees during each begin-block. This allows the Guru chain to manage the inflation. The burn ratio is configrable by the moderator_address and can be disabled if not needed.

Base Fee​

The base ratio defines the portion of the fees that will be incentivized to the state-defined base_address.

The base_address can be the central address which belongs to the service providers, organization or the manager juristiction.

Staking Rewards​

The remaining of the total colelcted fees, will be distributed among validators, delegators and community pool following the cosmos-sdk x/distribution module protocol.

Notes​

  • The sum of base, burn and staking_rewards ratio should always be equal to 1.0
  • base portion fo the fees are added to staking_rewards in case of the base_address is not defined in the module state

Moderator​

moderator is the custom role for the x/distribution module with the full permission of changing the fee ratio. Genesis state defines the address for the moderator, or it can be set later through gov proposal.

State​

The x/distribution module keeps the state variables needed for fee ratio calculation.

DescriptionKeyValueStore
ModeratorAdressmodule moderator address[]byte{10}[]byte{string}KV
BaseAdressbase address to receive the fees[]byte{11}[]byte{string}KV
Ratiofee distribution ratio[]byte{12}[]byte{ratio}KV

Genesis​

Moderator Address​

If the moderator_address is not defined at the genesis state, the gov module address is defined as the default moderator.

Base Address​

There is no default state for the base_address. If not defined, the base ratio will be added to staking_rewards

Ratio​

If the ratio is not defined at the genesis state, the ratio will be equally distributed among three options:

burn:            0.333333333333333333
base: 0.333333333333333333
staking_rewards: 0.333333333333333334

Begin Block​

The CollectedFees are distributed by the ratio at the beginning of each block.

Events​

The x/distribution module emits the following events:

BeginBlocker​

TypeAttribute KeyAttribute Value
burn_feeamount{BurnAmount}
base_feeamount{BaseAmount}

The staking_rewards events are same as in the cosmos-sdk distribution module.

MsgChangeModerator​

TypeAttribute KeyAttribute Value
change_moderator_addressmoderator{moderatorAddress}
change_moderator_addressaddress{newModeratorAddress}

Clients​

CLI​

A user can query and interact with the distribution module using the CLI.

Queries​

The query commands allow users to query distribution state.

CommandSubcommandDescription
query distributionratioGet current fee ratio
query distributionbase-addressGet current base address
query distributionmoderator-addressGet current moderator address
gurud query distribution --help
Ratio​

The ratio command allows users to query the current state of fee distribution ratio.

gurud query distribution ratio [flags]

Example:

gurud query distribution ratio ...

Example Output:

ratio:
base: "0.333333333333333333"
burn: "0.333333333333333333"
staking_rewards: "0.333333333333333334"
BaseAddress​

The base-address command allows users to query the current base address.

gurud query distribution base-address [address] [flags]

Example:

gurud query distribution base-address ...

Example Output:

base-address: guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3
ModeratorAddress​

The moderator_address command allows users to query the current moderator address.

gurud query distribution moderator-address [flags]

Example:

gurud query distribution moderator-address ...

Example Output:

moderator-address: guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3

Transactions​

The tx commands allow the moderator to change the feepolicy state.

CommandSubcommandDescription
tx distributionchange-ratioChange the current state of ratio
tx distributionchange-base-addressSet/change the current base address
tx distributionchange-moderatorChange the moderator address
ChangeRatio​

The change-ratio command allows the moderator to change the current state of the distribution ratio.

gurud tx distribution change-ratio STAKING_REWARDS BASE BURN [flags]

Example:

gurud tx distribution change-ratio 0.9 0.1 0 --from moderator_address ...
ChangeBaseAddress​

The change-base-address command allows the moderator to change the set/change the base address.

gurud tx distribution change-base-address NEW_BASE_ADDRESS [flags]

Example:

gurud tx distribution change-base-address guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3 --from moderator_address ...
ChangeModerator​

The change-moderator command allows the moderator to change the current moderator address.

gurud tx distribution change-moderator NEW_MODERATOR_ADDRESS [flags]

Example:

gurud tx distribution change-moderator guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3 --from moderator_address ...

Proposals​

The x/distribution module accept gov proposal for all moderator-specific transactions only if the moderator_address is the gov module address. Once the moderator_address is changed to EOA, gov proposals are no longer be authorized for such transaction.