For the complete documentation index, see llms.txt. This page is also available as Markdown.

getter.gno

CollectableEmissionReward

CollectableEmissionReward returns the claimable internal GNS reward for a live staked deposit or an exit checkpoint left by UnStakeToken.

Parameters

Name
Type
Description

positionId

uint64

staked position NFT token ID or position with an exit checkpoint

Return Values

Name
Type
Description

amount

int64

claimable internal reward amount

err

error

non-nil when positionId cannot be resolved

source

CollectableExternalIncentiveReward

CollectableExternalIncentiveReward returns a position's claimable external reward for a live staked deposit or an exit checkpoint left by UnStakeToken.

Parameters

Name
Type
Description

positionId

uint64

staked position NFT token ID or position with an exit checkpoint

incentiveId

string

external incentive identifier

Return Values

Name
Type
Description

amount

int64

claimable external reward amount

err

error

non-nil when the position or incentive cannot be resolved

source

GetAllowedTokens

GetAllowedTokens returns the allowed external incentive tokens.

Return Values

Name
Type
Description

tokenPaths

[]string

Copy of token paths permitted for external incentives.

source

GetCreatedHeightOfIncentive

GetCreatedHeightOfIncentive returns an incentive's creation block height.

Parameters

Name
Type
Description

poolPath

string

pool realm path

incentiveId

string

external incentive identifier

Return Values

Name
Type
Description

height

int64

creation block height

err

error

non-nil when the incentive cannot be resolved

source

GetDeniedRewardTokens

GetDeniedRewardTokens returns the denied external incentive reward tokens.

Return Values

Name
Type
Description

tokenPaths

[]string

Copy of token paths excluded from external incentive rewards.

source

GetDepositCollectedExternalReward

GetDepositCollectedExternalReward returns the collected external reward amount of a position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose collected reward should be read.

incentiveId

string

External incentive identifier whose collected amount should be read.

Return Values

Name
Type
Description

amount

int64

External reward amount already recorded as collected for the incentive, in token units.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositCollectedInternalReward

GetDepositCollectedInternalReward returns the collected internal reward amount of a position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose collected internal reward should be read.

Return Values

Name
Type
Description

amount

int64

Internal GNS reward amount already recorded as collected, in token units.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositExternalIncentiveIdList

GetDepositExternalIncentiveIdList returns external incentive IDs tracked by a deposit.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose deposit should be inspected.

Return Values

Name
Type
Description

incentiveIds

[]string

Independent copy of external incentive IDs associated with the deposit.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

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

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose external reward cursor should be read.

incentiveId

string

External incentive identifier whose collection cursor should be read.

Return Values

Name
Type
Description

timestamp

int64

Unix timestamp of the last collection cursor; newly tracked incentives use the deposit's stake time.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositGnsAmount

GetDepositGnsAmount returns the GNS deposit required for each external incentive.

Return Values

Name
Type
Description

amount

int64

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

source

GetDepositInternalRewardLastCollectTimestamp

GetDepositInternalRewardLastCollectTimestamp returns the last internal reward collection time for a position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose internal reward cursor should be read.

Return Values

Name
Type
Description

timestamp

int64

Unix timestamp of the deposit's last internal reward collection.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositLiquidity

GetDepositLiquidity returns the liquidity amount of a staked position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose liquidity should be read.

Return Values

Name
Type
Description

liquidity

*u256.Uint

Independent uint256 copy of the deposit's liquidity amount.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositLiquidityAsString

GetDepositLiquidityAsString returns the liquidity amount of a staked position as a decimal string.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose liquidity should be formatted.

Return Values

Name
Type
Description

liquidity

string

Decimal representation of the deposit's uint256 liquidity amount.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositOwner

GetDepositOwner returns the owner of a staked position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose owner should be read.

Return Values

Name
Type
Description

owner

address

Address recorded as the deposit owner.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositStakeTime

GetDepositStakeTime returns the Unix timestamp at which a position was staked.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose stake time should be read.

Return Values

Name
Type
Description

stakeTime

int64

Unix timestamp recorded when the deposit entered staking.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositTargetPoolPath

GetDepositTargetPoolPath returns the pool path of a staked position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose target pool should be read.

Return Values

Name
Type
Description

poolPath

string

Pool path stored on the deposit.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositTickLower

GetDepositTickLower returns the lower tick of a staked position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose lower boundary should be read.

Return Values

Name
Type
Description

tickLower

int32

Lower price-range tick stored on the deposit.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetDepositTickUpper

GetDepositTickUpper returns the upper tick of a staked position.

Parameters

Name
Type
Description

lpTokenId

uint64

Position NFT token ID whose upper boundary should be read.

Return Values

Name
Type
Description

tickUpper

int32

Upper price-range tick stored on the deposit.

err

error

Non-nil when lpTokenId does not resolve to a stored deposit.

source

GetIncentiveAccumulatedPenaltyAmount

GetIncentiveAccumulatedPenaltyAmount returns the accumulated warmup penalty amount of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

int64

Warmup penalty accumulated from collections for the incentive, in reward-token units.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveCreatedTimestamp

GetIncentiveCreatedTimestamp returns an incentive's creation timestamp.

Parameters

Name
Type
Description

poolPath

string

pool realm path

incentiveId

string

external incentive identifier

Return Values

Name
Type
Description

timestamp

int64

creation Unix timestamp

err

error

non-nil when the incentive cannot be resolved

source

GetIncentiveCreator

GetIncentiveCreator returns the creator address of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

creator

address

Address that created and funded the incentive.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveDepositGnsAmount

GetIncentiveDepositGnsAmount returns the deposited GNS amount of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

int64

GNS deposit locked by the incentive, in token units.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveDistributedRewardAmount

GetIncentiveDistributedRewardAmount returns the distributed reward amount of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

int64

Reward amount already delivered to positions or refunded at incentive end, in token units.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveEndTimestamp

GetIncentiveEndTimestamp returns the end timestamp of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

endTimestamp

int64

Incentive end time as a Unix timestamp.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveRefunded

GetIncentiveRefunded returns whether an incentive has been refunded.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

refunded

bool

True when the incentive has been finalized as refunded; false while it remains open.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveRemainingRewardAmount

GetIncentiveRemainingRewardAmount returns the remaining reward amount of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

int64

Mutable reward balance remaining after distributions and refunds, in token units.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveRewardAmount

GetIncentiveRewardAmount returns the remaining reward amount of an incentive, after deliveries and refunds represented by the current incentive state.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

*u256.Uint

Independent uint256 copy of the incentive's mutable remaining reward amount.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveRewardAmountAsString

GetIncentiveRewardAmountAsString returns the remaining reward amount of an incentive as string.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

string

Decimal string for the incentive's remaining reward amount after deliveries and refunds.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

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

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

rateX128

*u256.Uint

Clone of the Q128-scaled reward rate; divide by 2^128 to recover the actual token units per second.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveRewardToken

GetIncentiveRewardToken returns the reward token of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

tokenPath

string

Reward-token path configured for the incentive.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveStartTimestamp

GetIncentiveStartTimestamp returns the start timestamp of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

startTimestamp

int64

Incentive start time as a Unix timestamp.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetIncentiveTotalRewardAmount

GetIncentiveTotalRewardAmount returns the total reward amount of an incentive.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

amount

int64

Total reward amount configured when the incentive was created, in token units.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetMinimumRewardAmount

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

Return Values

Name
Type
Description

amount

int64

Default minimum external-incentive reward amount in token units.

source

GetMinimumRewardAmountForToken

GetMinimumRewardAmountForToken returns the minimum reward amount for a specific token.

Parameters

Name
Type
Description

tokenPath

string

Token path whose configured minimum-reward override should be read.

Return Values

Name
Type
Description

amount

int64

Token-specific minimum reward amount when configured, otherwise the default minimum, in token units.

source

GetPendingProtocolFees

GetPendingProtocolFees returns the pending protocol fee amount per token path.

Return Values

Name
Type
Description

fees

map[string]int64

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

source

GetPoolGlobalRewardRatioAccumulations

GetPoolGlobalRewardRatioAccumulations returns a read-only view of a pool's global reward ratio accumulation, keyed by the encoded block timestamp.

Parameters

Name
Type
Description

poolPath

string

Pool path whose global reward-ratio checkpoints should be read.

Return Values

Name
Type
Description

accumulations

*rotree.ReadOnlyTree

Read-only tree of timestamp keys to stored accumulation values, or nil when poolPath has no pool.

source

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

Name
Type
Description

poolPath

string

Pool path whose historical tick checkpoints should be read.

Return Values

Name
Type
Description

ticks

*rotree.ReadOnlyTree

Read-only tree of timestamp keys to int32 ticks, or nil when poolPath has no pool.

source

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

Name
Type
Description

poolPath

string

Pool path whose external-incentive records should be read.

Return Values

Name
Type
Description

incentives

*rotree.ReadOnlyTree

Read-only tree keyed by incentive ID with cloned entries, or nil when poolPath has no pool.

source

GetPoolReward

GetPoolReward returns the reward amount for a tier.

Parameters

Name
Type
Description

tier

uint64

Emission tier identifier for which to retrieve the per-pool reward.

Return Values

Name
Type
Description

reward

int64

Current per-pool GNS reward rate for tier, in token units per second.

err

error

Non-nil when tier is outside the valid range 1 through AllTierCount-1.

source

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

Name
Type
Description

poolPath

string

Pool path whose reward-cache checkpoints should be read.

Return Values

Name
Type
Description

caches

*rotree.ReadOnlyTree

Read-only tree of timestamp keys to cached reward values, or nil when poolPath has no pool.

source

GetPoolStakedLiquidity

GetPoolStakedLiquidity returns the current total staked liquidity of a pool.

Parameters

Name
Type
Description

poolPath

string

Pool path whose current staked liquidity should be read.

Return Values

Name
Type
Description

liquidity

string

Decimal string containing the pool's total staked liquidity at the current time.

err

error

Non-nil when poolPath does not resolve to a pool.

source

GetPoolTier

GetPoolTier returns the tier of a pool.

Parameters

Name
Type
Description

poolPath

string

Pool path whose current emission tier should be read.

Return Values

Name
Type
Description

tier

uint64

Current emission tier identifier; zero when the pool has no tier assignment.

source

GetPoolTierCount

GetPoolTierCount returns the number of pools in a tier.

Parameters

Name
Type
Description

tier

uint64

Emission tier identifier to count; tier zero has no pools.

Return Values

Name
Type
Description

count

uint64

Number of pools currently assigned to tier, or zero for tier zero.

source

GetPoolTierRatio

GetPoolTierRatio returns the reward ratio of a pool.

Parameters

Name
Type
Description

poolPath

string

Pool path whose current emission tier ratio should be read.

Return Values

Name
Type
Description

ratio

uint64

Stored reward-share ratio for the pool's current tier.

err

error

Non-nil when the pool's tier is invalid and has no configured ratio.

source

GetPoolsByTier

GetPoolsByTier returns the pool list for a tier.

Parameters

Name
Type
Description

tier

uint64

Emission tier identifier whose current pool memberships should be listed.

Return Values

Name
Type
Description

poolPaths

[]string

Copy of pool paths currently assigned to tier; tier zero yields an empty list.

err

error

Non-nil when the stored tier membership contains an invalid value.

source

GetSpecificTokenMinimumRewardAmount

GetSpecificTokenMinimumRewardAmount returns the explicitly set minimum reward amount for a token.

Parameters

Name
Type
Description

tokenPath

string

Token path whose explicit minimum-reward override should be read.

Return Values

Name
Type
Description

amount

int64

Explicit minimum reward amount in token units, or 0 when no override is configured.

found

bool

True when tokenPath has an explicit override; false when the default would be used.

source

GetTargetPoolPathByIncentiveId

GetTargetPoolPathByIncentiveId returns the pool path for an incentive ID.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

targetPoolPath

string

Pool path stored on the resolved incentive.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

GetTotalEmissionSent

GetTotalEmissionSent returns the total GNS emission sent.

Return Values

Name
Type
Description

amount

int64

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

source

GetUncollectedIncentiveCount

GetUncollectedIncentiveCount returns how many unstaked positions still owe a reward from the incentive.

Parameters

Name
Type
Description

incentiveId

string

External incentive identifier whose outstanding exit positions should be counted.

Return Values

Name
Type
Description

count

int64

Number of unstaked positions with an uncollected reward for incentiveId.

source

GetUnstakedPositionExitTime

GetUnstakedPositionExitTime returns the timestamp at which an unstaked position stopped accruing rewards.

Parameters

Name
Type
Description

positionId

uint64

Position NFT token ID identifying the unstaked exit checkpoint.

Return Values

Name
Type
Description

exitTime

int64

Unix timestamp pinned as the end of the position's reward-accrual window.

err

error

Non-nil when positionId has no unstaked checkpoint with uncollected rewards.

source

GetUnstakedPositionPendingIncentives

GetUnstakedPositionPendingIncentives returns the incentives an unstaked position has yet to collect.

Parameters

Name
Type
Description

positionId

uint64

Position NFT token ID identifying the unstaked exit checkpoint.

Return Values

Name
Type
Description

incentiveIds

[]string

Copy of external incentive IDs still pending for the exit checkpoint.

err

error

Non-nil when positionId has no unstaked checkpoint with uncollected rewards.

source

GetUnstakingFee

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

Return Values

Name
Type
Description

feeRate

uint64

Current staking-reward fee rate in basis points.

source

HasUnstakedPosition

HasUnstakedPosition returns whether a position was unstaked with rewards left to collect.

Parameters

Name
Type
Description

positionId

uint64

Position NFT token ID to check in the unstaked-position tree.

Return Values

Name
Type
Description

unstaked

bool

True when positionId has an exit checkpoint awaiting collection; false otherwise.

source

IsIncentiveActive

IsIncentiveActive reports whether an unrefunded incentive is active, including both start and end timestamps.

Parameters

Name
Type
Description

poolPath

string

Pool path containing the incentive record.

incentiveId

string

External incentive identifier to resolve.

Return Values

Name
Type
Description

active

bool

True when the current Unix time is within the incentive window and it has not been refunded.

err

error

Non-nil when poolPath or incentiveId cannot be resolved.

source

IsStaked

IsStaked returns whether a position is staked.

Parameters

Name
Type
Description

positionId

uint64

Position NFT token ID to check in the active deposit tree.

Return Values

Name
Type
Description

staked

bool

True when positionId has an active deposit; false for an unstaked or unknown position.

source

Last updated