GovernorLib

Title: GovernorLib

Authors: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80), Modified from OpenZeppelin (https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/governance/Governor.sol)

Library implementing the full on-chain governance lifecycle: proposal creation, voting (For/Against/Abstain with quorum), optional timelock queuing, execution, and cancellation. Includes EIP-712 castVoteBySig support.

Three-layer pattern: this library holds all logic and state. The stateless Governor facet delegates every external call here.

Constants

QUORUM_DENOMINATOR

Quorum denominator: quorum = (totalSupply * quorumNumerator) / QUORUM_DENOMINATOR.

uint256 internal constant QUORUM_DENOMINATOR = 100;

GRACE_PERIOD

How long a queued proposal stays executable after its ETA. Past eta + GRACE_PERIOD the proposal is Expired, which is terminal: state reports it, execute refuses it, and checkTimelockOperation makes a colocated timelock refuse to run its operation directly.

uint256 internal constant GRACE_PERIOD = 14 days;

Functions

governorStorage

Returns a storage reference to the GovernorStorage struct.

function governorStorage() internal pure returns (GovernorStorage storage $);

Returns

Name	Type	Description
$	`GovernorStorage`

registerInterface

Registers support for the IGovernor interface via ERC-165.

function registerInterface() internal;

__Governor_init

Initializes the Governor module.

Must be called between preInitializer and postInitializer.

function __Governor_init(
        string memory name_,
        address token_,
        address timelock_,
        uint48 votingDelay_,
        uint32 votingPeriod_,
        uint256 proposalThreshold_,
        uint256 quorumNumerator_
    ) internal;

Parameters

Name	Type	Description
name_	`string`	The human-readable name of the governor.
token_	`address`	The IVotes-compatible token used for voting power.
timelock_	`address`	Optional TimelockController address (address(0) for direct execution).
votingDelay_	`uint48`	Delay in clock units before voting starts (can be 0).
votingPeriod_	`uint32`	Duration in clock units of the voting window (must be > 0).
proposalThreshold_	`uint256`	Minimum voting power required to create a proposal.
quorumNumerator_	`uint256`	Quorum as a percentage of total supply (0–100).

name

Returns the human-readable name of this governor.

function name() internal view returns (string memory);

Returns

Name	Type	Description
<none>	`string`

version

Returns the version string ("1").

function version() internal pure returns (string memory);

Returns

Name	Type	Description
<none>	`string`

token

Returns the IVotes token address.

function token() internal view returns (address);

Returns

Name	Type	Description
<none>	`address`

timelock

Returns the configured TimelockController address (address(0) if none).

function timelock() internal view returns (address);

Returns

Name	Type	Description
<none>	`address`

clock

Returns the current clock value, delegating to the token's EIP-6372 clock. Falls back to block.timestamp if the token does not implement IERC6372.

function clock() internal view returns (uint48);

Returns

Name	Type	Description
<none>	`uint48`

CLOCK_MODE

Returns the machine-readable clock mode string, delegating to the token's CLOCK_MODE. Falls back to "mode=timestamp" if the token does not implement IERC6372.

function CLOCK_MODE() internal view returns (string memory);

Returns

Name	Type	Description
<none>	`string`

COUNTING_MODE

Returns the counting mode string (Bravo: For/Against/Abstain).

function COUNTING_MODE() internal pure returns (string memory);

Returns

Name	Type	Description
<none>	`string`

votingDelay

Returns the voting delay in clock units.

function votingDelay() internal view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

votingPeriod

Returns the voting period duration in clock units.

function votingPeriod() internal view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

proposalThreshold

Returns the proposal threshold (minimum voting power to propose).

function proposalThreshold() internal view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

quorumNumerator

Returns the current quorum numerator.

function quorumNumerator() internal view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

quorumNumeratorAt

Returns the quorum numerator at a given timepoint.

Simplified: returns the current numerator (no historical tracking).

function quorumNumeratorAt(
        uint256 /* timepoint */
    )
        internal
        view
        returns (uint256);

Parameters

Name	Type	Description
_	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

quorumDenominator

Returns the quorum denominator (100).

function quorumDenominator() internal pure returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

quorum

Returns the quorum (in token units) required at a given past timepoint.

function quorum(uint256 timepoint) internal view returns (uint256);

Parameters

Name	Type	Description
timepoint	`uint256`	The past clock value to query.

Returns

Name	Type	Description
<none>	`uint256`

getVotes

Returns the voting power of an account at a past timepoint.

function getVotes(address account, uint256 timepoint) internal view returns (uint256);

Parameters

Name	Type	Description
account	`address`
timepoint	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

hashProposal

Computes the proposal ID from targets, values, calldatas, and description hash.

function hashProposal(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        bytes32 descriptionHash
    ) internal pure returns (uint256);

Parameters

Name	Type	Description
targets	`address[]`
values	`uint256[]`
calldatas	`bytes[]`
descriptionHash	`bytes32`

Returns

Name	Type	Description
<none>	`uint256`

proposalSnapshot

Returns the clock value at which voting starts for a proposal.

function proposalSnapshot(uint256 proposalId) internal view returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

proposalDeadline

Returns the clock value at which voting ends for a proposal.

function proposalDeadline(uint256 proposalId) internal view returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

proposalProposer

Returns the address that created a proposal.

function proposalProposer(uint256 proposalId) internal view returns (address);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`address`

proposalEta

Returns the timelock ETA for a proposal (0 if not queued).

function proposalEta(uint256 proposalId) internal view returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

proposalVotes

Returns the vote totals for a proposal.

function proposalVotes(uint256 proposalId)
        internal
        view
        returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
againstVotes	`uint256`
forVotes	`uint256`
abstainVotes	`uint256`

hasVoted

Returns whether an account has voted on a proposal.

function hasVoted(uint256 proposalId, address account) internal view returns (bool);

Parameters

Name	Type	Description
proposalId	`uint256`
account	`address`

Returns

Name	Type	Description
<none>	`bool`

state

Returns the current state of a proposal.

State transitions (ordered by finality): Executed → Canceled → Pending → Active → Defeated → Succeeded → Queued → Expired Expired (queued, still pending in the timelock, and past eta + GRACE_PERIOD) is terminal: execute refuses it, and a timelock in the same diamond refuses its operation (see checkTimelockOperation).

function state(uint256 proposalId) internal view returns (IGovernor.ProposalState);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`IGovernor.ProposalState`

propose

Creates a new proposal.

function propose(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        string memory description
    ) internal returns (uint256);

Parameters

Name	Type	Description
targets	`address[]`	Contract addresses to call.
values	`uint256[]`	ETH values for each call.
calldatas	`bytes[]`	Encoded calldata for each call.
description	`string`	Human-readable description of the proposal.

Returns

Name	Type	Description
<none>	`uint256`	proposalId The unique ID of the new proposal.

_storeAndEmitProposal

Stores proposal core data and emits ProposalCreated. Extracted to avoid stack-too-deep.

function _storeAndEmitProposal(
        uint256 proposalId,
        address proposer,
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        string memory description
    ) private;

Parameters

Name	Type	Description
proposalId	`uint256`
proposer	`address`
targets	`address[]`
values	`uint256[]`
calldatas	`bytes[]`
description	`string`

queue

Queue a succeeded proposal in the TimelockController.

function queue(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash)
        internal
        returns (uint256);

Parameters

Name	Type	Description
targets	`address[]`	Contract addresses to call.
values	`uint256[]`	ETH values for each call.
calldatas	`bytes[]`	Encoded calldata for each call.
descriptionHash	`bytes32`	keccak256 hash of the description string.

Returns

Name	Type	Description
<none>	`uint256`	proposalId The proposal ID.

execute

Execute a proposal (succeeded with no timelock, or queued+ready with timelock and within the grace period).

function execute(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        bytes32 descriptionHash
    ) internal returns (uint256);

Parameters

Name	Type	Description
targets	`address[]`	Contract addresses to call.
values	`uint256[]`	ETH values for each call.
calldatas	`bytes[]`	Encoded calldata for each call.
descriptionHash	`bytes32`	keccak256 hash of the description string.

Returns

Name	Type	Description
<none>	`uint256`	proposalId The proposal ID.

cancel

Cancel a proposal. Only its proposer can cancel, and only while it is Pending (before voting starts), as in OpenZeppelin's Governor. Once voting has started, no single account can veto the proposal through the Governor; a queued operation can still be cancelled in the timelock by a CANCELLER_ROLE holder, after which state reports Canceled.

function cancel(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        bytes32 descriptionHash
    ) internal returns (uint256);

Parameters

Name	Type	Description
targets	`address[]`	Contract addresses for the proposal.
values	`uint256[]`	ETH values for the proposal.
calldatas	`bytes[]`	Calldata for the proposal.
descriptionHash	`bytes32`	keccak256 hash of the description string.

Returns

Name	Type	Description
<none>	`uint256`	proposalId The proposal ID.

castVote

Cast a vote on an active proposal.

function castVote(uint256 proposalId, uint8 support) internal returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`	The proposal to vote on.
support	`uint8`	Vote type: 0=Against, 1=For, 2=Abstain.

Returns

Name	Type	Description
<none>	`uint256`	weight The voter's voting power at the proposal snapshot.

castVoteWithReason

Cast a vote with a reason string.

function castVoteWithReason(uint256 proposalId, uint8 support, string calldata reason) internal returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`	The proposal to vote on.
support	`uint8`	Vote type: 0=Against, 1=For, 2=Abstain.
reason	`string`	Human-readable reason for the vote.

Returns

Name	Type	Description
<none>	`uint256`	weight The voter's voting power at the proposal snapshot.

castVoteWithReasonAndParams

Cast a vote with a reason string and extra params.

function castVoteWithReasonAndParams(
        uint256 proposalId,
        uint8 support,
        string calldata reason,
        bytes calldata params
    ) internal returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`	The proposal to vote on.
support	`uint8`	Vote type: 0=Against, 1=For, 2=Abstain.
reason	`string`	Human-readable reason for the vote.
params	`bytes`	Extra encoded parameters (e.g. fractional voting split).

Returns

Name	Type	Description
<none>	`uint256`	weight The voter's voting power at the proposal snapshot.

castVoteBySig

Cast a vote via an EIP-712 signature.

function castVoteBySig(uint256 proposalId, uint8 support, address voter, bytes memory signature)
        internal
        returns (uint256);

Parameters

Name	Type	Description
proposalId	`uint256`	The proposal to vote on.
support	`uint8`	Vote type: 0=Against, 1=For, 2=Abstain.
voter	`address`	The address that signed the vote.
signature	`bytes`	EIP-712 signature over the Ballot struct.

Returns

Name	Type	Description
<none>	`uint256`	weight The voter's voting power at the proposal snapshot.

setVotingDelay

Update the voting delay. Callable only via a passed governance proposal.

function setVotingDelay(uint48 newVotingDelay) internal;

Parameters

Name	Type	Description
newVotingDelay	`uint48`	The new voting delay in clock units.

setVotingPeriod

Update the voting period. Callable only via a passed governance proposal.

function setVotingPeriod(uint32 newVotingPeriod) internal;

Parameters

Name	Type	Description
newVotingPeriod	`uint32`	The new voting period in clock units (must be > 0).

setProposalThreshold

Update the proposal threshold. Callable only via a passed governance proposal.

function setProposalThreshold(uint256 newProposalThreshold) internal;

Parameters

Name	Type	Description
newProposalThreshold	`uint256`	The new minimum voting power to propose.

updateQuorumNumerator

Update the quorum numerator. Callable only via a passed governance proposal.

function updateQuorumNumerator(uint256 newQuorumNumerator) internal;

Parameters

Name	Type	Description
newQuorumNumerator	`uint256`	New quorum percentage (0–100).

updateTimelock

Update the timelock address. Callable only via a passed governance proposal.

function updateTimelock(address newTimelock) internal;

Parameters

Name	Type	Description
newTimelock	`address`	The new TimelockController address (or address(0) to disable).

checkTimelockOperation

Reverts if timelockId is the operation of a proposal this governor queued and the proposal is past its grace period (Expired).

Called by TimelockControllerLib before it runs an operation, so the grace is enforced even when the timelock's executor role is open and the operation is run directly, bypassing execute. It reads this diamond's Governor storage, so it only takes effect when the Governor and TimelockController facets share a diamond (as in GovernedVaultInit). An operation the governor did not queue maps to proposal 0 and passes. A TimelockController deployed apart from its governor cannot see the grace; grant its EXECUTOR_ROLE to the governor alone so every execution goes through execute.

function checkTimelockOperation(bytes32 timelockId) internal view;

Parameters

Name	Type	Description
timelockId	`bytes32`	The timelock operation id about to be executed.

_castVote

Internal implementation for all vote casting paths.

function _castVote(uint256 proposalId, address voter, uint8 support, string memory reason, bytes memory params)
        internal
        returns (uint256 weight);

Parameters

Name	Type	Description
proposalId	`uint256`
voter	`address`
support	`uint8`
reason	`string`
params	`bytes`

Returns

Name	Type	Description
weight	`uint256`

_voteSucceeded

Returns true if forVotes > againstVotes.

function _voteSucceeded(uint256 proposalId) internal view returns (bool);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`bool`

_quorumReached

Returns true if forVotes + abstainVotes >= quorum(snapshot).

function _quorumReached(uint256 proposalId) internal view returns (bool);

Parameters

Name	Type	Description
proposalId	`uint256`

Returns

Name	Type	Description
<none>	`bool`

_onlyGovernance

Reverts unless the caller is the configured executor: the timelock when one is set, otherwise this governor (direct execution). When a timelock relays the call, the exact calldata must have been authorized by a governor execute (see the _governanceCall bookkeeping) — this prevents the timelock from being used to invoke governor admin functions outside a passed proposal.

function _onlyGovernance() internal;

_executor

Returns the address responsible for executing passed proposals: the configured timelock if set, otherwise this governor.

function _executor() internal view returns (address);

Returns

Name	Type	Description
<none>	`address`

_encodeStateBitmap

Encodes a single ProposalState as a 1-bit bitmask for error reporting.

function _encodeStateBitmap(IGovernor.ProposalState proposalState) internal pure returns (bytes32);

Parameters

Name	Type	Description
proposalState	`IGovernor.ProposalState`

Returns

Name	Type	Description
<none>	`bytes32`