# Governance

Governance is the process from which users in the Secret Blockchain can come to consensus on software upgrades, parameters of the mainnet or signaling mechanisms through text proposals. This is done through voting on proposals, which will be submitted by SCRT holders on the mainnet.

Some considerations about the voting process:

  • Voting is done by bonded SCRT holders on a 1 bonded SCRT 1 vote basis.
  • Delegators inherit the vote of their validator if they don't vote.
  • Votes are tallied at the end of the voting period (1 week on mainnet) where each address can vote multiple times to update its Option value (paying the transaction fee each time), only the most recently cast vote will count as valid.
  • Voters can choose between options Yes, No, NoWithVeto and Abstain.
  • At the end of the voting period, a proposal is accepted IFF:
    • (YesVotes / (YesVotes+NoVotes+NoWithVetoVotes)) > 1/2 (threshold)
    • (NoWithVetoVotes / (YesVotes+NoVotes+NoWithVetoVotes)) < 1/3 (veto)
    • ((YesVotes+NoVotes+NoWithVetoVotes) / totalBondedStake) >= 1/3 (quorum)

For more information about the governance process and how it works, please check out the Governance module specification.

# Setup

# Create a Governance Proposal

In order to create a governance proposal, you must submit an initial deposit along with a title and description. Currently, in order to enter the voting period, a proposal must accumulate within a week deposits of at least 100 SCRT.

Note - Please remember through the duration of this guide that the secretcli counts SCRT in USCRT. 1 SCRT = 1,000,000 USCRT.

Various modules outside of governance may implement their own proposal types and handlers (eg. parameter changes), where the governance module itself supports Text proposals. Any module outside of governance has it's command mounted on top of submit-proposal.

# Text

To submit a Text proposal:

secretcli tx gov submit-proposal \
  --title <title> \
  --description <description> \
  --type Text \
  --deposit 100000000uscrt \
  --from <key_alias>

You may also provide the proposal directly through the --proposal flag which points to a JSON file containing the proposal:

secretcli tx gov submit-proposal --proposal <path/to/proposal.json> --from <key_alias>

Where proposal.json is:

  "type": "Text",
  "title": "My Cool Proposal",
  "description": "A description with line breaks \n and `code formatting`",
  "deposit": "100000000uscrt"

# Param Change

To submit a parameter change proposal, you must provide a proposal file as its contents are less friendly to CLI input:

secretcli tx gov submit-proposal param-change <path/to/proposal.json> --from <key_alias>

Where proposal.json is:

  "title": "Param Change: Update max validators",
  "description": "Update max validators with line breaks \n and `code formatting`",
  "changes": [
      "subspace": "Staking",
      "key": "MaxValidators",
      "value": 105
  "deposit": "10000000uscrt"

You can see another param-change example here: enigma-1-proposal-3.json

# Subspaces, Keys and Values

Subspace Key Type Example
auth MaxMemoCharacters string (uint64) "256"
auth TxSigLimit string (uint64) "7"
auth TxSizeCostPerByte string (uint64) "10"
auth SigVerifyCostED25519 string (uint64) "590"
auth SigVerifyCostSecp256k1 string (uint64) "1000"
baseapp BlockParams object {"max_bytes":"10000000","max_gas":"10000000"}
baseapp EvidenceParams object {"max_age_num_blocks":"100000","max_age_duration":"172800000000000","max_bytes":"50000"}
baseapp ValidatorParams object {"pub_key_types":["ed25519"]}
bank sendenabled bool true
crisis ConstantFee object (coin) {"denom": "uscrt", "amount": "1000"}
distribution communitytax string (dec) "0.020000000000000000"
distribution secretfoundationtax string (dec) "0.030000000000000000"
distribution secretfoundationaddress string "secret164z7wwzv84h4hwn6rvjjkns6j4ht43jv8u9k0c"
distribution baseproposerreward string (dec) "0.010000000000000000"
distribution bonusproposerreward string (dec) "0.040000000000000000"
distribution withdrawaddrenabled bool true
evidence MaxEvidenceAge string (time ns) "120000000000"
gov depositparams object {"min_deposit": [{"denom": "uscrt", "amount": "10000000"}], "max_deposit_period": "172800000000000"}
gov votingparams object {"voting_period": "172800000000000"}
gov tallyparams object {"quorum": "0.334000000000000000", "threshold": "0.500000000000000000", "veto": "0.334000000000000000"}
mint MintDenom string "uscrt"
mint InflationRateChange string (dec) "0.080000000000000000"
mint InflationMax string (dec) "0.150000000000000000"
mint InflationMin string (dec) "0.070000000000000000"
mint GoalBonded string (dec) "0.670000000000000000"
mint BlocksPerYear string (uint64) "6311520"
slashing SignedBlocksWindow string (int64) "5000"
slashing MinSignedPerWindow string (dec) "0.500000000000000000"
slashing DowntimeJailDuration string (time ns) "600000000000"
slashing SlashFractionDoubleSign string (dec) "0.050000000000000000"
slashing SlashFractionDowntime string (dec) "0.010000000000000000"
staking UnbondingTime string (time ns) "259200000000000"
staking MaxValidators uint16 100
staking KeyMaxEntries uint16 7
staking HistoricalEntries uint16 3
staking BondDenom string "uscrt"
ibc AllowedClients object (string[]) ["07-tendermint"]
ibc MaxExpectedTimePerBlock uint64 "30000000000"
transfer SendEnabled bool true
transfer ReceiveEnabled bool true

Please note:

  • The subspace is usually the ModuleName: E.g. https://github.com/cosmos/cosmos-sdk/blob/v0.38.1/x/distribution/types/keys.go#L11
  • The key is usually defined in x/$MODULE_NAME/types/params.go: E.g. https://github.com/cosmos/cosmos-sdk/blob/v0.38.1/x/distribution/types/params.go#L19-L22
  • The value's type is usually near the key definition: E.g. https://github.com/cosmos/cosmos-sdk/blob/v0.38.1/x/distribution/types/params.go#L26-L31
  • ⚠️ subspace and key are case sensitive and value must be of the correct type and within the allowed bounds. Proposals with errors on these inputs should not enter voting period (should not get deposits) or be voted on with NoWithVeto.
  • ⚠️ Currently parameter changes are evaluated but not validated, so it is very important that any value change is valid (i.e. correct type and within bounds) for its respective parameter, eg. MaxValidators should be an integer and not a decimal.
  • ⚠️ Proper vetting of a parameter change proposal should prevent this from happening (no deposits should occur during the governance process), but it should be noted regardless.
# Known Constraints
  • distribution.baseproposerreward + distribution.bonusproposerreward < 1. See this and this for more info.

To read more go to https://github.com/gavinly/CosmosParametersWiki.

# Community Pool Spend

To submit a community pool spend proposal, you also must provide a proposal file as its contents are less friendly to CLI input:

secretcli tx gov submit-proposal community-pool-spend <path/to/proposal.json> --from <key_alias>

Where proposal.json is:

  "title": "Community Pool Spend: Super important committee",
  "description": "Spend 10 SCRT with line breaks \n and `code formatting`",
  "recipient": "secret1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "amount": "100000000uscrt",
  "deposit": "100000000uscrt"

# Software Upgrade

The SoftwareUpgrade is currently not supported as it's not implemented and currently does not differ from the semantics of a Text proposal.

# Query Proposals

Once created, you can now query information of the proposal:

secretcli query gov proposal <proposal_id>

Or query all available proposals:

secretcli query gov proposals

You can also query proposals filtered by voter or depositor by using the corresponding flags.

To query for the proposer of a given governance proposal:

secretcli query gov proposer <proposal_id>

# Increase Deposit

If the proposal you previously created didn't meet the MinDeposit requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period:

secretcli tx gov deposit <proposal_id> "10000000uscrt" --from <key_alias>

NOTE: Proposals that don't meet this requirement will be deleted after MaxDepositPeriod is reached.

The only ways deposits won't be returned to their owners is:

  1. If in the voting period the proposal gets 1/3 NoWithVeto out of all votes, excluding Abstain votes (So NoWithVeto needs to be 1/3 out of all Yes, No & NoWithVeto ).
  2. If in the voting period less than 1/3 of voting power votes (== The proposal won't reach a quorum).

Anyone can deposit for a proposal, even if you have 0 SCRT tokens staked/delegated/bonded.

# Query Deposits

Once a new proposal is created, you can query all the deposits submitted to it:

secretcli query gov deposits <proposal_id>

You can also query a deposit submitted by a specific address:

secretcli query gov deposit <proposal_id> <depositor_address>

# Vote on a Proposal

After a proposal's deposit reaches the MinDeposit value, the voting period opens. Bonded SCRT holders can then cast vote on it:

secretcli tx gov vote <proposal_id> <Yes/No/NoWithVeto/Abstain> --from <key_alias>

# Query Votes

Check the vote with the option you just submitted:

secretcli query gov vote <proposal_id> <voter_address>

You can also get all the previous votes submitted to the proposal with:

secretcli query gov votes <proposal_id>

# Query proposal tally results

To check the current tally of a given proposal you can use the tally command:

secretcli query gov tally <proposal_id>

# Query Governance Parameters

To check the current governance parameters run:

secretcli query gov params

To query subsets of the governance parameters run:

secretcli query gov param voting
secretcli query gov param tallying
secretcli query gov param deposit