governance

package
v0.78.0-preview.2 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2024 License: AGPL-3.0 Imports: 36 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")
	ErrSettlementDataOutOfRange                  = errors.New("the settlement data is invalid")
)
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")
	ErrMaxPriceInvalid                       = errors.New("max price for capped future must be greater than zero")
)
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
	ValidateEthereumAddress(address, chainID string) error
}

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
	ValidateSettlementData(mktID string, data *num.Uint) 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) IsNodeValidationRequiredBatch added in v0.76.0 

func (n *NodeValidation) IsNodeValidationRequiredBatch(p *types.BatchProposal) (is bool)

func (*NodeValidation) OnTick 

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

OnTick returns validated proposal by all nodes.

func (*NodeValidation) OnTickBatch added in v0.76.0 

func (n *NodeValidation) OnTickBatch(t time.Time) (accepted []*batchProposal, rejected []*batchProposal)

OnTickBatch 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.

func (*NodeValidation) StartBatch added in v0.76.0 

func (n *NodeValidation) StartBatch(ctx context.Context, p *types.BatchProposal) 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) IsVolumeRebateProgramUpdate added in v0.77.8 

func (t ToEnact) IsVolumeRebateProgramUpdate() 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

func (*ToEnact) VolumeRebateProgramUpdate added in v0.77.8 

func (t *ToEnact) VolumeRebateProgramUpdate() *types.VolumeRebateProgram

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 ...

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.