gns source realm

Package gns implements the GNS governance and utility token for GnoSwap.

GNS

GnoSwap governance and utility token.

Overview

GNS is the native governance token of GnoSwap, featuring a deflationary emission schedule with halvings every 2 years over 12 years total.

Token Economics

Symbol: GNS
Decimals: 6
Max Supply: 1,000,000,000 GNS
Initial Mint: 100,000,000 GNS, pre-minted to the configured ADMIN role address during GNS realm initialization
Total Emission: 900,000,000 GNS over 12 years

Emission Schedule

Years	Annual Emission	Rate
1-2	225,000,000	100%
3-4	112,500,000	50%
5-6	56,250,000	25%
7-8	28,125,000	12.5%
9-12	14,062,500	6.25%

Core Functions

`Transfer`

Transfers tokens between addresses.

`TransferFrom`

Transfers with allowance.

`Approve`

Approves spending allowance.

`InitEmissionState`

Initializes the emission schedule with start height and timestamp. Sets up the 12-year emission schedule with halving periods. Only callable by emission contract.

`MintGns`

Mints new tokens per emission schedule. Only callable by emission contract. Calculates tokens to mint based on elapsed time and updates halving year state.

Usage

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

1// Transfer tokens
2Transfer(cross(cur), to, amount)
3
4// Approve and transfer
5Approve(cross(cur), spender, amount)
6TransferFrom(cross(cur), from, to, amount)
7
8// Mint per emission schedule (called by emission contract)
9MintGns(cross(cur), recipientAddress)

Distribution

See emission contract for distribution details.

Package gns implements the GNS governance and utility token for GnoSwap.

GNS is a GRC20-compliant token with a deflationary emission schedule. The emission follows a 12-year schedule with halving every 2 years:

Years 1-2: 225,000,000 GNS per year (100%)
Years 3-4: 112,500,000 GNS per year (50%)
Years 5-6: 56,250,000 GNS per year (25%)
Years 7-8: 28,125,000 GNS per year (12.5%)
Years 9-12: 14,062,500 GNS per year (6.25%)

Token Economics:

Maximum Supply: 1,000,000,000 GNS
Initial Mint: 100,000,000 GNS
Total Emission: 900,000,000 GNS

Key Functions:

InitEmissionState: Initializes emission schedule (emission contract only)
MintGns: Mints tokens per emission schedule (emission contract only)
Transfer/TransferFrom/Approve: Standard GRC20 operations

The emission state tracks accumulated and remaining amounts per halving year, ensuring precise token distribution according to the schedule.

1const (
2	SECONDS_IN_YEAR = 31536000
3
4	HALVING_START_YEAR = int64(1)
5	HALVING_END_YEAR   = int64(12)
6)

source

1const (
2	tokenID             = 0
3	MAXIMUM_SUPPLY      = int64(1_000_000_000_000_000)
4	INITIAL_MINT_AMOUNT = int64(100_000_000_000_000)
5	MAX_EMISSION_AMOUNT = int64(900_000_000_000_000) // MAXIMUM_SUPPLY - INITIAL_MINT_AMOUNT
6)

source

1func Allowance(owner, spender address) int64

source

Allowance returns the amount of GNS that a spender is allowed to transfer from an owner.

Parameters:

owner: token owner address
spender: spender address

Returns:

allowance: approved amount

1func Approve(cur realm, spender address, amount int64)

source

Approve allows spender to transfer GNS tokens from caller's account.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
spender: address authorized to spend
amount: maximum number of GNS base units spender can transfer

1func BalanceOf(owner address) int64

source

BalanceOf returns the GNS balance of a specific address.

Parameters:

owner: address to check balance for

Returns:

balance: token balance

1func CalculateMintGnsAmount(fromTimestamp, toTimestamp int64) int64

source

CalculateMintGnsAmount calculates the GNS base units allocated over an inclusive timestamp range without mutating the live emission state.

Parameters:

fromTimestamp: inclusive Unix timestamp at which allocation begins
toTimestamp: inclusive Unix timestamp at which allocation ends

Returns:

amount: GNS base units allocated in the overlapping schedule interval, or 0 for an invalid or non-overlapping range

1func Decimals() int

source

Decimals returns the number of decimal places for GNS token.

Returns:

decimals: number of decimal places

1func GetAmountPerSecondPerHalvingYear(year int64) int64

source

GetAmountPerSecondPerHalvingYear returns the configured GNS emission rate for a halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

amountPerSecond: GNS base units emitted per second in year, or 0 when year is invalid

1func GetCurrentYear() int64

source

GetCurrentYear returns the halving year containing the current Unix time.

Returns:

year: current halving year in [1, 12], or 0 when the current time is outside the schedule

1func GetEmissionAccumulatedAmountByTimestamp(timestamp int64) int64

source

GetEmissionAccumulatedAmountByTimestamp returns the stored minted allocation for the halving year containing timestamp.

Parameters:

timestamp: Unix timestamp used to select a halving year

Returns:

amount: minted GNS base units recorded for that halving year, or 0 outside the schedule

1func GetEmissionAmountPerSecondByTimestamp(timestamp int64) int64

source

GetEmissionAmountPerSecondByTimestamp returns the configured GNS emission rate for the halving year containing timestamp.

Parameters:

timestamp: Unix timestamp whose schedule rate is queried

Returns:

amount: GNS base units emitted per second for timestamp's halving year, or 0 outside the schedule

1func GetEmissionAmountPerSecondInRange(fromTime, toTime int64) ([]int64, []int64)

source

GetEmissionAmountPerSecondInRange returns paired emission-rate change points whose timestamps fall within the requested range.

Parameters:

fromTime: inclusive Unix timestamp lower bound
toTime: inclusive Unix timestamp upper bound; a lower value yields nil slices

Returns:

timestamps: schedule timestamps in the range where the rate changes, including the post-end zero-rate point when applicable
amounts: GNS base units emitted per second at each corresponding timestamp; same length and order as timestamps

1func GetEmissionCreatedHeight() int64

source

GetEmissionCreatedHeight returns the blockchain height recorded when the emission schedule was created.

Returns:

height: schedule creation height, or the uninitialized state's stored value

1func GetEmissionEndTimestamp() int64

source

GetEmissionEndTimestamp returns the inclusive Unix timestamp at which the configured emission schedule ends.

Returns:

timestamp: schedule end timestamp

1func GetEmissionLeftAmountByTimestamp(timestamp int64) int64

source

GetEmissionLeftAmountByTimestamp returns the stored unminted allocation for the halving year containing timestamp.

Parameters:

timestamp: Unix timestamp used to select a halving year

Returns:

amount: remaining GNS base units recorded for that halving year, or 0 outside the schedule

1func GetEmissionStartTimestamp() int64

source

GetEmissionStartTimestamp returns the inclusive Unix timestamp at which the configured emission schedule begins.

Returns:

timestamp: schedule start timestamp

1func GetHalvingAmountsPerYear(year int64) int64

source

GetHalvingAmountsPerYear returns the total GNS allocation configured for a halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

amount: total GNS base units allocated to year, or 0 when year is invalid

1func GetHalvingYear(timestamp int64) int64

source

GetHalvingYear returns the halving year containing timestamp.

Parameters:

timestamp: Unix timestamp to classify against the inclusive 12-year emission schedule

Returns:

year: halving year in [1, 12], or 0 when timestamp is before the start or after the end

1func GetHalvingYearEndTimestamp(year int64) int64

source

GetHalvingYearEndTimestamp returns the inclusive end Unix timestamp for a configured halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

timestamp: inclusive end timestamp for year, or 0 when year is invalid

1func GetHalvingYearInfo(timestamp int64) (int64, int64, int64)

source

GetHalvingYearInfo returns the configured halving interval containing timestamp.

Parameters:

timestamp: Unix timestamp to classify against the inclusive emission schedule

Returns:

year: halving year in [1, 12], or 0 outside the schedule
startTimestamp: inclusive start timestamp of year, or 0 when timestamp is outside the schedule
endTimestamp: inclusive end timestamp of year, or 0 when timestamp is outside the schedule

1func GetHalvingYearLeftAmount(year int64) int64

source

GetHalvingYearLeftAmount returns the remaining GNS allocation recorded for a halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

amount: unminted GNS base units for year, or 0 when year is invalid

1func GetHalvingYearMaxAmount(year int64) int64

source

GetHalvingYearMaxAmount returns the maximum GNS allocation for a halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

amount: maximum GNS base units allocated to year, or 0 when year is invalid

1func GetHalvingYearMintedAmount(year int64) int64

source

GetHalvingYearMintedAmount returns the minted GNS allocation recorded for a halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

amount: minted GNS base units for year, or 0 when year is invalid

1func GetHalvingYearStartTimestamp(year int64) int64

source

GetHalvingYearStartTimestamp returns the inclusive start Unix timestamp for a configured halving year.

Parameters:

year: halving year number in [1, 12]

Returns:

timestamp: inclusive start timestamp for year, or 0 when year is invalid

1func GetInitialMintAmount() int64

source

GetInitialMintAmount returns the initial GNS allocation minted before emissions.

Returns:

initialAmount: number of GNS base units in the initial mint

1func GetMaxEmissionAmount() int64

source

GetMaxEmissionAmount returns the configured lifetime GNS emission cap in base units.

Returns:

maxAmount: maximum number of GNS base units available for emission

1func GetMaximumSupply() int64

source

GetMaximumSupply returns the maximum possible GNS token supply in base units.

Returns:

maximumSupply: configured total supply cap, including the initial mint and emissions

1func InitEmissionState(cur realm, createdHeight int64, startTimestamp int64)

source

InitEmissionState initializes the emission schedule. It creates the 12-year schedule with two-year halving periods.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
createdHeight: block height when the schedule is initialized
startTimestamp: Unix timestamp when emission begins

Only callable by the emission contract.

1func IsEmissionActive() bool

source

IsEmissionActive reports whether emission is initialized and the current Unix time lies within the inclusive emission schedule.

Returns:

active: true during the configured schedule, including its endpoints; false otherwise

1func IsEmissionEnded() bool

source

IsEmissionEnded reports whether the current Unix time is after the emission end timestamp.

Returns:

ended: true after the configured schedule's end; false at or before that timestamp

1func IsEmissionInitialized() bool

source

IsEmissionInitialized reports whether the emission state has non-zero creation height and start timestamp.

Returns:

initialized: true when both initialization fields are set; false otherwise

1func KnownAccounts() int

source

KnownAccounts returns the number of addresses that have held GNS.

Returns:

count: number of known accounts

1func LastMintedTimestamp() int64

source

LastMintedTimestamp returns the timestamp of the last GNS emission mint.

Returns:

timestamp: last minted timestamp

1func LeftEmissionAmount() int64

source

LeftEmissionAmount returns the remaining GNS tokens available for emission.

Returns:

amount: remaining emission amount

1func MintGns(cur realm, address address) int64

source

MintGns mints new GNS tokens according to the emission schedule.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
address: recipient address for minted tokens

Returns:

amount: GNS minted for the current timestamp; zero when emission is already processed for that timestamp or the schedule has ended

Only callable by emission contract.

Note: Halt check is performed by the caller (emission.MintAndDistributeGns) to allow graceful handling. This function assumes caller has already verified halt status before invoking.

1func MintedEmissionAmount() int64

source

MintedEmissionAmount returns the total GNS tokens minted through emission, excluding the initial mint amount.

Returns:

amount: total minted emission amount

1func Name() string

source

Name returns the name of the GNS token.

Returns:

name: token name

1func Render(path string) string

source

Render returns token information for web interface.

Parameters:

path: render path for specific views

Returns:

output: formatted token information

1func Symbol() string

source

Symbol returns the symbol of the GNS token.

Returns:

symbol: token symbol

1func TotalSupply() int64

source

TotalSupply returns the total supply of GNS tokens in circulation.

Returns:

supply: total token supply

1func Transfer(cur realm, to address, amount int64)

source

Transfer transfers GNS tokens from caller to recipient.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
to: recipient address
amount: number of GNS base units to transfer

1func TransferFrom(cur realm, from, to address, amount int64)

source

TransferFrom transfers GNS tokens on behalf of owner.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
from: token owner address
to: recipient address
amount: number of GNS base units to transfer

1func NewEmissionState(createdHeight int64, startTimestamp int64) *EmissionState

source

NewEmissionState creates an emission state and its 12-year halving schedule.

Parameters:

createdHeight: blockchain height recorded as the schedule's creation height.
startTimestamp: Unix timestamp at which the first halving year begins.

Returns:

state: newly allocated emission state with an end timestamp and initialized halving data.

1func GetHalvingInfo() *HalvingData

source

GetHalvingInfo returns an independent copy of the configured 12-year halving schedule.

Returns:

halvingData: deep copy of schedule timestamps, allocations, minted amounts, remaining amounts, and rates

1func NewHalvingData(startTimestamp int64) *HalvingData

source

NewHalvingData creates a 12-year HalvingData emission schedule starting at startTimestamp. Each year receives configured timestamps, allocation, zero minted amount, remaining allocation, and an integer-truncated per-second rate.

Parameters:

startTimestamp: Unix timestamp at which halving year 1 begins

Returns:

halvingData: initialized schedule with years [1, 12] and their derived values

1type EmissionState struct {
2	createdHeight  int64
3	startTimestamp int64
4	endTimestamp   int64
5	halvingData    *HalvingData
6}

source

EmissionState manages emission state and halving data. Tracks emission timing, status, and halving year information for 12-year schedule.

1func (e *EmissionState) Clone() *EmissionState

source

Clone returns a deep copy of the emission state, including independent halving data.

Returns:

clone: independent EmissionState copy with the same schedule values.

1type HalvingData struct {
2	startTimestamps []int64
3	endTimestamps   []int64
4	maxAmount       []int64
5	leftAmount      []int64
6	mintedAmount    []int64
7	amountPerSecond []int64
8}

source

HalvingData stores emission data for each halving period. Contains timestamps, amounts, and rates for the 12-year emission schedule.

1func (h *HalvingData) Clone() *HalvingData

source

Clone creates a deep copy of all halving schedule slices.

Returns:

halvingData: independent copy of timestamps, allocations, minted amounts, remaining amounts, and rates

Readme View source

GNS

Overview

Token Economics

Emission Schedule

Core Functions

Transfer

TransferFrom

Approve

InitEmissionState

MintGns

Usage

Distribution

Overview

Constants 2

Functions 43

Types 2

Methods on EmissionState

Methods on HalvingData

Imports 11

Source Files 12

`Transfer`

`TransferFrom`

`Approve`

`InitEmissionState`

`MintGns`