staker state

PoolAccessor

poolAccessor

newPoolAccessor

EmissionAccessor

emissionAccessor

newEmissionAccessor

NFTAccessor

gnftAccessor

newNFTAccessor

Counter

NewCounter

NewCounter creates a counter initialized at zero. Returns: - counter: Counter whose next generated identifier is 1.

Deposit

Deposit returns the deposit snapshot captured when this position was unstaked. Returns: - deposit: Stored deposit state, including its owner, pool, liquidity, ticks, warmups, and collected reward fields.

NewDeposit

NewDeposit creates a deposit for a staked LP position and initializes its reward cursors and maps. Parameters: - owner: Address that owns the staked position. - targetPoolPath: Pool identifier associated with the position. - liquidity: LP liquidity amount represented by the position. - currentTime: Staking and initial reward-cursor time in Unix seconds. - tickLower: Lower signed tick boundary of the position's range. - tickUpper: Upper signed tick boundary of the position's range. - warmups: Warmup schedule to apply to this position's rewards. Returns: - deposit: Newly initialized deposit containing the supplied position and warmup state.

Warmup

NewWarmup

NewWarmup creates one warmup tier. Parameters: - timeDuration: Duration of this tier in seconds. - nextWarmupTime: Unix timestamp at which this tier ends. - warmupRatio: Percentage of the calculated reward credited to the position, from 0 to 100. Returns: - warmup: Warmup tier initialized with the supplied duration, end time, and ratio.

DefaultWarmupTemplate

DefaultWarmupTemplate returns the built-in four-tier warmup schedule. Returns: - warmups: Template with 5-day, 10-day, 30-day, and final-unbounded tiers using 30%, 50%, 70%, and 100% ratios; NextWarmupTime values are zero until instantiated.

GNS_PATH

WUGNOT_PATH

DefaultAllowedTokens

DefaultAllowedTokens returns the token paths accepted by the staker's default configuration. Returns: - tokenPaths: Slice containing the GNS and wrapped-GNOT token paths.

GetPool

GetPool returns a copy of the staking state for a pool. Parameters: - poolPath: pool realm path Returns: - pool: independent pool copy, or nil when an implementation has no pool value - err: implementation resolution error; the current v1 implementation returns not-found for a missing pool

GetDeposit

GetDeposit returns a copy of a staked position's deposit. Parameters: - lpTokenId: staked position NFT token ID Returns: - deposit: independent deposit copy, or nil when an implementation has no deposit value - err: implementation resolution error; the current v1 implementation returns not-found for a missing deposit

CollectableEmissionReward

CollectableEmissionReward returns the claimable internal GNS reward for a live staked deposit or an exit checkpoint left by UnStakeToken. Parameters: - positionId: staked position NFT token ID or position with an exit checkpoint Returns: - amount: claimable internal reward amount - err: non-nil when positionId cannot be resolved

CollectableExternalIncentiveReward

CollectableExternalIncentiveReward returns a position's claimable external reward for a live staked deposit or an exit checkpoint left by UnStakeToken. Parameters: - positionId: staked position NFT token ID or position with an exit checkpoint - incentiveId: external incentive identifier Returns: - amount: claimable external reward amount - err: non-nil when the position or incentive cannot be resolved

GetCreatedHeightOfIncentive

GetCreatedHeightOfIncentive returns an incentive's creation block height. Parameters: - poolPath: pool realm path - incentiveId: external incentive identifier Returns: - height: creation block height - err: non-nil when the incentive cannot be resolved

GetIncentiveCreatedTimestamp

GetIncentiveCreatedTimestamp returns an incentive's creation timestamp. Parameters: - poolPath: pool realm path - incentiveId: external incentive identifier Returns: - timestamp: creation Unix timestamp - err: non-nil when the incentive cannot be resolved

GetIncentiveTotalRewardAmount

GetIncentiveTotalRewardAmount returns the total reward amount of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: Total reward amount configured when the incentive was created, in token units. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveDistributedRewardAmount

GetIncentiveDistributedRewardAmount returns the distributed reward amount of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: Reward amount already delivered to positions or refunded at incentive end, in token units. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveRemainingRewardAmount

GetIncentiveRemainingRewardAmount returns the remaining reward amount of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: Mutable reward balance remaining after distributions and refunds, in token units. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveAccumulatedPenaltyAmount

GetIncentiveAccumulatedPenaltyAmount returns the accumulated warmup penalty amount of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: Warmup penalty accumulated from collections for the incentive, in reward-token units. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveDepositGnsAmount

GetIncentiveDepositGnsAmount returns the deposited GNS amount of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: GNS deposit locked by the incentive, in token units. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveRefunded

GetIncentiveRefunded returns whether an incentive has been refunded. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - refunded: True when the incentive has been finalized as refunded; false while it remains open. - err: Non-nil when poolPath or incentiveId cannot be resolved.

IsIncentiveActive

IsIncentiveActive reports whether an unrefunded incentive is active, including both start and end timestamps. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - active: True when the current Unix time is within the incentive window and it has not been refunded. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetDepositExternalRewardLastCollectTimestamp

GetDepositExternalRewardLastCollectTimestamp returns the last external reward collection time for a position and incentive. For a newly tracked incentive, the value is based on the stake timestamp. Parameters: - lpTokenId: Position NFT token ID whose external reward cursor should be read. - incentiveId: External incentive identifier whose collection cursor should be read. Returns: - timestamp: Unix timestamp of the last collection cursor; newly tracked incentives use the deposit's stake time. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositGnsAmount

GetDepositGnsAmount retrieves the GNS reserve amount deposited for the staker. Returns: - int64: Stored GNS reserve amount; panics on read or type failure.

GetDepositInternalRewardLastCollectTimestamp

GetDepositInternalRewardLastCollectTimestamp returns the last internal reward collection time for a position. Parameters: - lpTokenId: Position NFT token ID whose internal reward cursor should be read. Returns: - timestamp: Unix timestamp of the deposit's last internal reward collection. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositCollectedInternalReward

GetDepositCollectedInternalReward returns the collected internal reward amount of a position. Parameters: - lpTokenId: Position NFT token ID whose collected internal reward should be read. Returns: - amount: Internal GNS reward amount already recorded as collected, in token units. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositCollectedExternalReward

GetDepositCollectedExternalReward returns the collected external reward amount of a position. Parameters: - lpTokenId: Position NFT token ID whose collected reward should be read. - incentiveId: External incentive identifier whose collected amount should be read. Returns: - amount: External reward amount already recorded as collected for the incentive, in token units. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositLiquidity

GetDepositLiquidity returns the liquidity amount of a staked position. Parameters: - lpTokenId: Position NFT token ID whose liquidity should be read. Returns: - liquidity: Independent uint256 copy of the deposit's liquidity amount. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositLiquidityAsString

GetDepositLiquidityAsString returns the liquidity amount of a staked position as a decimal string. Parameters: - lpTokenId: Position NFT token ID whose liquidity should be formatted. Returns: - liquidity: Decimal representation of the deposit's uint256 liquidity amount. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositOwner

GetDepositStakeTime

GetDepositStakeTime returns the Unix timestamp at which a position was staked. Parameters: - lpTokenId: Position NFT token ID whose stake time should be read. Returns: - stakeTime: Unix timestamp recorded when the deposit entered staking. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositTargetPoolPath

GetDepositTargetPoolPath returns the pool path of a staked position. Parameters: - lpTokenId: Position NFT token ID whose target pool should be read. Returns: - poolPath: Pool path stored on the deposit. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositTickLower

GetDepositTickLower returns the lower tick of a staked position. Parameters: - lpTokenId: Position NFT token ID whose lower boundary should be read. Returns: - tickLower: Lower price-range tick stored on the deposit. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositTickUpper

GetDepositTickUpper returns the upper tick of a staked position. Parameters: - lpTokenId: Position NFT token ID whose upper boundary should be read. Returns: - tickUpper: Upper price-range tick stored on the deposit. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositWarmUp

GetDepositWarmUp returns the warmup records of a staked position. Parameters: - lpTokenId: Position NFT token ID whose warmup schedule should be inspected. Returns: - warmups: Independent copy of the deposit's warmup records. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetDepositExternalIncentiveIdList

GetDepositExternalIncentiveIdList returns external incentive IDs tracked by a deposit. Parameters: - lpTokenId: Position NFT token ID whose deposit should be inspected. Returns: - incentiveIds: Independent copy of external incentive IDs associated with the deposit. - err: Non-nil when lpTokenId does not resolve to a stored deposit.

GetExternalIncentiveByPoolPath

GetExternalIncentiveByPoolPath returns all external incentives for a pool. Parameters: - poolPath: Pool path whose external incentives should be listed. Returns: - incentives: Independent copies of incentives targeting poolPath. - err: Non-nil when stored incentive data cannot be read or cast.

GetIncentiveEndTimestamp

GetIncentiveEndTimestamp returns the end timestamp of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - endTimestamp: Incentive end time as a Unix timestamp. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveCreator

GetIncentiveRewardAmount

GetIncentiveRewardAmount returns the remaining reward amount of an incentive, after deliveries and refunds represented by the current incentive state. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: Independent uint256 copy of the incentive's mutable remaining reward amount. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveRewardAmountAsString

GetIncentiveRewardAmountAsString returns the remaining reward amount of an incentive as string. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - amount: Decimal string for the incentive's remaining reward amount after deliveries and refunds. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveRewardPerSecondX128

GetIncentiveRewardPerSecondX128 returns the reward rate per second of an incentive, expressed as a Q128 fixed-point number (i.e. actual rate = value / 2^128). Callers needing an integer rate can right-shift the result by 128. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - rateX128: Clone of the Q128-scaled reward rate; divide by 2^128 to recover the actual token units per second. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveRewardToken

GetIncentiveRewardToken returns the reward token of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - tokenPath: Reward-token path configured for the incentive. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetIncentiveStartTimestamp

GetIncentiveStartTimestamp returns the start timestamp of an incentive. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - startTimestamp: Incentive start time as a Unix timestamp. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetMinimumRewardAmount

GetMinimumRewardAmount retrieves the default minimum external reward amount. Returns: - int64: Stored default minimum reward amount; panics on read or type failure.

GetMinimumRewardAmountForToken

GetMinimumRewardAmountForToken returns the minimum reward amount for a specific token. Parameters: - tokenPath: Token path whose configured minimum-reward override should be read. Returns: - amount: Token-specific minimum reward amount when configured, otherwise the default minimum, in token units.

GetPoolStakedLiquidity

GetPoolStakedLiquidity returns the current total staked liquidity of a pool. Parameters: - poolPath: Pool path whose current staked liquidity should be read. Returns: - liquidity: Decimal string containing the pool's total staked liquidity at the current time. - err: Non-nil when poolPath does not resolve to a pool.

GetPoolsByTier

GetPoolsByTier returns the pool list for a tier. Parameters: - tier: Emission tier identifier whose current pool memberships should be listed. Returns: - poolPaths: Copy of pool paths currently assigned to tier; tier zero yields an empty list. - err: Non-nil when the stored tier membership contains an invalid value.

GetPoolReward

GetPoolReward returns the reward amount for a tier. Parameters: - tier: Emission tier identifier for which to retrieve the per-pool reward. Returns: - reward: Current per-pool GNS reward rate for tier, in token units per second. - err: Non-nil when tier is outside the valid range 1 through AllTierCount-1.

GetPoolTier

GetPoolTier returns the tier of a pool. Parameters: - poolPath: Pool path whose current emission tier should be read. Returns: - tier: Current emission tier identifier; zero when the pool has no tier assignment.

GetPoolTierCount

GetPoolTierCount returns the number of pools in a tier. Parameters: - tier: Emission tier identifier to count; tier zero has no pools. Returns: - count: Number of pools currently assigned to tier, or zero for tier zero.

GetPoolTierRatio

GetPoolTierRatio retrieves the configured pool-tier reward-share ratio. Returns: - TierRatio: Stored ratio distribution across tiers; panics on read or type failure.

GetSpecificTokenMinimumRewardAmount

GetSpecificTokenMinimumRewardAmount returns the explicitly set minimum reward amount for a token. Parameters: - tokenPath: Token path whose explicit minimum-reward override should be read. Returns: - amount: Explicit minimum reward amount in token units, or 0 when no override is configured. - found: True when tokenPath has an explicit override; false when the default would be used.

GetTargetPoolPathByIncentiveId

GetTargetPoolPathByIncentiveId returns the pool path for an incentive ID. Parameters: - poolPath: Pool path containing the incentive record. - incentiveId: External incentive identifier to resolve. Returns: - targetPoolPath: Pool path stored on the resolved incentive. - err: Non-nil when poolPath or incentiveId cannot be resolved.

GetUnstakingFee

GetUnstakingFee retrieves the configured unstaking fee rate. Returns: - uint64: Stored unstaking fee rate in basis points; panics on read or type failure.

HasUnstakedPosition

HasUnstakedPosition returns whether a position was unstaked with rewards left to collect. Parameters: - positionId: Position NFT token ID to check in the unstaked-position tree. Returns: - unstaked: True when positionId has an exit checkpoint awaiting collection; false otherwise.

GetUnstakedPositionExitTime

GetUnstakedPositionExitTime returns the timestamp at which an unstaked position stopped accruing rewards. Parameters: - positionId: Position NFT token ID identifying the unstaked exit checkpoint. Returns: - exitTime: Unix timestamp pinned as the end of the position's reward-accrual window. - err: Non-nil when positionId has no unstaked checkpoint with uncollected rewards.

GetUnstakedPositionPendingIncentives

GetUnstakedPositionPendingIncentives returns the incentives an unstaked position has yet to collect. Parameters: - positionId: Position NFT token ID identifying the unstaked exit checkpoint. Returns: - incentiveIds: Copy of external incentive IDs still pending for the exit checkpoint. - err: Non-nil when positionId has no unstaked checkpoint with uncollected rewards.

GetUncollectedIncentiveCount

GetUncollectedIncentiveCount returns how many unstaked positions still owe a reward from the incentive. Parameters: - incentiveId: External incentive identifier whose outstanding exit positions should be counted. Returns: - count: Number of unstaked positions with an uncollected reward for incentiveId.

IsStaked

IsStaked returns whether a position is staked. Parameters: - positionId: Position NFT token ID to check in the active deposit tree. Returns: - staked: True when positionId has an active deposit; false for an unstaked or unknown position.

GetTotalEmissionSent

GetTotalEmissionSent retrieves the cumulative emission amount sent. Returns: - int64: Stored cumulative emission amount; panics on read or type failure.

GetAllowedTokens

GetAllowedTokens retrieves a clone of the allowed external-reward token list. Returns: - \[]string: Allowed token paths copied for the caller; panics on read or type failure.

GetDeniedRewardTokens

GetDeniedRewardTokens retrieves the denied-reward list, treating a missing key as empty. Returns: - \[]string: Clone of denied reward-token paths; empty when the key is absent, and panics on read or type failure.

GetWarmupTemplate

GetWarmupTemplate retrieves a clone of the stored warmup schedule. Returns: - \[]Warmup: Warmup entries copied into the caller's realm; panics on read or type failure.

GetPoolRewardCaches

GetPoolRewardCaches returns a read-only view of a pool's reward cache, keyed by the encoded block timestamp. Callers paginate it themselves through IterateByOffset and decode keys with DecodeInt64. Parameters: - poolPath: Pool path whose reward-cache checkpoints should be read. Returns: - caches: Read-only tree of timestamp keys to cached reward values, or nil when poolPath has no pool.

GetPoolIncentives

GetPoolIncentives returns a read-only view of a pool's external incentives, keyed by incentive ID. Reading an entry yields a clone, so the view cannot mutate realm state. Parameters: - poolPath: Pool path whose external-incentive records should be read. Returns: - incentives: Read-only tree keyed by incentive ID with cloned entries, or nil when poolPath has no pool.

GetPoolGlobalRewardRatioAccumulations

GetPoolGlobalRewardRatioAccumulations returns a read-only view of a pool's global reward ratio accumulation, keyed by the encoded block timestamp. Parameters: - poolPath: Pool path whose global reward-ratio checkpoints should be read. Returns: - accumulations: Read-only tree of timestamp keys to stored accumulation values, or nil when poolPath has no pool.

GetPoolHistoricalTicks

GetPoolHistoricalTicks returns a read-only view of a pool's historical ticks, keyed by the encoded block timestamp with the int32 tick as the value. Parameters: - poolPath: Pool path whose historical tick checkpoints should be read. Returns: - ticks: Read-only tree of timestamp keys to int32 ticks, or nil when poolPath has no pool.

GetPendingProtocolFees

GetPendingProtocolFees retrieves pending protocol fee amounts keyed by token path. Returns: - map\[string]int64: Stored token-to-fee map; panics on read or type failure.

cloneStringSlice

cloneStringInt64Map

cloneStringBoolMap

cloneExternalIncentives

cloneWarmups

AllTierCount

// 0, 1, 2, 3

Pool

Pool is a struct for storing an incentivized pool information Each pool stores Incentives and Ticks associated with it. Fields: - poolPath: The path of the pool. - stakedLiquidity: The current total staked liquidity of the in-range positions for the pool. Updated when tick cross happens or stake/unstake happens. Used to calculate the global reward ratio accumulation or decide whether to enter/exit unclaimable period. - lastUnclaimableTime: The time at which the unclaimable period started. Set to 0 when the pool is not in an unclaimable period. - unclaimableAcc: The accumulated undistributed unclaimable reward. Reset to 0 when processUnclaimableReward is called and sent to community pool. - rewardCache: The cached per-second reward emitted for this pool. Stores new entry only when the reward is changed. PoolTier.cacheReward() updates this. \- incentives: The external incentives associated with the pool. \- ticks: The Ticks associated with the pool. - globalRewardRatioAccumulation: Global ratio of Time / TotalStake accumulation(since the pool creation) Stores new entry only when tick cross or stake/unstake happens. It is used to calculate the reward for a staked position at certain time. - historicalTick: The historical tick for the pool at a given time. It does not reflect the exact tick at the timestamp, but it provides correct ordering for the staked position's ticks. Therefore, you should not compare it for equality, only for ordering. Set when tick cross happens or a new position is created.

NewPool

NewPool creates pool reward state initialized at currentTime (Unix seconds). Parameters: - poolPath: Pool identifier to store in the new reward-state object. - currentTime: Unix timestamp in seconds used to seed the initial accumulation, reward-cache, and liquidity snapshots. Returns: - pool: Initialized pool with empty backing structures and zero initial reward/liquidity snapshots at currentTime.

Incentives

Incentives represents a collection of external incentives for a specific pool. Fields: - incentives: BPTree storing ExternalIncentive objects indexed by incentiveId The incentiveId serves as the key to efficiently lookup incentive details - targetPoolPath: String identifier for the pool this incentive collection belongs to Used to associate incentives with their corresponding liquidity pool - unclaimablePeriods: Tree storing periods when rewards cannot be claimed Maps start timestamp (key) to end timestamp (value) An end timestamp of 0 indicates an ongoing unclaimable period Used to track intervals when staking rewards are not claimable - byStartTime: Per-pool start-time index mapping an incentive's start timestamp (key) to the incentive IDs that start at that timestamp (value). This mirrors the lazy-discovery lookup previously served by a global creation-time index, but scoped to this pool's own incentives, so discovery cost is bounded by this pool's incentives instead of growing with the total number of incentives system-wide.

NewIncentives

NewIncentives creates an incentive collection for a pool and starts an open unclaimable period at the current time. Parameters: - targetPoolPath: Pool path to associate with the new incentive collection. Returns: - incentives: Collection with initialized incentive, start-time, and unclaimable-period trees.

ExternalIncentive

NewExternalIncentive

NewExternalIncentive creates a new external incentive Parameters: - incentiveId: Unique identifier assigned to the external incentive. - targetPoolPath: Pool path whose staked positions may receive this incentive. - rewardToken: Token path of the asset deposited for distribution. - rewardAmount: Total reward amount, also used as the initial remaining reward balance. - startTimestamp: Unix timestamp in seconds when reward distribution starts. - endTimestamp: Unix timestamp in seconds when reward distribution ends; duration is endTimestamp-startTimestamp and must be nonzero for the rate calculation. - creator: Address that funds the incentive and receives refunds at finalization. - depositGnsAmount: GNS amount deposited as the incentive's required collateral. - createdHeight: Block height to record for incentive creation. - currentTime: Unix timestamp in seconds recorded as the incentive creation time. Returns: - incentive: New incentive with a Q128-scaled per-second rate and zeroed distribution, penalty, and unclaimable counters.

Ticks

Tick mapping for each pool

NewTicks

NewTicks creates an empty tick mapping with a fanout-16 B+ tree. Returns: - ticks: Empty Ticks value ready to store pool tick records.

Tick

Tick represents the state of a specific tick in a pool. Fields: - id (int32): The ID of the tick. - stakedLiquidityGross (\*u256.Uint): Total gross staked liquidity at this tick. - stakedLiquidityDelta (\*i256.Int): Net change in staked liquidity at this tick. - outsideAccumulation (\*UintTree): RewardRatioAccumulation outside the tick.

NewTick

NewTick creates a tick with zero staked liquidity and an empty fanout-4 outside-accumulation tree. Parameters: - tickId: Tick index to assign to the new record. Returns: - tick: Initialized tick record.

TierRatio

100%, 0%, 0% if no tier2 and tier3 80%, 0%, 20% if no tier2 70%, 30%, 0% if no tier3 50%, 30%, 20% if has tier2 and tier3

NewTierRatio

NewTierRatio constructs the reward-share ratio for tiers 1 through 3. Parameters: - tier1: Tier-1 share scaled by 100 (for example, 70 means 70%). - tier2: Tier-2 share scaled by 100. - tier3: Tier-3 share scaled by 100. Returns: - ratio: TierRatio containing the supplied scaled shares.

SwapBatchProcessor

SwapBatchProcessor processes tick crosses in batch for a swap This processor accumulates all tick crosses that occur during a single swap and processes them together at the end, reducing redundant calculations and state updates that would occur with individual tick processing

NewSwapBatchProcessor

NewSwapBatchProcessor creates an active batch for collecting tick crosses in a pool swap. Parameters: - poolPath: Pool identifier associated with the swap. - pool: Pool state whose tick crosses are being collected. - timestamp: Unix timestamp in seconds when the swap began. Returns: - processor: Active processor with an empty cross sequence.

SwapTickCross

SwapTickCross stores information about a tick cross during a swap This struct is used to accumulate tick cross events during a single swap transaction for batch processing to optimize gas usage and computational efficiency

NewSwapTickCross

NewSwapTickCross creates a tick-cross record for a swap batch. Parameters: - tickID: Index of the tick crossed during the swap. - zeroForOne: Swap direction; true means token0-to-token1 and false means token1-to-token0. - delta: Precomputed signed staked-liquidity change for this tick cross. Returns: - cross: Tick-cross record containing the supplied index, direction, and delta.

StakeToken

StakeToken stakes a position NFT to earn rewards. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - positionId: LP position NFT token ID to stake. - referrer: Optional referral address string used for referral tracking. Returns: - string: Pool path where the position was staked. Halt check: reverts while the Staker halt scope is active.

UnStakeToken

UnStakeToken unstakes a position NFT and creates an exit checkpoint for its rewards. The NFT is returned to its owner without calculating or paying rewards. Use a Collect\* entry point afterward; collection of an exit checkpoint is permissionless and pays its pinned owner. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - positionId: LP position NFT token ID to unstake. Returns: - string: Pool path where the position was staked. Halt check: reverts while the Withdraw halt scope is active.

CollectReward

CollectReward collects both the GNS emission and external incentive rewards for a live staked deposit or an exit checkpoint left by UnStakeToken. A live-deposit collect requires the depositor/owner. An exit-checkpoint collect is permissionless and pays the owner pinned in the checkpoint. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - positionId: Staked position NFT token ID or position with an exit checkpoint. Returns: - string: GNS emission amount sent to the user. - string: GNS emission penalty amount sent to the community pool. - map\[string]int64: Gross external reward amount per reward token, before the staking-reward fee. - map\[string]int64: External penalty amount per reward token. Halt check: reverts while the Withdraw halt scope is active.

CollectEmissionReward

CollectEmissionReward collects only the GNS emission reward for a live staked deposit or an exit checkpoint left by UnStakeToken. A live-deposit collect requires the depositor/owner. An exit-checkpoint collect is permissionless and pays the owner pinned in the checkpoint. External incentive rewards keep accruing; collect them with CollectExternalIncentiveReward. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - positionId: Staked position NFT token ID or position with an exit checkpoint. Returns: - int64: GNS emission amount sent to the user. - int64: GNS emission penalty amount sent to the community pool. Halt check: reverts while the Withdraw halt scope is active.

CollectExternalIncentiveReward

CollectExternalIncentiveReward collects one external incentive reward for a live staked deposit or an exit checkpoint left by UnStakeToken. A live-deposit collect requires the depositor/owner. An exit-checkpoint collect is permissionless and pays the owner pinned in the checkpoint. The GNS emission reward and every other incentive keep accruing; collect the emission reward with CollectEmissionReward and the other incentives by calling this with their own incentive id. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - positionId: Staked position NFT token ID or position with an exit checkpoint. - incentiveId: External incentive identifier to collect. Returns: - int64: Gross reward amount before the staking-reward fee. - int64: Penalty amount retained by the incentive. Halt check: reverts while the Withdraw halt scope is active.

SetPoolTier

SetPoolTier assigns a pool to an internal GNS emission reward tier. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - poolPath: Pool path whose emission tier is assigned. - tier: Target tier number from 0 through 3; zero removes the pool from emission targeting. Halt check: reverts while the Staker halt scope is active.

ChangePoolTier

ChangePoolTier changes the internal GNS emission tier assigned to a pool. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - poolPath: Pool path whose emission tier is changed. - tier: New tier number from 0 through 3; zero means no internal-emission target. Halt check: reverts while the Staker halt scope is active.

RemovePoolTier

RemovePoolTier removes a pool from the internal GNS emission tier system. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - poolPath: Pool path to remove from emission-tier membership. Halt check: reverts while the Staker halt scope is active.

CreateExternalIncentive

CreateExternalIncentive creates an external reward incentive for a pool. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - targetPoolPath: Pool path whose liquidity providers will receive the incentive. - rewardToken: Registered token path used to pay the incentive. - rewardAmount: Total reward amount deposited, in reward-token units. - startTimestamp: Incentive start time as an inclusive Unix timestamp. - endTimestamp: Incentive end time as an inclusive Unix timestamp. Any caller may create an incentive after satisfying the token, duration, start-time, reward-minimum, and GNS-deposit checks. Halt check: reverts while the Staker halt scope is active.

EndExternalIncentive

EndExternalIncentive finalizes an external incentive once its end timestamp has passed, sending the unclaimable/remainder reward portion and GNS deposit to the explicit refundAddress. Only the incentive creator or admin may call it; an outstanding exit checkpoint for this incentive must be collected or forfeited first. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - targetPoolPath: Pool path containing the incentive. - incentiveId: Unique incentive identifier to finalize. - refundAddress: Address receiving the refundable reward tokens and GNS deposit. Halt check: reverts while the Withdraw halt scope is active.

CancelExternalIncentive

CancelExternalIncentive cancels an external incentive that has not started yet, removing it and refunding the reward tokens and the GNS deposit to the creator. Callable by admin, governance, or the incentive creator. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - targetPoolPath: Pool path containing the incentive. - incentiveId: Unique incentive identifier to cancel. Halt check: reverts while the Withdraw halt scope is active.

CollectExternalIncentivePenalty

CollectExternalIncentivePenalty collects accumulated warm-up penalties after EndExternalIncentive has finalized the incentive, sending them to refundAddress. Only the incentive creator or admin may call it. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - targetPoolPath: Pool path containing the incentive. - incentiveId: Unique incentive identifier whose penalty is collected. - refundAddress: Address receiving the collected penalty amount. Returns: - int64: Penalty amount transferred, capped by the staker's available reward-token balance. Halt check: reverts while the Withdraw halt scope is active.

AddToken

AddToken adds a token to the reward token whitelist. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - tokenPath: Registered token path to add to the allowed reward-token list. Halt check: reverts while the Staker halt scope is active.

RemoveToken

RemoveToken removes a token from the reward token whitelist. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - tokenPath: Token path to remove from the allowed reward-token list. Halt check: reverts while the Staker halt scope is active.

SetDeniedRewardToken

SetDeniedRewardToken sets or clears the operational deny flag for an external incentive reward token. Pool-pair tokens qualify as reward tokens without the governance allowlist (by design), so this flag is the only lever to stop NEW incentives in a pair token whose issuer turned hostile. Existing incentives and their collection are deliberately unaffected; the ledger-level delivery guard in the implementation bounds their blast radius instead. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - tokenPath: Reward-token path whose deny status is changed. - denied: True to block new incentives for tokenPath; false to clear that block. Halt check: reverts while the Staker halt scope is active.

SetWarmUp

SetWarmUp configures the duration for the warm-up tier selected by its fixed ratio. Finite tiers are capped at 365 days; the final 100% tier must retain math.MaxInt64. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - pct: Warm-up payout percentage selecting one of the 30%, 50%, 70%, or 100% tiers. - timeDuration: Warm-up duration in Unix seconds for the selected percentage tier; finite tiers are capped at 365 days and the 100% tier uses math.MaxInt64. Halt check: reverts while the Staker halt scope is active.

SetDepositGnsAmount

SetDepositGnsAmount stores the GNS amount deposited as the staker reserve. Parameters: - \_: Leading realm-call discriminator for the forwarded store call; callers pass 0. - rlm: Current staker realm context; it must be current before storage is written. - amount: GNS reserve amount used for staker initialization and accounting. Returns: - error: ErrSpoofedRealm when rlm is not current, or the underlying KV-store write error; nil on success.

SetMinimumRewardAmount

SetMinimumRewardAmount stores the default minimum external reward amount. Parameters: - \_: Leading realm-call discriminator for the forwarded store call; callers pass 0. - rlm: Current staker realm context; it must be current before storage is written. - amount: Default minimum reward amount applied when no token-specific override exists. Returns: - error: ErrSpoofedRealm when rlm is not current, or the underlying KV-store write error; nil on success.

SetTokenMinimumRewardAmount

SetTokenMinimumRewardAmount sets minimum reward amounts per token. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - paramsStr: Colon-delimited token path and minimum amount (\`tokenPath:amount\`); amount zero removes the override. Halt check: reverts while the Staker halt scope is active.

SetUnStakingFee

SetUnStakingFee sets the unstaking fee rate in basis points (0-1,000; 100 = 1%). Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - fee: Unstaking fee rate in basis points, from 0 through 1,000 inclusive. Halt check: reverts while the Staker halt scope is active.

Render

Render delegates web rendering to the active implementation.

ErrSpoofedRealm

kvStore

versionManager

implementation

init.126

initRegisterWritableContract

initializeDomainStore

getImplementation

updateImplementation

StoreKey

StoreKeyDepositGnsAmount

StoreKeyMinimumRewardAmount

StoreKeyDeposits

StoreKeyExternalIncentives

StoreKeyTotalEmissionSent

StoreKeyAllowedTokens

StoreKeyDeniedRewardTokens

StoreKeyIncentiveCounter

StoreKeyTokenSpecificMinimumRewards

StoreKeyUnstakingFee

StoreKeyPendingProtocolFees

StoreKeyUnstakedPositions

StoreKeyUncollectedIncentiveCounts

StoreKeyPools

StoreKeyPoolTierMemberships

StoreKeyPoolTierRatio

StoreKeyPoolTierCounts

StoreKeyPoolTierLastRewardCacheTimestamp

StoreKeyPoolTierCurrentEmission

StoreKeyPoolTierGetEmission

StoreKeyPoolTierGetHalvingBlocksInRange

StoreKeyWarmupTemplate

StoreKeyCurrentSwapBatch

stakerStore

NewStakerStore

NewStakerStore creates a new staker store instance with the provided KV store. This function is used by the upgrade system to create storage instances for each implementation. Parameters: - kvStore: Key-value store used for all staker state. Returns: - IStakerStore: Store interface backed by the supplied KV store.

makeIncentiveID

contains

UintTree

UintTree wraps a B+ tree with nonnegative int64 timestamp keys, encoded as fixed-width 8-byte big-endian strings to preserve numeric ordering. Methods: - Get: Retrieves a value associated with an int64 key. - Set: Stores a value with an int64 key. - Has: Checks if an int64 key exists in the tree. - Remove: Removes an int64 key and its associated value. - Iterate: Iterates over keys and values in a range. - ReverseIterate: Iterates in reverse order over keys and values in a range.

NewBPTreeN

NewBPTreeN allocates a raw BP-tree under /r/gnoswap/staker's realm context (the realm that declares Pool/Deposit/ExternalIncentive). The tree's PkgID is therefore /r/gnoswap/staker, matching the domain values it stores, so tree.Set leaf-slot writes clear the readonly-taint gate regardless of which realm (staker/v1, mock) calls Set (borrow rule #2 borrows m.Realm to the tree's owning realm). Implementations and mocks must allocate trees that hold /r/gnoswap/staker-declared values through here rather than calling bptree.NewBPTreeN directly in their own realm. Parameters: - fanout: Number of child pointers per B+ tree node; controls the tree's branching factor. Returns: - tree: Mutable raw B+ tree allocated in the staker realm context.

NewUintTree

NewUintTree creates a new UintTree instance with default fanout 64. Returns: - tree: Empty UintTree using the default fanout of 64.

NewUintTreeN

NewUintTreeN creates a new UintTree instance with the specified fanout. Parameters: - fanout: Number of child pointers per B+ tree node used by the wrapped tree. Returns: - tree: Empty UintTree configured with the requested fanout.

encodeInt64

decodeInt64

IStaker

IStakerManager

IStakerGetter

IStakerStore

UnstakedPosition

UnstakedPosition is the exit checkpoint of a position that left the pool before collecting. It pins the pool state a later collect must reproduce the exit-time reward from: the tick observed at the exit, the two boundary ticks (which the unstake may prune from the pool), and the tier context (which a later tier change would otherwise re-rate the window with). Collection is per source, so the checkpoint tracks what is left and is dropped when nothing is.

NewUnstakedPosition

NewUnstakedPosition creates an exit checkpoint owing every reward source of the deposit. Parameters: - deposit: Deposit state captured when the position leaves the pool. - exitTime: Unix timestamp when staking ended and this checkpoint's reward window stopped. - exitTick: Pool tick observed at exitTime for reconstructing in-range rewards. - lowerTick: Snapshot of the position's lower boundary tick, retained if the live pool prunes it. - upperTick: Snapshot of the position's upper boundary tick, retained if the live pool prunes it. - lowerOutsideAcc: Decimal-encoded outside reward-ratio accumulation of the lower tick at exitTime. - upperOutsideAcc: Decimal-encoded outside reward-ratio accumulation of the upper tick at exitTime. - tier: Pool emission tier at exitTime; zero denotes that the pool was not tiered. - tierRatio: Tier reward-share ratio, in its stored scaled form, at exitTime. - tierCount: Number of pools sharing the tier at exitTime for dividing tier rewards. - unstakingFee: Staking-reward fee rate in basis points at exitTime (0-1,000; 100 = 1%). - pendingIncentiveIds: External incentive IDs whose rewards are still owed by the position. Returns: - position: New exit checkpoint retaining the deposit and exit-time reward context; emission is initially uncollected and every supplied incentive is pending.

RegisterInitializer

RegisterInitializer registers a new staker implementation version. This function is called by each version (v1, v2, etc.) during initialization to register their implementation with the proxy system. The initializer function creates a new instance of the implementation using the provided stakerStore interface. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - initializer: Factory callback that receives the internal discriminator, current staker realm, and accessor interfaces, then returns the implementation instance. Security: Only contracts within the domain path can register initializers. Each package path can only register once to prevent duplicate registrations.

UpgradeImpl

UpgradeImpl switches the active staker implementation to a different version. It changes the implementation pointer without transforming persisted state; the selected implementation must understand the existing storage schema. Parameters: - cur: Current realm context; callers use cross(cur) when crossing into this realm. - packagePath: Registered package path of the implementation to activate. Security: Only admin or governance can perform upgrades. The new implementation must have been previously registered via RegisterInitializer.

GetImplementationPackagePath

GetImplementationPackagePath returns the package path of the currently active implementation. Returns: - packagePath: package path of the active implementation