How Onchain Governance Proposals Work

Detailed Instructions

Begin by drafting a formal proposal document, often using a template like the Ethereum Improvement Proposal (EIP) or a DAO-specific format. This document must clearly define the proposal type (e.g., treasury spend, parameter change), the rationale, and the technical specification. Before submitting onchain, share the draft on governance forums (e.g., Commonwealth, Discourse) to signal for feedback.

• Sub-step 1: Post the draft RFC (Request for Comments) on the official forum.
• Sub-step 2: Engage with community feedback, iterating on the proposal's technical and economic details.
• Sub-step 3: Reach a rough consensus or identify key objections before proceeding to a temperature check snapshot.

markdownCopy
# Proposal: Increase Protocol Fee to 0.05%
**Summary:** Adjust fee parameter in `FeeCollector.sol`.
**Motivation:** To sustainably fund grants program.

Tip: A successful signal phase demonstrates community alignment and reduces the risk of a failed, gas-expensive onchain vote.

Detailed Instructions

Once signaled, the proposal must be submitted onchain. This typically involves a privileged transaction from a proposer (often requiring a minimum token balance or delegate count). The submission transaction deploys or points to a proposal contract containing the executable calldata. Upon submission, the proposal enters a timelock queue, a mandatory delay period (e.g., 48-72 hours) before voting can begin, allowing users to review final code.

• Sub-step 1: Call the governance contract's propose() function with targets, values, and calldata.
• Sub-step 2: Verify the proposal ID is emitted in the event log and appears on block explorers.
• Sub-step 3: Monitor the timelock contract (TimelockController) for the scheduled execution transaction.

solidityCopy
// Example call to an OpenZeppelin Governor `propose` function
propose(
    targets: [0x1234...],
    values: [0],
    calldatas: ["0xabcd..."],
    description: "Proposal to upgrade Vault contract"
);

Tip: The timelock period is a critical security feature, providing a final window to detect malicious proposals.

Detailed Instructions

After the timelock delay, the voting period (e.g., 3-7 days) begins. Voting power is typically calculated via a snapshot of token balances or delegate votes at a specific block. Voters cast their choice (For, Against, Abstain) by signing a transaction or using gasless signing via tools like Snapshot or Tally. Key mechanisms include vote delegation (where users can delegate their voting power to others) and quorum requirements (a minimum percentage of total supply must participate for the vote to be valid).

• Sub-step 1: Connect wallet to governance UI (e.g., Tally, Boardroom) to see active proposals.
• Sub-step 2: Review the final proposal details and linked discussion before casting your vote.
• Sub-step 3: Sign the vote transaction or message, choosing your support stance.

solidityCopy
// Core voting logic often checks a snapshot of delegated votes
function _getVotes(address account, uint256 blockNumber) internal view returns (uint256) {
    return _delegates[account].getPastVotes(account, blockNumber);
}

Tip: Voting strategies can be complex, incorporating staked LP tokens or time-locked veTokens, so verify your calculated voting power.

Detailed Instructions

If the vote meets quorum and passes the required vote threshold (e.g., simple majority or supermajority), the proposal moves to the execution phase. Anyone (usually the proposer or a keeper) can call the execute() function on the governance contract, which relays the calldata through the timelock to the target contracts. In systems with optimistic governance (like Arbitrum), passed proposals enter a challenge period where they can be disputed by bonding funds and escalating to a dispute resolution layer.

• Sub-step 1: After the voting period ends, confirm the final vote tally and quorum on the governance dashboard.
• Sub-step 2: Call the execute function, paying the gas fee to trigger the state changes.
• Sub-step 3: In optimistic systems, monitor the challenge period for any disputes before execution is finalized.

solidityCopy
// Example execution call in a Governor contract
function execute(
    address[] memory targets,
    uint256[] memory values,
    bytes[] memory calldatas,
    bytes32 descriptionHash
) public payable returns (uint256 proposalId);

Tip: Failed proposals can often be resubmitted. Analyze the voting patterns to understand the opposition before redrafting.

Detailed Instructions

Begin by clearly defining the proposal's objective, whether it's a parameter change, treasury allocation, or smart contract upgrade. Write a detailed specification document (often a Temperature Check or Request for Comment) outlining the rationale, technical implementation, and expected impact. This document should be shared in the community forum for initial feedback. The core of the proposal is the executable calldata, which encodes the exact function calls to be executed upon passage. This typically involves the target contract address, function signature, and encoded arguments.

solidityCopy
// Example calldata for a Compound-style proposal to set a new interest rate model
// target: Comptroller contract
// signature: _setCompSpeed(address cToken, uint compSpeed)
bytes memory data = abi.encodeWithSignature("_setCompSpeed(address,uint256)", cTokenAddress, newSpeed);

Tip: Use a calldata encoder or a library like ethers.utils.Interface to generate the data payload correctly.

Detailed Instructions

Most governance systems require proposers to meet a proposal threshold before submission. This is often a minimum balance of governance tokens, which may need to be self-delegated or held by a specific delegate. For example, Uniswap governance requires 2.5M UNI delegated to your address. Alternatively, some systems like Compound use a proposal deposit (e.g., 100 COMP) that is refunded only if the proposal passes a preliminary vote. Verify your wallet holds the required tokens and that your voting power is correctly reflected on the governance dashboard. If using a deposit, ensure you approve the governance contract to spend your tokens.

• Check the protocol's documentation for the exact current threshold.
• Use getPriorVotes(address account, uint blockNumber) to verify your delegate voting power.
• For a deposit, call approve(governanceAddress, depositAmount) on the token contract first.

Tip: The required block number for vote snapshot is often one block before proposal creation, so confirm the latest protocol parameters.

Detailed Instructions

Interact directly with the governance smart contract's propose function. The function arguments typically include: an array of target addresses, an array of values (usually zero for non-payable calls), an array of calldata strings, and a description hash (the IPFS hash of your proposal description). The description is usually stored off-chain on IPFS, and its hash is submitted on-chain for immutability. Use a tool like Pinata to pin the description JSON to IPFS and obtain the CID. The transaction will revert if the proposer's voting power is below the threshold.

solidityCopy
// Example interaction for a GovernorBravo-style contract
function propose(
  address[] memory targets,
  uint256[] memory values,
  string[] memory signatures,
  bytes[] memory calldatas,
  string memory description
) public returns (uint256 proposalId);

• Targets: [0x3d9819210A31b4961b30EF54bE2aeD79B9c9Cd3B]
• Values: [0]
• Signatures: [""] (if using raw calldata)
• Calldatas: [data] (bytes from Step 1)
• Description: "QmXyZ..." (IPFS hash)

Tip: Estimate gas carefully; proposal submission is a complex transaction and may require a higher gas limit.

Detailed Instructions

After submission, the proposal enters a pending state until the voting delay elapses. Use the governance contract's state(proposalId) function to monitor its status (0=Pending, 1=Active, 2=Canceled, 3=Defeated, 4=Succeeded, 5=Queued, 6=Expired, 7=Executed). Once active, the voting period begins (e.g., 3-7 days). Proposers must actively campaign, explaining the proposal's benefits in forums and social channels to secure votes. Large token holders (whales) and delegates are key targets for outreach. Monitor voting power alignment using on-chain explorers or dashboards like Tally. Be prepared to answer technical questions about the calldata and its implications.

• Query state: await governor.state(proposalId);
• Track votes: await governor.getVotes(account, proposalSnapshotBlock);
• Calculate quorum: (forVotes + againstVotes) >= quorumVotes

Tip: The proposal proposalId is a unique uint256 derived from hashing the proposal data. Save this ID for all future tracking.

Detailed Instructions

If the proposal succeeds (passes quorum and majority vote), it must be executed. Some systems, like GovernorBravo, require a two-step process: first queue, then execute. The queue function moves the proposal to a timelock contract, introducing a mandatory delay (e.g., 48 hours) to allow users to react to the passed decision. After the timelock expires, anyone can call execute to run the encoded calldata on the target contracts. Ensure the transaction is sent to the correct contract (Governor or Timelock) and that you have the latest proposalId. Execution will fail if the proposal state is not Queued and ready, or if the underlying transaction would revert.

solidityCopy
// Example execution flow for a timelock system
// 1. Queue the proposal
timelock.queueTransaction(target, value, signature, data, eta);
// 2. After delay, execute it
timelock.executeTransaction(target, value, signature, data, eta);

• Verify execution ETA (Estimated Time of Arrival) from the queue transaction logs.
• Check that target contract states haven't changed to make the call fail.

Tip: The execute function is permissionless; you can use a service like Etherscan to send the transaction if your wallet lacks gas.