reward_state.gno

  1package launchpad
  2
  3import (
  4	u256 "gno.land/p/gnoswap/uint256/v1"
  5)
  6
  7// RewardState represents the state of a reward for a deposit.
  8// It contains the necessary data to manage and distribute rewards for a specific deposit.
  9type RewardState struct {
 10	priceDebtX128 *u256.Uint // price debt per GNS stake, Q128
 11	claimableTime int64      // time when reward can be claimed
 12
 13	depositAmount           int64 // amount of GNS staked
 14	distributeStartTime     int64 // time when launchpad started staking
 15	distributeEndTime       int64 // end time of reward calculation
 16	accumulatedRewardAmount int64 // legacy field; v1 reward accounting does not populate it
 17	accumulatedTime         int64 // last time when reward was calculated
 18	claimedAmount           int64 // amount of reward claimed so far
 19}
 20
 21// NewRewardState creates a reward state initialized from a reward-per-deposit index.
 22//
 23// Parameters:
 24//   - accumulatedRewardPerDepositX128: current accumulated reward-per-deposit index in Q128 fixed-point units; it becomes this deposit's initial price debt.
 25//   - depositAmount: GNS amount staked by the deposit, in base units.
 26//   - distributeStartTime: Unix timestamp in seconds when this deposit begins accruing rewards.
 27//   - distributeEndTime: Unix timestamp in seconds when this deposit stops accruing rewards.
 28//   - claimableTime: Unix timestamp in seconds after which the accrued reward can be claimed.
 29//
 30// Returns:
 31//   - rewardState: newly allocated state with claimed and legacy accumulation fields initialized to zero.
 32func NewRewardState(
 33	accumulatedRewardPerDepositX128 *u256.Uint,
 34	depositAmount,
 35	distributeStartTime,
 36	distributeEndTime int64,
 37	claimableTime int64,
 38) *RewardState {
 39	return &RewardState{
 40		priceDebtX128:           accumulatedRewardPerDepositX128,
 41		depositAmount:           depositAmount,
 42		distributeStartTime:     distributeStartTime,
 43		distributeEndTime:       distributeEndTime,
 44		claimableTime:           claimableTime,
 45		accumulatedRewardAmount: 0,
 46		claimedAmount:           0,
 47	}
 48}
 49
 50// PriceDebtX128 returns the deposit's initial reward index debt in Q128 fixed-point units.
 51//
 52// Returns:
 53//   - debt: stored price debt used to subtract rewards accrued before this deposit joined.
 54func (rs *RewardState) PriceDebtX128() *u256.Uint {
 55	return rs.priceDebtX128
 56}
 57
 58// SetPriceDebtX128 replaces the deposit's initial reward index debt.
 59//
 60// Parameters:
 61//   - debt: new price debt in Q128 fixed-point units; the value is copied into the state.
 62func (rs *RewardState) SetPriceDebtX128(debt *u256.Uint) {
 63	rs.priceDebtX128 = u256.Zero().Set(debt)
 64}
 65
 66// ClaimableTime returns the earliest Unix timestamp at which this reward may be claimed.
 67//
 68// Returns:
 69//   - claimableTime: claimability timestamp in Unix seconds.
 70func (rs *RewardState) ClaimableTime() int64 {
 71	return rs.claimableTime
 72}
 73
 74// SetClaimableTime sets the earliest Unix timestamp at which this reward may be claimed.
 75//
 76// Parameters:
 77//   - time: claimability timestamp in Unix seconds.
 78func (rs *RewardState) SetClaimableTime(time int64) {
 79	rs.claimableTime = time
 80}
 81
 82// DepositAmount returns the GNS principal represented by this reward state.
 83//
 84// Returns:
 85//   - amount: staked GNS amount in base units used for reward allocation.
 86func (rs *RewardState) DepositAmount() int64 {
 87	return rs.depositAmount
 88}
 89
 90// SetDepositAmount replaces the GNS principal represented by this reward state.
 91//
 92// Parameters:
 93//   - amount: staked GNS amount in base units used for reward allocation.
 94func (rs *RewardState) SetDepositAmount(amount int64) {
 95	rs.depositAmount = amount
 96}
 97
 98// DistributeStartTime returns the Unix timestamp when this deposit starts accruing rewards.
 99//
100// Returns:
101//   - startTime: reward accrual start timestamp in Unix seconds.
102func (rs *RewardState) DistributeStartTime() int64 {
103	return rs.distributeStartTime
104}
105
106// SetDistributeStartTime sets the Unix timestamp when this deposit starts accruing rewards.
107//
108// Parameters:
109//   - time: reward accrual start timestamp in Unix seconds.
110func (rs *RewardState) SetDistributeStartTime(time int64) {
111	rs.distributeStartTime = time
112}
113
114// DistributeEndTime returns the Unix timestamp when this deposit stops accruing rewards.
115//
116// Returns:
117//   - endTime: reward accrual end timestamp in Unix seconds.
118func (rs *RewardState) DistributeEndTime() int64 {
119	return rs.distributeEndTime
120}
121
122// SetDistributeEndTime sets the Unix timestamp when this deposit stops accruing rewards.
123//
124// Parameters:
125//   - time: reward accrual end timestamp in Unix seconds.
126func (rs *RewardState) SetDistributeEndTime(time int64) {
127	rs.distributeEndTime = time
128}
129
130// AccumulatedRewardAmount returns the legacy accumulated reward field.
131//
132// Returns:
133//   - amount: legacy reward amount in token base units; v1 accounting normally leaves it at zero unless explicitly set.
134func (rs *RewardState) AccumulatedRewardAmount() int64 {
135	return rs.accumulatedRewardAmount
136}
137
138// SetAccumulatedRewardAmount sets the legacy accumulated reward field.
139//
140// Parameters:
141//   - amount: legacy reward amount in token base units; v1 accounting does not update this field.
142func (rs *RewardState) SetAccumulatedRewardAmount(amount int64) {
143	rs.accumulatedRewardAmount = amount
144}
145
146// AccumulatedTime returns the last timestamp recorded for reward accumulation.
147//
148// Returns:
149//   - time: last accumulated timestamp in Unix seconds, or zero before one is recorded.
150func (rs *RewardState) AccumulatedTime() int64 {
151	return rs.accumulatedTime
152}
153
154// SetAccumulatedTime sets the last timestamp recorded for reward accumulation.
155//
156// Parameters:
157//   - time: last accumulated timestamp in Unix seconds.
158func (rs *RewardState) SetAccumulatedTime(time int64) {
159	rs.accumulatedTime = time
160}
161
162// ClaimedAmount returns the reward amount already claimed for this deposit.
163//
164// Returns:
165//   - amount: claimed reward amount in token base units.
166func (rs *RewardState) ClaimedAmount() int64 {
167	return rs.claimedAmount
168}
169
170// SetClaimedAmount replaces the reward amount already claimed for this deposit.
171//
172// Parameters:
173//   - amount: claimed reward amount in token base units.
174func (rs *RewardState) SetClaimedAmount(amount int64) {
175	rs.claimedAmount = amount
176}
177
178// Clone returns an independent copy of this reward state, including a cloned Q128 price debt value.
179//
180// Returns:
181//   - rewardState: deep copy of the reward state that can be modified without changing the source.
182func (rs RewardState) Clone() *RewardState {
183	return &RewardState{
184		priceDebtX128:           rs.priceDebtX128.Clone(),
185		claimableTime:           rs.claimableTime,
186		depositAmount:           rs.depositAmount,
187		distributeStartTime:     rs.distributeStartTime,
188		distributeEndTime:       rs.distributeEndTime,
189		accumulatedRewardAmount: rs.accumulatedRewardAmount,
190		accumulatedTime:         rs.accumulatedTime,
191		claimedAmount:           rs.claimedAmount,
192	}
193}