tessl/npm-openzeppelin--contracts
Secure Smart Contract library for Solidity with battle-tested implementations of token standards, access control, governance, and essential utilities for building decentralized applications.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
governance.mddocs/
Governance
Complete on-chain governance framework providing proposal management, voting systems, timelock controls, and delegation mechanisms for decentralized autonomous organizations (DAOs).
Capabilities
Core Governor Framework
Flexible governance system supporting proposals, voting, and execution with extensible architecture.
/**
* @dev Core governor interface defining standard governance functionality
*/
interface IGovernor is IERC165, IERC6372 {
/**
* @dev Create a new proposal
*/
function propose(
address[] memory targets,
uint256[] memory values,
bytes[] memory calldatas,
string memory description
) external returns (uint256 proposalId);
/**
* @dev Execute a successful proposal
*/
function execute(
address[] memory targets,
uint256[] memory values,
bytes[] memory calldatas,
bytes32 descriptionHash
) external payable returns (uint256 proposalId);
/**
* @dev Cast a vote on a proposal
*/
function castVote(uint256 proposalId, uint8 support) external returns (uint256 balance);
/**
* @dev Cast vote with reasoning
*/
function castVoteWithReason(uint256 proposalId, uint8 support, string calldata reason) external returns (uint256 balance);
/**
* @dev Cast vote using signature for gasless voting
*/
function castVoteBySig(uint256 proposalId, uint8 support, address voter, bytes memory signature) external returns (uint256 balance);
/**
* @dev Get current state of a proposal
*/
function state(uint256 proposalId) external view returns (ProposalState);
/**
* @dev Get required quorum at specific timepoint
*/
function quorum(uint256 timepoint) external view returns (uint256);
/**
* @dev Get voting weight of account at timepoint
*/
function getVotes(address account, uint256 timepoint) external view returns (uint256);
}
/**
* @dev Core Governor implementation with proposal lifecycle management
*/
abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC721Receiver, IERC1155Receiver {
/**
* @dev Execute arbitrary calls through governance (self-administration)
*/
function relay(address target, uint256 value, bytes calldata data) external payable virtual onlyGovernance;
/**
* @dev Modifier restricting access to governance itself
*/
modifier onlyGovernance();
}Voting Systems
Multiple voting mechanisms supporting different vote counting strategies and participation models.
/**
* @dev Simple 3-option voting: Against (0), For (1), Abstain (2)
*/
abstract contract GovernorCountingSimple is Governor {
/**
* @dev Get vote counts for a proposal
*/
function proposalVotes(uint256 proposalId) public view virtual returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes);
/**
* @dev Check if account has voted on proposal
*/
function hasVoted(uint256 proposalId, address account) public view virtual returns (bool);
}
/**
* @dev Fractional voting allowing split votes across options
*/
abstract contract GovernorCountingFractional is Governor {
/**
* @dev Get amount of votes already used by account on proposal
*/
function usedVotes(uint256 proposalId, address account) public view virtual returns (uint256);
/**
* @dev Cast fractional votes across multiple options
* @param params Encoded as abi.encodePacked(uint128(against), uint128(for), uint128(abstain))
*/
function castVoteWithReasonAndParams(uint256 proposalId, uint8 support, string calldata reason, bytes memory params) public virtual returns (uint256);
}Timelock Integration
Secure timelock mechanisms for delayed execution and multi-signature governance controls.
/**
* @dev Timelock controller for delayed execution of governance decisions
*/
contract TimelockController is AccessControl, IERC721Receiver, IERC1155Receiver {
/**
* @dev Schedule single operation for future execution
*/
function schedule(
address target,
uint256 value,
bytes calldata data,
bytes32 predecessor,
bytes32 salt,
uint256 delay
) public virtual onlyRole(PROPOSER_ROLE);
/**
* @dev Schedule batch of operations for future execution
*/
function scheduleBatch(
address[] calldata targets,
uint256[] calldata values,
bytes[] calldata payloads,
bytes32 predecessor,
bytes32 salt,
uint256 delay
) public virtual onlyRole(PROPOSER_ROLE);
/**
* @dev Execute ready operation
*/
function execute(
address target,
uint256 value,
bytes calldata payload,
bytes32 predecessor,
bytes32 salt
) public payable virtual onlyRoleOrOpenRole(EXECUTOR_ROLE);
/**
* @dev Cancel pending operation
*/
function cancel(bytes32 id) public virtual onlyRole(CANCELLER_ROLE);
/**
* @dev Update minimum delay for operations
*/
function updateDelay(uint256 newDelay) external virtual;
/**
* @dev Get operation state
*/
function getOperationState(bytes32 id) public view virtual returns (OperationState);
/**
* @dev Check if operation is ready for execution
*/
function isOperationReady(bytes32 id) public view virtual returns (bool);
}
/**
* @dev Governor extension integrating with TimelockController
*/
abstract contract GovernorTimelockControl is Governor {
/**
* @dev Get associated timelock address
*/
function timelock() public view virtual returns (address);
/**
* @dev Update timelock address (governance only)
*/
function updateTimelock(address newTimelock) external virtual onlyGovernance;
/**
* @dev Queue proposal for execution through timelock
*/
function queue(
address[] memory targets,
uint256[] memory values,
bytes[] memory calldatas,
bytes32 descriptionHash
) public virtual returns (uint256);
}Vote Delegation and Weight Management
Systems for delegating voting power and tracking voting weights over time with checkpoint-based history.
/**
* @dev Voting power delegation and historical tracking
*/
abstract contract Votes is Context, EIP712, Nonces, IERC5805 {
/**
* @dev Delegate voting power to another account
*/
function delegate(address delegatee) public virtual;
/**
* @dev Delegate voting power using signature (gasless)
*/
function delegateBySig(
address delegatee,
uint256 nonce,
uint256 expiry,
uint8 v,
bytes32 r,
bytes32 s
) public virtual;
/**
* @dev Get current voting power of account
*/
function getVotes(address account) public view virtual returns (uint256);
/**
* @dev Get historical voting power at specific timepoint
*/
function getPastVotes(address account, uint256 timepoint) public view virtual returns (uint256);
/**
* @dev Get total supply at specific timepoint
*/
function getPastTotalSupply(uint256 timepoint) public view virtual returns (uint256);
/**
* @dev Get current delegate of account
*/
function delegates(address account) public view virtual returns (address);
}
/**
* @dev Governor extension using external vote source (ERC20Votes/ERC721Votes)
*/
abstract contract GovernorVotes is Governor {
/**
* @dev Get voting power from token contract
*/
function getVotes(address account, uint256 timepoint) public view virtual override returns (uint256);
/**
* @dev Get associated voting token
*/
function token() public view virtual returns (IERC5805);
}Quorum Management
Flexible quorum systems with fractional requirements and historical tracking.
/**
* @dev Fractional quorum based on total supply percentage
*/
abstract contract GovernorVotesQuorumFraction is GovernorVotes {
/**
* @dev Get current quorum numerator
*/
function quorumNumerator() public view virtual returns (uint256);
/**
* @dev Get quorum denominator (default: 100 for percentage)
*/
function quorumDenominator() public view virtual returns (uint256);
/**
* @dev Update quorum numerator (governance only)
*/
function updateQuorumNumerator(uint256 newNumerator) external virtual onlyGovernance;
/**
* @dev Calculate quorum at specific timepoint
*/
function quorum(uint256 timepoint) public view virtual override returns (uint256);
/**
* @dev Get historical quorum numerator
*/
function quorumNumerator(uint256 timepoint) public view virtual returns (uint256);
}Advanced Governance Features
Extensions for enhanced governance functionality including late quorum protection and proposal guardians.
/**
* @dev Configurable governance settings
*/
abstract contract GovernorSettings is Governor {
/**
* @dev Set voting delay between proposal and voting start
*/
function setVotingDelay(uint256 newVotingDelay) public virtual onlyGovernance;
/**
* @dev Set voting period duration
*/
function setVotingPeriod(uint256 newVotingPeriod) public virtual onlyGovernance;
/**
* @dev Set minimum tokens needed to create proposal
*/
function setProposalThreshold(uint256 newProposalThreshold) public virtual onlyGovernance;
}
/**
* @dev Protection against late quorum manipulation
*/
abstract contract GovernorPreventLateQuorum is Governor {
/**
* @dev Get vote extension period when quorum reached late
*/
function lateQuorumVoteExtension() public view virtual returns (uint256);
/**
* @dev Set late quorum vote extension period
*/
function setLateQuorumVoteExtension(uint256 newExtension) public virtual onlyGovernance;
/**
* @dev Get proposal deadline with potential extension
*/
function proposalDeadline(uint256 proposalId) public view virtual override returns (uint256);
}
/**
* @dev Proposal guardian with cancellation authority
*/
abstract contract GovernorProposalGuardian is Governor {
/**
* @dev Get current proposal guardian
*/
function proposalGuardian() public view virtual returns (address);
/**
* @dev Set proposal guardian (governance only)
*/
function setProposalGuardian(address newGuardian) public virtual onlyGovernance;
/**
* @dev Cancel proposal (guardian or proposer only)
*/
function cancel(
address[] memory targets,
uint256[] memory values,
bytes[] memory calldatas,
bytes32 descriptionHash
) public virtual returns (uint256);
}
/**
* @dev Proposal storage for L2 optimization and enumeration
*/
abstract contract GovernorStorage is Governor {
/**
* @dev Queue proposal using stored details
*/
function queue(uint256 proposalId) public virtual;
/**
* @dev Execute proposal using stored details
*/
function execute(uint256 proposalId) public payable virtual;
/**
* @dev Get stored proposal details
*/
function proposalDetails(uint256 proposalId) public view virtual returns (ProposalDetails memory);
/**
* @dev Get total number of proposals created
*/
function proposalCount() public view virtual returns (uint256);
}Types
/**
* @dev Possible states of a governance proposal
*/
enum ProposalState {
Pending, // Proposal created, voting not started
Active, // Voting is active
Canceled, // Proposal was canceled
Defeated, // Proposal was defeated (not enough votes)
Succeeded, // Proposal succeeded (enough votes)
Queued, // Proposal queued in timelock
Expired, // Proposal expired before execution
Executed // Proposal was executed
}
/**
* @dev Timelock operation states
*/
enum OperationState {
Unset, // Operation not scheduled
Waiting, // Scheduled, waiting for delay
Ready, // Ready for execution
Done // Already executed
}
/**
* @dev Support options for voting
*/
enum VoteType {
Against, // Vote against proposal (0)
For, // Vote for proposal (1)
Abstain // Abstain from voting (2)
}
/**
* @dev Stored proposal details structure
*/
struct ProposalDetails {
address[] targets;
uint256[] values;
bytes[] calldatas;
bytes32 descriptionHash;
}
/**
* @dev Standard voting interface (ERC-5805)
*/
interface IERC5805 is IERC6372, IVotes {}
/**
* @dev Clock interface for timepoint queries (ERC-6372)
*/
interface IERC6372 {
function clock() external view returns (uint48);
function CLOCK_MODE() external view returns (string memory);
}
/**
* @dev Voting interface
*/
interface IVotes {
function getVotes(address account) external view returns (uint256);
function getPastVotes(address account, uint256 timepoint) external view returns (uint256);
function getPastTotalSupply(uint256 timepoint) external view returns (uint256);
function delegates(address account) external view returns (address);
function delegate(address delegatee) external;
function delegateBySig(address delegatee, uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s) external;
}
/**
* @dev Timelock controller roles
*/
bytes32 constant PROPOSER_ROLE = keccak256("PROPOSER_ROLE"); // Can schedule operations
bytes32 constant EXECUTOR_ROLE = keccak256("EXECUTOR_ROLE"); // Can execute operations
bytes32 constant CANCELLER_ROLE = keccak256("CANCELLER_ROLE"); // Can cancel operationsUsage Example:
import "@openzeppelin/contracts/governance/Governor.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorSettings.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorCountingSimple.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorVotesQuorumFraction.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorTimelockControl.sol";
contract MyDAO is
Governor,
GovernorSettings,
GovernorCountingSimple,
GovernorVotes,
GovernorVotesQuorumFraction,
GovernorTimelockControl
{
constructor(
IVotes _token,
TimelockController _timelock,
uint256 _quorumPercentage
)
Governor("MyDAO")
GovernorSettings(7200, 50400, 1000e18) // 1 day delay, 1 week voting, 1000 token threshold
GovernorVotes(_token)
GovernorVotesQuorumFraction(_quorumPercentage)
GovernorTimelockControl(_timelock)
{}
// Required override functions
function votingDelay() public view override(IGovernor, GovernorSettings) returns (uint256) {
return super.votingDelay();
}
function votingPeriod() public view override(IGovernor, GovernorSettings) returns (uint256) {
return super.votingPeriod();
}
function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) {
return super.proposalThreshold();
}
}Install with Tessl CLI
npx tessl i tessl/npm-openzeppelin--contracts