getter.gno

  1package gns
  2
  3import (
  4	"time"
  5
  6	gnsmath "gno.land/p/gnoswap/gnsmath/v1"
  7)
  8
  9// GetMaxEmissionAmount returns the configured lifetime GNS emission cap in base units.
 10//
 11// Returns:
 12//   - maxAmount: maximum number of GNS base units available for emission
 13func GetMaxEmissionAmount() int64 {
 14	return MAX_EMISSION_AMOUNT
 15}
 16
 17// GetMaximumSupply returns the maximum possible GNS token supply in base units.
 18//
 19// Returns:
 20//   - maximumSupply: configured total supply cap, including the initial mint and emissions
 21func GetMaximumSupply() int64 {
 22	return MAXIMUM_SUPPLY
 23}
 24
 25// GetInitialMintAmount returns the initial GNS allocation minted before emissions.
 26//
 27// Returns:
 28//   - initialAmount: number of GNS base units in the initial mint
 29func GetInitialMintAmount() int64 {
 30	return INITIAL_MINT_AMOUNT
 31}
 32
 33// IsEmissionInitialized reports whether the emission state has non-zero creation
 34// height and start timestamp.
 35//
 36// Returns:
 37//   - initialized: true when both initialization fields are set; false otherwise
 38func IsEmissionInitialized() bool {
 39	return getEmissionState().isInitialized()
 40}
 41
 42// IsEmissionActive reports whether emission is initialized and the current Unix
 43// time lies within the inclusive emission schedule.
 44//
 45// Returns:
 46//   - active: true during the configured schedule, including its endpoints; false otherwise
 47func IsEmissionActive() bool {
 48	return getEmissionState().isActive(time.Now().Unix())
 49}
 50
 51// IsEmissionEnded reports whether the current Unix time is after the emission end timestamp.
 52//
 53// Returns:
 54//   - ended: true after the configured schedule's end; false at or before that timestamp
 55func IsEmissionEnded() bool {
 56	return getEmissionState().isEnded(time.Now().Unix())
 57}
 58
 59// GetHalvingYear returns the halving year containing timestamp.
 60//
 61// Parameters:
 62//   - timestamp: Unix timestamp to classify against the inclusive 12-year emission schedule
 63//
 64// Returns:
 65//   - year: halving year in [1, 12], or 0 when timestamp is before the start or after the end
 66func GetHalvingYear(timestamp int64) int64 {
 67	return getEmissionState().getCurrentYear(timestamp)
 68}
 69
 70// GetCurrentYear returns the halving year containing the current Unix time.
 71//
 72// Returns:
 73//   - year: current halving year in [1, 12], or 0 when the current time is outside the schedule
 74func GetCurrentYear() int64 {
 75	return getEmissionState().getCurrentYear(time.Now().Unix())
 76}
 77
 78// GetEmissionAmountPerSecondInRange returns paired emission-rate change points
 79// whose timestamps fall within the requested range.
 80//
 81// Parameters:
 82//   - fromTime: inclusive Unix timestamp lower bound
 83//   - toTime: inclusive Unix timestamp upper bound; a lower value yields nil slices
 84//
 85// Returns:
 86//   - timestamps: schedule timestamps in the range where the rate changes, including the post-end zero-rate point when applicable
 87//   - amounts: GNS base units emitted per second at each corresponding timestamp; same length and order as timestamps
 88func GetEmissionAmountPerSecondInRange(fromTime, toTime int64) ([]int64, []int64) {
 89	if fromTime > toTime {
 90		return nil, nil
 91	}
 92
 93	halvingData := getEmissionState().getHalvingData()
 94	halvingTimes := make([]int64, 0, HALVING_END_YEAR+1)
 95	halvingEmissions := make([]int64, 0, HALVING_END_YEAR+1)
 96
 97	for year := HALVING_START_YEAR; year <= HALVING_END_YEAR; year++ {
 98		startTimestamp := halvingData.getStartTimestamp(year)
 99		if startTimestamp < fromTime {
100			continue
101		}
102
103		if toTime < startTimestamp {
104			break
105		}
106
107		halvingTimes = append(halvingTimes, startTimestamp)
108		halvingEmissions = append(halvingEmissions, halvingData.getAmountPerSecond(year))
109	}
110
111	emissionEndTimestamp := halvingData.getEndTimestamp(HALVING_END_YEAR)
112	if fromTime <= emissionEndTimestamp && emissionEndTimestamp < toTime {
113		halvingTimes = append(halvingTimes, gnsmath.SafeAddInt64(emissionEndTimestamp, 1))
114		halvingEmissions = append(halvingEmissions, 0)
115	}
116
117	return halvingTimes, halvingEmissions
118}
119
120// GetEmissionAmountPerSecondByTimestamp returns the configured GNS emission
121// rate for the halving year containing timestamp.
122//
123// Parameters:
124//   - timestamp: Unix timestamp whose schedule rate is queried
125//
126// Returns:
127//   - amount: GNS base units emitted per second for timestamp's halving year, or 0 outside the schedule
128func GetEmissionAmountPerSecondByTimestamp(timestamp int64) int64 {
129	state := getEmissionState()
130	year := state.getCurrentYear(timestamp)
131	return state.getHalvingYearAmountPerSecond(year)
132}
133
134// GetEmissionLeftAmountByTimestamp returns the stored unminted allocation for
135// the halving year containing timestamp.
136//
137// Parameters:
138//   - timestamp: Unix timestamp used to select a halving year
139//
140// Returns:
141//   - amount: remaining GNS base units recorded for that halving year, or 0 outside the schedule
142func GetEmissionLeftAmountByTimestamp(timestamp int64) int64 {
143	state := getEmissionState()
144	year := state.getCurrentYear(timestamp)
145	return state.getHalvingYearLeftAmount(year)
146}
147
148// GetEmissionAccumulatedAmountByTimestamp returns the stored minted allocation
149// for the halving year containing timestamp.
150//
151// Parameters:
152//   - timestamp: Unix timestamp used to select a halving year
153//
154// Returns:
155//   - amount: minted GNS base units recorded for that halving year, or 0 outside the schedule
156func GetEmissionAccumulatedAmountByTimestamp(timestamp int64) int64 {
157	state := getEmissionState()
158	year := state.getCurrentYear(timestamp)
159	return state.getHalvingYearMintedAmount(year)
160}
161
162// GetHalvingYearStartTimestamp returns the inclusive start Unix timestamp for
163// a configured halving year.
164//
165// Parameters:
166//   - year: halving year number in [1, 12]
167//
168// Returns:
169//   - timestamp: inclusive start timestamp for year, or 0 when year is invalid
170func GetHalvingYearStartTimestamp(year int64) int64 {
171	halvingData := getEmissionState().getHalvingData()
172	return halvingData.getStartTimestamp(year)
173}
174
175// GetHalvingYearEndTimestamp returns the inclusive end Unix timestamp for a
176// configured halving year.
177//
178// Parameters:
179//   - year: halving year number in [1, 12]
180//
181// Returns:
182//   - timestamp: inclusive end timestamp for year, or 0 when year is invalid
183func GetHalvingYearEndTimestamp(year int64) int64 {
184	halvingData := getEmissionState().getHalvingData()
185	return halvingData.getEndTimestamp(year)
186}
187
188// GetHalvingYearMaxAmount returns the maximum GNS allocation for a halving year.
189//
190// Parameters:
191//   - year: halving year number in [1, 12]
192//
193// Returns:
194//   - amount: maximum GNS base units allocated to year, or 0 when year is invalid
195func GetHalvingYearMaxAmount(year int64) int64 {
196	halvingData := getEmissionState().getHalvingData()
197	return halvingData.getMaxAmount(year)
198}
199
200// GetHalvingYearLeftAmount returns the remaining GNS allocation recorded for a
201// halving year.
202//
203// Parameters:
204//   - year: halving year number in [1, 12]
205//
206// Returns:
207//   - amount: unminted GNS base units for year, or 0 when year is invalid
208func GetHalvingYearLeftAmount(year int64) int64 {
209	halvingData := getEmissionState().getHalvingData()
210	return halvingData.getLeftAmount(year)
211}
212
213// GetHalvingYearMintedAmount returns the minted GNS allocation recorded for a
214// halving year.
215//
216// Parameters:
217//   - year: halving year number in [1, 12]
218//
219// Returns:
220//   - amount: minted GNS base units for year, or 0 when year is invalid
221func GetHalvingYearMintedAmount(year int64) int64 {
222	halvingData := getEmissionState().getHalvingData()
223	return halvingData.getMintedAmount(year)
224}
225
226// GetAmountPerSecondPerHalvingYear returns the configured GNS emission rate for
227// a halving year.
228//
229// Parameters:
230//   - year: halving year number in [1, 12]
231//
232// Returns:
233//   - amountPerSecond: GNS base units emitted per second in year, or 0 when year is invalid
234func GetAmountPerSecondPerHalvingYear(year int64) int64 {
235	halvingData := getEmissionState().getHalvingData()
236	return halvingData.getAmountPerSecond(year)
237}
238
239// GetHalvingAmountsPerYear returns the total GNS allocation configured for a
240// halving year.
241//
242// Parameters:
243//   - year: halving year number in [1, 12]
244//
245// Returns:
246//   - amount: total GNS base units allocated to year, or 0 when year is invalid
247func GetHalvingAmountsPerYear(year int64) int64 {
248	if validYear(year) != nil {
249		return 0
250	}
251	return halvingAmountsPerYear[year-1]
252}
253
254// GetEmissionCreatedHeight returns the blockchain height recorded when the
255// emission schedule was created.
256//
257// Returns:
258//   - height: schedule creation height, or the uninitialized state's stored value
259func GetEmissionCreatedHeight() int64 {
260	return getEmissionState().getCreatedHeight()
261}
262
263// GetEmissionStartTimestamp returns the inclusive Unix timestamp at which the
264// configured emission schedule begins.
265//
266// Returns:
267//   - timestamp: schedule start timestamp
268func GetEmissionStartTimestamp() int64 {
269	return getEmissionState().getStartTimestamp()
270}
271
272// GetEmissionEndTimestamp returns the inclusive Unix timestamp at which the
273// configured emission schedule ends.
274//
275// Returns:
276//   - timestamp: schedule end timestamp
277func GetEmissionEndTimestamp() int64 {
278	return getEmissionState().getEndTimestamp()
279}
280
281// GetHalvingYearInfo returns the configured halving interval containing timestamp.
282//
283// Parameters:
284//   - timestamp: Unix timestamp to classify against the inclusive emission schedule
285//
286// Returns:
287//   - year: halving year in [1, 12], or 0 outside the schedule
288//   - startTimestamp: inclusive start timestamp of year, or 0 when timestamp is outside the schedule
289//   - endTimestamp: inclusive end timestamp of year, or 0 when timestamp is outside the schedule
290func GetHalvingYearInfo(timestamp int64) (int64, int64, int64) {
291	state := getEmissionState()
292	year := state.getCurrentYear(timestamp)
293
294	// If outside emission period, return 0 values
295	if year == 0 {
296		return 0, 0, 0
297	}
298
299	// Use cached timestamps from HalvingData
300	halvingData := state.getHalvingData()
301	return year, halvingData.getStartTimestamp(year), halvingData.getEndTimestamp(year)
302}
303
304// GetHalvingInfo returns an independent copy of the configured 12-year halving schedule.
305//
306// Returns:
307//   - halvingData: deep copy of schedule timestamps, allocations, minted amounts, remaining amounts, and rates
308func GetHalvingInfo() *HalvingData {
309	return getEmissionState().getHalvingData().Clone()
310}
311
312// CalculateMintGnsAmount calculates the GNS base units allocated over an
313// inclusive timestamp range without mutating the live emission state.
314//
315// Parameters:
316//   - fromTimestamp: inclusive Unix timestamp at which allocation begins
317//   - toTimestamp: inclusive Unix timestamp at which allocation ends
318//
319// Returns:
320//   - amount: GNS base units allocated in the overlapping schedule interval, or 0 for an invalid or non-overlapping range
321func CalculateMintGnsAmount(fromTimestamp, toTimestamp int64) int64 {
322	state := getEmissionState().Clone()
323
324	amountToMint, err := calculateAmountToMint(state, fromTimestamp, toTimestamp)
325	if err != nil {
326		return 0
327	}
328
329	return amountToMint
330}