package v1 manages GNS token staking and delegation functionality. It handles delegation of voting power, distributio...
Liquidity mining and reward distribution for LP positions.
Staker manages distribution of internal (GNS emission) and external (user-provided) rewards to staked LP positions, with time-weighted rewards and warmup periods.
Every staked position progresses through warmup periods:
StakeTokenStakes LP position NFT to earn rewards.
UnStakeTokenUnstakes position and collects all rewards.
CollectRewardCollects accumulated rewards without unstaking.
CreateExternalIncentiveCreates external reward program for specific pool.
EndExternalIncentiveEnds incentive program and returns unused rewards.
Emission split across tiers based on active pools:
If only tier 1 has pools: [100%, 0%, 0%]
If tiers 1 & 3 have pools: [80%, 0%, 20%]
If tiers 1 & 2 have pools: [70%, 30%, 0%]
If all tiers have pools: [50%, 30%, 20%]
Mathematical representation:
TierRatio(t) =
[1, 0, 0] if Count(2) = 0 ∧ Count(3) = 0
[0.8, 0, 0.2] if Count(2) = 0
[0.7, 0.3, 0] if Count(3) = 0
[0.5, 0.3, 0.2] otherwise
poolReward(pool) = (emission × TierRatio[tier(pool)]) / Count(tier(pool))
Where emission is calculated as:
emission = GNSEmissionPerSecond × (avgMsPerBlock/1000) × StakerEmissionRatio
The reward for each position is calculated through:
Mathematical formula for total reward ratio:
TotalRewardRatio(s,e) = Σ[i=0 to m-1] ΔRaw(αᵢ, βᵢ) × rᵢ
where:
αᵢ = max(s, Hᵢ₋₁)
βᵢ = min(e, Hᵢ)
ΔRaw(a, b) = CalcRaw(b) - CalcRaw(a)
CalcRaw(h) =
L(h) - U(h) if tick(h) < ℓ
U(h) - L(h) if tick(h) ≥ u
G(h) - (L(h) + U(h)) otherwise
where:
L(h) = tickLower.OutsideAccumulation(h)
U(h) = tickUpper.OutsideAccumulation(h)
G(h) = globalRewardRatioAccumulation(h)
ℓ = tickLower.id
u = tickUpper.id
Final position reward:
finalReward = TotalRewardRatio × poolReward × positionLiquidity
= ∫[s to e] (poolReward × positionLiquidity) / TotalStakedLiquidity(h) dh
When price crosses an initialized tick with staked positions:
globalRewardRatioAccumulationCurrentOutsideAccumulationThe globalRewardRatioAccumulation tracks the integral:
globalRewardRatioAccumulation = ∫ 1/TotalStakedLiquidity(h) dh
This integral is only computed when TotalStakedLiquidity(h) ≠ 0, enabling precise reward calculation even as liquidity changes.
The system maintains:
1// Stake existing position
2StakeToken(123, "g1referrer...")
3
4// Create external incentive
5CreateExternalIncentive(
6 "gno.land/r/demo/bar:gno.land/r/demo/baz:3000",
7 "gno.land/r/demo/reward",
8 "1000000000", // 1000 tokens
9 startTime,
10 endTime,
11)
12
13// Collect rewards without unstaking
14CollectReward(123)
15
16// Unstake and collect all rewards
17UnStakeToken(123)
package v1 manages GNS token staking and delegation functionality. It handles delegation of voting power, distribution of protocol rewards, and implements a lockup period (default: 7-days) for unstaking operations (xGNS burned on collect).
NewDelegation creates a new delegation. This is a convenience wrapper around staker.NewDelegation.
Parameters:
Returns:
NewDelegationWithdraw creates a new delegation withdrawal with lockup period. This is a convenience wrapper around staker.NewDelegationWithdraw.
Parameters:
Returns:
NewDelegationWithdrawWithoutLockup creates a new delegation withdrawal that is immediately collectable. This is a convenience wrapper around staker.NewDelegationWithdrawWithoutLockup.
Parameters:
Returns:
GetUserDelegationIDs retrieves all delegation IDs for a specific delegator across all delegatees. This method is used to find all delegations made by a specific user.
Parameters:
Returns:
1func (dm *DelegationManagerResolver) GetUserDelegationIDsWithDelegatee(delegator, delegatee address) []int64GetUserDelegationIDsWithDelegatee retrieves all delegation IDs for a specific delegator-delegatee pair. This method is used to find delegations from a specific user to a specific delegate.
Parameters:
Returns:
CollectableAmount calculates the total amount that can be collected at the given time
UnDelegate processes an undelegation with lockup period
UnDelegateWithoutLockup processes an immediate undelegation without lockup
collect processes the collection of the specified amount from this withdrawal. This method validates collectability and updates the collection state.
Parameters:
Returns:
CollectableAmount calculates the amount available for collection at the given time. Returns zero if the withdrawal is not yet collectable or has been fully collected.
Parameters:
Returns:
IsCollectable determines whether the withdrawal can be collected at the given time. A withdrawal is collectable if: - The undelegated amount is positive - There is remaining uncollected amount - The current time is at or after the collectable time
Parameters:
Returns:
IsCollected returns whether the withdrawal has been fully collected.
Returns:
GetClaimableRewardAmount calculates the claimable reward amount for a specific address.
GetClaimableRewardAmount calculates the total amount of rewards that can be claimed. This includes both accumulated rewards and newly earned rewards based on current state.
Parameters:
Returns:
IsClaimable checks if rewards can be claimed at the given timestamp. Rewards are claimable if the current timestamp is greater than the last claimed timestamp.
Parameters:
Returns:
GetClaimableRewardAmounts calculates the claimable reward amounts for all tokens for a specific address. This method computes rewards based on current protocol fee distribution state and staking history.
Parameters:
Returns:
GetClaimableRewardAmounts calculates the claimable reward amounts for all tokens. This includes both accumulated rewards and newly earned rewards based on current state.
Parameters:
Returns:
IsClaimable checks if rewards can be claimed at the given timestamp. Rewards are claimable if the current timestamp is greater than the last claimed timestamp.
Parameters:
Returns:
