getter.gno

  1package staker
  2
  3import (
  4	u256 "gno.land/p/gnoswap/uint256/v1"
  5	rotree "gno.land/p/nt/bptree/rotree/v0"
  6)
  7
  8// IStakerGetter functions
  9
 10// GetPool returns a copy of the staking state for a pool.
 11//
 12// Parameters:
 13//   - poolPath: pool realm path
 14//
 15// Returns:
 16//   - pool: independent pool copy, or nil when an implementation has no pool value
 17//   - err: implementation resolution error; the current v1 implementation returns not-found for a missing pool
 18func GetPool(poolPath string) (*Pool, error) {
 19	pool, err := getImplementation().GetPool(poolPath)
 20	if err != nil {
 21		return nil, err
 22	}
 23	if pool == nil {
 24		return nil, nil
 25	}
 26	return pool.Clone(), nil
 27}
 28
 29// GetDeposit returns a copy of a staked position's deposit.
 30//
 31// Parameters:
 32//   - lpTokenId: staked position NFT token ID
 33//
 34// Returns:
 35//   - deposit: independent deposit copy, or nil when an implementation has no deposit value
 36//   - err: implementation resolution error; the current v1 implementation returns not-found for a missing deposit
 37func GetDeposit(lpTokenId uint64) (*Deposit, error) {
 38	deposit, err := getImplementation().GetDeposit(lpTokenId)
 39	if err != nil {
 40		return nil, err
 41	}
 42	if deposit == nil {
 43		return nil, nil
 44	}
 45	return deposit.Clone(), nil
 46}
 47
 48// CollectableEmissionReward returns the claimable internal GNS reward for a live staked deposit or
 49// an exit checkpoint left by UnStakeToken.
 50//
 51// Parameters:
 52//   - positionId: staked position NFT token ID or position with an exit checkpoint
 53//
 54// Returns:
 55//   - amount: claimable internal reward amount
 56//   - err: non-nil when positionId cannot be resolved
 57func CollectableEmissionReward(positionId uint64) (int64, error) {
 58	return getImplementation().CollectableEmissionReward(positionId)
 59}
 60
 61// CollectableExternalIncentiveReward returns a position's claimable external reward for a live
 62// staked deposit or an exit checkpoint left by UnStakeToken.
 63//
 64// Parameters:
 65//   - positionId: staked position NFT token ID or position with an exit checkpoint
 66//   - incentiveId: external incentive identifier
 67//
 68// Returns:
 69//   - amount: claimable external reward amount
 70//   - err: non-nil when the position or incentive cannot be resolved
 71func CollectableExternalIncentiveReward(positionId uint64, incentiveId string) (int64, error) {
 72	return getImplementation().CollectableExternalIncentiveReward(positionId, incentiveId)
 73}
 74
 75// GetCreatedHeightOfIncentive returns an incentive's creation block height.
 76//
 77// Parameters:
 78//   - poolPath: pool realm path
 79//   - incentiveId: external incentive identifier
 80//
 81// Returns:
 82//   - height: creation block height
 83//   - err: non-nil when the incentive cannot be resolved
 84func GetCreatedHeightOfIncentive(poolPath string, incentiveId string) (int64, error) {
 85	return getImplementation().GetCreatedHeightOfIncentive(poolPath, incentiveId)
 86}
 87
 88// GetIncentiveCreatedTimestamp returns an incentive's creation timestamp.
 89//
 90// Parameters:
 91//   - poolPath: pool realm path
 92//   - incentiveId: external incentive identifier
 93//
 94// Returns:
 95//   - timestamp: creation Unix timestamp
 96//   - err: non-nil when the incentive cannot be resolved
 97func GetIncentiveCreatedTimestamp(poolPath string, incentiveId string) (int64, error) {
 98	return getImplementation().GetIncentiveCreatedTimestamp(poolPath, incentiveId)
 99}
100
101// GetIncentiveTotalRewardAmount returns the total reward amount of an incentive.
102//
103// Parameters:
104//   - poolPath: Pool path containing the incentive record.
105//   - incentiveId: External incentive identifier to resolve.
106//
107// Returns:
108//   - amount: Total reward amount configured when the incentive was created, in token units.
109//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
110func GetIncentiveTotalRewardAmount(poolPath string, incentiveId string) (int64, error) {
111	return getImplementation().GetIncentiveTotalRewardAmount(poolPath, incentiveId)
112}
113
114// GetIncentiveDistributedRewardAmount returns the distributed reward amount of an incentive.
115//
116// Parameters:
117//   - poolPath: Pool path containing the incentive record.
118//   - incentiveId: External incentive identifier to resolve.
119//
120// Returns:
121//   - amount: Reward amount already delivered to positions or refunded at incentive end, in token units.
122//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
123func GetIncentiveDistributedRewardAmount(poolPath string, incentiveId string) (int64, error) {
124	return getImplementation().GetIncentiveDistributedRewardAmount(poolPath, incentiveId)
125}
126
127// GetIncentiveRemainingRewardAmount returns the remaining reward amount of an incentive.
128//
129// Parameters:
130//   - poolPath: Pool path containing the incentive record.
131//   - incentiveId: External incentive identifier to resolve.
132//
133// Returns:
134//   - amount: Mutable reward balance remaining after distributions and refunds, in token units.
135//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
136func GetIncentiveRemainingRewardAmount(poolPath string, incentiveId string) (int64, error) {
137	return getImplementation().GetIncentiveRemainingRewardAmount(poolPath, incentiveId)
138}
139
140// GetIncentiveAccumulatedPenaltyAmount returns the accumulated warmup penalty amount of an incentive.
141//
142// Parameters:
143//   - poolPath: Pool path containing the incentive record.
144//   - incentiveId: External incentive identifier to resolve.
145//
146// Returns:
147//   - amount: Warmup penalty accumulated from collections for the incentive, in reward-token units.
148//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
149func GetIncentiveAccumulatedPenaltyAmount(poolPath string, incentiveId string) (int64, error) {
150	return getImplementation().GetIncentiveAccumulatedPenaltyAmount(poolPath, incentiveId)
151}
152
153// GetIncentiveDepositGnsAmount returns the deposited GNS amount of an incentive.
154//
155// Parameters:
156//   - poolPath: Pool path containing the incentive record.
157//   - incentiveId: External incentive identifier to resolve.
158//
159// Returns:
160//   - amount: GNS deposit locked by the incentive, in token units.
161//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
162func GetIncentiveDepositGnsAmount(poolPath string, incentiveId string) (int64, error) {
163	return getImplementation().GetIncentiveDepositGnsAmount(poolPath, incentiveId)
164}
165
166// GetIncentiveRefunded returns whether an incentive has been refunded.
167//
168// Parameters:
169//   - poolPath: Pool path containing the incentive record.
170//   - incentiveId: External incentive identifier to resolve.
171//
172// Returns:
173//   - refunded: True when the incentive has been finalized as refunded; false while it remains open.
174//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
175func GetIncentiveRefunded(poolPath string, incentiveId string) (bool, error) {
176	return getImplementation().GetIncentiveRefunded(poolPath, incentiveId)
177}
178
179// IsIncentiveActive reports whether an unrefunded incentive is active, including both start and end timestamps.
180//
181// Parameters:
182//   - poolPath: Pool path containing the incentive record.
183//   - incentiveId: External incentive identifier to resolve.
184//
185// Returns:
186//   - active: True when the current Unix time is within the incentive window and it has not been refunded.
187//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
188func IsIncentiveActive(poolPath string, incentiveId string) (bool, error) {
189	return getImplementation().IsIncentiveActive(poolPath, incentiveId)
190}
191
192// GetDepositExternalRewardLastCollectTimestamp returns the last external reward collection time for
193// a position and incentive. For a newly tracked incentive, the value is based on the stake timestamp.
194//
195// Parameters:
196//   - lpTokenId: Position NFT token ID whose external reward cursor should be read.
197//   - incentiveId: External incentive identifier whose collection cursor should be read.
198//
199// Returns:
200//   - timestamp: Unix timestamp of the last collection cursor; newly tracked incentives use the deposit's stake time.
201//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
202func GetDepositExternalRewardLastCollectTimestamp(lpTokenId uint64, incentiveId string) (int64, error) {
203	return getImplementation().GetDepositExternalRewardLastCollectTimestamp(lpTokenId, incentiveId)
204}
205
206// GetDepositGnsAmount returns the GNS deposit required for each external incentive.
207//
208// Returns:
209//   - amount: Configured GNS deposit required per external incentive, in token units.
210func GetDepositGnsAmount() int64 {
211	return getImplementation().GetDepositGnsAmount()
212}
213
214// GetDepositInternalRewardLastCollectTimestamp returns the last internal reward collection time for a position.
215//
216// Parameters:
217//   - lpTokenId: Position NFT token ID whose internal reward cursor should be read.
218//
219// Returns:
220//   - timestamp: Unix timestamp of the deposit's last internal reward collection.
221//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
222func GetDepositInternalRewardLastCollectTimestamp(lpTokenId uint64) (int64, error) {
223	return getImplementation().GetDepositInternalRewardLastCollectTimestamp(lpTokenId)
224}
225
226// GetDepositCollectedInternalReward returns the collected internal reward amount of a position.
227//
228// Parameters:
229//   - lpTokenId: Position NFT token ID whose collected internal reward should be read.
230//
231// Returns:
232//   - amount: Internal GNS reward amount already recorded as collected, in token units.
233//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
234func GetDepositCollectedInternalReward(lpTokenId uint64) (int64, error) {
235	return getImplementation().GetDepositCollectedInternalReward(lpTokenId)
236}
237
238// GetDepositCollectedExternalReward returns the collected external reward amount of a position.
239//
240// Parameters:
241//   - lpTokenId: Position NFT token ID whose collected reward should be read.
242//   - incentiveId: External incentive identifier whose collected amount should be read.
243//
244// Returns:
245//   - amount: External reward amount already recorded as collected for the incentive, in token units.
246//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
247func GetDepositCollectedExternalReward(lpTokenId uint64, incentiveId string) (int64, error) {
248	return getImplementation().GetDepositCollectedExternalReward(lpTokenId, incentiveId)
249}
250
251// GetDepositLiquidity returns the liquidity amount of a staked position.
252//
253// Parameters:
254//   - lpTokenId: Position NFT token ID whose liquidity should be read.
255//
256// Returns:
257//   - liquidity: Independent uint256 copy of the deposit's liquidity amount.
258//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
259func GetDepositLiquidity(lpTokenId uint64) (*u256.Uint, error) {
260	liquidity, err := getImplementation().GetDepositLiquidity(lpTokenId)
261	if err != nil {
262		return nil, err
263	}
264	return liquidity.Clone(), nil
265}
266
267// GetDepositLiquidityAsString returns the liquidity amount of a staked position as a decimal string.
268//
269// Parameters:
270//   - lpTokenId: Position NFT token ID whose liquidity should be formatted.
271//
272// Returns:
273//   - liquidity: Decimal representation of the deposit's uint256 liquidity amount.
274//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
275func GetDepositLiquidityAsString(lpTokenId uint64) (string, error) {
276	return getImplementation().GetDepositLiquidityAsString(lpTokenId)
277}
278
279// GetDepositOwner returns the owner of a staked position.
280//
281// Parameters:
282//   - lpTokenId: Position NFT token ID whose owner should be read.
283//
284// Returns:
285//   - owner: Address recorded as the deposit owner.
286//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
287func GetDepositOwner(lpTokenId uint64) (address, error) {
288	return getImplementation().GetDepositOwner(lpTokenId)
289}
290
291// GetDepositStakeTime returns the Unix timestamp at which a position was staked.
292//
293// Parameters:
294//   - lpTokenId: Position NFT token ID whose stake time should be read.
295//
296// Returns:
297//   - stakeTime: Unix timestamp recorded when the deposit entered staking.
298//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
299func GetDepositStakeTime(lpTokenId uint64) (int64, error) {
300	return getImplementation().GetDepositStakeTime(lpTokenId)
301}
302
303// GetDepositTargetPoolPath returns the pool path of a staked position.
304//
305// Parameters:
306//   - lpTokenId: Position NFT token ID whose target pool should be read.
307//
308// Returns:
309//   - poolPath: Pool path stored on the deposit.
310//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
311func GetDepositTargetPoolPath(lpTokenId uint64) (string, error) {
312	return getImplementation().GetDepositTargetPoolPath(lpTokenId)
313}
314
315// GetDepositTickLower returns the lower tick of a staked position.
316//
317// Parameters:
318//   - lpTokenId: Position NFT token ID whose lower boundary should be read.
319//
320// Returns:
321//   - tickLower: Lower price-range tick stored on the deposit.
322//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
323func GetDepositTickLower(lpTokenId uint64) (int32, error) {
324	return getImplementation().GetDepositTickLower(lpTokenId)
325}
326
327// GetDepositTickUpper returns the upper tick of a staked position.
328//
329// Parameters:
330//   - lpTokenId: Position NFT token ID whose upper boundary should be read.
331//
332// Returns:
333//   - tickUpper: Upper price-range tick stored on the deposit.
334//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
335func GetDepositTickUpper(lpTokenId uint64) (int32, error) {
336	return getImplementation().GetDepositTickUpper(lpTokenId)
337}
338
339// GetDepositWarmUp returns the warmup records of a staked position.
340//
341// Parameters:
342//   - lpTokenId: Position NFT token ID whose warmup schedule should be inspected.
343//
344// Returns:
345//   - warmups: Independent copy of the deposit's warmup records.
346//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
347func GetDepositWarmUp(lpTokenId uint64) ([]Warmup, error) {
348	warmups, err := getImplementation().GetDepositWarmUp(lpTokenId)
349	if err != nil {
350		return nil, err
351	}
352	return cloneWarmups(warmups), nil
353}
354
355// GetDepositExternalIncentiveIdList returns external incentive IDs tracked by a deposit.
356//
357// Parameters:
358//   - lpTokenId: Position NFT token ID whose deposit should be inspected.
359//
360// Returns:
361//   - incentiveIds: Independent copy of external incentive IDs associated with the deposit.
362//   - err: Non-nil when lpTokenId does not resolve to a stored deposit.
363func GetDepositExternalIncentiveIdList(lpTokenId uint64) ([]string, error) {
364	ids, err := getImplementation().GetDepositExternalIncentiveIdList(lpTokenId)
365	if err != nil {
366		return nil, err
367	}
368	return cloneStringSlice(ids), nil
369}
370
371// GetExternalIncentiveByPoolPath returns all external incentives for a pool.
372//
373// Parameters:
374//   - poolPath: Pool path whose external incentives should be listed.
375//
376// Returns:
377//   - incentives: Independent copies of incentives targeting poolPath.
378//   - err: Non-nil when stored incentive data cannot be read or cast.
379func GetExternalIncentiveByPoolPath(poolPath string) ([]ExternalIncentive, error) {
380	incentives, err := getImplementation().GetExternalIncentiveByPoolPath(poolPath)
381	if err != nil {
382		return nil, err
383	}
384	return cloneExternalIncentives(incentives), nil
385}
386
387// GetIncentiveEndTimestamp returns the end timestamp of an incentive.
388//
389// Parameters:
390//   - poolPath: Pool path containing the incentive record.
391//   - incentiveId: External incentive identifier to resolve.
392//
393// Returns:
394//   - endTimestamp: Incentive end time as a Unix timestamp.
395//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
396func GetIncentiveEndTimestamp(poolPath string, incentiveId string) (int64, error) {
397	return getImplementation().GetIncentiveEndTimestamp(poolPath, incentiveId)
398}
399
400// GetIncentiveCreator returns the creator address of an incentive.
401//
402// Parameters:
403//   - poolPath: Pool path containing the incentive record.
404//   - incentiveId: External incentive identifier to resolve.
405//
406// Returns:
407//   - creator: Address that created and funded the incentive.
408//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
409func GetIncentiveCreator(poolPath string, incentiveId string) (address, error) {
410	return getImplementation().GetIncentiveCreator(poolPath, incentiveId)
411}
412
413// GetIncentiveRewardAmount returns the remaining reward amount of an incentive, after deliveries
414// and refunds represented by the current incentive state.
415//
416// Parameters:
417//   - poolPath: Pool path containing the incentive record.
418//   - incentiveId: External incentive identifier to resolve.
419//
420// Returns:
421//   - amount: Independent uint256 copy of the incentive's mutable remaining reward amount.
422//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
423func GetIncentiveRewardAmount(poolPath string, incentiveId string) (*u256.Uint, error) {
424	amount, err := getImplementation().GetIncentiveRewardAmount(poolPath, incentiveId)
425	if err != nil {
426		return nil, err
427	}
428	return amount.Clone(), nil
429}
430
431// GetIncentiveRewardAmountAsString returns the remaining reward amount of an incentive as string.
432//
433// Parameters:
434//   - poolPath: Pool path containing the incentive record.
435//   - incentiveId: External incentive identifier to resolve.
436//
437// Returns:
438//   - amount: Decimal string for the incentive's remaining reward amount after deliveries and refunds.
439//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
440func GetIncentiveRewardAmountAsString(poolPath string, incentiveId string) (string, error) {
441	return getImplementation().GetIncentiveRewardAmountAsString(poolPath, incentiveId)
442}
443
444// GetIncentiveRewardPerSecondX128 returns the reward rate per second of an
445// incentive, expressed as a Q128 fixed-point number (i.e. actual rate =
446// value / 2^128). Callers needing an integer rate can right-shift the result
447// by 128.
448//
449// Parameters:
450//   - poolPath: Pool path containing the incentive record.
451//   - incentiveId: External incentive identifier to resolve.
452//
453// Returns:
454//   - rateX128: Clone of the Q128-scaled reward rate; divide by 2^128 to recover the actual token units per second.
455//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
456func GetIncentiveRewardPerSecondX128(poolPath string, incentiveId string) (*u256.Uint, error) {
457	amount, err := getImplementation().GetIncentiveRewardPerSecondX128(poolPath, incentiveId)
458	if err != nil {
459		return nil, err
460	}
461	return amount.Clone(), nil
462}
463
464// GetIncentiveRewardToken returns the reward token of an incentive.
465//
466// Parameters:
467//   - poolPath: Pool path containing the incentive record.
468//   - incentiveId: External incentive identifier to resolve.
469//
470// Returns:
471//   - tokenPath: Reward-token path configured for the incentive.
472//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
473func GetIncentiveRewardToken(poolPath string, incentiveId string) (string, error) {
474	return getImplementation().GetIncentiveRewardToken(poolPath, incentiveId)
475}
476
477// GetIncentiveStartTimestamp returns the start timestamp of an incentive.
478//
479// Parameters:
480//   - poolPath: Pool path containing the incentive record.
481//   - incentiveId: External incentive identifier to resolve.
482//
483// Returns:
484//   - startTimestamp: Incentive start time as a Unix timestamp.
485//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
486func GetIncentiveStartTimestamp(poolPath string, incentiveId string) (int64, error) {
487	return getImplementation().GetIncentiveStartTimestamp(poolPath, incentiveId)
488}
489
490// GetMinimumRewardAmount returns the default minimum reward amount required to create an external
491// incentive. A token-specific override may apply.
492//
493// Returns:
494//   - amount: Default minimum external-incentive reward amount in token units.
495func GetMinimumRewardAmount() int64 {
496	return getImplementation().GetMinimumRewardAmount()
497}
498
499// GetMinimumRewardAmountForToken returns the minimum reward amount for a specific token.
500//
501// Parameters:
502//   - tokenPath: Token path whose configured minimum-reward override should be read.
503//
504// Returns:
505//   - amount: Token-specific minimum reward amount when configured, otherwise the default minimum, in token units.
506func GetMinimumRewardAmountForToken(tokenPath string) int64 {
507	return getImplementation().GetMinimumRewardAmountForToken(tokenPath)
508}
509
510// GetPoolStakedLiquidity returns the current total staked liquidity of a pool.
511//
512// Parameters:
513//   - poolPath: Pool path whose current staked liquidity should be read.
514//
515// Returns:
516//   - liquidity: Decimal string containing the pool's total staked liquidity at the current time.
517//   - err: Non-nil when poolPath does not resolve to a pool.
518func GetPoolStakedLiquidity(poolPath string) (string, error) {
519	return getImplementation().GetPoolStakedLiquidity(poolPath)
520}
521
522// GetPoolsByTier returns the pool list for a tier.
523//
524// Parameters:
525//   - tier: Emission tier identifier whose current pool memberships should be listed.
526//
527// Returns:
528//   - poolPaths: Copy of pool paths currently assigned to tier; tier zero yields an empty list.
529//   - err: Non-nil when the stored tier membership contains an invalid value.
530func GetPoolsByTier(tier uint64) ([]string, error) {
531	pools, err := getImplementation().GetPoolsByTier(tier)
532	if err != nil {
533		return nil, err
534	}
535	return cloneStringSlice(pools), nil
536}
537
538// GetPoolReward returns the reward amount for a tier.
539//
540// Parameters:
541//   - tier: Emission tier identifier for which to retrieve the per-pool reward.
542//
543// Returns:
544//   - reward: Current per-pool GNS reward rate for tier, in token units per second.
545//   - err: Non-nil when tier is outside the valid range 1 through AllTierCount-1.
546func GetPoolReward(tier uint64) (int64, error) {
547	return getImplementation().GetPoolReward(tier)
548}
549
550// GetPoolTier returns the tier of a pool.
551//
552// Parameters:
553//   - poolPath: Pool path whose current emission tier should be read.
554//
555// Returns:
556//   - tier: Current emission tier identifier; zero when the pool has no tier assignment.
557func GetPoolTier(poolPath string) uint64 {
558	return getImplementation().GetPoolTier(poolPath)
559}
560
561// GetPoolTierCount returns the number of pools in a tier.
562//
563// Parameters:
564//   - tier: Emission tier identifier to count; tier zero has no pools.
565//
566// Returns:
567//   - count: Number of pools currently assigned to tier, or zero for tier zero.
568func GetPoolTierCount(tier uint64) uint64 {
569	return getImplementation().GetPoolTierCount(tier)
570}
571
572// GetPoolTierRatio returns the reward ratio of a pool.
573//
574// Parameters:
575//   - poolPath: Pool path whose current emission tier ratio should be read.
576//
577// Returns:
578//   - ratio: Stored reward-share ratio for the pool's current tier.
579//   - err: Non-nil when the pool's tier is invalid and has no configured ratio.
580func GetPoolTierRatio(poolPath string) (uint64, error) {
581	return getImplementation().GetPoolTierRatio(poolPath)
582}
583
584// GetSpecificTokenMinimumRewardAmount returns the explicitly set minimum reward amount for a token.
585//
586// Parameters:
587//   - tokenPath: Token path whose explicit minimum-reward override should be read.
588//
589// Returns:
590//   - amount: Explicit minimum reward amount in token units, or 0 when no override is configured.
591//   - found: True when tokenPath has an explicit override; false when the default would be used.
592func GetSpecificTokenMinimumRewardAmount(tokenPath string) (int64, bool) {
593	return getImplementation().GetSpecificTokenMinimumRewardAmount(tokenPath)
594}
595
596// GetTargetPoolPathByIncentiveId returns the pool path for an incentive ID.
597//
598// Parameters:
599//   - poolPath: Pool path containing the incentive record.
600//   - incentiveId: External incentive identifier to resolve.
601//
602// Returns:
603//   - targetPoolPath: Pool path stored on the resolved incentive.
604//   - err: Non-nil when poolPath or incentiveId cannot be resolved.
605func GetTargetPoolPathByIncentiveId(poolPath string, incentiveId string) (string, error) {
606	return getImplementation().GetTargetPoolPathByIncentiveId(poolPath, incentiveId)
607}
608
609// GetUnstakingFee returns the current unstaking fee rate in basis points (0-1,000; 100 = 1%).
610//
611// Returns:
612//   - feeRate: Current staking-reward fee rate in basis points.
613func GetUnstakingFee() uint64 {
614	return getImplementation().GetUnstakingFee()
615}
616
617// HasUnstakedPosition returns whether a position was unstaked with rewards left to collect.
618//
619// Parameters:
620//   - positionId: Position NFT token ID to check in the unstaked-position tree.
621//
622// Returns:
623//   - unstaked: True when positionId has an exit checkpoint awaiting collection; false otherwise.
624func HasUnstakedPosition(positionId uint64) bool {
625	return getImplementation().HasUnstakedPosition(positionId)
626}
627
628// GetUnstakedPositionExitTime returns the timestamp at which an unstaked position stopped accruing rewards.
629//
630// Parameters:
631//   - positionId: Position NFT token ID identifying the unstaked exit checkpoint.
632//
633// Returns:
634//   - exitTime: Unix timestamp pinned as the end of the position's reward-accrual window.
635//   - err: Non-nil when positionId has no unstaked checkpoint with uncollected rewards.
636func GetUnstakedPositionExitTime(positionId uint64) (int64, error) {
637	return getImplementation().GetUnstakedPositionExitTime(positionId)
638}
639
640// GetUnstakedPositionPendingIncentives returns the incentives an unstaked position has yet to collect.
641//
642// Parameters:
643//   - positionId: Position NFT token ID identifying the unstaked exit checkpoint.
644//
645// Returns:
646//   - incentiveIds: Copy of external incentive IDs still pending for the exit checkpoint.
647//   - err: Non-nil when positionId has no unstaked checkpoint with uncollected rewards.
648func GetUnstakedPositionPendingIncentives(positionId uint64) ([]string, error) {
649	incentiveIds, err := getImplementation().GetUnstakedPositionPendingIncentives(positionId)
650	if err != nil {
651		return nil, err
652	}
653	return cloneStringSlice(incentiveIds), nil
654}
655
656// GetUncollectedIncentiveCount returns how many unstaked positions still owe a reward from the incentive.
657//
658// Parameters:
659//   - incentiveId: External incentive identifier whose outstanding exit positions should be counted.
660//
661// Returns:
662//   - count: Number of unstaked positions with an uncollected reward for incentiveId.
663func GetUncollectedIncentiveCount(incentiveId string) int64 {
664	return getImplementation().GetUncollectedIncentiveCount(incentiveId)
665}
666
667// IsStaked returns whether a position is staked.
668//
669// Parameters:
670//   - positionId: Position NFT token ID to check in the active deposit tree.
671//
672// Returns:
673//   - staked: True when positionId has an active deposit; false for an unstaked or unknown position.
674func IsStaked(positionId uint64) bool {
675	return getImplementation().IsStaked(positionId)
676}
677
678// GetTotalEmissionSent returns the total GNS emission sent.
679//
680// Returns:
681//   - amount: Cumulative GNS emission amount sent by the staker, in token units.
682func GetTotalEmissionSent() int64 {
683	return getImplementation().GetTotalEmissionSent()
684}
685
686// GetAllowedTokens returns the allowed external incentive tokens.
687//
688// Returns:
689//   - tokenPaths: Copy of token paths permitted for external incentives.
690func GetAllowedTokens() []string {
691	return cloneStringSlice(getImplementation().GetAllowedTokens())
692}
693
694// GetDeniedRewardTokens returns the denied external incentive reward tokens.
695//
696// Returns:
697//   - tokenPaths: Copy of token paths excluded from external incentive rewards.
698func GetDeniedRewardTokens() []string {
699	return cloneStringSlice(getImplementation().GetDeniedRewardTokens())
700}
701
702// GetWarmupTemplate returns the current warmup template.
703//
704// Returns:
705//   - warmups: Copy of the configured warmup schedule used for newly staked positions.
706func GetWarmupTemplate() []Warmup {
707	return cloneWarmups(getImplementation().GetWarmupTemplate())
708}
709
710// GetPoolRewardCaches returns a read-only view of a pool's reward cache, keyed
711// by the encoded block timestamp. Callers paginate it themselves through
712// IterateByOffset and decode keys with DecodeInt64.
713//
714// Parameters:
715//   - poolPath: Pool path whose reward-cache checkpoints should be read.
716//
717// Returns:
718//   - caches: Read-only tree of timestamp keys to cached reward values, or nil when poolPath has no pool.
719func GetPoolRewardCaches(poolPath string) *rotree.ReadOnlyTree {
720	return getImplementation().GetPoolRewardCaches(poolPath)
721}
722
723// GetPoolIncentives returns a read-only view of a pool's external incentives,
724// keyed by incentive ID. Reading an entry yields a clone, so the view cannot
725// mutate realm state.
726//
727// Parameters:
728//   - poolPath: Pool path whose external-incentive records should be read.
729//
730// Returns:
731//   - incentives: Read-only tree keyed by incentive ID with cloned entries, or nil when poolPath has no pool.
732func GetPoolIncentives(poolPath string) *rotree.ReadOnlyTree {
733	return getImplementation().GetPoolIncentives(poolPath)
734}
735
736// GetPoolGlobalRewardRatioAccumulations returns a read-only view of a pool's
737// global reward ratio accumulation, keyed by the encoded block timestamp.
738//
739// Parameters:
740//   - poolPath: Pool path whose global reward-ratio checkpoints should be read.
741//
742// Returns:
743//   - accumulations: Read-only tree of timestamp keys to stored accumulation values, or nil when poolPath has no pool.
744func GetPoolGlobalRewardRatioAccumulations(poolPath string) *rotree.ReadOnlyTree {
745	return getImplementation().GetPoolGlobalRewardRatioAccumulations(poolPath)
746}
747
748// GetPoolHistoricalTicks returns a read-only view of a pool's historical ticks,
749// keyed by the encoded block timestamp with the int32 tick as the value.
750//
751// Parameters:
752//   - poolPath: Pool path whose historical tick checkpoints should be read.
753//
754// Returns:
755//   - ticks: Read-only tree of timestamp keys to int32 ticks, or nil when poolPath has no pool.
756func GetPoolHistoricalTicks(poolPath string) *rotree.ReadOnlyTree {
757	return getImplementation().GetPoolHistoricalTicks(poolPath)
758}
759
760// GetPendingProtocolFees returns the pending protocol fee amount per token path.
761//
762// Returns:
763//   - fees: Copy of pending protocol-fee amounts keyed by token path, in the corresponding token units.
764func GetPendingProtocolFees() map[string]int64 {
765	return cloneStringInt64Map(getImplementation().GetPendingProtocolFees())
766}