Setting Up On-Chain Voting for Public Budget Prioritization

On-chain participatory budgeting (PB) is a governance mechanism that allows a community to directly propose, debate, and vote on how a shared treasury should be spent. Unlike traditional governance votes that often focus on protocol parameters or leadership, PB specifically allocates funds to public goods, community initiatives, or infrastructure projects. This process is executed via smart contracts on a blockchain, ensuring that the voting is transparent, tamper-proof, and automatically enforceable. The core components are a funding pool (the treasury), a proposal submission system, a voting mechanism, and an execution module that disburses funds based on the vote's outcome.

The first step in setting up a system is to define the voting parameters and eligibility. Key decisions include: Who can vote? This is typically based on token ownership (e.g., one-token-one-vote) or a delegated reputation system like quadratic voting to mitigate whale dominance. What is the voting mechanism? Common choices are simple majority, ranked-choice, or conviction voting. What is the proposal lifecycle? This includes submission requirements, a review or challenge period, the voting window, and a timelock for execution. These rules are codified into the smart contract logic before deployment, forming the immutable rules of the process.

A basic implementation involves several smart contracts. A Treasury contract holds the funds, often in a stablecoin like USDC or the network's native token. A Governor contract (inspired by OpenZeppelin's Governor standard) manages the proposal lifecycle. Proposers interact with a ProposalFactory to submit their budget requests, which include a recipient address, requested amount, and description. The voting power snapshot is typically determined by a VotingToken (ERC-20 or ERC-721) held in a user's wallet at a specific block. After the voting period ends, authorized executors can call the execute function on the Governor, which, if the proposal succeeded, instructs the Treasury to transfer funds.

For developers, a common starting point is the OpenZeppelin Governor contracts. You can extend the Governor base contract and configure it with a custom voting module and token. Here's a simplified example of a proposal submission and voting flow in a script:

javascriptCopy
// Pseudocode for proposal lifecycle
const proposalDescription = "Fund community garden: 5000 USDC";
const target = [gardenTreasury.address];
const values = ["0"];
const calldatas = [treasury.interface.encodeFunctionData('transfer', [gardener, ethers.utils.parseUnits('5000', 6)])];

// Propose
governor.propose(target, values, calldatas, proposalDescription);
// After review period, voters cast votes
governor.castVote(proposalId, 1); // 1 = For
// Execute after successful vote and timelock
governor.execute(target, values, calldatas, descriptionHash);

Security and Sybil resistance are critical. A naive one-token-one-vote system is vulnerable to vote buying and manipulation. Consider implementing sybil-resistant primitives like proof-of-personhood (e.g., BrightID, Worldcoin) for identity verification, or use a conviction voting model where voting power increases the longer tokens are locked in support of a proposal. All contracts should undergo rigorous audits, and major treasury actions should be protected by a timelock to give the community time to react to malicious proposals. Using established frameworks like Aragon, Colony, or Tally can reduce custom code and associated risks.

Successful on-chain PB requires more than just code; it needs active community engagement. Tools like Snapshot for off-chain signaling can help gauge sentiment before formal on-chain proposals. Transparency is paramount: all proposals, discussion, and vote histories should be easily accessible on block explorers and frontends like Tally or Boardroom. By combining robust smart contract architecture with clear community guidelines, on-chain participatory budgeting becomes a powerful tool for decentralized, transparent, and community-owned resource allocation.

Before deploying an on-chain voting system, you must establish a development environment and understand the core architectural components. The primary prerequisites are a Node.js environment (v18+), a package manager like npm or yarn, and a code editor such as VS Code. You will also need a basic understanding of Solidity for smart contracts, TypeScript/JavaScript for the frontend, and familiarity with a development framework like Hardhat or Foundry. Access to a blockchain node via a provider like Alchemy or Infura is essential for deployment and testing.

The system architecture follows a modular design separating concerns for security and scalability. The smart contract layer is the core, containing the voting logic, proposal management, and fund distribution. It is typically deployed on an EVM-compatible chain like Ethereum, Arbitrum, or Polygon. The frontend client layer, built with a framework like Next.js or React, interacts with the contracts via a library such as wagmi and viem. A backend indexer or subgraph (using The Graph) is often required to efficiently query complex voting data and proposal history from the chain.

Key smart contracts include a VotingToken (ERC-20 or ERC-1155) for governance rights, a Governor contract (often based on OpenZeppelin's Governor) to manage proposals and voting, and a Treasury (like OpenZeppelin's TimelockController) to securely hold and execute budget transfers. The Governor contract defines critical parameters: the voting delay (time between proposal submission and voting start), voting period (duration of the vote), and proposal threshold (minimum tokens required to submit a proposal). These values must be carefully calibrated for your community.

For the frontend, you'll need to integrate a wallet connection provider like RainbowKit or ConnectKit to authenticate users. The UI must fetch live proposal data, display voting options, and facilitate transaction signing. Since on-chain voting gas costs can be prohibitive, consider implementing gasless voting via meta-transactions with a relayer or using a Layer 2 solution. Always use verified contract addresses and published ABIs in your client to ensure transparency and security for end-users.

A critical architectural decision is the choice of voting mechanism. A simple token-weighted voting (1 token = 1 vote) is common but can lead to whale dominance. Alternatives include quadratic voting (where vote cost increases quadratically) or conviction voting (where voting power accrues over time). Your Governor contract must be customized to implement the chosen mechanism. Testing this logic thoroughly on a testnet like Sepolia or Goerli is non-negotiable before any mainnet deployment.

Finally, establish a clear workflow: 1) A community member submits a proposal with a calldata payload for budget distribution. 2) After the voting delay, token holders cast their votes. 3) If the proposal meets quorum and passes, it enters a timelock period for review. 4) After the timelock, anyone can execute the proposal, triggering the treasury to release funds. This multi-step process with built-in delays is crucial for preventing rushed or malicious budget allocations.

We'll use Foundry, a modern smart contract development toolkit written in Rust, for this project. It provides a fast testing framework, a local blockchain (Anvil), and a deployment tool (Forge). Start by installing Foundry via its installer script: curl -L https://foundry.paradigm.xyz | bash followed by foundryup. Verify the installation with forge --version. Then, create a new project directory and initialize it: forge init onchain-quadratic-voting. This command generates a standard project structure with src/ for contracts, test/ for tests, script/ for deployment scripts, and a foundry.toml configuration file.

The core of our system will be a single, upgradeable smart contract. We'll use the Transparent Proxy Pattern via OpenZeppelin's libraries to separate logic from storage, allowing for future upgrades without losing voter data. First, install the necessary OpenZeppelin contracts as a dependency: forge install OpenZeppelin/openzeppelin-contracts. This adds the library to your lib/ folder. In your foundry.toml, you can configure remappings for easier imports, for example: remappings = ["@openzeppelin/=lib/openzeppelin-contracts/"]. This lets you import contracts with import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";.

Now, create the main contract file: touch src/QuadraticVoting.sol. We'll start by defining the contract's storage layout and basic state variables. A crucial design choice is to use a struct to encapsulate proposal data. This struct will typically contain fields like id, description, budgetAllocated, and a mapping to track each voter's credit allocation. We also need a state variable to store the total community budget and a mapping from voter addresses to their remaining voting credits. Structuring storage carefully in the initial implementation is critical, as it cannot be changed in future upgrades when using the Transparent Proxy Pattern.

The contract's constructor should initialize the upgradeable proxy's admin and the logic contract's initial state. However, because we're using a proxy, the logic contract's constructor code is not executed on deployment of the proxy itself. Instead, we use an initializer function marked with the initializer modifier from OpenZeppelin. This function, which could be named initialize, will set the initial admin and the total community budget. It's vital that this function can only be called once to prevent re-initialization attacks. We'll also define basic view functions at this stage to return proposal details and a voter's credit balance, establishing the contract's initial interface.

Finally, set up a basic test to verify the project compiles and the initial state can be set. Create a test file: forge test --match-test testContractDeployment -vv. Write a test in test/QuadraticVoting.t.sol that deploys the logic contract, a proxy, and calls the initialize function through the proxy. This validates your setup, dependencies, and the core upgrade pattern before moving on to implementing the quadratic voting logic in the next step. Ensure your foundry.toml is configured for the correct EVM version (e.g., shanghai) and optimizer runs suitable for mainnet deployment.

A token-gated voter registry is a smart contract that manages a whitelist of eligible voters based on their token holdings. Its primary functions are to register voters, verify eligibility, and track participation. For a public budget prioritization system, you might gate access using a governance token (like $GOV) or a specific NFT representing community membership. The contract must check that a user's balance meets a minimum threshold (e.g., > 0 tokens) at the time of registration to prevent sybil attacks and ensure voters have skin in the game.

Below is a foundational example using Solidity and the OpenZeppelin library for secure token interface interaction. This contract, VoterRegistry, uses an IERC20 interface to check the caller's balance of a predefined governance token.

solidityCopy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract VoterRegistry {
    IERC20 public governanceToken;
    uint256 public minTokenRequirement;
    mapping(address => bool) public isRegisteredVoter;

    event VoterRegistered(address indexed voter);

    constructor(address _tokenAddress, uint256 _minTokens) {
        governanceToken = IERC20(_tokenAddress);
        minTokenRequirement = _minTokens;
    }

    function register() external {
        require(!isRegisteredVoter[msg.sender], "Already registered");
        require(
            governanceToken.balanceOf(msg.sender) >= minTokenRequirement,
            "Insufficient token balance"
        );

        isRegisteredVoter[msg.sender] = true;
        emit VoterRegistered(msg.sender);
    }
}

The register function is permissionless, but it enforces two key checks: the caller must not already be registered, and their balance of the specified governanceToken must meet the minTokenRequirement.

For a production system, this basic implementation requires several critical enhancements. Snapshotting is essential: you must record a voter's token balance at a specific block number (e.g., when a proposal is created) to prevent manipulation by buying or selling tokens after registration. Integrate a voting power mechanism where power is proportional to the token balance at the snapshot. Consider adding an admin function to update the token address or minimum requirement, protected by a multisig or governance vote. Always conduct thorough audits on the token contract itself to ensure it's not a malicious implementation that could bypass balance checks.

The registry must be integrated with your voting contract. The voting logic should include a modifier like onlyRegisteredVoter that queries the registry's public mapping. This separation of concerns keeps the voting contract logic clean and allows the voter registry to be upgraded or reused for other governance processes. For transparency, all registration events should be indexed by subgraph or queryable via an explorer, allowing the community to verify the voter roll.

Key security considerations include: - Preventing replay registration: The mapping check blocks this. - Handling token transfers: Use snapshotting to lock voting power at a past block. - Choosing the right token: The gating token should be widely distributed and aligned with the community's goals to avoid plutocracy. - Gas optimization: For systems expecting thousands of voters, consider using a Merkle tree-based allowlist to reduce gas costs for users, though this adds off-chain complexity.

After deploying this registry, the next step is to build the voting contract that consumes it. The registry acts as the source of truth for eligibility, enabling you to create secure, transparent, and token-weighted votes for budget proposals. Test extensively on a testnet with realistic token distributions before mainnet deployment.

The core of the public budget prioritization system is the proposal submission contract. This smart contract acts as a permissionless registry where any community member can create a proposal by depositing a proposal bond. This bond, typically a small amount of the native token (e.g., 1 ETH), serves two purposes: it prevents spam by creating a cost to submit, and it signals the proposer's conviction. The contract stores the proposal's metadata, which includes a title, description, funding amount request, recipient address, and a link to a full specification (often an IPFS hash).

When a user calls the submitProposal function, they must attach the bond and provide the proposal data. The contract emits an event with the new proposal's ID and details, making it easy for indexers and frontends to track submissions. A common pattern is to implement a timelock or review period where proposals are visible but not yet votable, allowing the community to discuss them on forums like the Commonwealth forum before they enter a formal voting round. This contract does not handle voting logic itself; it merely registers proposals for a subsequent voting contract to consume.

Here is a simplified example of a proposal submission function in Solidity, using OpenZeppelin's libraries for security:

solidityCopy
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";

contract ProposalSubmitter is Ownable, ReentrancyGuard {
    uint256 public proposalBond = 1 ether;
    uint256 public nextProposalId;

    struct Proposal {
        address proposer;
        uint256 bond;
        string title;
        string descriptionHash; // IPFS hash
        uint256 amountRequested;
        address recipient;
        bool approvedForVoting;
    }

    mapping(uint256 => Proposal) public proposals;

    event ProposalSubmitted(uint256 indexed proposalId, address indexed proposer, string title);

    function submitProposal(
        string memory _title,
        string memory _descriptionHash,
        uint256 _amountRequested,
        address _recipient
    ) external payable nonReentrant {
        require(msg.value == proposalBond, "Incorrect bond amount");

        proposals[nextProposalId] = Proposal({
            proposer: msg.sender,
            bond: msg.value,
            title: _title,
            descriptionHash: _descriptionHash,
            amountRequested: _amountRequested,
            recipient: _recipient,
            approvedForVoting: false
        });

        emit ProposalSubmitted(nextProposalId, msg.sender, _title);
        nextProposalId++;
    }

    // Additional functions for an admin or multisig to approve proposals for voting...
}

After deployment, the contract owner (often a DAO multisig) can adjust the proposalBond or set a whitelist of eligible tokens for the bond. The key security considerations are: preventing reentrancy attacks on the bond deposit, ensuring proposal metadata is stored efficiently off-chain to save gas, and implementing a clear process for slashing or returning bonds. The bond is typically returned if the proposal passes a vote or after a certain period if it fails, disincentivizing malicious proposals without punishing genuine participation.

Integrating this contract with a frontend is straightforward. A dApp would connect via a library like ethers.js or web3.js, allowing users to fill out a form, upload details to IPFS via a service like Pinata, and then call the submitProposal function with the returned hash. The frontend should clearly display the bond requirement and warn users that funds will be locked. Successful projects like MolochDAO and Compound Governance use similar bonding mechanisms to ensure proposal quality before costly on-chain voting executes.

We begin by defining the core data structures and state variables. The contract needs to track a proposal with a description and total votes, and a mapping of votes per voter. A critical variable is the votingPeriod, which defines the active window for casting votes. We'll use OpenZeppelin's Ownable contract for administrative functions like finalizing results. The constructor initializes the proposal and sets the contract owner.

solidityCopy
import "@openzeppelin/contracts/access/Ownable.sol";

contract QuadraticVoting is Ownable {
    struct Proposal {
        string description;
        uint256 totalVotes;
        bool isFinalized;
    }

    Proposal public proposal;
    mapping(address => uint256) public votes;
    uint256 public votingEndTime;
    uint256 public constant VOTING_DURATION = 7 days;
}

The heart of the contract is the vote function. Instead of a 1:1 relationship, quadratic voting calculates the cost of votePower as its square. If a user wants to cast 4 units of voting power, they must commit 16 tokens (4²). The function calculates the new total vote power a user is requesting, determines the quadratic cost (newTotal² - previousTotal²), and transfers that amount from the voter. This ensures marginal cost increases with each additional vote, a core Sybil-resistance mechanism. The function must enforce the voting period and update both the user's vote count and the proposal's total.

To finalize the voting and allocate the budget, the owner calls finalize. This function checks that the voting period has ended and sets the isFinalized flag. The collected funds can then be distributed according to the winning outcome via a separate function. It's crucial to include a withdraw function that allows voters to reclaim any unspent tokens they deposited, minus the quadratic cost of their actual votes. This design ensures the contract only holds funds proportional to the square of the votes cast, not the total deposited amount.

Key security considerations include:

• Reentrancy guards: Use OpenZeppelin's ReentrancyGuard for the vote and withdraw functions.
• Integer math: Perform quadratic calculations using uint256 and be mindful of overflow; Solidity 0.8.x has built-in checks.
• Front-running: The vote cost is deterministic based on the user's existing votes, minimizing front-running risk for cost, though the final vote tally can still be influenced.
• Access control: Clearly restrict finalize to the owner and consider implementing a timelock for production use.

For testing and deployment, use a framework like Hardhat or Foundry. Write tests that verify the quadratic cost calculation: asserting that casting 1, 2, 3, and 4 votes costs 1, 4, 9, and 16 tokens respectively. Simulate voting by multiple accounts to ensure no single voter can disproportionately sway the results. After deployment on a testnet like Sepolia, you can interact with the contract using a front-end library like ethers.js to build a simple interface for voters to commit their tokens and see the live tally.

Once the voting period concludes, the smart contract must tally the votes to determine which proposals have secured funding. This involves reading the final votes mapping for each proposal and applying the chosen voting mechanism. For a simple quadratic voting system, the contract calculates the square root of the total voice credits spent on each proposal. The contract logic should prevent any further votes from being cast after the deadline and ensure the tally is performed in a single, gas-efficient transaction to finalize the results.

After tallying, the contract moves to the execution phase. Proposals that meet or exceed a predefined quorum and are ranked within the available budget are marked as approved. The contract then initiates payouts, typically by transferring the allocated funds from the treasury to the recipient address specified in each winning proposal. This is often done via a transfer or call to the recipient's address. It's critical that this function includes access controls, such as onlyOwner or a timelock, to prevent premature execution and to allow for a review period if the results are contested.

For transparency, the contract should emit events such as VoteTallied and PayoutExecuted that log the results and each transaction. These events allow off-chain indexers and frontends to update their state. A complete execution function might look like this skeleton:

solidityCopy
function executePayouts(uint256[] memory winningProposalIds) external onlyOwner afterVotingEnded {
    for (uint i = 0; i < winningProposalIds.length; i++) {
        Proposal storage prop = proposals[winningProposalIds[i]];
        require(prop.isApproved, "Proposal not approved");
        (bool success, ) = prop.recipient.call{value: prop.amount}("");
        require(success, "Payout failed");
        emit PayoutExecuted(winningProposalIds[i], prop.recipient, prop.amount);
    }
}

Consider implementing the execution in batches if there are many winners to avoid hitting the block gas limit. You can also add a safety feature like a timelock between tallying and execution. This gives the community a final window to audit the results before funds are irreversibly sent. For more complex treasuries holding ERC-20 tokens, the function would need to call the transfer function of the token contract. Always verify the treasury's balance and the proposal's status before transferring to prevent failed transactions or double-spending.

Finally, the entire governance cycle is complete. The on-chain record of proposals, votes, and payouts provides a permanent, auditable ledger of community decisions. This transparent process, from submission to payout, is a foundational primitive for decentralized autonomous organizations (DAOs) and community-owned protocols. For further reading on secure pattern implementations, consult the OpenZeppelin Governor contract documentation or the Aragon OSx framework.

With your on-chain voting contract deployed, the next step is to integrate it with a frontend interface. Use a framework like React or Next.js with a Web3 library such as wagmi or ethers.js to connect user wallets, fetch proposal data, and submit votes. Your interface should clearly display the proposal title, description, allocated budget, and real-time vote tallies. Implement features to filter proposals by status (e.g., active, passed, executed) and calculate voting power, which may be based on token balance or a delegated snapshot.

Before launching, conduct thorough testing. Write and run unit tests for all contract functions using Hardhat or Foundry, simulating various scenarios: a user voting twice, executing a passed proposal, and handling failed transactions. Perform integration tests on a testnet (like Sepolia or Goerli) to verify the frontend-contract interaction works correctly under real network conditions. Use a block explorer to confirm all transactions and event logs are emitted as expected.

Security is paramount for systems controlling treasury funds. Key considerations include: - Proposal lifecycle: Enforce strict timelocks between a vote passing and fund execution to allow for review. - Access control: Use OpenZeppelin's Ownable or role-based access control (AccessControl) to restrict critical functions like createProposal or executeProposal to authorized addresses. - Vote manipulation: Guard against flash loan attacks by using a snapshot of token balances taken at the proposal creation block, not the voting time.

For ongoing maintenance, establish clear processes. This includes a method for upgrading contract logic via a transparent proxy pattern (like the TransparentUpgradeableProxy), a plan for handling emergency pauses if a vulnerability is discovered, and a public documentation site detailing the governance process. Monitor contract activity with tools like Tenderly or OpenZeppelin Defender for real-time alerts on suspicious transactions or failed executions.

Finally, consider advanced mechanisms to improve governance quality. Implement quadratic voting to reduce whale dominance by making vote cost increase quadratically with voting power, or a conviction voting model where voting power grows the longer a voter supports a proposal. These can be complex to implement but lead to more democratic outcomes. Always audit any major changes to the system by a reputable third-party firm before deployment.