Solidity API

B3TRGovernor

This contract is the main governance contract for the VeBetterDAO ecosystem. Anyone can create a proposal to both change the state of the contract, to execute a transaction on the timelock or to ask for a vote from the community without performing any onchain action. In order for the proposal to become active, the community needs to deposit a certain amount of VOT3 tokens. This is used as a heat check for the proposal, and funds are returned to the depositors after vote is concluded. Votes for proposals start periodically, based on the allocation rounds (see xAllocationVoting contract), and the round in which the proposal should be active is specified by the proposer during the proposal creation.

A minimum amount of voting power is required in order to vote on a proposal. The voting power is calculated through the quadratic vote formula based on the amount of VOT3 tokens held by the voter at the block when the proposal becomes active.

Once a proposal succeeds, it can be queued and executed. The execution is done through the timelock contract.

The contract is upgradeable and uses the UUPS pattern.

_The contract is upgradeable and uses the UUPS pattern. All logic is stored in libraries.

—————— VERSION 2 —————— - Replaced onlyGovernance modifier with onlyRoleOrGovernance which checks if the caller has the DEFAULT_ADMIN_ROLE role or if the function is called through a governance proposal —————— VERSION 3 —————— - Added the ability to toggle the quadratic voting mechanism on and off —————— VERSION 4 —————— - Integrated VeBetterPassport contract —————— VERSION 5 —————— - Difference from V4: Updated all libraries to use new version of IVoterRewards that supports GM Upgrades._

GOVERNOR_FUNCTIONS_SETTINGS_ROLE

bytes32 GOVERNOR_FUNCTIONS_SETTINGS_ROLE

The role that can whitelist allowed functions in the propose function

PAUSER_ROLE

bytes32 PAUSER_ROLE

The role that can pause the contract

CONTRACTS_ADDRESS_MANAGER_ROLE

bytes32 CONTRACTS_ADDRESS_MANAGER_ROLE

The role that can set external contracts addresses

PROPOSAL_EXECUTOR_ROLE

bytes32 PROPOSAL_EXECUTOR_ROLE

The role that can execute a proposal

constructor

constructor() public

onlyGovernance

modifier onlyGovernance()

_Restricts a function so it can only be executed through governance proposals. For example, governance parameter setters in {GovernorSettings} are protected using this modifier.

The governance executing address may be different from the Governor’s own address, for example it could be a timelock. This can be customized by modules by overriding {executor}. The executor is only able to invoke these functions during the execution of the governor’s {execute} function, and not under any other circumstances. Thus, for example, additional timelock proposers are not able to change governance parameters without going through the governance protocol (since v4.6).

onlyRoleOrGovernance

modifier onlyRoleOrGovernance(bytes32 role)

Modifier to check if the caller has the specified role or if the function is called through a governance proposal

Parameters

Name Type Description
role bytes32 The role to check against

onlyRoleOrOpenRole

modifier onlyRoleOrOpenRole(bytes32 role)

Modifier to make a function callable only by a certain role. In addition to checking the sender’s role, address(0) ’s role is also considered. Granting a role to address(0) is equivalent to enabling this role for everyone.

initialize

function initialize(struct GovernorTypes.InitializationData data, struct GovernorTypes.InitializationRolesData rolesData) external

Initializes the contract with the initial parameters

This function is called only once during the contract deployment

Parameters

Name Type Description
data struct GovernorTypes.InitializationData Initialization data containing the initial settings for the governor
rolesData struct GovernorTypes.InitializationRolesData

initializeV4

function initializeV4(contract IVeBetterPassport _veBetterPassport) public

receive

receive() external payable virtual

Function to receive VET that will be handled by the governor (disabled if executor is a third party contract)

relay

function relay(address target, uint256 value, bytes data) external payable virtual

Relays a transaction or function call to an arbitrary target. In cases where the governance executor is some contract other than the governor itself, like when using a timelock, this function can be invoked in a governance proposal to recover tokens or Ether that was sent to the governor contract by mistake. Note that if the executor is simply the governor itself, use of relay is redundant.

Parameters

Name Type Description
target address The target address
value uint256 The amount of ether to send
data bytes The data to call the target with

proposalNeedsQueuing

function proposalNeedsQueuing(uint256 proposalId) external view returns (bool)

Function to know if a proposal is executable or not. If the proposal was created without any targets, values, or calldatas, it is not executable. to check if the proposal is executable.

If no calldatas or targets then it’s not executable, otherwise it will check if the governance can execute transactions or not.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] bool bool True if the proposal needs queuing, false otherwise

state

function state(uint256 proposalId) external view returns (enum GovernorTypes.ProposalState)

Returns the state of a proposal

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] enum GovernorTypes.ProposalState GovernorTypes.ProposalState The state of the proposal

canProposalStartInNextRound

function canProposalStartInNextRound() public view returns (bool)

Check if the proposal can start in the next round

Return Values

Name Type Description
[0] bool bool True if the proposal can start in the next round, false otherwise

proposalProposer

function proposalProposer(uint256 proposalId) public view virtual returns (address)

See {IB3TRGovernor-proposalProposer}.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] address address The address of the proposer

proposalEta

function proposalEta(uint256 proposalId) public view virtual returns (uint256)

See {IB3TRGovernor-proposalEta}.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] uint256 uint256 The ETA of the proposal

proposalStartRound

function proposalStartRound(uint256 proposalId) public view returns (uint256)

See {IB3TRGovernor-proposalStartRound}

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] uint256 uint256 The start round of the proposal

proposalSnapshot

function proposalSnapshot(uint256 proposalId) external view returns (uint256)

See {IB3TRGovernor-proposalSnapshot}. We take for granted that the round starts the block after it ends. But it can happen that the round is not started yet for whatever reason. Knowing this, if the proposal starts 4 rounds in the future we need to consider also those extra blocks used to start the rounds.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] uint256 uint256 The snapshot of the proposal

proposalDeadline

function proposalDeadline(uint256 proposalId) external view returns (uint256)

See {IB3TRGovernor-proposalDeadline}.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] uint256 uint256 The deadline of the proposal

depositThreshold

function depositThreshold() external view returns (uint256)

Returns the deposit threshold

Return Values

Name Type Description
[0] uint256 uint256 The deposit threshold

depositThresholdPercentage

function depositThresholdPercentage() external view returns (uint256)

See {Governor-depositThreshold}.

Return Values

Name Type Description
[0] uint256 uint256 The deposit threshold percentage

votingThreshold

function votingThreshold() external view returns (uint256)

See {Governor-votingThreshold}.

Return Values

Name Type Description
[0] uint256 uint256 The voting threshold

getVotes

function getVotes(address account, uint256 timepoint) external view returns (uint256)

See {IB3TRGovernor-getVotes}.

Parameters

Name Type Description
account address The address of the account
timepoint uint256 The timepoint to get the votes at

Return Values

Name Type Description
[0] uint256 uint256 The number of votes

getQuadraticVotingPower

function getQuadraticVotingPower(address account, uint256 timepoint) external view returns (uint256)

Returns the quadratic voting power that account has. See {IB3TRGovernor-getQuadraticVotingPower}.

Parameters

Name Type Description
account address The address of the account
timepoint uint256 The timepoint to get the voting power at

Return Values

Name Type Description
[0] uint256 uint256 The quadratic voting power

clock

function clock() external view returns (uint48)

Clock (as specified in EIP-6372) is set to match the token’s clock. Fallback to block numbers if the token does not implement EIP-6372.

Return Values

Name Type Description
[0] uint48 uint48 The current clock time

CLOCK_MODE

function CLOCK_MODE() external view returns (string)

Machine-readable description of the clock as specified in EIP-6372.

Return Values

Name Type Description
[0] string string The clock mode

token

function token() external view returns (contract IVOT3)

The token that voting power is sourced from.

Return Values

Name Type Description
[0] contract IVOT3 IVOT3 The voting token

quorum

function quorum(uint256 blockNumber) external view returns (uint256)

Returns the quorum for a timepoint, in terms of number of votes: supply * numerator / denominator.

Parameters

Name Type Description
blockNumber uint256 The block number to get the quorum for

Return Values

Name Type Description
[0] uint256 uint256 The quorum

quorumNumerator

function quorumNumerator() external view returns (uint256)

Returns the current quorum numerator. See {quorumDenominator}.

Return Values

Name Type Description
[0] uint256 uint256 The current quorum numerator

quorumNumerator

function quorumNumerator(uint256 timepoint) external view returns (uint256)

Returns the quorum numerator at a specific timepoint using the GovernorQuorumFraction library.

Parameters

Name Type Description
timepoint uint256 The timepoint to get the quorum numerator for

Return Values

Name Type Description
[0] uint256 uint256 The quorum numerator at the given timepoint

quorumDenominator

function quorumDenominator() external pure returns (uint256)

Returns the quorum denominator using the GovernorQuorumFraction library. Defaults to 100, but may be overridden.

Return Values

Name Type Description
[0] uint256 uint256 The quorum denominator

isFunctionWhitelisted

function isFunctionWhitelisted(address target, bytes4 functionSelector) external view returns (bool)

Check if a function is restricted by the governor

Parameters

Name Type Description
target address The address of the contract
functionSelector bytes4 The function selector

Return Values

Name Type Description
[0] bool bool True if the function is whitelisted, false otherwise

minVotingDelay

function minVotingDelay() external view returns (uint256)

See {B3TRGovernor-minVotingDelay}.

Return Values

Name Type Description
[0] uint256 uint256 The minimum voting delay

votingPeriod

function votingPeriod() external view returns (uint256)

See {IB3TRGovernor-votingPeriod}.

Return Values

Name Type Description
[0] uint256 uint256 The voting period

hasVotedOnce

function hasVotedOnce(address user) external view returns (bool)

Check if a user has voted at least one time.

Parameters

Name Type Description
user address The address of the user to check if has voted at least one time

Return Values

Name Type Description
[0] bool bool True if the user has voted once, false otherwise

quorumReached

function quorumReached(uint256 proposalId) external view returns (bool)

Returns if quorum was reached or not

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] bool bool True if quorum was reached, false otherwise

proposalTotalVotes

function proposalTotalVotes(uint256 proposalId) external view returns (uint256)

Returns the total votes for a proposal

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] uint256 uint256 The total votes for the proposal

proposalVotes

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

Accessor to the internal vote counts, in terms of vote power.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
againstVotes uint256 The votes against the proposal
forVotes uint256 The votes for the proposal
abstainVotes uint256 The votes abstaining the proposal

COUNTING_MODE

function COUNTING_MODE() external pure returns (string)

Returns the counting mode

Return Values

Name Type Description
[0] string string The counting mode

hasVoted

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

See {IB3TRGovernor-hasVoted}.

Parameters

Name Type Description
proposalId uint256 The id of the proposal
account address The address of the account

Return Values

Name Type Description
[0] bool bool True if the account has voted, false otherwise

getProposalDeposits

function getProposalDeposits(uint256 proposalId) external view returns (uint256)

Returns the amount of deposits made to a proposal.

Parameters

Name Type Description
proposalId uint256 The id of the proposal.

Return Values

Name Type Description
[0] uint256 uint256 The amount of deposits

proposalDepositReached

function proposalDepositReached(uint256 proposalId) external view returns (bool)

Returns true if the threshold of deposits required to reach a proposal has been reached.

Parameters

Name Type Description
proposalId uint256 The id of the proposal.

Return Values

Name Type Description
[0] bool bool True if the threshold is reached, false otherwise

proposalDepositThreshold

function proposalDepositThreshold(uint256 proposalId) external view returns (uint256)

Returns the deposit threshold for a proposal.

Parameters

Name Type Description
proposalId uint256 The id of the proposal.

Return Values

Name Type Description
[0] uint256 uint256 The deposit threshold for the proposal.

getTimelockId

function getTimelockId(uint256 proposalId) public view returns (bytes32)

Public endpoint to retrieve the timelock id of a proposal.

Parameters

Name Type Description
proposalId uint256 The id of the proposal

Return Values

Name Type Description
[0] bytes32 bytes32 The timelock id

getUserDeposit

function getUserDeposit(uint256 proposalId, address user) external view returns (uint256)

Returns the amount of tokens a specific user has deposited to a proposal.

Parameters

Name Type Description
proposalId uint256 The id of the proposal.
user address The address of the user.

Return Values

Name Type Description
[0] uint256 uint256 The amount of tokens deposited by the user

name

function name() external view returns (string)

See {IB3TRGovernor-name}.

Return Values

Name Type Description
[0] string string The name of the governor

isQuadraticVotingDisabledForCurrentRound

function isQuadraticVotingDisabledForCurrentRound() external view returns (bool)

Check if quadratic voting is disabled for the current round.

Return Values

Name Type Description
[0] bool true if quadratic voting is disabled, false otherwise.

isQuadraticVotingDisabledForRound

function isQuadraticVotingDisabledForRound(uint256 roundId) external view returns (bool)

Check if quadratic voting is disabled at a specific round.

Parameters

Name Type Description
roundId uint256 - The round ID for which to check if quadratic voting is disabled.

Return Values

Name Type Description
[0] bool true if quadratic voting is disabled, false otherwise.

version

function version() external pure returns (string)

See {IB3TRGovernor-version}.

Return Values

Name Type Description
[0] string string The version of the governor

hashProposal

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

See {IB3TRGovernor-hashProposal}. The proposal id is produced by hashing the ABI encoded targets array, the values array, the calldatas array and the descriptionHash (bytes32 which itself is the keccak256 hash of the description string). This proposal id can be produced from the proposal data which is part of the {ProposalCreated} event. It can even be computed in advance, before the proposal is submitted. Note that the chainId and the governor address are not part of the proposal id computation. Consequently, the same proposal (with same operation and same description) will have the same id if submitted on multiple governors across multiple networks. This also means that in order to execute the same operation twice (on the same governor) the proposer will have to change the description in order to avoid proposal id conflicts.

Parameters

Name Type Description
targets address[] The list of target addresses
values uint256[] The list of values to send
calldatas bytes[] The list of call data
descriptionHash bytes32 The hash of the description

Return Values

Name Type Description
[0] uint256 uint256 The proposal id

timelockSalt

function timelockSalt(bytes32 descriptionHash) external view returns (bytes32)

Public endpoint to get the salt used for the timelock operation.

Parameters

Name Type Description
descriptionHash bytes32 The hash of the description

Return Values

Name Type Description
[0] bytes32 bytes32 The timelock salt

voterRewards

function voterRewards() external view returns (contract IVoterRewards)

The voter rewards contract.

Return Values

Name Type Description
[0] contract IVoterRewards IVoterRewardsV2 The voter rewards contract

xAllocationVoting

function xAllocationVoting() external view returns (contract IXAllocationVotingGovernor)

The XAllocationVotingGovernor contract.

Return Values

Name Type Description
[0] contract IXAllocationVotingGovernor IXAllocationVotingGovernor The XAllocationVotingGovernor contract

b3tr

function b3tr() external view returns (contract IB3TR)

See {B3TRGovernor-b3tr}.

Return Values

Name Type Description
[0] contract IB3TR IB3TR The B3TR contract

timelock

function timelock() external view virtual returns (address)

Public accessor to check the address of the timelock

Return Values

Name Type Description
[0] address address The address of the timelock

veBetterPassport

function veBetterPassport() external view returns (contract IVeBetterPassport)

Returns the VeBetterPassport contract.

Return Values

Name Type Description
[0] contract IVeBetterPassport The current VeBetterPassport contract.

pause

function pause() external

Pause the contract

unpause

function unpause() external

Unpause the contract

propose

function propose(address[] targets, uint256[] values, bytes[] calldatas, string description, uint256 startRoundId, uint256 depositAmount) external returns (uint256)

See {IB3TRGovernor-propose}. Callable only when contract is not paused.

Parameters

Name Type Description
targets address[] The list of target addresses
values uint256[] The list of values to send
calldatas bytes[] The list of call data
description string The proposal description
startRoundId uint256 The round in which the proposal should start
depositAmount uint256 The amount of deposit for the proposal

Return Values

Name Type Description
[0] uint256 uint256 The proposal id

queue

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

See {IB3TRGovernor-queue}. Callable only when contract is not paused.

Parameters

Name Type Description
targets address[] The list of target addresses
values uint256[] The list of values to send
calldatas bytes[] The list of call data
descriptionHash bytes32 The hash of the description

Return Values

Name Type Description
[0] uint256 uint256 The proposal id

execute

function execute(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external payable returns (uint256)

See {IB3TRGovernor-execute}. Callable only when contract is not paused.

Parameters

Name Type Description
targets address[] The list of target addresses
values uint256[] The list of values to send
calldatas bytes[] The list of call data
descriptionHash bytes32 The hash of the description

Return Values

Name Type Description
[0] uint256 uint256 The proposal id

cancel

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

See {Governor-cancel}.

Parameters

Name Type Description
targets address[] The list of target addresses
values uint256[] The list of values to send
calldatas bytes[] The list of call data
descriptionHash bytes32 The hash of the description

Return Values

Name Type Description
[0] uint256 uint256 The proposal id

castVote

function castVote(uint256 proposalId, uint8 support) external returns (uint256)

See {IB3TRGovernor-castVote}.

Parameters

Name Type Description
proposalId uint256 The id of the proposal
support uint8 The support value (0 = against, 1 = for, 2 = abstain)

Return Values

Name Type Description
[0] uint256 uint256 The voting power

castVoteWithReason

function castVoteWithReason(uint256 proposalId, uint8 support, string reason) external returns (uint256)

See {IB3TRGovernor-castVoteWithReason}.

Parameters

Name Type Description
proposalId uint256 The id of the proposal
support uint8 The support value (0 = against, 1 = for, 2 = abstain)
reason string The reason for the vote

Return Values

Name Type Description
[0] uint256 uint256 The voting power

withdraw

function withdraw(uint256 proposalId, address depositor) external

Withdraws deposits for a specific proposal

Parameters

Name Type Description
proposalId uint256 The id of the proposal
depositor address The address of the depositor

deposit

function deposit(uint256 amount, uint256 proposalId) external

Deposits tokens for a specific proposal

Parameters

Name Type Description
amount uint256 The amount of tokens to deposit
proposalId uint256 The id of the proposal

updateQuorumNumerator

function updateQuorumNumerator(uint256 newQuorumNumerator) external

Changes the quorum numerator. This operation can only be performed through a governance proposal. Emits a {QuorumNumeratorUpdated} event.

Parameters

Name Type Description
newQuorumNumerator uint256 The new quorum numerator

toggleQuadraticVoting

function toggleQuadraticVoting() external

Toggle quadratic voting for next round.

This function toggles the state of quadratic votingstarting from the next round. The state will flip between enabled and disabled each time the function is called.

setWhitelistFunction

function setWhitelistFunction(address target, bytes4 functionSelector, bool isWhitelisted) public

Method that allows to restrict functions that can be called by proposals for a single function selector

Parameters

Name Type Description
target address The address of the contract
functionSelector bytes4 The function selector
isWhitelisted bool Bool indicating if function is whitelisted for proposals

setWhitelistFunctions

function setWhitelistFunctions(address target, bytes4[] functionSelectors, bool isWhitelisted) public

Method that allows to restrict functions that can be called by proposals for multiple function selectors at once

Parameters

Name Type Description
target address The address of the contract
functionSelectors bytes4[] Array of function selectors
isWhitelisted bool Bool indicating if function is whitelisted for proposals

setIsFunctionRestrictionEnabled

function setIsFunctionRestrictionEnabled(bool isEnabled) public

Method that allows to toggle the function restriction on/off

Parameters

Name Type Description
isEnabled bool Flag to enable/disable function restriction

setDepositThresholdPercentage

function setDepositThresholdPercentage(uint256 newDepositThreshold) public

Update the deposit threshold. This operation can only be performed through a governance proposal. Emits a {DepositThresholdSet} event.

Parameters

Name Type Description
newDepositThreshold uint256 The new deposit threshold

setVotingThreshold

function setVotingThreshold(uint256 newVotingThreshold) public

Update the voting threshold. This operation can only be performed through a governance proposal. Emits a {VotingThresholdSet} event.

Parameters

Name Type Description
newVotingThreshold uint256 The new voting threshold

setMinVotingDelay

function setMinVotingDelay(uint256 newMinVotingDelay) public

Update the min voting delay before vote can start. This operation can only be performed through a governance proposal. Emits a {MinVotingDelaySet} event.

Parameters

Name Type Description
newMinVotingDelay uint256 The new minimum voting delay

setVoterRewards

function setVoterRewards(contract IVoterRewards newVoterRewards) public

Set the voter rewards contract This function is only callable through governance proposals or by the CONTRACTS_ADDRESS_MANAGER_ROLE

Parameters

Name Type Description
newVoterRewards contract IVoterRewards The new voter rewards contract

setXAllocationVoting

function setXAllocationVoting(contract IXAllocationVotingGovernor newXAllocationVoting) public

Set the xAllocationVoting contract This function is only callable through governance proposals or by the CONTRACTS_ADDRESS_MANAGER_ROLE

Parameters

Name Type Description
newXAllocationVoting contract IXAllocationVotingGovernor The new xAllocationVoting contract

updateTimelock

function updateTimelock(contract TimelockControllerUpgradeable newTimelock) external virtual

Public endpoint to update the underlying timelock instance. Restricted to the timelock itself, so updates must be proposed, scheduled, and executed through governance proposals. CAUTION: It is not recommended to change the timelock while there are other queued governance proposals.

Parameters

Name Type Description
newTimelock contract TimelockControllerUpgradeable The new timelock controller

setVeBetterPassport

function setVeBetterPassport(contract IVeBetterPassport newVeBetterPassport) public

Set the VeBetterPassport contract

Parameters

Name Type Description
newVeBetterPassport contract IVeBetterPassport The new VeBetterPassport contract

_authorizeUpgrade

function _authorizeUpgrade(address newImplementation) internal

Authorizes upgrade to a new implementation

Parameters

Name Type Description
newImplementation address The address of the new implementation

supportsInterface

function supportsInterface(bytes4 interfaceId) public pure returns (bool)

Checks if the contract supports a specific interface

Parameters

Name Type Description
interfaceId bytes4 The interface id to check

Return Values

Name Type Description
[0] bool bool True if the interface is supported, false otherwise

onERC1155Received

function onERC1155Received(address, address, uint256, uint256, bytes) public virtual returns (bytes4)

See {IERC1155Receiver-onERC1155Received}. Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock).

Return Values

Name Type Description
[0] bytes4 bytes4 The selector of the function

onERC721Received

function onERC721Received(address, address, uint256, bytes) public virtual returns (bytes4)

See {IERC721Receiver-onERC721Received}. Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock).

Return Values

Name Type Description
[0] bytes4 bytes4 The selector of the function

onERC1155BatchReceived

function onERC1155BatchReceived(address, address, uint256[], uint256[], bytes) public virtual returns (bytes4)

See {IERC1155Receiver-onERC1155BatchReceived}. Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock).

Return Values

Name Type Description
[0] bytes4 bytes4 The selector of the function