project_tier.gno

  1package launchpad
  2
  3import (
  4	ufmt "gno.land/p/nt/ufmt/v0"
  5
  6	u256 "gno.land/p/gnoswap/uint256/v1"
  7)
  8
  9// ProjectTier represents a tier within a project.
 10//
 11// This struct contains the necessary data and methods to manage and distribute
 12// rewards for a specific tier of a project.
 13//
 14// Fields:
 15// - distributeAmountPerSecondX128 (u256.Uint): The amount of tokens to be distributed per second, represented as a Q128 fixed-point number.
 16// - startTime (int64): The time for the start of the tier.
 17// - endTime (int64): The time for the end of the tier.
 18// - id (string): The unique identifier for the tier, formatted as "{projectID}:duration".
 19// - totalDistributeAmount (int64): The total amount of tokens to be distributed for the tier.
 20// - totalDepositAmount (int64): The total amount of tokens deposited for the tier.
 21// - totalWithdrawAmount (int64): The total amount of tokens withdrawn from the tier.
 22// - totalDepositCount (int64): The total number of deposits made to the tier.
 23// - totalWithdrawCount (int64): The total number of withdrawals from the tier.
 24// - totalCollectedAmount (int64): The total amount of tokens collected as rewards for the tier.
 25type ProjectTier struct {
 26	distributeAmountPerSecondX128 *u256.Uint // distribute amount per second, Q128
 27	id                            string     // '{projectId}:duration' // duration == 30, 90, 180
 28	totalDistributeAmount         int64
 29	totalDepositAmount            int64 // accumulated deposit amount
 30	totalWithdrawAmount           int64 // accumulated withdraw amount
 31	totalDepositCount             int64 // accumulated deposit count
 32	totalWithdrawCount            int64 // accumulated withdraw count
 33	totalCollectedAmount          int64 // total collected amount by user (reward)
 34	startTime                     int64
 35	endTime                       int64
 36}
 37
 38// DistributeAmountPerSecondX128 returns the distribute amount per second (Q128) of the project tier.
 39//
 40// Returns:
 41//   - amount: per-second distribution rate encoded as a Q128 fixed-point value.
 42func (pt *ProjectTier) DistributeAmountPerSecondX128() *u256.Uint {
 43	return pt.distributeAmountPerSecondX128
 44}
 45
 46// SetDistributeAmountPerSecondX128 sets the distribute amount per second (Q128) of the project tier.
 47//
 48// Parameters:
 49//   - amount: per-second distribution rate to store, encoded as a Q128 fixed-point value.
 50func (pt *ProjectTier) SetDistributeAmountPerSecondX128(amount *u256.Uint) {
 51	pt.distributeAmountPerSecondX128 = u256.Zero().Set(amount)
 52}
 53
 54// ID returns the ID of the project tier.
 55//
 56// Returns:
 57//   - id: tier identifier in the "{projectID}:{duration}" form.
 58func (pt *ProjectTier) ID() string {
 59	return pt.id
 60}
 61
 62// SetID sets the ID of the project tier.
 63//
 64// Parameters:
 65//   - id: tier identifier to store, normally "{projectID}:{duration}".
 66func (pt *ProjectTier) SetID(id string) {
 67	pt.id = id
 68}
 69
 70// TotalDistributeAmount returns the total distribute amount of the project tier.
 71//
 72// Returns:
 73//   - amount: total token amount allocated for distribution by this tier.
 74func (pt *ProjectTier) TotalDistributeAmount() int64 {
 75	return pt.totalDistributeAmount
 76}
 77
 78// SetTotalDistributeAmount sets the total distribute amount of the project tier.
 79//
 80// Parameters:
 81//   - amount: total token amount allocated for distribution by this tier.
 82func (pt *ProjectTier) SetTotalDistributeAmount(amount int64) {
 83	pt.totalDistributeAmount = amount
 84}
 85
 86// TotalDepositAmount returns the total deposit amount of the project tier.
 87//
 88// Returns:
 89//   - amount: aggregate token amount deposited into this tier.
 90func (pt *ProjectTier) TotalDepositAmount() int64 {
 91	return pt.totalDepositAmount
 92}
 93
 94// SetTotalDepositAmount sets the total deposit amount of the project tier.
 95//
 96// Parameters:
 97//   - amount: aggregate token amount to record as deposited into this tier.
 98func (pt *ProjectTier) SetTotalDepositAmount(amount int64) {
 99	pt.totalDepositAmount = amount
100}
101
102// TotalWithdrawAmount returns the total withdraw amount of the project tier.
103//
104// Returns:
105//   - amount: aggregate token amount withdrawn from this tier.
106func (pt *ProjectTier) TotalWithdrawAmount() int64 {
107	return pt.totalWithdrawAmount
108}
109
110// SetTotalWithdrawAmount sets the total withdraw amount of the project tier.
111//
112// Parameters:
113//   - amount: aggregate token amount to record as withdrawn from this tier.
114func (pt *ProjectTier) SetTotalWithdrawAmount(amount int64) {
115	pt.totalWithdrawAmount = amount
116}
117
118// TotalDepositCount returns the total deposit count of the project tier.
119//
120// Returns:
121//   - count: number of deposits recorded for this tier.
122func (pt *ProjectTier) TotalDepositCount() int64 {
123	return pt.totalDepositCount
124}
125
126// SetTotalDepositCount sets the total deposit count of the project tier.
127//
128// Parameters:
129//   - count: number of deposits to record for this tier.
130func (pt *ProjectTier) SetTotalDepositCount(count int64) {
131	pt.totalDepositCount = count
132}
133
134// TotalWithdrawCount returns the total withdraw count of the project tier.
135//
136// Returns:
137//   - count: number of withdrawals recorded for this tier.
138func (pt *ProjectTier) TotalWithdrawCount() int64 {
139	return pt.totalWithdrawCount
140}
141
142// SetTotalWithdrawCount sets the total withdraw count of the project tier.
143//
144// Parameters:
145//   - count: number of withdrawals to record for this tier.
146func (pt *ProjectTier) SetTotalWithdrawCount(count int64) {
147	pt.totalWithdrawCount = count
148}
149
150// TotalCollectedAmount returns the total collected amount of the project tier.
151//
152// Returns:
153//   - amount: aggregate reward amount collected from this tier.
154func (pt *ProjectTier) TotalCollectedAmount() int64 {
155	return pt.totalCollectedAmount
156}
157
158// SetTotalCollectedAmount sets the total collected amount of the project tier.
159//
160// Parameters:
161//   - amount: aggregate reward amount to record as collected from this tier.
162func (pt *ProjectTier) SetTotalCollectedAmount(amount int64) {
163	pt.totalCollectedAmount = amount
164}
165
166// StartTime returns the start time of the project tier.
167//
168// Returns:
169//   - time: tier start timestamp in Unix seconds.
170func (pt *ProjectTier) StartTime() int64 {
171	return pt.startTime
172}
173
174// SetStartTime sets the start time of the project tier.
175//
176// Parameters:
177//   - time: tier start timestamp in Unix seconds.
178func (pt *ProjectTier) SetStartTime(time int64) {
179	pt.startTime = time
180}
181
182// EndTime returns the end time of the project tier.
183//
184// Returns:
185//   - time: tier end timestamp in Unix seconds.
186func (pt *ProjectTier) EndTime() int64 {
187	return pt.endTime
188}
189
190// SetEndTime sets the end time of the project tier.
191//
192// Parameters:
193//   - time: tier end timestamp in Unix seconds.
194func (pt *ProjectTier) SetEndTime(time int64) {
195	pt.endTime = time
196}
197
198// IsActivated reports whether the tier is active at the supplied timestamp.
199//
200// Parameters:
201//   - currentTime: timestamp in Unix seconds to compare with the tier window.
202//
203// Returns:
204//   - activated: true when startTime <= currentTime and currentTime < endTime; false otherwise.
205func (pt *ProjectTier) IsActivated(currentTime int64) bool {
206	return pt.startTime <= currentTime && currentTime < pt.endTime
207}
208
209// IsEnded returns true if the project tier has ended.
210//
211// Parameters:
212//   - currentTime: timestamp in Unix seconds to compare with the tier end time.
213//
214// Returns:
215//   - ended: true when endTime is strictly less than currentTime; false at or before the end time.
216func (pt *ProjectTier) IsEnded(currentTime int64) bool {
217	return pt.endTime < currentTime
218}
219
220// Clone returns an independent copy of the project tier, including a cloned
221// Q128 distribution-rate value and all aggregate counters.
222//
223// Returns:
224//   - clone: copy whose mutable fixed-point value is independent of the receiver.
225func (pt ProjectTier) Clone() *ProjectTier {
226	return &ProjectTier{
227		id:                            pt.id,
228		totalDistributeAmount:         pt.totalDistributeAmount,
229		distributeAmountPerSecondX128: pt.distributeAmountPerSecondX128.Clone(),
230		startTime:                     pt.startTime,
231		endTime:                       pt.endTime,
232		totalDepositAmount:            pt.totalDepositAmount,
233		totalWithdrawAmount:           pt.totalWithdrawAmount,
234		totalDepositCount:             pt.totalDepositCount,
235		totalWithdrawCount:            pt.totalWithdrawCount,
236		totalCollectedAmount:          pt.totalCollectedAmount,
237	}
238}
239
240// NewProjectTier returns a pointer to a new ProjectTier with the given values.
241//
242// Parameters:
243//   - projectID: launchpad project identifier associated with the tier.
244//   - tierDuration: tier duration in days; launchpad tiers use 30, 90, or 180.
245//   - totalDistributeAmount: total token amount allocated for this tier.
246//   - startTime: tier start timestamp in Unix seconds.
247//   - endTime: tier end timestamp in Unix seconds.
248//
249// Returns:
250//   - tier: new ProjectTier with the supplied identity, allocation, and time window; counters and rates start at zero.
251func NewProjectTier(
252	projectID string,
253	tierDuration int64,
254	totalDistributeAmount int64,
255	startTime int64,
256	endTime int64,
257) *ProjectTier {
258	return &ProjectTier{
259		id:                            MakeProjectTierID(projectID, tierDuration),
260		totalDistributeAmount:         totalDistributeAmount,
261		distributeAmountPerSecondX128: u256.Zero(),
262		startTime:                     startTime,
263		endTime:                       endTime,
264		totalDepositAmount:            0,
265		totalWithdrawAmount:           0,
266		totalDepositCount:             0,
267		totalWithdrawCount:            0,
268		totalCollectedAmount:          0,
269	}
270}
271
272// MakeProjectTierID constructs the tier identifier from a project ID and duration.
273// The resulting identifier uses the "{projectID}:{duration}" format.
274//
275// Parameters:
276//   - projectID: unique launchpad project identifier associated with the tier.
277//   - duration: tier duration in days, such as 30, 90, or 180.
278//
279// Returns:
280//   - projectTierID: identifier combining projectID and duration with a colon.
281func MakeProjectTierID(projectID string, duration int64) string {
282	return ufmt.Sprintf("%s:%d", projectID, duration)
283}