gov

README

Custom Gov

The customgov module is wrapper around Cosmos SDK's vanilla gov module, inheriting most of its functionalities, with two changes:

• A custom vote tallying logic. Namely, tokens locked in the vesting contract count towards one's governance voting power.
• Type check proposal and vote metadata.

Tallying

Let's illustrate this by an example.

Consider a blockchain with only one validator, as well as two users, Alice and Bob, who have the following amounts of tokens:

user	staked	vesting
Alice	30	21
Bob	49	0

Assume the validator votes YES on a proposal, while neither Alice or Bob votes. In this case, the validator will vote on behalf of Alice and Bob's staked tokens. The vote will pass with 30 + 49 = 79 tokens voting YES and the rest 21 tokens not voting.

If Alice votes NO, this overrides the validator's voting. The vote will be defeated by 49 tokens voting YES vs 51 tokens voting NO.

Note

Currently, the module assumes the vesting contract is the first contract to be deployed on the chain, i.e. having the code ID of 1 and instance ID of 1. The module uses this info to derive the contract's address. Developers must make sure this is the case in the chain's genesis state.

Why not make it a configurable parameter? Because doing so involves modifying gov module's Params type definition which breaks a bunch of things, which we prefer not to.

Metadata

From Cosmos SDK v0.46, governance proposals no longer have a "title" and a "description", but instead a "metadata" which can be an arbitrary string. According to the docs, the recommended way to provide the metadata is to store it off-chain, and only upload an IPFS hash on-chain. Therefore, the vanilla gov module:

• Has a default 255 character limit for the metadata string
• Does not enforce a schema of the metadata string

In Mars customgov, we want to storage the metadata on-chain. In order for this to work, we increase the length limit to u64::MAX, essentially without a limit. Additionally, we implement type checks for the metadata. Specifically,

• For proposal metadata, we assert that it is non-empty and conforms to this schema (defined in TypeScript):

  type ProposalMetadata = {
    title: string;
    authors?: string[];
    summary: string;
    details?: string;
    proposal_forum_url?: string;
    vote_option_context?: string;
  };
  

  We make title and summary mandatory and the other fields optional, because from sdk 0.47 proposals will have mandatory title and summary fields. Once Mars Hub upgrades to sdk 0.47, we can make these two fields optional as well.

• For vote metadata, we assert that it is either an empty string (it's ok if a voter doesn't want to provide a rationale for their vote), or if it's not empty, conforms to this schema:

  type VoteMetadata = {
    justification?: string;
  };
  

Documentation

Index

• func EndBlocker(ctx sdk.Context, keeper keeper.Keeper)
• type AppModule
  • func NewAppModule(cdc codec.Codec, keeper keeper.Keeper, ak govtypes.AccountKeeper, ...) AppModule
  • func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate
  • func (am AppModule) RegisterServices(cfg module.Configurator)

Functions

func EndBlocker

func EndBlocker(ctx sdk.Context, keeper keeper.Keeper)

EndBlocker called at the end of every block, processing proposals

This is pretty much the same as the vanilla gov EndBlocker, except for we replace the `Tally` function with our own implementation.

Types

type AppModule

type AppModule struct {
	gov.AppModule
	// contains filtered or unexported fields
}

AppModule implements an application module for the custom gov module

NOTE: our custom AppModule wraps the vanilla `gov.AppModule` to inherit most of its functions. However, we overwrite the `EndBlock` function to replace it with our custom vote tallying logic.

func NewAppModule

func NewAppModule(cdc codec.Codec, keeper keeper.Keeper, ak govtypes.AccountKeeper, bk govtypes.BankKeeper) AppModule

NewAppModule creates a new AppModule object

func (AppModule) EndBlock

func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock returns the end blocker for the gov module. It returns no validator updates.

NOTE: this overwrites the vanilla gov module EndBlocker with our custom vote tallying logic.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers module services.

NOTE: this overwrites the vanilla gov module RegisterServices function