Governance

Governance Parameters

For governance proposals to enter the voting period, they must be submitted on-chain with a deposit that is not less than the min_deposit parameter set in the governance module, and this must be done before the deposit end time. Deposits are returned if a proposal gets approved or declined. However, if there are sufficient NO WITH VETO votes, the depositors will lose their deposits. Depositors will also forfeit their deposits if a quorum of more than 1% is not reached. In both scenarios, the deposits will be burnt.

The governance parameters can be accessed via the CLI, as demonstrated in the following example:

As of this writing the following are the governance parameters for Mainnet and Constantine (Testnet):

Best Practices

Code of Conduct

See the following signaling proposal for the implementation of the code of conduct.

Preliminary Forum Discussions

Proposals should be submitted to the Governance forum for review and discussion prior to being submitted on-chain.

This will enable preliminary exploration amongst community members to fully understand the scope of the proposal, provide input/ feedback, and ultimately improve the proposal before pushing toward a formal on-chain vote.

Proposals should be posted to the forum for a minimum of 3 days before being submitted for a vote on-chain.

Proposal Types and Templates

Archway supports several types of governance proposals, as detailed below:

• Simple Proposal: This type of proposal does not have its own specific type, and it is a general-purpose proposal.
• Community Pool Spend Proposal (community-pool-spend): This type of proposal allows valuable initiatives and projects to be funded by the community pool
• Parameter Change proposal (param-change): This type of proposal allows updating chain parameters

In addition to the above, Archway also supports the following proposals types:

• Cancel Software Upgrade (cancel-software-upgrade): Cancel the current software upgrade proposal
• Clear Contract Admin (clear-contract-admin): Submit a clear admin for a contract to prevent further migrations proposal
• Execute Contract (execute-contract): Submit a execute wasm contract proposal (it can be run by any address)
• IBC Upgrade (ibc-upgrade): Submit an IBC upgrade proposal
• Instantiate Contract (instantiate-contract): Submit an instantiate wasm contract proposal
• Migrate Contract (migrate-contract): Submit a migrate wasm contract to a new code version proposal
• Pin Codes (pin-codes):Submit a pin code proposal for pinning a code to cache
• Set Contract Admin (set-contract-admin): Submit a new admin for a contract proposal
• Software Upgrade (software-upgrade): Submit a software upgrade proposal
• Sudo Contract (sudo-contract): Submit a sudo wasm contract proposal (to call privileged commands)
• Unpin Codes (unpin-codes): Submit a unpin code proposal for unpinning a code to cache
• Update Client (update-client): Submit an update IBC client proposal
• Update Instanciate Config (update-instantiate-config): Submit an update instantiate config proposal.
• Wasm Store (wasm-store): Submit a wasm binary proposal

Determining Voting Power

Voting power is determined by stake weight at the end of the voting period and is proportional to the number of total ARCH participating in the vote. Only bonded ARCH tokens count towards the voting power for a governance proposal.

Unbonded ARCH will not count toward a vote or quorum. Only tokens staked with active validators will have voting power. Inactive validators are able to cast a vote, but their voting power (including the backing of their delegators) will not count toward the vote if they are not in the active set when the voting period ends.

Stages

STAGE 1: Proposal Discussion

Proposals should be submitted to the Governance forum for review and discussion prior to being submitted on-chain. This will enable preliminary exploration amongst community members to fully understand the scope of the proposal, provide input/feedback, and ultimately improve the proposal before pushing toward a formal on-chain vote. Before submitting an idea, think about how it affects other stakeholders.

STAGE 2: Proposal formalized for voting

After having reached a consensus in the Temperature Check, the initial proposer or another community member can submit the idea in the proposals category in the Governance forum. If you are using the CLI to create a proposal by setting the title and description flags, the text may be escaped (which will have undesired effects).

In general, it is recommended to put the proposal text into a JSON file and include that file as part of the CLI proposal, rather than specifying individual fields using flags. The JSON file will contain the information to be stored on-chain as the governance proposal. Each proposal type has a unique JSON format. You can refer to the 'Proposals Types Guidelines' section to see how JSON files are structured for the most common proposals.

Create the JSON file

It is recommended to place the proposal text in a JSON file and include that file during the CLI proposal submission.

In this section, we will explore how to create an appropriate .json file for each proposal type.

Simple proposal

You can create a simple proposal, by specifying the path to the json file and adding the key/value type: "Text" in the JSON file. For this proposal type, you don’t need to specify the <proposal type> in the CLI command.

You can use this proposal type to get feedback from the community with a question, agree on a direction and let stakeholders to signal their opinion. A signal proposal has no direct effect on the change of Archway aside from having a record of the proposal outcome on Archway chain.

These proposals are usually posted in the form of a question such as: "Is XXX harmful to the success of Archway?"

JSON example:

{   "title": "Should we start organizing hackathons?",   "description": "Organizing hackathons would be a great way to onboard developers to Archway!",   "type": "Text",   "deposit": "1000000000000000000000aarch"} 

Community Pool Spend (community-pool-spend)

The JSON file for this proposal type should have the following fields:

• Title - the unique name assigned to the proposal, often used by explorers to list proposals.
• Description - the body of the proposal that further describes what is being proposed and details surrounding the proposal
• Recipient - the Archway address that will receive funding from the community pool
• Amount - the amount of funding that the recipient will receive (denominated in aarch)
• Deposit - the amount that will be contributed to the deposit (denominated in aarch) from the account submitting the proposal

JSON example 1:

{   "title":"Let’s test a spending proposal",   "description":"This is just a test, but happy to receive some Const :D",   "recipient":"archway1ygltcxr7nev8h8cd60fw347vf4kaz0r3phmfry",   "amount":"10000000000000000000000000arch",   "deposit":"1000000000000000000000aarch"}

Parameter Change (param-change)

The JSON file for this proposal type should have the following fields:

• Title - the unique name assigned to the proposal, often used by explorers to list proposals
• Description - the main content of the proposal, elaborating on the proposal's purpose and providing further context and details
• Changes - the changes that you want to apply to the key-value pair of a subspace (e.g, bank, gov, slashing, staking) which can be found here

To submit any changes, make sure your JSON includes subspace, key, and the proposed value.

JSON example 2:

{   "title":"Parameter change: decrease unbonding time to 2 days",   "description":"Change to 2 days",   "changes":[      {         "subspace":"staking",         "key":"UnbondingTime",         "value":"172800000000000"      }   ],   "deposit":"100arch"}

JSON example 3:

{   "title":"Testable network parameters for gov and staking",   "description":"constantine-3 is a test network, with a goal to emulate mainnet as closely as possible. However, in order to allow testability network parameters must be tuned differently from mainnet. Network parameters on constantine-3 should allow reasonably short waiting times and low fund requirements, this will enable developers to run quick and frequent tests and increase development velocity",   "changes":[      {         "subspace":"gov",         "key":"tallyparams",         "value":{            "quorum":"0.010000000000000000",            "threshold":"0.050000000000000000",            "veto_threshold":"0.025000000000000000"         }      },      {         "subspace":"gov",         "key":"depositparams",         "value":{            "min_deposit":[               {                  "denom":"aarch",                  "amount":"100"               }            ],            "max_deposit_period":"300000000000"         }      },      {         "subspace":"gov",         "key":"votingparams",         "value":{            "voting_period":"60000000000"         }      },      {         "subspace":"staking",         "key":"UnbondingTime",         "value":"120000000000"      }   ],   "deposit":"100arch"}

1. Title - the unique name assigned to the proposal, often used by explorers to list proposals
2. Description - the body of the proposal that further describes what is being proposed and details surrounding the proposal
3. Subspace - the Archway module with the parameter that is being changed
4. Key - the parameter that will be changed
5. Value - the value of the parameter that will be changed by the governance mechanism
6. Denom - ARCH will be the type of asset used as the deposit
7. Amount - the amount that will be contributed to the deposit (in ARCH) from the account submitting the proposal

Once you have a final draft of your proposal ready to submit, it is advisable to verify the formatting of your json file by using a json formatter (e.g. json schema validator). This will make sure that you won’t encounter any issues when submitting the proposal.

STAGE 3: On-chain proposal

Once your JSON is properly formatted accordingly to the chosen proposal type, you can submit your proposal live on testnet (Constantine) first.

You may want to submit your proposal to the testnet chain before the mainnet for a number of reasons:

1. To see what the proposal description will look like.
2. To signal that your proposal is about to go live on mainnet.
3. To share what the proposal will look like in advance with stakeholders.
4. To test the functionality of the governance features.

Submitting the proposal

You can use the archwayd CLI to submit your governance proposal on-chain. Submitting to the testnet is identical to mainnet submissions aside from a few changes:

1. The chain-id for Archway is archway-1
2. The list of usable endpoints can be found in the Networks page
3. You will need ARCH testnet tokens. There is a faucet available on Discord. You can also find the faucet links for the different networks on the Networks page

How to submit the proposal via the archwayd CLI

Here are some examples on how to use the CLI to submit and query proposals.

To submit a simple proposal:

archwayd tx gov submit-proposal --from mywallet5 --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --proposal=/root/archway/proposals/testproposal.json --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3

You can also submit the proposal without the JSON and through the CLI flags directly:

archwayd tx gov submit-proposal --title="Test Proposal" --description="My awesome proposal" --type="Text" --deposit=1000000000000000000aarch --from mykey -node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3

Anyway, keep in mind that submitting a proposal through a JSON file is the recommended way.

To submit a community-pool-spend proposal:

archwayd tx gov submit-proposal community-pool-spend /root/archway/proposals/spendproposal.json --trace --from archwayaddress1234567 --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3

To submit a param-change proposal:

archwayd tx gov submit-proposal param-change /root/archway/proposals/change-param.json --from mywallet5 --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3

For the other proposals, you can check the CLI command usage:

Cancel Software upgrade (cancel-software-upgrade)

In this case, you can propose to cancel the current software upgrade proposal, for example:

archwayd tx gov  submit-proposal cancel-software-upgrade --node https://rpc.mainnet.archway.io:443 --title "test" --description "test2" --from mywallet5 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3

Execute contract (execute-contract)

Usage:

archwayd tx gov submit-proposal execute-contract [contract_addr_bech32] [json_encoded_migration_args] [flags]

IBC Upgrade (ibc-upgrade)

Usage:

archwayd tx gov submit-proposal ibc-upgrade [name] [height] [path/to/upgraded_client_state.json] [flags]

Instanciate contract (instanciate-contract)

Usage:

archwayd tx gov submit-proposal instantiate-contract [code_id_int64] [json_encoded_init_args] --label [text] --title [text] --description [text] --run-as [address] --admin [address,optional] --amount [coins,optional] [flags]

Migrate Contract (migrate-contract)

Usage:

archwayd tx gov submit-proposal migrate-contract [contract_addr_bech32] [new_code_id_int64] [json_encoded_migration_args] [flags]

Pin Codes (pin-codes)

Usage:

archwayd tx gov submit-proposal pin-codes [code-ids] [flags]

Set Contract Admin (set-contract-admin)

Usage:

archwayd tx gov submit-proposal set-contract-admin [contract_addr_bech32] [new_admin_addr_bech32] [flags]

Software Upgrade (software-upgrade)

Usage:

archwayd tx gov submit-proposal software-upgrade [name] (--upgrade-height [height]) (--upgrade-info [info]) [flags]

Sudo Contract (sudo-contract)

Usage:

archwayd tx gov submit-proposal sudo-contract [contract_addr_bech32] [json_encoded_migration_args] [flags]

Unpin Codes (unpin-codes)

Usage:

archwayd tx gov submit-proposal unpin-codes [code-ids] [flags]

Update Client (update-client)

Usage:

archwayd tx gov submit-proposal update-client [subject-client-id] [substitute-client-id] [flags]

Update Instanciate Config (update-instanciate-config)

Example:

archwayd tx gov submit-proposal update-instanciate-config --help --from mywallet5 --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3 --proposal=/root/archway/proposals/testproposal.json

Wasm Store (wasm-store)

Usage:

archwayd tx gov submit-proposal wasm-store [wasm file] --title [text] --description [text] --run-as [address] [flags]

Notes:

1. archwayd is the command-line interface client that is used to send transactions and query Archway Connect
2. tx gov submit-proposal param-change indicates that the transaction is submitting a param-change proposal
3. --from bob flag indicates the account key that pays the transaction fee and deposit amount is named bob. You would need to have added this key with archway accounts --add “bob". Alternatively, you can use the address, with --from archwayaddress123214wythfsdu
4. --gas 500000 Whatever this number is set to should be the maximum amount of gas permitted to be used to process the transaction
   1. the more content there is in the description of your proposal, the more gas your transaction will consume
   2. if this number isn't high enough and there isn't enough gas to process your transaction, the transaction will fail
   3. the transaction will only use the amount of gas needed to process the transaction
5. --fees is a flat-rate incentive for a validator to process your transaction
   1. the network still accepts zero fees, but many nodes will not transmit your transaction to the network without a minimum fee

Verifying the proposal transaction

After signing the transaction through your keyring passphrase, the transaction is submitted and the transaction's hash will be shown on the terminal. You can either query the tx by using the CLI or by searching the transaction hash using a blockexplorer.

You can query the proposals via the CLI, for example:

archwayd q gov proposals  --node https://rpc.mainnet.archway.io:443

Or query the specific proposal id, for example:

archwayd q gov proposal 8  --node https://rpc.mainnet.archway.io:443

If there have been issues with the proposal transaction, you can still query the tx id, for example:

archwayd q tx 39EB4C85EC00281BB54EEE6BC87F17038F3528D5E54BF7FFBDF13E7C15DF92FE  --node https://rpc.mainnet.archway.io:443

and check the value of the raw_log field for useful information

Depositing funds after a proposal has been submitted

If you have submitted the proposal without the minimum token amount deposited yet, don't worry! You are still in time to deposit more tokens to get the proposal into the voting stage. For example, you can launch:

archwayd tx gov deposit 8  10000000000000aarch --from mywallet4 --node https://rpc.mainnet.archway.io:443

STAGE 4: Voting on-chain (Archway Connect)

Now that the proposal is on-chain, you can engage the community on Discourse and Discord to make sure that the minimum quorum threshold is reached. Also, make sure that enough deposit is allocated to the proposal.

STAGE 5: On-chain execution

If the proposal passed, you are done.

If the proposal did not pass, make sure to understand why by engaging with the relevant stakeholders. You may be able to have the proposal passed after having made some changes.