1 of 5

Governance

Introduction

Governance is the process of Secret Network users coming 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.

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

To setup governance the secretcli must be installed. You can get a detailed description of how to install the secretcli here.

Creating Governance Proposals

Introduction

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 .

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

Modules

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.

Submit-Proposal

Proposals can be submitted using secretcli tx gov submit-proposal.

Using secretcli tx gov draft-proposal can help prepare a proposal. The tool will create a file containing the specified proposal message and it also helps with populating all the required proposal fields. You can always edit the file after you create it using draft-proposal

To submit a proposal:

metadata example:

Text

To submit a Text proposal:

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

Where proposal.json is:

Param Change

Most cosmos-sdk modules allow changing their governance gated parameters using a MsgUpdateParams which is a new way of updating governance parameters. It is important to note that MsgUpdateParams requires all parameters to be specified in the proposal message.

We will use draft-proposal to help us create a proposal file that we will later submit.

After choosing the /cosmos.staking.v1beta1.MsgUpdateParams message, the applet will allow you to set the message fields and some other proposal details. Upon completion, the proposal will be available in the directory where you called the gaiad command inside the draft_proposal.json file.

Here is an example of the draft_proposal.json file:

Finally, we submit the proposal:

Subspaces, Keys and Values

Further Proposal Details

The subspace is usually the ModuleName
The key is usually defined in x/$MODULE_NAME/types/params.go
The value's type is usually near the key definition
⚠️ 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

Community Pool Spend

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

We can createproposal.json using tx gov draft-proposal

Software Upgrade

To submit a software upgrade proposal use:

We can createproposal.json using tx gov draft-proposal

Query Proposals

Available Commands

Querying Proposals

Query Using Proposal ID

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

Query For All Proposals

You can query for all available proposals using:

Query For Proposal Depositor

You can query for the proposal depositor using:

Query For Proposal Depositors

You can query for the proposal depositors using:

Query For Proposal Voter

You can query for the proposal voter using:

Query for Proposal Proposer

To query for the proposer of a given governance proposal use:

Query Proposal Tally Results

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

Query Governance Proposals

To check the current governance parameters run:

Querying Subsets of Governance Proposals

Voting

To query subsets of the governance parameters for voting run:

Tallying

To query subsets of the governance parameters for tallying run:

Deposit

To query subsets of the deposit governance parameters for voting run:

Deposits

Increasing Deposits

If the proposal you previously created didn't meet the MinDeposit requirement, you can still increase the total amount deposited to activate it.

Note: Proposals not meeting this requirement will be deleted after MaxDepositPeriod is reached.

Once the minimum deposit is reached, the proposal enters voting period:

Note: The regular flags for the tx command are applicable to gov deposit (--fees, --gas, --account-number --ledger, --node, etc...)

Returning Deposits

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

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 ).
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.

Querying Deposits

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

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

Flags

There are several flags to use with secretcli query gov deposit:

Voting

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

Flags

Creating Governance Proposals

Introduction

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

Modules

Submit-Proposal

Proposals can be submitted using secretcli tx gov submit-proposal.

To submit a proposal:

metadata example:

{
        "title": "",
        "authors": [""],
        "summary": "",
        "details": "",
        "proposal_forum_url": "",
        "vote_option_context": "",
}

Text

To submit a Text proposal:

secretcli tx gov submit-legacy-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-legacy-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

We will use draft-proposal to help us create a proposal file that we will later submit.

secretcli tx gov draft-proposal
// running the command will start a terminal applet allowing you to choose the proposal type

// 1st screen
Use the arrow keys to navigate: ↓ ↑ → ←
? Select proposal type:
    text
    community-pool-spend
    software-upgrade
    cancel-software-upgrade
  ▸ other // choose this

// 2nd screen
✔ other
Use the arrow keys to navigate: ↓ ↑ → ←
? Select proposal message type::
↑   /cosmos.staking.v1beta1.MsgUndelegate
  ▸ /cosmos.staking.v1beta1.MsgUpdateParams // choose this option
    /cosmos.staking.v1beta1.MsgValidatorBond
    /cosmos.upgrade.v1beta1.MsgCancelUpgrade
↓   /cosmos.upgrade.v1beta1.MsgSoftwareUpgrade

Here is an example of the draft_proposal.json file:

{
 "messages": [
  {
   "@type": "/cosmos.staking.v1beta1.MsgUpdateParams",
   "authority": "secret1...",
   "params": {
    "unbonding_time": "0s",
    "max_validators": 0,
    "max_entries": 0,
    "historical_entries": 0,
    "bond_denom": "",
    "min_commission_rate": "0.000000000000000000"
   }
  }
 ],
 "metadata": "ipfs://CID",
 "deposit": "",
 "title": "Updating the staking params",
 "summary": ""
}

Finally, we submit the proposal:

secretcli tx gov submit-proposal <path_to_proposal.json>

You can see another param-change example here:

Subspaces, Keys and Values

Subspace

Key

Type

Example

Further Proposal Details

The subspace is usually the ModuleName
The key is usually defined in x/$MODULE_NAME/types/params.go
The value's type is usually near the key definition
⚠️ 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 and for more info.

To read more go to the .

Community Pool Spend

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

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

We can createproposal.json using tx gov draft-proposal

secretcli tx gov draft-proposal
// running the command will start a terminal applet allowing you to choose the proposal type

// 1st screen
Use the arrow keys to navigate: ↓ ↑ → ←
? Select proposal type:
    text
    community-pool-spend
  > software-upgrade
    cancel-software-upgrade
    other

Software Upgrade

To submit a software upgrade proposal use:

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

We can createproposal.json using tx gov draft-proposal

secretcli tx gov draft-proposal
// running the command will start a terminal applet allowing you to choose the proposal type

// 1st screen
Use the arrow keys to navigate: ↓ ↑ → ←
? Select proposal type:
    text
    community-pool-spend
  > software-upgrade
    cancel-software-upgrade
    other

Query Proposals

Available Commands

Querying Proposals

Query Using Proposal ID

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

Query For All Proposals

You can query for all available proposals using:

secretcli query gov proposals

Query For Proposal Depositor

You can query for the proposal depositor using:

secretcli query gov deposit \
    [proposal-id] \
    [depositer-addr] \
    [flags]

Query For Proposal Depositors

You can query for the proposal depositors using:

secretcli query gov deposits \
    [proposal-id] \
    [flags]

Query For Proposal Voter

You can query for the proposal voter using:

secretcli query gov vote \
    [proposal-id] \
    [voter-addr] \
    [flags]

Query for Proposal Proposer

To query for the proposer of a given governance proposal use:

secretcli query gov proposer 
    [proposal-id] \
    [flags]

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] \
    [flags]

Query Governance Proposals

To check the current governance parameters run:

secretcli query gov params

deposit_params:
  max_deposit_period: "3600000000000"
  min_deposit:
  - amount: "10000000"
    denom: uscrt
tally_params:
  quorum: "0.334000000000000000"
  threshold: "0.500000000000000000"
  veto_threshold: "0.334000000000000000"
voting_params:
  voting_period: "3600000000000"

Querying Subsets of Governance Proposals

Voting

To query subsets of the governance parameters for voting run:

secretcli query gov param voting

voting_period: "3600000000000"

Tallying

To query subsets of the governance parameters for tallying run:

secretcli query gov param tallying

quorum: "0.334000000000000000"
threshold: "0.500000000000000000"
veto_threshold: "0.334000000000000000"

Deposit

To query subsets of the deposit governance parameters for voting run:

secretcli query gov param deposit

max_deposit_period: "3600000000000"
min_deposit:
- amount: "10000000"
  denom: uscrt

Deposits

Increasing Deposits

If the proposal you previously created didn't meet the MinDeposit requirement, you can still increase the total amount deposited to activate it.

Note: Proposals not meeting this requirement will be deleted after MaxDepositPeriod is reached.

Once the minimum deposit is reached, the proposal enters voting period:

Note: The regular flags for the tx command are applicable to gov deposit (--fees, --gas, --account-number --ledger, --node, etc...)

Returning Deposits

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

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 ).
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.

Querying Deposits

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

secretcli query gov deposits \
    [proposal-id] \
    [flags]

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

secretcli query gov deposit \
    [proposal_id] \
    [depositor_address]

Flags

There are several flags to use with secretcli query gov deposit:

Flags:
      --count-total       
          count total number of records in deposits to query for
      --height int        
          Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help              
      help for deposits
      --limit uint        
          pagination limit of deposits to query for (default 100)
      --node string       
          <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --offset uint       
          pagination offset of deposits to query for
      --page uint         
          pagination page of deposits to query for. This sets offset to a multiple of limit (default 1)
      --page-key string   
          pagination page-key of deposits to query for
      --reverse           
          results are sorted in descending order