staker package

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.

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.

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.

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.

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.

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.

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.

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 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

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.

DefaultAllowedTokens returns the token paths accepted by the staker's default configuration.

Returns:

• tokenPaths: Slice containing the GNS and wrapped-GNOT token paths.

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.

GetAllowedTokens returns the allowed external incentive tokens.

Returns:

• tokenPaths: Copy of token paths permitted for external incentives.

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

GetDeniedRewardTokens returns the denied external incentive reward tokens.

Returns:

• tokenPaths: Copy of token paths excluded from external incentive rewards.

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.

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.

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.

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 returns the GNS deposit required for each external incentive.

Returns:

• amount: Configured GNS deposit required per external incentive, in token units.

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.

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 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.

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 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 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 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.

GetImplementationPackagePath returns the package path of the currently active implementation.

Returns:

• packagePath: package path of the active implementation

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.

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

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.

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.

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.

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.

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.

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 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 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 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 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.

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.

GetMinimumRewardAmount returns the default minimum reward amount required to create an external incentive. A token-specific override may apply.

Returns:

• amount: Default minimum external-incentive reward amount in token units.

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.

GetPendingProtocolFees returns the pending protocol fee amount per token path.

Returns:

• fees: Copy of pending protocol-fee amounts keyed by token path, in the corresponding token units.

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 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.

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.

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.

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.

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.

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 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 returns the reward ratio of a pool.

Parameters:

• poolPath: Pool path whose current emission tier ratio should be read.

Returns:

• ratio: Stored reward-share ratio for the pool's current tier.
• err: Non-nil when the pool's tier is invalid and has no configured ratio.

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.

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 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.

GetTotalEmissionSent returns the total GNS emission sent.

Returns:

• amount: Cumulative GNS emission amount sent by the staker, in token units.

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.

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 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.

GetUnstakingFee returns the current unstaking fee rate in basis points (0-1,000; 100 = 1%).

Returns:

• feeRate: Current staking-reward fee rate in basis points.

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.

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.

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.

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.

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.

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.

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.

Render delegates web rendering to the active implementation.

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.

SetDepositGnsAmount sets the GNS deposit required for each external incentive.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• amount: GNS amount required as the per-incentive deposit.

Halt check: reverts while the Staker halt scope is active.

SetMinimumRewardAmount sets the default minimum reward amount required to create an external incentive. A token-specific override may apply.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• amount: Default minimum reward amount, measured in the reward token's units.

Halt check: reverts while the Staker halt scope is active.

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.

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 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.

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.

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 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.

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.

NewCounter creates a counter initialized at zero.

Returns:

• counter: Counter whose next generated identifier is 1.

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

NewTicks creates an empty tick mapping with a fanout-16 B+ tree.

Returns:

• ticks: Empty Ticks value ready to store pool tick records.

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.

NewUintTree creates a new UintTree instance with default fanout 64.

Returns:

• tree: Empty UintTree using the default fanout of 64.

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.

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.

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.

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.

GetWarmupTemplate returns the current warmup template.

Returns:

• warmups: Copy of the configured warmup schedule used for newly staked positions.

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.