oracle

README

Oracle

Responsibilities of the Oracle:

• Spinning up the necessary services (e.g. the sidecar, the price fetchers, etc.).
• Managing the lifecycle of the providers.
• Determining the set of markets that need to be fetched and updating the providers accordingly.

Configuration

At a high level the oracle is configured with a oracle.json file that contains all providers that need to be instantiated. To read more about the configuration of oracle.json, please refer to the oracle configuration documentation.

Each provider is instantiated using the PriceAPIQueryHandlerFactory, PriceWebSocketQueryHandlerFactory, and MarketMapFactory factory functions. Think of these as the constructors for the providers.

• PriceAPIQueryHandlerFactory - This is used to create the API query handler for the provider - which is then passed into a base provider.
• PriceWebSocketQueryHandlerFactory - This is used to create the WebSocket query handler for the provider - which is then passed into a base provider.
• MarketMapFactory - This is used to create the market map provider.

Lifecycle

The oracle can be initialized with an option of WithMarketMap which allows each provider to be instantiated with a predetermined set of markets. If this option is not provided, the oracle will fetch the markets from the market map provider. Both options can be set.

The oracle will then start each provider in a separate goroutine. Additionally, if the oracle has a market map provider, it will start a goroutine that will periodically fetch the markets from the market map provider and update the providers accordingly.

All providers are running concurrently and will do so until the main context is canceled (what is passed into Start). If the oracle is canceled, it will cancel all providers and wait for them to finish before returning.

Documentation

Index

• type Option
  • func WithLastUpdated(lastUpdated uint64) Option
  • func WithLogger(logger *zap.Logger) Option
  • func WithMarketMap(marketMap mmtypes.MarketMap) Option
  • func WithMarketMapperFactory(factory mmclienttypes.MarketMapFactory) Option
  • func WithMetrics(met oraclemetrics.Metrics) Option
  • func WithPriceAPIQueryHandlerFactory(factory types.PriceAPIQueryHandlerFactory) Option
  • func WithPriceProviders(pps ...*types.PriceProvider) Option
  • func WithPriceWebSocketQueryHandlerFactory(factory types.PriceWebSocketQueryHandlerFactory) Option
  • func WithWriteTo(filePath string) Option
• type Oracle
  • func New(cfg config.OracleConfig, aggregator PriceAggregator, opts ...Option) (Oracle, error)
• type OracleImpl
  • func (o *OracleImpl) GetLastSyncTime() time.Time
  • func (o *OracleImpl) GetMarketMap() mmtypes.MarketMap
  • func (o *OracleImpl) GetMarketMapProvider() *mmclienttypes.MarketMapProvider
  • func (o *OracleImpl) GetPrices() types.Prices
  • func (o *OracleImpl) GetProviderState() map[string]ProviderState
  • func (o *OracleImpl) Init(ctx context.Context) error
  • func (o *OracleImpl) IsMarketMapValidUpdated(resp *mmtypes.MarketMapResponse) (mmtypes.MarketMap, bool, error)
  • func (o *OracleImpl) IsRunning() bool
  • func (o *OracleImpl) Start(ctx context.Context) error
  • func (o *OracleImpl) Stop()
  • func (o *OracleImpl) UpdateMarketMap(marketMap mmtypes.MarketMap) error
  • func (o *OracleImpl) UpdateProviderState(providerTickers []types.ProviderTicker, state ProviderState) (ProviderState, error)
  • func (o *OracleImpl) WriteMarketMap() error
• type PriceAggregator
• type ProviderState

Types

type Option

type Option func(impl *OracleImpl)

Option is a functional option for the market map state.

func WithLastUpdated

func WithLastUpdated(lastUpdated uint64) Option

WithLastUpdated sets the last updated for the oracle.

func WithLogger

func WithLogger(logger *zap.Logger) Option

WithLogger sets the logger for the oracle.

func WithMarketMap

func WithMarketMap(marketMap mmtypes.MarketMap) Option

WithMarketMap sets the market map for the oracle.

func WithMarketMapperFactory

func WithMarketMapperFactory(factory mmclienttypes.MarketMapFactory) Option

WithMarketMapperFactory sets the market map factory for the oracle. Specifically, this is what is utilized to construct market map providers.

func WithMetrics

func WithMetrics(met oraclemetrics.Metrics) Option

WithMetrics sets the metrics service the Oracle will use to emit metrics.

func WithPriceAPIQueryHandlerFactory

func WithPriceAPIQueryHandlerFactory(factory types.PriceAPIQueryHandlerFactory) Option

WithPriceAPIQueryHandlerFactory sets the Price API query handler factory for the oracle. Specifically, this is what is utilized to construct price providers that are API based.

func WithPriceProviders

func WithPriceProviders(pps ...*types.PriceProvider) Option

WithPriceProviders allows pre-instantiated price providers to be used in the Oracle's price fetching loop. This option is mainly used for testing, but can be useful for programmatically setting customized providers.

func WithPriceWebSocketQueryHandlerFactory

func WithPriceWebSocketQueryHandlerFactory(factory types.PriceWebSocketQueryHandlerFactory) Option

WithPriceWebSocketQueryHandlerFactory sets the websocket query handler factory for the oracle. Specifically, this is what is utilized to construct price providers that are websocket based.

func WithWriteTo

func WithWriteTo(filePath string) Option

WithWriteTo sets the file path to which market map updates will be written to. Note that this is optional.

type Oracle

type Oracle interface {
	IsRunning() bool
	GetLastSyncTime() time.Time
	GetPrices() types.Prices
	GetMarketMap() mmtypes.MarketMap
	Start(ctx context.Context) error
	Stop()
}

Oracle defines the expected interface for an oracle. It is consumed by the oracle server.

func New

func New(
	cfg config.OracleConfig,
	aggregator PriceAggregator,
	opts ...Option,
) (Oracle, error)

New returns a new Oracle.

type OracleImpl

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

OracleImpl maintains providers and the state provided by them. This includes pricing data and market map updates.

func (*OracleImpl) GetLastSyncTime

func (o *OracleImpl) GetLastSyncTime() time.Time

func (*OracleImpl) GetMarketMap

func (o *OracleImpl) GetMarketMap() mmtypes.MarketMap

GetMarketMap returns the market map.

func (*OracleImpl) GetMarketMapProvider

func (o *OracleImpl) GetMarketMapProvider() *mmclienttypes.MarketMapProvider

func (*OracleImpl) GetPrices

func (o *OracleImpl) GetPrices() types.Prices

func (*OracleImpl) GetProviderState

func (o *OracleImpl) GetProviderState() map[string]ProviderState

GetProviderState returns all providers and their state. This method is used for testing purposes only.

func (*OracleImpl) Init

func (o *OracleImpl) Init(ctx context.Context) error

Init initializes the all providers that are configured via the oracle config.

func (*OracleImpl) IsMarketMapValidUpdated

func (o *OracleImpl) IsMarketMapValidUpdated(resp *mmtypes.MarketMapResponse) (mmtypes.MarketMap, bool, error)

IsMarketMapValidUpdated checks if the given MarketMapResponse is an update to the existing MarketMap. - returns an error if the market map is fully invalid or the response is invalid - returns false if the market map is not updated - returns true and the new market map if the new market map is updated and valid.

func (*OracleImpl) IsRunning

func (o *OracleImpl) IsRunning() bool

func (*OracleImpl) Start

func (o *OracleImpl) Start(ctx context.Context) error

Start starts the (blocking) oracle. This will initialize the oracle with the relevant price and market mapper providers, and then start all of them.

func (*OracleImpl) Stop

func (o *OracleImpl) Stop()

Stop stops the oracle. This is a synchronous operation that will wait for all providers to exit.

func (*OracleImpl) UpdateMarketMap

func (o *OracleImpl) UpdateMarketMap(marketMap mmtypes.MarketMap) error

UpdateMarketMap updates the oracle's market map and updates the providers' market maps. Specifically, it determines if the provider's market map has a diff, and if so, updates the provider's state.

func (*OracleImpl) UpdateProviderState

func (o *OracleImpl) UpdateProviderState(providerTickers []types.ProviderTicker, state ProviderState) (ProviderState, error)

UpdateProviderState updates the provider's state based on the market map. Specifically, this will update the provider's query handler and the provider's market map.

func (*OracleImpl) WriteMarketMap

func (o *OracleImpl) WriteMarketMap() error

WriteMarketMap writes the oracle's market map to the configured path.

type PriceAggregator

type PriceAggregator interface {
	SetProviderPrices(provider string, prices types.Prices)
	UpdateMarketMap(mmtypes.MarketMap)
	AggregatePrices()
	GetPrices() types.Prices
	Reset()
}

PriceAggregator is an interface for aggregating prices from multiple providers. Implementations of PriceAggregator should be made safe for concurrent use.

type ProviderState

type ProviderState struct {
	// Provider is the price provider implementation.
	Provider *types.PriceProvider
	// Cfg is the provider configuration.
	//
	// TODO: Deprecate this once we have synchronous configuration updates.
	Cfg config.ProviderConfig
}

ProviderState is the state of a provider. This includes the provider implementation, the provider specific market map, and whether the provider is enabled.