api

package
v0.2402.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2024 License: Apache-2.0 Imports: 18 Imported by: 4

Documentation

Overview

Package api implements the governance APIs.

Index

Constants

View Source 
const (
	// MinProposalTitleLength is the minimum length of a proposal's title.
	MinProposalTitleLength = 3
	// MaxProposalTitleLength is the maximum length of a proposal's title.
	MaxProposalTitleLength = 100
)
View Source 
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"
)
View Source 
const (
	StateActive   ProposalState = 1
	StatePassed   ProposalState = 2
	StateRejected ProposalState = 3
	StateFailed   ProposalState = 4

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

Proposal state kinds.

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

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

Vote kinds.

View Source 
const ModuleName = "governance"

ModuleName is a unique module name for the governance backend.

Variables

View Source 
var (
	// ErrInvalidArgument is the error returned on malformed argument(s).
	ErrInvalidArgument = errors.New(ModuleName, 1, "governance: invalid argument")
	// ErrUpgradeTooSoon is the error returned when an upgrade is not enough in the future.
	ErrUpgradeTooSoon = errors.New(ModuleName, 2, "governance: upgrade too soon")
	// ErrUpgradeAlreadyPending is the error returned when an upgrade is already pending.
	ErrUpgradeAlreadyPending = errors.New(ModuleName, 3, "governance: upgrade already pending")
	// ErrNoSuchUpgrade is the error returned when an upgrade does not exist.
	ErrNoSuchUpgrade = errors.New(ModuleName, 4, "governance: no such upgrade")
	// ErrNoSuchProposal is the error retrued when a proposal does not exist.
	ErrNoSuchProposal = errors.New(ModuleName, 5, "governance: no such proposal")
	// ErrNotEligible is the error returned when a vote caster is not eligible for a vote.
	ErrNotEligible = errors.New(ModuleName, 6, "governance: not eligible")
	// ErrVotingIsClosed is the error returned when a vote is cast for a non-active proposal.
	ErrVotingIsClosed = errors.New(ModuleName, 7, "governance: voting is closed")

	// MethodSubmitProposal submits a new consensus layer governance proposal.
	MethodSubmitProposal = transaction.NewMethodName(ModuleName, "SubmitProposal", ProposalContent{})
	// MethodCastVote casts a vote for a consensus layer governance proposal.
	MethodCastVote = transaction.NewMethodName(ModuleName, "CastVote", ProposalVote{})

	// Methods is the list of all methods supported by the governance backend.
	Methods = []transaction.MethodName{
		MethodSubmitProposal,
		MethodCastVote,
	}
)
View Source 
var DefaultGasCosts = transaction.Costs{
	GasOpSubmitProposal: 1000,
	GasOpCastVote:       1000,
}

DefaultGasCosts are the "default" gas costs for operations.

Functions

func NewCastVoteTx 

func NewCastVoteTx(nonce uint64, fee *transaction.Fee, vote *ProposalVote) *transaction.Transaction

NewCastVoteTx creates a new cast vote transaction.

func NewSubmitProposalTx 

func NewSubmitProposalTx(nonce uint64, fee *transaction.Fee, proposal *ProposalContent) *transaction.Transaction

NewSubmitProposalTx creates a new submit proposal transaction.

func PendingUpgradesFromProposals 

func PendingUpgradesFromProposals(proposals []*Proposal, epoch beacon.EpochTime) ([]*upgrade.Descriptor, []uint64)

PendingUpgradesFromProposals computes pending upgrades proposals state.

Returns pending upgrades and corresponding proposal IDs. This is useful for initialzing genesis state which doesn't include pending upgrades, as these can always be computed from accepted proposals.

func RegisterService 

func RegisterService(server *grpc.Server, service Backend)

RegisterService registers a new governance service with the given gRPC server.

func SanityCheckPendingUpgrades 

func SanityCheckPendingUpgrades(upgrades []*upgrade.Descriptor, epoch beacon.EpochTime, params *ConsensusParameters) error

SanityCheckPendingUpgrades sanity checks pending upgrades.

func SanityCheckProposals 

func SanityCheckProposals(proposals []*Proposal, epoch beacon.EpochTime, governanceDeposit *quantity.Quantity) error

SanityCheckProposals sanity checks proposals.

func SanityCheckVotes 

func SanityCheckVotes(proposal *Proposal, votes []*VoteEntry) error

SanityCheckVotes sanity checks votes for a proposal.

Types

type Backend 

type Backend interface {
	// ActiveProposals returns a list of all proposals that have not yet closed.
	ActiveProposals(ctx context.Context, height int64) ([]*Proposal, error)

	// Proposals returns a list of all proposals.
	Proposals(ctx context.Context, height int64) ([]*Proposal, error)

	// Proposal looks up a specific proposal.
	Proposal(ctx context.Context, query *ProposalQuery) (*Proposal, error)

	// Votes looks up votes for a specific proposal.
	Votes(ctx context.Context, query *ProposalQuery) ([]*VoteEntry, error)

	// PendingUpgrades returns a list of all pending upgrades.
	PendingUpgrades(ctx context.Context, height int64) ([]*upgrade.Descriptor, error)

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(ctx context.Context, height int64) (*Genesis, error)

	// ConsensusParameters returns the governance consensus parameters.
	ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)

	// GetEvents returns the events at specified block height.
	GetEvents(ctx context.Context, height int64) ([]*Event, error)

	// WatchEvents returns a channel that produces a stream of Events.
	WatchEvents(ctx context.Context) (<-chan *Event, pubsub.ClosableSubscription, error)

	// Cleanup cleans up the backend.
	Cleanup()
}

Backend is a governance implementation.

func NewGovernanceClient 

func NewGovernanceClient(c *grpc.ClientConn) Backend

NewGovernanceClient creates a new gRPC governance client service.

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.

func (*CancelUpgradeProposal) Equals added in v0.2202.0 

func (cu *CancelUpgradeProposal) Equals(other *CancelUpgradeProposal) bool

Equals checks if cancel upgrade proposals are equal.

func (CancelUpgradeProposal) PrettyPrint 

func (cu CancelUpgradeProposal) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of CancelUpgradeProposal to the given writer.

func (CancelUpgradeProposal) PrettyType 

func (cu CancelUpgradeProposal) PrettyType() (interface{}, error)

PrettyType returns a representation of CancelUpgradeProposal that can be used for pretty printing.

type ChangeParametersProposal added in v0.2202.0 

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.

func (*ChangeParametersProposal) Equals added in v0.2202.0 

func (p *ChangeParametersProposal) Equals(other *ChangeParametersProposal) bool

Equals checks if change parameters proposals are equal.

func (*ChangeParametersProposal) PrettyPrint added in v0.2202.0 

func (p *ChangeParametersProposal) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of ChangeParametersProposal to the given writer.

func (*ChangeParametersProposal) PrettyType added in v0.2202.0 

func (p *ChangeParametersProposal) PrettyType() (interface{}, error)

PrettyType returns a representation of ChangeParametersProposal that can be used for pretty printing.

func (*ChangeParametersProposal) ValidateBasic added in v0.2202.0 

func (p *ChangeParametersProposal) ValidateBasic() error

ValidateBasic performs a basic validation on the change parameters proposal.

type ConsensusParameterChanges added in v0.2202.0 

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.

func (*ConsensusParameterChanges) Apply added in v0.2202.0 

func (c *ConsensusParameterChanges) Apply(params *ConsensusParameters) error

Apply applies changes to the given consensus parameters.

func (*ConsensusParameterChanges) SanityCheck added in v0.2202.0 

func (c *ConsensusParameterChanges) SanityCheck() error

SanityCheck performs a sanity check on the 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"`

	// AllowVoteWithoutEntity is true iff casting votes without a registered entity is allowed.
	AllowVoteWithoutEntity bool `json:"allow_vote_without_entity,omitempty"`

	// AllowProposalMetadata is true iff proposals are allowed to contain metadata.
	AllowProposalMetadata bool `json:"allow_proposal_metadata,omitempty"`
}

ConsensusParameters are the governance consensus parameters.

func (*ConsensusParameters) SanityCheck 

func (p *ConsensusParameters) SanityCheck() error

SanityCheck performs a sanity check on the 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.

func (*Genesis) SanityCheck 

func (g *Genesis) SanityCheck(now beacon.EpochTime, governanceDeposits *quantity.Quantity) error

SanityCheck does basic sanity checking on the genesis state.

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.

func (*Proposal) CloseProposal 

func (p *Proposal) CloseProposal(totalVotingStake quantity.Quantity, stakeThreshold uint8) error

CloseProposal closes an active proposal based on the vote results and specified voting parameters.

The proposal is accepted iff the percentage of yes votes relative to total voting power is at least `stakeThreshold`. Otherwise the proposal is rejected.

func (*Proposal) VotedSum 

func (p *Proposal) VotedSum() (*quantity.Quantity, error)

VotedSum returns the sum of all votes.

type ProposalContent 

type ProposalContent struct {
	// Metadata contains optional proposal metadata which is ignored during proposal execution.
	Metadata *ProposalMetadata `json:"metadata,omitempty"`

	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.

func (*ProposalContent) Equals 

func (p *ProposalContent) Equals(other *ProposalContent) bool

Equals checks if proposal contents are equal.

Note: this assumes valid proposals where each proposals will have exactly one field set.

func (ProposalContent) PrettyPrint 

func (p ProposalContent) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of ProposalContent to the given writer.

func (ProposalContent) PrettyType 

func (p ProposalContent) PrettyType() (interface{}, error)

PrettyType returns a representation of ProposalContent that can be used for pretty printing.

func (*ProposalContent) ValidateBasic 

func (p *ProposalContent) ValidateBasic(params *ConsensusParameters) error

ValidateBasic performs basic proposal content validity checks.

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.

func (*ProposalExecutedEvent) EventKind added in v0.2102.2 

func (e *ProposalExecutedEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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.

func (*ProposalFinalizedEvent) EventKind added in v0.2102.2 

func (e *ProposalFinalizedEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type ProposalMetadata added in v0.2400.0 

type ProposalMetadata struct {
	// Title is the human-readable proposal title.
	Title string `json:"title"`
	// Description is the human-readable description.
	Description string `json:"description,omitempty"`
}

ProposalMetadata contains metadata about a proposal.

func (ProposalMetadata) PrettyPrint added in v0.2400.0 

func (p ProposalMetadata) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of ProposalMetadata to the given writer.

func (ProposalMetadata) PrettyType added in v0.2400.0 

func (p ProposalMetadata) PrettyType() (interface{}, error)

PrettyType returns a representation of ProposalMetadata that can be used for pretty printing.

func (*ProposalMetadata) ValidateBasic added in v0.2400.0 

func (p *ProposalMetadata) ValidateBasic() error

ValidateBasic performs basic proposal metadata validity checks.

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.

func (*ProposalSubmittedEvent) EventKind added in v0.2102.2 

func (e *ProposalSubmittedEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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.

func (ProposalVote) PrettyPrint 

func (pv ProposalVote) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of ProposalVote to the given writer.

func (ProposalVote) PrettyType 

func (pv ProposalVote) PrettyType() (interface{}, error)

PrettyType returns a representation of ProposalVote that can be used for pretty printing.

type UpgradeProposal 

type UpgradeProposal struct {
	upgrade.Descriptor
}

UpgradeProposal is an upgrade proposal.

func (*UpgradeProposal) Equals added in v0.2202.0 

func (u *UpgradeProposal) Equals(other *UpgradeProposal) bool

Equals checks if upgrade proposals are equal.

func (UpgradeProposal) PrettyPrint 

func (u UpgradeProposal) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of UpgradeProposal to the given writer.

func (UpgradeProposal) PrettyType 

func (u UpgradeProposal) PrettyType() (interface{}, error)

PrettyType returns a representation of UpgradeProposal that can be used for pretty printing.

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.

func (*VoteEvent) EventKind added in v0.2102.2 

func (e *VoteEvent) EventKind() string

EventKind returns a string representation of this event's kind.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.