DAO & On-Chain Governance System

This project is a complete university-style DAO governance system for Blockchain Technologies 2 Assignment 4. It uses Solidity, Hardhat, OpenZeppelin Governor, TimelockController, an ERC20Votes token, a treasury contract, a controlled Box contract, tests, deployment scripts, and a minimal HTML/CSS/JavaScript frontend.

Project Overview

• Governance token with ERC20Votes and ERC20Permit
• Linear vesting contract for team tokens
• Governor + Timelock governance flow
• Treasury owned by the timelock
• Controlled Box contract for demo proposals
• Minimal frontend for wallet connection, delegation, proposal lookup, and voting
• Documentation for deployment, monitoring, security, and theory

Repository Structure

contracts/
docs/
frontend/
scripts/
test/
hardhat.config.js
package.json
README.md

Contracts

GovernanceToken.sol

• ERC-20 governance token
• Supports vote delegation through ERC20Votes
• Supports gasless approvals through ERC20Permit
• Total supply is minted once during deployment

TokenVesting.sol

• Holds the 40% team allocation
• Releases tokens linearly over 12 months
• Calculates releasable tokens based on time passed

MyGovernor.sol

• OpenZeppelin Governor implementation
• Voting delay: 7200 blocks
• Voting period: 50400 blocks
• Proposal threshold: 1% of total supply
• Quorum: 4% of total supply

Treasury.sol

• Holds ERC-20 tokens and ETH
• Only the timelock owner can move funds or change treasury settings
• Emits clear events for transfers and parameter changes

Box.sol

• Simple controlled contract
• Owned by the timelock
• Used to demonstrate a governance call like store(42)

Token Distribution

• 40% team allocation -> TokenVesting
• 30% treasury allocation -> Treasury
• 20% community allocation -> community wallet
• 10% liquidity allocation -> liquidity wallet

See token-distribution-diagram.md for the diagram.

Installation

npm install

Environment Variables

Copy .env.example to .env and fill in the real values if you want to deploy to Sepolia.

Required for testnet deployment:

• RPC_URL
• PRIVATE_KEY
• ETHERSCAN_API_KEY
• TEAM_BENEFICIARY
• COMMUNITY_AIRDROP_RECEIVER
• LIQUIDITY_RECEIVER

Compile

npx hardhat compile

Or with npm:

npm run compile

Test

npx hardhat test

Or with npm:

npm test

Deploy Locally

Start a local Hardhat node:

npx hardhat node

In another terminal, deploy:

npm run deploy:local

Check timelock roles and ownership:

npm run roles:local

Deploy to Testnet

After filling .env:

npm run deploy:testnet

Run the Frontend

Serve the frontend:

npm run frontend

Then open:

http://127.0.0.1:8080

Important:

• The frontend reads frontend/contracts.json
• That file is updated automatically by scripts/deploy.js
• MetaMask must be connected to the same chain where you deployed the contracts

Package Scripts

• npm run compile
• npm test
• npm run deploy:local
• npm run deploy:testnet
• npm run roles:local
• npm run frontend

Tests Included

• token deployment
• total supply
• token distribution
• delegation
• vote snapshots
• permit signatures
• vesting before release
• partial vesting after time passes
• full vesting after 12 months
• propose -> vote -> queue -> execute
• treasury transfer proposal
• parameter change proposal
• delegatee voting on behalf of delegator
• quorum failure
• defeated proposal
• full Box.store(42) end-to-end flow

Documentation

• security-audit-report.md
• deployment-checklist.md
• monitoring-plan.md
• governance-research.md
• demo-script.md
• proposal-lifecycle-log.md

Screenshot Checklist for Submission

1. Successful compile
2. Passing tests
3. Deployed contract addresses
4. Token delegation transaction
5. Proposal creation
6. Voting transaction
7. Queue transaction
8. Execute transaction
9. Box.retrieve() returns 42
10. Treasury transfer proposal
11. Frontend wallet connected
12. Frontend voting power
13. Frontend delegation
14. Frontend vote transaction proof
15. Slither output

Suggested Submission Flow

1. Compile the contracts
2. Run the tests
3. Start a local node
4. Deploy the contracts locally
5. Open the frontend
6. Delegate votes
7. Create and execute proposals
8. Capture screenshots as you go

Notes for Manual Editing

• Update .env before Sepolia deployment
• Replace placeholder wallet addresses in .env
• Install Slither separately if you want the static analysis output
• Etherscan verification requires a real ETHERSCAN_API_KEY
• The frontend contract addresses must match the network currently selected in MetaMask