gov

package
v1.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2024 License: GPL-3.0 Imports: 27 Imported by: 0

README

Governance Module

Table of Contents

Overview

Heimdall governance works exactly the same as Cosmos-sdk's gov module. In this system, holders of the native staking token of the chain can vote on proposals on a 1 token = 1 vote basis. Here is a list of features the module currently supports:

  • Proposal submission: Validators can submit proposals with a deposit. Once the minimum deposit is reached, proposal enters voting period. Validators that deposited on proposals can recover their deposits once the proposal is rejected or accepted.
  • Vote: Validators can vote on proposals that reached MinDeposit.

There are deposit period and voting period as params in gov module. Minimum deposit has to be achieved before deposit period ends, otherwise proposal will be automatically rejected.

Once minimum deposits reached within deposit period, voting period starts. In voting period, all validators should vote their choices for the proposal. After voting period ends, gov/endblocker.go executes tally function and accepts or rejects proposal based on tally_params — quorum, threshold and veto.

There are different types of proposals that can be implemented in Heimdall. As of now, it supports only the Param change proposal.

Param change proposal

Using this type of proposal, validators can change any params in any module of Heimdall.

Example: change minimum tx_fees for the transaction in auth module. When the proposal gets accepted, it automatically changes the params in Heimdall state. No extra TX is needed.

Commands

One can run the following commands from the governance module:

Query Commands
  • proposal - Query details of a single proposal
  • proposals - Query proposals with optional filters
  • vote - Query details of a single vote
  • votes - Query votes on a proposal
  • deposit - Query details of a deposit
  • deposits - Query deposits on a proposal
  • tally - Get the tally of a proposal vote
  • params - Query the parameters of the governance process
  • param - Query the parameters (voting|tallying|deposit) of the governance process
  • proposer - Query the proposer of a governance proposal
Tx Commands
  • submit-proposal - Submit a proposal along with an initial deposit
  • deposit - Deposit tokens for an active proposal
  • vote - Vote for an active proposal with options: yes/no/no_with_veto/abstain
Run Using CLI
heimdallcli query gov proposal [proposal-id]

heimdallcli query gov proposals

heimdallcli query gov vote [proposal-id] [voter-id]

heimdallcli query gov votes [proposal-id]

heimdallcli query gov deposit [proposal-id] [depositer-addr]

heimdallcli query gov deposits [proposal-id]

heimdallcli query gov tally [proposal-id]

heimdallcli query gov params

heimdallcli query gov param [param-type]

heimdallcli query gov proposer [proposal-id]

heimdallcli tx gov submit-proposal --proposal proposal.json --from key

where proposal.json will have

{
  "title": "Auth Param Change",
  "description": "Update max tx gas",
  "changes": [
    {
      "subspace": "auth",
      "key": "MaxTxGas",
      "value": "2000000"
    }
  ],
  "deposit": [
    {
      "denom": "matic",
      "amount": "1000000000000000000"
    }
  ]
}

heimdallcli tx gov deposit [proposal-id] [stake]

heimdallcli tx gov vote [proposal-id] [option] --validator-id 1  --chain-id <heimdall-chain-id>

with options from yes/no/no_with_veto/abstain, Like

heimdallcli tx gov vote 1 "Yes" --validator-id 1  --chain-id <heimdal-chain-id>
Run Using REST
curl "localhost:1317/gov/proposals"

curl "localhost:1317/gov/proposals/{proposal-id}"

curl "localhost:1317/gov/proposals/{proposal-id}/votes"

curl "localhost:1317/gov/proposals/{proposal-id}/votes/{voter-id}"

curl "localhost:1317/gov/proposals/{proposal-id}/deposits"

curl "localhost:1317/gov/proposals/{proposal-id}/deposits/{depositer-addr}"

curl "localhost:1317/gov/proposals/{proposal-id}/tally"

curl "localhost:1317/gov/params"

curl "localhost:1317/gov/proposals/{proposal-id}/proposer"

Documentation

Index

Constants

View Source 
const (
	// DefaultPeriod default period for deposits & voting
	DefaultPeriod time.Duration = 86400 * 2 * time.Second // 2 days
)

Variables

This section is empty.

Functions

func AllInvariants 

func AllInvariants(keeper Keeper) sdk.Invariant

AllInvariants runs all invariants of the governance module

func EndBlocker 

func EndBlocker(ctx sdk.Context, keeper Keeper)

EndBlocker called every block, process inflation, update validator set.

func InitGenesis 

func InitGenesis(ctx sdk.Context, k Keeper, supplyKeeper SupplyKeeper, data GenesisState)

InitGenesis - store genesis parameters

func ModuleAccountInvariant 

func ModuleAccountInvariant(keeper Keeper) sdk.Invariant

ModuleAccountInvariant checks that the module account coins reflects the sum of deposit amounts held on store

func NewHandler 

func NewHandler(keeper Keeper) sdk.Handler

NewHandler handle all "gov" type messages.

func NewQuerier 

func NewQuerier(keeper Keeper) sdk.Querier

func RegisterInvariants 

func RegisterInvariants(ir sdk.InvariantRegistry, keeper Keeper)

RegisterInvariants registers all governance invariants

func ValidateGenesis 

func ValidateGenesis(data GenesisState) error

ValidateGenesis checks if parameters are within valid ranges

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

___________________________ app module

func NewAppModule 

func NewAppModule(keeper Keeper, supplyKeeper SupplyKeeper) AppModule

NewAppModule creates a new AppModule object

func (AppModule) BeginBlock 

func (AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

module begin-block

func (AppModule) EndBlock 

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

module end-block

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context) json.RawMessage

module export genesis

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, data json.RawMessage) []abci.ValidatorUpdate

module init-genesis

func (AppModule) Name 

func (AppModule) Name() string

module name

func (AppModule) NewHandler 

func (am AppModule) NewHandler() sdk.Handler

module handler

func (AppModule) NewQuerierHandler 

func (am AppModule) NewQuerierHandler() sdk.Querier

module querier

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

module querier route name

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(ir sdk.InvariantRegistry)

register invariants

func (AppModule) Route 

func (AppModule) Route() string

module message route name

type AppModuleBasic 

type AppModuleBasic struct {
	// contains filtered or unexported fields
}

app module basics object

func NewAppModuleBasic 

func NewAppModuleBasic(proposalHandlers ...client.ProposalHandler) AppModuleBasic

NewAppModuleBasic creates a new AppModuleBasic object

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis() json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the auth module.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd(cdc *codec.Codec) *cobra.Command

get the root query command of this module

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd(cdc *codec.Codec) *cobra.Command

get the root tx command of this module

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

module name

func (AppModuleBasic) RegisterCodec 

func (AppModuleBasic) RegisterCodec(cdc *codec.Codec)

register module codec

func (AppModuleBasic) RegisterRESTRoutes 

func (a AppModuleBasic) RegisterRESTRoutes(ctx context.CLIContext, rtr *mux.Router)

register rest routes

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the auth module.

func (AppModuleBasic) VerifyGenesis 

func (AppModuleBasic) VerifyGenesis(bz map[string]json.RawMessage) error

VerifyGenesis performs verification on gov module state.

type GenesisState 

type GenesisState struct {
	StartingProposalID uint64              `json:"starting_proposal_id" yaml:"starting_proposal_id"`
	Deposits           types.Deposits      `json:"deposits" yaml:"deposits"`
	Votes              types.Votes         `json:"votes" yaml:"votes"`
	Proposals          []types.Proposal    `json:"proposals" yaml:"proposals"`
	DepositParams      types.DepositParams `json:"deposit_params" yaml:"deposit_params"`
	VotingParams       types.VotingParams  `json:"voting_params" yaml:"voting_params"`
	TallyParams        types.TallyParams   `json:"tally_params" yaml:"tally_params"`
}

GenesisState - all staking state that must be provided at genesis

func DefaultGenesisState 

func DefaultGenesisState() GenesisState

DefaultGenesisState get raw genesis raw message for testing

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, k Keeper) GenesisState

ExportGenesis - output genesis parameters

func NewGenesisState 

func NewGenesisState(startingProposalID uint64, dp types.DepositParams, vp types.VotingParams, tp types.TallyParams) GenesisState

NewGenesisState creates a new genesis state for the governance module

func (GenesisState) Equal 

func (data GenesisState) Equal(data2 GenesisState) bool

Equal checks whether 2 GenesisState structs are equivalent.

func (GenesisState) IsEmpty 

func (data GenesisState) IsEmpty() bool

IsEmpty returns if a GenesisState is empty or has data in it

type Keeper 

type Keeper struct {
	// contains filtered or unexported fields
}

Keeper governance Keeper

func NewKeeper 

func NewKeeper(
	cdc *codec.Codec,
	key sdk.StoreKey,
	paramSpace subspace.Subspace,
	supplyKeeper supply.Keeper,
	sk staking.Keeper,
	codespace sdk.CodespaceType,
	rtr Router,
) Keeper

NewKeeper returns a governance keeper. It handles: - submitting governance proposals - depositing funds into proposals, and activating upon sufficient funds being deposited - users voting on proposals, with weight proportional to stake in the system - and tallying the result of the vote.

func (Keeper) ActiveProposalQueueIterator 

func (keeper Keeper) ActiveProposalQueueIterator(ctx sdk.Context, endTime time.Time) sdk.Iterator

ActiveProposalQueueIterator returns an sdk.Iterator for all the proposals in the Active Queue that expire by endTime

func (Keeper) AddDeposit 

func (keeper Keeper) AddDeposit(ctx sdk.Context, proposalID uint64, depositorAddr hmTypes.HeimdallAddress, depositAmount sdk.Coins, validator hmTypes.ValidatorID) (sdk.Error, bool)

AddDeposit adds or updates a deposit of a specific depositor on a specific proposal Activates voting period when appropriate

func (Keeper) AddVote 

func (keeper Keeper) AddVote(ctx sdk.Context, proposalID uint64, voter hmTypes.HeimdallAddress, option types.VoteOption, validator hmTypes.ValidatorID) sdk.Error

AddVote Adds a vote on a specific proposal

func (Keeper) Codespace 

func (k Keeper) Codespace() sdk.CodespaceType

Codespace returns the codespace

func (Keeper) DeleteProposal 

func (keeper Keeper) DeleteProposal(ctx sdk.Context, proposalID uint64)

DeleteProposal deletes a proposal from store

func (Keeper) GetAllDeposits 

func (keeper Keeper) GetAllDeposits(ctx sdk.Context) (deposits types.Deposits)

GetAllDeposits returns all the deposits from the store

func (Keeper) GetAllVotes 

func (keeper Keeper) GetAllVotes(ctx sdk.Context) (votes types.Votes)

GetAllVotes returns all the votes from the store

func (Keeper) GetDeposit 

func (keeper Keeper) GetDeposit(ctx sdk.Context, proposalID uint64, validator hmTypes.ValidatorID) (deposit types.Deposit, found bool)

GetDeposit gets the deposit of a specific depositor on a specific proposal

func (Keeper) GetDepositParams 

func (keeper Keeper) GetDepositParams(ctx sdk.Context) types.DepositParams

Returns the current DepositParams from the global param store

func (Keeper) GetDeposits 

func (keeper Keeper) GetDeposits(ctx sdk.Context, proposalID uint64) (deposits types.Deposits)

GetDeposits returns all the deposits from a proposal

func (Keeper) GetDepositsIterator 

func (keeper Keeper) GetDepositsIterator(ctx sdk.Context, proposalID uint64) sdk.Iterator

GetDepositsIterator gets all the deposits on a specific proposal as an sdk.Iterator

func (Keeper) GetGovernanceAccount 

func (keeper Keeper) GetGovernanceAccount(ctx sdk.Context) supplyTypes.ModuleAccountInterface

GetGovernanceAccount returns the governance ModuleAccount

func (Keeper) GetProposal 

func (keeper Keeper) GetProposal(ctx sdk.Context, proposalID uint64) (proposal types.Proposal, ok bool)

GetProposal get Proposal from store by ProposalID

func (Keeper) GetProposalID 

func (keeper Keeper) GetProposalID(ctx sdk.Context) (proposalID uint64, err sdk.Error)

GetProposalID gets the highest proposal ID

func (Keeper) GetProposals 

func (keeper Keeper) GetProposals(ctx sdk.Context) (proposals types.Proposals)

GetProposals returns all the proposals from store

func (Keeper) GetProposalsFiltered 

func (keeper Keeper) GetProposalsFiltered(ctx sdk.Context, voterID hmTypes.ValidatorID, depositorID hmTypes.ValidatorID, status types.ProposalStatus, numLatest uint64) []types.Proposal

GetProposalsFiltered get Proposals from store by ProposalID voterAddr will filter proposals by whether or not that address has voted on them depositorAddr will filter proposals by whether or not that address has deposited to them status will filter proposals by status numLatest will fetch a specified number of the most recent proposals, or 0 for all proposals

func (Keeper) GetTallyParams 

func (keeper Keeper) GetTallyParams(ctx sdk.Context) types.TallyParams

Returns the current TallyParam from the global param store

func (Keeper) GetVote 

func (keeper Keeper) GetVote(ctx sdk.Context, proposalID uint64, voter hmTypes.ValidatorID) (vote types.Vote, found bool)

GetVote gets the vote from an address on a specific proposal

func (Keeper) GetVotes 

func (keeper Keeper) GetVotes(ctx sdk.Context, proposalID uint64) (votes types.Votes)

GetVotes returns all the votes from a proposal

func (Keeper) GetVotesIterator 

func (keeper Keeper) GetVotesIterator(ctx sdk.Context, proposalID uint64) sdk.Iterator

GetVotesIterator gets all the votes on a specific proposal as an sdk.Iterator

func (Keeper) GetVotingParams 

func (keeper Keeper) GetVotingParams(ctx sdk.Context) types.VotingParams

Returns the current VotingParams from the global param store

func (Keeper) InactiveProposalQueueIterator 

func (keeper Keeper) InactiveProposalQueueIterator(ctx sdk.Context, endTime time.Time) sdk.Iterator

InactiveProposalQueueIterator returns an sdk.Iterator for all the proposals in the Inactive Queue that expire by endTime

func (Keeper) InsertActiveProposalQueue 

func (keeper Keeper) InsertActiveProposalQueue(ctx sdk.Context, proposalID uint64, endTime time.Time)

InsertActiveProposalQueue inserts a ProposalID into the active proposal queue at endTime

func (Keeper) InsertInactiveProposalQueue 

func (keeper Keeper) InsertInactiveProposalQueue(ctx sdk.Context, proposalID uint64, endTime time.Time)

InsertInactiveProposalQueue Inserts a ProposalID into the inactive proposal queue at endTime

func (Keeper) IterateActiveProposalsQueue 

func (keeper Keeper) IterateActiveProposalsQueue(ctx sdk.Context, endTime time.Time, cb func(proposal types.Proposal) (stop bool))

IterateActiveProposalsQueue iterates over the proposals in the active proposal queue and performs a callback function

func (Keeper) IterateAllDeposits 

func (keeper Keeper) IterateAllDeposits(ctx sdk.Context, cb func(deposit types.Deposit) (stop bool))

IterateAllDeposits iterates over the all the stored deposits and performs a callback function

func (Keeper) IterateAllVotes 

func (keeper Keeper) IterateAllVotes(ctx sdk.Context, cb func(vote types.Vote) (stop bool))

IterateAllVotes iterates over the all the stored votes and performs a callback function

func (Keeper) IterateDeposits 

func (keeper Keeper) IterateDeposits(ctx sdk.Context, proposalID uint64, cb func(deposit types.Deposit) (stop bool))

IterateDeposits iterates over the all the proposals deposits and performs a callback function

func (Keeper) IterateInactiveProposalsQueue 

func (keeper Keeper) IterateInactiveProposalsQueue(ctx sdk.Context, endTime time.Time, cb func(proposal types.Proposal) (stop bool))

IterateInactiveProposalsQueue iterates over the proposals in the inactive proposal queue and performs a callback function

func (Keeper) IterateProposals 

func (keeper Keeper) IterateProposals(ctx sdk.Context, cb func(proposal types.Proposal) (stop bool))

IterateProposals iterates over the all the proposals and performs a callback function

func (Keeper) IterateVotes 

func (keeper Keeper) IterateVotes(ctx sdk.Context, proposalID uint64, cb func(vote types.Vote) (stop bool))

IterateVotes iterates over the all the proposals votes and performs a callback function

func (Keeper) Logger 

func (keeper Keeper) Logger(ctx sdk.Context) log.Logger

Logger returns a module-specific logger.

func (Keeper) RefundDeposits 

func (keeper Keeper) RefundDeposits(ctx sdk.Context, proposalID uint64)

RefundDeposits refunds and deletes all the deposits on a specific proposal

func (Keeper) RemoveFromActiveProposalQueue 

func (keeper Keeper) RemoveFromActiveProposalQueue(ctx sdk.Context, proposalID uint64, endTime time.Time)

RemoveFromActiveProposalQueue removes a proposalID from the Active Proposal Queue

func (Keeper) RemoveFromInactiveProposalQueue 

func (keeper Keeper) RemoveFromInactiveProposalQueue(ctx sdk.Context, proposalID uint64, endTime time.Time)

RemoveFromInactiveProposalQueue removes a proposalID from the Inactive Proposal Queue

func (Keeper) SetProposal 

func (keeper Keeper) SetProposal(ctx sdk.Context, proposal types.Proposal)

SetProposal set a proposal to store

func (Keeper) SubmitProposal 

func (keeper Keeper) SubmitProposal(ctx sdk.Context, content types.Content) (types.Proposal, sdk.Error)

SubmitProposal create new proposal given a content

type Router 

type Router interface {
	AddRoute(r string, h types.Handler) (rtr Router)
	HasRoute(r string) bool
	GetRoute(path string) (h types.Handler)
	Seal()
}

Router implements a governance Handler router.

TODO: Use generic router (ref #3976).

func NewRouter 

func NewRouter() Router

type SupplyKeeper 

type SupplyKeeper interface {
	GetModuleAddress(name string) hmTypes.HeimdallAddress
	GetModuleAccount(ctx sdk.Context, name string) supplyTypes.ModuleAccountInterface

	// TODO remove with genesis 2-phases refactor https://github.com/cosmos/cosmos-sdk/issues/2862
	SetModuleAccount(sdk.Context, supplyTypes.ModuleAccountInterface)

	SendCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr hmTypes.HeimdallAddress, amt sdk.Coins) sdk.Error
	SendCoinsFromAccountToModule(ctx sdk.Context, senderAddr hmTypes.HeimdallAddress, recipientModule string, amt sdk.Coins) sdk.Error
}

SupplyKeeper defines the supply Keeper for module accounts

Source Files

View all Source files

Directories

Path Synopsis
cli
rest
nolint
 nolint
utils
nolint
 nolint

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.