getter.gno

  1package staker
  2
  3import (
  4	"time"
  5
  6	gnsmath "gno.land/p/gnoswap/gnsmath/v1"
  7	"gno.land/p/gnoswap/uint256/v1"
  8	rotree "gno.land/p/nt/bptree/rotree/v0"
  9	ufmt "gno.land/p/nt/ufmt/v0"
 10
 11	"gno.land/r/gnoswap/emission"
 12	"gno.land/r/gnoswap/gov/staker"
 13	"gno.land/r/gnoswap/gov/xgns"
 14)
 15
 16// GetTotalxGnsSupply returns the total amount of xGNS supply, including
 17// xGNS held by the launchpad.
 18//
 19// Returns:
 20//   - int64: total xGNS supply, including the launchpad balance.
 21func (gs *govStakerV1) GetTotalxGnsSupply() int64 {
 22	return xgns.TotalSupply()
 23}
 24
 25// GetTotalDelegated returns the total amount of xGNS delegated.
 26//
 27// Returns:
 28//   - int64: total xGNS amount currently delegated.
 29func (gs *govStakerV1) GetTotalDelegated() int64 {
 30	return gs.store.GetTotalDelegatedAmount()
 31}
 32
 33// GetTotalLockedAmount returns the total amount of locked GNS.
 34//
 35// Returns:
 36//   - int64: total GNS amount currently locked.
 37func (gs *govStakerV1) GetTotalLockedAmount() int64 {
 38	return gs.store.GetTotalLockedAmount()
 39}
 40
 41// GetUnDelegationLockupPeriod returns the undelegation lockup period in seconds.
 42//
 43// Returns:
 44//   - int64: number of seconds an undelegation remains locked.
 45func (gs *govStakerV1) GetUnDelegationLockupPeriod() int64 {
 46	return gs.store.GetUnDelegationLockupPeriod()
 47}
 48
 49// GetDelegations returns a read-only view of every delegation, keyed by the
 50// decimal string form of the delegation ID.
 51//
 52// Returns:
 53//   - *rotree.ReadOnlyTree: read-only delegation tree keyed by decimal ID.
 54func (gs *govStakerV1) GetDelegations() *rotree.ReadOnlyTree {
 55	return rotree.Wrap(gs.store.GetAllDelegations(), cloneDelegationEntry)
 56}
 57
 58// ExistsDelegation checks if a delegation exists.
 59//
 60// Parameters:
 61//   - delegationID: delegation identifier to look up.
 62//
 63// Returns:
 64//   - bool: true when delegationID is stored, otherwise false.
 65func (gs *govStakerV1) ExistsDelegation(delegationID int64) bool {
 66	return gs.store.HasDelegation(delegationID)
 67}
 68
 69// GetDelegatorDelegations returns a read-only view of a delegator's delegations,
 70// keyed by delegatee address with that pair's delegation IDs as the value.
 71// nil is returned when the delegator has no delegations.
 72//
 73// Parameters:
 74//   - delegator: address whose outgoing delegations are requested.
 75//
 76// Returns:
 77//   - *rotree.ReadOnlyTree: read-only tree keyed by delegatee address, or nil
 78//     when delegator has no delegation entries.
 79func (gs *govStakerV1) GetDelegatorDelegations(delegator address) *rotree.ReadOnlyTree {
 80	delegationManager := gs.store.GetDelegationManager()
 81	delegatorTree, exists := delegationManager.GetDelegatorDelegations(delegator.String())
 82	if !exists {
 83		return nil
 84	}
 85	return rotree.Wrap(delegatorTree, cloneDelegationIDsEntry)
 86}
 87
 88// GetUserDelegationIDs returns the delegation IDs for a specific delegator and
 89// delegatee.
 90//
 91// Parameters:
 92//   - delegator: address that created the delegations.
 93//   - delegatee: address receiving the delegations.
 94//
 95// Returns:
 96//   - []int64: delegation IDs for the delegator/delegatee pair, or an empty
 97//     slice when no pair is stored.
 98func (gs *govStakerV1) GetUserDelegationIDs(delegator address, delegatee address) []int64 {
 99	delegationManager := gs.store.GetDelegationManager()
100
101	delegationIDs, exists := delegationManager.GetDelegationIDs(delegator.String(), delegatee.String())
102	if !exists {
103		return []int64{}
104	}
105
106	return delegationIDs
107}
108
109// HasDelegationSnapshotsKey reports whether delegation history has been stored.
110//
111// Returns:
112//   - bool: true when the total delegation history storage key exists.
113func (gs *govStakerV1) HasDelegationSnapshotsKey() bool {
114	return gs.store.HasTotalDelegationHistoryStoreKey()
115}
116
117// GetTotalDelegationAmountAtSnapshot returns the total delegation amount at a
118// Unix timestamp. It uses ReverseIterate to find the most recent history entry
119// at or before that timestamp; this is a timestamp lookup, not a block snapshot.
120//
121// Parameters:
122//   - snapshotTime: Unix timestamp to retrieve the history value for
123//
124// Returns:
125//   - int64: total delegation amount at the specified time
126//   - bool: true when a history entry exists at or before the timestamp
127func (gs *govStakerV1) GetTotalDelegationAmountAtSnapshot(snapshotTime int64) (int64, bool) {
128	history := gs.store.GetTotalDelegationHistory()
129	if history.Size() == 0 {
130		return 0, false
131	}
132
133	var (
134		totalAmount int64
135		exists      bool
136	)
137
138	// ReverseIterate from 0 to snapshotTime to find the most recent entry at or before snapshotTime
139	history.ReverseIterate(0, snapshotTime, func(key int64, value any) bool {
140		amountInt, ok := value.(int64)
141		if !ok {
142			panic(ufmt.Sprintf("invalid amount type: %T", value))
143		}
144
145		totalAmount = amountInt
146		exists = true
147
148		return true // stop after first (most recent) entry
149	})
150
151	return totalAmount, exists
152}
153
154// GetUserDelegationAmountAtSnapshot returns one user's delegation amount at a
155// Unix timestamp. The history is keyed by address and timestamp, and the
156// lookup returns the most recent entry at or before the requested time.
157//
158// Parameters:
159//   - userAddr: address of the user
160//   - snapshotTime: Unix timestamp to retrieve
161//
162// Returns:
163//   - int64: user delegation amount at the specified time
164//   - bool: true when a history entry exists at or before the timestamp
165func (gs *govStakerV1) GetUserDelegationAmountAtSnapshot(userAddr address, snapshotTime int64) (int64, bool) {
166	history := gs.store.GetUserDelegationHistory()
167
168	addrStr := userAddr.String()
169	lo, _ := userHistoryKeyRange(addrStr)
170	// Inclusive upper bound: largest key for this address at or before snapshotTime.
171	hi := makeUserHistoryKey(addrStr, snapshotTime)
172
173	var (
174		userAmount int64
175		exists     bool
176	)
177
178	// ReverseIterate from hi down to lo to find the most recent entry at or before snapshotTime
179	history.ReverseIterate(lo, hi, func(_ string, value any) bool {
180		amountInt, ok := value.(int64)
181		if !ok {
182			panic(ufmt.Sprintf("invalid amount type: %T", value))
183		}
184
185		userAmount = amountInt
186		exists = true
187
188		return true // stop after first (most recent) entry
189	})
190
191	return userAmount, exists
192}
193
194// GetClaimableRewardByAddress returns the claimable rewards for an address.
195//
196// Parameters:
197//   - addr: staker address whose emission and protocol fee rewards are requested.
198//
199// Returns:
200//   - int64: claimable emission reward amount.
201//   - map[string]int64: claimable protocol fee amounts keyed by token path.
202//   - error: nil on success; an error when emission or protocol fee reward
203//     resolution fails.
204func (gs *govStakerV1) GetClaimableRewardByAddress(addr address) (int64, map[string]int64, error) {
205	return gs.GetClaimableRewardByRewardID(addr.String())
206}
207
208// GetClaimableRewardByLaunchpad returns the claimable rewards for a launchpad
209// project address.
210//
211// Parameters:
212//   - addr: launchpad project address used to derive its reward ID.
213//
214// Returns:
215//   - int64: claimable emission reward amount for the launchpad project.
216//   - map[string]int64: claimable protocol fee amounts keyed by token path.
217//   - error: nil on success; an error when emission or protocol fee reward
218//     resolution fails.
219func (gs *govStakerV1) GetClaimableRewardByLaunchpad(addr address) (int64, map[string]int64, error) {
220	return gs.GetClaimableRewardByRewardID(gs.makeLaunchpadRewardID(addr.String()))
221}
222
223// GetClaimableRewardByRewardID returns the claimable rewards for a reward ID.
224//
225// Parameters:
226//   - rewardID: emission/protocol-fee reward state identifier to inspect.
227//
228// Returns:
229//   - int64: claimable emission reward amount.
230//   - map[string]int64: claimable protocol fee amounts keyed by token path.
231//   - error: nil on success; an error when emission or protocol fee reward
232//     resolution fails.
233func (gs *govStakerV1) GetClaimableRewardByRewardID(rewardID string) (int64, map[string]int64, error) {
234	emissionDistributedAmount := emission.GetAccuDistributedToGovStaker()
235	emissionRewardManager := gs.store.GetEmissionRewardManager()
236	emissionResolver := NewEmissionRewardManagerResolver(emissionRewardManager)
237	emissionReward, err := emissionResolver.GetClaimableRewardAmount(emissionDistributedAmount, rewardID, time.Now().Unix())
238	if err != nil {
239		return 0, make(map[string]int64), err
240	}
241
242	protocolFeeRewards, err := gs.getClaimableProtocolFeeRewards(rewardID)
243	if err != nil {
244		return 0, make(map[string]int64), err
245	}
246
247	return emissionReward, protocolFeeRewards, nil
248}
249
250// GetLaunchpadProjectDeposit returns the deposit amount for a launchpad project.
251//
252// Parameters:
253//   - projectAddr: launchpad project address used to derive its reward ID.
254//
255// Returns:
256//   - int64: stored launchpad project deposit amount.
257//   - bool: true when a deposit exists for projectAddr, otherwise false.
258func (gs *govStakerV1) GetLaunchpadProjectDeposit(projectAddr string) (int64, bool) {
259	launchpadDeposits := gs.store.GetLaunchpadProjectDeposits()
260	return launchpadDeposits.GetDeposit(gs.makeLaunchpadRewardID(projectAddr))
261}
262
263// GetDelegationWithdrawCount returns the total number of delegation withdraws
264// for a specific delegation.
265//
266// Parameters:
267//   - delegationID: delegation identifier whose withdrawals are counted.
268//
269// Returns:
270//   - int: number of withdrawals recorded for delegationID, or zero when the
271//     delegation does not exist.
272func (gs *govStakerV1) GetDelegationWithdrawCount(delegationID int64) int {
273	delegation, exists := gs.store.GetDelegation(delegationID)
274	if !exists {
275		return 0
276	}
277	return len(delegation.Withdraws())
278}
279
280// GetDelegationWithdraws returns a paginated list of delegation withdraws for a
281// specific delegation.
282//
283// Parameters:
284//   - delegationID: delegation identifier whose withdrawals are requested.
285//   - offset: zero-based index of the first withdrawal to return.
286//   - count: maximum number of withdrawals to return.
287//
288// Returns:
289//   - []staker.DelegationWithdraw: withdrawals in the requested range, or an
290//     empty slice when the delegation or page is absent.
291//   - error: nil; this accessor currently has no error path.
292func (gs *govStakerV1) GetDelegationWithdraws(delegationID int64, offset, count int) ([]staker.DelegationWithdraw, error) {
293	delegation, exists := gs.store.GetDelegation(delegationID)
294	if !exists {
295		return []staker.DelegationWithdraw{}, nil
296	}
297
298	withdraws := delegation.Withdraws()
299	size := len(withdraws)
300	if offset >= size {
301		return []staker.DelegationWithdraw{}, nil
302	}
303
304	end := offset + count
305	if end > size {
306		end = size
307	}
308
309	return withdraws[offset:end], nil
310}
311
312// GetCollectableWithdrawAmount returns the collectable withdraw amount for a
313// specific delegation as of the current Unix time.
314//
315// Parameters:
316//   - delegationID: delegation identifier whose matured withdrawals are summed.
317//
318// Returns:
319//   - int64: total amount currently collectable, or zero when the delegation
320//     does not exist.
321func (gs *govStakerV1) GetCollectableWithdrawAmount(delegationID int64) int64 {
322	delegation, exists := gs.store.GetDelegation(delegationID)
323	if !exists {
324		return 0
325	}
326
327	totalAmount := int64(0)
328	currentTime := time.Now().Unix()
329	for _, withdraw := range delegation.Withdraws() {
330		resolver := NewDelegationWithdrawResolver(&withdraw)
331		totalAmount = gnsmath.SafeAddInt64(totalAmount, resolver.CollectableAmount(currentTime))
332	}
333
334	return totalAmount
335}
336
337// GetProtocolFeeAccumulatedX128PerStake returns the accumulated protocol fee per
338// stake (Q128) for a token path.
339//
340// Parameters:
341//   - tokenPath: token identifier/path whose accumulator is requested.
342//
343// Returns:
344//   - *uint256.Uint: accumulated protocol fee per stake scaled by 2^128, or a
345//     zero value when no accumulator exists for tokenPath.
346func (gs *govStakerV1) GetProtocolFeeAccumulatedX128PerStake(tokenPath string) *uint256.Uint {
347	protocolFeeRewardManager := gs.store.GetProtocolFeeRewardManager()
348	accumulatedFee := protocolFeeRewardManager.GetAccumulatedProtocolFeeX128PerStake(tokenPath)
349	if accumulatedFee == nil {
350		return uint256.NewUint(0)
351	}
352
353	return accumulatedFee
354}
355
356// GetProtocolFeeAmount returns the protocol fee amount accumulated for a token
357// path.
358//
359// Parameters:
360//   - tokenPath: token identifier/path whose folded fee amount is requested.
361//
362// Returns:
363//   - int64: accumulated protocol fee amount for tokenPath.
364func (gs *govStakerV1) GetProtocolFeeAmount(tokenPath string) int64 {
365	protocolFeeRewardManager := gs.store.GetProtocolFeeRewardManager()
366	return protocolFeeRewardManager.GetProtocolFeeAmount(tokenPath)
367}
368
369// GetProtocolFeeAccumulatedTimestamp returns the accumulated timestamp for
370// protocol fee rewards.
371//
372// Returns:
373//   - int64: Unix timestamp represented by protocol fee accumulation state.
374func (gs *govStakerV1) GetProtocolFeeAccumulatedTimestamp() int64 {
375	protocolFeeRewardManager := gs.store.GetProtocolFeeRewardManager()
376	return protocolFeeRewardManager.GetAccumulatedTimestamp()
377}
378
379// GetEmissionAccumulatedX128PerStake returns the accumulated emission per stake
380// (Q128).
381//
382// Returns:
383//   - *uint256.Uint: accumulated emission reward per stake scaled by 2^128.
384func (gs *govStakerV1) GetEmissionAccumulatedX128PerStake() *uint256.Uint {
385	emissionRewardManager := gs.store.GetEmissionRewardManager()
386	return emissionRewardManager.GetAccumulatedRewardX128PerStake()
387}
388
389// GetEmissionDistributedAmount returns the total distributed emission amount.
390//
391// Returns:
392//   - int64: total emission amount recorded as distributed to governance stakers.
393func (gs *govStakerV1) GetEmissionDistributedAmount() int64 {
394	emissionRewardManager := gs.store.GetEmissionRewardManager()
395	return emissionRewardManager.GetDistributedAmount()
396}
397
398// GetEmissionAccumulatedTimestamp returns the accumulated timestamp for emission
399// rewards.
400//
401// Returns:
402//   - int64: Unix timestamp represented by emission accumulation state.
403func (gs *govStakerV1) GetEmissionAccumulatedTimestamp() int64 {
404	emissionRewardManager := gs.store.GetEmissionRewardManager()
405	return emissionRewardManager.GetAccumulatedTimestamp()
406}