ProposalManager

Overview

ProposalManager is a governance contract built on OpenZeppelin’s Governor framework, incorporating additional logic for:

• Protected Function Selectors: Certain function calls (on specific chain IDs and target addresses) are restricted to the contract owner. This prevents unauthorized calls to critical on-chain functionality within governance proposals.

• Cross-Chain Awareness: Maintains a set of valid chain IDs for bridging proposals, allowing secure multi-chain governance actions when using the bridge.

• Custom Quorum Rules: Allows the owner to adjust the quorum fraction within set bounds (25%–80%).

The contract also integrates with a Calldata Helper (CALLDATA_HELPER) to decode function selectors from the bridging calls. By extending Governor, GovernorCountingSimple, GovernorVotes, GovernorVotesQuorumFraction, GovernorTimelockControl, and Ownable, ProposalManager offers a robust on-chain DAO mechanism with time-locked execution, vote counting, adjustable quorum, and protective measures for crucial function selectors.

Inherited Contracts and Interfaces

1. Governor (OpenZeppelin): Base contract for on-chain governance, offering functionalities such as proposal creation, voting, proposal states, etc.

2. GovernorCountingSimple (OpenZeppelin): Implements a simple vote counting mechanism: For, Against, and Abstain.

3. GovernorVotes (OpenZeppelin): Integrates an IVotes token (in this case, an escrow manager providing voting power) for calculating a user’s votes at proposal snapshot blocks.

Additional External References:

• ICalldataHelperV1 (CALLDATA_HELPER): A contract that decodes selectors from proposal call data, used for identifying protected function selectors in bridging calls.

• EnumerableSet (OpenZeppelin): Used to store a set of valid chain IDs, ensuring efficient addition, removal, and existence checks.

Constants

• MINIMUM_QUORUM_NUMERATOR (25): Minimum permissible quorum fraction (25%).

• MAXIMUM_QUORUM_NUMERATOR (80): Maximum permissible quorum fraction (80%).

State Variables

• CALLDATA_HELPER (ICalldataHelperV1 immutable) The address of a helper contract used to decode function selectors for bridging calls. Set in the constructor and cannot be changed.

• s_bridge (address) The address of the bridge contract used for cross-chain proposals or calls. Initially set in the constructor, can be updated by setBridge.

Constructor

• Parameters:

  • escrowManager_: An IVotes-compliant contract (e.g., an escrow manager) used for vote calculations.

  • timelock_: The TimelockController contract address used to queue and execute proposals after a time delay.

External Functions

1. setBridge(address bridge_)

• Description: Updates the s_bridge address used for bridging calls. Only callable by the contract owner.

• Parameters:

  • bridge_: The new bridge contract address.

2. addChainId(uint256 chainId_)

• Description: Adds a new chain ID to _chainIds. If the chain ID already exists, it reverts.

• Checks:

  • _chainIds.add(chainId_) must return true, otherwise reverts with ChainIdAlreadyExists(chainId_).

3. removeChainId(uint256 chainId_)

• Description: Removes an existing chain ID from _chainIds. If the chain ID does not exist, it reverts.

• Checks:

  • _chainIds.remove(chainId_) must return true, otherwise reverts with ChainIdDoesNotExist(chainId_).

4. getChainIdsLength()

• Description: Returns the number of chain IDs stored in _chainIds.

• Return:

  • uint256: The length of _chainIds.

5. getChainIdAtIndex(uint256 index_)

• Description: Retrieves a chain ID from _chainIds by index_.

• Return:

  • uint256: The chain ID at the specified index.

6. addProtectedSelector(uint256 chainId_, address target_, bytes4 selector_)

• Description: Marks a function selector (selector_) as protected on a particular chainId_ and target_. If the chain ID doesn’t exist or the selector is already protected, it reverts.

• Events & Checks:

  • Must have _chainIds.contains(chainId_)

7. removeProtectedSelector(uint256 chainId_, address target_, bytes4 selector_)

• Description: Removes a protected function selector from s_protectedSelectorsByChainIdAndTarget. If the chain ID isn’t recognized or the selector isn’t actually protected, it reverts.

• Logic:

  1. Ensures chainId_ is valid in _chainIds.

8. updateQuorumNumerator(uint256 quorumNumerator_)

• Description: An override from GovernorVotesQuorumFraction that checks if the new quorum fraction is within [MINIMUM_QUORUM_NUMERATOR, MAXIMUM_QUORUM_NUMERATOR]. Otherwise reverts with GovernorInvalidQuorumFraction(...).

9. updateTimelock(TimelockController)

• Description: An override from GovernorTimelockControl. This function does nothing here (the timelock is set in the constructor).

10. propose(...) (Overridden from Governor)

• Description:

  • Creates a new proposal. Before creation, the contract calls _checkSelectors(...) to see if any protected calls are included in calldatas_. If protected calls are found but the proposer is not the owner, it reverts with ProtectedFunctionSelectorUsed().

  • After checking, it calls super.propose(...)

Integration with OpenZeppelin Governor Modules

clock() (IERC6372)

• Description: Returns the current timestamp as a uint48. Used by the governance system for time-related logic.

state(uint256 proposalId_)

• Description: Returns the current state of a proposal (Pending, Active, Canceled, Defeated, Succeeded, Queued, Expired, or Executed), integrating timelock considerations.

quorum(uint256 timepoint_)

• Description: Calculates the number of votes required for quorum at a given timepoint_, i.e., (totalSupplyAt(timepoint_) * quorumNumerator(timepoint_)) / quorumDenominator().

CLOCK_MODE()

• Description: Returns "mode=timestamp", indicating that block timestamps (instead of block numbers) are used for governance timing.

proposalThreshold(), votingDelay(), votingPeriod(), proposalNeedsQueuing(...)

These standard overrides define:

• proposalThreshold(): 2_500e18 — minimum voting power needed to create a proposal.

• votingDelay(): 2 days — time between proposal creation and the start of voting.

Internal Functions

_checkSelectors(...)

• Description:

  • Iterates over targets_ and associated calldatas_, extracting the function selector for each. Then checks if it is among the protected selectors for the given chain ID (block.chainid) or if the target is the s_bridge address.

_queueOperations(...), _executeOperations(...), _cancel(...), _executor()

These are standard overrides from GovernorTimelockControl that handle queueing, executing, and canceling proposals in the timelock. The _executeOperations override also calls _checkSelectors(...) again before executing the proposal.

Events

1. BridgeUpdated(address indexed oldBridge, address indexed newBridge)

   • Emitted when the bridge address changes via setBridge.

No additional custom events are defined besides those in the IProposalManager interface and standard Governor events.

Errors

From IProposalManager, we have:

• ChainIdAlreadyExists(uint256 chainId)

• ChainIdDoesNotExist(uint256 chainId)

• SelectorAlreadyExists(bytes4 selector)

Summary

ProposalManager extends and customizes OpenZeppelin’s Governor to cater to CrossCurve DAO’s multi-chain governance needs. Through protective measures (_checkSelectors), it guards certain function calls on specific chain IDs and target addresses, ensuring only the contract owner can propose them. Additionally, it manages a dynamic range of acceptable quorum fractions and integrates with a TimelockController for secure, time-delayed proposal execution. By combining these features with ICalldataHelperV1 for decoding bridging calls, ProposalManager offers a flexible yet secure governance solution for cross-chain proposals in the CrossCurve ecosystem.