How to Architect a Proposal and Voting Lifecycle

On-chain governance architecture defines the rules and processes by which a decentralized protocol or DAO makes collective decisions. At its core, this architecture automates the proposal lifecycle—from submission and voting to execution—using smart contracts. Unlike informal off-chain discussions, on-chain governance provides a transparent, immutable, and enforceable record of decisions, directly altering protocol parameters, treasury allocations, or smart contract code. Key components include a proposal factory, voting token or mechanism, timelock controller, and an execution module. This guide focuses on architecting these components into a cohesive, secure system.

The proposal lifecycle begins with submission. A proposer, often required to stake a minimum amount of governance tokens (e.g., 100 UNI for Uniswap), submits a transaction to a ProposalFactory contract. This transaction encodes the target addresses, function signatures, and calldata for the proposed actions. The contract validates the proposal's format and the proposer's stake before emitting an event and storing the proposal with a unique ID. A voting delay period typically follows, allowing token holders to review the proposal details before voting opens, which is a critical security measure against rushed decisions.

The voting phase is governed by a VotingContract. Most systems use token-weighted voting, where one token equals one vote, though quadratic voting or conviction voting are alternatives. The contract manages a configurable voting period (e.g., 7 days for Compound) and tallies votes for, against, and abstain. To pass, a proposal must meet a quorum (minimum participation, like 4% of supply) and a majority threshold (e.g., >50% for, or 67% for sensitive upgrades). Votes are usually cast via signature-based castVoteBySig to save gas, with results stored on-chain for verification.

After a successful vote, proposals do not execute immediately. They enter a timelock period, managed by a TimelockController contract (like OpenZeppelin's). This delay, often 2-7 days, acts as a final safeguard, allowing users to exit the system if they disagree with the outcome. Once the timelock expires, any address can call the execute function, which relays the approved calldata to the target contracts. This separation of voting and execution via a timelock is a critical security pattern, preventing instant, potentially malicious state changes and providing a last-chance review.

Architecting for upgradeability and security is paramount. Governance contracts should be minimal and audited, as they hold significant power. Use proxy patterns (e.g., Transparent or UUPS) for upgradability, with the upgrade mechanism itself subject to governance. Consider emergency safeguards like a Guardian role (as seen in MakerDAO) with limited power to pause proposals. For complex parameter changes, use signaling votes off-chain via Snapshot before binding on-chain votes. Always implement comprehensive event logging for full transparency and off-chain indexing by tools like The Graph.

A governance lifecycle defines the end-to-end process for making and implementing collective decisions on-chain. The core phases are: proposal creation, voting, timelock/grace period, and execution. Each phase is enforced by smart contract logic, typically using a modular pattern where a central Governor contract orchestrates interactions with separate Voting, Timelock, and Executor modules. This separation of concerns, as seen in OpenZeppelin's Governor contracts, improves security and upgradeability. The lifecycle is parameterized by configurable values like votingDelay, votingPeriod, and proposalThreshold.

Proposals are the fundamental unit of governance action. Architecturally, a proposal is a data structure containing: a unique ID, the proposer's address, a list of target contracts, calldata for function calls, and a description hash. The propose function validates the sender has sufficient voting power (meets the proposalThreshold) and creates a new proposal in a Pending state. For security, proposals should explicitly encode all on-chain actions via targets, values, and calldata arrays. Off-chain metadata, like a Snapshot discussion link, is referenced by a hash to keep gas costs manageable.

The voting mechanism is the core of decentralized decision-making. After the votingDelay, a proposal moves to Active state. Voters cast votes using their governance token balance, often employing a vote delegation system for efficiency. Key voting strategies include: simple majority (for/against), quorum-based voting (minimum participation required), and weighted voting (like quadratic voting). Votes are typically cast as For, Against, or Abstain. The contract must implement a castVote function that respects snapshotting (checking balances at a specific block) to prevent manipulation.

Once the voting period ends, the proposal is queued if it meets two conditions: it achieved a quorum (minimum voting power participation) and received more For than Against votes. Successful proposals are then sent to a Timelock contract, which introduces a mandatory delay before execution. This delay is a critical security feature, allowing token holders to react to malicious proposals. During this period, the proposal state is Queued. The Timelock also batches multi-step operations atomically, ensuring all transactions in a proposal succeed or fail together.

After the timelock delay expires, anyone can call the execute function to run the proposal's encoded transactions. Execution changes the on-chain state by calling the functions specified in the proposal's targets and calldata. Upon successful execution, the proposal state becomes Executed. If execution fails (e.g., a revert) or the proposal is defeated in voting, it reaches a Canceled or Defeated state. It's essential to design proposal calldata carefully, simulating execution in a forked environment (using tools like Tenderly or Foundry's forge test) to avoid failed executions that waste gas and delay governance.

When architecting your system, consider key parameters and extensions. Set votingPeriod (e.g., 3-7 days) and timelockDelay (e.g., 2 days) based on your community's needs. Use contract extensions for advanced features: GovernorCountingSimple for tallying, GovernorVotes for snapshot-based voting power, and GovernorTimelockControl for timelock integration. Always implement an emergency cancel function (often restricted to a guardian) as a last-resort safety mechanism. Test the entire flow rigorously, including edge cases like proposal updates mid-vote and delegation logic.

On-chain governance systems require a formalized process to ensure proposals are properly vetted, debated, and executed. The five-stage lifecycle provides this structure: 1. Ideation & Drafting, 2. Temperature Check, 3. Formal Proposal, 4. Voting, and 5. Execution & Timelock. This model, used by protocols like Compound and Uniswap, creates clear guardrails for community-led decision-making. Each stage has a specific purpose, from gathering initial feedback in off-chain forums to the final on-chain execution of code via a timelock contract.

The lifecycle begins with Ideation & Drafting. Here, a community member or core team drafts a proposal, typically as a Governance Proposal Request (GPR) or a similar document. This occurs in off-chain forums like the Uniswap Governance Forum or Compound's Discourse. The draft outlines the problem, proposed solution, and technical specifications. This stage is crucial for gathering initial community sentiment and identifying potential flaws before consuming on-chain resources, which can be expensive on networks like Ethereum.

Next, a Temperature Check gauges broad community support. This is often a simple, non-binding snapshot vote using tools like Snapshot. It answers the question: "Is this proposal worth pursuing to a formal vote?" A successful temperature check, often requiring a minimum quorum and approval threshold (e.g., 50,000 votes and 50% approval), signals the proposer to move forward. This stage filters out poorly conceived or unpopular ideas, preventing governance fatigue and unnecessary on-chain transactions.

The Formal Proposal stage codifies the idea into an executable on-chain transaction. The proposer submits the finalized code—such as a parameter change or a new contract address—to the governance contract. This usually requires the proposer to lock a proposal bond (e.g., 2,500 UNI for Uniswap). The proposal enters a review period, a delay (often 2-7 days) where delegates and security experts can audit the code for bugs or malicious intent before voting begins, a critical security measure.

Voting is the core decision-making phase. Token holders or their delegates cast votes, with weight proportional to their stake, during a fixed window (e.g., 7 days). Different voting mechanisms are used: Simple Majority, Quadratic Voting, or Weighted Voting. The proposal must meet predefined criteria to pass, commonly a minimum quorum (e.g., 4% of circulating supply) and an approval threshold (e.g., >50% for, with <33.4% against for a veto). Votes are immutable and recorded on-chain.

Finally, Execution & Timelock ensures safe implementation. Once a proposal passes, it does not execute immediately. It is queued in a timelock contract—a mandatory delay period (e.g., 48 hours for Compound). This gives users a final window to exit systems or prepare for changes if they disagree with the outcome. After the delay, any address can call the execute function to run the proposal's encoded transactions. This stage is the ultimate safeguard, preventing immediate execution of potentially harmful code.

The proposal lifecycle is the core state machine of any governance system. A typical flow begins with a proposal creation phase, where an authorized address submits a transaction containing the proposal's metadata and executable calldata. The system must validate prerequisites, such as the proposer's token balance or delegate status, and enforce a timelock or delay period before voting begins. This initial state is crucial for preventing spam and allowing community review. Smart contracts like OpenZeppelin's Governor provide a standardized base for this lifecycle, defining states like Pending, Active, Canceled, Defeated, Succeeded, Queued, and Expired.

Voting logic determines how votes are cast, counted, and tallied. The most common pattern is token-weighted voting, where each governance token (e.g., UNI, COMP) grants one vote. Implementations must decide between simple majority (50%+1 of votes cast) and supermajority (e.g., 66.67%) thresholds for passage. More advanced systems employ quadratic voting to reduce whale dominance or conviction voting to weight votes by the duration of token commitment. The voting contract must handle vote delegation, snapshotting token balances at a specific block to prevent manipulation, and securely recording votes on-chain.

A quorum is the minimum level of participation required for a vote to be valid. Without it, a small, unrepresentative group could pass proposals. Quorums are typically defined as a percentage of the total token supply (e.g., 4% of all UNI) rather than votes cast. In the Governor contract, this is enforced in the _quorumReached function. Setting this parameter is critical: too high and governance is paralyzed; too low and it's insecure. Many DAOs implement adaptive quorums that adjust based on historical participation or proposal type, a pattern used by Compound and Uniswap.

The final stage is proposal execution. After a vote succeeds and any mandatory timelock expires, the approved calldata can be executed. This often involves a TimelockController contract, which queues and executes transactions after a delay, providing a safety window for the community to react to malicious proposals. Execution must be permissioned, typically allowing any address to trigger it, which prevents obstruction. The logic must also handle edge cases: what happens if the target transaction reverts? How are expired proposals cleaned up? Robust systems include a cancel function for the proposer and a guardian role for emergency intervention.

Here is a simplified code snippet illustrating core voting and quorum logic using a Solidity pattern:

solidityCopy
function castVote(uint256 proposalId, uint8 support) external {
    require(state(proposalId) == ProposalState.Active, "Voting closed");
    uint256 voterWeight = getVotes(msg.sender, proposalSnapshot(proposalId));
    require(voterWeight > 0, "No voting power");
    _castVote(proposalId, msg.sender, support, voterWeight);
}

function _quorumReached(uint256 proposalId) internal view returns (bool) {
    Proposal storage proposal = _proposals[proposalId];
    uint256 totalSupplyAtSnapshot = getPastTotalSupply(proposal.snapshotBlock);
    return proposal.forVotes + proposal.againstVotes >= (totalSupplyAtSnapshot * quorumNumerator) / quorumDenominator;
}

This shows vote casting with snapshot-based power and a quorum check against the historic total supply.

When architecting your system, key decisions include: the voting period length (3-7 days is common), proposal threshold for submission, quorum basis (supply vs. circulating), and upgradability mechanisms. Always audit the integration between the governor, token, and timelock contracts. For further reading, study the source code of established systems like Compound Governor Bravo and OpenZeppelin's Governance documentation.

A timelock is a smart contract that acts as a queue and delay mechanism for transactions. When integrated into a governance system, it sits between the voting contract (like Governor Bravo) and the target protocol. After a proposal passes, its encoded actions are not executed immediately. Instead, they are scheduled into the timelock with a predefined delay, typically 2-7 days. This creates a crucial window for users to review the exact calldata, assess risks, and exit the system if necessary. It is a foundational security pattern used by major protocols like Compound and Uniswap to prevent malicious or buggy proposals from causing instant, irreversible damage.

Architecting the proposal lifecycle requires connecting three core components: the Governor, the Timelock, and the Executor. The Governor contract handles proposal creation, voting, and quorum logic. Once a proposal succeeds, the Governor does not call the target function directly. It calls queue on the Timelock contract, which stores the proposal's target, value, calldata, and a future eta (estimated time of arrival). The Timelock enforces that block.timestamp >= eta before allowing the execute function to be called, which finally performs the intended action. This separation of concerns ensures the voting logic is distinct from the execution logic.

Implementing this with OpenZeppelin's contracts provides a standardized and audited foundation. A typical setup involves deploying a TimelockController contract, specifying the minDelay and a list of proposers (initially just the Governor) and executors. The Governor contract is then deployed, configured to use the Timelock's address as its executor. Proposals are built by encoding function calls to the target contracts. For example, a proposal to update a protocol fee might encode a call to FeeManager.setFee(500) for a specific target address. This encoded data is what gets queued and later executed by the timelock.

The security benefits are significant. The delay allows for: Last-minute vetoes by a guardian role (if configured), Public scrutiny of the exact transaction bytes on-chain, and User protection where participants can withdraw funds if they disagree with a passed action. It also mitigates flash loan governance attacks by removing the ability to borrow votes, pass, and execute a malicious proposal within a single block. However, it introduces latency, making the system slower to respond to emergencies. Some protocols use a separate, shorter Emergency Timelock for critical security patches, governed by a smaller, more trusted multisig.

When testing, you must account for the delay. In a local fork or testnet, you can simulate the passage of time using ethers.provider.send('evm_increaseTime', [delay]) and then mine a new block. A full integration test should verify the flow: 1. Proposal is created and voted on, 2. After passing, it is successfully queued in the timelock, 3. Execution fails if attempted before the delay, and 4. Execution succeeds after the delay has elapsed. This ensures the entire lifecycle—from proposal to delayed execution—functions as a secure, autonomous system.

A failed on-chain upgrade, such as a rejected proposal or a buggy contract deployment, can halt a protocol. The primary defense is a multi-stage proposal lifecycle. A typical flow includes a Temperature Check (forum sentiment), a Consensus Check (formal off-chain vote), and finally an Execution stage. This phased approach allows the community to identify flaws and build consensus before any irreversible on-chain action. Critical proposals, especially those modifying core protocol logic or treasury access, should require higher quorums and longer voting periods to ensure broad participation and scrutiny.

The most critical technical safeguard is a timelock. Before execution, a successfully passed proposal is queued in a timelock contract for a predefined period (e.g., 48-72 hours). This creates a mandatory review window where any user can analyze the exact calldata that will be executed. During this period, governance participants or a dedicated security council can cancel the proposal if a critical vulnerability is discovered. The Compound Governor Bravo contract is a canonical implementation of this pattern, separating the voting and execution logic with an explicit timelock.

For maximum safety, the upgrade mechanism itself should be modular and pausable. Instead of upgrading a monolithic core contract, use a proxy pattern (like Transparent or UUPS) where a proxy points to a logic contract. The upgrade proposal changes this pointer. A fallback procedure involves maintaining an escape hatch—a privileged function (guarded by a separate, simpler multisig or a delayed governance) that can pause the new logic contract and revert the proxy to a known-good previous version. This is a last-resort rollback mechanism.

Code examples solidify these concepts. A basic timelock check in a proposal validation function might look like:

solidityCopy
require(block.timestamp >= proposal.eta, "Timelock: execution before ETA");
require(!proposal.canceled, "Timelock: proposal canceled");

Furthermore, the proposal execution function should explicitly verify the target and calldata hash against what was voted on, preventing execution of modified transactions.

solidityCopy
bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta));
require(txHash == proposal.txHash, "Governor: proposal hash mismatch");

Beyond the smart contract layer, operational fallbacks are essential. Maintain clear off-chain communication channels (like Discord, Twitter, emergency forums) to alert the community of a suspected issue during the timelock window. Establish a pre-defined process for security researchers to submit critical bugs, potentially with a bug bounty for findings that lead to a cancellation. The final fallback is social consensus: if all automated systems fail, the community must be prepared to coordinate a social migration to a new, corrected contract suite, using token snapshots from a block prior to the faulty upgrade.

You now have a blueprint for a basic on-chain governance system. The core lifecycle—proposal creation, a timelock delay, on-chain voting, and automated execution—provides a foundation for decentralized decision-making. To implement this, you would deploy the smart contracts, configure parameters like votingDelay and votingPeriod, and connect a frontend interface for user interaction. Remember that security is paramount; always use established, audited libraries like OpenZeppelin's Governor contracts as your base.

For production systems, consider integrating more sophisticated mechanisms. Gasless voting via signatures (like EIP-712) can drastically improve voter participation. Treasury management modules, such as a multisig executor or a Zodiac Safe module, add an extra layer of security for high-value transactions. Furthermore, explore snapshot voting for off-chain signaling on complex proposals before committing gas fees for on-chain execution. Tools like Tally and Sybil can help delegate voting power and analyze governance activity.

Your architecture should evolve with your DAO's needs. Start with a simple, secure Governor contract and incrementally add complexity. Continuously monitor key metrics: proposal turnout, voting power concentration, and execution success rates. Engage with the broader ecosystem by reviewing the documentation for leading frameworks like OpenZeppelin Governor and Compound's Governor Bravo. The goal is to create a system that is not only functional but also resilient, transparent, and aligned with your community's values.