oracles

package
v0.72.0 Latest Latest
Warning

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

Go to latest
Published: Jul 6, 2023 License: MIT Imports: 16 Imported by: 0

README

Oracles

The Vega network runs on data. Market settlement, risk models, and other features require a supplied price (or other data), which must come from somewhere, often completely external to Vega. This necessitates the use of both internal and external data sources for a variety of purposes.

These external data sources are called oracles.

Any features that want to consume oracle data can specify conditions on the data they are expecting. This condition are defined inside an oracle spec.

Documentation

Index

Constants

View Source
const (
	BuiltinOraclePrefix    = "vegaprotocol.builtin"
	BuiltinOracleTimestamp = BuiltinOraclePrefix + ".timestamp"
)

Variables

View Source
var (
	// ErrMissingSigners is returned when the datapb.OracleSpec is missing
	// its signers.
	ErrMissingSigners = errors.New("signers are required")
	// ErrAtLeastOneFilterIsRequired is returned when the datapb.OracleSpec
	// has no expected properties nor filters. At least one of these should be
	// defined.
	ErrAtLeastOneFilterIsRequired = errors.New("at least one filter is required")
	// ErrInvalidTimestamp is returned when the timestamp has a negative value
	// which may happen in case of unsigned integer overflow.
	ErrInvalidTimestamp = errors.New("invalid timestamp")
	// ErrMissingPropertyKey is returned when a property key is undefined.
	ErrMissingPropertyKey = errors.New("a property key is required")
	// ErrMissingPropertyName is returned when a property as no name.
	ErrMissingPropertyName = errors.New("a property name is required")
	// ErrInvalidPropertyKey is returned if validation finds a reserved Vega property key.
	ErrInvalidPropertyKey = errors.New("property key is reserved")
)

Functions

This section is empty.

Types

type Broker

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

Broker interface. Do not need to mock (use package broker/mock).

type Builtin

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

func NewBuiltinOracle

func NewBuiltinOracle(engine *Engine, ts TimeService) *Builtin

func (*Builtin) OnTick

func (b *Builtin) OnTick(ctx context.Context, _ time.Time)

type Config

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

Config represent the configuration of the oracle engine.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates an instance of the package specific configuration, given a pointer to a logger instance to be used for logging within the package.

type Engine

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

Engine is responsible for broadcasting the OracleData to products and risk models interested in it.

func NewEngine

func NewEngine(
	log *logging.Logger,
	conf Config,
	ts TimeService,
	broker Broker,
) *Engine

NewEngine creates a new oracle Engine.

func (*Engine) BroadcastData

func (e *Engine) BroadcastData(ctx context.Context, data OracleData) error

BroadcastData broadcasts data to products and risk models that are interested in it. If no one is listening to this OracleData, it is discarded.

func (*Engine) HasMatch added in v0.55.0

func (e *Engine) HasMatch(data OracleData) (bool, error)

func (*Engine) ListensToSigners added in v0.61.0

func (e *Engine) ListensToSigners(data OracleData) bool

ListensToSigners checks if the signatures (pubkeys, ETH addresses) from provided OracleData are among the keys current OracleSpecs listen to.

func (*Engine) Subscribe

Subscribe registers a callback for a given OracleSpec that is called when an OracleData matches the spec. It returns a SubscriptionID that is used to Unsubscribe. If cb is nil, the method panics.

func (*Engine) Unsubscribe

func (e *Engine) Unsubscribe(ctx context.Context, id SubscriptionID)

Unsubscribe unregisters the callback associated to the SubscriptionID. If the id doesn't exist, this method panics.

type OnMatchedOracleData

type OnMatchedOracleData func(ctx context.Context, data OracleData) error

OnMatchedOracleData describes the callback function used when an oracle data matches the spec.

type OracleData

type OracleData struct {
	Signers []*types.Signer
	Data    map[string]string
}

OracleData holds normalized data coming from an oracle.

func (OracleData) Debug

func (d OracleData) Debug() []zap.Field

func (OracleData) FromInternalOracle

func (d OracleData) FromInternalOracle() bool

FromInternalOracle returns true if the oracle data has been emitted by an internal oracle.

func (OracleData) GetBoolean

func (d OracleData) GetBoolean(propertyName string) (bool, error)

GetBoolean converts the value associated to propertyName into a boolean.

func (OracleData) GetDecimal

func (d OracleData) GetDecimal(propertyName string) (num.Decimal, error)

GetDecimal converts the value associated to propertyName into a decimal.

func (OracleData) GetInteger

func (d OracleData) GetInteger(propertyName string) (*num.Int, error)

GetInteger converts the value associated to propertyName into an integer.

func (OracleData) GetString

func (d OracleData) GetString(propertyName string) (string, error)

GetString returns the value associated to propertyName.

func (OracleData) GetTimestamp

func (d OracleData) GetTimestamp(propertyName string) (int64, error)

GetTimestamp converts the value associated to propertyName into a timestamp.

func (OracleData) GetUint

func (d OracleData) GetUint(name string) (*num.Uint, error)

type OracleSpec

type OracleSpec struct {

	// OriginalSpec is the protobuf description of OracleSpec
	OriginalSpec *types.OracleSpec
	// contains filtered or unexported fields
}

func NewOracleSpec

func NewOracleSpec(originalSpec types.ExternalDataSourceSpec) (*OracleSpec, error)

NewOracleSpec builds an OracleSpec from a types.OracleSpec (currently uses one level below - types.ExternalDataSourceSpec) in a form that suits the processing of the filters. OracleSpec allows the existence of one and only one. Currently VEGA network utilises internal triggers in the oracle function path, even though the oracles are treated as external data sources. For this reason this function checks if the provided external type of data source definition contains a key name that indicates a builtin type of logic and if the given data source definition is an internal type of data source, for more context refer to https://github.com/vegaprotocol/specs/blob/master/protocol/0048-DSRI-data_source_internal.md#13-vega-time-changed

func (OracleSpec) EnsureBoundableProperty

func (s OracleSpec) EnsureBoundableProperty(property string, propType datapb.PropertyKey_Type) error

func (*OracleSpec) MatchData

func (s *OracleSpec) MatchData(data OracleData) (bool, error)

MatchData indicates if a given OracleData matches the spec or not.

func (*OracleSpec) MatchSigners added in v0.61.0

func (s *OracleSpec) MatchSigners(data OracleData) bool

MatchSigners tries to match the public keys from the provided OracleData object with the ones present in the Spec.

type OracleSpecID

type OracleSpecID string

type OracleSpecPredicate

type OracleSpecPredicate func(spec OracleSpec) (bool, error)

OracleSpecPredicate describes the predicate used to filter the subscribers. When returning true, all the subscribers associated to the matching OracleSpec are collected. The order between specs and subscribers is preserved.

type OracleSubscriptionPredicate

type OracleSubscriptionPredicate func(spec OracleSpec) bool

OracleSubscriptionPredicate describes the predicate used to check if any of the currently existing subscriptions expects the public keys inside the incoming OracleSpec object.

type SubscriptionID

type SubscriptionID uint64

SubscriptionID is a unique identifier referencing the subscription of an OnMatchedOracleData to an OracleSpec.

type TimeService

type TimeService interface {
	GetTimeNow() time.Time
}

TimeService interface.

type Unsubscriber

type Unsubscriber func(context.Context, SubscriptionID)

Unsubscriber is a closure that is created at subscription step in order to provide the ability to unsubscribe at any conveninent moment.

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