Submitting a proposal

This page is for anyone putting a proposal on the Cosmos Hub. It assumes gaiad is configured for the Hub with a funded key (Delegator CLI guide) and that you have read the Governance process. At the end your proposal is in its deposit or voting period. You can check its state from the chain. The deposit is at risk: a vetoed proposal loses all 500 ATOM, and a cancelled one loses half. The stages below exist to make sure a proposal that reaches the chain has already been read by the people who will vote on it.

Stage 1: the idea

Before writing anything formal, find out whether the community wants it. Post the idea on the Cosmos Hub forum under Hub Proposals. Raise it in the governance channels on Discord. Talk directly to the people it affects: large validators and stakers, the teams that maintain the code it touches, and anyone a previous proposal on the subject involved. Search past proposals first. Many ideas have been voted on before, and the earlier discussion tells you what voters objected to. For a parameter change or an upgrade, the idea stage is also where you confirm the change is possible on the current gaia version. The module pages under Modules on the Hub list what each module exposes.

Stage 2: the draft

Write the proposal as a document with these parts, in this order, so that someone who stops after the summary can still vote:

Summary: what changes, in a few sentences, with the exact values or amounts.
Details: the reasoning, the alternatives considered, and what happens if it does not pass.
Impact: who is affected and how, including risks and how they are mitigated.
Links: the forum thread, any code or audit, and the author’s contact.
Vote option context: what Yes, No, and NoWithVeto mean for this proposal.

The forum has a template thread for each type: text, community spend, parameter change, and software upgrade. A parameter change proposal should also state the current value and the query that returns it. A spend proposal should state the recipient address, the amount in uatom, the deliverables, and the schedule. Post the draft as a new forum topic. Leave it up for at least a week while people comment. Revise it in place, and keep a changelog at the bottom. The on-chain summary should match the final forum draft. Voters compare them.

Stage 3: the proposal JSON

On gaia v28.3.1 a proposal is a JSON file with the messages to execute, the metadata reference, the deposit, title, summary, and the expedited flag. The draft-proposal command builds the skeleton interactively:

gaiad tx gov draft-proposal

Pick the type (text, community-pool-spend, software-upgrade, cancel-software-upgrade, or other for any message type) and answer the prompts. The command writes draft_proposal.json and draft_metadata.json in the current directory. The proposal file for a text proposal looks like this:

{
  "messages": [],
  "metadata": "ipfs://CID",
  "deposit": "50000000uatom",
  "title": "Proposal title",
  "summary": "Short summary, repeated from the forum draft.",
  "expedited": false
}

Fields:

messages: the messages to execute on pass, empty for a text proposal. Each must carry "authority": "cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn". The per type shapes are on the proposal type pages.
metadata: a reference to the full text, usually an InterPlanetary File System (IPFS) URI. The Cosmos SDK accepts any string up to the gov metadata limit. The Hub convention is the metadata JSON that draft-proposal writes (title, authors, summary, details, proposal_forum_url, vote_option_context), pinned to IPFS.
deposit: the initial deposit from the proposer, at least 50 ATOM (10 percent of the 500 ATOM minimum). Putting the full 500 ATOM here moves the proposal straight to voting.
title and summary: shown by every explorer and wallet. Keep the summary under a few hundred words. The details belong in the metadata.
expedited: true for a 3 day vote with a 501 ATOM deposit and a 66.7 percent threshold.

Host the metadata before submitting. Pin draft_metadata.json to IPFS with a node of your own or a pinning service. Confirm the content identifier (CID) resolves on a public gateway. Put ipfs://<CID> in metadata. Pinned content cannot be edited, which is the point. A proposal whose metadata changes after submission is treated as suspect.

Stage 4: rehearse on the testnet

The Hub testnet (chain-id provider) runs the same gov module with testnet tokens from a faucet. The exact JSON and the exact command can therefore be sent there first. Endpoints and the faucet are on Join testnet. Submit with --chain-id provider --node <testnet rpc> and a testnet key. Then check the proposal appears with gaiad q gov proposal <id> against the testnet node. Expect to fix the JSON at least once.

Stage 5: submit on mainnet

gaiad tx gov submit-proposal draft_proposal.json --from mykey \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.005uatom

The command prints the transaction for confirmation and returns a txhash. The proposal id is in the transaction events:

gaiad q tx <txhash> --output json | jq -r '.events[] | select(.type=="submit_proposal") | .attributes[] | select(.key=="proposal_id") | .value'
gaiad q gov proposal <id>

The gaiad q gov proposal command prints status: PROPOSAL_STATUS_DEPOSIT_PERIOD with total_deposit equal to what you sent, or PROPOSAL_STATUS_VOTING_PERIOD if the initial deposit was the full 500 ATOM. Common rejections, each reported in the transaction’s raw_log:

minimum deposit is too small: the initial deposit was under 50 ATOM.
invalid authority or expected gov account as only signer: a message’s authority is not the gov module account.
metadata too long or summary too long: move text into the IPFS document.
insufficient fee: query gaiad q feemarket gas-price uatom and raise --gas-prices.
unknown message type: the @type string is wrong for this gaia version. Compare with a recent proposal of the same kind.

Stage 6: complete the deposit and announce

If the initial deposit was under 500 ATOM, anyone can top it up, in amounts of at least 5 ATOM, until the deposit period ends 14 days after submission:

gaiad tx gov deposit <id> 450000000uatom --from mykey --gas auto --gas-adjustment 1.5 --gas-prices 0.005uatom
gaiad q gov deposits <id>

The proposal moves to voting in the block the deposit is filled. Post the proposal id and the explorer link in the forum thread. Tell the validators directly: most of the voting power is theirs, and they vote late in the period. During the 7 days, answer questions in the thread. A proposal is rarely rejected for its content and often for its author going silent.

Cancel a wrong proposal with gaiad tx gov cancel-proposal <id> --from <proposer key> before the voting period ends, then resubmit it. A proposal cannot be edited after submission. Cancelling refunds half of the deposit. Letting a wrong proposal run to a veto loses the entire deposit.

Verify

gaiad q gov proposal <id> --output json --node https://cosmos-rpc.publicnode.com:443 | jq '{status: .proposal.status, deposit: .proposal.total_deposit, voting_end: .proposal.voting_end_time, messages: [.proposal.messages[]["@type"]]}'

The status field is PROPOSAL_STATUS_VOTING_PERIOD. The deposit is at least 500 ATOM. The voting_end is 7 days (or 3 for expedited) after the deposit was filled. The messages list holds exactly the message types you intended. Run gaiad q gov tally <id> during the period. Compare the result with the explorer.

Proposal types for the message JSON of each type.
Governance process for what the vote needs to pass.
Delegator CLI guide to submit from a multisig.

​Stage 1: the idea

​Stage 2: the draft

​Stage 3: the proposal JSON

​Stage 4: rehearse on the testnet

​Stage 5: submit on mainnet

​Stage 6: complete the deposit and announce

​Verify

​Next

Stage 1: the idea

Stage 2: the draft

Stage 3: the proposal JSON

Stage 4: rehearse on the testnet

Stage 5: submit on mainnet

Stage 6: complete the deposit and announce

Verify

Next