Gauge V3

contract GaugeV3 is IGaugeV3, ACLTrait, SanityCheckTrait

struct QuotaRateParams {
    uint16 minRate;           // Minimum rate (set by risk committee)
    uint16 maxRate;           // Maximum rate (set by DAO)
    uint96 totalVotesLpSide;  // Total votes for LP side
    uint96 totalVotesCaSide;  // Total votes for CA side
}

struct UserVotes {
    uint96 votesLpSide;  // User's votes on LP side
    uint96 votesCaSide;  // User's votes on CA side
}

function vote(
    address user,
    uint96 votes,
    bytes calldata extraData
) external

// Vote 1000 votes for WETH on LP side
bytes memory extraData = abi.encode(WETH, true);
voter.vote(user, 1000, extraData);

function unvote(
    address user,
    uint96 votes,
    bytes calldata extraData
) external

// Remove 500 votes from WBTC on CA side
bytes memory extraData = abi.encode(WBTC, false);
voter.unvote(user, 500, extraData);

function updateEpoch() external

// Anyone can call to update epoch
gauge.updateEpoch();

function getRates(address[] calldata tokens)
    external
    view
    returns (uint16[] memory rates)

rate = (minRate * votesCaSide + maxRate * votesLpSide) / totalVotes

// Get current rates (may differ from active rates until next epoch)
address[] memory tokens = new address[](2);
tokens[0] = WETH;
tokens[1] = WBTC;
uint16[] memory rates = gauge.getRates(tokens);

function addQuotaToken(
    address token,
    uint16 minRate,
    uint16 maxRate
) external

// Add WETH with 2% min, 15% max
gauge.addQuotaToken(
    WETH,
    200,   // 2% minimum
    1500   // 15% maximum
);

function addToken(address token) external

function changeQuotaMinRate(address token, uint16 minRate) external

// Increase WETH minimum rate to 3%
gauge.changeQuotaMinRate(WETH, 300);

function changeQuotaMaxRate(address token, uint16 maxRate) external

// Decrease WBTC maximum rate to 12%
gauge.changeQuotaMaxRate(WBTC, 1200);

function setFrozenEpoch(bool status) external

// Freeze gauge before migration
gauge.setFrozenEpoch(true);

// ... perform migration ...

// Unfreeze after migration complete
gauge.setFrozenEpoch(false);

function quotaRateParams(address token) external view returns (
    uint16 minRate,
    uint16 maxRate,
    uint96 totalVotesLpSide,
    uint96 totalVotesCaSide
)

// Check WETH rate params and votes
(
    uint16 minRate,
    uint16 maxRate,
    uint96 lpVotes,
    uint96 caVotes
) = gauge.quotaRateParams(WETH);

console.log("Rate range:", minRate, "-", maxRate, "bps");
console.log("LP votes:", lpVotes);
console.log("CA votes:", caVotes);

function userTokenVotes(address user, address token) external view returns (
    uint96 votesLpSide,
    uint96 votesCaSide  
)

function isTokenAdded(address token) external view returns (bool)

event UpdateEpoch(uint16 epochNow)
event Vote(address indexed user, address indexed token, uint96 votes, bool lpSide)
event Unvote(address indexed user, address indexed token, uint96 votes, bool lpSide)
event AddQuotaToken(address indexed token, uint16 minRate, uint16 maxRate)
event SetQuotaTokenParams(address indexed token, uint16 minRate, uint16 maxRate)
event SetFrozenEpoch(bool status)

// Deploy gauge
GaugeV3 gauge = new GaugeV3(poolAddress, gearStakingAddress);

// Add tokens with rate bounds
gauge.addQuotaToken(
    WETH,
    200,   // 2% min (risk committee says min safe rate)
    1500   // 15% max (DAO says max competitive rate)
);

gauge.addQuotaToken(
    WBTC,
    150,   // 1.5% min
    1200   // 12% max
);

// Unfreeze to allow rate updates
gauge.setFrozenEpoch(false);

// User stakes GEAR to get voting power
gearStaking.stake(1000e18);

// Vote 500 votes for WETH on LP side (wants higher rates for LPs)
bytes memory wethLpVote = abi.encode(WETH, true);
gearStaking.submitVote(gauge, 500, wethLpVote);

// Vote 300 votes for WBTC on CA side (wants lower rates for borrowers)
bytes memory wbtcCaVote = abi.encode(WBTC, false);
gearStaking.submitVote(gauge, 300, wbtcCaVote);

// Later, remove some votes
gearStaking.removeVote(gauge, 200, wethLpVote);

// At the start of a new epoch (e.g., Monday 00:00 UTC):

// 1. Anyone triggers epoch update
gauge.updateEpoch();
// This calls poolQuotaKeeper.updateRates() internally

// 2. Quota keeper queries new rates from gauge
address[] memory tokens = quotaKeeper.quotedTokens();
uint16[] memory rates = gauge.getRates(tokens);
// rates[0] = weighted average between minRate and maxRate based on votes

// 3. Quota keeper updates cumulative indexes and sets new rates
// These new rates will apply for the next week until next epoch update

// Check current vote distribution for WETH
(uint16 min, uint16 max, uint96 lpVotes, uint96 caVotes) = 
    gauge.quotaRateParams(WETH);

console.log("WETH rate range:", min, "-", max, "bps");
console.log("LP side votes:", lpVotes);
console.log("CA side votes:", caVotes);

// Calculate effective rate
uint256 totalVotes = lpVotes + caVotes;
uint16 effectiveRate = totalVotes == 0 
    ? min
    : uint16((min * caVotes + max * lpVotes) / totalVotes);
console.log("Effective rate:", effectiveRate, "bps");

// Check user's individual votes
(uint96 userLpVotes, uint96 userCaVotes) = 
    gauge.userTokenVotes(userAddress, WETH);
console.log("User's WETH votes - LP:", userLpVotes, "CA:", userCaVotes);