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
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.

`Burn`

Burns tokens from supply.

Usage

1// Transfer tokens
2Transfer(to, amount)
3
4// Approve and transfer
5Approve(spender, amount)
6TransferFrom(from, to, amount)
7
8// Mint per emission schedule (called by emission contract)
9MintGns(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)
Burn: Burns tokens from circulation (admin 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.

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

source

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

Parameters:

spender: address authorized to spend
amount: maximum amount spender can transfer

1func BalanceOf(owner address) int64

source

BalanceOf returns the GNS balance of a specific address.

1func CalculateMintGnsAmount(fromTimestamp, toTimestamp int64) int64

source

CalculateMintGnsAmount returns the amount of GNS that would be minted for the given timestamp range.

1func Decimals() int

source

Decimals returns the number of decimal places for GNS token.

1func GetAmountPerSecondPerHalvingYear(year int64) int64

source

GetAmountPerSecondPerHalvingYear returns the emission rate per second for the specified halving year.

1func GetCurrentYear() int64

source

GetCurrentYear returns the current halving year (1-12) or 0 if emission is not active.

1func GetEmissionAccumulatedAmountByTimestamp(timestamp int64) int64

source

GetEmissionAccumulatedAmountByTimestamp returns the accumulated emission amount for the halving year at given timestamp. Returns 0 if timestamp is outside emission period.

1func GetEmissionAmountPerSecondByTimestamp(timestamp int64) int64

source

GetEmissionAmountPerSecondByTimestamp returns the emission rate per second for a given timestamp. Returns 0 if timestamp is outside emission period.

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

source

GetEmissionAmountPerSecondInRange returns halving timestamps and emission rates for the given time range. Returns two slices: timestamps when halving periods start and corresponding emission rates per second.

1func GetEmissionCreatedHeight() int64

source

GetEmissionCreatedHeight returns the block height when emission schedule was created.

1func GetEmissionEndTimestamp() int64

source

GetEmissionEndTimestamp returns the timestamp when emission schedule ends.

1func GetEmissionLeftAmountByTimestamp(timestamp int64) int64

source

GetEmissionLeftAmountByTimestamp returns the remaining emission amount for the halving year at given timestamp. Returns 0 if timestamp is outside emission period.

1func GetEmissionStartTimestamp() int64

source

GetEmissionStartTimestamp returns the timestamp when emission schedule begins.

1func GetHalvingAmountsPerYear(year int64) int64

source

GetHalvingAmountsPerYear returns the total emission amount allocated for the specified year. Returns 0 if year is outside the valid range (1-12).

1func GetHalvingYear(timestamp int64) int64

source

GetHalvingYear returns the halving year (1-12) for a given timestamp.

1func GetHalvingYearAccuAmount(year int64) int64

source

GetHalvingYearAccuAmount returns the accumulated token issuance for the specified halving year.

1func GetHalvingYearEndTimestamp(year int64) int64

source

GetHalvingYearEndTimestamp returns the end timestamp for the specified halving year.

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

source

GetHalvingYearInfo returns the halving year, start timestamp, and end timestamp for a given timestamp. Returns (year, startTimestamp, endTimestamp). Year is 0 if outside emission period.

1func GetHalvingYearLeftAmount(year int64) int64

source

GetHalvingYearLeftAmount returns the remaining token issuance for the specified halving year.

1func GetHalvingYearMaxAmount(year int64) int64

source

GetHalvingYearMaxAmount returns the maximum token issuance for the specified halving year.

1func GetHalvingYearMintAmount(year int64) int64

source

GetHalvingYearMintAmount returns the amount of tokens minted for the specified halving year.

1func GetHalvingYearStartTimestamp(year int64) int64

source

GetHalvingYearStartTimestamp returns the start timestamp for the specified halving year.

1func GetInitialMintAmount() int64

source

GetInitialMintAmount returns the initial amount of gns tokens to be minted.

1func GetMaxEmissionAmount() int64

source

GetMaxEmissionAmount returns the maximum amount of emission allowed.

1func GetMaximumSupply() int64

source

GetMaximumSupply returns the maximum supply of gns tokens.

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

source

InitEmissionState initializes emission schedule with start timestamp. Only callable by emission contract. Sets up 12-year emission schedule with halving every 2 years. Panics if caller is not emission contract.

1func IsEmissionActive() bool

source

IsEmissionActive returns true if emission is currently active based on current time.

1func IsEmissionEnded() bool

source

IsEmissionEnded returns true if emission schedule has completed.

1func IsEmissionInitialized() bool

source

IsEmissionInitialized returns true if emission schedule has been initialized.

1func KnownAccounts() int

source

KnownAccounts returns the number of addresses that have held GNS.

1func LastMintedTimestamp() int64

source

LastMintedTimestamp returns the timestamp of the last GNS emission mint.

1func LeftEmissionAmount() int64

source

LeftEmissionAmount returns the remaining GNS tokens available for emission.

1func MintGns(cur realm, address address) int64

source

MintGns mints new GNS tokens according to the emission schedule.

Parameters:

address: recipient address for minted tokens

Returns amount minted. 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.

1func Name() string

source

Name returns the name of the GNS token.

1func Render(path string) string

source

Render returns token information for web interface.

1func Symbol() string

source

Symbol returns the symbol of the GNS token.

1func TotalSupply() int64

source

TotalSupply returns the total supply of GNS tokens in circulation.

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

source

Transfer transfers GNS tokens from caller to recipient.

Parameters:

to: recipient address
amount: amount to transfer

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

source

TransferFrom transfers GNS tokens on behalf of owner.

Parameters:

from: token owner address
to: recipient address
amount: amount to transfer

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

source

NewEmissionState creates a new EmissionState with specified start height and timestamp. Calculates emission end time based on 12-year schedule and initializes halving data.

1func GetHalvingInfo() *HalvingData

source

GetHalvingInfo returns a clone of the halving data.

1func NewHalvingData(startTimestamp int64) *HalvingData

source

NewHalvingData creates a new HalvingData instance with emission schedule. Initializes 12 years of halving periods with timestamps, amounts, and rates based on startTimestamp.

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

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

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

Readme View source

GNS

Overview

Token Economics

Emission Schedule

Core Functions

Transfer

TransferFrom

Approve

InitEmissionState

MintGns

Burn

Usage

Distribution

Overview

Constants 2

Functions 44

Types 2

Methods on EmissionState

Methods on HalvingData

Imports 12

Source Files 11

`Transfer`

`TransferFrom`

`Approve`

`InitEmissionState`

`MintGns`

`Burn`