Setting Up a Proposal and Voting Framework for Platform Upgrades

Decentralized governance frameworks transform protocol development from a centralized process into a community-driven one. At its core, this involves creating a system where token holders can submit on-chain proposals, signal their preferences through weighted voting, and automatically execute approved upgrades. This guide focuses on implementing a standard Governor contract using OpenZeppelin's modular libraries, which provide battle-tested security patterns for functions like proposal lifecycle management, vote tallying, and timelock execution. We'll build a system compatible with ERC-20, ERC-721, or ERC-1155 voting tokens.

The first step is defining the governance parameters that dictate the proposal process. These are critical security and operational levers set in the contract's constructor:

• Voting Delay: The number of blocks between a proposal's submission and the start of the voting period.
• Voting Period: The duration (in blocks) during which votes can be cast.
• Proposal Threshold: The minimum token balance required to submit a proposal.
• Quorum: The minimum percentage of the total voting power that must participate for a vote to be valid. For a DAO managing a high-value protocol, you might set a 2-day voting delay (17280 blocks on Ethereum), a 7-day voting period (50400 blocks), a proposal threshold of 100,000 tokens, and a quorum of 4%.

Here is a foundational implementation using Solidity and OpenZeppelin's Governor contract, which handles the core state machine for proposals. This example uses the GovernorSettings module to configure the parameters and GovernorCountingSimple for majority voting logic.

solidityCopy
import "@openzeppelin/contracts/governance/Governor.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorSettings.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorCountingSimple.sol";

contract ProtocolGovernor is Governor, GovernorSettings, GovernorCountingSimple {
    constructor(IVotes _token)
        Governor("ProtocolGovernor")
        GovernorSettings(7200 /* 1 day */, 50400 /* 1 week */, 1e18)
    {}

    function votingDelay() public view override(IGovernor, GovernorSettings) returns (uint256) {
        return super.votingDelay();
    }
    // ... Override other required functions for votingPeriod, quorum, etc.
}

The contract inherits the proposal lifecycle, where a proposal moves from Pending to Active, Succeeded or Defeated, and finally Queued and Executed.

To enable secure, trust-minimized execution of approved proposals, you must integrate a TimelockController. This contract acts as the sole executor for the Governor, introducing a mandatory delay between a proposal's approval and its execution. This delay provides a critical safety mechanism, allowing users to review the executed code or exit the system if a malicious proposal passes. The Governor is configured as a "Proposer" role, and a separate multisig or EOA is typically set as the "Executor." The flow becomes: Proposal succeeds → Governor queues it in the Timelock → Delay elapses → Anyone can trigger execution.

Submitting and voting on a proposal involves calling specific functions in the Governor contract. A proposal is created by calling propose(), which takes arrays of target addresses, ETH values, and calldata for the actions to be executed. Voting is done via castVote(proposalId, support), where support is an integer (e.g., 1 for For, 0 Against). Voting power is typically snapshot at the block when the proposal is created, preventing last-minute token buying ("vote buying"). After the voting period ends, anyone can call queue() to send the proposal to the Timelock, and after the delay, execute() to run the encoded transactions.

For production systems, consider advanced modules like GovernorVotes for snapshot-based voting power, GovernorVotesQuorumFraction for dynamic quorum, and GovernorTimelockControl for Timelock integration. Always conduct thorough audits on the final governance suite. Real-world examples include Compound's Governor Bravo and Uniswap's governance system, which have processed billions in protocol upgrades. The final framework empowers a community to manage treasury funds, adjust system parameters, and upgrade contract logic in a transparent and verifiable manner on-chain.

The first prerequisite is a development environment capable of interacting with a blockchain. You will need Node.js (v18 or later) and a package manager like npm or Yarn installed. Essential tools include Hardhat or Foundry for smart contract development and testing, along with a wallet such as MetaMask for transaction signing. Familiarity with a blockchain explorer like Etherscan for the target network (e.g., Ethereum Sepolia, Polygon Mumbai) is also required to verify deployments and track transactions.

Core technical requirements center on the smart contract architecture. You will need a basic understanding of Solidity (0.8.x) to write and audit the governance contracts. The framework typically consists of three main contracts: a governance token (ERC-20 or ERC-1155) for voting power, a timelock controller (like OpenZeppelin's) to queue and execute successful proposals, and the core governor contract (e.g., OpenZeppelin Governor) that manages proposal lifecycle and voting logic. Setting up a local testnet with Hardhat is recommended for initial development.

You must also configure your project dependencies. Initialize a new project and install critical libraries: @openzeppelin/contracts for secure, audited base contracts and @nomicfoundation/hardhat-toolbox for the Hardhat development stack. A hardhat.config.js file must be set up with network configurations, including RPC URLs for testnets and your account's private key (stored securely in a .env file using dotenv). This setup allows you to compile, test, and deploy your contracts.

Understanding the proposal lifecycle is a key conceptual prerequisite. A standard flow involves: 1) Proposal submission with calldata, 2) A voting delay period, 3) An active voting period where token holders cast votes, 4) A timelock period for execution queuing, and 5) Final execution. You must decide on critical parameters like voting delay, voting period (e.g., 3 days), proposal threshold (minimum tokens to propose), and quorum (minimum votes for a proposal to pass).

Finally, prepare for front-end integration. While the backend is the smart contract system, you'll likely need a web interface for users. This requires a framework like Next.js or Vite, and libraries such as wagmi and viem for blockchain interaction, or web3.js/ethers.js. You will need to connect your UI to read proposal state, token balances, and to trigger transactions for creating proposals and casting votes. Testing the full stack end-to-end on a testnet is the final step before mainnet consideration.

A robust governance framework is essential for decentralized platforms to evolve without centralized control. This process typically involves three core phases: proposal creation, voting, and execution. The lifecycle begins when a community member or core developer drafts a formal proposal, often a Governance Proposal Standard like Ethereum's EIP or a DAO-specific template. This document outlines the proposed changes, which can range from adjusting protocol parameters (like fees or rewards) to upgrading smart contract logic. The proposal is then submitted to a governance smart contract, such as OpenZeppelin's Governor or a custom implementation, which enforces the rules of the process.

Once submitted, the proposal enters a timelock period before voting begins. This delay allows token holders to review the technical details and implications. Voting is usually conducted on-chain using governance tokens, with common models being token-weighted voting (one token, one vote) or delegated voting where users assign voting power to representatives. Key parameters must be configured in the governance contract: the voting delay (time between proposal and vote start), voting period (duration of the vote, e.g., 3-7 days), and quorum (minimum participation required for validity). For example, a Compound Governor contract might set a quorum of 4% of total token supply.

The technical implementation involves deploying and configuring specific smart contracts. A standard setup using OpenZeppelin Contracts includes a TimelockController to queue executed proposals and a Governor contract that references the token and timelock. The proposal's calldata—the encoded function calls to upgrade contracts—is critical. Here's a simplified flow: a proposer calls propose() on the Governor with target addresses, values, and calldata. If the vote passes the quorum and majority threshold, anyone can call execute() to send the approved transactions through the timelock. Security best practices include using a multisig as the timelock executor and conducting thorough audits on both the governance contracts and the upgrade logic itself.

Successful governance requires clear communication and tooling. Proposals should be discussed extensively on forums like Commonwealth or Discourse before on-chain submission. Voting interfaces like Tally or Snapshot (for gasless off-chain signaling) make participation accessible. After execution, the changes are live. It's crucial to monitor the upgrade via on-chain analytics and have a rollback plan or emergency shutdown mechanism in case of vulnerabilities. This end-to-end framework ensures platform upgrades are transparent, participatory, and secure, aligning protocol evolution with the collective will of its stakeholders.

A proposal smart contract is a specialized contract that manages the lifecycle of a governance proposal. Its primary functions are to store proposal metadata (title, description, target contract, calldata), enforce a voting period, tally votes according to a predefined mechanism (e.g., token-weighted, quadratic), and execute the approved transaction on-chain. This contract acts as the single source of truth, ensuring all governance actions are transparent, immutable, and verifiable by anyone. Popular frameworks like OpenZeppelin's Governor provide modular, audited base contracts to build upon.

The contract's design must explicitly define the proposal state machine. Typical states include Pending, Active, Canceled, Defeated, Succeeded, Queued, and Executed. Transitions between these states are triggered by specific conditions, such as the passage of time (voting period ending) or the execution of a privileged function (like execute). Implementing clear state transitions prevents proposals from being stuck or executed under invalid conditions, which is a critical security consideration.

Key parameters must be set in the contract's constructor or via initialization. These include the voting delay (time between proposal submission and voting start), voting period (duration of the active vote), proposal threshold (minimum voting power required to submit), and quorum (minimum percentage of total supply that must participate for a vote to be valid). For example, a common setup on an L2 might be a 1-block voting delay, a 5-day (≈ 34,560 blocks) voting period, and a quorum of 4% of the token supply.

The most critical function is the proposal execution logic. After a vote succeeds, the execute function calls the target contract with the encoded calldata. This must include security checks to re-verify the proposal state and voting outcome before performing the low-level call. A timelock contract is often inserted between the Governor and the target, introducing a mandatory delay between proposal approval and execution. This gives users a final window to exit the system if they disagree with the upgrade.

When writing the contract, use existing standards and audits as a foundation. The Compound/Aave Governor model, implemented in OpenZeppelin Contracts, is the industry standard. Start by extending Governor, GovernorCompatibilityBravo, or GovernorTimelockControl. Your main tasks are to configure the parameters mentioned above and optionally override functions like _quorumReached or _voteSucceeded to implement custom voting logic. Always include comprehensive event emissions for each state change to enable off-chain indexing and user interface updates.

Finally, thorough testing is non-negotiable. Write unit and integration tests that simulate the full proposal lifecycle: submission, voting with various weights, state transitions, and execution. Test edge cases like attempting to execute a defeated proposal, voting after the period ends, and meeting/exceeding quorum requirements. Use forked mainnet tests to validate interactions with real token contracts. The security of your entire upgrade mechanism depends on the robustness of this single contract.

The choice between an on-chain or off-chain voting module defines the governance system's finality and gas efficiency. On-chain voting, using contracts like OpenZeppelin's Governor, executes upgrades automatically upon a successful vote, providing maximum transparency and immutability. Off-chain voting, using tools like Snapshot, is gas-free and used for signaling community sentiment, requiring a separate, trusted execution step. Most mature DAOs use a hybrid model: Snapshot for frequent, low-stakes polls and an on-chain Governor for binding treasury or protocol upgrades.

For on-chain implementation, the Governor contract suite is the industry standard. Your setup involves deploying at least three contracts: the Governor contract itself, a Voting Token (often an ERC-20 or ERC-721), and a TimelockController for safe execution. The Governor contract defines key parameters: votingDelay (time between proposal submission and voting start), votingPeriod (duration of the vote), and quorum (minimum voting power required). A common starting configuration is a 1-block delay, a 3-day voting period, and a 4% quorum, which you can adjust based on token distribution.

Proposals are created by calling propose() on the Governor contract, which takes an array of target addresses, values, and calldata for the actions to execute. For example, to upgrade a proxy contract, the calldata would be the encoded function call to upgradeTo(address). Once a proposal is active, token holders cast votes using castVote(proposalId, support), where support is 0 (against), 1 (for), or 2 (abstain). Votes are weighted by the holder's token balance at the block snapshot taken when the proposal was created.

Integrating a TimelockController is a critical security best practice. It sits between the Governor and the protocol, introducing a mandatory delay between a vote's conclusion and the execution of its actions. This delay gives users a final window to exit the system if they disagree with an upgrade. The Governor is set as a "Proposer" on the Timelock, and the protocol's admin or owner role is transferred to the Timelock address, ensuring only successful proposals can execute privileged actions.

For off-chain voting with Snapshot, you create a space linked to your token contract. Proposals are created via a UI or API, and votes are signed cryptographically, incurring no gas costs. While not binding on-chain, Snapshot votes can be used to gate the creation of on-chain proposals or guide multi-sig signers. The integrity relies on the "Snapshot block number" which records token balances, preventing sybil attacks. This makes it ideal for gathering consensus on strategic direction, grant funding, or parameter adjustments before an on-chain proposal is drafted.

To connect off-chain sentiment to on-chain execution, you can implement a validation contract. For instance, an on-chain proposal's propose() function could require a passed Snapshot proposal ID as a parameter, checking a registry contract that confirms the vote succeeded. This creates a two-step governance process: signal off-chain, execute on-chain. Always thoroughly test the entire flow—from proposal creation to execution—on a testnet using frameworks like Hardhat or Foundry, simulating various voting outcomes and edge cases before mainnet deployment.

The governance framework is defined by three critical parameters: quorum, approval threshold, and timelock. Quorum is the minimum percentage of the total voting power that must participate for a vote to be valid. This prevents a small, active group from making decisions without broader community engagement. For example, a 4% quorum on a token with 10 million supply requires at least 400,000 tokens to be used in voting. Setting this too high can lead to voter apathy and governance paralysis, while setting it too low risks low-engagement attacks.

The approval threshold is the percentage of participating votes (not total supply) required for a proposal to pass. Common thresholds are simple majority (51%) or supermajority (e.g., 66.67%). A higher threshold provides more security for major protocol changes but makes passing any proposal more difficult. These parameters are often set in the governance contract's constructor or via a privileged function. For instance, in an OpenZeppelin Governor contract, you might initialize it with _quorumNumerator = 400 (for 4%) and _votingDelay, _votingPeriod blocks.

A timelock is a mandatory delay between a proposal's successful vote and its execution. This is a critical security mechanism, acting as a final circuit breaker. During the timelock period (e.g., 48 hours), users can review the executed calldata and, if a malicious proposal somehow passed, exit the system or prepare a response. The timelock contract holds the protocol's upgrade authority, and the Governor contract schedules transactions onto it. This separation of powers (voting vs. execution) is a best-practice design pattern.

Here is a simplified example of initializing these parameters in a contract derived from OpenZeppelin's Governor and TimelockController:

solidityCopy
// Example Constructor Setup
uint48 public constant MIN_DELAY = 2 days; // 48-hour timelock
uint256 public constant VOTING_DELAY = 1; // 1 block
uint256 public constant VOTING_PERIOD = 45818; // ~7 days in blocks
uint256 public constant QUORUM_PERCENTAGE = 4; // 4% quorum

constructor(IVotes _token, TimelockController _timelock)
    Governor("MyGovernor")
    GovernorVotes(_token)
    GovernorVotesQuorumFraction(QUORUM_PERCENTAGE) // Sets quorum
    GovernorTimelockControl(_timelock) // Integrates timelock
{}

function votingDelay() public pure override returns (uint256) { return VOTING_DELAY; }
function votingPeriod() public pure override returns (uint256) { return VOTING_PERIOD; }

The GovernorVotesQuorumFraction sets the quorum based on token supply, and GovernorTimelockControl delegates execution.

Choosing the right values is a governance decision in itself. Start with conservative defaults for a new DAO: a moderate quorum (2-5%), a high approval threshold for upgrades (66-75%), and a timelock long enough for community reaction (24-72 hours). These parameters can and should be updated via governance proposals as the DAO matures. The goal is to balance security against stagnation, ensuring the platform can evolve without being captured by a malicious actor or held hostage by voter inertia.

A well-structured proposal template serves multiple critical functions. It enforces consistency across submissions, making it easier for voters to understand and compare different initiatives. It acts as a pre-flight checklist, ensuring all necessary technical and financial details are included before a proposal goes on-chain. For developers, it provides a clear specification; for token holders, it offers a transparent breakdown of the ask. Without standardization, governance can become chaotic, with proposals ranging from vague ideas to overly technical specifications that alienate non-technical participants.

The core components of a proposal template should address the what, why, how, and cost. Start with a clear title and a concise summary. The main body must detail the problem statement and the proposed solution. For platform upgrades, this includes specifying the smart contract addresses to be upgraded, the new bytecode or source code (often via an IPFS hash), and the functions that will be altered. A critical section is the technical impact analysis, which should outline any state changes, storage variable migrations, or potential risks to system invariants.

Financial and operational details are non-negotiable. The template must include a budget request denominated in the native governance token or a stablecoin, with a justification for the amount. For multi-sig or delegate execution, specify the executor address. Include a voting timeline (e.g., 3-day voting period, 1-day timelock) and a clear execution plan. Many DAOs, like Uniswap or Compound, publish their canonical templates on their governance forums, providing a real-world reference. Using a markdown template stored in a GitHub repository ensures version control and community contributions to the template itself.

For code-based proposals, integrate executable specifications directly into the template. This often involves linking to an Ethereum Improvement Proposal (EIP) number, a verified contract on Etherscan, or a diff between the old and new code. A template might include a section for Test Instructions with a link to a forked testnet environment and Verification Steps for post-upgrade checks. Here is a minimal example structure for a Solidity contract upgrade proposal:

codeCopy
## Target Contract
- Address: 0x...
- Current Implementation: 0x...
- New Implementation: 0x... (IPFS: Qm...)

## Code Diff & Audit
- Diff Link: https://github.com/org/repo/pull/123
- Audit Report: [Security Firm](https://audit.link)

## Execution
- Timelock Delay: 48 hours
- Executor: 0x... (DAO Treasury Multisig)

Finally, establish a pre-proposal discussion requirement in your governance process. Mandate that a draft using the template is posted to a forum like Commonwealth or the project's Discord for community feedback before an on-chain vote. This social layer catches ambiguities, builds consensus, and refines the technical details, increasing the proposal's chance of success. The template is not just a form to fill out; it's a framework for collaborative decision-making that aligns technical execution with community intent.

The frontend acts as the user's gateway to the governance system. Using a framework like React or Next.js with a Web3 library such as wagmi or ethers.js, you connect to the user's wallet (e.g., MetaMask). The core tasks are to fetch live data from the governance contract—like active proposals, vote tallies, and member status—and to provide interfaces for key actions: creating proposals, casting votes, and executing passed proposals. State management is crucial for reflecting real-time blockchain data and transaction states (pending, confirmed, failed).

The execution flow begins when a member with sufficient tokens creates a proposal. The frontend calls the createProposal function, sending the calldata for the intended upgrade (e.g., a function call to a Timelock contract). During the voting period, members call vote with their choice (For, Against, Abstain). A crucial frontend responsibility is calculating and displaying voting power, which often involves querying the user's token balance or delegated votes at the snapshot block defined in the proposal.

Once a proposal succeeds, any member can trigger its execution. The frontend calls the executeProposal function, which validates all conditions (quorum, majority, timelock delay) before forwarding the stored calldata to the target contract. This is where the actual platform upgrade occurs. Implementing clear transaction status feedback and event listening is essential for user confidence. For a production system, consider integrating The Graph for efficient historical querying or Safe{Wallet} for multi-signature execution.

Security in the frontend is paramount. Always use the checks-effects-interactions pattern indirectly by relying on the contract's security. Validate all user inputs on the client-side to prevent revert gas waste. Use Chainlink Data Feeds or similar oracles if proposals require off-chain data for execution. The UI should also guard against common pitfalls like replay attacks on signed messages or incorrectly calculated voting power.

A complete example for casting a vote using ethers.js and a typical governance ABI involves: connecting the signer, constructing the transaction for the vote(uint256 proposalId, uint8 support) function, and handling the response. After execution, the frontend should re-fetch the proposal state to update the UI, showing the new vote count and whether the proposal is ready to be executed.

Successfully deploying a proposal and voting framework involves integrating several key components. You must deploy your custom Governor contract, which defines the voting rules and timelock. Next, deploy the TimelockController, a critical security module that enforces a mandatory delay between a proposal's approval and its execution. Finally, you grant the TimelockController the PROPOSER_ROLE in your Governor and assign the EXECUTOR_ROLE and potentially CANCELLER_ROLE to trusted entities (like a multisig or the zero address for open execution). The TimelockController will then hold the admin privileges for the upgradeable contracts, such as a TransparentUpgradeableProxy managed by OpenZeppelin.

The security of your governance system hinges on the integrity of the voting token and the proposal lifecycle. Use a reputable, audited token standard like OpenZeppelin's ERC20Votes or ERC721Votes to prevent double-voting and ensure accurate vote snapshotting. Proposal thresholds (minimum votes required) and quorums (minimum participation) must be set carefully to balance accessibility with security against low-turnout attacks. All proposals should include a detailed description and on-chain calldata for transparent review. The mandatory timelock period between vote completion and execution is non-negotiable; it provides a final safety net for users to react to malicious proposals.

Beyond the core contracts, operational security is paramount. Never store private keys for the Timelock's PROPOSER_ROLE or admin roles on a single machine. Use a hardware wallet or a decentralized multisig like Safe for these roles. Conduct regular security audits of the entire governance and upgrade stack, especially after any modifications. Establish clear community guidelines for proposal submission and encourage thorough discussion off-chain (e.g., in forums) before creating on-chain proposals. Monitor for governance attacks, such as token borrowing to manipulate votes ("governance attacks"), and consider implementing defenses like vote delegation or a protocol-owned liquidity pool to increase the cost of such attacks.