CarbGovernor & CarbTimelock

CarbGovernor inherits: Governor, GovernorSettings, GovernorCountingSimple, GovernorVotes, GovernorVotesQuorumFraction, GovernorTimelockControl (OpenZeppelin 4.9.3). CarbTimelock inherits: TimelockController. Sources: contracts/token/CarbGovernor.sol, contracts/token/CarbTimelock.sol.

Governance covers protocol parameters only. It has no control over credit issuance (the NFT's ISSUER_ROLE and ISSUER_ADMIN_ROLE are never given to it) and no control over user escrow (it holds no role that could touch it).

How it works

• Voting power: CARB with ERC20Votes. Tokens count only after delegate(...). Tokens held by CarbStaking and IssuerBond carry no votes.
• Clock: the token's clock is block.timestamp, so votingDelay, votingPeriod, proposalSnapshot and proposalDeadline are seconds (timestamps), not blocks.
• Counting: for / against / abstain (GovernorCountingSimple). Quorum is a percentage of the total supply at the proposal snapshot.
• Execution: a succeeded proposal is queued in CarbTimelock and executed after the timelock delay. The timelock, not the governor, is the account that holds PARAMETER_ROLE and SLASHER_ROLE on the protocol contracts, so governance power is exactly what those roles allow.

What the timelock can do (once the roles are granted at stage 1 or later, see Roles & Security):

Every setter keeps its own hard bounds, so a passed proposal cannot go outside them (for example trading fee at most 1 %).

CarbGovernor

Constructor

constructor(
    IVotes token_,
    TimelockController timelock_,
    uint256 votingDelay_,
    uint256 votingPeriod_,
    uint256 proposalThreshold_,
    uint256 quorumPercent_,
    address[] memory initialTargets
)

The governor is named CarbGovernor. The constructor allowlists itself, the timelock and every address in initialTargets (the deployment helper passes marketplace, staking and bond). The bounds below are checked at construction and on every update, so the constructor can revert with their messages; allowedTargets rejects the zero address (Invalid target).

Bounds (constants)

Target allowlist

allowedTargets(address) is a public mapping. propose reverts unless every target is allowlisted and every values[i] is zero, so a proposal cannot call other contracts or carry ETH. The allowlist is a second line of defence: even if governance voted to allowlist the NFT, executing an issuance grant would fail because the timelock holds no NFT role (covered by a test).

Functions

Hash a proposal with hashProposal(targets, values, calldatas, keccak256(bytes(description))).

Events

Errors (revert strings)

Everything else is standard OpenZeppelin Governor: / TimelockController: reverts (for example Governor: proposer votes below proposal threshold, Governor: proposal not successful).

CarbTimelock

An OpenZeppelin TimelockController whose minimum delay is bounded, so governance can never collapse the public exit window to zero.

constructor(uint256 minDelay, address[] memory proposers, address[] memory executors, address admin)

The timelock is intended to be self-administered: pass admin = address(0), or renounce TIMELOCK_ADMIN_ROLE after wiring. The deployment helper (deployGovernance) grants the governor PROPOSER_ROLE and CANCELLER_ROLE, grants EXECUTOR_ROLE to address(0) (anyone may execute a queued operation) unless configured otherwise, and renounces the deployer's temporary TIMELOCK_ADMIN_ROLE.

It holds no credit-issuance, escrow or admin role. assertGovernanceBoundaries in the same helper fails if the timelock ever holds a forbidden role.

Caveats

• Governance capture. One token, one vote. If the owner, treasury or a few holders control most delegated supply, they control the outcome. Bounds and the least-privilege timelock limit what a captured vote can do (fee at most 1 %, discount at most 50 % of the fee, no issuance, no escrow). They do not prevent slashing bonded issuers or changing the KYC-gate and minimum-price parameters.
• Quorum vs. non-voting supply. Quorum is a fraction of total supply, including treasury, staked and bonded tokens that cannot vote. Calibrate quorumPercent against the real distribution of delegated tokens or governance can stall.
• Delegation is required. Undelegated tokens have no votes.
• Timestamps. The sequencer sets block.timestamp on an L2 within bounded drift; durations are days, so drift is immaterial, but a sequencer outage delays proposal progress.
• Emergency powers stay off-governance. PAUSER_ROLE intentionally stays with a fast multisig at every stage.
• Not upgradeable.