v1 source realm

Package v1 manages GNS delegation and xGNS accounting. It maintains timestamped delegation history, distributes GNS e...

Gov Staker

Governance delegation and xGNS-based voting power management.

Overview

Gov Staker accepts GNS staking, mints and burns xGNS, maintains delegatee balances and timestamped delegation history, tracks undelegation lockups, and settles two reward streams for stakers: GNS emission rewards and protocol-fee rewards in any registered token.

Configuration

Undelegation Lockup: configurable; the default is 7 days before undelegated GNS can be collected.
Reward Sources: GNS emission (single token) and protocol-fee distribution (one accumulator per fee token).
Delegation State: per-delegator/delegatee records, total and user timestamp histories, and reward stake events.

Core Features

Delegation

Delegate GNS to any valid address; the delegated amount is mirrored as xGNS voting power.
Redelegate between delegatees without a lockup. Redelegation performs an immediate remove-plus-add for reward accounting.
Track undelegated balances until the configured lockup expires; collecting then burns the corresponding xGNS and returns GNS.

Rewards

CollectReward claims both the emission stream and all known protocol-fee tokens.
CollectEmissionReward claims only GNS emission rewards.
CollectProtocolFeeReward claims one protocol-fee token; its bucket and stake-event work is bounded per call, so remaining work is collected later.
Launchpad can collect the matching emission and protocol-fee rewards for a registered project wallet through launchpad-only entry points.

Protocol-fee rewards are not calculated as a single current-balance share. Each token's fee buckets are divided by the total stake in force during their accrual epochs, accumulated in Q128 fixed point, and settled across each staker's timestamped stake-event segments. Fractional remainders remain in state for later collection.

History and Snapshots

Historical delegation snapshots are timestamp lookups used by governance's configured smoothing calculation; they are not block-height snapshots.
Cleanup functions preserve history needed by active proposals.

Key Functions

`Delegate`

Transfers GNS from the caller, mints the same amount of xGNS, and assigns the delegated voting power to a target address. The caller must approve the GNS transfer first.

`Undelegate`

Removes voting power immediately and creates a withdrawal subject to the configured lockup.

`Redelegate`

Moves delegated balance from one delegatee to another immediately, without creating a user-facing lockup.

`CollectReward`

Claims the caller's GNS emission rewards and all known protocol-fee rewards. The all-token path intentionally grows with the number of known fee tokens.

`CollectEmissionReward`

Claims only the caller's accumulated GNS emission reward.

`CollectProtocolFeeReward`

Claims one token path's accumulated protocol-fee reward. A later call may be required when pending accrual buckets or stake events exceed the per-call bound.

`CollectUndelegatedGns`

Collects GNS after the configured undelegation lockup has passed and burns the corresponding xGNS.

`CollectRewardFromLaunchPad`

Collects both reward streams for a registered launchpad project wallet. This entry point is callable only by the launchpad contract and sends rewards to the supplied project-wallet address.

Delegation Logic

Delegation Flow

Approve GNS spending by the gov/staker realm.
Delegate GNS to a delegatee; xGNS is minted and timestamped history is updated.
Governance reads the delegatee's history at proposal-defined timestamps for vote weight.
Undelegate to start the lockup, or redelegate immediately to another delegatee.
After the lockup expires, collect undelegated GNS.

Usage

These snippets call the public domain proxy from a realm function with a current cur token. Import the proxy package and qualify its function names in integrating code.

 1// Delegate GNS to another address; xGNS voting power is minted 1:1.
 2delegatedAmount := Delegate(cross(cur), delegatee, 1_000_000_000, "g1referrer...")
 3
 4// Redelegate part of the active balance immediately.
 5Redelegate(cross(cur), delegatee, newDelegatee, 500_000_000)
 6
 7// Claim both GNS emission and all known protocol-fee tokens.
 8CollectReward(cross(cur))
 9
10// Or claim only one stream/token.
11CollectEmissionReward(cross(cur))
12CollectProtocolFeeReward(cross(cur), tokenPath)
13
14// Start undelegation. Collect only after the configured lockup (7 days by default).
15Undelegate(cross(cur), delegatee, 250_000_000)
16// ...wait until the lockup has expired...
17CollectUndelegatedGns(cross(cur))

Security

Timestamped delegation history and configurable smoothing reduce flash-loan-style voting manipulation; they do not provide a block snapshot.
Undelegation removes voting power immediately, while the lockup delays GNS withdrawal.
Protocol-fee stake changes must remain independent of the number of fee tokens; only collection folds fee buckets.
Launchpad reward entry points are restricted to the launchpad contract and registered project wallets.
Snapshot cleanup must preserve data still needed by active proposals.

Package v1 manages GNS delegation and xGNS accounting. It maintains timestamped delegation history, distributes GNS emission and protocol-fee rewards, and enforces a configurable undelegation lockup (7 days by default; xGNS is burned when undelegated GNS is collected).

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

source

NewDelegation creates a new delegation. This is a convenience wrapper around staker.NewDelegation.

Parameters:

id: delegation ID
delegateFrom: delegator's address
delegateTo: delegatee's address
delegateAmount: amount to delegate
createdHeight: creation block height
createdAt: creation timestamp

Returns:

*staker.Delegation: new delegation instance

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

source

NewDelegationWithdraw creates a new delegation withdrawal with lockup period. This is a convenience wrapper around staker.NewDelegationWithdraw.

Parameters:

delegationID: unique identifier of the associated delegation
unDelegateAmount: amount being withdrawn
createdHeight: height when the withdrawal was created
createdAt: timestamp when the withdrawal was created
unDelegationLockupPeriod: duration of the lockup period in seconds

Returns:

staker.DelegationWithdraw: new withdrawal instance with lockup

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

source

NewDelegationWithdrawWithoutLockup creates a new delegation withdrawal that is immediately collectable. This is a convenience wrapper around staker.NewDelegationWithdrawWithoutLockup.

Parameters:

delegationID: unique identifier of the associated delegation
unDelegateAmount: amount being withdrawn
createdHeight: height when the withdrawal was created
createdAt: timestamp when the withdrawal was created

Returns:

staker.DelegationWithdraw: new withdrawal instance that is immediately collectable

1func NewGovStakerV1(store staker.IGovStakerStore) staker.IGovStaker

source

NewGovStakerV1 creates the governance staker v1 implementation backed by store.

Parameters:

store: governance-staker storage interface used by the implementation.

Returns:

staker.IGovStaker: governance staker API backed by store.

1func NewDelegationManagerResolver(delegationManager *staker.DelegationManager) *DelegationManagerResolver

source

NewDelegationManagerResolver creates a resolver over an existing delegation manager.

Parameters:

delegationManager: manager whose domain-owned delegation trees will be queried or updated.

Returns:

*DelegationManagerResolver: resolver exposing address-typed delegation operations.

1func NewDelegationResolver(delegation *staker.Delegation) *DelegationResolver

source

NewDelegationResolver wraps a delegation in a resolver for derived amounts and withdrawals.

Parameters:

delegation: delegation state to resolve

Returns:

*DelegationResolver: resolver backed by delegation

1func NewDelegationWithdrawResolver(withdraw *staker.DelegationWithdraw) *DelegationWithdrawResolver

source

NewDelegationWithdrawResolver wraps a delegation withdrawal for collection state and lockup calculations.

Parameters:

withdraw: delegation withdrawal state to resolve

Returns:

*DelegationWithdrawResolver: resolver retaining the supplied withdrawal pointer

1func NewEmissionRewardManagerResolver(emissionRewardManager *staker.EmissionRewardManager) *EmissionRewardManagerResolver

source

NewEmissionRewardManagerResolver wraps an emission reward manager with reward calculation and stake-accounting helpers.

Parameters:

emissionRewardManager: manager state to resolve and mutate.

Returns:

*EmissionRewardManagerResolver: resolver backed by emissionRewardManager.

1func NewEmissionRewardStateResolver(emissionRewardState *staker.EmissionRewardState) *EmissionRewardStateResolver

source

NewEmissionRewardStateResolver wraps an on-chain emission reward state for reward calculation and stake/claim updates.

Parameters:

emissionRewardState: persisted reward state to expose through the resolver

Returns:

*EmissionRewardStateResolver: resolver backed by emissionRewardState

1func NewLaunchpadProjectDepositsResolver(launchpadProjectDeposits *staker.LaunchpadProjectDeposits) *LaunchpadProjectDepositsResolver

source

NewLaunchpadProjectDepositsResolver wraps launchpad project deposit state.

Parameters:

launchpadProjectDeposits: project deposit state to resolve and mutate

Returns:

*LaunchpadProjectDepositsResolver: resolver retaining the supplied deposit state pointer

1func NewProtocolFeeRewardManagerResolver(manager *staker.ProtocolFeeRewardManager) *ProtocolFeeRewardManagerResolver

source

NewProtocolFeeRewardManagerResolver wraps the shared protocol-fee reward manager.

Parameters:

manager: Protocol-fee reward state to resolve and mutate.

Returns:

*ProtocolFeeRewardManagerResolver: resolver operating on manager's accounting state.

1func NewProtocolFeeRewardStateResolver(protocolFeeRewardState *staker.ProtocolFeeRewardState) *ProtocolFeeRewardStateResolver

source

NewProtocolFeeRewardStateResolver wraps one staker's protocol fee reward state with settlement operations.

Parameters:

protocolFeeRewardState: staker reward state to resolve and mutate.

Returns:

*ProtocolFeeRewardStateResolver: resolver backed by protocolFeeRewardState.

1type DelegationManagerResolver struct {
2	*staker.DelegationManager
3}

source

1func (dm *DelegationManagerResolver) GetUserDelegationIDs(delegator address) []int64

source

GetUserDelegationIDs retrieves all delegation IDs for a specific delegator across all delegatees. This method is used to find all delegations made by a specific user.

Parameters:

delegator: address of the user whose delegations to retrieve

Returns:

[]int64: concatenated delegation IDs from every stored delegatee entry, or an empty slice when absent.

1func (dm *DelegationManagerResolver) GetUserDelegationIDsWithDelegatee(delegator, delegatee address) []int64

source

GetUserDelegationIDsWithDelegatee retrieves all delegation IDs for a specific delegator-delegatee pair. This method is used to find delegations from a specific user to a specific delegate.

Parameters:

delegator: address of the user who delegated tokens
delegatee: address of the user who received the delegation

Returns:

[]int64: matching delegation IDs, or an empty slice when no pair is stored.

1type DelegationResolver struct {
2	delegation *staker.Delegation
3}

source

1func (r *DelegationResolver) CollectableAmount(currentTime int64) (total int64)

source

CollectableAmount calculates the total amount that can be collected at the given time.

Parameters:

currentTime: current Unix timestamp used to evaluate each withdrawal's lockup

Returns:

total: sum of all withdrawal amounts currently available for collection

1func (r *DelegationResolver) DelegatedAmount() int64

source

DelegatedAmount returns total delegated amount minus amount already undelegated.

Returns:

int64: amount still delegated

1func (r *DelegationResolver) Get() *staker.Delegation

source

Get returns the underlying delegation state.

Returns:

*staker.Delegation: wrapped delegation instance

1func (r *DelegationResolver) IsEmpty() bool

source

IsEmpty reports whether no locked delegation amount remains.

Returns:

bool: true when LockedAmount is zero, otherwise false

1func (r *DelegationResolver) LockedAmount() int64

source

LockedAmount returns total delegated amount minus amount already collected.

Returns:

int64: amount still locked in the delegation

1func (r *DelegationResolver) UnDelegate(
2	amount, currentHeight, currentTimestamp, unDelegationLockupPeriod int64,
3)

source

UnDelegate processes an undelegation with a time-based lockup period.

Parameters:

amount: amount to undelegate and place into a withdrawal
currentHeight: block height at which the undelegation is recorded
currentTimestamp: Unix timestamp at which the undelegation is recorded
unDelegationLockupPeriod: lockup duration in seconds before the withdrawal is collectible

1func (r *DelegationResolver) UnDelegateWithoutLockup(
2	amount, currentHeight, currentTime int64,
3)

source

UnDelegateWithoutLockup processes an immediate undelegation without lockup.

Parameters:

amount: amount to undelegate and mark as collected immediately
currentHeight: current block height context; retained for API symmetry and unused by this immediate path
currentTime: current Unix timestamp context; retained for API symmetry and unused by this immediate path

1type DelegationWithdrawResolver struct {
2	withdraw *staker.DelegationWithdraw
3}

source

1func (r *DelegationWithdrawResolver) Collect(amount int64, currentTime int64) error

source

collect processes the collection of the specified amount from this withdrawal. This method validates collectability and updates the collection state.

Parameters:

amount: GNS amount to add to this withdrawal's collected amount
currentTime: Unix timestamp used to check lockup expiry and record collection time

Returns:

error: nil after the collection state is updated; errWithdrawNotCollectable when the withdrawal is not collectable

1func (r *DelegationWithdrawResolver) CollectableAmount(currentTime int64) int64

source

CollectableAmount calculates the amount available for collection at the given time. Returns zero if the withdrawal is not yet collectable or has been fully collected.

Parameters:

currentTime: current timestamp to check collectability against

Returns:

int64: amount available for collection

1func (r *DelegationWithdrawResolver) Get() *staker.DelegationWithdraw

source

Get returns the wrapped delegation withdrawal value.

Returns:

*staker.DelegationWithdraw: wrapped withdrawal pointer, or nil when the resolver was constructed with nil

1func (r *DelegationWithdrawResolver) IsCollectable(currentTime int64) bool

source

IsCollectable determines whether the withdrawal can be collected at the given time. A withdrawal is collectable if: - The undelegated amount is positive - There is remaining uncollected amount - The current time is at or after the collectable time

Parameters:

currentTime: current timestamp to check against

Returns:

bool: true if the withdrawal can be collected, false otherwise

1func (r *DelegationWithdrawResolver) IsCollected() bool

source

IsCollected returns whether the withdrawal has been fully collected.

Returns:

bool: true if fully collected, false otherwise

1type EmissionRewardManagerResolver struct {
2	*staker.EmissionRewardManager
3}

source

1func (self *EmissionRewardManagerResolver) GetClaimableRewardAmount(
2	currentDistributedAmount int64,
3	address string,
4	currentTimestamp int64,
5) (int64, error)

source

GetClaimableRewardAmount calculates the claimable reward amount for a specific address.

Parameters:

currentDistributedAmount: total emission amount distributed to the staker manager at the current observation point.
address: reward-state identifier whose claimable amount is requested.
currentTimestamp: Unix timestamp used to settle the address's reward state.

Returns:

int64: emission reward currently claimable by address, or zero when no reward state exists.
error: nil on success; an error from accumulated-reward or reward-state resolution when calculation fails.

1type EmissionRewardStateResolver struct {
2	*staker.EmissionRewardState
3}

source

1func (self *EmissionRewardStateResolver) GetClaimableRewardAmount(
2	accumulatedRewardX128PerStake *u256.Uint,
3	currentTimestamp int64,
4) (int64, error)

source

GetClaimableRewardAmount calculates the total amount of rewards that can be claimed. It combines newly earned rewards with accumulated rewards not yet claimed.

Parameters:

accumulatedRewardX128PerStake: system-wide accumulated reward per stake, scaled by 2^128
currentTimestamp: timestamp through which newly earned rewards are calculated

Returns:

int64: total claimable amount, including accumulated-but-unclaimed and newly earned rewards
error: nil on success; an error propagated from reward calculation otherwise

1func (self *EmissionRewardStateResolver) IsClaimable(currentTimestamp int64) bool

source

IsClaimable checks if rewards can be claimed at the given timestamp. Rewards are claimable only when currentTimestamp is later than the stored claimed timestamp.

Parameters:

currentTimestamp: timestamp at which claimability is evaluated

Returns:

bool: true when currentTimestamp is greater than the last claimed timestamp

1type LaunchpadProjectDepositsResolver struct {
2	*staker.LaunchpadProjectDeposits
3}

source

1type ProtocolFeeRewardManagerResolver struct {
2	*staker.ProtocolFeeRewardManager
3}

source

ProtocolFeeRewardManagerResolver drives the ProtocolFeeRewardManager.

Stake changes only move the epoch, the total stake history and the staker's own event list. Fees are folded into a token's accumulator when that token is collected, each accrual bucket against the total stake in force during its epoch.

1func (self *ProtocolFeeRewardManagerResolver) GetClaimableRewardAmount(rewardID string, tokenPath string, pendingEpochs []int64, pendingAmounts []int64) (int64, error)

source

GetClaimableRewardAmount returns what collecting tokenPath for rewardID would pay, with the given pending buckets projected on top of the accumulator. Parameters:

rewardID: Identifier of the staker whose claimable reward is quoted.
tokenPath: Token path whose claimable protocol-fee reward is quoted.
pendingEpochs: Pending bucket epochs projected on the accumulator.
pendingAmounts: Pending fee amounts parallel to pendingEpochs.

Returns:

int64: protocol-fee amount that collecting tokenPath would pay in token base units.
error: nil on success; non-nil when reward-state lookup or projection fails.

1type ProtocolFeeRewardStateResolver struct {
2	*staker.ProtocolFeeRewardState
3}

source

ProtocolFeeRewardStateResolver settles one staker's protocol fee rewards.

A staker's reward for a token is the sum, over the segments between their stake events, of the stake held during the segment times the growth of the token's accumulated fee per stake across it. Segments are folded in event order, so the work of settling a token is proportional to the staker's own stake changes since the token was last settled, never to the number of tokens.

1func (p *ProtocolFeeRewardStateResolver) IsClaimable(currentTimestamp int64) bool

source

IsClaimable reports whether every token may be collected at once at currentTimestamp.

Parameters:

currentTimestamp: current Unix timestamp used to compare the last collection.

Returns:

bool: true when currentTimestamp is later than the state's claimed timestamp.

Readme View source

Gov Staker

Overview

Configuration

Core Features

Delegation

Rewards

History and Snapshots

Key Functions

Delegate

Undelegate

Redelegate

CollectReward

CollectEmissionReward

CollectProtocolFeeReward

CollectUndelegatedGns

CollectRewardFromLaunchPad

Delegation Logic

Delegation Flow

Usage

Security

Overview

Functions 12

Types 8

Methods on DelegationManagerResolver

Methods on DelegationResolver

Methods on DelegationWithdrawResolver

Methods on EmissionRewardManagerResolver

Methods on EmissionRewardStateResolver

Methods on ProtocolFeeRewardManagerResolver

Methods on ProtocolFeeRewardStateResolver

Imports 28

Source Files 25

`Delegate`

`Undelegate`

`Redelegate`

`CollectReward`

`CollectEmissionReward`

`CollectProtocolFeeReward`

`CollectUndelegatedGns`

`CollectRewardFromLaunchPad`