Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

gns package

Overview

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.

Functions

Allowance

func Allowance(owner, spender address) int64

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

Params

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.Allowance(,)"

Result

Approve

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

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

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "Approve" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "Approve" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

BalanceOf

func BalanceOf(owner address) int64

BalanceOf returns the GNS balance of a specific address.

Parameters:

  • owner: address to check balance for

Returns:

  • balance: token balance

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.BalanceOf()"

Result

CalculateMintGnsAmount

func CalculateMintGnsAmount(fromTimestamp, toTimestamp int64) int64

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

Params

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.CalculateMintGnsAmount(,)"

Result

Decimals

func Decimals() int

Decimals returns the number of decimal places for GNS token.

Returns:

  • decimals: number of decimal places

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.Decimals()"

Result

GetAmountPerSecondPerHalvingYear

func GetAmountPerSecondPerHalvingYear(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetAmountPerSecondPerHalvingYear()"

Result

GetCurrentYear

func GetCurrentYear() int64

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetCurrentYear()"

Result

GetEmissionAccumulatedAmountByTimestamp

func GetEmissionAccumulatedAmountByTimestamp(timestamp int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionAccumulatedAmountByTimestamp()"

Result

GetEmissionAmountPerSecondByTimestamp

func GetEmissionAmountPerSecondByTimestamp(timestamp int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionAmountPerSecondByTimestamp()"

Result

GetEmissionAmountPerSecondInRange

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

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

Params

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionAmountPerSecondInRange(,)"

Result

GetEmissionCreatedHeight

func GetEmissionCreatedHeight() int64

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

Returns:

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionCreatedHeight()"

Result

GetEmissionEndTimestamp

func GetEmissionEndTimestamp() int64

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

Returns:

  • timestamp: schedule end timestamp

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionEndTimestamp()"

Result

GetEmissionLeftAmountByTimestamp

func GetEmissionLeftAmountByTimestamp(timestamp int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionLeftAmountByTimestamp()"

Result

GetEmissionStartTimestamp

func GetEmissionStartTimestamp() int64

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

Returns:

  • timestamp: schedule start timestamp

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetEmissionStartTimestamp()"

Result

GetHalvingAmountsPerYear

func GetHalvingAmountsPerYear(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingAmountsPerYear()"

Result

GetHalvingYear

func GetHalvingYear(timestamp int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYear()"

Result

GetHalvingYearEndTimestamp

func GetHalvingYearEndTimestamp(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYearEndTimestamp()"

Result

GetHalvingYearInfo

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

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYearInfo()"

Result

GetHalvingYearLeftAmount

func GetHalvingYearLeftAmount(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYearLeftAmount()"

Result

GetHalvingYearMaxAmount

func GetHalvingYearMaxAmount(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYearMaxAmount()"

Result

GetHalvingYearMintedAmount

func GetHalvingYearMintedAmount(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYearMintedAmount()"

Result

GetHalvingYearStartTimestamp

func GetHalvingYearStartTimestamp(year int64) int64

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingYearStartTimestamp()"

Result

GetInitialMintAmount

func GetInitialMintAmount() int64

GetInitialMintAmount returns the initial GNS allocation minted before emissions.

Returns:

  • initialAmount: number of GNS base units in the initial mint

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetInitialMintAmount()"

Result

GetMaxEmissionAmount

func GetMaxEmissionAmount() int64

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

Returns:

  • maxAmount: maximum number of GNS base units available for emission

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetMaxEmissionAmount()"

Result

GetMaximumSupply

func GetMaximumSupply() int64

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

Returns:

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetMaximumSupply()"

Result

InitEmissionState

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

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.

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "InitEmissionState" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "InitEmissionState" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

IsEmissionActive

func IsEmissionActive() bool

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.IsEmissionActive()"

Result

IsEmissionEnded

func IsEmissionEnded() bool

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.IsEmissionEnded()"

Result

IsEmissionInitialized

func IsEmissionInitialized() bool

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.IsEmissionInitialized()"

Result

KnownAccounts

func KnownAccounts() int

KnownAccounts returns the number of addresses that have held GNS.

Returns:

  • count: number of known accounts

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.KnownAccounts()"

Result

LastMintedTimestamp

func LastMintedTimestamp() int64

LastMintedTimestamp returns the timestamp of the last GNS emission mint.

Returns:

  • timestamp: last minted timestamp

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.LastMintedTimestamp()"

Result

LeftEmissionAmount

func LeftEmissionAmount() int64

LeftEmissionAmount returns the remaining GNS tokens available for emission.

Returns:

  • amount: remaining emission amount

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.LeftEmissionAmount()"

Result

MintGns

func MintGns(cur realm, address address) int64

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.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "MintGns" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "MintGns" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

MintedEmissionAmount

func MintedEmissionAmount() int64

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

Returns:

  • amount: total minted emission amount

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.MintedEmissionAmount()"

Result

Name

func Name() string

Name returns the name of the GNS token.

Returns:

  • name: token name

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.Name()"

Result

Render

func Render(path string) string

Render returns token information for web interface.

Parameters:

  • path: render path for specific views

Returns:

  • output: formatted token information

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.Render()"

Result

Symbol

func Symbol() string

Symbol returns the symbol of the GNS token.

Returns:

  • symbol: token symbol

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.Symbol()"

Result

TotalSupply

func TotalSupply() int64

TotalSupply returns the total supply of GNS tokens in circulation.

Returns:

  • supply: total token supply

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.TotalSupply()"

Result

Transfer

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

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

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "Transfer" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "Transfer" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

TransferFrom

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

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

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "TransferFrom" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/gns" -func "TransferFrom" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

NewEmissionState

func NewEmissionState(createdHeight int64, startTimestamp int64) *EmissionState

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.

Params

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.NewEmissionState(,)"

Result

GetHalvingInfo

func GetHalvingInfo() *HalvingData

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

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.GetHalvingInfo()"

Result

NewHalvingData

func NewHalvingData(startTimestamp int64) *HalvingData

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

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/gns.NewHalvingData()"

Result