emission state

assertDefaultInitialPoolExists

validateDistributionTarget

validateDistributionTarget returns an error if the given distribution target is invalid.

assertValidDistributionTarget

assertValidDistributionTarget panics if the given distribution target is invalid. Kept for internal invariant checks.

assertValidDistributionPct

assertValidDistributionPct ensures the sum of all distribution percentages equals 10000 (100%). Panics if the sum does not equal exactly 10000 basis points.

LIQUIDITY_STAKER

DEVOPS

COMMUNITY_POOL

GOV_STAKER

distributionBpsPct

distributedToStaker

// can be cleared by staker contract

distributedToDevOps

distributedToCommunityPool

distributedToGovStaker

// can be cleared by governance staker

accuDistributedToStaker

accuDistributedToDevOps

accuDistributedToCommunityPool

accuDistributedToGovStaker

init.17

ChangeDistributionPct

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: ChangeDistributionPct( 7000, // 70% to liquidity stakers 2000, // 20% to devops 1000, // 10% to community pool 0, // 0% to governance stakers ) Only callable by admin or governance.

changeDistributionPcts

changeDistributionPcts updates the distribution percentages for all targets.

calculateDistributableAmounts

calculateAmount

calculateAmount converts basis points to actual token amount.

applyDistribution

transferToTarget

GetDistributionBpsPct

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.

GetDistributedToStaker

GetDistributedToStaker returns the pending GNS amount allocated to liquidity stakers. Returns: - amount: pending liquidity-staker allocation in GNS base units since the last clear.

GetDistributedToDevOps

GetDistributedToDevOps returns the GNS amount currently accumulated for DevOps. Returns: - amount: accumulated DevOps allocation in GNS base units.

GetDistributedToCommunityPool

GetDistributedToCommunityPool returns the GNS amount currently accumulated for the community pool. Returns: - amount: accumulated community-pool allocation in GNS base units.

GetDistributedToGovStaker

GetDistributedToGovStaker returns the pending GNS amount allocated to governance stakers. Returns: - amount: pending governance-staker allocation in GNS base units since the last clear.

AccumulateDistributedInfo

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.

GetAccuDistributedToStaker

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.

GetAccuDistributedToDevOps

GetAccuDistributedToDevOps returns the total historical GNS amount allocated to DevOps. Returns: - amount: cumulative DevOps allocation in GNS base units; this value is not cleared.

GetAccuDistributedToCommunityPool

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.

GetAccuDistributedToGovStaker

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.

GetEmissionAmountPerSecondBy

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.

GetStakerEmissionAmountPerSecond

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

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.

ClearDistributedToStaker

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.

ClearDistributedToGovStaker

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.

setDistributionBpsPct

setDistributionBpsPct changes percentage of each target for how much GNS it will get by emission. Creates new map if nil.

targetToStr

targetToStr converts target constant to string representation.

totalDistributionDuration

// 12 years

DefaultInitialPoolTierPath

leftGNSAmount

lastExecutedTimestamp

emissionAddr

distributionStartTimestamp

onDistributionPctChangeCallback

defaultInitialPoolChecker

init.49

setLeftGNSAmount

setLeftGNSAmount updates the undistributed GNS token amount

setLastExecutedTimestamp

setLastExecutedTimestamp updates the timestamp of the last emission distribution execution.

MintAndDistributeGns

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.

SetDistributionStartTime

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

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.

SetDefaultInitialPoolChecker

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.

errInvalidEmissionTarget

errInvalidEmissionPct

errDuplicateTarget

errDistributionAddressNotFound

errInvalidEmissionStart

makeErrorWithDetails

makeErrorWithDetails creates a new error by combining a base error with additional details.

GetLeftGNSAmount

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

GetDistributionStartTimestamp

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

GetLastExecutedTimestamp

GetLastExecutedTimestamp returns the timestamp of the last emission distribution execution. Returns: - timestamp: last execution timestamp

GetAllDistributionBpsPct

GetAllDistributionBpsPct returns all distribution percentages in basis points. Returns: - percentages: map of target to percentage in basis points

GetTotalAccuDistributed

GetTotalAccuDistributed returns the total accumulated distributed GNS amount. Returns: - amount: total accumulated distributed GNS

GetTotalDistributed

GetTotalDistributed returns the total pending distributed GNS amount. Returns: - amount: total pending distributed GNS

GetDistributionEndTimestamp

GetDistributionEndTimestamp returns the timestamp when emission distribution ends. Returns: - timestamp: distribution end timestamp, or 0 if not started

GetDistributableAmount

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

gnsDisplayScale

Render

Render returns the current GNS emission and distribution state.

formatEmissionTimestamp

formatGnsAmount

formatDistributionPercent

zeroPadUnsigned