api

package
v0.2103.1 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2021 License: Apache-2.0 Imports: 15 Imported by: 4

Documentation

Overview

Package api implements the governance APIs.

Index

Constants

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.

View Source 
const ProposalContentInvalidText = "(invalid)"

ProposalContentInvalidText is the textual representation of an invalid ProposalContent.

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) PrettyPrint 

func (cu CancelUpgradeProposal) PrettyPrint(ctx 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 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"`

	// Quorum is he minimum percentage of voting power that needs to be cast on
	// a proposal for the result to be valid.
	Quorum uint8 `json:"quorum,omitempty"`

	// Threshold is the minimum percentage of VoteYes votes in order for a
	// proposal to be accepted.
	Threshold uint8 `json:"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"`
}

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, quorum, threshold uint8) error

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

The proposal is accepted if:

  • percentage of votes relative to total voting power is at least `quorum`
  • and percentage of yes votes relative to all votes is at least `threshold`

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 {
	Upgrade       *UpgradeProposal       `json:"upgrade,omitempty"`
	CancelUpgrade *CancelUpgradeProposal `json:"cancel_upgrade,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() 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 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(ctx 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) 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.