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.

	Description	Key	Value	Store
ModeratorAdress	module moderator address	[]byte{10}	[]byte{string}	KV
BaseAdress	base address to receive the fees	[]byte{11}	[]byte{string}	KV
Ratio	fee 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

Type	Attribute Key	Attribute Value
burn_fee	amount	{BurnAmount}
base_fee	amount	{BaseAmount}

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

MsgChangeModerator

Type	Attribute Key	Attribute Value
change_moderator_address	moderator	{moderatorAddress}
change_moderator_address	address	{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.

Command	Subcommand	Description
query distribution	ratio	Get current fee ratio
query distribution	base-address	Get current base address
query distribution	moderator-address	Get 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.

Command	Subcommand	Description
tx distribution	change-ratio	Change the current state of ratio
tx distribution	change-base-address	Set/change the current base address
tx distribution	change-moderator	Change 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.