Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

reward_calculation_pool.gno

27.85 Kb · 784 lines
  1package staker
  2
  3import (
  4	"errors"
  5	"math"
  6	"time"
  7
  8	"gno.land/p/gnoswap/gnsmath/v1"
  9	bptree "gno.land/p/nt/bptree/v0"
 10	ufmt "gno.land/p/nt/ufmt/v0"
 11
 12	i256 "gno.land/p/gnoswap/int256/v1"
 13	u256 "gno.land/p/gnoswap/uint256/v1"
 14	sr "gno.land/r/gnoswap/staker"
 15)
 16
 17var q128 = u256.MustFromDecimal("340282366920938463463374607431768211456")
 18
 19// Pools represents the global pool storage
 20type Pools struct {
 21	tree *bptree.BPTree // string poolPath -> pool
 22}
 23
 24// NewPools creates an empty resolver for global pool storage.
 25//
 26// Returns:
 27//   - pools: Pools resolver backed by a new B+ tree keyed by pool path.
 28func NewPools() *Pools {
 29	return &Pools{
 30		tree: sr.NewBPTreeN(16),
 31	}
 32}
 33
 34// Get returns the pool stored under the given pool path.
 35//
 36// Parameters:
 37//   - poolPath: Pool path used as the storage key.
 38//
 39// Returns:
 40//   - pool: Stored pool pointer when poolPath exists; nil when absent.
 41//   - found: True when poolPath resolves to a pool; false when no entry exists.
 42func (self *Pools) Get(poolPath string) (*sr.Pool, bool) {
 43	v := self.tree.Get(poolPath)
 44	if v == nil {
 45		return nil, false
 46	}
 47	p, ok := v.(*sr.Pool)
 48	if !ok {
 49		panic(ufmt.Sprintf("failed to cast v to *Pool: %T", v))
 50	}
 51	return p, true
 52}
 53
 54// GetPoolOrNil returns the pool for the given pool path, or nil when it does not exist.
 55//
 56// Parameters:
 57//   - poolPath: Pool path used as the storage key.
 58//
 59// Returns:
 60//   - pool: Stored pool pointer, or nil when poolPath is absent.
 61func (self *Pools) GetPoolOrNil(poolPath string) *sr.Pool {
 62	pool, ok := self.Get(poolPath)
 63	if !ok {
 64		return nil
 65	}
 66	return pool
 67}
 68
 69// set sets the pool for the given poolPath.
 70func (self *Pools) set(poolPath string, pool *sr.Pool) {
 71	self.tree.Set(poolPath, pool)
 72}
 73
 74// Has reports whether a pool exists for the given pool path.
 75//
 76// Parameters:
 77//   - poolPath: Pool path used as the storage key.
 78//
 79// Returns:
 80//   - exists: True when poolPath is present in the pool tree; false otherwise.
 81func (self *Pools) Has(poolPath string) bool {
 82	return self.tree.Has(poolPath)
 83}
 84
 85// IterateAll visits every stored pool until the callback requests that traversal stop.
 86//
 87// Parameters:
 88//   - fn: Callback receiving each pool path and pool pointer; return true to stop iteration, false to continue.
 89func (self *Pools) IterateAll(fn func(key string, pool *sr.Pool) bool) {
 90	self.tree.Iterate("", "", func(key string, value any) bool {
 91		p, ok := value.(*sr.Pool)
 92		if !ok {
 93			panic(ufmt.Sprintf("failed to cast value to *Pool: %T", value))
 94		}
 95		return fn(key, p)
 96	})
 97}
 98
 99type PoolResolver struct {
100	*sr.Pool
101
102	// exit is set only when collecting an exit checkpoint, and overrides the pool reads that
103	// would otherwise come from state the position no longer takes part in.
104	exit *sr.UnstakedPosition
105}
106
107// IncentivesResolver returns a resolver over the pool's external-incentive state.
108//
109// Returns:
110//   - resolver: Incentives resolver backed by this pool's incentive tree and unclaimable periods.
111func (self *PoolResolver) IncentivesResolver() *IncentivesResolver {
112	return NewIncentivesResolver(self.Incentives())
113}
114
115// CurrentGlobalRewardRatioAccumulation returns the latest stored global reward-ratio checkpoint in the [0, currentTime] range.
116//
117// Parameters:
118//   - currentTime: Unix timestamp bounding the checkpoint lookup.
119//
120// Returns:
121//   - time: Timestamp of the latest stored checkpoint at or before currentTime; zero when no checkpoint exists.
122//   - acc: Decimal-encoded Q128-scaled global reward-ratio accumulation at time.
123func (self *PoolResolver) CurrentGlobalRewardRatioAccumulation(currentTime int64) (time int64, acc string) {
124	acc = "0"
125
126	self.GlobalRewardRatioAccumulation().ReverseIterate(0, currentTime, func(key int64, value any) bool {
127		time = key
128
129		valueStr, ok := value.(string)
130		if !ok {
131			panic(ufmt.Sprintf("failed to cast value to string: %T", value))
132		}
133
134		acc = valueStr
135
136		return true
137	})
138
139	return time, acc
140}
141
142// CurrentTick returns the latest historical tick in the [0, currentTime] range.
143//
144// Parameters:
145//   - currentTime: Unix timestamp bounding the historical-tick lookup.
146//
147// Returns:
148//   - tick: Latest historical tick at or before currentTime; an exit resolver uses its pinned exit tick at or after exit time.
149func (self *PoolResolver) CurrentTick(currentTime int64) (tick int32) {
150	if self.exit != nil && currentTime >= self.exit.ExitTime() {
151		return self.exit.ExitTick()
152	}
153
154	self.HistoricalTick().ReverseIterate(0, currentTime, func(key int64, value any) bool {
155		res, ok := value.(int32)
156		if !ok {
157			panic(ufmt.Sprintf("failed to cast value to int32: %T", value))
158		}
159		tick = res
160		return true
161	})
162	return tick
163}
164
165// CurrentStakedLiquidity returns the latest staked-liquidity checkpoint in the [0, currentTime] range.
166//
167// Parameters:
168//   - currentTime: Unix timestamp bounding the staked-liquidity lookup.
169//
170// Returns:
171//   - liquidity: Uint256 staked liquidity effective at or before currentTime; zero when no checkpoint exists.
172func (self *PoolResolver) CurrentStakedLiquidity(currentTime int64) (liquidity *u256.Uint) {
173	liquidity = u256.Zero()
174
175	self.StakedLiquidity().ReverseIterate(0, currentTime, func(key int64, value any) bool {
176		res, ok := value.(*u256.Uint)
177		if !ok {
178			panic(ufmt.Sprintf("failed to cast value to *u256.Uint: %T", value))
179		}
180		liquidity = res
181		return true
182	})
183	return liquidity
184}
185
186// GetOrNewTick returns the existing tick or a new zero-valued tick.
187//
188// Parameters:
189//   - tickId: Boundary tick identifier to retrieve or initialize.
190//
191// Returns:
192//   - tick: Existing stored tick, or a zero-valued tick with tickId when no entry exists.
193//
194// Substituting a zero-valued tick on a read is safe because ticks are pruned
195// only when their staked gross liquidity reaches zero, in the same call that
196// removes the last deposit referencing them.
197func (self *PoolResolver) GetOrNewTick(tickId int32) *sr.Tick {
198	if self.exit != nil {
199		if lowerTick := self.exit.LowerTick(); lowerTick != nil && lowerTick.Id() == tickId {
200			return lowerTick
201		}
202		if upperTick := self.exit.UpperTick(); upperTick != nil && upperTick.Id() == tickId {
203			return upperTick
204		}
205	}
206
207	tick := self.Ticks().Get(tickId)
208	if tick == nil {
209		return sr.NewTick(tickId)
210	}
211	return tick
212}
213
214// initializeNewTickOutsideAccumulation seeds a just-created boundary tick so
215// that below(tick) == globalAccumulation holds, keeping the three branches of
216// outsideAccumulationAt returns a boundary tick's outside accumulation at currentTime.
217//
218// An exit checkpoint answers for its own exit timestamp from the value pinned when it was
219// written: a tick cross later in the same block overwrites the entry at that timestamp, while
220// earlier entries can no longer change.
221func (self *PoolResolver) outsideAccumulationAt(tickId int32, currentTime int64) *u256.Uint {
222	if self.exit != nil && currentTime == self.exit.ExitTime() {
223		switch tickId {
224		case self.exit.Deposit().TickLower():
225			return u256.MustFromDecimal(self.exit.LowerOutsideAcc())
226		case self.exit.Deposit().TickUpper():
227			return u256.MustFromDecimal(self.exit.UpperOutsideAcc())
228		}
229	}
230
231	return NewTickResolver(self.GetOrNewTick(tickId)).CurrentOutsideAccumulation(currentTime)
232}
233
234// CalculateRawRewardForPosition consistent.
235func (self *PoolResolver) initializeNewTickOutsideAccumulation(currentTime int64, currentTick, tickId int32, tick *sr.Tick) {
236	if tickId > currentTick {
237		return
238	}
239
240	globalAcc, _ := self.globalRewardRatioAccumulationAt(currentTime)
241	tick.SetOutsideAccumulationAt(currentTime, globalAcc)
242}
243
244// IsExternallyIncentivizedPool reports whether the pool has any external incentive that has not ended,
245// including incentives whose start time is still in the future.
246//
247// Returns:
248//   - incentivized: True when at least one non-ended external incentive is indexed for the pool; false when all are ended or none exist.
249func (self *PoolResolver) IsExternallyIncentivizedPool() bool {
250	currentTime := time.Now().Unix()
251	hasIncentive := false
252	// With a maximum duration of 365 days, older starts have already ended.
253	// Keep future starts eligible and retain historical records for reward claims.
254	self.Incentives().IterateIncentiveIdsByTime(stakeScanLowerBound(currentTime), math.MaxInt64, func(incentiveId string) bool {
255		incentive, ok := self.Incentives().Incentive(incentiveId)
256		if !ok {
257			panic("incentive missing from pool start-time index")
258		}
259
260		resolver := NewExternalIncentiveResolver(incentive)
261		if !resolver.IsEnded(currentTime) {
262			hasIncentive = true
263			return true
264		}
265
266		return false
267	})
268
269	return hasIncentive
270}
271
272// CurrentReward returns the latest cached per-pool reward rate in the [0, currentTime] range.
273//
274// Parameters:
275//   - currentTime: Unix timestamp bounding the reward-cache lookup.
276//
277// Returns:
278//   - reward: Latest cached GNS reward rate at or before currentTime, in units per second; zero when no checkpoint exists.
279func (self *PoolResolver) CurrentReward(currentTime int64) (reward int64) {
280	self.RewardCache().ReverseIterate(0, currentTime, func(key int64, value any) bool {
281		res, ok := value.(int64)
282		if !ok {
283			panic(ufmt.Sprintf("failed to cast value to int64: %T", value))
284		}
285		reward = res
286		return true
287	})
288	return reward
289}
290
291func (self *PoolResolver) isChangedTick(currentTime int64, currentTick int32) bool {
292	if self.HistoricalTick().Size() == 0 {
293		return true
294	}
295
296	previousTick := self.CurrentTick(currentTime)
297
298	return previousTick != currentTick
299}
300
301// cacheReward sets the current reward for the pool
302// If the pool is in unclaimable period, it will end the unclaimable period, updates the reward, and start the unclaimable period again.
303//
304// Important behavior for initial tier assignment:
305// - When a pool first receives a tier, oldTierReward=0 and currentTierReward>0
306// - If the pool has zero liquidity at this point, startUnclaimablePeriod() is called
307// - This ensures unclaimable period tracking begins from the moment rewards start emitting
308func (self *PoolResolver) cacheReward(currentTime int64, currentTierReward int64) {
309	oldTierReward := self.CurrentReward(currentTime)
310	if oldTierReward == currentTierReward {
311		return
312	}
313
314	isInUnclaimable := self.CurrentStakedLiquidity(currentTime).IsZero()
315	if isInUnclaimable {
316		// End any existing unclaimable period
317		// Note: If lastUnclaimableTime is 0 (not yet tracking), this is a no-op
318		self.endUnclaimablePeriod(currentTime)
319	}
320
321	self.Pool.SetRewardCacheAt(currentTime, currentTierReward)
322
323	if isInUnclaimable {
324		// Start/restart unclaimable period tracking
325		// This handles initial tier assignment when lastUnclaimableTime is 0
326		self.startUnclaimablePeriod(currentTime)
327	}
328}
329
330func (self *PoolResolver) calculateGlobalRewardRatioAccumulation(currentTime int64, currentStakedLiquidity *u256.Uint) *u256.Uint {
331	oldAccTime, oldAccStr := self.CurrentGlobalRewardRatioAccumulation(currentTime)
332	timeDiff := gnsmath.SafeSubInt64(currentTime, oldAccTime)
333	if timeDiff == 0 {
334		return u256.MustFromDecimal(oldAccStr)
335	}
336	if timeDiff < 0 {
337		panic("time cannot go backwards")
338	}
339
340	if currentStakedLiquidity.IsZero() {
341		return u256.MustFromDecimal(oldAccStr)
342	}
343
344	oldAcc := u256.MustFromDecimal(oldAccStr)
345	acc := u256.MulDiv(
346		u256.NewUintFromInt64(timeDiff),
347		q128,
348		currentStakedLiquidity,
349	)
350	return u256.Zero().Add(oldAcc, acc)
351}
352
353// globalRewardRatioAccumulationAt returns the global reward ratio accumulation *at* currentTime.
354//
355// CurrentGlobalRewardRatioAccumulation returns the latest stored checkpoint (<= currentTime), which is
356// only equal to the accumulation at currentTime when a checkpoint was written at that very timestamp.
357// Checkpoints are written exclusively by modifyDeposit (staked liquidity changes), so on any other path
358// the stored value lags by (currentTime - lastCheckpointTime) * q128 / stakedLiquidity.
359//
360// Reward calculation never has this problem because it derives the accumulation on demand
361// (CalculateRawRewardForPosition). Event emission must do the same, otherwise off-chain indexers that
362// treat the emitted accumulator as authoritative at the event timestamp silently drop that interval.
363func (self *PoolResolver) globalRewardRatioAccumulationAt(currentTime int64) (*u256.Uint, *u256.Uint) {
364	stakedLiquidity := self.CurrentStakedLiquidity(currentTime)
365	accumulation := self.calculateGlobalRewardRatioAccumulation(currentTime, stakedLiquidity)
366
367	return accumulation, stakedLiquidity
368}
369
370// updateGlobalRewardRatioAccumulation updates the global reward ratio accumulation and returns the new accumulation.
371func (self *PoolResolver) updateGlobalRewardRatioAccumulation(currentTime int64, currentStakedLiquidity *u256.Uint) *u256.Uint {
372	newAcc := self.calculateGlobalRewardRatioAccumulation(currentTime, currentStakedLiquidity)
373
374	// Persist as string to reduce stored object complexity.
375	self.Pool.SetGlobalRewardRatioAccumulationAt(currentTime, newAcc.ToString())
376	return newAcc
377}
378
379// RewardStateOf initializes a new RewardState for the given deposit, allocating reward and penalty slots for each warmup.
380//
381// Parameters:
382//   - deposit: Staked deposit whose pool, liquidity, and warmup schedule will be resolved.
383//
384// Returns:
385//   - state: RewardState initialized with zeroed per-warmup reward and penalty accumulators.
386func (self *PoolResolver) RewardStateOf(deposit *sr.Deposit) *RewardState {
387	warmups := len(deposit.Warmups())
388	result := &RewardState{
389		pool:      self,
390		deposit:   NewDepositResolver(deposit),
391		rewards:   make([]int64, warmups),
392		penalties: make([]int64, warmups),
393	}
394
395	return result
396}
397
398// reset clears cached rewards/penalties so a RewardState can be reused without re-allocating.
399func (self *RewardState) reset() {
400	for i := range self.rewards {
401		self.rewards[i] = 0
402		self.penalties[i] = 0
403	}
404}
405
406// NewPoolResolver wraps a pool's persisted reward, liquidity, tick, and incentive state for calculations.
407//
408// Parameters:
409//   - pool: Pool state to resolve.
410//
411// Returns:
412//   - resolver: Pool resolver backed by pool.
413func NewPoolResolver(pool *sr.Pool) *PoolResolver {
414	return &PoolResolver{
415		Pool: pool,
416	}
417}
418
419// newPoolResolverWithExit builds a resolver that reads the pool through an exit checkpoint.
420func newPoolResolverWithExit(pool *sr.Pool, exit *sr.UnstakedPosition) *PoolResolver {
421	return &PoolResolver{
422		Pool: pool,
423		exit: exit,
424	}
425}
426
427// RewardState is a struct for storing the intermediate state for reward calculation.
428type RewardState struct {
429	pool    *PoolResolver
430	deposit *DepositResolver
431
432	// accumulated rewards for each warmup
433	rewards   []int64
434	penalties []int64
435}
436
437// calculateInternalReward computes the position's per-warmup rewards and penalties from a pre-resolved
438// per-second reward-rate schedule (see PoolResolver.resolveInternalRewardSegments).
439//
440// It is pure: it neither queries pool tier/emission state nor writes any state, so the read-only view
441// path and the collect path use it identically. Each segment [start, end) is applied at its constant
442// per-second rate; rewardPerWarmup is a no-op for empty segments (start == end).
443func (self *RewardState) calculateInternalReward(segments []internalRewardSegment) ([]int64, []int64) {
444	for _, seg := range segments {
445		if err := self.rewardPerWarmup(seg.start, seg.end, seg.rewardPerSecond); err != nil {
446			panic(err)
447		}
448	}
449
450	self.applyWarmup()
451
452	return self.rewards, self.penalties
453}
454
455// updateExternalReward updates the external reward for the deposit.
456// It updates the last collect time for the external reward for the given incentive ID.
457// It returns an error if the current time is less than the last collect time for the external reward for the given incentive ID.
458func (self *RewardState) updateExternalReward(startTime, endTime int64, incentive *sr.ExternalIncentive) error {
459	lastCollectTime := self.deposit.ExternalRewardLastCollectTime(incentive.IncentiveId())
460	if startTime < lastCollectTime {
461		// This must not happen, but adding some guards just in case.
462		startTime = lastCollectTime
463	}
464
465	ictvStart := incentive.StartTimestamp()
466	if endTime < ictvStart {
467		return nil // Not started yet
468	}
469
470	if startTime < ictvStart {
471		startTime = ictvStart
472	}
473
474	ictvEnd := incentive.EndTimestamp()
475	if endTime > ictvEnd {
476		endTime = ictvEnd
477	}
478
479	if startTime > ictvEnd {
480		return nil // Already ended
481	}
482
483	return self.rewardPerWarmupX128(startTime, endTime, incentive.RewardPerSecondX128())
484}
485
486// calculateCollectableExternalReward calculates the calculated external reward for the deposit.
487// It calls updateExternalReward for the incentive period, applies warmup and returns the rewards and penalties.
488// used for reward calculation for a calculatable incentive
489func (self *RewardState) calculateCollectableExternalReward(startTime, endTime int64, incentive *sr.ExternalIncentive) int64 {
490	err := self.updateExternalReward(startTime, endTime, incentive)
491	if err != nil {
492		panic(err)
493	}
494
495	currentReward := u256.Zero()
496
497	for i := range self.rewards {
498		currentReward = currentReward.Add(currentReward, u256.NewUintFromInt64(self.rewards[i]))
499	}
500
501	return gnsmath.SafeConvertToInt64(currentReward)
502}
503
504// calculateExternalReward calculates the external reward for the deposit.
505// It calls rewardPerWarmup for startTime to endTime(clamped to the incentive period), applies warmup and returns the rewards and penalties.
506func (self *RewardState) calculateExternalReward(startTime, endTime int64, incentive *sr.ExternalIncentive) ([]int64, []int64) {
507	err := self.updateExternalReward(startTime, endTime, incentive)
508	if err != nil {
509		panic(err)
510	}
511
512	// apply warmup to collect rewards
513	self.applyWarmup()
514
515	return self.rewards, self.penalties
516}
517
518// applyWarmup applies the warmup to the rewards and calculate penalties.
519func (self *RewardState) applyWarmup() {
520	for i, warmup := range self.deposit.Warmups() {
521		warmupReward := self.rewards[i]
522
523		// calculate warmup reward applying warmup ratio
524		self.rewards[i] = gnsmath.SafeMulDivInt64(warmupReward, int64(warmup.WarmupRatio), 100)
525
526		// warmup penalty is the difference between the warmup reward and the warmup reward applying warmup ratio
527		self.penalties[i] = gnsmath.SafeSubInt64(warmupReward, self.rewards[i])
528	}
529}
530
531// rewardPerWarmup calculates the reward for each warmup, adds to the RewardState's rewards array.
532// Used by the internal reward path where rewardPerSecond is an int64 emission rate.
533func (self *RewardState) rewardPerWarmup(startTime, endTime int64, rewardPerSecond int64) error {
534	// Return early if startTime equals endTime to avoid unnecessary computation
535	if startTime == endTime {
536		return nil
537	}
538
539	startTick := self.pool.CurrentTick(startTime)
540	startRaw := self.pool.CalculateRawRewardForPosition(startTime, startTick, self.deposit.Deposit)
541
542	for i, warmup := range self.deposit.Warmups() {
543		if startTime >= warmup.NextWarmupTime {
544			// passed the warmup
545			continue
546		}
547
548		if endTime < warmup.NextWarmupTime {
549			endTick := self.pool.CurrentTick(endTime)
550			endRaw := self.pool.CalculateRawRewardForPosition(endTime, endTick, self.deposit.Deposit)
551			// Modular by design: boundary ticks created at different times give a
552			// wrapped base, so the borrow is expected and the wrapped difference
553			// is the true accumulation (Uniswap V3 subtracts unchecked too).
554			rewardAcc := u256.Zero().Sub(endRaw, startRaw)
555
556			rewardAcc, overflow := u256.Zero().MulOverflow(rewardAcc, self.deposit.Liquidity())
557			if overflow {
558				panic(errors.New(errOverflow))
559			}
560
561			rewardAcc = u256.MulDiv(rewardAcc, u256.NewUintFromInt64(rewardPerSecond), q128)
562			self.rewards[i] = gnsmath.SafeAddInt64(self.rewards[i], gnsmath.SafeConvertToInt64(rewardAcc))
563
564			break
565		}
566
567		endTick := self.pool.CurrentTick(warmup.NextWarmupTime)
568		endRaw := self.pool.CalculateRawRewardForPosition(warmup.NextWarmupTime, endTick, self.deposit.Deposit)
569		// See the note above: the subtraction is intentionally modular.
570		rewardAcc := u256.Zero().Sub(endRaw, startRaw)
571
572		rewardAcc, overflow := u256.Zero().MulOverflow(rewardAcc, self.deposit.Liquidity())
573		if overflow {
574			panic(errors.New(errOverflow))
575		}
576
577		rewardAcc = u256.MulDiv(rewardAcc, u256.NewUintFromInt64(rewardPerSecond), q128)
578		self.rewards[i] = gnsmath.SafeAddInt64(self.rewards[i], gnsmath.SafeConvertToInt64(rewardAcc))
579
580		startTime = warmup.NextWarmupTime
581		startTick = endTick
582		startRaw = endRaw
583	}
584
585	return nil
586}
587
588// rewardPerWarmupX128 calculates the reward for each warmup using a Q128-scaled
589// per-second rate. Used by the external incentive path; the per-second rate is
590// stored as `(rewardAmount << 128) / duration` in ExternalIncentive, so an
591// extra `>> 128` is needed after the standard `MulDiv(rewardAcc, rps, q128)`
592// to materialize the integer result.
593func (self *RewardState) rewardPerWarmupX128(startTime, endTime int64, rewardPerSecondX128 *u256.Uint) error {
594	if startTime == endTime {
595		return nil
596	}
597
598	startTick := self.pool.CurrentTick(startTime)
599	startRaw := self.pool.CalculateRawRewardForPosition(startTime, startTick, self.deposit.Deposit)
600
601	for i, warmup := range self.deposit.Warmups() {
602		if startTime >= warmup.NextWarmupTime {
603			continue
604		}
605
606		if endTime < warmup.NextWarmupTime {
607			endTick := self.pool.CurrentTick(endTime)
608			endRaw := self.pool.CalculateRawRewardForPosition(endTime, endTick, self.deposit.Deposit)
609			// Modular by design: boundary ticks created at different times give a
610			// wrapped base, so the borrow is expected and the wrapped difference
611			// is the true accumulation (Uniswap V3 subtracts unchecked too).
612			rewardAcc := u256.Zero().Sub(endRaw, startRaw)
613
614			rewardAcc, overflow := u256.Zero().MulOverflow(rewardAcc, self.deposit.Liquidity())
615			if overflow {
616				panic(errors.New(errOverflow))
617			}
618
619			rewardAcc = u256.MulDiv(rewardAcc, rewardPerSecondX128, q128)
620			rewardAcc = u256.Zero().Rsh(rewardAcc, 128)
621			self.rewards[i] = gnsmath.SafeAddInt64(self.rewards[i], gnsmath.SafeConvertToInt64(rewardAcc))
622
623			break
624		}
625
626		endTick := self.pool.CurrentTick(warmup.NextWarmupTime)
627		endRaw := self.pool.CalculateRawRewardForPosition(warmup.NextWarmupTime, endTick, self.deposit.Deposit)
628		// See the note above: the subtraction is intentionally modular.
629		rewardAcc := u256.Zero().Sub(endRaw, startRaw)
630
631		rewardAcc, overflow := u256.Zero().MulOverflow(rewardAcc, self.deposit.Liquidity())
632		if overflow {
633			panic(errors.New(errOverflow))
634		}
635
636		rewardAcc = u256.MulDiv(rewardAcc, rewardPerSecondX128, q128)
637		rewardAcc = u256.Zero().Rsh(rewardAcc, 128)
638		self.rewards[i] = gnsmath.SafeAddInt64(self.rewards[i], gnsmath.SafeConvertToInt64(rewardAcc))
639
640		startTime = warmup.NextWarmupTime
641		startTick = endTick
642		startRaw = endRaw
643	}
644
645	return nil
646}
647
648// modifyDeposit updates the pool's staked liquidity and returns the new staked liquidity.
649// updates when there is a change in the staked liquidity(tick cross, stake, unstake)
650func (self *PoolResolver) modifyDeposit(delta *i256.Int, currentTime int64, nextTick int32) *u256.Uint {
651	// update staker side pool info
652	lastStakedLiquidity := self.CurrentStakedLiquidity(currentTime)
653	deltaApplied := gnsmath.LiquidityMathAddDelta(lastStakedLiquidity, delta)
654	result := self.updateGlobalRewardRatioAccumulation(currentTime, lastStakedLiquidity)
655
656	// historical tick does NOT actually reflect the tick at the timestamp, but it provides correct ordering for the staked positions
657	// because TickCrossHook is assured to be called for the staked-initialized ticks
658	if self.isChangedTick(currentTime, nextTick) {
659		self.Pool.SetHistoricalTickAt(currentTime, nextTick)
660	}
661
662	switch deltaApplied.Sign() {
663	case -1:
664		panic("stakedLiquidity is less than 0, should not happen")
665	case 0:
666		if lastStakedLiquidity.Sign() == 1 {
667			// StakedLiquidity moved from positive to zero, start unclaimable period
668			self.startUnclaimablePeriod(currentTime)
669			self.IncentivesResolver().startUnclaimablePeriod(currentTime)
670		}
671	case 1:
672		if lastStakedLiquidity.Sign() == 0 {
673			// StakedLiquidity moved from zero to positive, end unclaimable period
674			self.endUnclaimablePeriod(currentTime)
675			self.IncentivesResolver().endUnclaimablePeriod(currentTime)
676		}
677	}
678
679	// Only append a staked-liquidity entry when the value actually changes (e.g. a tick cross whose
680	// net delta is zero leaves it unchanged). Unlike the global reward ratio accumulation, this tree
681	// carries no time-checkpoint semantics: it is read purely as a point-in-time value via
682	// CurrentStakedLiquidity (latest entry <= t), so omitting a duplicate-valued entry preserves
683	// behavior while keeping this append-only tree from growing on no-op updates.
684	if !lastStakedLiquidity.Eq(deltaApplied) {
685		self.Pool.SetStakedLiquidityAt(currentTime, deltaApplied)
686	}
687
688	return result
689}
690
691// startUnclaimablePeriod starts the unclaimable period.
692func (self *PoolResolver) startUnclaimablePeriod(currentTime int64) {
693	if self.LastUnclaimableTime() == 0 {
694		// We set only if it's the first time entering(0 indicates not set yet)
695		self.SetLastUnclaimableTime(currentTime)
696	}
697}
698
699// endUnclaimablePeriod ends the unclaimable period.
700// Accumulates to unclaimableAcc and resets lastUnclaimableTime to 0.
701func (self *PoolResolver) endUnclaimablePeriod(currentTime int64) {
702	if self.LastUnclaimableTime() == 0 {
703		// lastUnclaimableTime = 0 means tracking hasn't started yet
704		// This is normal during initial pool creation or when called from cacheReward
705		// during tier assignment with zero liquidity
706		return
707	}
708
709	self.updateUnclaimableAccumulateRewards(currentTime)
710	self.SetLastUnclaimableTime(0)
711}
712
713// updateUnclaimableAccumulateRewards ends the unclaimable period.
714// Accumulates to unclaimableAcc and resets lastUnclaimableTime to 0.
715func (self *PoolResolver) updateUnclaimableAccumulateRewards(currentTime int64) {
716	if self.LastUnclaimableTime() >= currentTime {
717		return
718	}
719
720	unclaimableDuration := gnsmath.SafeSubInt64(currentTime, self.LastUnclaimableTime())
721	currentUnclaimableReward := gnsmath.SafeMulInt64(unclaimableDuration, self.CurrentReward(self.LastUnclaimableTime()))
722	self.SetUnclaimableAcc(gnsmath.SafeAddInt64(self.UnclaimableAcc(), currentUnclaimableReward))
723}
724
725// processUnclaimableReward processes the unclaimable reward and returns the accumulated reward.
726// It resets unclaimableAcc to 0 and properly manages lastUnclaimableTime based on pool state.
727func (self *PoolResolver) processUnclaimableReward(endTime int64) int64 {
728	// Check current pool liquidity state
729	isZeroStakedLiquidity := self.CurrentStakedLiquidity(endTime).IsZero()
730
731	if self.LastUnclaimableTime() > 0 {
732		// We have an ongoing unclaimable period tracking
733		self.updateUnclaimableAccumulateRewards(endTime)
734
735		if isZeroStakedLiquidity {
736			// Still unclaimable - accumulate rewards up to endTime
737			// Update tracking time for continuing unclaimable period
738			self.SetLastUnclaimableTime(endTime)
739		} else {
740			// Was unclaimable but now has liquidity - properly end the period
741			self.SetLastUnclaimableTime(0)
742		}
743	} else {
744		if isZeroStakedLiquidity {
745			// No previous tracking but currently unclaimable - this shouldn't normally happen
746			// as startUnclaimablePeriod should have been called when liquidity reached 0
747			// Start tracking from now
748			self.SetLastUnclaimableTime(endTime)
749		}
750	}
751
752	// Return and reset accumulated unclaimable rewards
753	internalUnClaimable := self.UnclaimableAcc()
754	self.SetUnclaimableAcc(0)
755	return internalUnClaimable
756}
757
758// CalculateRawRewardForPosition calculates the theoretical reward accumulator for a position without debt or warmup adjustments.
759//
760// Parameters:
761//   - currentTime: Unix timestamp at which pool reward state is evaluated.
762//   - currentTick: Pool tick used to determine whether the position is below, inside, or above its range.
763//   - deposit: Position deposit whose liquidity and boundary ticks determine the raw reward.
764//
765// Returns:
766//   - reward: Q128-scaled raw reward accumulator for the position; debt, warmup ratios, and fees are not applied.
767func (self *PoolResolver) CalculateRawRewardForPosition(currentTime int64, currentTick int32, deposit *sr.Deposit) *u256.Uint {
768	var rewardAcc *u256.Uint
769
770	globalAcc := self.calculateGlobalRewardRatioAccumulation(currentTime, self.CurrentStakedLiquidity(currentTime))
771
772	lowerAcc := self.outsideAccumulationAt(deposit.TickLower(), currentTime)
773	upperAcc := self.outsideAccumulationAt(deposit.TickUpper(), currentTime)
774	if currentTick < deposit.TickLower() {
775		rewardAcc = u256.Zero().Sub(lowerAcc, upperAcc)
776	} else if currentTick >= deposit.TickUpper() {
777		rewardAcc = u256.Zero().Sub(upperAcc, lowerAcc)
778	} else {
779		rewardAcc = u256.Zero().Sub(globalAcc, lowerAcc)
780		rewardAcc = rewardAcc.Sub(rewardAcc, upperAcc)
781	}
782
783	return rewardAcc
784}