emission_reward_manager.gno

  1package staker
  2
  3import (
  4	bptree "gno.land/p/nt/bptree/v0"
  5	ufmt "gno.land/p/nt/ufmt/v0"
  6
  7	u256 "gno.land/p/gnoswap/uint256/v1"
  8)
  9
 10const errFailedToCastRewardState = "failed to cast rewardStates's element to *EmissionRewardState: %T"
 11
 12// EmissionRewardManager manages the distribution of emission rewards to stakers.
 13type EmissionRewardManager struct {
 14	// rewardStates maps address to EmissionRewardState for tracking individual staker rewards
 15	rewardStates *bptree.BPTree // address -> EmissionRewardState
 16
 17	// accumulatedRewardX128PerStake tracks the cumulative reward per unit of stake with 128-bit precision
 18	accumulatedRewardX128PerStake *u256.Uint
 19	// distributedAmount tracks the total amount of rewards distributed
 20	distributedAmount int64
 21	// accumulatedTimestamp tracks the last timestamp when rewards were accumulated
 22	accumulatedTimestamp int64
 23	// totalStakedAmount tracks the total amount of tokens staked in the system
 24	totalStakedAmount int64
 25}
 26
 27// NewEmissionRewardManager creates and initializes an EmissionRewardManager with empty reward states and zero accounting totals.
 28// Returns:
 29//   - *EmissionRewardManager: initialized manager with empty reward states, zero totals, and a zero Q128 accumulator.
 30func NewEmissionRewardManager() *EmissionRewardManager {
 31	return &EmissionRewardManager{
 32		accumulatedRewardX128PerStake: u256.NewUint(0),
 33		accumulatedTimestamp:          0,
 34		totalStakedAmount:             0,
 35		distributedAmount:             0,
 36		rewardStates:                  bptree.NewBPTreeN(16),
 37	}
 38}
 39
 40// GetAccumulatedRewardX128PerStake returns the accumulated reward per stake with 128-bit precision.
 41// Returns:
 42//   - *u256.Uint: accumulated emission reward per unit of stake in Q128 fixed-point form.
 43func (e *EmissionRewardManager) GetAccumulatedRewardX128PerStake() *u256.Uint {
 44	return e.accumulatedRewardX128PerStake
 45}
 46
 47// GetAccumulatedTimestamp returns the last timestamp when rewards were accumulated.
 48// Returns:
 49//   - int64: Unix timestamp of the latest emission-reward accumulation.
 50func (e *EmissionRewardManager) GetAccumulatedTimestamp() int64 {
 51	return e.accumulatedTimestamp
 52}
 53
 54// GetTotalStakedAmount returns the total amount of tokens staked in the system.
 55// Returns:
 56//   - int64: total staked token amount tracked by the manager.
 57func (e *EmissionRewardManager) GetTotalStakedAmount() int64 {
 58	return e.totalStakedAmount
 59}
 60
 61// GetDistributedAmount returns the total amount of rewards distributed.
 62// Returns:
 63//   - int64: total emission reward amount marked as distributed.
 64func (e *EmissionRewardManager) GetDistributedAmount() int64 {
 65	return e.distributedAmount
 66}
 67
 68// GetRewardState retrieves the reward state for addr.
 69//
 70// Parameters:
 71//   - addr: Address key identifying the staker's emission reward state.
 72//
 73// Returns:
 74//   - *EmissionRewardState: stored state, or nil when addr has no state.
 75//   - bool: true when a reward state exists for addr; false when absent.
 76//   - error: nil on success or absence; non-nil when the stored value has the wrong type.
 77func (e *EmissionRewardManager) GetRewardState(addr string) (*EmissionRewardState, bool, error) {
 78	ri := e.rewardStates.Get(addr)
 79	if ri == nil {
 80		return nil, false, nil
 81	}
 82	rs, castOk := ri.(*EmissionRewardState)
 83	if !castOk {
 84		return nil, false, ufmt.Errorf(errFailedToCastRewardState, ri)
 85	}
 86	return rs, true, nil
 87}
 88
 89/* Setters */
 90
 91// SetRewardStates replaces the tree containing per-address emission reward states.
 92//
 93// Parameters:
 94//   - rewardStates: BPTree mapping staker addresses to emission reward states.
 95func (e *EmissionRewardManager) SetRewardStates(rewardStates *bptree.BPTree) {
 96	e.rewardStates = rewardStates
 97}
 98
 99// SetAccumulatedRewardX128PerStake stores the accumulated emission reward per stake.
100//
101// Parameters:
102//   - accumulatedRewardX128PerStake: Q128 fixed-point reward-per-stake accumulator to copy into the manager.
103func (e *EmissionRewardManager) SetAccumulatedRewardX128PerStake(accumulatedRewardX128PerStake *u256.Uint) {
104	e.accumulatedRewardX128PerStake = u256.Zero().Set(accumulatedRewardX128PerStake)
105}
106
107// SetDistributedAmount stores the total emission amount marked as distributed.
108//
109// Parameters:
110//   - distributedAmount: Total emission reward amount distributed so far.
111func (e *EmissionRewardManager) SetDistributedAmount(distributedAmount int64) {
112	e.distributedAmount = distributedAmount
113}
114
115// SetAccumulatedTimestamp stores the latest emission-reward accumulation timestamp.
116//
117// Parameters:
118//   - accumulatedTimestamp: Unix timestamp associated with the current accumulator.
119func (e *EmissionRewardManager) SetAccumulatedTimestamp(accumulatedTimestamp int64) {
120	e.accumulatedTimestamp = accumulatedTimestamp
121}
122
123// SetTotalStakedAmount stores the total amount currently staked.
124//
125// Parameters:
126//   - totalStakedAmount: Aggregate token amount participating in emission rewards.
127func (e *EmissionRewardManager) SetTotalStakedAmount(totalStakedAmount int64) {
128	e.totalStakedAmount = totalStakedAmount
129}
130
131// SetRewardState sets the reward state for a specific address
132// SetRewardState stores one staker's emission reward state under address.
133//
134// Parameters:
135//   - address: Address key for the staker's reward state.
136//   - rewardState: Emission reward state to store for address.
137func (e *EmissionRewardManager) SetRewardState(address string, rewardState *EmissionRewardState) {
138	e.rewardStates.Set(address, rewardState)
139}