governance

package
v0.75.8 Latest Latest
Warning

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

Go to latest
Published: Apr 3, 2024 License: AGPL-3.0 Imports: 35 Imported by: 0

README

Governance engine

The governance engine receives proposals that have passed through consensus (meaning they come from the chain). For each block, the OnChainTimeUpdate function is called, which will have the engine check currently active proposals to see if the voting period for these proposals has expired. Once the voting period has expired, the engine will check to see if the proposal was accepted or rejected. Rejected proposals, obviously, have reached the end of their useful lives. Accepted ones, however, are fed back into the execution engine to be enacted.

Votes will also be fed into this engine. Votes are expected to be cast on proposals by ID (a vote can only be cast on a proposal once it's considered valid). We track all votes (yes/no votes).

Dependencies

The Governance engine needs to be able to check the accounts of parties (seeing how many tokens a given party has, and how many total tokens are in the system). This information is currently accessible through the collateral engine.

To expose the proposals API (gRPC), we'll create a buffer which will allow the governance service to stream updates regarding proposals over a gRPC call, should this be required.

Accepted proposals

Accepted proposals are returned from the OnChainTimeUpdate call, for the execution engine to act on them.

Convenience

For the governance service to more easily return the requested data (e.g. GetProposalByReference), there are some convenience functions available to expose active proposals by reference and id.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrProposalDoesNotExist                      = errors.New("proposal does not exist")
	ErrMarketDoesNotExist                        = errors.New("market does not exist")
	ErrMarketStateUpdateNotAllowed               = errors.New("market state does not allow for state update")
	ErrMarketProposalStillOpen                   = errors.New("original market proposal is still open")
	ErrProposalNotOpenForVotes                   = errors.New("proposal is not open for votes")
	ErrProposalIsDuplicate                       = errors.New("proposal with given ID already exists")
	ErrVoterInsufficientTokensAndEquityLikeShare = errors.New("vote requires tokens or equity-like share")
	ErrVoterInsufficientTokens                   = errors.New("vote requires more tokens than the party has")
	ErrUnsupportedProposalType                   = errors.New("unsupported proposal type")
	ErrUnsupportedAssetSourceType                = errors.New("unsupported asset source type")
	ErrExpectedERC20Asset                        = errors.New("expected an ERC20 asset but was not")
	ErrErc20AddressAlreadyInUse                  = errors.New("erc20 address already in use")
	ErrParentMarketDoesNotExist                  = errors.New("market to succeed does not exist")
	ErrParentMarketAlreadySucceeded              = errors.New("the parent market was already succeeded by a prior proposal")
	ErrParentMarketSucceededByCompeting          = errors.New("the parent market has been succeeded by a competing propsal")
)
View Source
var (
	// ErrMissingProduct is returned if selected product is nil.
	ErrMissingProduct = errors.New("missing product")
	// ErrUnsupportedProduct is returned if selected product is not supported.
	ErrUnsupportedProduct = errors.New("product type is not supported")
	// ErrUnsupportedRiskParameters is returned if risk parameters supplied via governance are not yet supported.
	ErrUnsupportedRiskParameters = errors.New("risk model parameters are not supported")
	// ErrMissingRiskParameters ...
	ErrMissingRiskParameters = errors.New("missing risk parameters")
	// ErrMissingDataSourceSpecBinding is returned when the data source spec binding is absent.
	ErrMissingDataSourceSpecBinding = errors.New("missing data source spec binding")
	// ErrMissingDataSourceSpecForSettlementData is returned when the data source spec for settlement data is absent.
	ErrMissingDataSourceSpecForSettlementData = errors.New("missing data source spec for settlement data")
	// ErrMissingDataSourceSpecForSettlementData is returned when the data source spec for settlement data is absent.
	ErrSettlementWithInternalDataSourceIsNotAllowed = errors.New("settlement with internal data source is not allwed")
	// ErrMissingDataSourceSpecForTradingTermination is returned when the data source spec for trading termination is absent.
	ErrMissingDataSourceSpecForTradingTermination = errors.New("missing data source spec for trading termination")
	// ErrMissingDataSourceSpecForSettlementSchedule is returned when the data source spec for trading termination is absent.
	ErrMissingDataSourceSpecForSettlementSchedule = errors.New("missing data source spec for settlement schedule")
	// ErrInternalTimeTriggerForFuturesInNotAllowed is returned when a proposal containing timetrigger terminaiton type of data is received.
	ErrInternalTimeTriggerForFuturesInNotAllowed = errors.New("setting internal time trigger for future termination is not allowed")
	// ErrDataSourceSpecTerminationTimeBeforeEnactment is returned when termination time is before enactment
	// for time triggered termination condition.
	ErrDataSourceSpecTerminationTimeBeforeEnactment = errors.New("data source spec termination time before enactment")
	// ErrMissingPerpsProduct is returned when perps product is absent from the instrument.
	ErrMissingPerpsProduct = errors.New("missing perps product")
	// ErrMissingFutureProduct is returned when future product is absent from the instrument.
	ErrMissingFutureProduct = errors.New("missing future product")
	// ErrMissingSpotProduct is returned when spot product is absent from the instrument.
	ErrMissingSpotProduct = errors.New("missing spot product")
	// ErrInvalidRiskParameter ...
	ErrInvalidRiskParameter = errors.New("invalid risk parameter")
	// ErrInvalidInsurancePoolFraction is returned if the insurance pool fraction parameter is outside of the 0-1 range.
	ErrInvalidInsurancePoolFraction          = errors.New("insurnace pool fraction invalid")
	ErrUpdateMarketDifferentProduct          = errors.New("cannot update a market to a different product type")
	ErrInvalidEVMChainIDInEthereumOracleSpec = errors.New("invalid source chain id in ethereum oracle spec")
)
View Source
var (
	ErrEmptyNetParamKey   = errors.New("empty network parameter key")
	ErrEmptyNetParamValue = errors.New("empty network parameter value")
)
View Source
var (
	ErrNoNodeValidationRequired                = errors.New("no node validation required")
	ErrProposalReferenceDuplicate              = errors.New("proposal duplicate")
	ErrProposalValidationTimestampTooLate      = errors.New("proposal validation timestamp must be earlier than closing time")
	ErrProposalValidationTimestampOutsideRange = fmt.Errorf("proposal validation timestamp must be within %d-%d seconds from submission time", minValidationPeriod, maxValidationPeriod)
)

Functions

This section is empty.

Types

type Assets

type Assets interface {
	NewAsset(ctx context.Context, ref string, assetDetails *types.AssetDetails) (string, error)
	Get(assetID string) (*assets.Asset, error)
	IsEnabled(string) bool
	SetRejected(ctx context.Context, assetID string) error
	SetPendingListing(ctx context.Context, assetID string) error
	ValidateAsset(assetID string) error
	ExistsForEthereumAddress(address string) bool
}

type Banking added in v0.72.0

type Banking interface {
	VerifyGovernanceTransfer(transfer *types.NewTransferConfiguration) error
	VerifyCancelGovernanceTransfer(transferID string) error
}

type Broker

type Broker interface {
	Send(e events.Event)
	SendBatch(es []events.Event)
}

Broker - event bus.

type Config

type Config struct {
	// logging level
	Level encoding.LogLevel `long:"log-level"`
}

Config represents governance specific configuration.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates an instance of the package specific configuration.

type Engine

type Engine struct {
	Config
	// contains filtered or unexported fields
}

Engine is the governance engine that handles proposal and vote lifecycle.

func NewEngine

func NewEngine(
	log *logging.Logger,
	cfg Config,
	accs StakingAccounts,
	tm TimeService,
	broker Broker,
	assets Assets,
	witness Witness,
	markets Markets,
	netp NetParams,
	banking Banking,
) *Engine

func (*Engine) AddVote

func (e *Engine) AddVote(ctx context.Context, cmd types.VoteSubmission, party string) error

AddVote adds a vote onto an existing active proposal.

func (*Engine) Checkpoint

func (e *Engine) Checkpoint() ([]byte, error)

func (*Engine) FinaliseEnactment

func (e *Engine) FinaliseEnactment(ctx context.Context, prop *types.Proposal)

FinaliseEnactment receives the enact proposal and updates the state in our enactedProposal list to have the current state of the proposals. This is entirely so that when we restore from a snapshot we can propagate the proposal with the latest state back into the API service.

func (*Engine) GetState

func (e *Engine) GetState(k string) ([]byte, []types.StateProvider, error)

func (*Engine) Hash

func (e *Engine) Hash() []byte

func (*Engine) Keys

func (e *Engine) Keys() []string

func (*Engine) Load

func (e *Engine) Load(ctx context.Context, data []byte) error

func (*Engine) LoadState

func (e *Engine) LoadState(ctx context.Context, p *types.Payload) ([]types.StateProvider, error)

func (*Engine) Name

func (e *Engine) Name() types.CheckpointName

func (*Engine) Namespace

func (e *Engine) Namespace() types.SnapshotNamespace

func (*Engine) OnChainIDUpdate added in v0.74.0

func (e *Engine) OnChainIDUpdate(cID uint64) error

func (*Engine) OnStateLoaded added in v0.72.8

func (e *Engine) OnStateLoaded(ctx context.Context) error

func (*Engine) OnTick

func (e *Engine) OnTick(ctx context.Context, t time.Time) ([]*ToEnact, []*VoteClosed)

func (*Engine) RejectBatchProposal added in v0.74.0

func (e *Engine) RejectBatchProposal(
	ctx context.Context, proposalID string, r types.ProposalError, errorDetails error,
) error

func (*Engine) RejectProposal

func (e *Engine) RejectProposal(
	ctx context.Context, p *types.Proposal, r types.ProposalError, errorDetails error,
) error

func (*Engine) ReloadConf

func (e *Engine) ReloadConf(cfg Config)

ReloadConf updates the internal configuration of the governance engine.

func (*Engine) Stopped

func (e *Engine) Stopped() bool

func (*Engine) SubmitBatchProposal added in v0.74.0

func (e *Engine) SubmitBatchProposal(
	ctx context.Context,
	bpsub types.BatchProposalSubmission,
	batchID, party string,
) ([]*ToSubmit, error)

func (*Engine) SubmitProposal

func (e *Engine) SubmitProposal(
	ctx context.Context,
	psub types.ProposalSubmission,
	id, party string,
) (ts *ToSubmit, err error)

SubmitProposal submits new proposal to the governance engine so it can be voted on, passed and enacted. Only open can be submitted and validated at this point. No further validation happens.

func (*Engine) ValidatorKeyChanged

func (e *Engine) ValidatorKeyChanged(ctx context.Context, oldKey, newKey string)

type Markets

type Markets interface {
	MarketExists(market string) bool
	GetMarket(market string, settled bool) (types.Market, bool)
	GetMarketState(market string) (types.MarketState, error)
	GetEquityLikeShareForMarketAndParty(market, party string) (num.Decimal, bool)
	RestoreMarket(ctx context.Context, marketConfig *types.Market) error
	StartOpeningAuction(ctx context.Context, marketID string) error
	UpdateMarket(ctx context.Context, marketConfig *types.Market) error
	IsSucceeded(mktID string) bool
}

Markets allows to get the market data for use in the market update proposal computation.

type NetParams

type NetParams interface {
	Validate(string, string) error
	Update(context.Context, string, string) error
	GetDecimal(string) (num.Decimal, error)
	GetInt(string) (int64, error)
	GetUint(string) (*num.Uint, error)
	GetDuration(string) (time.Duration, error)
	GetJSONStruct(string, netparams.Reset) error
	Get(string) (string, error)
}

type NewMarketVoteClosed

type NewMarketVoteClosed struct {
	// contains filtered or unexported fields
}

func (*NewMarketVoteClosed) Rejected

func (t *NewMarketVoteClosed) Rejected() bool

func (*NewMarketVoteClosed) StartAuction

func (t *NewMarketVoteClosed) StartAuction() bool

type NodeValidation

type NodeValidation struct {
	// contains filtered or unexported fields
}

func NewNodeValidation

func NewNodeValidation(
	log *logging.Logger,
	assets Assets,
	now time.Time,
	witness Witness,
) *NodeValidation

func (*NodeValidation) Hash

func (n *NodeValidation) Hash() []byte

func (*NodeValidation) IsNodeValidationRequired

func (n *NodeValidation) IsNodeValidationRequired(p *types.Proposal) bool

IsNodeValidationRequired returns true if the given proposal require validation from a node.

func (*NodeValidation) OnTick

func (n *NodeValidation) OnTick(t time.Time) (accepted []*proposal, rejected []*proposal)

OnTick returns validated proposal by all nodes.

func (*NodeValidation) Start

func (n *NodeValidation) Start(ctx context.Context, p *types.Proposal) error

Start the node validation of a proposal.

type StakingAccounts

type StakingAccounts interface {
	GetAvailableBalance(party string) (*num.Uint, error)
	GetStakingAssetTotalSupply() *num.Uint
}

StakingAccounts ...

type TimeService

type TimeService interface {
	GetTimeNow() time.Time
}

TimeService ...

type ToEnact

type ToEnact struct {
	// contains filtered or unexported fields
}

ToEnact wraps the proposal in a type that has a convenient interface to quickly work out what change we're dealing with, and get the data.

func (*ToEnact) CancelTransfer added in v0.72.0

func (t *ToEnact) CancelTransfer() *ToEnactCancelTransfer

func (ToEnact) IsCancelTransfer added in v0.72.0

func (t ToEnact) IsCancelTransfer() bool

func (ToEnact) IsFreeform

func (t ToEnact) IsFreeform() bool

func (ToEnact) IsMarketStateUpdate added in v0.73.0

func (t ToEnact) IsMarketStateUpdate() bool

func (ToEnact) IsNewAsset

func (t ToEnact) IsNewAsset() bool

func (ToEnact) IsNewAssetDetails

func (t ToEnact) IsNewAssetDetails() bool

func (ToEnact) IsNewMarket

func (t ToEnact) IsNewMarket() bool

func (ToEnact) IsNewSpotMarket added in v0.72.0

func (t ToEnact) IsNewSpotMarket() bool

func (ToEnact) IsNewTransfer added in v0.72.0

func (t ToEnact) IsNewTransfer() bool

func (ToEnact) IsReferralProgramUpdate added in v0.73.0

func (t ToEnact) IsReferralProgramUpdate() bool

func (*ToEnact) IsUpdateAsset

func (t *ToEnact) IsUpdateAsset() bool

func (ToEnact) IsUpdateMarket

func (t ToEnact) IsUpdateMarket() bool

func (ToEnact) IsUpdateNetworkParameter

func (t ToEnact) IsUpdateNetworkParameter() bool

func (ToEnact) IsUpdateSpotMarket added in v0.72.0

func (t ToEnact) IsUpdateSpotMarket() bool

func (ToEnact) IsVolumeDiscountProgramUpdate added in v0.73.0

func (t ToEnact) IsVolumeDiscountProgramUpdate() bool

func (*ToEnact) MarketStateUpdate added in v0.73.0

func (t *ToEnact) MarketStateUpdate() *ToEnactMarketStateUpdate

func (*ToEnact) NewAsset

func (t *ToEnact) NewAsset() *types.Asset

func (*ToEnact) NewAssetDetails

func (t *ToEnact) NewAssetDetails() *types.AssetDetails

func (*ToEnact) NewFreeform

func (t *ToEnact) NewFreeform() *ToEnactFreeform

func (*ToEnact) NewMarket

func (t *ToEnact) NewMarket() *ToEnactNewMarket

func (*ToEnact) NewTransfer added in v0.72.0

func (t *ToEnact) NewTransfer() *ToEnactTransfer

func (*ToEnact) Proposal

func (t *ToEnact) Proposal() *types.Proposal

func (*ToEnact) ProposalData

func (t *ToEnact) ProposalData() *proposal

func (*ToEnact) ReferralProgramChanges added in v0.73.0

func (t *ToEnact) ReferralProgramChanges() *types.ReferralProgram

func (*ToEnact) UpdateAsset

func (t *ToEnact) UpdateAsset() *types.Asset

func (*ToEnact) UpdateMarket

func (t *ToEnact) UpdateMarket() *types.Market

func (*ToEnact) UpdateNetworkParameter

func (t *ToEnact) UpdateNetworkParameter() *types.NetworkParameter

func (*ToEnact) UpdateSpotMarket added in v0.72.0

func (t *ToEnact) UpdateSpotMarket() *types.Market

func (*ToEnact) VolumeDiscountProgramUpdate added in v0.73.0

func (t *ToEnact) VolumeDiscountProgramUpdate() *types.VolumeDiscountProgram

type ToEnactCancelTransfer added in v0.72.0

type ToEnactCancelTransfer struct{}

type ToEnactFreeform

type ToEnactFreeform struct{}

ToEnactFreeform there is nothing to enact with a freeform proposal.

type ToEnactMarketStateUpdate added in v0.73.0

type ToEnactMarketStateUpdate struct{}

type ToEnactNewMarket

type ToEnactNewMarket struct{}

ToEnactNewMarket is just a empty struct, to signal an enacted market. nothing to be done with it for now (later maybe add information to check end of opening auction or so).

type ToEnactNewSpotMarket added in v0.72.0

type ToEnactNewSpotMarket struct{}

type ToEnactTransfer added in v0.72.0

type ToEnactTransfer struct{}

type ToSubmit

type ToSubmit struct {
	// contains filtered or unexported fields
}

ToSubmit wraps the proposal in a type that has a convenient interface to quickly work out what change we're dealing with, and get the data This cover every kind of proposal which requires action after a proposal is submitted.

func (*ToSubmit) InsurancePoolFraction added in v0.72.0

func (t *ToSubmit) InsurancePoolFraction() *num.Decimal

func (ToSubmit) IsNewMarket

func (t ToSubmit) IsNewMarket() bool

func (ToSubmit) IsNewSpotMarket added in v0.72.0

func (t ToSubmit) IsNewSpotMarket() bool

func (*ToSubmit) NewMarket

func (t *ToSubmit) NewMarket() *ToSubmitNewMarket

func (*ToSubmit) NewSpotMarket added in v0.72.0

func (t *ToSubmit) NewSpotMarket() *ToSubmitNewSpotMarket

func (*ToSubmit) ParentMarketID added in v0.72.0

func (t *ToSubmit) ParentMarketID() string

func (*ToSubmit) Proposal

func (t *ToSubmit) Proposal() *types.Proposal

type ToSubmitNewMarket

type ToSubmitNewMarket struct {
	// contains filtered or unexported fields
}

func (*ToSubmitNewMarket) Market

func (t *ToSubmitNewMarket) Market() *types.Market

func (*ToSubmitNewMarket) OpeningAuctionStart added in v0.72.0

func (t *ToSubmitNewMarket) OpeningAuctionStart() time.Time

type ToSubmitNewSpotMarket added in v0.72.0

type ToSubmitNewSpotMarket struct {
	// contains filtered or unexported fields
}

func (*ToSubmitNewSpotMarket) Market added in v0.72.0

func (t *ToSubmitNewSpotMarket) Market() *types.Market

type VoteClosed

type VoteClosed struct {
	// contains filtered or unexported fields
}

func (*VoteClosed) IsNewMarket

func (t *VoteClosed) IsNewMarket() bool

func (*VoteClosed) NewMarket

func (t *VoteClosed) NewMarket() *NewMarketVoteClosed

func (*VoteClosed) Proposal

func (t *VoteClosed) Proposal() *types.Proposal

type Witness

type Witness interface {
	StartCheck(validators.Resource, func(interface{}, bool), time.Time) error
	RestoreResource(validators.Resource, func(interface{}, bool)) error
}

Witness ...

Directories

Path Synopsis
Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL