governance state

govStakerAccessor

newGovStakerAccessor

Config

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

NewConfig

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

NewConfigPtr

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

NewDefaultConfig

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

NewConfigTree

NewConfigTree creates an empty BPTree used to index configuration values by their encoded int64 version. Returns: - \*bptree.BPTree: empty configuration index tree

Counter

Counter manages unique incrementing IDs.

NewCounter

NewCounter creates a new Counter whose current ID is initialized to zero. Returns: - \*Counter: counter initialized with current ID 0

GetLatestConfigVersion

GetLatestConfigVersion returns the current governance configuration version. Returns: - int64: latest configuration version stored by governance

GetCurrentProposalID

GetCurrentProposalID returns the current proposal ID counter. Returns: - int64: current proposal ID counter used for newly created proposals

GetMaxSmoothingPeriod

GetMaxSmoothingPeriod returns the maximum smoothing period for delegation history cleanup. Returns: - int64: maximum permitted smoothing period in seconds

GetLatestConfig

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

GetConfig

GetConfig retrieves one governance configuration by version. A missing version returns the zero Config and false. Parameters: - version: configuration version used to form the tree key Returns: - Config: configuration stored for version, or zero Config when absent - bool: true when version was found; false when no configuration is stored

GetProposals

GetProposals retrieves the persisted proposals tree. Storage or type-cast failures panic. Returns: - \*bptree.BPTree: tree containing proposals keyed by formatted proposal ID

ExistsProposal

ExistsProposal checks whether a proposal is stored. Parameters: - proposalID: proposal identifier to look up Returns: - bool: true when proposalID is stored, otherwise false

GetProposerByProposalId

GetProposalTypeByProposalId

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

GetYeaByProposalId

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

GetNayByProposalId

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

GetConfigVersionByProposalId

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

GetQuorumAmountByProposalId

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

GetTitleByProposalId

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

GetDescriptionByProposalId

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

GetProposalStatusByProposalId

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

GetProposalCreatedAt

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

GetProposalCreatedHeight

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

GetVoteStatus

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

GetVotingInfos

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

ExistsVotingInfo

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

GetVoteWeight

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

GetVotedHeight

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

GetVotedAt

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

GetProposalCommunityPoolSpendInfo

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

GetProposalExecutionInfo

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

GetUserProposals

GetUserProposals retrieves the persisted user-to-proposals index. Storage or type-cast failures panic. Returns: - \*bptree.BPTree: tree mapping user strings to proposal ID slices

GetOldestActiveProposalSnapshotTime

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

GetCurrentVotingWeightSnapshot

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

Proposal

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.

NewProposal

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

NewProposalTree

NewProposalTree creates an empty B+ tree for proposals keyed by proposal ID. Returns: - \*bptree.BPTree: empty 16-way proposal tree

NewUserProposalTree

NewUserProposalTree creates an empty B+ tree mapping users to proposal IDs. Returns: - \*bptree.BPTree: empty 16-way user-proposal index tree

NewVotingInfoTree

NewVotingInfoTree creates an empty B+ tree for per-user voting information. Returns: - \*bptree.BPTree: empty 16-way voting-information tree

NewProposalUserVotingInfoTree

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

ProposalActionStatus

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

NewProposalActionStatus

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

ProposalMetadata

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

NewProposalMetadata

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

ProposalData

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

NewProposalData

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

CommunityPoolSpendInfo

CommunityPoolSpendInfo contains information for community pool spending proposals.

NewCommunityPoolSpendInfo

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.

ExecutionInfo

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

NewExecutionInfo

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.

ParameterChangeInfo

ParameterChangeInfo represents a single parameter change to be executed.

NewParameterChangeInfo

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.

ProposalScheduleStatus

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.

NewProposalScheduleStatus

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

ProposalStatusType

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

StatusUpcoming

// Proposal created but voting hasn't started yet

StatusActive

// Proposal is in voting period

StatusPassed

// Proposal has passed but hasn't been executed (or is text proposal)

StatusRejected

// Proposal failed to meet voting requirements

StatusExecutable

// Proposal can be executed (passed and in execution window)

StatusExecuted

// Proposal has been successfully executed

StatusExpired

// Proposal execution window has passed

StatusCanceled

// Proposal has been canceled

ProposalStatus

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.

NewProposalStatusBy

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

ProposalType

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

Text

// Informational proposals for community discussion

CommunityPoolSpend

CommunityPoolSpend returns the community pool spending information. Returns: - \*CommunityPoolSpendInfo: community pool spending details

ParameterChange

// Proposals to modify system parameters

ProposalVoteStatus

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

NewProposalVoteStatus

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

ProposeText

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.

ProposeCommunityPoolSpend

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.

ProposeParameterChange

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.

Vote

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.

Execute

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.

Cancel

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.

RemoveInactiveProposalFromIndex

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.

Reconfigure

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.

Render

Render delegates web rendering to the active implementation.

ErrSpoofedRealm

currentAddress

domainPath

kvStore

versionManager

implementation

init.90

initializeDomainStore

getImplementation

updateImplementation

StoreKey

StoreKeyConfigCounter

// Config version counter

StoreKeyProposalCounter

// Proposal ID counter

StoreKeyConfigs

// Configurations BPTree

StoreKeyProposals

// Proposals BPTree

StoreKeyActiveProposalsBySnapshot

StoreKeyProposalUserVotingInfos

// Proposal voting infos BPTree

StoreKeyUserProposals

// User proposals mapping BPTree

governanceStore

NewGovernanceStore

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

formatInt64Key

formatInt64Key formats int64 identifiers for storage keys.

IGovernance

IGovernanceManager

IGovernanceGetter

IGovernanceGetter provides read-only access to governance data.

IGovernanceStore

GovStakerAccessor

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

RegisterInitializer

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.

UpgradeImpl

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.

GetImplementationPackagePath

GetImplementationPackagePath returns the package path of the currently active implementation. Returns: - packagePath: package path of the active implementation

VotingInfo

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.

NewVotingInfo

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

DefaultVotingInfo

DefaultVotingInfo creates an empty voting information value. Returns: - VotingInfo: zero-valued voting record with no available weight and no vote recorded

NewVotedVotingInfo

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