reward_manager.gno

  1package launchpad
  2
  3import (
  4	bptree "gno.land/p/nt/bptree/v0"
  5
  6	u256 "gno.land/p/gnoswap/uint256/v1"
  7)
  8
  9// RewardManager manages the distribution of rewards for a project tier.
 10//
 11// This struct contains the necessary data and methods to calculate and track
 12// rewards for deposits associated with a project tier.
 13//
 14// Fields:
 15// - rewards (bptree.BPTree): A map of deposit IDs to their associated reward states.
 16// - distributeAmountPerSecondX128 (u256.Uint): The amount of tokens to be distributed per second, represented as a Q128 fixed-point number.
 17// - accumulatedRewardPerDepositX128 (u256.Uint): The accumulated reward per GNS stake, represented as a Q128 fixed-point number.
 18// - totalDistributeAmount (int64): The total token allocation for this tier.
 19// - totalClaimedAmount (int64): The total amount of tokens claimed.
 20// - distributeStartTime (int64): The start time of the reward calculation.
 21// - distributeEndTime (int64): The end time of the reward calculation.
 22// - accumulatedDistributeAmount (int64): A legacy field not maintained by v1 reward accounting; normally zero unless explicitly set.
 23// - rewardClaimableDuration (int64): The duration of reward claimable.
 24type RewardManager struct {
 25	rewards *bptree.BPTree // depositId -> RewardState
 26
 27	distributeAmountPerSecondX128   *u256.Uint // distribute amount per second, Q128
 28	accumulatedRewardPerDepositX128 *u256.Uint // accumulated reward per GNS stake, Q128
 29
 30	totalDistributeAmount       int64 // total token allocation for this tier
 31	totalClaimedAmount          int64 // total claimed amount
 32	activeDepositAmount         int64 // principal represented by active reward states
 33	activeClaimedAmount         int64 // claims paid to active reward states
 34	distributeStartTime         int64 // start time of reward calculation
 35	distributeEndTime           int64 // end time of reward calculation
 36	accumulatedDistributeAmount int64 // legacy field; v1 reward paths do not update it
 37	accumulatedTime             int64 // last time when reward was calculated
 38	rewardClaimableDuration     int64 // duration of reward claimable
 39
 40	activePriceDebtX128 *u256.Uint // sum of active deposit amount × initial reward index
 41}
 42
 43// Rewards returns the rewards tree of the reward manager.
 44//
 45// Returns:
 46//   - rewards: reward-state tree keyed by deposit ID.
 47func (rm *RewardManager) Rewards() *bptree.BPTree {
 48	return rm.rewards
 49}
 50
 51// SetRewards sets the rewards tree of the reward manager.
 52//
 53// Parameters:
 54//   - rewards: reward-state tree to use for this manager.
 55func (rm *RewardManager) SetRewards(rewards *bptree.BPTree) {
 56	rm.rewards = rewards
 57}
 58
 59// SetReward associates a reward state with a deposit ID in the manager's reward tree.
 60//
 61// Parameters:
 62//   - depositID: deposit identifier used as the reward-tree key.
 63//   - rewardState: reward state to store for that deposit.
 64func (rm *RewardManager) SetReward(depositID string, rewardState *RewardState) {
 65	rm.rewards.Set(depositID, rewardState)
 66}
 67
 68// RemoveReward removes the reward state associated with a deposit ID.
 69//
 70// Parameters:
 71//   - depositID: deposit identifier whose reward state is removed.
 72func (rm *RewardManager) RemoveReward(depositID string) {
 73	rm.rewards.Remove(depositID)
 74}
 75
 76// DistributeAmountPerSecondX128 returns the distribute amount per second (Q128) of the reward manager.
 77//
 78// Returns:
 79//   - amountPerSecondX128: reward distribution rate in Q128 fixed-point token units per second.
 80func (rm *RewardManager) DistributeAmountPerSecondX128() *u256.Uint {
 81	return rm.distributeAmountPerSecondX128
 82}
 83
 84// SetDistributeAmountPerSecondX128 sets the distribute amount per second (Q128) of the reward manager.
 85//
 86// Parameters:
 87//   - amount: replacement reward distribution rate in Q128 fixed-point token units per second; the value is copied.
 88func (rm *RewardManager) SetDistributeAmountPerSecondX128(amount *u256.Uint) {
 89	rm.distributeAmountPerSecondX128 = u256.Zero().Set(amount)
 90}
 91
 92// AccumulatedRewardPerDepositX128 returns the accumulated reward per deposit (Q128) of the reward manager.
 93//
 94// Returns:
 95//   - accumulatedRewardPerDepositX128: accumulated reward index per deposited GNS unit in Q128 fixed-point units.
 96func (rm *RewardManager) AccumulatedRewardPerDepositX128() *u256.Uint {
 97	return rm.accumulatedRewardPerDepositX128
 98}
 99
100// SetAccumulatedRewardPerDepositX128 sets the accumulated reward per deposit (Q128) of the reward manager.
101//
102// Parameters:
103//   - amount: replacement accumulated reward-per-deposit index in Q128 fixed-point units; the value is copied.
104func (rm *RewardManager) SetAccumulatedRewardPerDepositX128(amount *u256.Uint) {
105	rm.accumulatedRewardPerDepositX128 = u256.Zero().Set(amount)
106}
107
108// TotalDistributeAmount returns the total distribute amount of the reward manager.
109//
110// Returns:
111//   - amount: total reward allocation for the tier in token base units.
112func (rm *RewardManager) TotalDistributeAmount() int64 {
113	return rm.totalDistributeAmount
114}
115
116// SetTotalDistributeAmount sets the total distribute amount of the reward manager.
117//
118// Parameters:
119//   - amount: total reward allocation for the tier in token base units.
120func (rm *RewardManager) SetTotalDistributeAmount(amount int64) {
121	rm.totalDistributeAmount = amount
122}
123
124// TotalClaimedAmount returns the total claimed amount of the reward manager.
125//
126// Returns:
127//   - amount: total reward amount claimed from the tier in token base units.
128func (rm *RewardManager) TotalClaimedAmount() int64 {
129	return rm.totalClaimedAmount
130}
131
132// SetTotalClaimedAmount sets the total claimed amount of the reward manager.
133//
134// Parameters:
135//   - amount: total claimed reward amount in token base units.
136func (rm *RewardManager) SetTotalClaimedAmount(amount int64) {
137	rm.totalClaimedAmount = amount
138}
139
140// ActiveDepositAmount returns the principal represented by currently active reward states.
141//
142// Returns:
143//   - amount: active deposited GNS principal in base units.
144func (rm *RewardManager) ActiveDepositAmount() int64 {
145	return rm.activeDepositAmount
146}
147
148// SetActiveDepositAmount replaces the principal represented by currently active reward states.
149//
150// Parameters:
151//   - amount: active deposited GNS principal in base units.
152func (rm *RewardManager) SetActiveDepositAmount(amount int64) {
153	rm.activeDepositAmount = amount
154}
155
156// ActiveClaimedAmount returns the reward amount claimed by currently active reward states.
157//
158// Returns:
159//   - amount: active claimed reward amount in token base units.
160func (rm *RewardManager) ActiveClaimedAmount() int64 {
161	return rm.activeClaimedAmount
162}
163
164// SetActiveClaimedAmount replaces the reward amount claimed by currently active reward states.
165//
166// Parameters:
167//   - amount: active claimed reward amount in token base units.
168func (rm *RewardManager) SetActiveClaimedAmount(amount int64) {
169	rm.activeClaimedAmount = amount
170}
171
172// ActivePriceDebtX128 returns the sum of active deposits' initial reward-index debts.
173//
174// Returns:
175//   - debt: aggregate active price debt in Q128 fixed-point units.
176func (rm *RewardManager) ActivePriceDebtX128() *u256.Uint {
177	return rm.activePriceDebtX128
178}
179
180// SetActivePriceDebtX128 replaces the aggregate active price-index debt.
181//
182// Parameters:
183//   - debt: aggregate active price debt in Q128 fixed-point units; the value is copied.
184func (rm *RewardManager) SetActivePriceDebtX128(debt *u256.Uint) {
185	rm.activePriceDebtX128 = u256.Zero().Set(debt)
186}
187
188// DistributeStartTime returns the distribute start time of the reward manager.
189//
190// Returns:
191//   - startTime: reward distribution start timestamp in Unix seconds.
192func (rm *RewardManager) DistributeStartTime() int64 {
193	return rm.distributeStartTime
194}
195
196// SetDistributeStartTime sets the distribute start time of the reward manager.
197//
198// Parameters:
199//   - time: reward distribution start timestamp in Unix seconds.
200func (rm *RewardManager) SetDistributeStartTime(time int64) {
201	rm.distributeStartTime = time
202}
203
204// DistributeEndTime returns the distribute end time of the reward manager.
205//
206// Returns:
207//   - endTime: reward distribution end timestamp in Unix seconds.
208func (rm *RewardManager) DistributeEndTime() int64 {
209	return rm.distributeEndTime
210}
211
212// SetDistributeEndTime sets the distribute end time of the reward manager.
213//
214// Parameters:
215//   - time: reward distribution end timestamp in Unix seconds.
216func (rm *RewardManager) SetDistributeEndTime(time int64) {
217	rm.distributeEndTime = time
218}
219
220// AccumulatedDistributeAmount returns the legacy reward-manager field.
221// v1 reward paths do not maintain it, so normal reads return zero unless it was
222// explicitly set.
223//
224// Returns:
225//   - amount: legacy accumulated distribution amount in token base units; v1 accounting normally leaves it at zero unless explicitly set.
226func (rm *RewardManager) AccumulatedDistributeAmount() int64 {
227	return rm.accumulatedDistributeAmount
228}
229
230// SetAccumulatedDistributeAmount sets the legacy reward-manager field. It is not
231// used by v1 reward accounting.
232//
233// Parameters:
234//   - amount: legacy accumulated distribution amount in token base units; v1 accounting does not update this field.
235func (rm *RewardManager) SetAccumulatedDistributeAmount(amount int64) {
236	rm.accumulatedDistributeAmount = amount
237}
238
239// AccumulatedTime returns the accumulated time of the reward manager.
240//
241// Returns:
242//   - time: last reward-accumulation timestamp in Unix seconds, or zero before accumulation.
243func (rm *RewardManager) AccumulatedTime() int64 {
244	return rm.accumulatedTime
245}
246
247// SetAccumulatedTime sets the accumulated time of the reward manager.
248//
249// Parameters:
250//   - time: last reward-accumulation timestamp in Unix seconds.
251func (rm *RewardManager) SetAccumulatedTime(time int64) {
252	rm.accumulatedTime = time
253}
254
255// RewardClaimableDuration returns the reward claimable duration of the reward manager.
256//
257// Returns:
258//   - duration: time after a reward becomes claimable during which it remains collectible, in seconds.
259func (rm *RewardManager) RewardClaimableDuration() int64 {
260	return rm.rewardClaimableDuration
261}
262
263// SetRewardClaimableDuration sets the reward claimable duration of the reward manager.
264//
265// Parameters:
266//   - duration: claimable reward window in seconds.
267func (rm *RewardManager) SetRewardClaimableDuration(duration int64) {
268	rm.rewardClaimableDuration = duration
269}
270
271// Clone returns an independent copy of the reward manager, including its reward states and Q128 values.
272//
273// Returns:
274//   - rewardManager: deep copy with a separate reward tree and mutable numeric values.
275func (rm RewardManager) Clone() *RewardManager {
276	rewardsTree := bptree.NewBPTreeN(16)
277	rm.rewards.Iterate("", "", func(key string, value interface{}) bool {
278		rewardState, ok := value.(*RewardState)
279		if !ok {
280			return true
281		}
282		rewardsTree.Set(key, rewardState.Clone())
283		return false
284	})
285
286	return &RewardManager{
287		rewards:                         rewardsTree,
288		distributeAmountPerSecondX128:   rm.distributeAmountPerSecondX128.Clone(),
289		accumulatedRewardPerDepositX128: rm.accumulatedRewardPerDepositX128.Clone(),
290		totalDistributeAmount:           rm.totalDistributeAmount,
291		totalClaimedAmount:              rm.totalClaimedAmount,
292		activeDepositAmount:             rm.activeDepositAmount,
293		activeClaimedAmount:             rm.activeClaimedAmount,
294		distributeStartTime:             rm.distributeStartTime,
295		distributeEndTime:               rm.distributeEndTime,
296		accumulatedDistributeAmount:     rm.accumulatedDistributeAmount,
297		accumulatedTime:                 rm.accumulatedTime,
298		rewardClaimableDuration:         rm.rewardClaimableDuration,
299		activePriceDebtX128:             rm.activePriceDebtX128.Clone(),
300	}
301}
302
303// NewRewardManager returns a pointer to a new RewardManager with the given values.
304//
305// Parameters:
306//   - totalDistributeAmount: total reward allocation for the tier in token base units.
307//   - distributeStartTime: reward distribution start timestamp in Unix seconds.
308//   - distributeEndTime: reward distribution end timestamp in Unix seconds.
309//   - rewardCollectableDuration: duration in seconds for which each accrued reward remains claimable.
310//
311// Returns:
312//   - rewardManager: initialized manager with zeroed accounting counters and an empty reward tree.
313func NewRewardManager(
314	totalDistributeAmount int64,
315	distributeStartTime int64,
316	distributeEndTime int64,
317	rewardCollectableDuration int64,
318) *RewardManager {
319	return &RewardManager{
320		totalDistributeAmount:           totalDistributeAmount,
321		distributeStartTime:             distributeStartTime,
322		distributeEndTime:               distributeEndTime,
323		totalClaimedAmount:              0,
324		activeDepositAmount:             0,
325		activeClaimedAmount:             0,
326		accumulatedDistributeAmount:     0,
327		accumulatedTime:                 0,
328		accumulatedRewardPerDepositX128: u256.Zero(),
329		distributeAmountPerSecondX128:   u256.Zero(),
330		rewardClaimableDuration:         rewardCollectableDuration,
331		activePriceDebtX128:             u256.Zero(),
332		rewards:                         bptree.NewBPTreeN(16),
333	}
334}