gns state

SECONDS_IN_YEAR

HALVING_START_YEAR

HALVING_END_YEAR

halvingAmountsPerYear

MUST BE IMMUTABLE, DO NOT MODIFY. Annual halving amount - maximum issuance per year

InitEmissionState

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.

emissionState

init.6

EmissionState

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

NewEmissionState

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.

getEmissionState

getEmissionState returns the singleton emission state instance.

errInvalidYear

errTooManyEmission

errInvalidEmissionAmount

makeErrorWithDetails

GetMaxEmissionAmount

GetMaxEmissionAmount returns the configured lifetime GNS emission cap in base units. Returns: - maxAmount: maximum number of GNS base units available for emission

GetMaximumSupply

GetMaximumSupply returns the maximum possible GNS token supply in base units. Returns: - maximumSupply: configured total supply cap, including the initial mint and emissions

GetInitialMintAmount

GetInitialMintAmount returns the initial GNS allocation minted before emissions. Returns: - initialAmount: number of GNS base units in the initial mint

IsEmissionInitialized

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

IsEmissionActive

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

IsEmissionEnded

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

GetHalvingYear

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

GetCurrentYear

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

GetEmissionAmountPerSecondInRange

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

GetEmissionAmountPerSecondByTimestamp

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

GetEmissionLeftAmountByTimestamp

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

GetEmissionAccumulatedAmountByTimestamp

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

GetHalvingYearStartTimestamp

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

GetHalvingYearEndTimestamp

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

GetHalvingYearMaxAmount

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

GetHalvingYearLeftAmount

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

GetHalvingYearMintedAmount

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

GetAmountPerSecondPerHalvingYear

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

GetHalvingAmountsPerYear

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

GetEmissionCreatedHeight

GetEmissionCreatedHeight returns the blockchain height recorded when the emission schedule was created. Returns: - height: schedule creation height, or the uninitialized state's stored value

GetEmissionStartTimestamp

GetEmissionStartTimestamp returns the inclusive Unix timestamp at which the configured emission schedule begins. Returns: - timestamp: schedule start timestamp

GetEmissionEndTimestamp

GetEmissionEndTimestamp returns the inclusive Unix timestamp at which the configured emission schedule ends. Returns: - timestamp: schedule end timestamp

GetHalvingYearInfo

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

GetHalvingInfo

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

CalculateMintGnsAmount

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

tokenID

MAXIMUM_SUPPLY

INITIAL_MINT_AMOUNT

MAX_EMISSION_AMOUNT

// MAXIMUM\_SUPPLY - INITIAL\_MINT\_AMOUNT

token

privateLedger

userTeller

leftEmissionAmount

// amount of GNS can be minted for emission

mintedEmissionAmount

// amount of GNS that has been minted for emission

lastMintedTimestamp

// last block time that gns was minted for emission

init.49

Name

Name returns the name of the GNS token. Returns: - name: token name

Symbol

Symbol returns the symbol of the GNS token. Returns: - symbol: token symbol

Decimals

Decimals returns the number of decimal places for GNS token. Returns: - decimals: number of decimal places

TotalSupply

TotalSupply returns the total supply of GNS tokens in circulation. Returns: - supply: total token supply

KnownAccounts

KnownAccounts returns the number of addresses that have held GNS. Returns: - count: number of known accounts

BalanceOf

BalanceOf returns the GNS balance of a specific address. Parameters: - owner: address to check balance for Returns: - balance: token balance

Allowance

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

MintGns

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.

Transfer

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

Approve

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

TransferFrom

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

Render

Render returns token information for web interface. Parameters: - path: render path for specific views Returns: - output: formatted token information

checkErr

checkErr panics if error is not nil.

calculateAmountToMint

calculateAmountToMint calculates and allocates GNS tokens to mint for given timestamp range. This function has side effects: it updates the accumulated and remaining amounts for each halving year in the emission state.

LastMintedTimestamp

LastMintedTimestamp returns the timestamp of the last GNS emission mint. Returns: - timestamp: last minted timestamp

LeftEmissionAmount

LeftEmissionAmount returns the remaining GNS tokens available for emission. Returns: - amount: remaining emission amount

MintedEmissionAmount

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

setLastMintedTimestamp

setLastMintedTimestamp sets the timestamp of the last emission mint.

setLeftEmissionAmount

setLeftEmissionAmount sets the remaining emission amount.

setMintedEmissionAmount

setMintedEmissionAmount sets the total minted emission amount.

HalvingData

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

NewHalvingData

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

setupPreMint

setupPreMint mints the initial GNS supply to fixed recipients at realm init. Generated by scripts/patch-gns-premint.sh from GNS\_PRE\_MINT. It replaces the upstream role-based recipient (rbac ADMIN) with the addresses listed below.

validYear

validYear validates that year is within halving period range (1-12). Returns error if year is outside the valid range.

validEmissionAmount

validEmissionAmount validates that the emission amount does not exceed maximum. Returns error if minting the amount would exceed MAX\_EMISSION\_AMOUNT.

i64Min

i64Min returns the smaller of two int64 values.