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 system enables GNS holders to stake for xGNS voting power, create proposals, and vote on protocol changes. For more details, check out docs.

Configuration

The governance.Config type defines the core governance parameters. All values can be modified through governance proposals. This type can be found in the config.gno file.

Field	Description	Default
`VotingStartDelay`	Delay before voting starts after proposal creation	1 day
`VotingPeriod`	Duration for collecting votes	7 days
`VotingWeightSmoothingDuration`	Period for averaging voting weight (prevents flash loans)	1 day
`Quorum`	Percentage of active xGNS required for proposal passage	50%
`ProposalCreationThreshold`	Minimum xGNS amount required to create a proposal	1,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

Core Mechanics

Staking Flow

1GNS → Stake → xGNS (voting power) → Delegate → Vote

Stake GNS to receive equal xGNS
Delegate voting power (can be self)
Vote on proposals with delegated power
7-day lockup for undelegation

Proposal Types

Text: Signal proposals without execution
CommunityPoolSpend: Treasury disbursements
ParameterChange: Protocol parameter updates

Proposal Lifecycle

Creation

Requires 1,000 xGNS balance
One active proposal per address
Valid type and parameters required

Voting

1 day delay before voting starts
7 days voting period
Weight = 24hr average delegation (prevents flash loans)

Execution

A proposal is considered valid and executable when:

The voting period has ended
Total votes meet the quorum threshold (50% of xGNS total supply)
YES votes strictly exceed NO votes (ties do not pass)
The execution delay period (configured via ExecutionDelay default: 24 hours) has passed after voting ends
Within the execution window period (configured via ExecutionWindow default: 30 days)
- ExecutionDelay and ExecutionWindow are configured through the governance.Config type.
Anyone can trigger execution once conditions are met

Technical Details

Vote Weight Calculation

1// 24-hour average prevents manipulation
2snapshot1 = getDelegationAt(proposalTime - 24hr)
3snapshot2 = getDelegationAt(proposalTime)
4voteWeight = (snapshot1 + snapshot2) / 2

Quorum Calculation

1activeXGNS = totalXGNS - launchpadXGNS
2quorumAmount = activeXGNS * quorumPercent / 100  // quorumPercent defaults to 50

The quorum threshold is calculated based on the Quorum percentage (default: 50%) of the active xGNS supply at the time of proposal creation. A proposal passes only when total votes reach quorum and the accumulated YES votes strictly exceed the accumulated NO votes.

Rewards Distribution

xGNS holders earn protocol fees:

1userShare = (userXGNS / totalXGNS) * protocolFees

Usage

 1// Stake GNS for xGNS
 2Delegate(amount, delegateTo)
 3
 4// Create proposal
 5ProposeText(title, description, body)
 6ProposeCommunityPoolSpend(recipient, amount)
 7ProposeParameterChange(title, description, numToExecute, executions)
 8
 9// Vote on proposal
10Vote(proposalId, true)  // YES
11Vote(proposalId, false) // NO
12
13// Execute after timelock
14Execute(proposalId)
15
16// Undelegate (7-day lockup)
17Undelegate()

Security

Flash loan protection via vote smoothing
Sybil resistance through stake weighting
Timelock prevents rushed execution
Single proposal limit per address
Dynamic quorum excludes inactive xGNS

Package governance implements proposal lifecycle management and voting. It supports text proposals, parameter changes, and community pool spending. Proposals go through creation, voting, and execution phases with configurable parameters for voting delays, periods, and thresholds.

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	StoreKeyProposalUserVotingInfos StoreKey = "proposalUserVotingInfos" // Proposal voting infos BPTree
10
11	StoreKeyUserProposals StoreKey = "userProposals" // User proposals mapping BPTree
12)

source

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

source

Cancel cancels a proposal before voting begins. Only callable by the proposer.

Parameters:

proposalId: ID of the proposal to cancel

Returns:

int64: cancellation result code

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

source

Execute executes a passed proposal that is in the execution window.

Parameters:

proposalId: ID of the proposal to execute

Returns:

int64: execution result code

1func ExistsProposal(proposalID int64) bool

source

ExistsProposal checks if a proposal exists.

1func ExistsVotingInfo(proposalID int64, addr address) bool

source

ExistsVotingInfo checks if a voting info exists for a user on a proposal.

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

source

GetConfigVersionByProposalId returns the config version used by a proposal.

1func GetCurrentProposalID() int64

source

GetCurrentProposalID returns the current proposal ID counter.

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

source

GetCurrentVotingWeightSnapshot returns the current voting weight snapshot.

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

source

GetDescriptionByProposalId returns the description of a proposal.

1func GetImplementationPackagePath() string

source

GetImplementationPackagePath returns the package path of the currently active implementation.

1func GetLatestConfigVersion() int64

source

GetLatestConfigVersion returns the current config version.

1func GetMaxSmoothingPeriod() int64

source

GetMaxSmoothingPeriod returns the maximum smoothing period for delegation history cleanup.

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

source

GetNayByProposalId returns the no vote weight of a proposal.

1func GetOldestActiveProposalSnapshotTime() (int64, bool)

source

GetOldestActiveProposalSnapshotTime returns the oldest snapshot time among active proposals.

1func GetProposalCount() int

source

GetProposalCount returns the total number of proposals.

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

source

GetProposalCreatedAt returns the creation timestamp of a proposal.

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

source

GetProposalCreatedHeight returns the creation block height of a proposal.

1func GetProposalIDs(offset, count int) []int64

source

GetProposalIDs returns a paginated list of proposal IDs.

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

source

GetProposalStatusByProposalId returns the current status of a proposal.

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

source

GetQuorumAmountByProposalId returns the quorum requirement for a proposal.

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

source

GetTitleByProposalId returns the title of a proposal.

1func GetUserProposalCount(user address) int

source

GetUserProposalCount returns the number of proposals created by a user.

1func GetUserProposalIDs(user address, offset, count int) []int64

source

GetUserProposalIDs returns a paginated list of proposal IDs created by a user.

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

source

GetVoteStatus returns the vote status of a proposal.

Returns:

quorum: minimum vote weight required for proposal to pass
maxVotingWeight: maximum possible voting weight
yesWeight: total weight of "yes" votes
noWeight: total weight of "no" votes

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

source

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

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

source

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

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

source

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

1func GetVotingInfoCount(proposalID int64) int

source

GetVotingInfoCount returns the number of voters for a proposal.

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

source

GetYeaByProposalId returns the yes vote weight of a proposal.

1func NewConfigTree() *bptree.BPTree

source

1func NewProposalTree() *bptree.BPTree

source

1func NewProposalUserVotingInfoTree() *bptree.BPTree

source

1func NewUserProposalTree() *bptree.BPTree

source

1func NewVotingInfoTree() *bptree.BPTree

source

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 new community pool spending proposal.

Parameters:

title: proposal title
description: detailed proposal description
to: recipient address
tokenPath: token path to transfer
amount: amount to transfer

Returns:

int64: ID of the created proposal

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

source

ProposeParameterChange creates a new parameter change proposal.

Parameters:

title: proposal title
description: detailed proposal description
numToExecute: number of executions to perform
executions: encoded execution messages

Returns:

int64: ID of the created proposal

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

source

ProposeText creates a new text proposal for general governance decisions.

Parameters:

title: proposal title
description: detailed proposal description

Returns:

int64: ID of the created proposal

 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:

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

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.

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.

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

source

Vote casts a vote on a proposal.

Parameters:

proposalId: ID of the proposal to vote on
yes: true for yes vote, false for no vote

Returns:

string: voting result information

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

source

GetProposalCommunityPoolSpendInfo returns the community pool spend info for a proposal.

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

source

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

source

GetConfig returns a specific governance configuration by version.

1func GetLatestConfig() Config

source

GetLatestConfig returns the latest governance configuration.

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

source

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.

1func NewDefaultConfig() Config

source

1func NewCounter() *Counter

source

NewCounter creates a new Counter starting at 0.

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

source

GetProposalExecutionInfo returns the execution info for a proposal.

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

source

1func NewGovernanceStore(kvStore store.KVStore) IGovernanceStore

source

NewGovernanceStore creates a new governance store instance with the provided KV store. This function is used by the upgrade system to create storage instances for each implementation.

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

source

1func GetProposal(proposalID int64) (*Proposal, error)

source

GetProposal returns a proposal by ID. Returns a clone to prevent external modification.

 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 provided parameters. NewProposal is the main constructor for creating governance proposals.

metadata: proposal title and description
data: type-specific proposal data
proposerAddress: address of the proposal creator
configVersion: governance configuration version
snapshotTime: timestamp for voting weight snapshot lookup
createdHeight: creation block height

Returns:

*Proposal: newly created proposal instance

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

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

source

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

source

GetProposalTypeByProposalId returns the type of a proposal.

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 GetVotingInfo(proposalID int64, addr address) (*VotingInfo, error)

source

GetVotingInfo returns the voting info for a user on a proposal. Returns a clone to prevent external modification.

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 structure

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

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

source

Clone creates a deep copy of the CommunityPoolSpendInfo.

1func (i *CommunityPoolSpendInfo) To() address

source

Getter methods

1func (i *CommunityPoolSpendInfo) TokenPath() string

source

 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 active xGNS supply required for proposal approval
10	Quorum int64
11	// ProposalCreationThreshold is the minimum xGNS amount required to create a proposal
12	ProposalCreationThreshold int64
13	// ExecutionDelay is the waiting period after voting ends before a proposal can be executed (in seconds)
14	ExecutionDelay int64
15	// ExecutionWindow is the time window during which an approved proposal can be executed (in seconds)
16	ExecutionWindow int64
17}

source

Config represents the configuration of the governor contract All parameters in this struct can be modified through governance.

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

source

1type Counter struct {
2	id int64
3}

source

Counter manages unique incrementing IDs.

1func (c *Counter) Get() int64

source

Get returns the current ID without incrementing.

1func (c *Counter) Next() int64

source

next increments and returns the next ID.

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

source

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.

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

source

1func (i *ExecutionInfo) Num() int64

source

Getter methods

 1type GovStakerAccessor interface {
 2	// GetTotalDelegationAmountAtSnapshot returns the total delegation amount at a specific snapshot time.
 3	GetTotalDelegationAmountAtSnapshot(snapshotTime int64) (int64, bool)
 4
 5	// GetUserDelegationAmountAtSnapshot returns the user delegation amount at a specific snapshot time.
 6	GetUserDelegationAmountAtSnapshot(userAddr address, snapshotTime int64) (int64, bool)
 7
 8	// GetTotalxGnsSupply returns the total xGNS supply used as the quorum base.
 9	GetTotalxGnsSupply() int64
10}

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}

source

 1type IGovernanceGetter interface {
 2	// Store data getters
 3	GetLatestConfigVersion() int64
 4	GetCurrentProposalID() int64
 5	GetMaxSmoothingPeriod() int64
 6
 7	// Config getters
 8	GetLatestConfig() Config
 9	GetConfig(configVersion int64) (Config, error)
10
11	// Proposal getters
12	GetProposalCount() int
13	GetProposalIDs(offset, count int) []int64
14	ExistsProposal(proposalID int64) bool
15	GetProposal(proposalID int64) (*Proposal, error)
16	GetProposerByProposalId(proposalId int64) (address, error)
17	GetProposalTypeByProposalId(proposalId int64) (ProposalType, error)
18	GetYeaByProposalId(proposalId int64) (int64, error)
19	GetNayByProposalId(proposalId int64) (int64, error)
20	GetConfigVersionByProposalId(proposalId int64) (int64, error)
21	GetQuorumAmountByProposalId(proposalId int64) (int64, error)
22	GetTitleByProposalId(proposalId int64) (string, error)
23	GetDescriptionByProposalId(proposalId int64) (string, error)
24	GetProposalStatusByProposalId(proposalId int64) (string, error)
25
26	// Vote getters
27	GetVoteStatus(proposalId int64) (quorum, maxVotingWeight, yesWeight, noWeight int64, err error)
28	GetVotingInfoCount(proposalID int64) int
29	GetVotingInfoAddresses(proposalID int64, offset, count int) []address
30	ExistsVotingInfo(proposalID int64, addr address) bool
31	GetVotingInfo(proposalID int64, addr address) (*VotingInfo, error)
32	GetVoteWeight(proposalID int64, addr address) (int64, error)
33	GetVotedHeight(proposalID int64, addr address) (int64, error)
34	GetVotedAt(proposalID int64, addr address) (int64, error)
35
36	// User proposal getters
37	GetUserProposalCount(user address) int
38	GetUserProposalIDs(user address, offset, count int) []int64
39
40	// Active proposal query
41	GetOldestActiveProposalSnapshotTime() (int64, bool)
42
43	// Voting weight snapshot getters
44	GetCurrentVotingWeightSnapshot() (int64, int64, error)
45}

source

IGovernanceGetter provides read-only access to governance data.

 1type IGovernanceManager interface {
 2	// Proposal management
 3	ProposeText(
 4		_ int, rlm realm,
 5		title string,
 6		description string,
 7	) int64
 8
 9	ProposeCommunityPoolSpend(
10		_ int, rlm realm,
11		title string,
12		description string,
13		to address,
14		tokenPath string,
15		amount int64,
16	) int64
17
18	ProposeParameterChange(
19		_ int, rlm realm,
20		title string,
21		description string,
22		numToExecute int64,
23		executions string,
24	) int64
25
26	// Voting
27	Vote(
28		_ int, rlm realm,
29		proposalId int64,
30		yes bool,
31	) string
32
33	// Execution
34	Execute(
35		_ int, rlm realm,
36		proposalId int64,
37	) int64
38
39	Cancel(
40		_ int, rlm realm,
41		proposalId int64,
42	) int64
43
44	// Configuration
45	Reconfigure(
46		_ int, rlm realm,
47		votingStartDelay int64,
48		votingPeriod int64,
49		votingWeightSmoothingDuration int64,
50		quorum int64,
51		proposalCreationThreshold int64,
52		executionDelay int64,
53		executionWindow int64,
54	) int64
55}

source

 1type IGovernanceStore interface {
 2	// Counter methods
 3	HasConfigCounterStoreKey() bool
 4	GetConfigCounter() *Counter
 5	SetConfigCounter(_ int, rlm realm, counter *Counter) error
 6
 7	HasProposalCounterStoreKey() bool
 8	GetProposalCounter() *Counter
 9	SetProposalCounter(_ int, rlm realm, counter *Counter) error
10
11	// Config methods
12	HasConfigsStoreKey() bool
13	SetConfigs(_ int, rlm realm, configs *bptree.BPTree) error
14	SetConfig(_ int, rlm realm, version int64, config Config) error
15	GetConfig(version int64) (Config, bool)
16
17	// Proposal methods
18	HasProposalsStoreKey() bool
19	GetProposals() *bptree.BPTree
20	GetProposal(proposalID int64) (*Proposal, bool)
21	SetProposal(_ int, rlm realm, proposalID int64, proposal *Proposal) error
22	SetProposals(_ int, rlm realm, proposals *bptree.BPTree) error
23
24	// Proposal voting info methods
25	HasProposalUserVotingInfosStoreKey() bool
26	GetProposalUserVotingInfos() *bptree.BPTree
27	SetProposalUserVotingInfos(_ int, rlm realm, votingInfos *bptree.BPTree) error
28	GetProposalVotingInfos(proposalID int64) (*bptree.BPTree, bool)
29	SetProposalVotingInfos(_ int, rlm realm, proposalID int64, votingInfos *bptree.BPTree) error
30
31	// User proposals methods
32	HasUserProposalsStoreKey() bool
33	GetUserProposalIDs(user string) ([]int64, bool)
34	SetUserProposals(_ int, rlm realm, userProposals *bptree.BPTree) error
35	AddUserProposal(_ int, rlm realm, user string, proposalID int64) error
36	RemoveUserProposal(_ int, rlm realm, user string, proposalID int64) error
37}

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

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

source

1func (i *ParameterChangeInfo) PkgPath() string

source

Getter methods

 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 creates a deep copy of the Proposal.

1func (p *Proposal) ConfigVersion() int64

source

ConfigVersion returns the governance configuration version used for this proposal.

1func (p *Proposal) CreatedAt() int64

source

CreatedAt returns the creation timestamp of the proposal.

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

source

Data returns the proposal data.

1func (p *Proposal) Description() string

source

Description returns the proposal description.

1func (p *Proposal) ID() int64

source

ID returns the unique identifier of the proposal.

1func (p *Proposal) IsCommunityPoolSpendType() bool

source

IsCommunityPoolSpendType checks if this is a community pool spend proposal.

1func (p *Proposal) IsParameterChangeType() bool

source

IsParameterChangeType checks if this is a parameter change proposal.

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

source

IsProposer checks if the given address is the proposer of this proposal.

1func (p *Proposal) IsTextType() bool

source

IsTextType checks if this is a text proposal.

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

source

Metadata returns the proposal metadata.

1func (p *Proposal) Proposer() address

source

Proposer returns the address of the proposal creator.

1func (p *Proposal) SnapshotTime() int64

source

SnapshotTime returns the snapshot time for voting weight lookup.

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

source

Status returns the proposal status.

1func (p *Proposal) Title() string

source

Title returns the proposal title.

1func (p *Proposal) Type() ProposalType

source

Type returns the type of this proposal.

1func (p *Proposal) VotingMaxWeight() int64

source

VotingMaxWeight returns maximum possible voting weight for this proposal.

1func (p *Proposal) VotingNoWeight() int64

source

VotingNoWeight returns the total weight of "no" votes.

1func (p *Proposal) VotingQuorumAmount() int64

source

VotingQuorumAmount returns minimum vote weight required for proposal to pass.

1func (p *Proposal) VotingYesWeight() int64

source

VotingYesWeight returns the total weight of "yes" votes.

 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

Getter methods

1func (p *ProposalActionStatus) CanceledAt() int64

source

1func (p *ProposalActionStatus) CanceledBy() address

source

CanceledBy returns the address that canceled the proposal. Only meaningful if IsCanceled() returns true.

Returns:

std.Address: address of the canceller

1func (p *ProposalActionStatus) CanceledHeight() int64

source

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

source

Clone creates a deep copy of the ProposalActionStatus.

1func (p *ProposalActionStatus) Executable() bool

source

1func (p *ProposalActionStatus) Executed() bool

source

1func (p *ProposalActionStatus) ExecutedAt() int64

source

1func (p *ProposalActionStatus) ExecutedBy() address

source

ExecutedBy returns the address that executed the proposal. Only meaningful if IsExecuted() returns true.

Returns:

std.Address: address of the executor

1func (p *ProposalActionStatus) ExecutedHeight() int64

source

1func (p *ProposalActionStatus) IsExecutable() bool

source

IsExecutable returns whether this proposal type can be executed. Text proposals return false, while other types return true.

Returns:

bool: true if proposal type supports execution

1func (p *ProposalActionStatus) IsExecuted() bool

source

IsExecuted returns whether the proposal has been executed.

Returns:

bool: true if proposal has been executed

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

source

Setter methods

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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.

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.

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

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

source

Clone creates a deep copy of the ProposalScheduleStatus.

1func (p *ProposalScheduleStatus) CreateTime() int64

source

Getter methods

1func (p *ProposalScheduleStatus) ExecutableTime() int64

source

1func (p *ProposalScheduleStatus) ExpiredTime() int64

source

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

source

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

source

Setter methods

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

source

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

source

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

source

1func (p *ProposalScheduleStatus) VotingEndTime() int64

source

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

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

source

Clone creates a deep copy of the ProposalStatus.

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

Getter methods

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

source

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: human-readable status name

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.

1func (p ProposalType) String() string

source

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

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 creates a deep copy of the ProposalVoteStatus.

1func (p *ProposalVoteStatus) MaxVotingWeight() int64

source

Getter methods

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

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

source

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

source

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

source

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

source

Setter methods

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

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) Clone() *VotingInfo

source

Clone creates a deep copy of the VotingInfo.

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) SetAvailableVoteWeight(availableVoteWeight int64)

source

Setter methods

1func (v *VotingInfo) SetVoted(voted bool)

source

1func (v *VotingInfo) SetVotedAt(votedAt int64)

source

1func (v *VotingInfo) SetVotedHeight(votedHeight int64)

source

1func (v *VotingInfo) SetVotedWeight(votedWeight int64)

source

1func (v *VotingInfo) SetVotedYes(votedYes bool)

source

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 package
gno.land/p/gnoswap/version_manager package
gno.land/p/nt/bptree/v0 package
gno.land/p/nt/ufmt/v0 package
gno.land/r/gnoswap/access realm
gno.land/r/gnoswap/gov/staker realm
gno.land/r/gnoswap/rbac 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