v1 state

TIMESTAMP_90DAYS

TIMESTAMP_180DAYS

TIMESTAMP_365DAYS

MAX_UNIX_EPOCH_TIME

// 9999-12-31 23:59:59

assertIsValidAmount

assertIsValidAmount ensures the amount is non-negative.

assertIsValidRewardAmountFormat

assertIsValidRewardAmountFormat ensures the reward amount string is formatted as "tokenPath:amount".

assertIsDepositor

assertIsDepositor ensures the caller is the owner of the deposit.

assertIsNotStaked

assertIsNotStaked ensures the position is not already staked.

assertIsPoolExists

assertIsPoolExists ensures the pool exists.

assertIsValidPoolTier

assertIsValidPoolTier ensures the tier is within valid range.

assertIsGreaterThanMinimumRewardAmount

assertIsGreaterThanMinimumRewardAmount ensures the reward amount meets minimum requirements.

assertIsAllowedForExternalReward

assertIsAllowedForExternalReward ensures the token is allowed for external rewards.

maxUnstakingFee

// 10%

assertIsValidFeeRate

assertIsValidFeeRate ensures the fee rate is within valid range (0-1000 basis points).

assertIsValidIncentiveStartTime

assertIsValidIncentiveStartTime ensures the incentive starts at midnight of a future date.

assertIsValidIncentiveEndTime

assertIsValidIncentiveEndTime ensures the end timestamp is within valid epoch range.

assertIsValidIncentiveDuration

assertIsValidIncentiveDuration ensures the duration is 90, 180, or 365 days.

assertIsValidAddress

AssertIsValidAddress panics if the provided address is invalid.

isMidnight

isMidnight checks if a time represents midnight (00:00:00).

assertIsPositionOwner

assertIsPositionOwner validates that the caller has permission to operate the token.

Reward

Reward is a struct for storing reward for a position. Internal reward is the GNS reward, external reward is the reward for other incentives. Penalties are the amount that is deducted from the reward due to the position's warmup.

CalcPositionRewardParam

CalcPositionRewardParam is a struct for calculating position reward

getInitialCollectTime

getInitialCollectTime determines the initial collection time for an incentive by taking the maximum of the deposit's stake time and the incentive's start time. This ensures rewards are only calculated from when both conditions are met: - The position must be staked (deposit.stakeTime) - The incentive must be active (incentive.startTimestamp) This function is used for lazy initialization when a position collects from an incentive for the first time, avoiding the need to iterate through all deposits when a new incentive is created.

GNS_TOKEN_KEY

WUGNOT_TOKEN_KEY

emitSetPoolTier

errNoPermission

errPoolNotFound

errNotAvailableUpdateCollectTime

errInvalidInput

errInvalidUnstakingFee

errAlreadyStaked

errNonIncentivizedPool

errCannotEndIncentive

errInvalidIncentiveStartTime

errDefaultExternalToken

errInvalidPoolPath

errInvalidPoolTier

errDataNotFound

errCalculationError

errZeroLiquidity

errInvalidIncentiveDuration

errNotAllowedForExternalReward

errIncentiveAlreadyExists

errOverflow

errAddExistingToken

errInvalidAddress

errIsNotEndedIncentive

errSpoofedRealm

makeErrorWithDetails

tickCrossEventInfo

NewTickCrossEventInfo

checkCannotAddDefaultToken

checkCannotRemoveDefaultToken

defaultDepositGnsAmount

defaultMinimumRewardAmount

defaultUnstakingFee

// 1%

defaultInitialPoolTierPath

init.58

registerStakerV1

initStoreData

initializePoolTier

stakerV1

NewStakerV1

NOT_EMISSION_TARGET_TIER

pctToIndex

pctToIndex converts percentage to warmup index.

IncentivesResolver

NewIncentivesResolver

retrieveIncentive

calculateUnClaimableDuration

calculateUnClaimableDuration calculates the duration of overlap between an unclaimable period and incentive period

q128

Pools

Pools represents the global pool storage

NewPools

PoolResolver

NewPoolResolver

NewPool creates a new pool with the given poolPath and currentHeight.

RewardState

RewardState is a struct for storing the intermediate state for reward calculation.

AllTierCount

// 0, 1, 2, 3

Tier1

Tier2

Tier3

TierRatioFromCounts

TierRatioFromCounts calculates the ratio distribution for each tier based on pool counts. Parameters: - tier1Count (uint64): Number of pools in tier 1. - tier2Count (uint64): Number of pools in tier 2. - tier3Count (uint64): Number of pools in tier 3. Returns: - TierRatio: The ratio distribution across tier 1, 2, and 3, scaled up by 100.

PoolTier

PoolTier manages pool counts, ratios, and rewards for different tiers. Fields: - membership: Tracks which tier a pool belongs to (poolPath -> blockNumber -> tier). Methods: - CurrentCount: Returns the current count of pools in a tier at a specific timestamp. - CurrentRatio: Returns the current ratio for a tier at a specific timestamp. - CurrentTier: Returns the tier of a specific pool at a given timestamp. - CurrentReward: Retrieves the reward for a tier at a specific timestamp. - changeTier: Updates the tier of a pool and recalculates ratios.

NewPoolTier

NewPoolTier creates a new PoolTier instance with single initial 1 tier pool. Parameters: - pools: The pool collection. - currentTime: The current block time. - initialPoolPath: The path of the initial pool. - getEmission: A function that returns the current emission to the staker contract. - getHalvingBlocksInRange: A function that returns a list of halving blocks within the interval \[start, end) in ascending order. Returns: - \*PoolTier: The new PoolTier instance.

NewPoolTierBy

calculatePoolReward

calculatePoolReward calculates the reward for a pool based on the emission, tier ratio, and tier count. Parameters: - emission: The emission for the pool. - tierRatio: The tier ratio for the pool. - tierCount: The tier count for the pool. Returns: - int64: The reward for the pool.

TickResolver

NewTickResolver

EncodeUint

EncodeUint converts a uint64 number into a zero-padded 20-character string. Parameters: - num (uint64): The number to encode. Returns: - string: A zero-padded string representation of the number. Example: Input: 12345 Output: "00000000000000012345"

EncodeInt64

DecodeUint

DecodeUint converts a zero-padded string back into a uint64 number. Parameters: - s (string): The zero-padded string. Returns: - uint64: The decoded number. Panics: - If the string cannot be parsed into a uint64. Example: Input: "00000000000000012345" Output: 12345

DecodeInt64

maxDurationOneYear

// 31,536,000 seconds

modifyWarmup

expected to be called by governance

instantiateWarmup

applyWarmup

applyWarmup applies the warmup to the rewards and calculate penalties.

safeAddTime

safeAddTime performs safe addition with overflow protection

ZERO_ADDRESS

Deposits

Deposits manages all staked positions.

NewDeposits

NewDeposits creates a new Deposits instance.

retrieveDeposit

retrieveDeposit safely casts data to Deposit type.

ExternalIncentives

ExternalIncentives manages external incentive programs.

NewExternalIncentives

NewExternalIncentives creates a new ExternalIncentives instance.

tokenHasLiquidity

tokenHasLiquidity checks if the target positionId has non-zero liquidity

getLiquidity

getTickOf

ExternalIncentiveResolver

NewExternalIncentiveResolver

NewExternalIncentive creates a new external incentive

DepositResolver

NewDepositResolver

poolPathDivide

poolPathDivide splits a pool path into token addresses and fee tier.

positionIdFrom

positionIdFrom converts a uint64 position ID to grc721.TokenID.

contains

contains checks if a string exists in a slice.