api

Documentation

Overview

Package api implements the governance APIs.

Index

• Constants
• type CancelUpgradeProposal
• type ChangeParametersProposal
• type ConsensusParameterChanges
• type ConsensusParameters
• type Event
• type Genesis
• type Proposal
• type ProposalContent
• type ProposalExecutedEvent
• type ProposalFinalizedEvent
• type ProposalQuery
• type ProposalState
  • func (p ProposalState) MarshalText() ([]byte, error)
  • func (p ProposalState) String() string
  • func (p *ProposalState) UnmarshalText(text []byte) error
• type ProposalSubmittedEvent
• type ProposalVote
• type UpgradeProposal
• type Vote
  • func (v Vote) MarshalText() ([]byte, error)
  • func (v Vote) String() string
  • func (v *Vote) UnmarshalText(text []byte) error
• type VoteEntry
• type VoteEvent

Constants

const (
	// GasOpSubmitProposal is the gas operation identifier for submitting proposal.
	GasOpSubmitProposal transaction.Op = "submit_proposal"
	// GasOpCastVote is the gas operation identifier for casting vote.
	GasOpCastVote transaction.Op = "cast_vote"
)

const (
	StateActive   ProposalState = 1
	StatePassed   ProposalState = 2
	StateRejected ProposalState = 3
	StateFailed   ProposalState = 4

	StateActiveName   = "active"
	StatePassedName   = "passed"
	StateRejectedName = "rejected"
	StateFailedName   = "failed"
)

Proposal state kinds.

const (
	VoteYes     Vote = 1
	VoteNo      Vote = 2
	VoteAbstain Vote = 3

	VoteYesName     = "yes"
	VoteNoName      = "no"
	VoteAbstainName = "abstain"
)

Vote kinds.

const ModuleName = "governance"

ModuleName is a unique module name for the governance backend.

const ProposalContentInvalidText = "(invalid)"

ProposalContentInvalidText is the textual representation of an invalid ProposalContent.

Types

type CancelUpgradeProposal

type CancelUpgradeProposal struct {
	// ProposalID is the identifier of the pending upgrade proposal.
	ProposalID uint64 `json:"proposal_id"`
}

CancelUpgradeProposal is an upgrade cancellation proposal.

type ChangeParametersProposal

type ChangeParametersProposal struct {
	// Module identifies the consensus backend module to which changes should be applied.
	Module string `json:"module"`
	// Changes are consensus parameter changes that should be applied to the module.
	Changes cbor.RawMessage `json:"changes"`
}

ChangeParametersProposal is a consensus change parameters proposal.

type ConsensusParameterChanges

type ConsensusParameterChanges struct {
	// GasCosts are the new gas costs.
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`

	// MinProposalDeposit is the new minimal proposal deposit.
	MinProposalDeposit *quantity.Quantity `json:"min_proposal_deposit,omitempty"`

	// VotingPeriod is the new voting period.
	VotingPeriod *beacon.EpochTime `json:"voting_period,omitempty"`

	// StakeThreshold is the new stake threshold.
	StakeThreshold *uint8 `json:"stake_threshold,omitempty"`

	// UpgradeMinEpochDiff is the new minimal epoch difference between two pending upgrades.
	UpgradeMinEpochDiff *beacon.EpochTime `json:"upgrade_min_epoch_diff,omitempty"`

	// UpgradeCancelMinEpochDiff is the new minimal epoch difference for the upgrade cancellation
	// proposal to be valid.
	UpgradeCancelMinEpochDiff *beacon.EpochTime `json:"upgrade_cancel_min_epoch_diff,omitempty"`

	// EnableChangeParametersProposal is the new enable change parameters proposal flag.
	EnableChangeParametersProposal *bool `json:"enable_change_parameters_proposal,omitempty"`
}

ConsensusParameterChanges are allowed governance consensus parameter changes.

type ConsensusParameters

type ConsensusParameters struct {
	// GasCosts are the governance transaction gas costs.
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`

	// MinProposalDeposit is the number of base units that are deposited when
	// creating a new proposal.
	MinProposalDeposit quantity.Quantity `json:"min_proposal_deposit,omitempty"`

	// VotingPeriod is the number of epochs after which the voting for a proposal
	// is closed and the votes are tallied.
	VotingPeriod beacon.EpochTime `json:"voting_period,omitempty"`

	// StakeThreshold is the minimum percentage of VoteYes votes in terms
	// of total voting power when the proposal expires in order for a
	// proposal to be accepted.  This value has a lower bound of 67.
	StakeThreshold uint8 `json:"stake_threshold,omitempty"`

	// UpgradeMinEpochDiff is the minimum number of epochs between the current
	// epoch and the proposed upgrade epoch for the upgrade proposal to be valid.
	// This is also the minimum number of epochs between two pending upgrades.
	UpgradeMinEpochDiff beacon.EpochTime `json:"upgrade_min_epoch_diff,omitempty"`

	// UpgradeCancelMinEpochDiff is the minimum number of epochs between the current
	// epoch and the proposed upgrade epoch for the upgrade cancellation proposal to be valid.
	UpgradeCancelMinEpochDiff beacon.EpochTime `json:"upgrade_cancel_min_epoch_diff,omitempty"`

	// EnableChangeParametersProposal is true iff change parameters proposals are allowed.
	EnableChangeParametersProposal bool `json:"enable_change_parameters_proposal,omitempty"`
}

ConsensusParameters are the governance consensus parameters.

type Event

type Event struct {
	Height int64     `json:"height,omitempty"`
	TxHash hash.Hash `json:"tx_hash,omitempty"`

	ProposalSubmitted *ProposalSubmittedEvent `json:"proposal_submitted,omitempty"`
	ProposalExecuted  *ProposalExecutedEvent  `json:"proposal_executed,omitempty"`
	ProposalFinalized *ProposalFinalizedEvent `json:"proposal_finalized,omitempty"`
	Vote              *VoteEvent              `json:"vote,omitempty"`
}

Event signifies a governance event, returned via GetEvents.

type Genesis

type Genesis struct {
	// Parameters are the genesis consensus parameters.
	Parameters ConsensusParameters `json:"params"`

	// Proposals are the governance proposals.
	Proposals []*Proposal `json:"proposals,omitempty"`

	// VoteEntries are the governance proposal vote entries.
	VoteEntries map[uint64][]*VoteEntry `json:"vote_entries,omitempty"`
}

Genesis is the initial governance state for use in the genesis block.

Note: PendingProposalUpgrades are not included in genesis, but are instead computed at InitChain from accepted proposals.

type Proposal

type Proposal struct {
	// ID is the unique identifier of the proposal.
	ID uint64 `json:"id"`
	// Submitter is the address of the proposal submitter.
	Submitter staking.Address `json:"submitter"`
	// State is the state of the proposal.
	State ProposalState `json:"state"`
	// Deposit is the deposit attached to the proposal.
	Deposit quantity.Quantity `json:"deposit"`

	// Content is the content of the proposal.
	Content ProposalContent `json:"content"`

	// CreatedAt is the epoch at which the proposal was created.
	CreatedAt beacon.EpochTime `json:"created_at"`
	// ClosesAt is the epoch at which the proposal will close and votes will
	// be tallied.
	ClosesAt beacon.EpochTime `json:"closes_at"`
	// Results are the final tallied results after the voting period has
	// ended.
	Results map[Vote]quantity.Quantity `json:"results,omitempty"`
	// InvalidVotes is the number of invalid votes after tallying.
	InvalidVotes uint64 `json:"invalid_votes,omitempty"`
}

Proposal is a consensus upgrade proposal.

type ProposalContent

type ProposalContent struct {
	Upgrade          *UpgradeProposal          `json:"upgrade,omitempty"`
	CancelUpgrade    *CancelUpgradeProposal    `json:"cancel_upgrade,omitempty"`
	ChangeParameters *ChangeParametersProposal `json:"change_parameters,omitempty"`
}

ProposalContent is a consensus layer governance proposal content.

type ProposalExecutedEvent

type ProposalExecutedEvent struct {
	// ID is the unique identifier of a proposal.
	ID uint64 `json:"id"`
}

ProposalExecutedEvent is emitted when a proposal is executed.

type ProposalFinalizedEvent

type ProposalFinalizedEvent struct {
	// ID is the unique identifier of a proposal.
	ID uint64 `json:"id"`
	// State is the new proposal state.
	State ProposalState `json:"state"`
}

ProposalFinalizedEvent is the event emitted when a proposal is finalized.

type ProposalQuery

type ProposalQuery struct {
	Height     int64  `json:"height"`
	ProposalID uint64 `json:"id"`
}

ProposalQuery is a proposal query.

type ProposalState

type ProposalState uint8

ProposalState is the state of the proposal.

func (ProposalState) MarshalText

func (p ProposalState) MarshalText() ([]byte, error)

MarshalText encodes a ProposalState into text form.

func (ProposalState) String

func (p ProposalState) String() string

String returns a string representation of a ProposalState.

func (*ProposalState) UnmarshalText

func (p *ProposalState) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a ProposalState.

type ProposalSubmittedEvent

type ProposalSubmittedEvent struct {
	// ID is the unique identifier of a proposal.
	ID uint64 `json:"id"`
	// Submitter is the staking account address of the submitter.
	Submitter staking.Address `json:"submitter"`
}

ProposalSubmittedEvent is the event emitted when a new proposal is submitted.

type ProposalVote

type ProposalVote struct {
	// ID is the unique identifier of a proposal.
	ID uint64 `json:"id"`
	// Vote is the vote.
	Vote Vote `json:"vote"`
}

ProposalVote is a vote for a proposal.

type UpgradeProposal

type UpgradeProposal struct {
	upgrade.Descriptor
}

UpgradeProposal is an upgrade proposal.

type Vote

type Vote uint8

Vote is a governance vote.

func (Vote) MarshalText

func (v Vote) MarshalText() ([]byte, error)

MarshalText encodes a Vote into text form.

func (Vote) String

func (v Vote) String() string

String returns a string representation of a Vote.

func (*Vote) UnmarshalText

func (v *Vote) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a Vote.

type VoteEntry

type VoteEntry struct {
	Voter staking.Address `json:"voter"`
	Vote  Vote            `json:"vote"`
}

VoteEntry contains data about a cast vote.

type VoteEvent

type VoteEvent struct {
	// ID is the unique identifier of a proposal.
	ID uint64 `json:"id"`
	// Submitter is the staking account address of the vote submitter.
	Submitter staking.Address `json:"submitter"`
	// Vote is the cast vote.
	Vote Vote `json:"vote"`
}

VoteEvent is the event emitted when a vote is cast.