oracles

package
v0.0.0-...-f6bc33c Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2023 License: MIT Imports: 16 Imported by: 0

README

Oracles

The Zeta 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 Zeta. 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    = "zetaprotocol.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 Zeta 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 

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

func (*Engine) ListensToSigners 

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 

func (e *Engine) Subscribe(ctx context.Context, spec OracleSpec, cb OnMatchedOracleData) (SubscriptionID, Unsubscriber)

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 ZETA 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/zetaprotocol/specs/blob/master/protocol/0048-DSRI-data_source_internal.md#13-zeta-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 

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.

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.