Submitting a Proposal

This page walks through submitting a governance proposal on AIOZ Network end-to-end, from preparing supporting material to depositing after submission. For what to propose, see Proposal Types; for the exact JSON shape, see Formatting a Proposal. If you haven't built community support yet, do that first: see Off-Chain Proposal Process.

Hosting Supplementary Materials

A title and description have to fit in a transaction, so keep them concise and host anything longer (full rationale, risk analysis, supporting data, discussion history) externally and link to it from the description. A public, durable location works best: a community forum post, a document pinned via AIOZ Pin, or a Telegram post that stays accessible.

Avoid linking to something only you can edit or take down later, a private doc, a message that can be deleted. Voters and anyone auditing the proposal afterward should be able to re-check exactly what they voted on, indefinitely.

Formatting the JSON File for the Governance Proposal

Every type other than Text needs a JSON proposal file rather than CLI flags alone. See Formatting a Proposal for the exact shape per type.

Validate the JSON locally before broadcasting; a malformed file fails the transaction outright and wastes the gas fee without the proposal ever entering the deposit period. A JSON linter or a quick jq . proposal.json is enough to catch syntax errors; catching semantic errors (wrong subspace, wrong field names) is what the testnet rehearsal at the end of this page is for.

Sending the Transaction That Submits Your Governance Proposal

A Text proposal can be submitted directly with flags, no file needed:

aiozd tx gov submit-legacy-proposal \
  --title="<title>" \
  --description="<description>" \
  --type="Text" \
  --deposit="1000000000000000000000attoaioz" \
  --from=<key> \
  --chain-id=<chain_id>

For types that need a JSON file, the subcommand takes the file path instead of --type:

aiozd tx gov submit-legacy-proposal param-change <path/to/proposal.json> \
  --from=<key> \
  --chain-id=<chain_id>

The pattern is the same across every type: aiozd tx gov submit-legacy-proposal <subcommand> <file> for anything with a JSON payload, aiozd tx gov submit-legacy-proposal --type=Text for anything without one.

Proposal Types

Legacy Proposals (cosmos-sdk < v0.47)

AIOZ Network's aiozd currently exposes the legacy, content-based proposal interface shown throughout this section, reached via submit-legacy-proposal: --type="Text", param-change, community-pool-spend, each mounted as its own subcommand with a fixed, module-defined payload shape. This is the interface every example on this page uses, and the one that matches every proposal submitted on AIOZ mainnet to date.

Proposals (cosmos-sdk >= v0.47)

AIOZ mainnet's gov module also exposes a newer, generic Msg-based proposal interface, reached via the plain submit-proposal command (no legacy). It accepts a messages array of arbitrary proto-JSON-encoded Msgs, including a legacy Content type wrapped in MsgExecLegacyContent.

This was confirmed by generating an unsigned transaction against a real node: the old flat {title, changes, deposit} shape is rejected outright on this path.

Querying /cosmos/gov/v1/params/voting on the LCD shows this interface also carries parameters the legacy path doesn't:

• expedited_voting_period (3 hours) and expedited_threshold (66.7%), for proposals that opt into a shorter, higher-bar expedited track
• proposal_cancel_ratio and min_deposit_ratio, for finer control over deposit behavior

The proposal file itself has four top-level fields, confirmed by the exact JSON this interface accepted during testing:

• title: the short name voters and block explorers will list the proposal under.
• summary: the full explanation of what's being proposed and why; unlike the legacy interface's description, this is the field name the v1 schema actually validates against.
• deposit: the initial amount attached at submission, in attoaioz, same as the legacy path.
• metadata: typically a link to supplementary material hosted off-chain (a forum post, a pinned document via AIOZ Pin) rather than free-form text; see Hosting Supplementary Materials above.

messages sits alongside these four and carries the actual proto-JSON-encoded Msgs to execute if the proposal passes; it's what makes this interface generic rather than tied to a fixed set of content types.

aiozd query gov params

Minimal Deposit Amount

A proposal needs its total deposit to reach min_deposit before voting opens: currently 1000 AIOZ (1000000000000000000000attoaioz) on mainnet. This is a gov module parameter, not a constant, so it can itself change over a Parameter Change proposal; confirm the live value before submitting rather than trusting a number you saw a while ago:

aiozd query gov params

Walkthrough Example (Changing x/staking Params)

aiozd query staking params

{
  "title": "Increase max validators",
  "description": "Raise the active validator set from 50 to 75",
  "changes": [
    { "subspace": "staking", "key": "MaxValidators", "value": 75 }
  ],
  "deposit": "1000000000000000000000attoaioz"
}

aiozd tx gov submit-legacy-proposal param-change proposal.json \
  --from=<key> \
  --chain-id=<chain_id>

aiozd query gov proposal <proposal_id>

Verifying Your Transaction

aiozd query tx <tx_hash>

A successful submission returns code: 0 and includes the assigned proposal_id in its emitted events, under the submit_proposal event type. Save that ID immediately; it's what every subsequent command on this page needs.

Troubleshooting a Failed Transaction

• Non-zero code in the tx result: read the accompanying raw_log; a malformed JSON file or an invalid subspace/key pair is the most common cause, and the log usually names the exact field.
• Insufficient fees: re-check --gas-prices against the current network minimum; a transaction can be rejected at the mempool level before it ever reaches a block.
• Proposal never leaves the deposit period: the deposit hasn't reached min_deposit yet; see the next section rather than resubmitting the same proposal again.
• account sequence mismatch: another transaction from the same key confirmed in between building and broadcasting this one; rebuild the transaction to pick up the current sequence number and resend.

Depositing Funds After a Proposal Has Been Submitted

Anyone can add to an existing proposal's deposit, not only the original proposer, which is useful when a proposer wants to gauge interest with a smaller initial amount rather than committing the full min_deposit up front:

aiozd tx gov deposit <proposal_id> "1000000000000000000000attoaioz" \
  --from=<key> \
  --chain-id=<chain_id>

aiozd query gov deposits <proposal_id>

Submitting Your Proposal to the Testnet

Rehearse the exact same proposal on AIOZ testnet before spending a real deposit on mainnet. Reusing the identical JSON file, only the chain-id and node change, is the point: it's a mechanical check that the payload itself is valid, not a test of a simplified version of it.

Get testnet AIOZ for the deposit and gas fees from the AIOZ Faucet (opens in a new tab) rather than needing a real balance.

aiozd tx gov submit-legacy-proposal param-change proposal.json \
  --from=<key> \
  --chain-id=aioztestnet_4102-2 \
  --node=https://rpc-ds.testnet.aioz.network:443

If it behaves as expected through a full deposit and voting cycle on testnet, that's a reasonable signal it will behave the same way on mainnet; the module logic doesn't differ between the two networks.