1const (
 2	// Basic configuration
 3	StoreKeyUnDelegationLockupPeriod = "unDelegationLockupPeriod"
 4	StoreKeyTotalDelegatedAmount     = "totalDelegatedAmount"
 5	StoreKeyTotalLockedAmount        = "totalLockedAmount"
 6
 7	// Counters
 8	StoreKeyDelegationNextID = "delegationNextID"
 9
10	// Complex data structures
11	StoreKeyDelegations            = "delegations"            // BPTree of delegations
12	StoreKeyTotalDelegationHistory = "totalDelegationHistory" // UintTree: timestamp -> int64 (cumulative total)
13	StoreKeyUserDelegationHistory  = "userDelegationHistory"  // BPTree: address -> *UintTree[timestamp -> int64]
14
15	// Manager states
16	StoreKeyEmissionRewardManager    = "emissionRewardManager"
17	StoreKeyProtocolFeeRewardManager = "protocolFeeRewardManager"
18	StoreKeyDelegationManager        = "delegationManager"
19	StoreKeyLaunchpadProjectDeposits = "launchpadProjectDeposits"
20)

1const ErrSpoofedRealm = "rlm does not match the current crossing frame"

1const (
2	DelegateType   DelegationType = "DELEGATE"
3	UnDelegateType DelegationType = "UNDELEGATE"
4)

1func CleanStakerDelegationSnapshotByAdmin(cur realm, threshold int64, target address)

1func CollectEmissionReward(cur realm)

1func CollectEmissionRewardFromLaunchPad(cur realm, to address)

1func CollectProtocolFeeReward(cur realm, tokenPath string)

1func CollectProtocolFeeRewardFromLaunchPad(cur realm, to address, tokenPath string)

1func CollectReward(cur realm)

1func CollectRewardFromLaunchPad(cur realm, to address)

1func CollectUndelegatedGns(cur realm) int64

1func Delegate(cur realm, to address, amount int64, referrer string) int64

1func ExistsDelegation(delegationID int64) bool

1func GetClaimableRewardByAddress(addr address) (int64, map[string]int64, error)

1func GetClaimableRewardByLaunchpad(addr address) (int64, map[string]int64, error)

1func GetClaimableRewardByRewardID(rewardID string) (int64, map[string]int64, error)

1func GetCollectableWithdrawAmount(delegationID int64) int64

1func GetDelegationWithdrawCount(delegationID int64) int

1func GetDelegations() *rotree.ReadOnlyTree

1func GetDelegatorDelegations(delegator address) *rotree.ReadOnlyTree

1func GetEmissionAccumulatedTimestamp() int64

1func GetEmissionAccumulatedX128PerStake() *u256.Uint

1func GetEmissionDistributedAmount() int64

1func GetImplementationPackagePath() string

1func GetLaunchpadProjectDeposit(projectAddr string) (int64, bool)

1func GetProtocolFeeAccumulatedTimestamp() int64

1func GetProtocolFeeAccumulatedX128PerStake(tokenPath string) *u256.Uint

1func GetProtocolFeeAmount(tokenPath string) int64

1func GetTotalDelegated() int64

1func GetTotalDelegationAmountAtSnapshot(snapshotTime int64) (int64, bool)

1func GetTotalLockedAmount() int64

1func GetTotalxGnsSupply() int64

1func GetUnDelegationLockupPeriod() int64

1func GetUserDelegationAmountAtSnapshot(userAddr address, snapshotTime int64) (int64, bool)

1func GetUserDelegationIDs(delegator address, delegatee address) []int64

1func HasDelegationSnapshotsKey() bool

1func NewDelegationTree() *bptree.BPTree

1func NewUserDelegationTree() *bptree.BPTree

1func Redelegate(cur realm, delegatee, newDelegatee address, amount int64) int64

1func RegisterInitializer(cur realm, initializer func(_ int, rlm realm, govStakerStore IGovStakerStore) IGovStaker)

1func Render(path string) string

1func SetAmountByProjectWallet(cur realm, addr address, amount int64, add bool)

1func SetUnDelegationLockupPeriodByAdmin(cur realm, period int64)

1func Undelegate(cur realm, from address, amount int64) int64

1func UpgradeImpl(cur realm, packagePath string)

1func NewCounter() *Counter

1func NewDelegation(
2	id int64,
3	delegateFrom, delegateTo address,
4	delegateAmount, createdHeight, createdAt int64,
5) *Delegation

1func NewDelegationManager() *DelegationManager

1func GetDelegationWithdraws(delegationID int64, offset, count int) ([]DelegationWithdraw, error)

1func NewDelegationWithdraw(
2	delegationID,
3	unDelegateAmount,
4	createdHeight,
5	createdAt,
6	unDelegationLockupPeriod int64,
7) DelegationWithdraw

1func NewDelegationWithdrawWithoutLockup(
2	delegationID,
3	unDelegateAmount,
4	createdHeight,
5	createdAt int64,
6) DelegationWithdraw

1func NewEmissionRewardManager() *EmissionRewardManager

1func NewEmissionRewardState(accumulatedRewardX128PerStake *u256.Uint) *EmissionRewardState

1func NewGovStakerStore(kvStore store.KVStore) IGovStakerStore

1func NewLaunchpadProjectDeposits() *LaunchpadProjectDeposits

1func NewProtocolFeeRewardManager() *ProtocolFeeRewardManager

1func NewProtocolFeeRewardState() *ProtocolFeeRewardState

1func NewProtocolFeeTokenAccumulator() *ProtocolFeeTokenAccumulator

1func NewProtocolFeeTokenRewardState(eventCursor int64, segmentStakedAmount int64, segmentStartX128 *u256.Uint) *ProtocolFeeTokenRewardState

1func NewUintTree() *UintTree

1type Counter struct {
2	id int64
3}

 1type Delegation struct {
 2	id               int64
 3	delegateAmount   int64
 4	unDelegateAmount int64
 5	collectedAmount  int64
 6	delegateFrom     address
 7	delegateTo       address
 8	createdHeight    int64
 9	createdAt        int64
10	withdraws        []DelegationWithdraw
11}

1type DelegationManager struct {
2	// userDelegations maps delegator address -> *bptree.BPTree (delegatee address -> list of delegation IDs)
3	// Using BPTree instead of map to handle unbounded growth of delegators efficiently
4	userDelegations *bptree.BPTree
5}

1type DelegationType string

 1type DelegationWithdraw struct {
 2	// delegationID is the unique identifier of the associated delegation
 3	delegationID int64
 4	// unDelegateAmount is the total amount that was undelegated
 5	unDelegateAmount int64
 6	// unDelegatedHeight is the height when the undelegation occurred
 7	unDelegatedHeight int64
 8	// unDelegatedAt is the timestamp when the undelegation occurred
 9	unDelegatedAt int64
10	// collectedAmount is the amount that has already been collected
11	collectedAmount int64
12	// collectableTime is the timestamp when collection becomes available
13	collectableTime int64
14	// collectedAt is the timestamp when collection occurred
15	collectedAt int64
16	// collected indicates whether the withdrawal has been fully collected
17	collected bool
18}

 1type EmissionRewardManager struct {
 2	// rewardStates maps address to EmissionRewardState for tracking individual staker rewards
 3	rewardStates *bptree.BPTree // address -> EmissionRewardState
 4
 5	// accumulatedRewardX128PerStake tracks the cumulative reward per unit of stake with 128-bit precision
 6	accumulatedRewardX128PerStake *u256.Uint
 7	// distributedAmount tracks the total amount of rewards distributed
 8	distributedAmount int64
 9	// accumulatedTimestamp tracks the last timestamp when rewards were accumulated
10	accumulatedTimestamp int64
11	// totalStakedAmount tracks the total amount of tokens staked in the system
12	totalStakedAmount int64
13}

 1type EmissionRewardState struct {
 2	// rewardDebtX128 represents the reward debt with 128-bit precision scaling
 3	// Used to calculate rewards earned since the last update
 4	rewardDebtX128 *u256.Uint
 5	// accumulatedRewardAmount is the total rewards accumulated but not yet claimed
 6	accumulatedRewardAmount int64
 7	// accumulatedTimestamp is the last timestamp when rewards were accumulated
 8	accumulatedTimestamp int64
 9	// claimedRewardAmount is the total amount of rewards that have been claimed
10	claimedRewardAmount int64
11	// claimedTimestamp is the last timestamp when rewards were claimed
12	claimedTimestamp int64
13	// stakedAmount is the current amount of tokens staked by this address
14	stakedAmount int64
15}

1type IGovStaker interface {
2	IGovStakerDelegation
3	IGovStakerReward
4	IGovStakerGetter
5	IGovStakerAdmin
6	Render(path string) string
7}

 1type IGovStakerAdmin interface {
 2	// CleanStakerDelegationSnapshotByAdmin removes delegation-history entries
 3	// older than a validated timestamp cutoff.
 4	//
 5	// Parameters:
 6	//   - _: leading realm-call discriminator; callers pass 0 for the forwarded implementation call
 7	//   - rlm: propagated current realm context validated before administrative state updates
 8	//   - snapshotTime: Unix timestamp cutoff before which eligible history entries are removed
 9	//   - target: address whose user delegation history is cleaned
10	CleanStakerDelegationSnapshotByAdmin(_ int, rlm realm, snapshotTime int64, target address)
11	// SetUnDelegationLockupPeriodByAdmin updates the duration used by future
12	// undelegation withdrawals.
13	//
14	// Parameters:
15	//   - _: leading realm-call discriminator; callers pass 0 for the forwarded implementation call
16	//   - rlm: propagated current realm context validated before the administrative store write
17	//   - period: non-negative undelegation lockup duration in seconds
18	SetUnDelegationLockupPeriodByAdmin(_ int, rlm realm, period int64)
19}

 1type IGovStakerDelegation interface {
 2	// Main delegation operations
 3	// Delegate moves GNS into delegation and assigns the corresponding xGNS voting power.
 4	//
 5	// Parameters:
 6	//   - _: leading realm-call discriminator; callers pass 0 for the forwarded implementation call
 7	//   - rlm: propagated current realm context validated before token transfers and state updates
 8	//   - to: address that receives the delegated voting power
 9	//   - amount: positive GNS amount to delegate
10	//   - referrer: optional referral identifier associated with the delegation
11	//
12	// Returns:
13	//   - int64: amount delegated and represented as xGNS
14	Delegate(_ int, rlm realm, to address, amount int64, referrer string) int64
15	// Undelegate removes voting power from an existing delegatee and starts the
16	// undelegation lockup for the returned GNS.
17	//
18	// Parameters:
19	//   - _: leading realm-call discriminator; callers pass 0 for the forwarded implementation call
20	//   - rlm: propagated current realm context validated before token and state updates
21	//   - from: delegatee address from which the caller removes delegation
22	//   - amount: positive xGNS amount to undelegate
23	//
24	// Returns:
25	//   - int64: amount moved from active delegation into undelegation lockup
26	Undelegate(_ int, rlm realm, from address, amount int64) int64
27	// Redelegate moves voting power from one delegatee to another without a
28	// user-facing undelegation lockup.
29	//
30	// Parameters:
31	//   - _: leading realm-call discriminator; callers pass 0 for the forwarded implementation call
32	//   - rlm: propagated current realm context validated before token and state updates
33	//   - delegatee: current delegatee address whose delegation is reduced
34	//   - newDelegatee: destination address that receives the redelegated amount
35	//   - amount: positive xGNS amount to move between delegatees
36	//
37	// Returns:
38	//   - int64: amount moved from the current delegatee to the new delegatee
39	Redelegate(_ int, rlm realm, delegatee, newDelegatee address, amount int64) int64
40	// CollectUndelegatedGns releases GNS whose undelegation lockup has expired.
41	//
42	// Parameters:
43	//   - _: leading realm-call discriminator; callers pass 0 for the forwarded implementation call
44	//   - rlm: propagated current realm context validated before token and state updates
45	//
46	// Returns:
47	//   - int64: amount of unlocked GNS collected by the caller
48	CollectUndelegatedGns(_ int, rlm realm) int64
49}

  1type IGovStakerGetter interface {
  2	// Store data getters
  3	// GetUnDelegationLockupPeriod returns the configured undelegation cooldown.
  4	//
  5	// Returns:
  6	//   - int64: undelegation lockup duration in seconds
  7	GetUnDelegationLockupPeriod() int64
  8
  9	// Delegation getters
 10	// GetTotalxGnsSupply returns total xGNS supply, including xGNS held by the
 11	// launchpad.
 12	//
 13	// Returns:
 14	//   - int64: total xGNS supply used as the governance quorum base
 15	GetTotalxGnsSupply() int64
 16	// GetTotalDelegated returns the amount currently delegated for governance
 17	// voting power.
 18	//
 19	// Returns:
 20	//   - int64: total active delegated xGNS amount
 21	GetTotalDelegated() int64
 22	// GetTotalLockedAmount returns GNS held by the staker contract for active
 23	// delegations and not-yet-collected undelegations.
 24	//
 25	// Returns:
 26	//   - int64: total locked GNS amount
 27	GetTotalLockedAmount() int64
 28	// GetDelegations returns a read-only tree of all delegations keyed by their
 29	// decimal-string IDs.
 30	//
 31	// Returns:
 32	//   - *rotree.ReadOnlyTree: read-only delegation index whose entries are cloned for callers
 33	GetDelegations() *rotree.ReadOnlyTree
 34	// ExistsDelegation checks whether a delegation record exists.
 35	//
 36	// Parameters:
 37	//   - delegationID: unique delegation identifier to look up
 38	//
 39	// Returns:
 40	//   - bool: true when delegationID has a stored record; false otherwise
 41	ExistsDelegation(delegationID int64) bool
 42	// GetDelegatorDelegations returns a read-only tree for one delegator, keyed
 43	// by delegatee address.
 44	//
 45	// Parameters:
 46	//   - delegator: address whose delegatee mappings are requested
 47	//
 48	// Returns:
 49	//   - *rotree.ReadOnlyTree: delegatee-to-delegation-ID tree, or nil when the delegator has no delegations
 50	GetDelegatorDelegations(delegator address) *rotree.ReadOnlyTree
 51	// GetUserDelegationIDs returns delegation IDs for one delegator-delegatee
 52	// pair.
 53	//
 54	// Parameters:
 55	//   - delegator: address that owns the delegation
 56	//   - delegatee: address receiving the delegation
 57	//
 58	// Returns:
 59	//   - []int64: stored delegation IDs for the pair, or an empty list when none exist
 60	GetUserDelegationIDs(delegator address, delegatee address) []int64
 61	// HasDelegationSnapshotsKey reports whether total delegation history has
 62	// been initialized in storage.
 63	//
 64	// Returns:
 65	//   - bool: true when the total delegation history store key exists; false otherwise
 66	HasDelegationSnapshotsKey() bool
 67	// GetTotalDelegationAmountAtSnapshot finds the latest total delegation
 68	// history value at or before a Unix timestamp.
 69	//
 70	// Parameters:
 71	//   - snapshotTime: Unix timestamp at which to resolve historical total delegation
 72	//
 73	// Returns:
 74	//   - int64: total delegated amount from the latest qualifying history entry
 75	//   - bool: true when a qualifying history entry exists; false when history has no such entry
 76	GetTotalDelegationAmountAtSnapshot(snapshotTime int64) (int64, bool)
 77	// GetUserDelegationAmountAtSnapshot finds one user's latest delegation
 78	// history value at or before a Unix timestamp.
 79	//
 80	// Parameters:
 81	//   - userAddr: user's address whose delegation history is searched
 82	//   - snapshotTime: Unix timestamp at which to resolve the user's historical delegation
 83	//
 84	// Returns:
 85	//   - int64: user's delegated amount from the latest qualifying history entry
 86	//   - bool: true when a qualifying history entry exists; false otherwise
 87	GetUserDelegationAmountAtSnapshot(userAddr address, snapshotTime int64) (int64, bool)
 88
 89	// Reward getters
 90	// GetClaimableRewardByAddress computes current claimable emission and
 91	// protocol-fee rewards for an address reward ID.
 92	//
 93	// Parameters:
 94	//   - addr: staker address whose reward ID is queried
 95	//
 96	// Returns:
 97	//   - int64: claimable GNS emission reward amount
 98	//   - map[string]int64: claimable protocol-fee amounts keyed by token path
 99	//   - error: nil when both reward streams are computed; otherwise the reward-accounting error
100	GetClaimableRewardByAddress(addr address) (int64, map[string]int64, error)
101	// GetClaimableRewardByLaunchpad computes rewards for a launchpad project
102	// wallet's launchpad-specific reward ID.
103	//
104	// Parameters:
105	//   - addr: registered launchpad project wallet address
106	//
107	// Returns:
108	//   - int64: claimable GNS emission reward amount
109	//   - map[string]int64: claimable protocol-fee amounts keyed by token path
110	//   - error: nil when both reward streams are computed; otherwise the reward-accounting error
111	GetClaimableRewardByLaunchpad(addr address) (int64, map[string]int64, error)
112	// GetClaimableRewardByRewardID computes current rewards for an explicit
113	// reward identifier.
114	//
115	// Parameters:
116	//   - rewardID: staker or launchpad reward-state identifier
117	//
118	// Returns:
119	//   - int64: claimable GNS emission reward amount
120	//   - map[string]int64: claimable protocol-fee amounts keyed by token path
121	//   - error: nil when both reward streams are computed; otherwise the reward-accounting error
122	GetClaimableRewardByRewardID(rewardID string) (int64, map[string]int64, error)
123
124	// Launchpad getters
125	// GetLaunchpadProjectDeposit returns a project's recorded launchpad deposit.
126	//
127	// Parameters:
128	//   - projectAddr: project address identifier used to derive the launchpad reward key
129	//
130	// Returns:
131	//   - int64: stored project deposit amount
132	//   - bool: true when a deposit record exists for projectAddr; false otherwise
133	GetLaunchpadProjectDeposit(projectAddr string) (int64, bool)
134
135	// Withdraw getters
136	// GetDelegationWithdrawCount returns the number of pending withdrawal
137	// records attached to a delegation.
138	//
139	// Parameters:
140	//   - delegationID: delegation whose withdrawal list is counted
141	//
142	// Returns:
143	//   - int: number of withdrawal records, or 0 when the delegation is absent
144	GetDelegationWithdrawCount(delegationID int64) int
145	// GetDelegationWithdraws returns a slice of a delegation's withdrawal list.
146	//
147	// Parameters:
148	//   - delegationID: delegation whose withdrawals are requested
149	//   - offset: non-negative zero-based starting index in the withdrawal list
150	//   - count: non-negative maximum number of withdrawals to include
151	//
152	// Returns:
153	//   - []DelegationWithdraw: withdrawals in the requested range, or an empty slice when the delegation or range is absent
154	//   - error: nil when the lookup completes; an unknown delegation yields an empty slice
155	GetDelegationWithdraws(delegationID int64, offset, count int) ([]DelegationWithdraw, error)
156	// GetCollectableWithdrawAmount sums all withdrawal amounts currently
157	// collectable for a delegation.
158	//
159	// Parameters:
160	//   - delegationID: delegation whose expired withdrawals are summed
161	//
162	// Returns:
163	//   - int64: total GNS amount collectable now, or 0 when none is collectable
164	GetCollectableWithdrawAmount(delegationID int64) int64
165
166	// Protocol fee reward getters
167	// GetProtocolFeeAccumulatedX128PerStake returns the per-stake protocol-fee
168	// accumulator for a token path, scaled by 2^128.
169	//
170	// Parameters:
171	//   - tokenPath: registered token path whose accumulator is queried
172	//
173	// Returns:
174	//   - *uint256.Uint: Q128-scaled accumulated fee per stake, zero when the token has no folded fee
175	GetProtocolFeeAccumulatedX128PerStake(tokenPath string) *uint256.Uint
176	// GetProtocolFeeAmount returns the total protocol fee folded for a token
177	// path.
178	//
179	// Parameters:
180	//   - tokenPath: registered token path whose folded fee amount is queried
181	//
182	// Returns:
183	//   - int64: total folded protocol-fee amount, or 0 when the token has no accumulator
184	GetProtocolFeeAmount(tokenPath string) int64
185	// GetProtocolFeeAccumulatedTimestamp returns the last timestamp at which
186	// protocol-fee accrual state advanced.
187	//
188	// Returns:
189	//   - int64: Unix timestamp of the latest protocol-fee accumulation update
190	GetProtocolFeeAccumulatedTimestamp() int64
191
192	// Emission reward getters
193	// GetEmissionAccumulatedX128PerStake returns the accumulated GNS emission
194	// reward per stake, scaled by 2^128.
195	//
196	// Returns:
197	//   - *uint256.Uint: Q128-scaled accumulated emission per stake
198	GetEmissionAccumulatedX128PerStake() *uint256.Uint
199	// GetEmissionDistributedAmount returns the total GNS emission distributed
200	// through the staker reward manager.
201	//
202	// Returns:
203	//   - int64: cumulative distributed GNS emission amount
204	GetEmissionDistributedAmount() int64
205	// GetEmissionAccumulatedTimestamp returns the last timestamp at which
206	// emission reward accrual state advanced.
207	//
208	// Returns:
209	//   - int64: Unix timestamp of the latest emission accumulation update
210	GetEmissionAccumulatedTimestamp() int64
211}