staker package

CleanStakerDelegationSnapshotByAdmin removes old delegation snapshots for the total history and the user history of a single target address. Only callable by admin.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• threshold: Unix timestamp cutoff for removing eligible old delegation history
• target: user address whose delegation history to clean

Halt check: reverts while the GovStaker halt scope is active.

CollectEmissionReward claims the caller's accumulated GNS emission reward.

The call is subject to the withdrawal halt and transfers GNS when a reward is available.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.

Halt check: reverts while the Withdraw halt scope is active.

CollectEmissionRewardFromLaunchPad claims only accumulated GNS emission rewards for a registered launchpad project wallet.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• to: registered launchpad project wallet whose emission reward is claimed

Halt check: reverts while the Withdraw halt scope is active.

CollectProtocolFeeReward claims accumulated protocol-fee rewards for one registered token path. Folding and settlement are bounded per call; any remaining buckets or stake events are collected by a later call.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• tokenPath: registered token path whose accumulated protocol-fee reward is claimed

Halt check: reverts while the Withdraw halt scope is active.

CollectProtocolFeeRewardFromLaunchPad claims one token path of accumulated protocol-fee rewards for a registered launchpad project wallet.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• to: registered launchpad project wallet whose protocol-fee reward is claimed
• tokenPath: registered token path whose accumulated protocol-fee reward is claimed

Halt check: reverts while the Withdraw halt scope is active.

CollectReward claims the caller's GNS emission reward and all known protocol-fee token rewards.

The all-token path folds and settles every known token. It is not a single-current-xGNS-balance formula.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.

Halt check: reverts while the Withdraw halt scope is active.

CollectRewardFromLaunchPad claims both GNS emission and protocol-fee rewards for a registered launchpad project wallet. Only the launchpad contract may call this entry point.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• to: registered launchpad project wallet that receives both reward streams

Halt check: reverts while the Withdraw halt scope is active.

CollectUndelegatedGns collects the amount of the undelegated GNS.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.

Returns:

• amount: GNS amount released to the caller after eligible undelegation withdrawals are collected

Halt check: reverts while the Withdraw halt scope is active.

Delegate delegates GNS to a delegate.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• to: delegatee address that receives voting power
• amount: positive GNS amount to delegate and convert to xGNS voting power
• referrer: optional referral identifier to register for reward tracking

Returns:

• delegatedAmount: The amount of GNS delegated and mirrored as xGNS.

Halt check: reverts while the GovStaker halt scope is active.

ExistsDelegation checks if a delegation exists. Parameters:

• delegationID: Numeric identifier of the delegation to look up.

Returns:

• bool: true when a delegation with delegationID exists, false otherwise.

GetClaimableRewardByAddress returns claimable rewards for an address.

Parameters:

• addr: Address whose emission and protocol-fee rewards are queried.

Returns:

• int64: emission reward amount available to addr.
• map[string]int64: protocol-fee reward amounts keyed by token path.
• error: nil on success; non-nil when reward state cannot be resolved for addr.

GetClaimableRewardByLaunchpad returns claimable launchpad rewards for an address.

Parameters:

• addr: Address whose launchpad and protocol-fee rewards are queried.

Returns:

• int64: emission reward amount available to addr.
• map[string]int64: protocol-fee reward amounts keyed by token path.
• error: nil on success; non-nil when reward state cannot be resolved for addr.

GetClaimableRewardByRewardID returns claimable reward details by reward ID.

Parameters:

• rewardID: Reward-state identifier whose claimable rewards are queried.

Returns:

• int64: emission reward amount associated with rewardID.
• map[string]int64: protocol-fee reward amounts keyed by token path.
• error: nil on success; non-nil when rewardID cannot be resolved.

GetCollectableWithdrawAmount returns the collectable withdraw amount for a specific delegation. Parameters:

• delegationID: Identifier of the delegation whose collectable amount is queried.

Returns:

• int64: amount currently available to collect from delegationID.

GetDelegationWithdrawCount returns the total number of delegation withdraws for a specific delegation. Parameters:

• delegationID: Identifier of the delegation whose withdrawals are counted.

Returns:

• int: number of withdrawal records associated with delegationID.

GetDelegations returns a read-only view of every delegation, keyed by the decimal string form of the delegation ID. Callers paginate it themselves through IterateByOffset. Reading an entry yields a clone, so the view cannot mutate realm state. Returns:

• *rotree.ReadOnlyTree: read-only delegation view keyed by decimal delegation ID; entry reads return clones.

GetDelegatorDelegations returns a read-only view of a delegator's delegations, keyed by delegatee address with that pair's delegation IDs as the value. Reading an entry yields a copy of the ID slice, so the view cannot mutate realm state. nil is returned when the delegator has no delegations. Parameters:

• delegator: Address whose delegations should be listed.

Returns:

• *rotree.ReadOnlyTree: read-only view keyed by delegatee address, or nil when delegator has no delegations.

GetEmissionAccumulatedTimestamp returns the accumulated timestamp for emission rewards. Returns:

• int64: Unix timestamp at which emission accumulation was last updated.

GetEmissionAccumulatedX128PerStake returns the accumulated emission per stake (Q128). Returns:

• *u256.Uint: accumulated emission reward per unit stake in Q128 fixed-point form.

GetEmissionDistributedAmount returns the total distributed emission amount. Returns:

• int64: total emission amount distributed to stakers.

GetImplementationPackagePath returns the package path of the currently active implementation.

Returns:

• packagePath: package path of the active implementation

GetLaunchpadProjectDeposit returns the deposit amount for a launchpad project. Parameters:

• projectAddr: Launchpad project address whose deposited amount is queried.

Returns:

• int64: recorded launchpad project deposit amount.
• bool: true when a deposit record exists for projectAddr; false otherwise.

GetProtocolFeeAccumulatedTimestamp returns the accumulated timestamp for protocol fee rewards. Returns:

• int64: Unix timestamp at which protocol-fee accumulation was last updated.

GetProtocolFeeAccumulatedX128PerStake returns the accumulated protocol fee per stake (Q128) for a token path. Parameters:

• tokenPath: Registered token path whose protocol-fee accumulator is queried.

Returns:

• *u256.Uint: accumulated protocol-fee amount per unit stake in Q128 fixed-point form.

GetProtocolFeeAmount returns the protocol fee amounts for a token path. Parameters:

• tokenPath: Registered token path whose protocol fees are queried.

Returns:

• int64: accumulated protocol-fee amount for tokenPath in token base units.

GetTotalDelegated returns the total amount of GNS delegated. Returns:

• int64: total GNS amount delegated across all delegators.

GetTotalDelegationAmountAtSnapshot returns total delegation at a Unix timestamp, using the latest history entry at or before that timestamp. The lookup is timestamp-based rather than a block-height snapshot. Parameters:

• snapshotTime: Unix timestamp at or before which to select the latest aggregate delegation history entry.

Returns:

• int64: aggregate delegated amount recorded at or before snapshotTime.
• bool: true when a qualifying history entry exists; false when no entry is available.

GetTotalLockedAmount returns the total amount of GNS locked in undelegation. Returns:

• int64: total GNS amount currently locked in undelegation withdrawals.

GetTotalxGnsSupply returns total xGNS supply, including launchpad-held xGNS. Returns:

• int64: total xGNS supply, including xGNS held by launchpad projects.

GetUnDelegationLockupPeriod returns the undelegation lockup period in seconds. Returns:

• int64: configured undelegation lockup duration in seconds.

GetUserDelegationAmountAtSnapshot returns one user's delegation at a Unix timestamp, using that user's latest history entry at or before the timestamp. The bool is false when no qualifying history entry exists. Parameters:

• userAddr: Delegator address whose historical delegation is queried.
• snapshotTime: Unix timestamp at or before which to select the user's latest history entry.

Returns:

• int64: user's delegated amount recorded at or before snapshotTime.
• bool: true when a qualifying user-history entry exists; false otherwise.

GetUserDelegationIDs returns a list of delegation IDs for a specific delegator-delegatee pair. Parameters:

• delegator: Address that supplied the delegation.
• delegatee: Address receiving that delegation.

Returns:

• []int64: delegation IDs for the delegator-delegatee pair; the returned slice is independent of realm state.

HasDelegationSnapshotsKey returns true if delegation history exists. Returns:

• bool: true when delegation history has been initialized in storage.

NewDelegationTree creates an empty tree for delegatee-to-delegation-ID mappings.

Returns:

• *bptree.BPTree: empty tree configured for delegation lookup entries.

NewUserDelegationTree creates an empty tree for user delegation mappings. Returns:

• *bptree.BPTree: empty tree configured for user delegation entries.

Redelegate redelegates xGNS from the existing delegate to another.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• delegatee: current delegatee address whose voting power is reduced
• newDelegatee: destination address that receives the redelegated voting power
• amount: positive xGNS amount to move without a user-facing lockup

Returns:

• redelegatedAmount: The amount moved from the current delegatee to the new delegatee.

Halt check: reverts while the GovStaker halt scope is active.

RegisterInitializer registers an implementation initializer for this realm. Each implementation version calls it during initialization. The callback receives the current realm context and shared gov/staker store so it can construct the versioned implementation.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm
• initializer: callback invoked with discriminator 0, validated propagated realm context, and IGovStakerStore, returning the implementation

Render delegates web rendering to the active implementation.

SetAmountByProjectWallet adjusts launchpad-backed stake and xGNS accounting for a project wallet. Only callable by launchpad contract.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• addr: registered project wallet whose launchpad-backed stake is adjusted
• amount: stake amount delta passed to the launchpad reward accounting
• add: true to add stake and mint xGNS; false to remove stake and burn xGNS

Halt check: reverts while the GovStaker halt scope is active when add is true, or while the Withdraw halt scope is active when add is false.

SetUnDelegationLockupPeriodByAdmin sets the undelegation lockup period. Only callable by admin.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• period: non-negative undelegation lockup duration in seconds

Halt check: reverts while the GovStaker halt scope is active.

Undelegate undelegates xGNS from the existing delegate.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• from: delegatee address from which the caller removes delegation
• amount: positive xGNS amount to move into undelegation lockup

Returns:

• amount: The amount of GNS moved into undelegation lockup.

Halt check: reverts while the Withdraw halt scope is active.

UpgradeImpl upgrades the active implementation to packagePath. Only admin or governance can call this function.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm
• packagePath: package path of the implementation version to activate

NewCounter creates a counter initialized before the first allocated identifier.

Returns:

• *Counter: counter whose current identifier is zero.

NewDelegation creates a delegation record with no undelegated or collected amount.

Parameters:

• id: unique identifier assigned to this delegation record.
• delegateFrom: address whose tokens are delegated.
• delegateTo: address receiving the delegated voting power.
• delegateAmount: initial delegated token amount in the smallest token unit.
• createdHeight: block height at which the delegation was created.
• createdAt: Unix timestamp at which the delegation was created.

Returns:

• *Delegation: initialized delegation with empty withdrawal history.

NewDelegationManager creates a new instance of DelegationManager. This factory function initializes the BPTree structure for tracking user delegations.

Returns:

• *DelegationManager: manager ready to track delegator/delegatee ID lists.

GetDelegationWithdraws returns a paginated list of delegation withdraws for a specific delegation. Parameters:

• delegationID: Identifier of the delegation whose withdrawals are requested.
• offset: Number of matching withdrawal records to skip before collecting results.
• count: Maximum number of withdrawal records to return.

Returns:

• []DelegationWithdraw: requested page of withdrawal records, copied before returning.
• error: nil on success; non-nil when the requested delegation or page cannot be read.

NewDelegationWithdraw creates a new delegation withdrawal with lockup period. The withdrawal becomes collectable after the lockup period expires.

Parameters:

• delegationID: Unique identifier of the associated delegation.
• unDelegateAmount: Amount being withdrawn.
• createdHeight: Block height at which the undelegation was created.
• createdAt: Unix timestamp at which the withdrawal was created.
• unDelegationLockupPeriod: Lockup duration in seconds.

Returns:

• DelegationWithdraw: new withdrawal instance with its collectable time set after the lockup.

NewDelegationWithdrawWithoutLockup creates a withdrawal that is immediately collectable. This is used for special cases such as redelegation where no lockup is required.

Parameters:

• delegationID: Unique identifier of the associated delegation.
• unDelegateAmount: Amount being withdrawn.
• createdHeight: Block height at which the undelegation was created.
• createdAt: Unix timestamp at which the withdrawal was created.

Returns:

• DelegationWithdraw: new withdrawal instance marked collected with collectable time equal to createdAt.

NewEmissionRewardManager creates and initializes an EmissionRewardManager with empty reward states and zero accounting totals. Returns:

• *EmissionRewardManager: initialized manager with empty reward states, zero totals, and a zero Q128 accumulator.

NewEmissionRewardState creates a new emission reward state for a staker. This factory function initializes the state with the current system reward debt.

Parameters:

• accumulatedRewardX128PerStake: current system-wide accumulated reward per stake

Returns:

• *EmissionRewardState: new emission reward state instance

NewGovStakerStore creates a new governance staker store instance backed by kvStore.

Parameters:

• kvStore: Key-value store used to persist governance staker state.

Returns:

• IGovStakerStore: store implementation that reads and writes the supplied KV store.

NewLaunchpadProjectDeposits creates an empty owner-to-deposit tree.

Returns:

• *LaunchpadProjectDeposits: deposit manager initialized with an empty tree.

NewProtocolFeeRewardManager creates a new instance of ProtocolFeeRewardManager.

Returns:

• *ProtocolFeeRewardManager: new protocol fee reward manager instance

NewProtocolFeeRewardState creates an empty state for a staker with no stake.

Returns:

• *ProtocolFeeRewardState: initialized reward state with empty event and token trees

NewProtocolFeeTokenAccumulator creates an empty accumulator with no folded epochs or protocol fees recorded.

Returns:

• *ProtocolFeeTokenAccumulator: accumulator initialized with zero values and empty epoch history.

NewProtocolFeeTokenRewardState creates the settlement state of a token whose open segment starts at the given cursor, stake and accumulator value.

Parameters:

• eventCursor: number of stake events already folded into this token state
• segmentStakedAmount: stake amount in force during the open segment
• segmentStartX128: accumulated fee-per-stake value at the open segment start, scaled by 2^128

Returns:

• *ProtocolFeeTokenRewardState: token settlement state with zero closed-segment earnings and claimed reward

NewUintTree creates a new UintTree instance.

Returns:

• *UintTree: new tree backed by an empty ordered BPTree