governance source realm

Package governance implements proposal lifecycle management and voting. It supports text proposals, parameter changes...

Governance

Decentralized protocol governance via GNS staking and voting.

Overview

Governance enables GNS holders to stake through gov/staker, receive xGNS, delegate voting power, create proposals, and vote on protocol changes. For more details, check out docs.

Configuration

The governance.Config type defines the governance parameters. The values used by a proposal are stored with that proposal; later reconfiguration does not rewrite an existing proposal. The current configuration can be changed through the governance Reconfigure handler. This type can be found in config.gno.

Field	Description	Default
`VotingStartDelay`	Delay before voting starts after proposal creation	1 day
`VotingPeriod`	Duration for collecting votes	7 days
`VotingWeightSmoothingDuration`	Duration used for timestamp-based voting-weight averaging	1 day
`Quorum`	Percentage of total xGNS supply required for proposal passage; total supply includes launchpad-held issuance	50%
`ProposalCreationThreshold`	Minimum xGNS balance required to create a proposal	1,000,000,000 xGNS
`ExecutionDelay`	Waiting period after voting ends before execution	1 day
`ExecutionWindow`	Time window during which an approved proposal can be executed	30 days

All values are configurable; the values above are the defaults in NewDefaultConfig.

Core Mechanics

Staking Flow

1GNS → Delegate → xGNS + delegated voting history → Vote

Delegate GNS through gov/staker to receive an equal amount of xGNS.
Assign voting power to a delegatee (which may be the delegator itself).
Vote on proposals with the delegatee's timestamped delegation weight.
Undelegation removes voting power immediately; the default lockup before collecting GNS is 7 days and is configurable.

Launchpad-backed xGNS is included in total xGNS supply for quorum, but is not an ordinary user delegation record.

Proposal Types

Text: Signal proposals without execution.
CommunityPoolSpend: Treasury disbursements encoded as a community-pool transfer on execution.
ParameterChange: Protocol parameter updates dispatched to registered handlers.

Proposal Lifecycle

Creation

Requires the configured ProposalCreationThreshold xGNS balance (1,000,000,000 xGNS by default).
One active proposal per address.
Valid type and parameters are required. Community-pool spend amounts must be strictly positive, recipients must be valid, and token paths must be registered.
A proposal stores its configuration version, creation timestamp, creation block height, quorum amount, and timestamp used for historical delegation lookup. The block height is metadata; voting-weight lookup is timestamp-based.

Voting

Voting starts after the configured start delay (1 day by default) and runs for the configured voting period (7 days by default).
Weight is the average of the caller's delegation at the proposal's stored snapshot timestamp and at proposal creation time. The snapshot timestamp is createdAt - VotingWeightSmoothingDuration (clamped at zero), and the smoothing duration defaults to 24 hours.
Each address can vote only once on a proposal. Vote returns the applied vote weight as a decimal string.

Execution

A proposal is considered valid and executable when:

The voting period has ended.
Total votes meet the quorum amount computed at creation from the total xGNS supply (including launchpad-held issuance) and the proposal's configured quorum percentage.
YES votes strictly exceed NO votes (ties do not pass).
The configured execution delay (1 day by default) has passed after voting ends.
Execution occurs within the configured execution window (30 days by default).
Text proposals are informational and cannot be executed; anyone can trigger execution of an approved executable proposal.

An approved community-pool spend can still fail at execution if the pool no longer has enough of the registered token.

Technical Details

Vote Weight Calculation

1// `smoothing` is the proposal's configured VotingWeightSmoothingDuration.
2snapshotTime = max(createdAt - smoothing, 0)
3weightAtSnapshot = getDelegationAt(voter, snapshotTime)
4weightAtCreation = getDelegationAt(voter, createdAt)
5voteWeight = (weightAtSnapshot + weightAtCreation) / 2

The lookups read delegation history by Unix timestamp. This is not a block-height snapshot.

Quorum Calculation

1quorumWeight = totalXGnsSupplyAtProposalCreation // includes launchpad-held xGNS
2quorumAmount = quorumWeight * quorumPercent / 100  // quorumPercent defaults to 50

The quorum amount is stored on the proposal and is not recomputed from the proposer's or voters' smoothed voting weight. A proposal passes only when total votes reach quorum and accumulated YES votes strictly exceed accumulated NO votes.

Rewards Distribution

Gov/staker exposes two reward streams:

GNS emission rewards use the emission accumulator and each staker's own stake history.
Protocol-fee rewards are tracked per token and accrual epoch. Each consumed bucket is divided by the total stake in force during that epoch, added to that token's Q128 accumulator, and settled over the staker's stake-event segments. Sub-unit Q128 remainders are retained for later collection.

CollectReward settles the emission stream and every known protocol-fee token. CollectEmissionReward and CollectProtocolFeeReward(tokenPath) are narrower paths; the token-specific protocol-fee path bounds both pending accrual buckets and stake events per call, so remaining work is collected later. Launchpad project wallets use the corresponding launchpad-only entry points.

Usage

These snippets call the public domain proxies from a realm function with a current cur token. Import the corresponding proxy packages and qualify their function names in integrating code.

 1// Through gov/staker: delegate GNS for xGNS voting power.
 2Delegate(cross(cur), delegatee, 1_000_000_000, "g1referrer...")
 3
 4// Create a text or community-pool proposal.
 5ProposeText(cross(cur), "Title", "Description")
 6ProposeCommunityPoolSpend(cross(cur), "Title", "Description", recipient, tokenPath, amount)
 7
 8// A parameter-change execution uses a registered handler. This is one valid
 9// Reconfigure message (all seven parameters are required).
10execution := "gno.land/r/gnoswap/gov/governance*EXE*Reconfigure*EXE*86400,604800,86400,50,1000000000,86400,2592000"
11ProposeParameterChange(cross(cur), "Update config", "Rationale", 1, execution)
12
13// Vote; the return value is the applied weight formatted as a decimal string.
14voteWeight := Vote(cross(cur), proposalId, true) // YES
15
16// Execute after the configured timelock and then, if needed, start undelegation.
17Execute(cross(cur), proposalId)
18Undelegate(cross(cur), delegatee, 250_000_000)
19
20// Collect only after the configured undelegation lockup has expired.
21CollectUndelegatedGns(cross(cur))

Security

Timestamp-based smoothing reduces flash-loan-style voting manipulation; it is not a block snapshot.
Sybil resistance comes from stake-weighted delegation.
The execution delay and window constrain when approved executable proposals can run.
A single active proposal is allowed per proposer address.
Quorum is fixed from the creation-time total xGNS supply, including launchpad-held issuance.
Community-pool balance is checked when the approved transfer executes, not when the proposal is created.

Package governance implements proposal lifecycle management and voting. It supports text proposals, parameter changes, and community-pool spending. Voting uses timestamped delegation history and quorum from total xGNS supply (including launchpad-held xGNS); proposal timing and thresholds are configurable.

1const ErrSpoofedRealm = "rlm does not match the current crossing frame"

source

 1const (
 2	_                ProposalStatusType = iota
 3	StatusUpcoming                      // Proposal created but voting hasn't started yet
 4	StatusActive                        // Proposal is in voting period
 5	StatusPassed                        // Proposal has passed but hasn't been executed (or is text proposal)
 6	StatusRejected                      // Proposal failed to meet voting requirements
 7	StatusExecutable                    // Proposal can be executed (passed and in execution window)
 8	StatusExecuted                      // Proposal has been successfully executed
 9	StatusExpired                       // Proposal execution window has passed
10	StatusCanceled                      // Proposal has been canceled
11)

source

1const (
2	Text               ProposalType = "TEXT"                 // Informational proposals for community discussion
3	CommunityPoolSpend ProposalType = "COMMUNITY_POOL_SPEND" // Proposals to spend community pool funds
4	ParameterChange    ProposalType = "PARAMETER_CHANGE"     // Proposals to modify system parameters
5)

source

 1const (
 2	StoreKeyConfigCounter   StoreKey = "configCounter"   // Config version counter
 3	StoreKeyProposalCounter StoreKey = "proposalCounter" // Proposal ID counter
 4
 5	StoreKeyConfigs StoreKey = "configs" // Configurations BPTree
 6
 7	StoreKeyProposals StoreKey = "proposals" // Proposals BPTree
 8
 9	StoreKeyActiveProposalsBySnapshot StoreKey = "activeProposalsBySnapshot"
10
11	StoreKeyProposalUserVotingInfos StoreKey = "proposalUserVotingInfos" // Proposal voting infos BPTree
12
13	StoreKeyUserProposals StoreKey = "userProposals" // User proposals mapping BPTree
14)

source

1func Cancel(
2	cur realm,
3	proposalId int64,
4) int64

source

Cancel cancels the proposal with the given ID.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
proposalId: The ID of the proposal to cancel.

Returns:

proposalId: The ID of the proposal.

Halt check: reverts while the Governance halt scope is active.

1func Execute(
2	cur realm,
3	proposalId int64,
4) int64

source

Execute executes the given proposal.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
proposalId: The ID of the proposal to execute.

Returns:

proposalId: The ID of the proposal.

Halt check: reverts while the Governance halt scope is active, except for halt-recovery proposals that only target the halt realm.

1func ExistsProposal(proposalID int64) bool

source

ExistsProposal checks whether a proposal is stored.

Parameters:

proposalID: proposal identifier to look up

Returns:

bool: true when proposalID is stored, otherwise false

1func ExistsVotingInfo(proposalID int64, addr address) bool

source

ExistsVotingInfo checks whether voting information exists for a user on a proposal.

Parameters:

proposalID: proposal identifier to inspect
addr: voter address to look up within proposalID

Returns:

bool: true when voting information exists for the proposal and address

1func GetConfigVersionByProposalId(proposalId int64) (int64, error)

source

GetConfigVersionByProposalId returns the config version used by a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

int64: governance configuration version captured by the proposal
error: nil on success, or an error when the proposal does not exist

1func GetCurrentProposalID() int64

source

GetCurrentProposalID returns the current proposal ID counter.

Returns:

int64: current proposal ID counter used for newly created proposals

1func GetCurrentVotingWeightSnapshot() (int64, int64, error)

source

GetCurrentVotingWeightSnapshot returns the current total voting weight and its timestamp anchor computed with the configured smoothing duration.

Returns:

int64: total voting weight averaged over the configured smoothing window
int64: Unix timestamp used as the snapshot history anchor
error: nil on success, or an error when the current configuration or snapshot data cannot be retrieved

1func GetDescriptionByProposalId(proposalId int64) (string, error)

source

GetDescriptionByProposalId returns the description of a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

string: proposal description
error: nil on success, or an error when the proposal does not exist

1func GetImplementationPackagePath() string

source

GetImplementationPackagePath returns the package path of the currently active implementation.

Returns:

packagePath: package path of the active implementation

1func GetLatestConfigVersion() int64

source

GetLatestConfigVersion returns the current governance configuration version.

Returns:

int64: latest configuration version stored by governance

1func GetMaxSmoothingPeriod() int64

source

GetMaxSmoothingPeriod returns the maximum smoothing period for delegation history cleanup.

Returns:

int64: maximum permitted smoothing period in seconds

1func GetNayByProposalId(proposalId int64) (int64, error)

source

GetNayByProposalId returns the no vote weight of a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

int64: total voting weight recorded for no votes
error: nil on success, or an error when the proposal does not exist

1func GetOldestActiveProposalSnapshotTime() (int64, bool, error)

source

GetOldestActiveProposalSnapshotTime returns the oldest active proposal's timestamp anchor. An empty index returns no active proposal; a stale or missing first entry returns an error so cleanup cannot silently skip it.

Returns:

int64: snapshot timestamp of the oldest active proposal, or zero when the index is empty or an error occurs
bool: true when an active proposal was found at the oldest index entry, otherwise false
error: nil for an empty index or active entry, or an error when the entry is missing or inactive

1func GetProposalCreatedAt(proposalId int64) (int64, error)

source

GetProposalCreatedAt returns the creation timestamp of a proposal.

Parameters:

proposalId: proposal identifier to look up

Returns:

int64: Unix timestamp at which the proposal was created
error: nil on success, or an error when the proposal does not exist

1func GetProposalCreatedHeight(proposalId int64) (int64, error)

source

GetProposalCreatedHeight returns the creation block height of a proposal.

Parameters:

proposalId: proposal identifier to look up

Returns:

int64: block height at which the proposal was created
error: nil on success, or an error when the proposal does not exist

1func GetProposalStatusByProposalId(proposalId int64) (string, error)

source

GetProposalStatusByProposalId returns the current status of a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

string: status computed from the proposal and the current Unix time
error: nil on success, or an error when the proposal does not exist

1func GetProposals() *rotree.ReadOnlyTree

source

GetProposals returns a read-only view of every proposal, keyed by the decimal string form of the proposal ID. Callers paginate it themselves through IterateByOffset. Reading an entry yields a clone, so the view cannot mutate realm state.

Returns:

*rotree.ReadOnlyTree: read-only proposal tree keyed by decimal proposal ID

1func GetQuorumAmountByProposalId(proposalId int64) (int64, error)

source

GetQuorumAmountByProposalId returns the quorum requirement for a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

int64: minimum voting weight required for the proposal's quorum
error: nil on success, or an error when the proposal does not exist

1func GetTitleByProposalId(proposalId int64) (string, error)

source

GetTitleByProposalId returns the title of a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

string: proposal title
error: nil on success, or an error when the proposal does not exist

1func GetUserProposals() *rotree.ReadOnlyTree

source

GetUserProposals returns a read-only view of the proposals created per user, keyed by creator address with the creator's proposal IDs as the value. Reading an entry yields a copy of the ID slice, so the view cannot mutate realm state.

Returns:

*rotree.ReadOnlyTree: read-only user-proposal tree keyed by creator address

1func GetVoteStatus(proposalId int64) (quorum, maxVotingWeight, yesWeight, noWeight int64, err error)

source

GetVoteStatus returns the vote status of a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

quorum: minimum vote weight required for the proposal to pass
maxVotingWeight: maximum possible voting weight recorded for the proposal
yesWeight: total weight of yes votes
noWeight: total weight of no votes
err: nil on success, or an error when the proposal does not exist

1func GetVoteWeight(proposalID int64, addr address) (int64, error)

source

GetVoteWeight returns the voting weight of an address for a proposal.

Parameters:

proposalID: proposal identifier to inspect
addr: voter address whose recorded vote weight is requested

Returns:

int64: weight recorded for addr's vote
error: nil on success, or an error when no voting information exists for the proposal and address

1func GetVotedAt(proposalID int64, addr address) (int64, error)

source

GetVotedAt returns the timestamp when an address voted on a proposal.

Parameters:

proposalID: proposal identifier to inspect
addr: voter address whose vote timestamp is requested

Returns:

int64: Unix timestamp recorded for addr's vote
error: nil on success, or an error when no voting information exists for the proposal and address

1func GetVotedHeight(proposalID int64, addr address) (int64, error)

source

GetVotedHeight returns the block height when an address voted on a proposal.

Parameters:

proposalID: proposal identifier to inspect
addr: voter address whose vote height is requested

Returns:

int64: block height recorded for addr's vote
error: nil on success, or an error when no voting information exists for the proposal and address

1func GetVotingInfos(proposalID int64) *rotree.ReadOnlyTree

source

GetVotingInfos returns a read-only view of a proposal's value-backed voting infos, keyed by voter address. Existing proposals have an empty view before the first vote; nil is returned only when the stored voting-info tree is absent.

Parameters:

proposalID: proposal identifier whose voting information is requested

Returns:

*rotree.ReadOnlyTree: read-only voting-info tree keyed by voter address, or nil when no tree is stored

1func GetYeaByProposalId(proposalId int64) (int64, error)

source

GetYeaByProposalId returns the yes vote weight of a proposal.

Parameters:

proposalId: proposal identifier to inspect

Returns:

int64: total voting weight recorded for yes votes
error: nil on success, or an error when the proposal does not exist

1func NewConfigTree() *bptree.BPTree

source

NewConfigTree creates an empty BPTree used to index configuration values by their encoded int64 version.

Returns:

*bptree.BPTree: empty configuration index tree

1func NewProposalTree() *bptree.BPTree

source

NewProposalTree creates an empty B+ tree for proposals keyed by proposal ID.

Returns:

*bptree.BPTree: empty 16-way proposal tree

1func NewProposalUserVotingInfoTree() *bptree.BPTree

source

NewProposalUserVotingInfoTree creates an empty B+ tree mapping proposal IDs to their per-user voting-information trees.

Returns:

*bptree.BPTree: empty 16-way proposal voting-information index tree

1func NewUserProposalTree() *bptree.BPTree

source

NewUserProposalTree creates an empty B+ tree mapping users to proposal IDs.

Returns:

*bptree.BPTree: empty 16-way user-proposal index tree

1func NewVotingInfoTree() *bptree.BPTree

source

NewVotingInfoTree creates an empty B+ tree for per-user voting information.

Returns:

*bptree.BPTree: empty 16-way voting-information tree

1func ProposeCommunityPoolSpend(
2	cur realm,
3	title string,
4	description string,
5	to address,
6	tokenPath string,
7	amount int64,
8) int64

source

ProposeCommunityPoolSpend creates a CommunityPoolSpend proposal with the provided data. The transfer is attempted when an approved proposal executes.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
title: The title of the proposal.
description: The description of the proposal.
to: A valid address to receive the spent token.
tokenPath: A registered token path.
amount: A strictly positive amount in the token's smallest unit.

The community-pool balance is checked at execution, not proposal creation.

Returns:

proposalId: The ID of the proposal.

Halt check: reverts while the Governance halt scope is active.

1func ProposeParameterChange(
2	cur realm,
3	title string,
4	description string,
5	numToExecute int64,
6	executions string,
7) int64

source

ProposeParameterChange creates a ParameterChange proposal with the provided data.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
title: The title of the proposal.
description: The description of the proposal.
numToExecute: The number of changes to execute.
executions: The list of changes to execute.

Returns:

proposalId: The ID of the proposal.

Halt check: reverts while the Governance halt scope is active, except for halt-recovery proposals that only target the halt realm.

1func ProposeText(
2	cur realm,
3	title string,
4	description string,
5) int64

source

ProposeText creates a new text proposal with the provided data.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
title: The title of the proposal.
description: The description of the proposal.

Returns:

proposalId: The ID of the proposal.

Halt check: reverts while the Governance halt scope is active.

 1func Reconfigure(
 2	cur realm,
 3	votingStartDelay int64,
 4	votingPeriod int64,
 5	votingWeightSmoothingDuration int64,
 6	quorum int64,
 7	proposalCreationThreshold int64,
 8	executionDelay int64,
 9	executionWindow int64,
10) int64

source

Reconfigure updates the governance configuration parameters. Only callable by admin or governance.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
votingStartDelay: delay before voting starts (seconds)
votingPeriod: voting duration (seconds)
votingWeightSmoothingDuration: weight smoothing duration (seconds)
quorum: minimum voting weight required (percentage)
proposalCreationThreshold: minimum weight to create proposal
executionDelay: delay before execution (seconds)
executionWindow: execution time window (seconds)

Returns:

int64: new configuration version

Halt check: reverts while the Governance halt scope is active.

1func RegisterInitializer(cur realm, initializer func(_ int, rlm realm, governanceStore IGovernanceStore, stakerAccessor GovStakerAccessor) IGovernance)

source

RegisterInitializer registers a version-specific initializer. Each version (e.g. v1, v2) calls this function from its init body to plug itself into the proxy.

The initializer constructs the version's IGovernance from the supplied IGovernanceStore and GovStakerAccessor. It receives a realm value that resolves to the governance proxy realm — the only address with write permission on the shared KV store — so any per-version store bootstrap performed inside the initializer passes the proxy's authorization check.

Security: Only contracts within the domain path can register initializers. Each package path can only register once to prevent duplicate registrations. Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
initializer: Callback that receives the proxy-authorized realm context, governance store, and staker accessor and returns the versioned implementation.

1func RemoveInactiveProposalFromIndex(cur realm, proposalID int64)

source

RemoveInactiveProposalFromIndex removes an inactive proposal from the timestamp-ordered index without deleting its proposal or voting history. Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
proposalID: Identifier of the inactive proposal to remove from the active index.

Halt check: reverts while the Governance halt scope is active.

1func Render(path string) string

source

Render delegates web rendering to the active implementation.

1func UpgradeImpl(cur realm, targetPackagePath string)

source

UpgradeImpl switches the active governance implementation to a different version. This function allows seamless upgrades from one version to another without data migration or downtime.

Security: Only admin or governance can perform upgrades. The new implementation must have been previously registered via RegisterInitializer. Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
targetPackagePath: Registered implementation package path to activate.

1func Vote(
2	cur realm,
3	proposalId int64,
4	yes bool,
5) string

source

Vote allows a user to vote on a given proposal.

The proposal's timestamp-based smoothing calculation determines the applied weight. A vote cannot be changed after it is recorded.

Parameters:

cur: Current realm context; callers use cross(cur) when crossing into this realm.
proposalId: The ID of the proposal to vote.
yes: The flag to vote as yes or not.

Returns:

voteWeight: The caller's calculated vote weight, formatted as a decimal string.

Halt check: reverts while the Governance halt scope is active, except for halt-recovery proposals that only target the halt realm.

1func GetProposalCommunityPoolSpendInfo(proposalID int64) (*CommunityPoolSpendInfo, error)

source

GetProposalCommunityPoolSpendInfo returns a cloned copy of the community pool spend info for a proposal.

Parameters:

proposalID: proposal identifier to inspect

Returns:

*CommunityPoolSpendInfo: cloned community-pool spend details, or nil when an error occurs
error: nil on success, or an error when the proposal is missing or has no spend data

1func NewCommunityPoolSpendInfo(to address, tokenPath string, amount int64) *CommunityPoolSpendInfo

source

NewCommunityPoolSpendInfo creates community-pool spend data.

Parameters:

to: Recipient address that receives the community-pool transfer.
tokenPath: Registered token path of the asset to transfer.
amount: Transfer amount in the token's smallest unit.

Returns:

*CommunityPoolSpendInfo: spend data containing the recipient, token path, and amount.

1func GetConfig(configVersion int64) (Config, error)

source

GetConfig returns a specific governance configuration by version.

Parameters:

configVersion: configuration version to retrieve

Returns:

Config: configuration stored under configVersion
error: nil on success, or an error when configVersion is not found

1func GetLatestConfig() (Config, error)

source

GetLatestConfig returns the latest governance configuration.

Returns:

Config: latest stored configuration for the current version
error: nil on success, or an error when the current configuration is missing

1func NewConfig(
2	votingStartDelay,
3	votingPeriod,
4	votingWeightSmoothingDuration,
5	quorum,
6	proposalCreationThreshold,
7	executionDelay,
8	executionWindow int64,
9) Config

source

NewConfig constructs a governance configuration from the supplied delays, thresholds, quorum percentage, and execution window.

Parameters:

votingStartDelay: delay from proposal creation until voting opens, in seconds
votingPeriod: duration for which voting remains open, in seconds
votingWeightSmoothingDuration: interval used to smooth delegation weight, in seconds
quorum: required approval percentage of total xGNS supply, from 0 through 100
proposalCreationThreshold: minimum xGNS amount required to create a proposal
executionDelay: delay after voting ends before execution, in seconds
executionWindow: duration after the execution delay during which execution is allowed, in seconds

Returns:

Config: configuration value populated with the supplied governance parameters

1func NewConfigPtr(
2	votingStartDelay,
3	votingPeriod,
4	votingWeightSmoothingDuration,
5	quorum,
6	proposalCreationThreshold,
7	executionDelay,
8	executionWindow int64,
9) *Config

source

NewConfigPtr constructs a Config and returns a pointer to it. The Config is allocated within the governance domain realm, satisfying realm allocation checks for callers (such as tests) that require a *Config value.

Parameters:

votingStartDelay: delay from proposal creation until voting opens, in seconds
votingPeriod: duration for which voting remains open, in seconds
votingWeightSmoothingDuration: interval used to smooth delegation weight, in seconds
quorum: required approval percentage of total xGNS supply, from 0 through 100
proposalCreationThreshold: minimum xGNS amount required to create a proposal
executionDelay: delay after voting ends before execution, in seconds
executionWindow: duration after the execution delay during which execution is allowed, in seconds

Returns:

*Config: pointer to a configuration value populated with the supplied governance parameters

1func NewDefaultConfig() Config

source

NewDefaultConfig returns the governance configuration's built-in defaults: one day before voting, seven days of voting, one day of weight smoothing, 50% quorum, a 1-billion-xGNS creation threshold, one day execution delay, and a 30-day execution window.

Returns:

Config: default governance configuration value

1func NewCounter() *Counter

source

NewCounter creates a new Counter whose current ID is initialized to zero.

Returns:

*Counter: counter initialized with current ID 0

1func GetProposalExecutionInfo(proposalID int64) (*ExecutionInfo, error)

source

GetProposalExecutionInfo returns a cloned copy of the execution info for a proposal.

Parameters:

proposalID: proposal identifier to inspect

Returns:

*ExecutionInfo: cloned parameter-change execution messages and count, or nil when an error occurs
error: nil on success, or an error when the proposal is missing or has no execution data

1func NewExecutionInfo(num int64, msgs []string) *ExecutionInfo

source

NewExecutionInfo creates execution data for a parameter-change proposal.

Parameters:

num: Number of encoded parameter-change messages to execute.
msgs: Encoded parameter-change messages, one message per execution.

Returns:

*ExecutionInfo: execution data containing the declared count and messages.

1func NewGovernanceStore(kvStore store.KVStore) IGovernanceStore

source

NewGovernanceStore creates a governance store backed by the provided KV store. The returned interface is used by governance implementations and upgrades.

Parameters:

kvStore: KV store used for governance counters, trees, and records

Returns:

IGovernanceStore: governance store implementation backed by kvStore

1func NewParameterChangeInfo(pkgPath string, function string, params []string) ParameterChangeInfo

source

NewParameterChangeInfo creates one encoded parameter-change target description.

Parameters:

pkgPath: Package path containing the parameter-change handler.
function: Handler function name to invoke.
params: String arguments passed to the handler in order.

Returns:

ParameterChangeInfo: parameter-change target and its encoded arguments.

 1func NewProposal(
 2	proposalID int64,
 3	status *ProposalStatus,
 4	metadata *ProposalMetadata,
 5	data *ProposalData,
 6	proposerAddress address,
 7	configVersion int64,
 8	snapshotTime int64,
 9	createdHeight int64,
10) *Proposal

source

NewProposal creates a new proposal instance with the supplied identity, lifecycle, metadata, and type-specific data.

Parameters:

proposalID: unique identifier assigned to the proposal
status: initial schedule, action, and voting status
metadata: proposal title and description metadata
data: type-specific proposal data
proposerAddress: address of the proposal creator
configVersion: governance configuration version captured for the proposal
snapshotTime: timestamp anchor for historical voting-weight lookup
createdHeight: block height at which the proposal was created

Returns:

*Proposal: newly initialized proposal containing the supplied fields

1func NewProposalActionStatus(executable bool) *ProposalActionStatus

source

NewProposalActionStatus creates a new action status for a proposal. Initializes the status with default values and the executable flag.

Parameters:

executable: whether this proposal type can be executed

Returns:

*ProposalActionStatus: new action status instance

1func NewProposalData(proposalType ProposalType, communityPoolSpend *CommunityPoolSpendInfo, execution *ExecutionInfo) *ProposalData

source

NewProposalData creates a new proposal data instance with the specified components.

Parameters:

proposalType: type of the proposal
communityPoolSpend: community pool spending information
execution: parameter change execution information

Returns:

*ProposalData: new proposal data instance

1func NewProposalMetadata(title string, description string) *ProposalMetadata

source

NewProposalMetadata creates a new proposal metadata instance with trimmed input.

Parameters:

title: proposal title
description: proposal description

Returns:

*ProposalMetadata: new metadata instance with trimmed whitespace

1func NewProposalScheduleStatus(
2	createTime int64,
3	activeTime int64,
4	votingEndTime int64,
5	executableTime int64,
6	expiredTime int64,
7) *ProposalScheduleStatus

source

NewProposalScheduleStatus creates a proposal schedule from its lifecycle timestamps.

Parameters:

createTime: Unix timestamp when the proposal was created
activeTime: Unix timestamp when voting starts
votingEndTime: Unix timestamp when voting ends
executableTime: Unix timestamp when the execution window starts
expiredTime: Unix timestamp when the execution window closes

Returns:

*ProposalScheduleStatus: schedule containing the supplied lifecycle timestamps

1func NewProposalStatusBy(
2	schedule *ProposalScheduleStatus,
3	actionStatus *ProposalActionStatus,
4	voteStatus *ProposalVoteStatus,
5) *ProposalStatus

source

NewProposalStatusBy combines schedule, action, and vote state into a proposal status.

Parameters:

schedule: time-based lifecycle schedule for the proposal
actionStatus: execution and cancellation state for the proposal
voteStatus: vote tallies and voting requirements for the proposal

Returns:

*ProposalStatus: status object containing the supplied lifecycle components

1func GetProposalTypeByProposalId(proposalId int64) (ProposalType, error)

source

GetProposalTypeByProposalId returns the type of a proposal.

Parameters:

proposalId: proposal identifier to look up

Returns:

ProposalType: type recorded for the proposal
error: nil on success, or an error when the proposal does not exist

1func NewProposalVoteStatus(
2	maxVotingWeight int64,
3	quorumAmount int64,
4) *ProposalVoteStatus

source

NewProposalVoteStatus creates a new vote status for a proposal. Initializes vote tallies to zero and calculates the quorum requirement.

Parameters:

maxVotingWeight: maximum possible voting weight for this proposal
quorumAmount: quorum amount required for passage

Returns:

*ProposalVoteStatus: new vote status instance

1func DefaultVotingInfo() VotingInfo

source

DefaultVotingInfo creates an empty voting information value.

Returns:

VotingInfo: zero-valued voting record with no available weight and no vote recorded

1func NewVotedVotingInfo(availableVoteWeight int64, votedYes bool, votedWeight, votedHeight, votedAt int64) VotingInfo

source

NewVotedVotingInfo creates a voting information value with a recorded vote.

Parameters:

availableVoteWeight: total voting weight available to the user for this proposal
votedYes: true when the recorded vote is yes, false when it is no
votedWeight: voting weight applied to the recorded vote
votedHeight: block height at which the vote was recorded
votedAt: Unix timestamp at which the vote was recorded

Returns:

VotingInfo: voting record populated with the supplied weight, choice, height, and timestamp and marked as voted

1func NewVotingInfo(availableVoteWeight int64) VotingInfo

source

NewVotingInfo creates a new voting information structure for a user. This constructor initializes the voting eligibility based on delegation snapshots.

Parameters:

availableVoteWeight: total voting weight available to this user

Returns:

VotingInfo: newly created voting information value

1type CommunityPoolSpendInfo struct {
2	to        address // Recipient address for token transfer
3	tokenPath string  // Path of the token to transfer
4	amount    int64   // Amount of tokens to transfer
5}

source

CommunityPoolSpendInfo contains information for community pool spending proposals.

1func (i *CommunityPoolSpendInfo) Amount() int64

source

Returns:

int64: transfer amount in the token's smallest unit.

1func (i *CommunityPoolSpendInfo) Clone() *CommunityPoolSpendInfo

source

Clone creates a deep copy of the CommunityPoolSpendInfo. Returns:

*CommunityPoolSpendInfo: independent spend-data copy, or nil when the receiver is nil.

1func (i *CommunityPoolSpendInfo) To() address

source

Example

1Getter methods

Returns:

address: recipient address configured for the community-pool spend.

1func (i *CommunityPoolSpendInfo) TokenPath() string

source

Returns:

string: registered token path configured for the community-pool spend.

 1type Config struct {
 2	// VotingStartDelay is the delay before voting starts after proposal creation (in seconds)
 3	VotingStartDelay int64
 4	// VotingPeriod is the duration during which votes are collected (in seconds)
 5	VotingPeriod int64
 6	// VotingWeightSmoothingDuration is the period over which voting weight is averaged
 7	// for proposal creation and cancellation threshold calculations (in seconds).
 8	VotingWeightSmoothingDuration int64
 9	// Quorum is the percentage of total xGNS supply required for proposal approval.
10	// Total supply includes xGNS held by the launchpad.
11	Quorum int64
12	// ProposalCreationThreshold is the minimum xGNS amount required to create a proposal
13	ProposalCreationThreshold int64
14	// ExecutionDelay is the waiting period after voting ends before a proposal can be executed (in seconds)
15	ExecutionDelay int64
16	// ExecutionWindow is the time window during which an approved proposal can be executed (in seconds)
17	ExecutionWindow int64
18}

source

Config represents the configuration of the governor contract. All parameters can be modified through Reconfigure by admin or governance.

1func (c Config) IsValid(currentTime int64) error

source

IsValid reports whether the configuration's durations, threshold, quorum, and cumulative schedule values satisfy the governance validation constraints.

Parameters:

currentTime: current time value included when checking that the cumulative schedule does not become negative

Returns:

error: nil when all fields and cumulative values are valid; otherwise an error describing the first invalid value

1type Counter struct {
2	id int64
3}

source

Counter manages unique incrementing IDs.

1func (c *Counter) Get() int64

source

Get returns the counter's current ID without changing it.

Returns:

int64: currently stored counter ID

1func (c *Counter) Next() int64

source

Next increments the counter and returns the resulting ID.

Returns:

int64: incremented counter ID after the update

1func (c *Counter) Set(id int64)

source

Set replaces the counter's current ID with id.

Parameters:

id: new current ID to store; the value is not incremented

1type ExecutionInfo struct {
2	num  int64    // Number of parameter changes to execute
3	msgs []string // Execution messages separated by messageSeparator (*GOV*)
4}

source

ExecutionInfo contains information for parameter change execution. Messages are encoded strings that specify function calls and parameters.

1func (i *ExecutionInfo) Clone() *ExecutionInfo

source

Clone creates a deep copy of the ExecutionInfo. Returns:

*ExecutionInfo: independent execution-data copy including a copied message slice, or nil when the receiver is nil.

1func (i *ExecutionInfo) Msgs() []string

source

Returns:

[]string: encoded parameter-change messages in execution order.

1func (i *ExecutionInfo) Num() int64

source

Example

1Getter methods

Returns:

int64: declared number of parameter-change messages.

 1type GovStakerAccessor interface {
 2	// GetTotalDelegationAmountAtSnapshot returns the total delegation amount at a specific snapshot time.
 3	//
 4	// Parameters:
 5	//   - snapshotTime: Unix timestamp at which delegation history is sampled.
 6	//
 7	// Returns:
 8	//   - int64: total delegated amount at snapshotTime.
 9	//   - bool: true when a snapshot value exists at that timestamp.
10	GetTotalDelegationAmountAtSnapshot(snapshotTime int64) (int64, bool)
11
12	// GetUserDelegationAmountAtSnapshot returns the user delegation amount at a specific snapshot time.
13	//
14	// Parameters:
15	//   - userAddr: user address whose delegated amount is sampled.
16	//   - snapshotTime: Unix timestamp at which the user's history is sampled.
17	//
18	// Returns:
19	//   - int64: user's delegated amount at snapshotTime.
20	//   - bool: true when a snapshot value exists for the user and timestamp.
21	GetUserDelegationAmountAtSnapshot(userAddr address, snapshotTime int64) (int64, bool)
22
23	// GetTotalxGnsSupply returns the total xGNS supply used as the quorum base.
24	//
25	// Returns:
26	//   - int64: total xGNS supply used as the governance quorum base.
27	GetTotalxGnsSupply() int64
28}

source

GovStakerAccessor provides an interface for accessing gov staker functionality. This abstraction allows for easier testing by enabling mock implementations.

1type IGovernance interface {
2	IGovernanceManager
3	IGovernanceGetter
4	Render(path string) string
5}

source

  1type IGovernanceGetter interface {
  2	// Store data getters
  3	// GetLatestConfigVersion returns the version number of the current governance configuration.
  4	//
  5	// Returns:
  6	//   - int64: current configuration version used for new proposals.
  7	GetLatestConfigVersion() int64
  8	// GetCurrentProposalID returns the current proposal ID counter value.
  9	//
 10	// Returns:
 11	//   - int64: current proposal identifier counter value.
 12	GetCurrentProposalID() int64
 13	// GetMaxSmoothingPeriod returns the upper bound for the voting-weight smoothing period.
 14	//
 15	// Returns:
 16	//   - int64: fixed maximum smoothing duration of 30 days (2,592,000 seconds).
 17	GetMaxSmoothingPeriod() int64
 18
 19	// Config getters
 20	// GetLatestConfig returns the current governance configuration.
 21	//
 22	// Returns:
 23	//   - Config: latest stored configuration, or a zero configuration when unavailable.
 24	//   - error: nil when found; otherwise an error indicating that the configuration is unavailable.
 25	GetLatestConfig() (Config, error)
 26	// GetConfig returns a governance configuration by version.
 27	//
 28	// Parameters:
 29	//   - configVersion: configuration version to retrieve.
 30	//
 31	// Returns:
 32	//   - Config: configuration stored at the requested version, or a zero configuration when absent.
 33	//   - error: nil when found; otherwise an error identifying the missing version.
 34	GetConfig(configVersion int64) (Config, error)
 35
 36	// GetProposals returns a read-only view of stored proposals keyed by decimal proposal ID.
 37	//
 38	// Returns:
 39	//   - *rotree.ReadOnlyTree: read-only proposal tree with cloned proposal values.
 40	GetProposals() *rotree.ReadOnlyTree
 41	// ExistsProposal reports whether a proposal is stored for an ID.
 42	//
 43	// Parameters:
 44	//   - proposalID: proposal identifier to look up.
 45	//
 46	// Returns:
 47	//   - bool: true when a proposal exists for proposalID.
 48	ExistsProposal(proposalID int64) bool
 49	// GetProposerByProposalId returns the address that created a proposal.
 50	//
 51	// Parameters:
 52	//   - proposalId: proposal identifier to look up.
 53	//
 54	// Returns:
 55	//   - address: proposer address recorded on the proposal.
 56	//   - error: nil when found; otherwise an error indicating the proposal is missing.
 57	GetProposerByProposalId(proposalId int64) (address, error)
 58	// GetProposalTypeByProposalId returns the type discriminator of a proposal.
 59	//
 60	// Parameters:
 61	//   - proposalId: proposal identifier to look up.
 62	//
 63	// Returns:
 64	//   - ProposalType: proposal type stored on the proposal.
 65	//   - error: nil when found; otherwise an error indicating the proposal is missing.
 66	GetProposalTypeByProposalId(proposalId int64) (ProposalType, error)
 67	// GetProposalCreatedAt returns a proposal's creation timestamp.
 68	//
 69	// Parameters:
 70	//   - proposalId: proposal identifier to look up.
 71	//
 72	// Returns:
 73	//   - int64: creation time as a Unix timestamp in seconds.
 74	//   - error: nil when found; otherwise an error indicating the proposal is missing.
 75	GetProposalCreatedAt(proposalId int64) (int64, error)
 76	// GetProposalCreatedHeight returns the block height at which a proposal was created.
 77	//
 78	// Parameters:
 79	//   - proposalId: proposal identifier to look up.
 80	//
 81	// Returns:
 82	//   - int64: creation block height.
 83	//   - error: nil when found; otherwise an error indicating the proposal is missing.
 84	GetProposalCreatedHeight(proposalId int64) (int64, error)
 85	// GetProposalCommunityPoolSpendInfo returns the treasury-transfer payload of a proposal.
 86	//
 87	// Parameters:
 88	//   - proposalID: proposal identifier to look up.
 89	//
 90	// Returns:
 91	//   - *CommunityPoolSpendInfo: spend payload, or nil when the proposal is absent or another type.
 92	//   - error: nil for a community-pool-spend proposal; otherwise a not-found or wrong-type error.
 93	GetProposalCommunityPoolSpendInfo(proposalID int64) (*CommunityPoolSpendInfo, error)
 94	// GetProposalExecutionInfo returns the parameter-execution payload of a proposal.
 95	//
 96	// Parameters:
 97	//   - proposalID: proposal identifier to look up.
 98	//
 99	// Returns:
100	//   - *ExecutionInfo: execution payload, or nil when the proposal is absent or another type.
101	//   - error: nil for a parameter-change proposal; otherwise a not-found or wrong-type error.
102	GetProposalExecutionInfo(proposalID int64) (*ExecutionInfo, error)
103	// GetYeaByProposalId returns the affirmative vote weight recorded on a proposal.
104	//
105	// Parameters:
106	//   - proposalId: proposal identifier to look up.
107	//
108	// Returns:
109	//   - int64: total yes-vote weight.
110	//   - error: nil when found; otherwise an error indicating the proposal is missing.
111	GetYeaByProposalId(proposalId int64) (int64, error)
112	// GetNayByProposalId returns the negative vote weight recorded on a proposal.
113	//
114	// Parameters:
115	//   - proposalId: proposal identifier to look up.
116	//
117	// Returns:
118	//   - int64: total no-vote weight.
119	//   - error: nil when found; otherwise an error indicating the proposal is missing.
120	GetNayByProposalId(proposalId int64) (int64, error)
121	// GetConfigVersionByProposalId returns the configuration version captured by a proposal.
122	//
123	// Parameters:
124	//   - proposalId: proposal identifier to look up.
125	//
126	// Returns:
127	//   - int64: configuration version used to create the proposal.
128	//   - error: nil when found; otherwise an error indicating the proposal is missing.
129	GetConfigVersionByProposalId(proposalId int64) (int64, error)
130	// GetQuorumAmountByProposalId returns the proposal's stored quorum requirement.
131	//
132	// Parameters:
133	//   - proposalId: proposal identifier to look up.
134	//
135	// Returns:
136	//   - int64: minimum vote weight required for quorum.
137	//   - error: nil when found; otherwise an error indicating the proposal is missing.
138	GetQuorumAmountByProposalId(proposalId int64) (int64, error)
139	// GetTitleByProposalId returns a proposal's title.
140	//
141	// Parameters:
142	//   - proposalId: proposal identifier to look up.
143	//
144	// Returns:
145	//   - string: title stored in proposal metadata.
146	//   - error: nil when found; otherwise an error indicating the proposal is missing.
147	GetTitleByProposalId(proposalId int64) (string, error)
148	// GetDescriptionByProposalId returns a proposal's full description.
149	//
150	// Parameters:
151	//   - proposalId: proposal identifier to look up.
152	//
153	// Returns:
154	//   - string: description stored in proposal metadata.
155	//   - error: nil when found; otherwise an error indicating the proposal is missing.
156	GetDescriptionByProposalId(proposalId int64) (string, error)
157	// GetProposalStatusByProposalId returns the current status string for a proposal.
158	//
159	// Parameters:
160	//   - proposalId: proposal identifier to look up.
161	//
162	// Returns:
163	//   - string: status computed from the proposal state and current time.
164	//   - error: nil when found; otherwise an error indicating the proposal is missing.
165	GetProposalStatusByProposalId(proposalId int64) (string, error)
166
167	// Vote getters
168	// GetVoteStatus returns the quorum and vote tallies stored for a proposal.
169	//
170	// Parameters:
171	//   - proposalId: proposal identifier to look up.
172	//
173	// Returns:
174	//   - quorum: minimum vote weight required for quorum.
175	//   - maxVotingWeight: maximum voting weight captured at proposal creation.
176	//   - yesWeight: total affirmative vote weight.
177	//   - noWeight: total negative vote weight.
178	//   - err: nil when found; otherwise an error indicating the proposal is missing.
179	GetVoteStatus(proposalId int64) (quorum, maxVotingWeight, yesWeight, noWeight int64, err error)
180	// GetVotingInfos returns a read-only view of a proposal's voter records.
181	//
182	// Parameters:
183	//   - proposalID: proposal identifier whose voting records should be viewed.
184	//
185	// Returns:
186	//   - *rotree.ReadOnlyTree: read-only voter-info tree, or nil when its stored tree is absent.
187	GetVotingInfos(proposalID int64) *rotree.ReadOnlyTree
188	// ExistsVotingInfo reports whether an address has a voting record for a proposal.
189	//
190	// Parameters:
191	//   - proposalID: proposal identifier to inspect.
192	//   - addr: voter address to look up.
193	//
194	// Returns:
195	//   - bool: true when a voting record exists for the proposal and address.
196	ExistsVotingInfo(proposalID int64, addr address) bool
197	// GetVoteWeight returns the recorded voting weight for an address.
198	//
199	// Parameters:
200	//   - proposalID: proposal identifier to inspect.
201	//   - addr: voter address to look up.
202	//
203	// Returns:
204	//   - int64: weight applied to the address's vote.
205	//   - error: nil when a voting record exists; otherwise an error identifying the missing record.
206	GetVoteWeight(proposalID int64, addr address) (int64, error)
207	// GetVotedHeight returns the block height at which an address voted.
208	//
209	// Parameters:
210	//   - proposalID: proposal identifier to inspect.
211	//   - addr: voter address to look up.
212	//
213	// Returns:
214	//   - int64: block height recorded for the vote.
215	//   - error: nil when a voting record exists; otherwise an error identifying the missing record.
216	GetVotedHeight(proposalID int64, addr address) (int64, error)
217	// GetVotedAt returns the timestamp at which an address voted.
218	//
219	// Parameters:
220	//   - proposalID: proposal identifier to inspect.
221	//   - addr: voter address to look up.
222	//
223	// Returns:
224	//   - int64: vote timestamp as Unix seconds.
225	//   - error: nil when a voting record exists; otherwise an error identifying the missing record.
226	GetVotedAt(proposalID int64, addr address) (int64, error)
227
228	// GetUserProposals returns a read-only view of proposal IDs grouped by creator address.
229	//
230	// Returns:
231	//   - *rotree.ReadOnlyTree: read-only creator-to-proposal-ID tree with copied ID slices.
232	GetUserProposals() *rotree.ReadOnlyTree
233
234	// Active proposal query
235	// GetOldestActiveProposalSnapshotTime inspects the first timestamp-ordered active-proposal index entry.
236	//
237	// Returns:
238	//   - snapshotTime: snapshot timestamp of the oldest active proposal.
239	//   - hasActive: true when an active indexed proposal was found; false when the index is empty.
240	//   - error: nil on success; otherwise an error when the index entry is missing or needs cleanup.
241	GetOldestActiveProposalSnapshotTime() (int64, bool, error)
242
243	// Voting weight snapshot getters
244	// GetCurrentVotingWeightSnapshot computes the current total voting weight and its smoothed timestamp anchor.
245	//
246	// Returns:
247	//   - totalVotingWeight: total delegation weight at the computed snapshot.
248	//   - snapshotTime: Unix timestamp used as the snapshot anchor.
249	//   - error: nil when the current configuration and snapshot are available; otherwise the lookup error.
250	GetCurrentVotingWeightSnapshot() (int64, int64, error)
251}

source

IGovernanceGetter provides read-only access to governance data.

  1type IGovernanceManager interface {
  2	// Proposal management
  3	// ProposeText creates a non-executable proposal for community discussion.
  4	//
  5	// Parameters:
  6	//   - _: Noncrossing implementation-call discriminator; pass 0.
  7	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
  8	//   - title: short, non-empty title describing the proposal.
  9	//   - description: non-empty proposal rationale and discussion text.
 10	//
 11	// Returns:
 12	//   - int64: ID assigned to the newly created text proposal.
 13	ProposeText(
 14		_ int, rlm realm,
 15		title string,
 16		description string,
 17	) int64
 18
 19	// ProposeCommunityPoolSpend creates a proposal to transfer registered tokens from the community pool.
 20	//
 21	// Parameters:
 22	//   - _: Noncrossing implementation-call discriminator; pass 0.
 23	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
 24	//   - title: short title describing the requested disbursement.
 25	//   - description: rationale and budget details for the disbursement.
 26	//   - to: recipient address for the community-pool transfer.
 27	//   - tokenPath: registered token realm path to transfer.
 28	//   - amount: positive transfer amount in the token's smallest unit.
 29	//
 30	// Returns:
 31	//   - int64: ID assigned to the newly created community-pool-spend proposal.
 32	ProposeCommunityPoolSpend(
 33		_ int, rlm realm,
 34		title string,
 35		description string,
 36		to address,
 37		tokenPath string,
 38		amount int64,
 39	) int64
 40
 41	// ProposeParameterChange creates a proposal containing registered parameter-handler executions.
 42	//
 43	// Parameters:
 44	//   - _: Noncrossing implementation-call discriminator; pass 0.
 45	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
 46	//   - title: short title describing the parameter changes.
 47	//   - description: rationale and impact details for the changes.
 48	//   - numToExecute: number of encoded parameter-change executions expected.
 49	//   - executions: execution messages encoded with the governance execution delimiters.
 50	//
 51	// Returns:
 52	//   - int64: ID assigned to the newly created parameter-change proposal.
 53	ProposeParameterChange(
 54		_ int, rlm realm,
 55		title string,
 56		description string,
 57		numToExecute int64,
 58		executions string,
 59	) int64
 60
 61	// Voting
 62	// Vote records the caller's final yes or no vote on a proposal.
 63	//
 64	// Parameters:
 65	//   - _: Noncrossing implementation-call discriminator; pass 0.
 66	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
 67	//   - proposalId: ID of the proposal to vote on.
 68	//   - yes: true to cast an affirmative vote, false to cast a negative vote.
 69	//
 70	// Returns:
 71	//   - string: caller's applied voting weight formatted as a decimal string.
 72	Vote(
 73		_ int, rlm realm,
 74		proposalId int64,
 75		yes bool,
 76	) string
 77
 78	// Execution
 79	// Execute applies an approved executable proposal within its delay and execution window.
 80	//
 81	// Parameters:
 82	//   - _: Noncrossing implementation-call discriminator; pass 0.
 83	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
 84	//   - proposalId: ID of the proposal to execute.
 85	//
 86	// Returns:
 87	//   - int64: ID of the proposal successfully executed.
 88	Execute(
 89		_ int, rlm realm,
 90		proposalId int64,
 91	) int64
 92
 93	// Cancel marks an upcoming proposal as cancelled at the request of its proposer.
 94	//
 95	// Parameters:
 96	//   - _: Noncrossing implementation-call discriminator; pass 0.
 97	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
 98	//   - proposalId: ID of the proposal to cancel.
 99	//
100	// Returns:
101	//   - int64: ID of the proposal successfully cancelled.
102	Cancel(
103		_ int, rlm realm,
104		proposalId int64,
105	) int64
106
107	// RemoveInactiveProposalFromIndex removes an inactive proposal from the snapshot index.
108	//
109	// Parameters:
110	//   - _: Noncrossing implementation-call discriminator; pass 0.
111	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
112	//   - proposalID: ID of the inactive proposal index entry to remove.
113	RemoveInactiveProposalFromIndex(_ int, rlm realm, proposalID int64)
114
115	// Configuration
116	// Reconfigure validates and stores a new governance configuration version.
117	//
118	// Parameters:
119	//   - _: Noncrossing implementation-call discriminator; pass 0.
120	//   - rlm: Current realm context forwarded unchanged by the governance proxy.
121	//   - votingStartDelay: seconds from proposal creation until voting opens.
122	//   - votingPeriod: seconds for which voting remains open.
123	//   - votingWeightSmoothingDuration: seconds used to smooth delegation history for voting weight.
124	//   - quorum: required approval percentage of total xGNS supply, from 0 through 100.
125	//   - proposalCreationThreshold: minimum xGNS amount required to create a proposal.
126	//   - executionDelay: seconds required between approval and execution.
127	//   - executionWindow: seconds after the delay during which execution is allowed.
128	//
129	// Returns:
130	//   - int64: newly stored governance configuration version.
131	Reconfigure(
132		_ int, rlm realm,
133		votingStartDelay int64,
134		votingPeriod int64,
135		votingWeightSmoothingDuration int64,
136		quorum int64,
137		proposalCreationThreshold int64,
138		executionDelay int64,
139		executionWindow int64,
140	) int64
141}

source

  1type IGovernanceStore interface {
  2	// Counter methods
  3	// HasConfigCounterStoreKey reports whether the configuration counter key exists.
  4	//
  5	// Returns:
  6	//   - bool: true when the configuration counter is present in persistent storage.
  7	HasConfigCounterStoreKey() bool
  8	// GetConfigCounter returns the persisted configuration-version counter.
  9	//
 10	// Returns:
 11	//   - *Counter: stored configuration counter; underlying storage/type failures panic.
 12	GetConfigCounter() *Counter
 13	// SetConfigCounter persists the configuration-version counter.
 14	//
 15	// Parameters:
 16	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
 17	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
 18	//   - counter: counter value to store.
 19	//
 20	// Returns:
 21	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
 22	SetConfigCounter(_ int, rlm realm, counter *Counter) error
 23
 24	// HasProposalCounterStoreKey reports whether the proposal counter key exists.
 25	//
 26	// Returns:
 27	//   - bool: true when the proposal counter is present in persistent storage.
 28	HasProposalCounterStoreKey() bool
 29	// GetProposalCounter returns the persisted proposal-ID counter.
 30	//
 31	// Returns:
 32	//   - *Counter: stored proposal counter; underlying storage/type failures panic.
 33	GetProposalCounter() *Counter
 34	// SetProposalCounter persists the proposal-ID counter.
 35	//
 36	// Parameters:
 37	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
 38	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
 39	//   - counter: counter value to store.
 40	//
 41	// Returns:
 42	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
 43	SetProposalCounter(_ int, rlm realm, counter *Counter) error
 44
 45	// Config methods
 46	// HasConfigsStoreKey reports whether the configurations tree key exists.
 47	//
 48	// Returns:
 49	//   - bool: true when the configurations tree is present in persistent storage.
 50	HasConfigsStoreKey() bool
 51	// SetConfigs replaces the persisted configuration-version tree.
 52	//
 53	// Parameters:
 54	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
 55	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
 56	//   - configs: configuration-version tree to store.
 57	//
 58	// Returns:
 59	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
 60	SetConfigs(_ int, rlm realm, configs *bptree.BPTree) error
 61	// SetConfig stores one configuration under its version key.
 62	//
 63	// Parameters:
 64	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
 65	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
 66	//   - version: configuration version key.
 67	//   - config: configuration value to store.
 68	//
 69	// Returns:
 70	//   - error: nil when persisted; otherwise a spoofed-realm, missing-tree, or key-value store error.
 71	SetConfig(_ int, rlm realm, version int64, config Config) error
 72	// GetConfig retrieves one configuration from the persisted version tree.
 73	//
 74	// Parameters:
 75	//   - version: configuration version key to look up.
 76	//
 77	// Returns:
 78	//   - Config: stored configuration, or its zero value when absent; wrong stored types panic.
 79	//   - bool: true when a configuration exists for version.
 80	GetConfig(version int64) (Config, bool)
 81
 82	// Proposal methods
 83	// HasProposalsStoreKey reports whether the proposals tree key exists.
 84	//
 85	// Returns:
 86	//   - bool: true when the proposals tree is present in persistent storage.
 87	HasProposalsStoreKey() bool
 88	// GetProposals returns the mutable domain-owned proposals tree.
 89	//
 90	// Returns:
 91	//   - *bptree.BPTree: stored proposal tree keyed by proposal ID string; storage/type failures panic.
 92	GetProposals() *bptree.BPTree
 93	// GetProposal retrieves a proposal by numeric ID.
 94	//
 95	// Parameters:
 96	//   - proposalID: proposal identifier used as the tree key.
 97	//
 98	// Returns:
 99	//   - *Proposal: stored proposal when present and correctly typed.
100	//   - bool: true when a valid proposal exists for proposalID.
101	GetProposal(proposalID int64) (*Proposal, bool)
102	// SetProposal stores a proposal under its matching numeric ID.
103	//
104	// Parameters:
105	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
106	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
107	//   - proposalID: storage key that must match proposal.ID().
108	//   - proposal: proposal value to persist.
109	//
110	// Returns:
111	//   - error: nil when persisted; otherwise a spoofed-realm, missing-tree, or ID-mismatch error.
112	SetProposal(_ int, rlm realm, proposalID int64, proposal *Proposal) error
113	// SetProposals replaces the persisted proposals tree.
114	//
115	// Parameters:
116	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
117	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
118	//   - proposals: proposal tree to persist.
119	//
120	// Returns:
121	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
122	SetProposals(_ int, rlm realm, proposals *bptree.BPTree) error
123
124	// HasActiveProposalsBySnapshotStoreKey reports whether the active-proposal snapshot index exists.
125	//
126	// Returns:
127	//   - bool: true when the timestamp-ordered active-proposal index is present.
128	HasActiveProposalsBySnapshotStoreKey() bool
129	// GetActiveProposalsBySnapshot returns the domain-owned active-proposal snapshot index.
130	//
131	// Returns:
132	//   - *bptree.BPTree: index keyed by snapshot timestamp and containing proposal IDs; storage/type failures panic.
133	GetActiveProposalsBySnapshot() *bptree.BPTree
134	// SetActiveProposalsBySnapshot replaces the active-proposal snapshot index.
135	//
136	// Parameters:
137	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
138	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
139	//   - tree: timestamp-ordered active-proposal index to persist.
140	//
141	// Returns:
142	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
143	SetActiveProposalsBySnapshot(_ int, rlm realm, tree *bptree.BPTree) error
144
145	// Proposal voting info methods
146	// HasProposalUserVotingInfosStoreKey reports whether the root voting-info tree exists.
147	//
148	// Returns:
149	//   - bool: true when proposal voting-info storage is present.
150	HasProposalUserVotingInfosStoreKey() bool
151	// GetProposalUserVotingInfos returns the root proposal-to-voter-info tree.
152	//
153	// Returns:
154	//   - *bptree.BPTree: stored tree containing one voter-info tree per proposal; storage/type failures panic.
155	GetProposalUserVotingInfos() *bptree.BPTree
156	// SetProposalUserVotingInfos replaces the root proposal-to-voter-info tree.
157	//
158	// Parameters:
159	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
160	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
161	//   - votingInfos: root proposal-to-voter-info tree to persist.
162	//
163	// Returns:
164	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
165	SetProposalUserVotingInfos(_ int, rlm realm, votingInfos *bptree.BPTree) error
166	// GetProposalVotingInfos returns the voter-info tree for one proposal.
167	//
168	// Parameters:
169	//   - proposalID: proposal identifier used as the root-tree key.
170	//
171	// Returns:
172	//   - *bptree.BPTree: voter-address-to-voting-info tree when present.
173	//   - bool: true when the proposal has a correctly typed voter-info tree.
174	GetProposalVotingInfos(proposalID int64) (*bptree.BPTree, bool)
175	// SetProposalVotingInfos stores one proposal's voter-info tree.
176	//
177	// Parameters:
178	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
179	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
180	//   - proposalID: proposal identifier used as the root-tree key.
181	//   - votingInfos: voter-address-to-voting-info tree to persist.
182	//
183	// Returns:
184	//   - error: nil when persisted; otherwise a spoofed-realm, missing-tree, or key-value store error.
185	SetProposalVotingInfos(_ int, rlm realm, proposalID int64, votingInfos *bptree.BPTree) error
186
187	// User proposals methods
188	// HasUserProposalsStoreKey reports whether the user-to-proposal index exists.
189	//
190	// Returns:
191	//   - bool: true when user proposal storage is present.
192	HasUserProposalsStoreKey() bool
193	// GetUserProposals returns the domain-owned user-to-proposal index tree.
194	//
195	// Returns:
196	//   - *bptree.BPTree: tree mapping user strings to proposal-ID slices; storage/type failures panic.
197	GetUserProposals() *bptree.BPTree
198	// GetUserProposalIDs returns proposal IDs currently indexed for a user.
199	//
200	// Parameters:
201	//   - user: user-string key in the user-to-proposals index.
202	//
203	// Returns:
204	//   - []int64: proposal IDs indexed for user, or nil when absent; wrong stored types panic.
205	//   - bool: true when the user has an index entry.
206	GetUserProposalIDs(user string) ([]int64, bool)
207	// SetUserProposals replaces the persisted user-to-proposal index.
208	//
209	// Parameters:
210	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
211	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
212	//   - userProposals: user-to-proposal index tree to persist.
213	//
214	// Returns:
215	//   - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
216	SetUserProposals(_ int, rlm realm, userProposals *bptree.BPTree) error
217	// AddUserProposal appends a proposal ID to a user's indexed list.
218	//
219	// Parameters:
220	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
221	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
222	//   - user: user-string key whose proposal list is updated.
223	//   - proposalID: proposal identifier to append.
224	//
225	// Returns:
226	//   - error: nil when persisted; otherwise a spoofed-realm, missing-key, or key-value store error.
227	AddUserProposal(_ int, rlm realm, user string, proposalID int64) error
228	// RemoveUserProposal removes every occurrence of a proposal ID from a user's list.
229	// A missing user entry is treated as an already-complete no-op.
230	//
231	// Parameters:
232	//   - _: leading realm-call discriminator for the internal store method; callers pass 0.
233	//   - rlm: forwarded realm context for the persistent write; the store validates it as current.
234	//   - user: user-string key whose proposal list is updated.
235	//   - proposalID: proposal identifier to remove.
236	//
237	// Returns:
238	//   - error: nil when removed or already absent; otherwise a spoofed-realm, missing-key, or key-value store error.
239	RemoveUserProposal(_ int, rlm realm, user string, proposalID int64) error
240}

source

1type ParameterChangeInfo struct {
2	pkgPath  string   // Package path of the target contract
3	function string   // Function name to call
4	params   []string // Parameters to pass to the function
5}

source

ParameterChangeInfo represents a single parameter change to be executed.

1func (i *ParameterChangeInfo) Function() string

source

Returns:

string: function name of the parameter-change handler.

1func (i *ParameterChangeInfo) Params() []string

source

Returns:

[]string: encoded arguments passed to the parameter-change handler.

1func (i *ParameterChangeInfo) PkgPath() string

source

Example

1Getter methods

Returns:

string: package path of the parameter-change handler.

 1type Proposal struct {
 2	id            int64             // Unique identifier for the proposal
 3	proposer      address           // The address of the proposer
 4	configVersion int64             // The version of the governance config used
 5	status        *ProposalStatus   // Current status and voting information
 6	metadata      *ProposalMetadata // Title and description
 7	data          *ProposalData     // Type-specific proposal data
 8	snapshotTime  int64             // Timestamp for voting weight snapshot lookup
 9	createdHeight int64             // Block height at creation
10}

source

Proposal represents a governance proposal with all its associated data and state. This is the core structure that tracks proposal lifecycle from creation to execution.

1func (p *Proposal) Clone() *Proposal

source

Clone returns a deep copy of the proposal, including its type-specific data and nested execution messages.

The returned proposal and all nested status, metadata, data, and message values are independent copies; mutating the clone does not mutate realm state.

Returns:

*Proposal: independent proposal copy, or nil when the receiver is nil

1func (p *Proposal) ConfigVersion() int64

source

ConfigVersion returns the governance configuration version used by the proposal.

Returns:

int64: configuration version captured when the proposal was created

1func (p *Proposal) CreatedAt() int64

source

CreatedAt returns the proposal creation timestamp recorded in its schedule.

Returns:

int64: proposal creation timestamp

1func (p *Proposal) CreatedHeight() int64

source

CreatedHeight returns the block height at which the proposal was created.

Returns:

int64: proposal creation block height

1func (p *Proposal) Data() *ProposalData

source

Data returns the proposal's type-specific data.

Returns:

*ProposalData: type-specific proposal data stored on the proposal

1func (p *Proposal) Description() string

source

Description returns the proposal description stored in its metadata.

Returns:

string: proposal description

1func (p *Proposal) ID() int64

source

ID returns the unique identifier assigned to the proposal.

Returns:

int64: proposal identifier used as its storage key

1func (p *Proposal) IsCommunityPoolSpendType() bool

source

IsCommunityPoolSpendType reports whether the proposal spends community-pool funds.

Returns:

bool: true when the proposal type is CommunityPoolSpend

1func (p *Proposal) IsParameterChangeType() bool

source

IsParameterChangeType reports whether the proposal changes governance parameters.

Returns:

bool: true when the proposal type is ParameterChange

1func (p *Proposal) IsProposer(addr address) bool

source

IsProposer reports whether addr matches the proposal's proposer address.

Parameters:

addr: address to compare with the proposal proposer

Returns:

bool: true when addr is the proposal proposer

1func (p *Proposal) IsTextType() bool

source

IsTextType reports whether the proposal is a text proposal.

Returns:

bool: true when the proposal type is Text

1func (p *Proposal) Metadata() *ProposalMetadata

source

Metadata returns the proposal's title and description metadata.

Returns:

*ProposalMetadata: metadata stored on the proposal

1func (p *Proposal) Proposer() address

source

Proposer returns the address that created the proposal.

Returns:

address: proposal creator's address

1func (p *Proposal) SnapshotTime() int64

source

SnapshotTime returns the timestamp used to look up historical voting weight.

Returns:

int64: voting-weight snapshot timestamp

1func (p *Proposal) Status() *ProposalStatus

source

Status returns the proposal's schedule, vote, and action status.

Returns:

*ProposalStatus: mutable aggregate status associated with the proposal

1func (p *Proposal) Title() string

source

Title returns the proposal title stored in its metadata.

Returns:

string: proposal title

1func (p *Proposal) Type() ProposalType

source

Type returns the proposal's type discriminator from its type-specific data.

Returns:

ProposalType: proposal kind, such as text, community-pool spend, or parameter change

1func (p *Proposal) VotingMaxWeight() int64

source

VotingMaxWeight returns the maximum voting weight recorded for this proposal.

Returns:

int64: maximum voting weight used for the proposal's quorum calculation

1func (p *Proposal) VotingNoWeight() int64

source

VotingNoWeight returns the total weight recorded for "no" votes.

Returns:

int64: current "no" vote weight

1func (p *Proposal) VotingQuorumAmount() int64

source

VotingQuorumAmount returns the minimum total vote weight required to pass.

Returns:

int64: quorum vote weight required by this proposal's configuration

1func (p *Proposal) VotingYesWeight() int64

source

VotingYesWeight returns the total weight recorded for "yes" votes.

Returns:

int64: current "yes" vote weight

 1type ProposalActionStatus struct {
 2	canceled       bool    // Whether the proposal has been canceled
 3	canceledAt     int64   // Timestamp when proposal was canceled
 4	canceledHeight int64   // Block height when proposal was canceled
 5	canceledBy     address // Who canceled the proposal
 6
 7	executed       bool    // Whether the proposal has been executed
 8	executedAt     int64   // Timestamp when proposal was executed
 9	executedHeight int64   // Block height when proposal was executed
10	executedBy     address // Who executed the proposal
11
12	executable bool // Whether this proposal type supports execution
13}

source

ProposalActionStatus tracks the execution and cancellation status of a proposal. This structure manages the action-related state including who performed actions and when.

1func (p *ProposalActionStatus) Canceled() bool

source

Example

1Getter methods

Canceled reports whether this proposal has been marked canceled.

Returns:

bool: true when cancellation has been recorded

1func (p *ProposalActionStatus) CanceledAt() int64

source

CanceledAt returns the timestamp recorded when the proposal was canceled.

Returns:

int64: cancellation timestamp, or zero when none has been recorded

1func (p *ProposalActionStatus) CanceledBy() address

source

CanceledBy returns the address recorded as having canceled the proposal. The value is meaningful when Canceled() is true; before then it is the zero address unless a caller has explicitly stored another value.

Returns:

address: address recorded for the cancellation actor

1func (p *ProposalActionStatus) CanceledHeight() int64

source

CanceledHeight returns the block height recorded when the proposal was canceled.

Returns:

int64: cancellation block height, or zero when none has been recorded

1func (p *ProposalActionStatus) Clone() *ProposalActionStatus

source

Clone creates a deep copy of the ProposalActionStatus, or nil when the receiver is nil.

Returns:

*ProposalActionStatus: independent copy of the status, or nil for a nil receiver

1func (p *ProposalActionStatus) Executable() bool

source

Executable reports whether this proposal type supports execution.

Returns:

bool: true when the proposal's action can be executed

1func (p *ProposalActionStatus) Executed() bool

source

Executed reports whether this proposal has been marked executed.

Returns:

bool: true when execution has been recorded

1func (p *ProposalActionStatus) ExecutedAt() int64

source

ExecutedAt returns the timestamp recorded when the proposal was executed.

Returns:

int64: execution timestamp, or zero when none has been recorded

1func (p *ProposalActionStatus) ExecutedBy() address

source

ExecutedBy returns the address recorded as having executed the proposal. The value is meaningful when IsExecuted() is true; before then it is the zero address unless a caller has explicitly stored another value.

Returns:

address: address recorded for the execution actor

1func (p *ProposalActionStatus) ExecutedHeight() int64

source

ExecutedHeight returns the block height recorded when the proposal was executed.

Returns:

int64: execution block height, or zero when none has been recorded

1func (p *ProposalActionStatus) IsExecutable() bool

source

IsExecutable reports whether this proposal type can be executed.

Returns:

bool: true when execution is supported for the proposal type

1func (p *ProposalActionStatus) IsExecuted() bool

source

IsExecuted reports whether execution has been recorded for the proposal.

Returns:

bool: true when the proposal has been marked executed

1func (p *ProposalActionStatus) SetCanceled(canceled bool)

source

Example

1Setter methods

SetCanceled records whether the proposal is canceled.

Parameters:

canceled: cancellation state to store

1func (p *ProposalActionStatus) SetCanceledAt(canceledAt int64)

source

SetCanceledAt records the timestamp associated with proposal cancellation.

Parameters:

canceledAt: cancellation timestamp to store

1func (p *ProposalActionStatus) SetCanceledBy(canceledBy address)

source

SetCanceledBy records the address that canceled the proposal.

Parameters:

canceledBy: address of the actor that canceled the proposal

1func (p *ProposalActionStatus) SetCanceledHeight(canceledHeight int64)

source

SetCanceledHeight records the block height associated with proposal cancellation.

Parameters:

canceledHeight: cancellation block height to store

1func (p *ProposalActionStatus) SetExecutable(executable bool)

source

SetExecutable records whether this proposal type supports execution.

Parameters:

executable: execution capability to store for the proposal type

1func (p *ProposalActionStatus) SetExecuted(executed bool)

source

SetExecuted records whether the proposal is executed.

Parameters:

executed: execution state to store

1func (p *ProposalActionStatus) SetExecutedAt(executedAt int64)

source

SetExecutedAt records the timestamp associated with proposal execution.

Parameters:

executedAt: execution timestamp to store

1func (p *ProposalActionStatus) SetExecutedBy(executedBy address)

source

SetExecutedBy records the address that executed the proposal.

Parameters:

executedBy: address of the actor that executed the proposal

1func (p *ProposalActionStatus) SetExecutedHeight(executedHeight int64)

source

SetExecutedHeight records the block height associated with proposal execution.

Parameters:

executedHeight: execution block height to store

1type ProposalData struct {
2	proposalType       ProposalType            // Type of proposal (Text, CommunityPoolSpend, ParameterChange)
3	communityPoolSpend *CommunityPoolSpendInfo // Data for community pool spending proposals
4	execution          *ExecutionInfo          // Data for parameter change proposals
5}

source

ProposalData contains the type-specific data for a proposal. This structure holds different data depending on the proposal type.

1func (p *ProposalData) Clone() *ProposalData

source

Clone creates a deep copy of the ProposalData. Returns:

*ProposalData: independent proposal-data copy with cloned nested values, or nil when the receiver is nil.

1func (p *ProposalData) CommunityPoolSpend() *CommunityPoolSpendInfo

source

CommunityPoolSpend returns the community pool spending information.

Returns:

*CommunityPoolSpendInfo: community pool spending details

1func (p *ProposalData) Execution() *ExecutionInfo

source

Execution returns the execution information for parameter changes.

Returns:

*ExecutionInfo: parameter change execution details

1func (p *ProposalData) ProposalType() ProposalType

source

ProposalType returns the type of this proposal.

Returns:

ProposalType: the proposal type

1type ProposalMetadata struct {
2	title       string // Proposal title (max 255 characters)
3	description string // Detailed proposal description (max 10,000 characters)
4}

source

ProposalMetadata contains descriptive information about a proposal. This includes the title and description that are displayed to voters.

1func (p *ProposalMetadata) Clone() *ProposalMetadata

source

Clone creates a deep copy of the ProposalMetadata. Returns:

*ProposalMetadata: independent metadata copy, or nil when the receiver is nil.

1func (p *ProposalMetadata) Description() string

source

Description returns the proposal description.

Returns:

string: proposal description

1func (p *ProposalMetadata) Title() string

source

Title returns the proposal title.

Returns:

string: proposal title

1type ProposalScheduleStatus struct {
2	createTime     int64 // When the proposal was created
3	activeTime     int64 // When voting starts (CreateTime + VotingStartDelay)
4	votingEndTime  int64 // When voting ends (ActiveTime + VotingPeriod)
5	executableTime int64 // When execution window starts (VotingEndTime + ExecutionDelay)
6	expiredTime    int64 // When execution window ends (ExecutableTime + ExecutionWindow)
7}

source

ProposalScheduleStatus represents the pre-calculated time schedule for a proposal. This structure defines all the important timestamps in a proposal's lifecycle, from creation through voting to execution and expiration.

1func (p *ProposalScheduleStatus) ActiveTime() int64

source

ActiveTime returns the Unix timestamp when proposal voting starts.

Returns:

int64: voting start timestamp

1func (p *ProposalScheduleStatus) Clone() *ProposalScheduleStatus

source

Clone creates a deep copy of the ProposalScheduleStatus.

Returns:

*ProposalScheduleStatus: copied schedule, or nil when the receiver is nil

1func (p *ProposalScheduleStatus) CreateTime() int64

source

Example

1Getter methods

CreateTime returns the Unix timestamp when the proposal was created.

Returns:

int64: proposal creation timestamp

1func (p *ProposalScheduleStatus) ExecutableTime() int64

source

ExecutableTime returns the Unix timestamp when the execution window starts.

Returns:

int64: execution start timestamp

1func (p *ProposalScheduleStatus) ExpiredTime() int64

source

ExpiredTime returns the Unix timestamp when the execution window closes.

Returns:

int64: execution expiration timestamp

1func (p *ProposalScheduleStatus) SetActiveTime(activeTime int64)

source

SetActiveTime updates the timestamp when proposal voting starts.

Parameters:

activeTime: Unix timestamp when voting starts

1func (p *ProposalScheduleStatus) SetCreateTime(createTime int64)

source

Example

1Setter methods

SetCreateTime updates the proposal creation timestamp.

Parameters:

createTime: Unix timestamp when the proposal was created

1func (p *ProposalScheduleStatus) SetExecutableTime(executableTime int64)

source

SetExecutableTime updates the timestamp when proposal execution can start.

Parameters:

executableTime: Unix timestamp when the execution window starts

1func (p *ProposalScheduleStatus) SetExpiredTime(expiredTime int64)

source

SetExpiredTime updates the timestamp when proposal execution expires.

Parameters:

expiredTime: Unix timestamp when the execution window closes

1func (p *ProposalScheduleStatus) SetVotingEndTime(votingEndTime int64)

source

SetVotingEndTime updates the timestamp when proposal voting ends.

Parameters:

votingEndTime: Unix timestamp when voting ends

1func (p *ProposalScheduleStatus) VotingEndTime() int64

source

VotingEndTime returns the Unix timestamp when proposal voting ends.

Returns:

int64: voting end timestamp

1type ProposalStatus struct {
2	schedule     *ProposalScheduleStatus // Time-based scheduling information
3	actionStatus *ProposalActionStatus   // Execution and cancellation status
4	voteStatus   *ProposalVoteStatus     // Voting tallies and requirements
5}

source

ProposalStatus manages the complete status of a proposal including scheduling, voting, and actions. This is the central status tracking structure that coordinates different aspects of proposal state.

1func (s *ProposalStatus) ActionStatus() *ProposalActionStatus

source

ActionStatus returns the proposal's execution and cancellation state.

Returns:

*ProposalActionStatus: action state associated with the proposal

1func (s *ProposalStatus) Clone() *ProposalStatus

source

Clone creates a deep copy of the ProposalStatus, or nil when the receiver is nil.

Returns:

*ProposalStatus: independent copy of the status, or nil for a nil receiver

1func (s *ProposalStatus) NoWeight() int64

source

NoWeight returns the total weight of "no" votes.

Returns:

int64: total "no" vote weight

1func (s *ProposalStatus) Schedule() *ProposalScheduleStatus

source

Example

1Getter methods

Schedule returns the proposal's time-based scheduling state.

Returns:

*ProposalScheduleStatus: schedule containing proposal lifecycle timestamps

1func (s *ProposalStatus) VoteStatus() *ProposalVoteStatus

source

VoteStatus returns the proposal's vote tallies and voting requirements.

Returns:

*ProposalVoteStatus: vote state associated with the proposal

1func (s *ProposalStatus) YesWeight() int64

source

YesWeight returns the total weight of "yes" votes.

Returns:

int64: total "yes" vote weight

1type ProposalStatusType int

source

ProposalStatusType represents the current status of a proposal in its lifecycle. These statuses determine what actions are available for a proposal.

1func (s ProposalStatusType) String() string

source

String returns the string representation of ProposalStatusType for display purposes.

Returns:

string: lowercase status name, or "unknown" for an unrecognized value

1type ProposalType string

source

ProposalType defines the different types of proposals supported by the governance system. Each type has different execution behavior and validation requirements.

1func (p ProposalType) IsExecutable() bool

source

IsExecutable determines whether this proposal type can be executed. Text proposals are informational only and cannot be executed.

Returns:

bool: true for executable CommunityPoolSpend or ParameterChange types; false for Text and unknown types

1func (p ProposalType) String() string

source

String returns the human-readable string representation of the proposal type.

Returns:

string: "Text", "CommunityPoolSpend", or "ParameterChange" for a known type; "Unknown" otherwise

1type ProposalVoteStatus struct {
2	yea             int64 // Total weight of "yes" votes collected
3	nay             int64 // Total weight of "no" votes collected
4	maxVotingWeight int64 // The max voting weight at the time of proposal creation
5	quorumAmount    int64 // How many total votes must be collected for the proposal to be valid
6}

source

ProposalVoteStatus tracks the voting tallies and requirements for a proposal. This structure manages vote counting, quorum calculation, and voting outcome determination.

1func (p *ProposalVoteStatus) Clone() *ProposalVoteStatus

source

Clone returns an independent copy of the vote status, or nil when the receiver is nil.

Returns:

*ProposalVoteStatus: copied vote tallies and requirements, or nil for a nil receiver.

1func (p *ProposalVoteStatus) MaxVotingWeight() int64

source

Example

1Getter methods

MaxVotingWeight returns the maximum voting weight captured for the proposal.

Returns:

int64: maximum voting weight used when evaluating the proposal's quorum.

1func (p *ProposalVoteStatus) NoWeight() int64

source

NoWeight returns the total weight of "no" votes.

Returns:

int64: total "no" vote weight

1func (p *ProposalVoteStatus) QuorumAmount() int64

source

QuorumAmount returns the voting weight required for the proposal to satisfy quorum.

Returns:

int64: minimum total vote weight required by this proposal.

1func (p *ProposalVoteStatus) SetMaxVotingWeight(maxVotingWeight int64)

source

SetMaxVotingWeight records the proposal's maximum voting-weight snapshot.

Parameters:

maxVotingWeight: maximum voting weight available when the proposal was created.

1func (p *ProposalVoteStatus) SetNoWeight(no int64)

source

SetNoWeight replaces the proposal's accumulated no-vote weight.

Parameters:

no: total weight to record for negative votes.

1func (p *ProposalVoteStatus) SetQuorumAmount(quorumAmount int64)

source

SetQuorumAmount records the proposal's quorum requirement.

Parameters:

quorumAmount: minimum total vote weight required for this proposal.

1func (p *ProposalVoteStatus) SetYesWeight(yes int64)

source

Example

1Setter methods

SetYesWeight replaces the proposal's accumulated yes-vote weight.

Parameters:

yes: total weight to record for affirmative votes.

1func (p *ProposalVoteStatus) YesWeight() int64

source

YesWeight returns the total weight of "yes" votes.

Returns:

int64: total "yes" vote weight

1type StoreKey string

source

1func (s StoreKey) String() string

source

String returns the storage-key text represented by s.

Returns:

string: underlying string used as the KV-store key

1type VotingInfo struct {
2	availableVoteWeight int64 // Total voting weight available to this user for this proposal
3	votedWeight         int64 // Actual weight used when voting (0 if not voted)
4	votedHeight         int64 // Block height when vote was cast
5	votedAt             int64 // Timestamp when vote was cast
6	votedYes            bool  // True if voted "yes", false if voted "no"
7	voted               bool  // True if user has already voted
8}

source

VotingInfo tracks voting-related information for a specific user on a specific proposal. This structure maintains the user's voting eligibility, voting history, and voting power.

1func (v VotingInfo) AvailableVoteWeight() int64

source

AvailableVoteWeight returns the total voting weight available to this user. This weight is determined at proposal creation time based on delegation snapshots.

Returns:

int64: available voting weight

1func (v VotingInfo) IsVoted() bool

source

IsVoted checks if the user has already cast their vote.

Returns:

bool: true if user has voted on this proposal

1func (v VotingInfo) VotedAt() int64

source

VotedAt returns the timestamp when the vote was cast. Returns 0 if the user hasn't voted yet.

Returns:

int64: timestamp when vote was cast

1func (v VotingInfo) VotedHeight() int64

source

VotedHeight returns the block height when the vote was cast. Returns 0 if the user hasn't voted yet.

Returns:

int64: block height when vote was cast

1func (v VotingInfo) VotedNo() bool

source

VotedNo checks if the user voted "no" on the proposal. Only meaningful if IsVoted() returns true.

Returns:

bool: true if user voted "no"

1func (v VotingInfo) VotedWeight() int64

source

VotedWeight returns the weight actually used when voting. Returns 0 if the user hasn't voted yet.

Returns:

int64: weight used for voting, or 0 if not voted

1func (v VotingInfo) VotedYes() bool

source

VotedYes checks if the user voted "yes" on the proposal. Only meaningful if IsVoted() returns true.

Returns:

bool: true if user voted "yes"

1func (v VotingInfo) VotingType() string

source

VotingType returns a human-readable string representation of the vote choice.

Returns:

string: "yes" or "no" based on voting choice

errors stdlib
gno.land/p/gnoswap/store/v1 package
gno.land/p/gnoswap/version_manager/v1 package
gno.land/p/nt/bptree/rotree/v0 package
gno.land/p/nt/bptree/v0 package
gno.land/p/nt/ufmt/v0 package
gno.land/r/gnoswap/access/v1 realm
gno.land/r/gnoswap/gov/staker realm
gno.land/r/gnoswap/rbac/v1 realm
strconv stdlib
strings stdlib

Readme View source

Governance

Overview

Configuration

Core Mechanics

Staking Flow

Proposal Types

Proposal Lifecycle

Creation

Voting

Execution

Technical Details

Vote Weight Calculation

Quorum Calculation

Rewards Distribution

Usage

Security

Overview

Constants 4

Functions 63

Types 21

Methods on CommunityPoolSpendInfo

Methods on Config

Methods on Counter

Methods on ExecutionInfo

Methods on ParameterChangeInfo

Methods on Proposal

Methods on ProposalActionStatus