emission package

AccumulateDistributedInfo returns the current pending allocation for every distribution target.

Returns:

• toStaker: pending GNS allocation for liquidity stakers, in token base units.
• toDevOps: accumulated GNS allocation for DevOps, in token base units.
• toCommunityPool: accumulated GNS allocation for the community pool, in token base units.
• toGovStaker: pending GNS allocation for governance stakers, in token base units.

ChangeDistributionPct changes distribution percentages for emission targets.

This function redistributes how newly minted GNS tokens are allocated across protocol components. Before applying new ratios, it distributes any accumulated emissions using the current ratios, ensuring emissions are distributed according to the ratios in effect when they were generated. This prevents retroactive application of new ratios to past emissions.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• liquidityStakerPct: percentage for liquidity stakers in basis points (100 = 1%, 10000 = 100%).
• devOpsPct: percentage for DevOps in basis points (100 = 1%, 10000 = 100%).
• communityPoolPct: percentage for the community pool in basis points (100 = 1%, 10000 = 100%).
• govStakerPct: percentage for governance stakers in basis points (100 = 1%, 10000 = 100%).

Requirements:

• Percentages must sum to exactly 10000 (100%).
• Each percentage must be between 0 and 10000 inclusive.

Example:

1ChangeDistributionPct(
2  7000,  // 70% to liquidity stakers
3  2000,  // 20% to devops
4  1000,  // 10% to community pool
5  0,     // 0% to governance stakers
6)

Only callable by admin or governance.

ClearDistributedToGovStaker resets the pending distribution amount for governance stakers.

Parameters:

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

Only callable by governance staker contract.

ClearDistributedToStaker resets the pending distribution amount for liquidity stakers.

Parameters:

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

Only callable by staker contract.

GetAccuDistributedToCommunityPool returns the total historical GNS amount allocated to the community pool.

Returns:

• amount: cumulative community-pool allocation in GNS base units; this value is not cleared.

GetAccuDistributedToDevOps returns the total historical GNS amount allocated to DevOps.

Returns:

• amount: cumulative DevOps allocation in GNS base units; this value is not cleared.

GetAccuDistributedToGovStaker returns the total historical GNS amount allocated to governance stakers.

Returns:

• amount: cumulative governance-staker allocation in GNS base units; this value is not cleared.

GetAccuDistributedToStaker returns the total historical GNS amount allocated to liquidity stakers.

Returns:

• amount: cumulative liquidity-staker allocation in GNS base units; this value is not cleared.

GetAllDistributionBpsPct returns all distribution percentages in basis points.

Returns:

• percentages: map of target to percentage in basis points

GetDistributableAmount returns distribution amounts by target and the remainder. If timestamp is outside the distribution window, it returns an empty map and the full amount as left.

Parameters:

• amount: total amount to distribute
• timestamp: timestamp to check distribution window

Returns:

• distributions: map of target to distribution amount
• remainder: undistributed amount

GetDistributedToCommunityPool returns the GNS amount currently accumulated for the community pool.

Returns:

• amount: accumulated community-pool allocation in GNS base units.

GetDistributedToDevOps returns the GNS amount currently accumulated for DevOps.

Returns:

• amount: accumulated DevOps allocation in GNS base units.

GetDistributedToGovStaker returns the pending GNS amount allocated to governance stakers.

Returns:

• amount: pending governance-staker allocation in GNS base units since the last clear.

GetDistributedToStaker returns the pending GNS amount allocated to liquidity stakers.

Returns:

• amount: pending liquidity-staker allocation in GNS base units since the last clear.

GetDistributionBpsPct returns the configured distribution percentage in basis points for a target.

Parameters:

• target: distribution target constant whose configured share is queried.

Returns:

• pct: configured target share in basis points (100 = 1%, 10000 = 100%).
• error: nil when the target exists in the initialized map; otherwise an invalid-target error.

GetDistributionEndTimestamp returns the timestamp when emission distribution ends.

Returns:

• timestamp: distribution end timestamp, or 0 if not started

GetDistributionStartTimestamp returns the configured emission start timestamp. The value may be in the future; it is 0 when no start timestamp is configured.

Returns:

• timestamp: configured distribution start timestamp, or 0 if unconfigured

GetEmissionAmountPerSecondBy returns the GNS emission rate per second for a timestamp and target share.

Parameters:

• timestamp: Unix timestamp at which the base emission rate is queried.
• distributionPct: target share in basis points, from 0 through 10000 inclusive.

Returns:

• amountPerSecond: target's GNS emission rate in token base units per second, or zero outside the schedule.

GetLastExecutedTimestamp returns the timestamp of the last emission distribution execution.

Returns:

• timestamp: last execution timestamp

GetLeftGNSAmount returns the amount of undistributed GNS tokens from previous distributions.

Returns:

• amount: undistributed GNS amount

GetStakerEmissionAmountPerSecond returns the current GNS emission rate allocated to liquidity stakers.

Returns:

• amountPerSecond: current liquidity-staker emission rate in GNS base units per second.
• error: nil when the liquidity-staker distribution share is available; otherwise the target lookup error.

GetStakerEmissionAmountPerSecondInRange returns liquidity-staker emission-rate change points in a time range.

Parameters:

• start: inclusive start Unix timestamp for the range.
• end: inclusive end Unix timestamp for the range.

Returns:

• timestamps: ordered timestamps in the range where the base emission rate changes.
• amountsPerSecond: liquidity-staker GNS rates corresponding to timestamps, in token base units per second.
• error: nil when the liquidity-staker distribution share is available; otherwise the target lookup error.

GetTotalAccuDistributed returns the total accumulated distributed GNS amount.

Returns:

• amount: total accumulated distributed GNS

GetTotalDistributed returns the total pending distributed GNS amount.

Returns:

• amount: total pending distributed GNS

MintAndDistributeGns mints and distributes GNS tokens according to the emission schedule.

This function is called automatically by protocol contracts during user interactions to trigger periodic GNS emission. It mints new tokens based on elapsed time since last distribution and distributes them to predefined targets (staker, devops, etc.).

Parameters:

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

Returns:

• distributedAmount: total amount of GNS distributed in this call
• success: false only when emission is halted; true when processing completes, even if no tokens are distributed

Note: Distribution only occurs if start timestamp is set and reached. Any undistributed tokens from previous calls are carried forward.

Render returns the current GNS emission and distribution state.

SetDefaultInitialPoolChecker registers the callback that verifies the canonical default initial pool exists before emission starts.

The checker receives the pool path as a parameter so emission owns the canonical path policy (DefaultInitialPoolTierPath) while pool supplies only the generic "does this pool exist" capability.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• checker: nonnil function returning true when the supplied pool path exists; it is called with DefaultInitialPoolTierPath and nil causes a panic.

Only callable by the pool contract.

SetDistributionStartTime sets the timestamp when emission distribution starts.

This function controls when GNS emission begins. Before the configured timestamp is reached, an admin or governance caller may reschedule it. Once the timestamp is reached, the start time is immutable.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• startTimestamp: positive future Unix timestamp when emission should begin.

Requirements:

• Must be called before distribution starts.
• Timestamp must be in the future and leave room for the 12-year schedule.

Effects:

• Sets global distribution start time.
• Initializes GNS emission state if not already started.
• Emission begins automatically when timestamp is reached.

Only callable by admin or governance.

SetOnDistributionPctChangeCallback registers the optional callback invoked when distribution percentages change. A nil callback clears the registration. This allows external contracts (like staker) to update their internal caches when governance or admin changes emission rates.

Parameters:

• cur: Current realm context; callers use cross(cur) when crossing into this realm.
• callback: nil to clear the callback, or a function receiving its callback realm context and the current staker GNS emission rate per second; a nonnil callback is invoked immediately after registration.