v1 state

TIMESTAMP_90DAYS

TIMESTAMP_180DAYS

TIMESTAMP_365DAYS

maxIncentiveStartDelay

MAX_UNIX_EPOCH_TIME

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

maxUnstakingFee

// 10%

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.

assertIsIncentiveOfPool

assertIsIncentiveOfDeposit ensures the incentive exists and targets the pool the position is staked in, so a caller cannot ask a deposit to collect an incentive that can never pay it. assertIsIncentiveOfPool ensures the incentive targets the pool the position is staked in.

assertHasNoExitCheckpoint

assertHasNoExitCheckpoint ensures the position carries no reward from a previous stake. Collecting it here would smuggle an unbounded calculation into staking, and leaving it would let the next unstake overwrite the checkpoint.

assertHasNoUncollectedIncentive

assertHasNoUncollectedIncentive ensures no unstaked position still owes a reward from this incentive, which has not been drawn down from it yet.

assertIsNotStaked

assertIsNotStaked ensures the position is not already staked.

assertIsPoolExists

assertIsPoolExists ensures the pool exists.

assertIsValidPoolTier

assertIsValidPoolTier ensures the tier is within valid range.

assertTier1HasSparePool

assertTier1HasSparePool ensures tier 1 keeps at least one pool after a tier change.

assertIsGreaterThanMinimumRewardAmount

assertIsGreaterThanMinimumRewardAmount ensures the reward amount meets minimum requirements.

assertIsAllowedForExternalReward

assertIsAllowedForExternalReward ensures the token is allowed for external rewards.

assertIsExternalRewardTokenAvailable

assertIsExternalRewardTokenAvailable ensures a pool has no unfinished incentive for the token.

assertIsValidFeeRate

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

assertIsValidIncentiveStartTime

assertIsValidIncentiveStartTime ensures the incentive starts at midnight no earlier than 24 hours after creation and no later than 7 days after the first eligible midnight.

assertIsAdminGovernanceOrCreator

assertIsAdminGovernanceOrCreator ensures the caller may act on an incentive: admin and governance are the protocol-level operators, and the creator is the address that funded the incentive in CreateExternalIncentive.

assertIsNotStartedIncentive

assertIsNotStartedIncentive ensures the incentive can still be cancelled, i.e. it has not started and nothing has been distributed from it. Only such an incentive may be removed outright; anything that already emitted rewards has to be finalized through EndExternalIncentive so the refund accounting and the penalty balance stay reachable.

getMinimumIncentiveStartTimestamp

getMinimumIncentiveStartTimestamp returns after 24 hours from now.

getMaximumIncentiveStartTimestamp

getMaximumIncentiveStartTimestamp returns 7 days after the first midnight that satisfies the minimum 24-hour delay.

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.

aggregateRewards

aggregateRewards sums the per-warmup rewards/penalties into a single Reward.

calculatePositionRewardParam

calculatePositionRewardParam is a struct for calculating position reward

positionRewardUpdate

positionRewardUpdate carries the persisted-state changes produced (but not applied) by a calculation. They are applied by the update\* functions, so that only the collect path mutates state while the calculation stays pure.

positionRewardContext

positionRewardContext carries the per-position state that both the internal (GNS emission) and the external (incentive) reward calculations need. Resolving it once lets each path be calculated on its own without duplicating the deposit/pool/reward-state setup.

internalRewardSegment

internalRewardSegment is a \[start, end) span over which the per-second emission reward rate is constant.

appendInternalRewardTailSegments

appendInternalRewardTailSegments appends the schedule for the tail \[startTime, endTime], where no persisted cache entry exists beyond startTime. Over this span tier/count are constant, so the rate changes only at halving boundaries.

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

errCannotCancelIncentive

errUncollectedPosition

errDeniedRewardToken

errCannotDenyDefaultToken

errInsufficientRewardTokenBalance

makeErrorWithDetails

tickCrossEventInfo

NewTickCrossEventInfo

NewTickCrossEventInfo captures the values emitted when a swap crosses a tick. Parameters: - tickID: Tick index crossed during the swap. - stakedLiquidityGross: Total staked liquidity at the crossed tick. - stakedLiquidityDelta: Net staked liquidity change applied at the crossed tick. - outsideAccumulation: Reward-ratio accumulation outside the crossed tick. Returns: - info: Event payload containing the supplied tick-cross values.

checkCannotAddDefaultToken

checkCannotRemoveDefaultToken

checkCannotDenyDefaultToken

cloneExternalIncentiveEntry

cloneExternalIncentiveEntry is the transformation for a pool's incentive tree. ExternalIncentive is mutable and its setters are declared in /r/gnoswap/staker, so an external holder of the stored pointer could write realm state through it.

rewardCacheEntry

rewardCacheEntry, accumulationEntry, and historicalTickEntry are the transformations for the UintTree-backed views. Their values are immutable scalars, so nothing needs copying; they type-check instead, which keeps the filtering the replaced slice getters did when an entry failed its cast.

accumulationEntry

historicalTickEntry

defaultDepositGnsAmount

defaultMinimumRewardAmount

defaultUnstakingFee

// 1%

init.81

registerStakerV1

initStoreData

initializePoolTier

initializePoolTier seeds the staker's pool tiering state on first init. The default pool is the canonical WUGNOT:GNS:3000 pool, sourced from the emission realm's DefaultInitialPoolTierPath constant so that the staker's tier-1 base pool is guaranteed to match the pool emission distributes to. When SetDistributionStartTime executes, emission distributes to this default pool and the staker uses the same path as the base tier-1 pool for reward accrual. Keeping both sides on emission's single constant structurally enforces that invariant and removes any risk of the two realms drifting apart on the canonical default pool identity.

stakerV1

NewStakerV1

NewStakerV1 constructs a version 1 staker implementation backed by the supplied accessors. Parameters: - stakerStore: Persistent storage accessor for pools, deposits, incentives, tier state, and reward bookkeeping. - poolAccessor: Accessor for pool state used while updating and resolving staked positions. - emissionAccessor: Accessor for GNS emission data used to calculate rewards. - nftAccessor: Accessor for the position NFT ownership and token operations. Returns: - staker: New stakerV1 implementation wired to the supplied store and accessors.

NOT_EMISSION_TARGET_TIER

pctToIndex

pctToIndex converts percentage to warmup index.

IncentivesResolver

IncentivesResolver returns a resolver over the pool's external-incentive state. Returns: - resolver: Incentives resolver backed by this pool's incentive tree and unclaimable periods.

NewIncentivesResolver

NewIncentivesResolver wraps the persisted external-incentive state for lookup and mutation. Parameters: - incentives: External incentive state containing the incentive tree and unclaimable periods. Returns: - resolver: Resolver backed by incentives.

retrieveIncentive

calculateUnClaimableDuration

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

q128

Pools

Pools represents the global pool storage

NewPools

NewPools creates an empty resolver for global pool storage. Returns: - pools: Pools resolver backed by a new B+ tree keyed by pool path.

PoolResolver

NewPoolResolver

NewPoolResolver wraps a pool's persisted reward, liquidity, tick, and incentive state for calculations. Parameters: - pool: Pool state to resolve. Returns: - resolver: Pool resolver backed by pool.

newPoolResolverWithExit

newPoolResolverWithExit builds a resolver that reads the pool through an exit checkpoint.

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

NewPoolTierBy reconstructs a PoolTier from persisted membership, ratios, counts, and callbacks. Parameters: - membership: Persisted pool-path-to-tier mapping. - tierRatio: Persisted reward-share ratio for each tier. - counts: Persisted number of pools in each tier index. - lastRewardCacheTimestamp: Timestamp through which reward caches have been materialized. - currentEmission: Emission rate currently used for reward accrual. - getEmission: Callback returning the current staker emission rate or an error. - getHalvingBlocksInRange: Callback returning halving timestamps and corresponding emissions in \[start, end). Returns: - \*PoolTier: Reconstructed tier manager using the supplied persisted state and callbacks.

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. - error: An invalid calculation input.

TickResolver

NewTickResolver

NewTickResolver wraps a staker tick to expose reward-accumulation updates. Parameters: - tick: Staker tick whose state is resolved. Returns: - \*TickResolver: Resolver backed by tick.

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. Returns: - deposits: Empty deposit collection backed by a position-ID tree.

retrieveDeposit

retrieveDeposit safely casts data to Deposit type.

ExternalIncentives

ExternalIncentives manages external incentive programs.

NewExternalIncentives

NewExternalIncentives creates a new ExternalIncentives instance. Returns: - incentives: Empty external-incentive collection backed by an incentive-ID tree.

stakeScanLowerBound

stakeScanLowerBound returns the lower bound of the stake-time incentive scan window, clamped to 0. The start-time index encodes keys as unsigned, so a negative bound aborts when the chain time is under TIMESTAMP\_365DAYS.

collectContext

collectContext carries the values every reward delivery of one collect call shares: the deposit being collected, the collect timestamp and height, the caller identity used in events, and the accumulator snapshot emitted with every collect event. Resolving it once is what keeps a collect-everything call at a single snapshot: the emission delivery and each incentive delivery all read the same context.

externalDeliveryOutcome

externalDeliveryOutcome is what deliverExternalIncentiveReward did with one incentive. The checkpoint bookkeeping keys off it instead of re-deriving the decision from incentive state, which a permissionless re-entering collect may already have changed.

externalDeliveryPaid

externalDeliveryNothingOwed

externalDeliveryAlreadyDelivered

externalDeliveryDeferred

externalDeliveryUnpayable

collectTarget

collectTarget is the record a collect runs against: the live deposit while staked, or the exit checkpoint an unstake left behind.

tokenHasLiquidity

tokenHasLiquidity checks if the target positionId has non-zero liquidity

getLiquidity

getTickOf

ExternalIncentiveResolver

NewExternalIncentiveResolver

NewExternalIncentiveResolver wraps an external incentive with resolver operations. Parameters: - externalIncentive: External incentive whose timestamps and accounting state the resolver exposes. Returns: - resolver: Resolver backed by externalIncentive.

DepositResolver

NewDepositResolver

NewDepositResolver wraps a deposit with reward-cursor and warmup resolution helpers. Parameters: - deposit: Deposit whose persisted reward state should be resolved. Returns: - resolver: Resolver backed by deposit.

UnstakedPositions

UnstakedPositions manages exit checkpoints.

NewUnstakedPositions

NewUnstakedPositions creates a new UnstakedPositions instance. Returns: - \*UnstakedPositions: Empty exit-checkpoint manager backed by a new B+ tree.

addUncollectedIncentiveCountTo

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.