Kind Realm (renderable)
Name staker
Namespace gnoswap
Exported functions 102
Module gno.land/r/gnoswap/staker
gno 0.9 pool.gno gno
⧉
1 package staker 2 3 import ( 4 "errors" 5 "time" 6 7 "gno.land/p/gnoswap/consts/v1" 8 AddToken (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, tokenPath string)
CancelExternalIncentive (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, targetPoolPath string, incentiveId string)
ChangePoolTier (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, poolPath string, tier uint64)
CollectableEmissionReward (positionId uint64) (int64, interface {Error func() string})
CollectableExternalIncentiveReward (positionId uint64, incentiveId string) (int64, interface {Error func() string})
CollectEmissionReward (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, positionId uint64) (int64, int64)
CollectExternalIncentivePenalty (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, targetPoolPath string, incentiveId string, refundAddress string) int64
CollectExternalIncentiveReward (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, positionId uint64, incentiveId string) (int64, int64)
CollectReward (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, positionId uint64) (string, string, map[string]int64, map[string]int64)
CreateExternalIncentive (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, targetPoolPath string, rewardToken string, rewardAmount int64, startTimestamp int64, endTimestamp int64)
DefaultAllowedTokens () []string
DefaultWarmupTemplate () []gno.land/r/gnoswap/staker.Warmup
EndExternalIncentive (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, targetPoolPath string, incentiveId string, refundAddress string)
GetAllowedTokens () []string
GetCreatedHeightOfIncentive (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetDeniedRewardTokens () []string
GetDeposit (lpTokenId uint64) (*gno.land/r/gnoswap/staker.Deposit, interface {Error func() string})
GetDepositCollectedExternalReward (lpTokenId uint64, incentiveId string) (int64, interface {Error func() string})
GetDepositCollectedInternalReward (lpTokenId uint64) (int64, interface {Error func() string})
GetDepositExternalIncentiveIdList (lpTokenId uint64) ([]string, interface {Error func() string})
GetDepositExternalRewardLastCollectTimestamp (lpTokenId uint64, incentiveId string) (int64, interface {Error func() string})
GetDepositGnsAmount () int64
GetDepositInternalRewardLastCollectTimestamp (lpTokenId uint64) (int64, interface {Error func() string})
GetDepositLiquidity (lpTokenId uint64) (*gno.land/p/gnoswap/uint256/v1.Uint, interface {Error func() string})
GetDepositLiquidityAsString (lpTokenId uint64) (string, interface {Error func() string})
GetDepositOwner (lpTokenId uint64) (string, interface {Error func() string})
GetDepositStakeTime (lpTokenId uint64) (int64, interface {Error func() string})
GetDepositTargetPoolPath (lpTokenId uint64) (string, interface {Error func() string})
GetDepositTickLower (lpTokenId uint64) (int32, interface {Error func() string})
GetDepositTickUpper (lpTokenId uint64) (int32, interface {Error func() string})
GetDepositWarmUp (lpTokenId uint64) ([]gno.land/r/gnoswap/staker.Warmup, interface {Error func() string})
GetExternalIncentiveByPoolPath (poolPath string) ([]gno.land/r/gnoswap/staker.ExternalIncentive, interface {Error func() string})
GetImplementationPackagePath () string
GetIncentiveAccumulatedPenaltyAmount (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveCreatedTimestamp (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveCreator (poolPath string, incentiveId string) (string, interface {Error func() string})
GetIncentiveDepositGnsAmount (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveDistributedRewardAmount (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveEndTimestamp (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveRefunded (poolPath string, incentiveId string) (bool, interface {Error func() string})
GetIncentiveRemainingRewardAmount (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveRewardAmount (poolPath string, incentiveId string) (*gno.land/p/gnoswap/uint256/v1.Uint, interface {Error func() string})
GetIncentiveRewardAmountAsString (poolPath string, incentiveId string) (string, interface {Error func() string})
GetIncentiveRewardPerSecondX128 (poolPath string, incentiveId string) (*gno.land/p/gnoswap/uint256/v1.Uint, interface {Error func() string})
GetIncentiveRewardToken (poolPath string, incentiveId string) (string, interface {Error func() string})
GetIncentiveStartTimestamp (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetIncentiveTotalRewardAmount (poolPath string, incentiveId string) (int64, interface {Error func() string})
GetMinimumRewardAmount () int64
GetMinimumRewardAmountForToken (tokenPath string) int64
GetPendingProtocolFees () map[string]int64
GetPool (poolPath string) (*gno.land/r/gnoswap/staker.Pool, interface {Error func() string})
GetPoolGlobalRewardRatioAccumulations (poolPath string) *gno.land/p/nt/bptree/rotree/v0.ReadOnlyTree
GetPoolHistoricalTicks (poolPath string) *gno.land/p/nt/bptree/rotree/v0.ReadOnlyTree
GetPoolIncentives (poolPath string) *gno.land/p/nt/bptree/rotree/v0.ReadOnlyTree
GetPoolReward (tier uint64) (int64, interface {Error func() string})
GetPoolRewardCaches (poolPath string) *gno.land/p/nt/bptree/rotree/v0.ReadOnlyTree
GetPoolsByTier (tier uint64) ([]string, interface {Error func() string})
GetPoolStakedLiquidity (poolPath string) (string, interface {Error func() string})
GetPoolTier (poolPath string) uint64
GetPoolTierCount (tier uint64) uint64
GetPoolTierRatio (poolPath string) (uint64, interface {Error func() string})
GetSpecificTokenMinimumRewardAmount (tokenPath string) (int64, bool)
GetTargetPoolPathByIncentiveId (poolPath string, incentiveId string) (string, interface {Error func() string})
GetTotalEmissionSent () int64
GetUncollectedIncentiveCount (incentiveId string) int64
GetUnstakedPositionExitTime (positionId uint64) (int64, interface {Error func() string})
GetUnstakedPositionPendingIncentives (positionId uint64) ([]string, interface {Error func() string})
GetUnstakingFee () uint64
GetWarmupTemplate () []gno.land/r/gnoswap/staker.Warmup
HasUnstakedPosition (positionId uint64) bool
IsIncentiveActive (poolPath string, incentiveId string) (bool, interface {Error func() string})
IsStaked (positionId uint64) bool
NewBPTreeN (fanout int) *gno.land/p/nt/bptree/v0.BPTree
NewCounter () *gno.land/r/gnoswap/staker.Counter
NewDeposit (owner string, targetPoolPath string, liquidity *gno.land/p/gnoswap/uint256/v1.Uint, currentTime int64, tickLower int32, tickUpper int32, warmups []gno.land/r/gnoswap/staker.Warmup) *gno.land/r/gnoswap/staker.Deposit
NewExternalIncentive (incentiveId string, targetPoolPath string, rewardToken string, rewardAmount int64, startTimestamp int64, endTimestamp int64, creator string, depositGnsAmount int64, createdHeight int64, currentTime int64) *gno.land/r/gnoswap/staker.ExternalIncentive
NewIncentives (targetPoolPath string) *gno.land/r/gnoswap/staker.Incentives
NewPool (poolPath string, currentTime int64) *gno.land/r/gnoswap/staker.Pool
NewStakerStore (kvStore interface {AddAuthorizedCaller func(int, .uverse.realm, .uverse.address, gno.land/p/gnoswap/store/v1.Permission) .uverse.error; Delete func(int, .uverse.realm, string) .uverse.error; Get func(string) (interface {}, .uverse.error); GetAddress func(string) (.uverse.address, .uverse.error); GetAllKeys func() ([]string, .uverse.error); GetAuthorizedCallers func() (map[.uverse.address]gno.land/p/gnoswap/store/v1.Permission, .uverse.error); GetBPTree func(string) (*gno.land/p/nt/bptree/v0.BPTree, .uverse.error); GetBool func(string) (bool, .uverse.error); GetDomainAddress func() .uverse.address; GetInt64 func(string) (int64, .uverse.error); GetString func(string) (string, .uverse.error); GetUint64 func(string) (uint64, .uverse.error); Has func(string) bool; IsWriteAuthorized func(.uverse.address) bool; RemoveAuthorizedCaller func(int, .uverse.realm, .uverse.address) .uverse.error; Set func(int, .uverse.realm, string, interface {}) .uverse.error; UpdateAuthorizedCaller func(int, .uverse.realm, .uverse.address, gno.land/p/gnoswap/store/v1.Permission) .uverse.error}) interface {AddAllowedToken func(int, .uverse.realm, string) .uverse.error; AddDeniedRewardToken func(int, .uverse.realm, string) .uverse.error; GetAllowedTokens func() []string; GetCurrentSwapBatch func() *gno.land/r/gnoswap/staker.SwapBatchProcessor; GetDeniedRewardTokens func() []string; GetDepositGnsAmount func() int64; GetDeposits func() *gno.land/p/nt/bptree/v0.BPTree; GetExternalIncentives func() *gno.land/p/nt/bptree/v0.BPTree; GetIncentiveCounter func() *gno.land/r/gnoswap/staker.Counter; GetMinimumRewardAmount func() int64; GetPendingProtocolFee func(string) int64; GetPendingProtocolFees func() map[string]int64; GetPoolTierCounts func() [4]uint64; GetPoolTierCurrentEmission func() int64; GetPoolTierGetEmission func() func() (int64, .uverse.error); GetPoolTierGetHalvingBlocksInRange func() func(int64, int64) ([]int64, []int64, .uverse.error); GetPoolTierLastRewardCacheTimestamp func() int64; GetPoolTierMemberships func() *gno.land/p/nt/bptree/v0.BPTree; GetPoolTierRatio func() gno.land/r/gnoswap/staker.TierRatio; GetPools func() *gno.land/p/nt/bptree/v0.BPTree; GetTokenSpecificMinimumRewards func() map[string]int64; GetTotalEmissionSent func() int64; GetUncollectedIncentiveCounts func() *gno.land/p/nt/bptree/v0.BPTree; GetUnstakedPositions func() *gno.land/p/nt/bptree/v0.BPTree; GetUnstakingFee func() uint64; GetWarmupTemplate func() []gno.land/r/gnoswap/staker.Warmup; HasAllowedTokensStoreKey func() bool; HasCurrentSwapBatchStoreKey func() bool; HasDeniedRewardTokensStoreKey func() bool; HasDepositGnsAmountStoreKey func() bool; HasDepositsStoreKey func() bool; HasExternalIncentivesStoreKey func() bool; HasIncentiveCounterStoreKey func() bool; HasMinimumRewardAmountStoreKey func() bool; HasPendingProtocolFeesStoreKey func() bool; HasPoolTierCountsStoreKey func() bool; HasPoolTierCurrentEmissionStoreKey func() bool; HasPoolTierGetEmissionStoreKey func() bool; HasPoolTierGetHalvingBlocksInRangeStoreKey func() bool; HasPoolTierLastRewardCacheTimestampStoreKey func() bool; HasPoolTierMembershipsStoreKey func() bool; HasPoolTierRatioStoreKey func() bool; HasPoolsStoreKey func() bool; HasTokenSpecificMinimumRewardsStoreKey func() bool; HasTotalEmissionSentStoreKey func() bool; HasUncollectedIncentiveCountsStoreKey func() bool; HasUnstakedPositionsStoreKey func() bool; HasUnstakingFeeStoreKey func() bool; HasWarmupTemplateStoreKey func() bool; NextIncentiveID func(.uverse.address, int64) string; RemoveAllowedToken func(int, .uverse.realm, string) .uverse.error; RemoveDeniedRewardToken func(int, .uverse.realm, string) .uverse.error; RemovePendingProtocolFee func(int, .uverse.realm, string) .uverse.error; RemoveTokenSpecificMinimumRewardItem func(int, .uverse.realm, string) .uverse.error; SetAllowedTokens func(int, .uverse.realm, []string) .uverse.error; SetCurrentSwapBatch func(int, .uverse.realm, *gno.land/r/gnoswap/staker.SwapBatchProcessor) .uverse.error; SetDepositGnsAmount func(int, .uverse.realm, int64) .uverse.error; SetDeposits func(int, .uverse.realm, *gno.land/p/nt/bptree/v0.BPTree) .uverse.error; SetExternalIncentives func(int, .uverse.realm, *gno.land/p/nt/bptree/v0.BPTree) .uverse.error; SetIncentiveCounter func(int, .uverse.realm, *gno.land/r/gnoswap/staker.Counter) .uverse.error; SetMinimumRewardAmount func(int, .uverse.realm, int64) .uverse.error; SetPendingProtocolFee func(int, .uverse.realm, string, int64) .uverse.error; SetPendingProtocolFees func(int, .uverse.realm, map[string]int64) .uverse.error; SetPoolTierCounts func(int, .uverse.realm, [4]uint64) .uverse.error; SetPoolTierCurrentEmission func(int, .uverse.realm, int64) .uverse.error; SetPoolTierGetEmission func(int, .uverse.realm, func() (int64, .uverse.error)) .uverse.error; SetPoolTierGetHalvingBlocksInRange func(int, .uverse.realm, func(int64, int64) ([]int64, []int64, .uverse.error)) .uverse.error; SetPoolTierLastRewardCacheTimestamp func(int, .uverse.realm, int64) .uverse.error; SetPoolTierMemberships func(int, .uverse.realm, *gno.land/p/nt/bptree/v0.BPTree) .uverse.error; SetPoolTierRatio func(int, .uverse.realm, gno.land/r/gnoswap/staker.TierRatio) .uverse.error; SetPools func(int, .uverse.realm, *gno.land/p/nt/bptree/v0.BPTree) .uverse.error; SetTokenSpecificMinimumRewardItem func(int, .uverse.realm, string, int64) .uverse.error; SetTokenSpecificMinimumRewards func(int, .uverse.realm, map[string]int64) .uverse.error; SetTotalEmissionSent func(int, .uverse.realm, int64) .uverse.error; SetUncollectedIncentiveCounts func(int, .uverse.realm, *gno.land/p/nt/bptree/v0.BPTree) .uverse.error; SetUnstakedPositions func(int, .uverse.realm, *gno.land/p/nt/bptree/v0.BPTree) .uverse.error; SetUnstakingFee func(int, .uverse.realm, uint64) .uverse.error; SetWarmupTemplate func(int, .uverse.realm, []gno.land/r/gnoswap/staker.Warmup) .uverse.error}
NewSwapBatchProcessor (poolPath string, pool *gno.land/r/gnoswap/staker.Pool, timestamp int64) *gno.land/r/gnoswap/staker.SwapBatchProcessor
NewSwapTickCross (tickID int32, zeroForOne bool, delta *gno.land/p/gnoswap/int256/v1.Int) *gno.land/r/gnoswap/staker.SwapTickCross
NewTick (tickId int32) *gno.land/r/gnoswap/staker.Tick
NewTicks () struct{tree *gno.land/p/nt/bptree/v0.BPTree}
NewTierRatio (tier1 uint64, tier2 uint64, tier3 uint64) struct{Tier1 uint64; Tier2 uint64; Tier3 uint64}
NewUintTree () *gno.land/r/gnoswap/staker.UintTree
NewUintTreeN (fanout int) *gno.land/r/gnoswap/staker.UintTree
NewUnstakedPosition (deposit *gno.land/r/gnoswap/staker.Deposit, exitTime int64, exitTick int32, lowerTick *gno.land/r/gnoswap/staker.Tick, upperTick *gno.land/r/gnoswap/staker.Tick, lowerOutsideAcc string, upperOutsideAcc string, tier uint64, tierRatio uint64, tierCount uint64, unstakingFee uint64, pendingIncentiveIds []string) *gno.land/r/gnoswap/staker.UnstakedPosition
NewWarmup (timeDuration int64, nextWarmupTime int64, warmupRatio uint64) struct{TimeDuration int64; NextWarmupTime int64; WarmupRatio uint64}
RegisterInitializer (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, initializer func(int, .uverse.realm, gno.land/r/gnoswap/staker.IStakerStore, gno.land/r/gnoswap/staker.PoolAccessor, gno.land/r/gnoswap/staker.EmissionAccessor, gno.land/r/gnoswap/staker.NFTAccessor) gno.land/r/gnoswap/staker.IStaker)
RemovePoolTier (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, poolPath string)
RemoveToken (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, tokenPath string)
Render (path string) string
SetDeniedRewardToken (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, tokenPath string, denied bool)
SetDepositGnsAmount (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, amount int64)
SetMinimumRewardAmount (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, amount int64)
SetPoolTier (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, poolPath string, tier uint64)
SetTokenMinimumRewardAmount (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, paramsStr string)
SetUnStakingFee (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, fee uint64)
SetWarmUp (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, pct int64, timeDuration int64)
StakeToken (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, positionId uint64, referrer string) string
UnStakeToken (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, positionId uint64) string
UpgradeImpl (cur interface {.seal func(); Address func() .uverse.address; IsCode func() bool; IsCurrent func() bool; IsEphemeral func() bool; IsUser func() bool; IsUserCall func() bool; IsUserRun func() bool; PkgPath func() string; Previous func() .uverse.realm; String func() string; Sub func(string) .uverse.realm; Subpath func() string}, packagePath string)
Signatures reconstructed verbatim from vm/qfuncs — interface params keep their inline definitions.
i256 "gno.land/p/gnoswap/int256/v1"
9 u256 "gno.land/p/gnoswap/uint256/v1"
10 "gno.land/p/gnoswap/utils/v1"
11 bptree "gno.land/p/nt/bptree/v0"
12 ufmt "gno.land/p/nt/ufmt/v0"
13 )
14
15 const AllTierCount = 4 // 0, 1, 2, 3
16
17 // Pool is a struct for storing an incentivized pool information
18 // Each pool stores Incentives and Ticks associated with it.
19 //
20 // Fields:
21 // - poolPath: The path of the pool.
22 //
23 // - stakedLiquidity:
24 // The current total staked liquidity of the in-range positions for the pool.
25 // Updated when tick cross happens or stake/unstake happens.
26 // Used to calculate the global reward ratio accumulation or
27 // decide whether to enter/exit unclaimable period.
28 //
29 // - lastUnclaimableTime:
30 // The time at which the unclaimable period started.
31 // Set to 0 when the pool is not in an unclaimable period.
32 //
33 // - unclaimableAcc:
34 // The accumulated undistributed unclaimable reward.
35 // Reset to 0 when processUnclaimableReward is called and sent to community pool.
36 //
37 // - rewardCache:
38 // The cached per-second reward emitted for this pool.
39 // Stores new entry only when the reward is changed.
40 // PoolTier.cacheReward() updates this.
41 //
42 // - incentives: The external incentives associated with the pool.
43 //
44 // - ticks: The Ticks associated with the pool.
45 //
46 // - globalRewardRatioAccumulation:
47 // Global ratio of Time / TotalStake accumulation(since the pool creation)
48 // Stores new entry only when tick cross or stake/unstake happens.
49 // It is used to calculate the reward for a staked position at certain time.
50 //
51 // - historicalTick:
52 // The historical tick for the pool at a given time.
53 // It does not reflect the exact tick at the timestamp,
54 // but it provides correct ordering for the staked position's ticks.
55 // Therefore, you should not compare it for equality, only for ordering.
56 // Set when tick cross happens or a new position is created.
57 type Pool struct {
58 poolPath string
59
60 stakedLiquidity *UintTree // uint64 timestamp -> *u256.Uint(Q128)
61
62 lastUnclaimableTime int64
63 unclaimableAcc int64
64
65 rewardCache *UintTree // uint64 timestamp -> int64 gnsReward
66
67 incentives *Incentives
68
69 ticks Ticks // int32 tickId -> Tick tick
70
71 globalRewardRatioAccumulation *UintTree // uint64 timestamp -> *u256.Uint(Q128) rewardRatioAccumulation
72
73 historicalTick *UintTree // uint64 timestamp -> int32 tickId
74 }
75
76 // Pool Getter/Setter methods
77
78 // PoolPath returns the pool path
79 //
80 // Returns:
81 // - path: Pool identifier used to associate this state with a liquidity pool.
82 func (p *Pool) PoolPath() string {
83 return p.poolPath
84 }
85
86 // SetPoolPath sets the pool path
87 //
88 // Parameters:
89 // - poolPath: Pool identifier to store.
90 func (p *Pool) SetPoolPath(poolPath string ) {
91 p.poolPath = poolPath
92 }
93
94 // StakedLiquidity returns the staked liquidity tree
95 //
96 // Returns:
97 // - tree: Historical staked-liquidity tree keyed by Unix timestamp, with Q128-scaled liquidity values.
98 func (p *Pool) StakedLiquidity() *UintTree {
99 return p.stakedLiquidity
100 }
101
102 // SetStakedLiquidity sets the staked liquidity tree
103 //
104 // Parameters:
105 // - stakedLiquidity: Tree of historical total staked liquidity snapshots.
106 func (p *Pool) SetStakedLiquidity(stakedLiquidity *UintTree) {
107 p.stakedLiquidity = stakedLiquidity
108 }
109
110 // SetStakedLiquidityAt records the current total staked liquidity at a timestamp.
111 //
112 // Parameters:
113 // - currentTime: Nonnegative Unix timestamp in seconds used as the snapshot key.
114 // - delta: Total staked liquidity at currentTime, stored as a copied Q128-scaled uint value.
115 func (p *Pool) SetStakedLiquidityAt(currentTime int64 , delta *u256.Uint) {
116 p.StakedLiquidity().Set(currentTime, u256.Zero().Set(delta))
117 }
118
119 // LastUnclaimableTime returns the last unclaimable time
120 //
121 // Returns:
122 // - timestamp: Unix timestamp in seconds at which the pool entered its current unclaimable period, or 0 when tracking has not started.
123 func (p *Pool) LastUnclaimableTime() int64 {
124 return p.lastUnclaimableTime
125 }
126
127 // SetLastUnclaimableTime sets the last unclaimable time
128 //
129 // Parameters:
130 // - lastUnclaimableTime: Unix timestamp in seconds marking the start of the current unclaimable period; use 0 when no period is active.
131 func (p *Pool) SetLastUnclaimableTime(lastUnclaimableTime int64 ) {
132 p.lastUnclaimableTime = lastUnclaimableTime
133 }
134
135 // UnclaimableAcc returns the unclaimable accumulation
136 //
137 // Returns:
138 // - amount: Accumulated undistributed unclaimable reward amount in the pool's int64 reward units.
139 func (p *Pool) UnclaimableAcc() int64 {
140 return p.unclaimableAcc
141 }
142
143 // SetUnclaimableAcc sets the unclaimable accumulation
144 //
145 // Parameters:
146 // - unclaimableAcc: Accumulated undistributed unclaimable reward amount in the pool's int64 reward units.
147 func (p *Pool) SetUnclaimableAcc(unclaimableAcc int64 ) {
148 p.unclaimableAcc = unclaimableAcc
149 }
150
151 // RewardCache returns the reward cache tree
152 //
153 // Returns:
154 // - tree: Historical per-second GNS reward cache keyed by Unix timestamp.
155 func (p *Pool) RewardCache() *UintTree {
156 return p.rewardCache
157 }
158
159 // SetRewardCache sets the reward cache tree
160 //
161 // Parameters:
162 // - rewardCache: Tree containing the pool's per-second GNS reward snapshots.
163 func (p *Pool) SetRewardCache(rewardCache *UintTree) {
164 p.rewardCache = rewardCache
165 }
166
167 // SetRewardCacheAt records the per-second reward rate for a timestamp.
168 //
169 // Parameters:
170 // - currentTime: Nonnegative Unix timestamp in seconds used as the cache key.
171 // - reward: GNS reward emitted per second from currentTime until the next cached change.
172 func (p *Pool) SetRewardCacheAt(currentTime int64 , reward int64 ) {
173 p.RewardCache().Set(currentTime, reward)
174 }
175
176 // Incentives returns the incentives
177 //
178 // Returns:
179 // - incentives: External-incentive collection associated with this pool.
180 func (p *Pool) Incentives() *Incentives {
181 return p.incentives
182 }
183
184 // SetIncentives sets the incentives
185 //
186 // Parameters:
187 // - incentives: External-incentive collection to associate with the pool.
188 func (p *Pool) SetIncentives(incentives *Incentives) {
189 p.incentives = incentives
190 }
191
192 // Ticks returns the ticks
193 //
194 // Returns:
195 // - ticks: Addressable tick mapping for this pool's staked positions.
196 func (p *Pool) Ticks() *Ticks {
197 return &p.ticks
198 }
199
200 // SetTicks sets the ticks
201 //
202 // Parameters:
203 // - ticks: Tick mapping value to store in the pool.
204 func (p *Pool) SetTicks(ticks Ticks) {
205 p.ticks = ticks
206 }
207
208 // GlobalRewardRatioAccumulation returns the global reward ratio accumulation tree
209 //
210 // Returns:
211 // - tree: Historical global time-per-total-stake accumulation keyed by Unix timestamp.
212 func (p *Pool) GlobalRewardRatioAccumulation() *UintTree {
213 return p.globalRewardRatioAccumulation
214 }
215
216 // SetGlobalRewardRatioAccumulation sets the global reward ratio accumulation tree
217 //
218 // Parameters:
219 // - globalRewardRatioAccumulation: Tree of serialized Q128-scaled reward-ratio accumulation snapshots.
220 func (p *Pool) SetGlobalRewardRatioAccumulation(globalRewardRatioAccumulation *UintTree) {
221 p.globalRewardRatioAccumulation = globalRewardRatioAccumulation
222 }
223
224 // SetGlobalRewardRatioAccumulationAt records a serialized global reward-ratio accumulation snapshot.
225 //
226 // Parameters:
227 // - currentTime: Nonnegative Unix timestamp in seconds used as the snapshot key.
228 // - acc: Serialized Q128-scaled global reward-ratio accumulation value.
229 func (p *Pool) SetGlobalRewardRatioAccumulationAt(currentTime int64 , acc string ) {
230 p.GlobalRewardRatioAccumulation().Set(currentTime, acc)
231 }
232
233 // HistoricalTick returns the historical tick tree
234 //
235 // Returns:
236 // - tree: Historical tick-ID ordering snapshots keyed by Unix timestamp.
237 func (p *Pool) HistoricalTick() *UintTree {
238 return p.historicalTick
239 }
240
241 // SetHistoricalTick sets the historical tick tree
242 //
243 // Parameters:
244 // - historicalTick: Tree of tick IDs representing the ordering history of staked positions.
245 func (p *Pool) SetHistoricalTick(historicalTick *UintTree) {
246 p.historicalTick = historicalTick
247 }
248
249 // SetHistoricalTickAt records the tick ordering snapshot for a timestamp.
250 //
251 // Parameters:
252 // - currentTime: Nonnegative Unix timestamp in seconds used as the snapshot key.
253 // - tick: Tick ID representing the pool's historical ordering at currentTime.
254 func (p *Pool) SetHistoricalTickAt(currentTime int64 , tick int32 ) {
255 p.HistoricalTick().Set(currentTime, tick)
256 }
257
258 // Clone returns a pool copy of the scalar state with a fresh tick container.
259 //
260 // Returns:
261 // - pool: Pool copy carrying scalar state and a fresh tick container; backing trees and incentives are nil, and nil receiver yields nil.
262 func (p *Pool) Clone() *Pool {
263 if p == nil {
264 return nil
265 }
266
267 return &Pool{
268 poolPath: p.poolPath,
269 stakedLiquidity: nil ,
270 lastUnclaimableTime: p.lastUnclaimableTime,
271 unclaimableAcc: p.unclaimableAcc,
272 rewardCache: nil ,
273 incentives: nil ,
274 ticks: NewTicks(),
275 globalRewardRatioAccumulation: nil ,
276 historicalTick: nil ,
277 }
278 }
279
280 // NewPool creates pool reward state initialized at currentTime (Unix seconds).
281 //
282 // Parameters:
283 // - poolPath: Pool identifier to store in the new reward-state object.
284 // - currentTime: Unix timestamp in seconds used to seed the initial accumulation, reward-cache, and liquidity snapshots.
285 //
286 // Returns:
287 // - pool: Initialized pool with empty backing structures and zero initial reward/liquidity snapshots at currentTime.
288 func NewPool(poolPath string , currentTime int64 ) *Pool {
289 pool := &Pool{
290 poolPath: poolPath,
291 stakedLiquidity: NewUintTreeN( 64 ),
292 // lastUnclaimableTime is initialized to 0, which means "tracking not started yet".
293 // When the pool receives a tier assignment (or external incentive), `cacheReward` will be called,
294 // which will automatically call `startUnclaimablePeriod` if the pool has zero liquidity.
295 // This ensures proper unclaimable period tracking from the moment rewards start emitting.
296 lastUnclaimableTime: 0 ,
297 unclaimableAcc: 0 ,
298 rewardCache: NewUintTreeN( 64 ),
299 incentives: NewIncentives(poolPath),
300 ticks: NewTicks(),
301 globalRewardRatioAccumulation: NewUintTreeN( 64 ),
302 historicalTick: NewUintTreeN( 64 ),
303 }
304
305 pool.SetGlobalRewardRatioAccumulationAt(currentTime, "0" )
306
307 // Initialize rewardCache to 0 to ensure `cacheReward` will trigger on first tier assignment
308 pool.SetRewardCacheAt(currentTime, int64 ( 0 ))
309 pool.SetStakedLiquidityAt(currentTime, u256.Zero())
310
311 return pool
312 }
313
314 // Incentives represents a collection of external incentives for a specific pool.
315 //
316 // Fields:
317 //
318 // - incentives: BPTree storing ExternalIncentive objects indexed by incentiveId
319 // The incentiveId serves as the key to efficiently lookup incentive details
320 //
321 // - targetPoolPath: String identifier for the pool this incentive collection belongs to
322 // Used to associate incentives with their corresponding liquidity pool
323 //
324 // - unclaimablePeriods: Tree storing periods when rewards cannot be claimed
325 // Maps start timestamp (key) to end timestamp (value)
326 // An end timestamp of 0 indicates an ongoing unclaimable period
327 // Used to track intervals when staking rewards are not claimable
328 //
329 // - byStartTime: Per-pool start-time index mapping an incentive's start
330 // timestamp (key) to the incentive IDs that start at that timestamp
331 // (value). This mirrors the lazy-discovery lookup previously served by a
332 // global creation-time index, but scoped to this pool's own incentives, so
333 // discovery cost is bounded by this pool's incentives instead of growing
334 // with the total number of incentives system-wide.
335 type Incentives struct {
336 incentives *bptree.BPTree // (incentiveId) => ExternalIncentive
337
338 targetPoolPath string // The target pool path for this incentive collection
339
340 unclaimablePeriods *UintTree // blockTimestamp -> any
341
342 byStartTime *UintTree // startTimestamp -> []incentiveId
343 }
344
345 // Incentives Getter/Setter methods
346
347 // Incentives returns the incentives tree
348 //
349 // Returns:
350 // - tree: Mutable B+ tree mapping incentive IDs to ExternalIncentive records.
351 func (i *Incentives) IncentiveTrees() *bptree.BPTree {
352 return i.incentives
353 }
354
355 // SetIncentives sets the incentives tree
356 //
357 // Parameters:
358 // - incentives: B+ tree to use for incentive ID lookups and storage.
359 func (i *Incentives) SetIncentives(incentives *bptree.BPTree) {
360 i.incentives = incentives
361 }
362
363 // TargetPoolPath returns the target pool path
364 //
365 // Returns:
366 // - path: Pool path to which this incentive collection belongs.
367 func (i *Incentives) TargetPoolPath() string {
368 return i.targetPoolPath
369 }
370
371 // SetTargetPoolPath sets the target pool path
372 //
373 // Parameters:
374 // - targetPoolPath: Pool path to associate with this incentive collection.
375 func (i *Incentives) SetTargetPoolPath(targetPoolPath string ) {
376 i.targetPoolPath = targetPoolPath
377 }
378
379 // UnclaimablePeriods returns the unclaimable periods tree
380 //
381 // Returns:
382 // - periods: Tree mapping unclaimable-period start timestamps to end timestamps; end 0 denotes an open period.
383 func (i *Incentives) UnclaimablePeriods() *UintTree {
384 return i.unclaimablePeriods
385 }
386
387 // SetUnclaimablePeriods sets the unclaimable periods tree
388 //
389 // Parameters:
390 // - unclaimablePeriods: Tree of reward-unclaimable intervals keyed by their start timestamps.
391 func (i *Incentives) SetUnclaimablePeriods(unclaimablePeriods *UintTree) {
392 i.unclaimablePeriods = unclaimablePeriods
393 }
394
395 // Incentive returns an incentive by ID
396 //
397 // Parameters:
398 // - incentiveId: Identifier used to look up the external incentive record.
399 //
400 // Returns:
401 // - incentive: Matching ExternalIncentive pointer, or nil when no value is stored for incentiveId.
402 // - found: True only when the stored value has ExternalIncentive type; false for a missing or mismatched value.
403 func (i *Incentives) Incentive(incentiveId string ) (*ExternalIncentive, bool ) {
404 value := i.incentives.Get(incentiveId)
405 if value == nil {
406 return nil , false
407 }
408 incentive, ok := value.(*ExternalIncentive)
409 return incentive, ok
410 }
411
412 // SetIncentive sets an incentive by ID
413 //
414 // Parameters:
415 // - incentiveId: Identifier under which to store the incentive.
416 // - incentive: ExternalIncentive record to store for incentiveId.
417 func (i *Incentives) SetIncentive(incentiveId string , incentive *ExternalIncentive) {
418 i.incentives.Set(incentiveId, incentive)
419 }
420
421 // RemoveIncentive deletes an incentive by ID.
422 //
423 // Only an incentive that never started may be removed: once rewards begin
424 // accruing, deposits and the refund accounting reference the record, so an
425 // ended incentive is marked refunded instead of removed.
426 //
427 // Parameters:
428 // - incentiveId: Identifier of the external incentive record to remove.
429 func (i *Incentives) RemoveIncentive(incentiveId string ) {
430 i.incentives.Remove(incentiveId)
431 }
432
433 // SetUnclaimablePeriod records an interval during which staking rewards cannot be claimed.
434 //
435 // Parameters:
436 // - startTimestamp: Nonnegative Unix timestamp in seconds at which the interval begins.
437 // - endTimestamp: Unix timestamp in seconds at which the interval ends; 0 records an ongoing interval.
438 func (i *Incentives) SetUnclaimablePeriod(startTimestamp int64 , endTimestamp int64 ) {
439 i.unclaimablePeriods.Set(startTimestamp, endTimestamp)
440 }
441
442 // RemoveUnclaimablePeriod removes the interval keyed by its start timestamp.
443 //
444 // Parameters:
445 // - startTimestamp: Nonnegative Unix timestamp in seconds identifying the interval to remove.
446 func (i *Incentives) RemoveUnclaimablePeriod(startTimestamp int64 ) {
447 i.unclaimablePeriods.Remove(startTimestamp)
448 }
449
450 // IterateIncentives iterates over all incentives
451 //
452 // Parameters:
453 // - fn: Callback receiving each incentive ID and record; returning true requests that iteration stop.
454 func (i *Incentives) IterateIncentives(fn func (incentiveId string , incentive *ExternalIncentive) bool ) {
455 i.incentives.Iterate( "" , "" , func (key string , value interface {}) bool {
456 if incentive, ok := value.(*ExternalIncentive); ok {
457 return fn(key, incentive)
458 }
459 return false
460 })
461 }
462
463 // AddIncentiveByStartTime registers an incentive ID under its start timestamp
464 // in the per-pool start-time index. Multiple incentives starting at the same
465 // timestamp are accumulated as a list.
466 //
467 // Parameters:
468 // - startTimestamp: Nonnegative Unix timestamp in seconds used as the start-time index key.
469 // - incentiveId: Incentive identifier to append to that timestamp's bucket.
470 func (i *Incentives) AddIncentiveByStartTime(startTimestamp int64 , incentiveId string ) {
471 var incentiveIds [] string
472 if value, ok := i.byStartTime.Get(startTimestamp); ok {
473 if ids, ok := value.([] string ); ok {
474 incentiveIds = ids
475 }
476 }
477 incentiveIds = append(incentiveIds, incentiveId)
478 i.byStartTime.Set(startTimestamp, incentiveIds)
479 }
480
481 // RemoveIncentiveByStartTime unregisters an incentive ID from the per-pool
482 // start-time index. The bucket itself is dropped once its last ID is removed,
483 // so the index never keeps an empty entry that discovery would still visit.
484 //
485 // Parameters:
486 // - startTimestamp: Nonnegative Unix timestamp in seconds identifying the start-time bucket.
487 // - incentiveId: Incentive identifier to remove from that bucket; all matching entries are omitted.
488 func (i *Incentives) RemoveIncentiveByStartTime(startTimestamp int64 , incentiveId string ) {
489 value, ok := i.byStartTime.Get(startTimestamp)
490 if !ok {
491 return
492 }
493
494 ids, ok := value.([] string )
495 if !ok {
496 return
497 }
498
499 remaining := make([] string , 0 , len(ids))
500 for _, id := range ids {
501 if id == incentiveId {
502 continue
503 }
504 remaining = append(remaining, id)
505 }
506
507 if len(remaining) == 0 {
508 i.byStartTime.Remove(startTimestamp)
509 return
510 }
511
512 i.byStartTime.Set(startTimestamp, remaining)
513 }
514
515 // IterateIncentiveIdsByTime iterates over the incentive IDs that start within
516 // the inclusive [startTime, endTime] range, visiting only the buckets that
517 // fall in the range. ReverseIterate is used because it is inclusive on both
518 // ends, matching the discovery semantics previously implemented as
519 // (startTimestamp >= startTime && startTimestamp <= endTime).
520 //
521 // Parameters:
522 // - startTime: Inclusive lower Unix timestamp bound for incentive starts.
523 // - endTime: Inclusive upper Unix timestamp bound for incentive starts.
524 // - fn: Callback receiving each matching incentive ID; returning true requests that iteration stop.
525 func (i *Incentives) IterateIncentiveIdsByTime(startTime, endTime int64 , fn func (incentiveId string ) bool ) {
526 i.byStartTime.ReverseIterate(startTime, endTime, func (_ int64 , value any ) bool {
527 incentiveIds, ok := value.([] string )
528 if !ok {
529 return false
530 }
531 for _, incentiveId := range incentiveIds {
532 if fn(incentiveId) {
533 return true
534 }
535 }
536 return false
537 })
538 }
539
540 // NewIncentives creates an incentive collection for a pool and starts an open unclaimable period at the current time.
541 //
542 // Parameters:
543 // - targetPoolPath: Pool path to associate with the new incentive collection.
544 //
545 // Returns:
546 // - incentives: Collection with initialized incentive, start-time, and unclaimable-period trees.
547 func NewIncentives(targetPoolPath string ) *Incentives {
548 result := &Incentives{
549 targetPoolPath: targetPoolPath,
550 unclaimablePeriods: NewUintTreeN( 64 ),
551 incentives: bptree.NewBPTreeN( 16 ),
552 byStartTime: NewUintTreeN( 64 ),
553 }
554
555 // initial unclaimable period starts, as there cannot be any staked positions yet.
556 currentTimestamp := time.Now().Unix()
557 result.SetUnclaimablePeriod(currentTimestamp, int64 ( 0 ))
558 return result
559 }
560
561 type ExternalIncentive struct {
562 incentiveId string // incentive id
563 startTimestamp int64 // start time for external reward
564 endTimestamp int64 // end time for external reward
565 createdHeight int64 // block height when the incentive was created
566 createdTimestamp int64 // timestamp when the incentive was created
567 depositGnsAmount int64 // deposited gns amount
568 targetPoolPath string // external reward target pool path
569 rewardToken string // external reward token path
570 totalRewardAmount int64 // total reward amount
571 rewardAmount int64 // mutable remaining reward amount
572 rewardPerSecondX128 *u256.Uint // reward per second, scaled by 2^128 to preserve sub-second precision
573 distributedRewardAmount int64 // reward amount delivered to positions or refunded at incentive end
574 accumulatedPenaltyAmount int64 // accumulated warmup penalty from CollectReward
575 creator address // creator address
576
577 refunded bool // whether EndExternalIncentive finalized the incentive and returned its refundable portion and GNS deposit
578
579 unclaimableSeconds int64 // accumulated seconds of unclaimable periods overlapping the incentive window
580 }
581
582 // ExternalIncentive Getter/Setter methods
583
584 // IncentiveId returns the incentive ID
585 //
586 // Returns:
587 // - id: Identifier assigned to this external incentive.
588 func (e *ExternalIncentive) IncentiveId() string {
589 return e.incentiveId
590 }
591
592 // SetIncentiveId sets the incentive ID
593 //
594 // Parameters:
595 // - incentiveId: Identifier to store on the incentive record.
596 func (e *ExternalIncentive) SetIncentiveId(incentiveId string ) {
597 e.incentiveId = incentiveId
598 }
599
600 // StartTimestamp returns the start timestamp.
601 //
602 // It keys the byStartTime discovery index and must stay immutable after the
603 // incentive is registered, so no setter is exposed.
604 //
605 // Returns:
606 // - timestamp: Unix timestamp in seconds at which reward distribution starts.
607 func (e *ExternalIncentive) StartTimestamp() int64 {
608 return e.startTimestamp
609 }
610
611 // EndTimestamp returns the end timestamp
612 //
613 // Returns:
614 // - timestamp: Unix timestamp in seconds at which the incentive window ends.
615 func (e *ExternalIncentive) EndTimestamp() int64 {
616 return e.endTimestamp
617 }
618
619 // SetEndTimestamp sets the end timestamp
620 //
621 // Parameters:
622 // - endTimestamp: Unix timestamp in seconds at which the incentive window ends.
623 func (e *ExternalIncentive) SetEndTimestamp(endTimestamp int64 ) {
624 e.endTimestamp = endTimestamp
625 }
626
627 // CreatedHeight returns the created height
628 //
629 // Returns:
630 // - height: Block height at which the incentive record was created.
631 func (e *ExternalIncentive) CreatedHeight() int64 {
632 return e.createdHeight
633 }
634
635 // SetCreatedHeight sets the created height
636 //
637 // Parameters:
638 // - createdHeight: Block height to record as the incentive's creation height.
639 func (e *ExternalIncentive) SetCreatedHeight(createdHeight int64 ) {
640 e.createdHeight = createdHeight
641 }
642
643 // CreatedTimestamp returns the created timestamp
644 //
645 // Returns:
646 // - timestamp: Unix timestamp in seconds at which the incentive record was created.
647 func (e *ExternalIncentive) CreatedTimestamp() int64 {
648 return e.createdTimestamp
649 }
650
651 // SetCreatedTimestamp sets the created timestamp
652 //
653 // Parameters:
654 // - createdTimestamp: Unix timestamp in seconds to record as the incentive creation time.
655 func (e *ExternalIncentive) SetCreatedTimestamp(createdTimestamp int64 ) {
656 e.createdTimestamp = createdTimestamp
657 }
658
659 // DepositGnsAmount returns the deposit GNS amount
660 //
661 // Returns:
662 // - amount: GNS amount deposited to back this external incentive.
663 func (e *ExternalIncentive) DepositGnsAmount() int64 {
664 return e.depositGnsAmount
665 }
666
667 // SetDepositGnsAmount sets the deposit GNS amount
668 //
669 // Parameters:
670 // - depositGnsAmount: GNS amount deposited to back this external incentive.
671 func (e *ExternalIncentive) SetDepositGnsAmount(depositGnsAmount int64 ) {
672 e.depositGnsAmount = depositGnsAmount
673 }
674
675 // TargetPoolPath returns the target pool path
676 //
677 // Returns:
678 // - path: Pool path targeted by this external incentive.
679 func (e *ExternalIncentive) TargetPoolPath() string {
680 return e.targetPoolPath
681 }
682
683 // SetTargetPoolPath sets the target pool path
684 //
685 // Parameters:
686 // - targetPoolPath: Pool path to target with this external incentive.
687 func (e *ExternalIncentive) SetTargetPoolPath(targetPoolPath string ) {
688 e.targetPoolPath = targetPoolPath
689 }
690
691 // RewardToken returns the reward token
692 //
693 // Returns:
694 // - token: Reward-token path distributed by this incentive.
695 func (e *ExternalIncentive) RewardToken() string {
696 return e.rewardToken
697 }
698
699 // SetRewardToken sets the reward token
700 //
701 // Parameters:
702 // - rewardToken: Token path of the reward asset distributed by this incentive.
703 func (e *ExternalIncentive) SetRewardToken(rewardToken string ) {
704 e.rewardToken = rewardToken
705 }
706
707 // TotalRewardAmount returns the total reward amount
708 //
709 // Returns:
710 // - amount: Total reward amount configured when the incentive was created.
711 func (e *ExternalIncentive) TotalRewardAmount() int64 {
712 return e.totalRewardAmount
713 }
714
715 // SetTotalRewardAmount sets the total reward amount
716 //
717 // Parameters:
718 // - totalRewardAmount: Total reward amount to record for the incentive.
719 func (e *ExternalIncentive) SetTotalRewardAmount(totalRewardAmount int64 ) {
720 e.totalRewardAmount = totalRewardAmount
721 }
722
723 // RewardAmount returns the reward amount
724 //
725 // Returns:
726 // - amount: Mutable reward amount remaining after distributions and refunds.
727 func (e *ExternalIncentive) RewardAmount() int64 {
728 return e.rewardAmount
729 }
730
731 // SetRewardAmount sets the reward amount
732 //
733 // Parameters:
734 // - rewardAmount: Remaining reward amount to store after accounting adjustments.
735 func (e *ExternalIncentive) SetRewardAmount(rewardAmount int64 ) {
736 e.rewardAmount = rewardAmount
737 }
738
739 // RewardPerSecondX128 returns the Q128-scaled reward per second.
740 // The underlying value is (rewardAmount << 128) / duration.
741 //
742 // Returns:
743 // - rate: Reward emitted per second, scaled by 2^128 for fixed-point accounting.
744 func (e *ExternalIncentive) RewardPerSecondX128() *u256.Uint {
745 return e.rewardPerSecondX128
746 }
747
748 // SetRewardPerSecondX128 sets the Q128-scaled reward per second.
749 //
750 // Parameters:
751 // - rewardPerSecondX128: Q128-scaled per-second reward rate; the value is copied before storage.
752 func (e *ExternalIncentive) SetRewardPerSecondX128(rewardPerSecondX128 *u256.Uint) {
753 e.rewardPerSecondX128 = u256.Zero().Set(rewardPerSecondX128)
754 }
755
756 // DistributedRewardAmount returns the distributed reward amount
757 //
758 // Returns:
759 // - amount: Reward amount already delivered to positions or refunded at incentive end.
760 func (e *ExternalIncentive) DistributedRewardAmount() int64 {
761 return e.distributedRewardAmount
762 }
763
764 // SetDistributedRewardAmount sets the distributed reward amount
765 //
766 // Parameters:
767 // - distributedRewardAmount: Reward amount delivered to positions or refunded at incentive end.
768 func (e *ExternalIncentive) SetDistributedRewardAmount(distributedRewardAmount int64 ) {
769 e.distributedRewardAmount = distributedRewardAmount
770 }
771
772 // AccumulatedPenaltyAmount returns the accumulated warmup penalty amount
773 //
774 // Returns:
775 // - amount: Warm-up penalty accumulated from reward collections for this incentive.
776 func (e *ExternalIncentive) AccumulatedPenaltyAmount() int64 {
777 return e.accumulatedPenaltyAmount
778 }
779
780 // SetAccumulatedPenaltyAmount sets the accumulated warmup penalty amount
781 //
782 // Parameters:
783 // - accumulatedPenaltyAmount: Warm-up penalty amount to store in the incentive's accumulated accounting.
784 func (e *ExternalIncentive) SetAccumulatedPenaltyAmount(accumulatedPenaltyAmount int64 ) {
785 e.accumulatedPenaltyAmount = accumulatedPenaltyAmount
786 }
787
788 // Creator returns the creator address
789 //
790 // Returns:
791 // - creator: Address that created and funded the incentive.
792 func (e *ExternalIncentive) Creator() address {
793 return e.creator
794 }
795
796 // SetCreator sets the creator address
797 //
798 // Parameters:
799 // - creator: Address to record as the incentive creator and refund recipient.
800 func (e *ExternalIncentive) SetCreator(creator address) {
801 e.creator = creator
802 }
803
804 // Refunded returns the refunded status
805 //
806 // Returns:
807 // - refunded: True when incentive finalization has marked its refundable balances as returned.
808 func (e *ExternalIncentive) Refunded() bool {
809 return e.refunded
810 }
811
812 // SetRefunded sets the refunded status
813 //
814 // Parameters:
815 // - refunded: Finalization status to store for the incentive.
816 func (e *ExternalIncentive) SetRefunded(refunded bool ) {
817 e.refunded = refunded
818 }
819
820 // UnclaimableSeconds returns the accumulated seconds of unclaimable periods
821 // that overlap the incentive window. It is updated whenever an unclaimable
822 // period closes and is backfilled once from the historical unclaimable
823 // periods tree after an upgrade.
824 //
825 // Returns:
826 // - seconds: Accumulated seconds of unclaimable periods overlapping the incentive window.
827 func (e *ExternalIncentive) UnclaimableSeconds() int64 {
828 return e.unclaimableSeconds
829 }
830
831 // SetUnclaimableSeconds sets the accumulated unclaimable seconds.
832 //
833 // Parameters:
834 // - unclaimableSeconds: Overlapping unclaimable duration in seconds to store.
835 func (e *ExternalIncentive) SetUnclaimableSeconds(unclaimableSeconds int64 ) {
836 e.unclaimableSeconds = unclaimableSeconds
837 }
838
839 // Clone returns an independent ExternalIncentive value with scalar fields copied and its fixed-point rate duplicated.
840 //
841 // Returns:
842 // - incentive: Copied external incentive record; its fixed-point rate is cloned when present and otherwise initialized to zero.
843 func (e *ExternalIncentive) Clone() *ExternalIncentive {
844 rewardPerSecondX128 := u256.Zero()
845
846 if e.rewardPerSecondX128 != nil {
847 rewardPerSecondX128 = e.rewardPerSecondX128.Clone()
848 }
849
850 return &ExternalIncentive{
851 incentiveId: e.incentiveId,
852 startTimestamp: e.startTimestamp,
853 endTimestamp: e.endTimestamp,
854 createdHeight: e.createdHeight,
855 createdTimestamp: e.createdTimestamp,
856 depositGnsAmount: e.depositGnsAmount,
857 targetPoolPath: e.targetPoolPath,
858 rewardToken: e.rewardToken,
859 totalRewardAmount: e.totalRewardAmount,
860 rewardAmount: e.rewardAmount,
861 rewardPerSecondX128: rewardPerSecondX128,
862 creator: e.creator,
863 refunded: e.refunded,
864 unclaimableSeconds: e.unclaimableSeconds,
865 distributedRewardAmount: e.distributedRewardAmount,
866 accumulatedPenaltyAmount: e.accumulatedPenaltyAmount,
867 }
868 }
869
870 // NewExternalIncentive creates a new external incentive
871 //
872 // Parameters:
873 // - incentiveId: Unique identifier assigned to the external incentive.
874 // - targetPoolPath: Pool path whose staked positions may receive this incentive.
875 // - rewardToken: Token path of the asset deposited for distribution.
876 // - rewardAmount: Total reward amount, also used as the initial remaining reward balance.
877 // - startTimestamp: Unix timestamp in seconds when reward distribution starts.
878 // - endTimestamp: Unix timestamp in seconds when reward distribution ends; duration is endTimestamp-startTimestamp and must be nonzero for the rate calculation.
879 // - creator: Address that funds the incentive and receives refunds at finalization.
880 // - depositGnsAmount: GNS amount deposited as the incentive's required collateral.
881 // - createdHeight: Block height to record for incentive creation.
882 // - currentTime: Unix timestamp in seconds recorded as the incentive creation time.
883 //
884 // Returns:
885 // - incentive: New incentive with a Q128-scaled per-second rate and zeroed distribution, penalty, and unclaimable counters.
886 func NewExternalIncentive(
887 incentiveId string ,
888 targetPoolPath string ,
889 rewardToken string ,
890 rewardAmount int64 ,
891 startTimestamp int64 , // timestamp is in unix time(seconds)
892 endTimestamp int64 ,
893 creator address,
894 depositGnsAmount int64 ,
895 createdHeight int64 ,
896 currentTime int64 , // current time in unix time(seconds)
897 ) *ExternalIncentive {
898 incentiveDuration := endTimestamp - startTimestamp
899
900 // Compute reward per second scaled by 2^128 to preserve sub-second precision.
901 // rewardPerSecondX128 = (rewardAmount << 128) / incentiveDuration.
902 // Consumers must divide by 2^128 when materializing back to a plain integer.
903 rewardPerSecondX128 := u256.MulDiv(
904 u256.NewUintFromInt64(rewardAmount),
905 consts.Q128(),
906 u256.NewUintFromInt64(incentiveDuration),
907 )
908
909 return &ExternalIncentive{
910 incentiveId: incentiveId,
911 targetPoolPath: targetPoolPath,
912 rewardToken: rewardToken,
913 totalRewardAmount: rewardAmount,
914 rewardAmount: rewardAmount,
915 startTimestamp: startTimestamp,
916 endTimestamp: endTimestamp,
917 rewardPerSecondX128: rewardPerSecondX128,
918 distributedRewardAmount: 0 ,
919 accumulatedPenaltyAmount: 0 ,
920 creator: creator,
921 createdHeight: createdHeight,
922 createdTimestamp: currentTime,
923 depositGnsAmount: depositGnsAmount,
924 refunded: false ,
925 unclaimableSeconds: 0 ,
926 }
927 }
928
929 // Tick mapping for each pool
930 type Ticks struct {
931 tree *bptree.BPTree // int32 tickId -> tick
932 }
933
934 // Ticks Getter/Setter methods
935
936 // Tree returns the ticks tree
937 //
938 // Returns:
939 // - tree: Mutable B+ tree mapping encoded int32 tick IDs to Tick records.
940 func (t *Ticks) Tree() *bptree.BPTree {
941 return t.tree
942 }
943
944 // SetTree sets the ticks tree
945 //
946 // Parameters:
947 // - tree: B+ tree to use for tick storage.
948 func (t *Ticks) SetTree(tree *bptree.BPTree) {
949 t.tree = tree
950 }
951
952 // Get returns the tick for the given tickId, or nil if it does not exist.
953 //
954 // Parameters:
955 // - tickId: Tick index to look up.
956 //
957 // Returns:
958 // - tick: Matching Tick record, or nil when the encoded ID is absent; panics if a stored value has the wrong type.
959 func (t *Ticks) Get(tickId int32 ) *Tick {
960 v := t.tree.Get(utils.EncodeInt32(tickId))
961 if v == nil {
962 return nil
963 }
964
965 tick, ok := v.(*Tick)
966 if !ok {
967 panic( "failed to cast value to *Tick" )
968 }
969 return tick
970 }
971
972 // Has reports whether a tick ID is present in the underlying tree.
973 //
974 // Parameters:
975 // - tickId: Tick index whose encoded key is tested.
976 //
977 // Returns:
978 // - present: True when the encoded tick ID exists in the underlying tree.
979 func (self *Ticks) Has(tickId int32 ) bool {
980 return self.tree.Has(utils.EncodeInt32(tickId))
981 }
982
983 // SetTick sets a tick by ID
984 //
985 // Parameters:
986 // - tickId: Tick index under which to store the record.
987 // - tick: Non-nil Tick record to store; a zero gross staked liquidity removes the tick instead, while nil input panics during the gross-liquidity check.
988 func (t *Ticks) SetTick(tickId int32 , tick *Tick) {
989 if tick.stakedLiquidityGross.IsZero() {
990 t.tree.Remove(utils.EncodeInt32(tickId))
991 return
992 }
993
994 t.tree.Set(utils.EncodeInt32(tickId), tick)
995 }
996
997 // IterateTicks iterates over all ticks
998 //
999 // Parameters:
1000 // - fn: Callback receiving each stored Tick and decoded tick ID; returning true requests that iteration stop.
1001 func (t *Ticks) IterateTicks(fn func (tickId int32 , tick *Tick) bool ) {
1002 t.tree.Iterate( "" , "" , func (key string , value interface {}) bool {
1003 tick, ok := value.(*Tick)
1004 if !ok {
1005 return false
1006 }
1007
1008 return fn(utils.DecodeInt32(key), tick)
1009 })
1010 }
1011
1012 // Clone returns a deep copy of ticks.
1013 //
1014 // Returns:
1015 // - ticks: New Ticks value with cloned Tick records in a fresh fanout-16 tree.
1016 func (t Ticks) Clone() Ticks {
1017 cloned := bptree.NewBPTreeN( 16 )
1018 t.tree.Iterate( "" , "" , func (key string , value any ) bool {
1019 tick, ok := value.(*Tick)
1020 if !ok {
1021 panic( "failed to cast value to *Tick" )
1022 }
1023 cloned.Set(key, tick.Clone())
1024 return false
1025 })
1026 return Ticks{tree: cloned}
1027 }
1028
1029 // NewTicks creates an empty tick mapping with a fanout-16 B+ tree.
1030 //
1031 // Returns:
1032 // - ticks: Empty Ticks value ready to store pool tick records.
1033 func NewTicks() Ticks {
1034 return Ticks{
1035 tree: bptree.NewBPTreeN( 16 ),
1036 }
1037 }
1038
1039 // Tick represents the state of a specific tick in a pool.
1040 //
1041 // Fields:
1042 // - id (int32): The ID of the tick.
1043 // - stakedLiquidityGross (*u256.Uint): Total gross staked liquidity at this tick.
1044 // - stakedLiquidityDelta (*i256.Int): Net change in staked liquidity at this tick.
1045 // - outsideAccumulation (*UintTree): RewardRatioAccumulation outside the tick.
1046 type Tick struct {
1047 id int32
1048
1049 // conceptually equal with Pool.liquidityGross but only for the staked positions
1050 stakedLiquidityGross *u256.Uint
1051
1052 // conceptually equal with Pool.liquidityNet but only for the staked positions
1053 stakedLiquidityDelta *i256.Int
1054
1055 // currentOutsideAccumulation is the accumulation of the time / TotalStake outside the tick.
1056 // It is calculated by subtracting the current tick's currentOutsideAccumulation from the global reward ratio accumulation.
1057 outsideAccumulation *UintTree // timestamp -> fixed 32-byte big-endian string
1058 }
1059
1060 // Tick Getter/Setter methods
1061
1062 // Id returns the tick ID
1063 //
1064 // Returns:
1065 // - id: Tick index represented by this record.
1066 func (t *Tick) Id() int32 {
1067 return t.id
1068 }
1069
1070 // SetId sets the tick ID
1071 //
1072 // Parameters:
1073 // - id: Tick index to store in the record.
1074 func (t *Tick) SetId(id int32 ) {
1075 t.id = id
1076 }
1077
1078 // StakedLiquidityGross returns the staked liquidity gross
1079 //
1080 // Returns:
1081 // - liquidity: Total gross staked liquidity currently associated with this tick.
1082 func (t *Tick) StakedLiquidityGross() *u256.Uint {
1083 return t.stakedLiquidityGross
1084 }
1085
1086 // SetStakedLiquidityGross sets the staked liquidity gross
1087 //
1088 // Parameters:
1089 // - stakedLiquidityGross: New total gross staked liquidity; the value is copied before storage.
1090 func (t *Tick) SetStakedLiquidityGross(stakedLiquidityGross *u256.Uint) {
1091 t.stakedLiquidityGross = u256.Zero().Set(stakedLiquidityGross)
1092 }
1093
1094 // StakedLiquidityDelta returns the staked liquidity delta
1095 //
1096 // Returns:
1097 // - delta: Net staked liquidity change associated with this tick.
1098 func (t *Tick) StakedLiquidityDelta() *i256.Int {
1099 return t.stakedLiquidityDelta
1100 }
1101
1102 // SetStakedLiquidityDelta sets the staked liquidity delta
1103 //
1104 // Parameters:
1105 // - stakedLiquidityDelta: New net staked liquidity delta; the value is copied before storage.
1106 func (t *Tick) SetStakedLiquidityDelta(stakedLiquidityDelta *i256.Int) {
1107 t.stakedLiquidityDelta = i256.Zero().Set(stakedLiquidityDelta)
1108 }
1109
1110 // OutsideAccumulation returns the outside accumulation tree
1111 //
1112 // Returns:
1113 // - tree: Historical reward-ratio accumulation observed outside this tick.
1114 func (t *Tick) OutsideAccumulation() *UintTree {
1115 return t.outsideAccumulation
1116 }
1117
1118 // SetOutsideAccumulation sets the outside accumulation tree
1119 //
1120 // Parameters:
1121 // - outsideAccumulation: UintTree of outside-accumulation snapshots keyed by Unix timestamp.
1122 func (t *Tick) SetOutsideAccumulation(outsideAccumulation *UintTree) {
1123 t.outsideAccumulation = outsideAccumulation
1124 }
1125
1126 // SetOutsideAccumulationAt sets the outside accumulation at the timestamp.
1127 // SetOutsideAccumulationAt records the Q128-scaled outside accumulation at a timestamp.
1128 //
1129 // Parameters:
1130 // - timestamp: Nonnegative Unix timestamp in seconds used as the snapshot key.
1131 // - acc: Q128-scaled accumulation value encoded into the tree.
1132 func (t *Tick) SetOutsideAccumulationAt(timestamp int64 , acc *u256.Uint) {
1133 t.outsideAccumulation.Set(timestamp, utils.EncodeUint256(acc))
1134 }
1135
1136 // Clone returns a deep copy of the tick.
1137 //
1138 // Returns:
1139 // - tick: Deep copy of the tick and its outside-accumulation tree, or nil when the receiver is nil.
1140 func (t *Tick) Clone() *Tick {
1141 if t == nil {
1142 return nil
1143 }
1144
1145 return &Tick{
1146 id: t.id,
1147 stakedLiquidityGross: t.stakedLiquidityGross.Clone(),
1148 stakedLiquidityDelta: t.stakedLiquidityDelta.Clone(),
1149 outsideAccumulation: t.outsideAccumulation.Clone(),
1150 }
1151 }
1152
1153 // NewTick creates a tick with zero staked liquidity and an empty fanout-4 outside-accumulation tree.
1154 //
1155 // Parameters:
1156 // - tickId: Tick index to assign to the new record.
1157 //
1158 // Returns:
1159 // - tick: Initialized tick record.
1160 func NewTick(tickId int32 ) *Tick {
1161 return &Tick{
1162 id: tickId,
1163 stakedLiquidityGross: u256.Zero(),
1164 stakedLiquidityDelta: i256.Zero(),
1165 outsideAccumulation: NewUintTreeN( 4 ),
1166 }
1167 }
1168
1169 // 100%, 0%, 0% if no tier2 and tier3
1170 // 80%, 0%, 20% if no tier2
1171 // 70%, 30%, 0% if no tier3
1172 // 50%, 30%, 20% if has tier2 and tier3
1173 type TierRatio struct {
1174 Tier1 uint64
1175 Tier2 uint64
1176 Tier3 uint64
1177 }
1178
1179 // NewTierRatio constructs the reward-share ratio for tiers 1 through 3.
1180 //
1181 // Parameters:
1182 // - tier1: Tier-1 share scaled by 100 (for example, 70 means 70%).
1183 // - tier2: Tier-2 share scaled by 100.
1184 // - tier3: Tier-3 share scaled by 100.
1185 //
1186 // Returns:
1187 // - ratio: TierRatio containing the supplied scaled shares.
1188 func NewTierRatio(tier1, tier2, tier3 uint64 ) TierRatio {
1189 return TierRatio{
1190 Tier1: tier1,
1191 Tier2: tier2,
1192 Tier3: tier3,
1193 }
1194 }
1195
1196 // Get returns the ratio(scaled up by 100) for the given tier.
1197 //
1198 // Parameters:
1199 // - tier: Tier number to query; only tiers 1, 2, and 3 are supported.
1200 //
1201 // Returns:
1202 // - ratio: Requested tier share scaled by 100.
1203 // - err: Non-nil when tier is not 1, 2, or 3; nil for a supported tier.
1204 func (ratio *TierRatio) Get(tier uint64 ) ( uint64 , error ) {
1205 switch tier {
1206 case 1 :
1207 return ratio.Tier1, nil
1208 case 2 :
1209 return ratio.Tier2, nil
1210 case 3 :
1211 return ratio.Tier3, nil
1212 default :
1213 return 0 , errors.New(ufmt.Sprintf( "unsupported tier(%d)" , tier))
1214 }
1215 }
1216
1217 // SwapBatchProcessor processes tick crosses in batch for a swap
1218 // This processor accumulates all tick crosses that occur during a single swap
1219 // and processes them together at the end, reducing redundant calculations
1220 // and state updates that would occur with individual tick processing
1221 type SwapBatchProcessor struct {
1222 poolPath string // The pool path identifier for this swap
1223 pool *Pool // Reference to the pool being swapped in
1224 crosses []*SwapTickCross // Accumulated tick crosses during the swap
1225 timestamp int64 // Timestamp when the swap started
1226 isActive bool // Flag to prevent accumulation after swap ends
1227 }
1228
1229 // PoolPath returns the pool path associated with this swap batch.
1230 //
1231 // Returns:
1232 // - path: Pool identifier for the swap being processed.
1233 func (s *SwapBatchProcessor) PoolPath() string {
1234 return s.poolPath
1235 }
1236
1237 // SetPoolPath stores the pool identifier associated with this swap batch.
1238 //
1239 // Parameters:
1240 // - poolPath: Pool identifier to associate with the swap batch.
1241 func (s *SwapBatchProcessor) SetPoolPath(poolPath string ) {
1242 s.poolPath = poolPath
1243 }
1244
1245 // Pool returns the pool referenced by this swap batch.
1246 //
1247 // Returns:
1248 // - pool: Pool state used to process the accumulated tick crosses.
1249 func (s *SwapBatchProcessor) Pool() *Pool {
1250 return s.pool
1251 }
1252
1253 // SetPool replaces the pool reference used by this swap batch.
1254 //
1255 // Parameters:
1256 // - pool: Pool state to reference while processing tick crosses.
1257 func (s *SwapBatchProcessor) SetPool(pool *Pool) {
1258 s.pool = pool
1259 }
1260
1261 // Crosses returns the tick crosses accumulated by this batch.
1262 //
1263 // Returns:
1264 // - crosses: Slice of tick-cross records in the order they were added.
1265 func (s *SwapBatchProcessor) Crosses() []*SwapTickCross {
1266 return s.crosses
1267 }
1268
1269 // SetCrosses replaces the batch's accumulated tick-cross sequence.
1270 //
1271 // Parameters:
1272 // - crosses: Tick-cross records to store as the batch's accumulated sequence.
1273 func (s *SwapBatchProcessor) SetCrosses(crosses []*SwapTickCross) {
1274 s.crosses = crosses
1275 }
1276
1277 // Timestamp returns the Unix timestamp in seconds recorded when the swap started.
1278 //
1279 // Returns:
1280 // - timestamp: Swap-start timestamp in Unix seconds.
1281 func (s *SwapBatchProcessor) Timestamp() int64 {
1282 return s.timestamp
1283 }
1284
1285 // SetTimestamp stores the swap-start timestamp for this batch.
1286 //
1287 // Parameters:
1288 // - timestamp: Unix timestamp in seconds to record for the swap batch.
1289 func (s *SwapBatchProcessor) SetTimestamp(timestamp int64 ) {
1290 s.timestamp = timestamp
1291 }
1292
1293 // IsActive reports the processor's stored active flag.
1294 //
1295 // Returns:
1296 // - active: True when the batch is marked active for the swap lifecycle.
1297 func (s *SwapBatchProcessor) IsActive() bool {
1298 return s.isActive
1299 }
1300
1301 // SetIsActive stores the processor's active lifecycle flag.
1302 //
1303 // Parameters:
1304 // - isActive: Active flag to store for the swap lifecycle.
1305 func (s *SwapBatchProcessor) SetIsActive(isActive bool ) {
1306 s.isActive = isActive
1307 }
1308
1309 // LastCross returns the most recently appended tick cross.
1310 //
1311 // Returns:
1312 // - cross: Last tick-cross record, or nil when no crosses have been added.
1313 func (s *SwapBatchProcessor) LastCross() *SwapTickCross {
1314 if len(s.crosses) == 0 {
1315 return nil
1316 }
1317
1318 return s.crosses[len(s.crosses)- 1 ]
1319 }
1320
1321 // AddCross appends a tick-cross record to the batch sequence.
1322 //
1323 // Parameters:
1324 // - tickCross: Tick-cross record to append.
1325 func (s *SwapBatchProcessor) AddCross(tickCross *SwapTickCross) {
1326 s.crosses = append(s.crosses, tickCross)
1327 }
1328
1329 // NewSwapBatchProcessor creates an active batch for collecting tick crosses in a pool swap.
1330 //
1331 // Parameters:
1332 // - poolPath: Pool identifier associated with the swap.
1333 // - pool: Pool state whose tick crosses are being collected.
1334 // - timestamp: Unix timestamp in seconds when the swap began.
1335 //
1336 // Returns:
1337 // - processor: Active processor with an empty cross sequence.
1338 func NewSwapBatchProcessor(poolPath string , pool *Pool, timestamp int64 ) *SwapBatchProcessor {
1339 return &SwapBatchProcessor{
1340 poolPath: poolPath,
1341 pool: pool,
1342 crosses: make([]*SwapTickCross, 0 ),
1343 timestamp: timestamp,
1344 isActive: true ,
1345 }
1346 }
1347
1348 // SwapTickCross stores information about a tick cross during a swap
1349 // This struct is used to accumulate tick cross events during a single swap transaction
1350 // for batch processing to optimize gas usage and computational efficiency
1351 type SwapTickCross struct {
1352 tickID int32 // The tick index that was crossed
1353 zeroForOne bool // Direction of the swap (true: token0->token1, false: token1->token0)
1354 delta *i256.Int // Pre-calculated liquidity delta for this tick cross
1355 }
1356
1357 // TickID returns the index of the crossed tick.
1358 //
1359 // Returns:
1360 // - tickID: Tick index represented by this cross.
1361 func (s *SwapTickCross) TickID() int32 {
1362 return s.tickID
1363 }
1364
1365 // ZeroForOne reports the swap direction represented by this cross.
1366 //
1367 // Returns:
1368 // - zeroForOne: True for token0-to-token1 swaps; false for token1-to-token0 swaps.
1369 func (s *SwapTickCross) ZeroForOne() bool {
1370 return s.zeroForOne
1371 }
1372
1373 // Delta returns the precomputed net staked-liquidity change for the crossed tick.
1374 //
1375 // Returns:
1376 // - delta: Signed liquidity delta to apply at the crossed tick.
1377 func (s *SwapTickCross) Delta() *i256.Int {
1378 return s.delta
1379 }
1380
1381 // NewSwapTickCross creates a tick-cross record for a swap batch.
1382 //
1383 // Parameters:
1384 // - tickID: Index of the tick crossed during the swap.
1385 // - zeroForOne: Swap direction; true means token0-to-token1 and false means token1-to-token0.
1386 // - delta: Precomputed signed staked-liquidity change for this tick cross.
1387 //
1388 // Returns:
1389 // - cross: Tick-cross record containing the supplied index, direction, and delta.
1390 func NewSwapTickCross(tickID int32 , zeroForOne bool , delta *i256.Int) *SwapTickCross {
1391 return &SwapTickCross{
1392 tickID: tickID,
1393 zeroForOne: zeroForOne,
1394 delta: delta,
1395 }
1396 }
1397
vm/qrender output, sanitized (docs/render-security.md) and displayed in an empty-sandbox iframe — scripts, forms and popups cannot run. Links stay inert in-preview; right-click to open.