Gauge Controller
The GaugeController is responsible for managing and coordinating the distribution of rewards to liquidity providers in various liquidity pools. It determines the allocation of CRV rewards based on the liquidity provided by users. By analyzing the gauges, which are parameters that define how rewards are distributed across different pools, the GaugeController ensures a fair and balanced distribution of incentives, encouraging liquidity provision and participation in Curve's ecosystem.
Function to add a gauge to the GaugeController
Contract Source & Deployment
GaugeController contract is deployed to the Ethereum mainnet at: 0x2F50D538606Fa9EDD2B11E2446BEb18C9D5846bB.
Source code available on Github.
The GaugeController
does not have a public getter to check whether a gauge has been added or not. Alternatively, one can try to query the gauge_types
of the gauge.
>>> GaugeController.gauge_types("0xbfcf63294ad7105dea65aa58f8ae5be2d9d0952a")
0
>>> GaugeController.gauge_types("0xc840e5ed7a1b6a9c1a6bf1ecaca6ddb151b2fd6e")
Error: Returned error: execution reverted
If the gauge returns an int128
, this means the gauge has been added. The returned value represents the gauge type. If the query call reverts, this means the gauge has not been added.
Gauge Types¶
Each liquidity gauge is assigned a type within the gauge controller. Grouping gauges by type allows the DAO to adjust the emissions according to type, making it possible to e.g. end all emissions for a single type.
Description | Gauge Type |
---|---|
Ethereum (stable pools) | 0 |
Fantom | 1 |
Polygon | 2 |
deprecated | 3 |
Gnosis | 4 |
Ethereum (crypto pools) | 5 |
deprecated | 6 |
Arbitrum | 7 |
Avalance | 8 |
Harmony | 9 |
Fundraising | 10 |
Optimism | 11 |
BinanceSmartChain | 12 |
gauge_types
¶
GaugeController.gauge_types(_addr: address) -> int128: view
Getter for the gauge type of gauge _addr
.
Returns: gauge type (int128
).
Input | Type | Description |
---|---|---|
_addr | address | Gauge address |
Source code
n_gauge_types
¶
GaugeController.n_gauge_types() -> int128: view
Getter for the total number of gauge types.
Returns: total number of types (int128
).
Source code
n_gauge_types: public(int128)
@external
def add_type(_name: String[64], weight: uint256 = 0):
"""
@notice Add gauge type with name `_name` and weight `weight`
@param _name Name of gauge type
@param weight Weight of gauge type
"""
assert msg.sender == self.admin
type_id: int128 = self.n_gauge_types
self.gauge_type_names[type_id] = _name
self.n_gauge_types = type_id + 1
if weight != 0:
self._change_type_weight(type_id, weight)
log AddType(_name, type_id)
gauge_type_names
¶
GaugeController.gauge_type_names(arg0: int128) -> String[64]: view
Getter for the name of gauge type at index arg0
.
Returns: type name (string
).
Input | Type | Description |
---|---|---|
arg0 | int128 | Gauge type index |
get_type_weight
¶
GaugeController.get_type_weight(type_id: int128) -> uint256
Getter for the type weight of type_id
.
Returns: type weight (uint256
).
Input | Type | Description |
---|---|---|
type_id | int128 | gauge type id |
Source code
@external
@view
def get_type_weight(type_id: int128) -> uint256:
"""
@notice Get current type weight
@param type_id Type id
@return Type weight
"""
return self.points_type_weight[type_id][self.time_type_weight[type_id]]
@internal
def _get_type_weight(gauge_type: int128) -> uint256:
"""
@notice Fill historic type weights week-over-week for missed checkins
and return the type weight for the future week
@param gauge_type Gauge type id
@return Type weight
"""
t: uint256 = self.time_type_weight[gauge_type]
if t > 0:
w: uint256 = self.points_type_weight[gauge_type][t]
for i in range(500):
if t > block.timestamp:
break
t += WEEK
self.points_type_weight[gauge_type][t] = w
if t > block.timestamp:
self.time_type_weight[gauge_type] = t
return w
else:
return 0
Gauges Weights¶
Gauge weights define how much CRV emissions a gauge receives.
Gauge weights are updated every Thursday at 00:00 UTC. At this timestamp, the CRV emissions for one week are based on the gauge weights. The current weights remain the same until someone votes. If there are no votes for several weeks in a row, the gauge weights and CRV emissions will stay the same for all subsequent weeks.
CRV emissions and gauge weights
If a gauge receives 10% of the total weight, it will receive 10% of the emissions for the current week. At the time of writing, the inflation rate per second of CRV is 5181574864521283150 (CRV.rate())
, which equals 5.18157486452128315 CRV per second. The gauge will, therefore, receive approximately 313,381.65 CRV tokens as emissions for the current week, calculated as 5.18157486452128315 CRV per second * 10% * (7 * 86400 seconds).
gauge_relative_weight
¶
GaugeController.gauge_relative_weight(addr: address, time: uint256 = block.timestamp) -> uint256: view
Getter for the relative weight of gauge addr
at timestamp time
.
Returns: relative gauge weight (uint256
).
Input | Type | Description |
---|---|---|
addr | address | Gauge address |
time | uint256 | Timestamp to check the weight at; Defaults to block.timestamp |
Source code
@external
@view
def gauge_relative_weight(addr: address, time: uint256 = block.timestamp) -> uint256:
"""
@notice Get Gauge relative weight (not more than 1.0) normalized to 1e18
(e.g. 1.0 == 1e18). Inflation which will be received by it is
inflation_rate * relative_weight / 1e18
@param addr Gauge address
@param time Relative weight at the specified timestamp in the past or present
@return Value of relative weight normalized to 1e18
"""
return self._gauge_relative_weight(addr, time)
@internal
@view
def _gauge_relative_weight(addr: address, time: uint256) -> uint256:
"""
@notice Get Gauge relative weight (not more than 1.0) normalized to 1e18
(e.g. 1.0 == 1e18). Inflation which will be received by it is
inflation_rate * relative_weight / 1e18
@param addr Gauge address
@param time Relative weight at the specified timestamp in the past or present
@return Value of relative weight normalized to 1e18
"""
t: uint256 = time / WEEK * WEEK
_total_weight: uint256 = self.points_total[t]
if _total_weight > 0:
gauge_type: int128 = self.gauge_types_[addr] - 1
_type_weight: uint256 = self.points_type_weight[gauge_type][t]
_gauge_weight: uint256 = self.points_weight[addr][t].bias
return MULTIPLIER * _type_weight * _gauge_weight / _total_weight
else:
return 0
get_gauge_weight
¶
GaugeController.get_gauge_weight(addr: address) -> uint256: view`
Getter for the current gauge weight of gauge addr
.
Returns: gauge weight (uint256
).
Input | Type | Description |
---|---|---|
addr | address | Gauge address |
Source code
points_weight: public(HashMap[address, HashMap[uint256, Point]]) # gauge_addr -> time -> Point
@external
@view
def get_gauge_weight(addr: address) -> uint256:
"""
@notice Get current gauge weight
@param addr Gauge address
@return Gauge weight
"""
return self.points_weight[addr][self.time_weight[addr]].bias
get_total_weight
¶
GaugeController.get_total_weight() -> uint256: view
Getter for the current total weight.
Returns: total weight (uint256
).
Source code
get_weights_sum_per_type
¶
GaugeController.get_weights_sum_per_type(type_id: int128) -> uint256: view
Getter for the summed weight of gauge type type_id
.
Returns: summed weight (uint256
).
Input | Type | Description |
---|---|---|
type_id | int128 | Gauge type ID |
Source code
points_sum: public(HashMap[int128, HashMap[uint256, Point]]) # type_id -> time -> Point
@external
@view
def get_weights_sum_per_type(type_id: int128) -> uint256:
"""
@notice Get sum of gauge weights per type
@param type_id Type id
@return Sum of gauge weights
"""
return self.points_sum[type_id][self.time_sum[type_id]].bias
Vote-Weighting¶
Users who have a positive veCRV balance can allocate their voting power to gauges.
vote_for_gauge_weights
¶
GaugeController.vote_for_gauge_weights(_gauge_addr: address, _user_weight: uint256):
Warning
A gauge weight vote may only be modified once every 10 days.
Function to allocate _user_weight
voting power to gauge _gauge_addr
. _user_weight
is expressed and measured in bps (uints of 0.01%). Minimal weight is 0.01%.
Emits: VoteForGauge
Input | Type | Description |
---|---|---|
_gauge_addr | address | Gauge address |
_user_weight | address | Weight to allocate |
Source code
event VoteForGauge:
time: uint256
user: address
gauge_addr: address
weight: uint256
@external
def vote_for_gauge_weights(_gauge_addr: address, _user_weight: uint256):
"""
@notice Allocate voting power for changing pool weights
@param _gauge_addr Gauge which `msg.sender` votes for
@param _user_weight Weight for a gauge in bps (units of 0.01%). Minimal is 0.01%. Ignored if 0
"""
escrow: address = self.voting_escrow
slope: uint256 = convert(VotingEscrow(escrow).get_last_user_slope(msg.sender), uint256)
lock_end: uint256 = VotingEscrow(escrow).locked__end(msg.sender)
_n_gauges: int128 = self.n_gauges
next_time: uint256 = (block.timestamp + WEEK) / WEEK * WEEK
assert lock_end > next_time, "Your token lock expires too soon"
assert (_user_weight >= 0) and (_user_weight <= 10000), "You used all your voting power"
assert block.timestamp >= self.last_user_vote[msg.sender][_gauge_addr] + WEIGHT_VOTE_DELAY, "Cannot vote so often"
gauge_type: int128 = self.gauge_types_[_gauge_addr] - 1
assert gauge_type >= 0, "Gauge not added"
# Prepare slopes and biases in memory
old_slope: VotedSlope = self.vote_user_slopes[msg.sender][_gauge_addr]
old_dt: uint256 = 0
if old_slope.end > next_time:
old_dt = old_slope.end - next_time
old_bias: uint256 = old_slope.slope * old_dt
new_slope: VotedSlope = VotedSlope({
slope: slope * _user_weight / 10000,
end: lock_end,
power: _user_weight
})
new_dt: uint256 = lock_end - next_time # dev: raises when expired
new_bias: uint256 = new_slope.slope * new_dt
# Check and update powers (weights) used
power_used: uint256 = self.vote_user_power[msg.sender]
power_used = power_used + new_slope.power - old_slope.power
self.vote_user_power[msg.sender] = power_used
assert (power_used >= 0) and (power_used <= 10000), 'Used too much power'
## Remove old and schedule new slope changes
# Remove slope changes for old slopes
# Schedule recording of initial slope for next_time
old_weight_bias: uint256 = self._get_weight(_gauge_addr)
old_weight_slope: uint256 = self.points_weight[_gauge_addr][next_time].slope
old_sum_bias: uint256 = self._get_sum(gauge_type)
old_sum_slope: uint256 = self.points_sum[gauge_type][next_time].slope
self.points_weight[_gauge_addr][next_time].bias = max(old_weight_bias + new_bias, old_bias) - old_bias
self.points_sum[gauge_type][next_time].bias = max(old_sum_bias + new_bias, old_bias) - old_bias
if old_slope.end > next_time:
self.points_weight[_gauge_addr][next_time].slope = max(old_weight_slope + new_slope.slope, old_slope.slope) - old_slope.slope
self.points_sum[gauge_type][next_time].slope = max(old_sum_slope + new_slope.slope, old_slope.slope) - old_slope.slope
else:
self.points_weight[_gauge_addr][next_time].slope += new_slope.slope
self.points_sum[gauge_type][next_time].slope += new_slope.slope
if old_slope.end > block.timestamp:
# Cancel old slope changes if they still didn't happen
self.changes_weight[_gauge_addr][old_slope.end] -= old_slope.slope
self.changes_sum[gauge_type][old_slope.end] -= old_slope.slope
# Add slope changes for new slopes
self.changes_weight[_gauge_addr][new_slope.end] += new_slope.slope
self.changes_sum[gauge_type][new_slope.end] += new_slope.slope
self._get_total()
self.vote_user_slopes[msg.sender][_gauge_addr] = new_slope
# Record last action time
self.last_user_vote[msg.sender][_gauge_addr] = block.timestamp
log VoteForGauge(block.timestamp, msg.sender, _gauge_addr, _user_weight)
vote_user_power
¶
GaugeController.vote_user_power(arg0: address) -> uint256: view
Getter method for the total allocated voting power by address arg0
. If a user has a veCRV balance but has not yet voted, this function will return 0.
Returns: used voting power (uint256
).
Input | Type | Description |
---|---|---|
arg0 | address | User address |
last_user_vote
¶
GaugeController.last_user_vote(arg0: address, arg1: address) -> uint256: view
Getter for the last timestamp user arg0
voted for gauge arg1
.
Returns: timestamp (uint256
).
Input | Type | Description |
---|---|---|
arg0 | address | User address |
arg1 | address | Gauge address |
Source code
vote_user_slopes
¶
GaugeController.vote_user_slopes(arg0: address, arg1: address) -> slope: uint256, power: uint256, end: uint256
Getter method for informations about the current vote weight of user arg0
for gauge arg1
. In this variable, informations are stored at the time of voting.
Returns: slope (uint256
), allocated voting-power (uint256
) and veCRV lock end (uint256
).
Input | Type | Description |
---|---|---|
arg0 | address | User address |
arg1 | address | Gauge address |
Source code
Points¶
GaugeController records points (bias + slope) per gauge in vote_points
, and scheduled changes in biases and slopes for those points in vote_bias_changes
and vote_slope_changes
. New changes are applied at the start of each epoch week.
A Point
is composed of a bias
and a slope
:
points_weight
¶
GaugeController.points_weight(arg0: address, arg1: uint256)
Getter for the Point
information of a user arg0
.
Returns: bias (uint256
) and slope (uint256
).
Input | Type | Description |
---|---|---|
arg0 | address | User address |
arg1 | uint256 | Point |
Source code
time_weight
¶
GaugeController.time_weight(arg0: address) -> uint256: view
Getter for the last scheduled time the gauge weight of gauge arg0
updates. This should always be the coming Thursday at 00:00 UTC and is updated when a gauge weight is updated.
Returns: timestamp (uint256
).
Input | Type | Description |
---|---|---|
arg0 | address | Gauge address |
Source code
points_sum
¶
GaugeController.points_sum(arg0: int128, arg1: uint256) -> bias: uint256, slope: uint256: view
Getter for informations from Point
struct.
Returns: bias (uint256
) and slope (uint256
).
Input | Type | Description |
---|---|---|
arg0 | int128 | Gauge type ID |
arg0 | address | Timestamp |
time_sum
¶
GaugeController.time_sum(arg0: uint256) -> uint256: view
Getter for the last scheduled time (next week).
Returns: timestamp (uin256
).
Input | Type | Description |
---|---|---|
arg0 | int128 | Gauge type ID |
points_total
¶
GaugeController.points_total(arg0: uint256) -> uint256: view
Getter for the currennt future total weight at timestamp arg0
.
Returns: total points (uin256
).
Input | Type | Description |
---|---|---|
arg0 | uint256 | Timestamp of the next gauge weight update |
time_total
¶
GaugeController.time_total() -> uint256: view
Getter for the last scheduled time when the gauge weights will update.
Returns: timestamp (uin256
).
points_type_weight
¶
GaugeController.points_type_weight(arg0: int128, arg1: uint256) -> uint256: view
Getter for the weight for gauge type arg0
at the next update, which is at timestamp arg1
.
Returns: type weigt (uint256
).
Input | Type | Description |
---|---|---|
arg0 | int128 | Gauge type ID |
arg1 | uint256 | Timestamp |
Source code
time_type_weight
¶
GaugeController.time_type_weight(arg0: uint256) -> uint256: view
Getter for the last scheduled time, when the type weights update.
Returns: timestamp (uint256
).
Input | Type | Description |
---|---|---|
arg0 | uint256 | Type ID |
Source code
Gauge Info¶
n_gauges
¶
GaugeController.n_gauges -> int128: view
Getter for the total number of individual gauges. This variable is incremented by one each time a new gauge is added (add_gauge
) to the GaugeController.
Returns: amount of gauges (int128
).
Source code
n_gauges: public(int128)
@external
def add_gauge(addr: address, gauge_type: int128, weight: uint256 = 0):
"""
@notice Add gauge `addr` of type `gauge_type` with weight `weight`
@param addr Gauge address
@param gauge_type Gauge type
@param weight Gauge weight
"""
assert msg.sender == self.admin
assert (gauge_type >= 0) and (gauge_type < self.n_gauge_types)
assert self.gauge_types_[addr] == 0 # dev: cannot add the same gauge twice
n: int128 = self.n_gauges
self.n_gauges = n + 1
...
gauges
¶
GaugeController.gauges(arg0: uint256) -> address: view
Getter for the gauge address at index arg0
.
Returns: gauge (address
).
Input | Type | Description |
---|---|---|
arg0 | uint256 | Gauge index |
Source code
gauges: public(address[1000000000])
@external
def add_gauge(addr: address, gauge_type: int128, weight: uint256 = 0):
"""
@notice Add gauge `addr` of type `gauge_type` with weight `weight`
@param addr Gauge address
@param gauge_type Gauge type
@param weight Gauge weight
"""
assert msg.sender == self.admin
assert (gauge_type >= 0) and (gauge_type < self.n_gauge_types)
assert self.gauge_types_[addr] == 0 # dev: cannot add the same gauge twice
n: int128 = self.n_gauges
self.n_gauges = n + 1
self.gauges[n] = addr
...
Contract Info Methods¶
token
¶
GaugeController.token() -> address: view
Getter for the Curve DAO Token.
Returns: crv token (address
).
Source code
voting_escrow
¶
GaugeController.voting_escrow() -> address: view
Getter for the VotingEscrow contract.
Returns: voting escrow (address
).
Source code
voting_escrow: public(address) # Voting escrow
@external
def __init__(_token: address, _voting_escrow: address):
"""
@notice Contract constructor
@param _token `ERC20CRV` contract address
@param _voting_escrow `VotingEscrow` contract address
"""
...
assert _voting_escrow != ZERO_ADDRESS
...
self.voting_escrow = _voting_escrow