The module that makes decentralized change accountable. Four gates, three thresholds, one committed block.
Governance in the Cosmos SDK is not advisory. A text proposal might produce only a community signal, but every other proposal type produces a state mutation that the chain's entire validator set executes simultaneously. Software upgrade proposals trigger chain halts. Parameter change proposals mutate running behavior. Community pool spend proposals move treasury tokens to named recipients. The x/gov module makes these mutations accountable: the change does not happen unless the validator set — weighted by bonded stake — votes for it.
This lesson covers the x/gov module from the Interchain Dev perspective: how the module is architectured, how voting power flows through the delegation model, how the three tally thresholds interact, and how the software upgrade proposal bridges the governance module to the x/upgrade module.
The x/gov module manages four data structures: proposals, deposits, votes, and governance parameters. Each structure has keeper methods that write to and read from the module's KV store partition. The module registers message handlers with the message server: MsgSubmitProposal, MsgDeposit, MsgVote, and MsgVoteWeighted. It also registers an end-block handler that runs the tally algorithm when any proposal's voting period expires.
content field (protobuf Any wrapping a typed proposal). SDK v0.47+ uses a messages field containing a list of sdk.Msg — any message the application's router supports. This shift allows governance to invoke IBC messages, staking messages, or custom module actions directly. Interchain Dev candidates must recognize both patterns and identify which a given chain uses from its SDK version.
The end-block handler is the key architectural detail: it runs inside every block's EndBlock function. Proposals whose deposit_end_time or voting_end_time has passed are processed at the very next block. Tally executes in a single block, not deferred. A proposal's outcome is committed in one BFT-finalized block — as Petrov notes in Database Internals (Ch. 14, p. 325), Byzantine Fault Tolerant consensus commits a block with two-thirds-plus-one supermajority agreement, making the tally result irreversible the moment its block commits.
No executable content. Community signal only. Safe entry point for new governance participants. Records the validator set's direction on a question; no code runs on passage.
Carries an UpgradePlan: handler name, target height, optional info string. On passage, writes UpgradePlan to x/upgrade state. Chain halts at target height automatically.
Targets a subspace-key-value triple in a module's param store. Change takes effect immediately at tally passage. Unbonding times, slash fractions, and voting periods can all be altered this way.
Routes tokens from the distribution module's community pool to a named recipient. Executes the transfer on passage. Primary mechanism for on-chain treasury distribution and ecosystem grants.
Tally runs at voting period expiry. Three thresholds determine outcome — applied in sequence, each can fail the proposal independently:
The veto-burn mechanism is the community's tool against governance spam. The 33.4% veto threshold is deliberately lower than a majority: it takes a significant minority who consider a proposal actively harmful — not merely wrong — to trigger the burn. This asymmetry is by design.
Cosmos SDK governance voting power is stake-weighted, not one-validator-one-vote. A validator with 5% of total bonded stake carries 5% of voting weight. This accountability model means the governance decision-maker has skin in the game proportional to their influence.
When a validator calls MsgVote, their vote covers all bonded stake delegated to them for which no delegator has cast an independent vote. The validator's vote is the default for their delegators — the fallback, not the override.
A delegator who wants a different result submits MsgVote from their own address. The chain recomputes at tally time: the delegator's stake is removed from the validator's option tally and credited to the delegator's chosen option. This is the inheritance rule: at tally, for each validator, start with total bonded stake, subtract any delegator-overridden stake, distribute the override stakes to their chosen options, then sum across all validators.
SDK v0.46+ supports weighted votes. A single MsgVoteWeighted transaction splits the sender's voting power across multiple options with fractions summing to 1.0. A validator might cast 70% Yes / 30% Abstain if they consider a proposal directionally sound but technically incomplete. Rare in practice; supported at the module level.
This five-phase sequence describes the operational choreography from upgrade proposal to resumed chain:
Phase 1: Proposal authorship. The proposer must have the UpgradePlan parameters ready before submitting: upgrade handler name (exact string match required), target height, and info string. The target height must allow every validator time to download or build the binary and stage it before the halt. Cosmos Hub upgrades typically target a height four to seven days ahead of expected passage.
Phase 2: Deposit and vote. The proposal moves through the four-gate passage. Large validators are expected to comment in governance forums; governance participation is partly social and reputational, not only an on-chain transaction.
Phase 3: Passage and UpgradePlan write. When tally passes, the module writes the UpgradePlan to x/upgrade state. The chain is now committed to halting at the specified height. No further governance action is needed or possible to trigger the halt.
Phase 4: Pre-halt rehearsal. Validators read the info string, acquire the new binary, verify the checksum, and stage it at the path their daemon manager expects. On Cosmovisor, this means placing the binary in the correct upgrade/ subdirectory before the halt height.
Phase 5: Halt and resume. At the target height, x/upgrade fires the halt. The new binary starts, finds the UpgradePlan, executes the registered handler, and resumes block production. If the handler name in the UpgradePlan does not exactly match the handler registered in the binary, the binary panics and the chain does not resume.
The Ops lesson documents the governance lifecycle as validator operational discipline: tracking proposals, managing operator-key transactions, voting before deadlines, and understanding the governance-upgrade bridge. This lesson provides the module-level foundation for those operations. The four gates exist because the x/gov module's state machine defines them. The three tally thresholds are specific numeric checks in the module's tally algorithm. The upgrade proposal produces the UpgradePlan that x/upgrade acts on — governance and upgrade are separate modules, coupled through a single keeper write.
The Dev lesson's three Bash scripts interact directly with the x/gov module's RPC endpoints. The governance watch loop queries gov proposals --status voting_period, reading the module's proposal store filtered by status. The vote wrapper calls gov vote, submitting a MsgVote. The deposit guard calls gov proposal to read deposit state. Every CLI call in the Bash lesson corresponds to a message handler or keeper method in the x/gov module.
"v2-upgrade". The registered handler in the new binary is "v2_upgrade" (underscore). What happens at the halt height?"v2-upgrade". Exact string match is required. The handler "v2_upgrade" does not match. The binary panics with an "unknown upgrade" error. Every validator must patch and redeploy the binary with the correct handler name.
messages field pattern (SDK v0.47+). What happens?messages field; it expects the content protobuf Any pattern. The submitter must use TextProposal, SoftwareUpgradeProposal, or other content-typed proposals for chains on SDK v0.46 and below.
The x/gov module defines the accountability architecture for Cosmos SDK chains. Its three tally thresholds are not arbitrary. Quorum prevents a small minority from deciding for the whole network. The veto threshold gives a meaningful minority a way to reject active harm at a lower bar than majority rejection. The pass threshold sets a majority requirement for affirmative change. Together they encode the principle that change on a decentralized network requires broad legitimacy, not just the loudest voice.
The Interchain Dev candidate who holds this module's state machine, voting-power mechanics, and upgrade-vote coordination pattern carries the theory needed to operate these mechanisms with precision. The Ops and Dev lessons for today hold the practice.