Overview of Governance on Matic


Heimdall governance works exactly the same as Cosmos-sdk x/gov module. https://docs.cosmos.network/master/modules/gov/

In this system, holders of the native staking token of the chain can vote on proposals on a 1 token - 1 vote basis. Next is a list of features the module currently supports:

  • Proposal submission: Validators can submit proposals with a deposit. Once the minimum deposit is reached, the proposal enters the 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 the gov module. Minimum deposit will be achieved before the deposit period ends, otherwise the proposal will be automatically rejected.

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

Source: https://github.com/maticnetwork/heimdall/blob/develop/gov/endblocker.go

There are different types of proposals that can be implemented in Heimdall but as of now, it supports only one proposal:

  • 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 the auth module. When the proposal gets accepted, it automatically changes the params in Heimdall state. No extra TX is needed.

CLI commands

Query gov params

heimdallcli query gov params --trust-node

This shows all params for the governance module.

  voting_period: 48h0m0s
  quorum: "334000000000000000"
  threshold: "500000000000000000"
  veto: "334000000000000000"
  - denom: matic
      i: "10000000000000000000"
  max_deposit_period: 48h0m0s

Submit a proposal

heimdallcli tx gov submit-proposal \
	--validator-id 1 param-change proposal.json \
	--chain-id <heimdall-chain-id>

proposal.json is a file that includes proposal in JSON format.

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

Query proposal

To query all proposals

heimdallcli query gov proposals --trust-node

To query a particular proposal

heimdallcli query gov proposals 1 --trust-node

Vote on proposal

To vote on a particular proposal

heimdallcli tx gov vote 1 "Yes" --validator-id 1  --chain-id <heimdal-chain-id>

The proposal will be automatically tallied after the voting period.


Name Method Endpoint
Get all proposals GET /gov/proposals
Get proposal details GET /gov/proposals/proposal-id
Get all votes for the proposal GET /gov/proposals/proposal-id/votes

Hey everyone, so does this mean that the consensus needs threshold: β€œ500000000000000000” votes to pass ?

Hey @JennCrypto, the threshold is 50% of all votes cast for a particular proposal, once a 33,4% quroum is reached.

By the way, we’re currently working on updating our governance-related documentation to increase the general understanding of the system.