oracle

README

Oracle Client

Overview

The oracle client is responsible for fetching data from a price oracle that is running externally from the Cosmos SDK application. The client will fetch prices, standardize them according to the preferences of the application and include them in a validator's vote extension.

// OracleClient defines the interface that will be utilized by the application
// to query the oracle service. This interface is meant to be implemented by
// the gRPC client that connects to the oracle service.
type OracleClient interface {
	// Prices defines a method for fetching the latest prices.
	Prices(ctx context.Context, in *QueryPricesRequest, opts ...grpc.CallOption) (*QueryPricesResponse, error)

	// Start starts the oracle client.
	Start() error

	// Stop stops the oracle client.
	Stop() error
}

There are two types of clients that are supported:

• Vanilla GRPC oracle client - This client is responsible for fetching data from an oracle that is aggregating price data. It implements a GRPC client that connects to the oracle service and fetches the latest prices.
• Metrics GRPC oracle client - This client implements the same functionality as the vanilla GRPC oracle client, but also exposes metrics that can be scraped by Prometheus.

To enable the metrics GRPC client, please read over the oracle configurations documentation.

Documentation

Index

• type GRPCClient
  • func (c *GRPCClient) MarketMap(ctx context.Context, req *types.QueryMarketMapRequest, _ ...grpc.CallOption) (res *types.QueryMarketMapResponse, err error)
  • func (c *GRPCClient) Prices(ctx context.Context, req *types.QueryPricesRequest, _ ...grpc.CallOption) (resp *types.QueryPricesResponse, err error)
  • func (c *GRPCClient) Start(ctx context.Context) error
  • func (c *GRPCClient) Stop() error
  • func (c *GRPCClient) Version(ctx context.Context, req *types.QueryVersionRequest, _ ...grpc.CallOption) (res *types.QueryVersionResponse, err error)
• type NoOpClient
  • func (c NoOpClient) MarketMap(_ context.Context, _ *types.QueryMarketMapRequest, _ ...grpc.CallOption) (*types.QueryMarketMapResponse, error)
  • func (NoOpClient) Prices(_ context.Context, _ *types.QueryPricesRequest, _ ...grpc.CallOption) (*types.QueryPricesResponse, error)
  • func (NoOpClient) Start(context.Context) error
  • func (NoOpClient) Stop() error
  • func (c NoOpClient) Version(_ context.Context, _ *types.QueryVersionRequest, _ ...grpc.CallOption) (*types.QueryVersionResponse, error)
• type Option
  • func WithBlockingDial() Option
• type OracleClient
  • func NewClient(logger log.Logger, addr string, timeout time.Duration, metrics metrics.Metrics, ...) (OracleClient, error)
  • func NewClientFromConfig(cfg config.AppConfig, logger log.Logger, metrics metrics.Metrics, ...) (OracleClient, error)
  • func NewPriceDaemonClientFromConfig(cfg config.AppConfig, logger log.Logger, metrics metrics.Metrics, ...) (OracleClient, error)
• type PriceDaemon
  • func NewPriceDaemon(logger log.Logger, cfg config.AppConfig, client OracleClient) (*PriceDaemon, error)
  • func (d *PriceDaemon) Prices(_ context.Context, _ *types.QueryPricesRequest, _ ...grpc.CallOption) (*types.QueryPricesResponse, error)
  • func (d *PriceDaemon) Start(ctx context.Context) error
  • func (d *PriceDaemon) Stop() error
• type ThreadSafeResponse
  • func NewThreadSafeResponse() *ThreadSafeResponse
  • func (r *ThreadSafeResponse) Get() (*types.QueryPricesResponse, time.Time)
  • func (r *ThreadSafeResponse) Update(resp *types.QueryPricesResponse)

Types

type GRPCClient

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

GRPCClient defines an implementation of a gRPC oracle client. This client can be used in ABCI++ calls where the application wants the oracle process to be run out-of-process. The client must be started upon app construction and stopped upon app shutdown/cleanup.

func (*GRPCClient) MarketMap

func (c *GRPCClient) MarketMap(ctx context.Context, req *types.QueryMarketMapRequest, _ ...grpc.CallOption) (res *types.QueryMarketMapResponse, err error)

func (*GRPCClient) Prices

func (c *GRPCClient) Prices(
	ctx context.Context,
	req *types.QueryPricesRequest,
	_ ...grpc.CallOption,
) (resp *types.QueryPricesResponse, err error)

Prices returns the prices from the remote oracle service. This method blocks for the timeout duration configured on the client, otherwise it returns the response from the remote oracle.

func (*GRPCClient) Start

func (c *GRPCClient) Start(ctx context.Context) error

Start starts the GRPC client. This method dials the remote oracle-service and errors if the connection fails. This method may block (depending on the blockingDial option).

func (*GRPCClient) Stop

func (c *GRPCClient) Stop() error

Stop stops the GRPC client. This method closes the connection to the remote.

func (*GRPCClient) Version

func (c *GRPCClient) Version(ctx context.Context, req *types.QueryVersionRequest, _ ...grpc.CallOption) (res *types.QueryVersionResponse, err error)

Version returns the version of the oracle service.

type NoOpClient

type NoOpClient struct{}

NoOpClient is a no-op implementation of the OracleClient interface. This implementation is used when the oracle service is disabled.

func (NoOpClient) MarketMap

func (c NoOpClient) MarketMap(
	_ context.Context,
	_ *types.QueryMarketMapRequest,
	_ ...grpc.CallOption,
) (*types.QueryMarketMapResponse, error)

func (NoOpClient) Prices

func (NoOpClient) Prices(
	_ context.Context,
	_ *types.QueryPricesRequest,
	_ ...grpc.CallOption,
) (*types.QueryPricesResponse, error)

Prices is a no-op.

func (NoOpClient) Start

func (NoOpClient) Start(context.Context) error

Start is a no-op.

func (NoOpClient) Stop

func (NoOpClient) Stop() error

Stop is a no-op.

func (NoOpClient) Version

func (c NoOpClient) Version(
	_ context.Context,
	_ *types.QueryVersionRequest,
	_ ...grpc.CallOption,
) (*types.QueryVersionResponse, error)

type Option

type Option func(OracleClient)

Option enables consumers to configure the behavior of an OracleClient on initialization.

func WithBlockingDial

func WithBlockingDial() Option

WithBlockingDial configures the OracleClient to block on dialing the remote oracle server.

NOTICE: This option is not recommended to be used in practice. See the [GRPC docs](https://github.com/grpc/grpc-go/blob/master/Documentation/anti-patterns.md)

type OracleClient

type OracleClient interface {
	types.OracleClient

	// Start starts the oracle client. This should connect to the remote oracle
	// service and return an error if the connection fails.
	Start(context.Context) error

	// Stop stops the oracle client.
	Stop() error
}

OracleClient defines the interface that will be utilized by the application to query the oracle service. This interface is meant to be implemented by the gRPC client that connects to the oracle service.

func NewClient

func NewClient(
	logger log.Logger,
	addr string,
	timeout time.Duration,
	metrics metrics.Metrics,
	opts ...Option,
) (OracleClient, error)

NewClient creates a new grpc client of the oracle service with the given address and timeout.

func NewClientFromConfig

func NewClientFromConfig(
	cfg config.AppConfig,
	logger log.Logger,
	metrics metrics.Metrics,
	opts ...Option,
) (OracleClient, error)

NewClientFromConfig creates a new grpc client of the oracle service with the given app configuration. This returns an error if the configuration is invalid.

func NewPriceDaemonClientFromConfig

func NewPriceDaemonClientFromConfig(
	cfg config.AppConfig,
	logger log.Logger,
	metrics metrics.Metrics,
	opts ...Option,
) (OracleClient, error)

NewPriceDaemonClientFromConfig creates a new grpc client of the oracle service with the given app configuration. This returns an error if the configuration is invalid. Specifically, this client will be a daemon client that has prices available in constant time.

type PriceDaemon

type PriceDaemon struct {

	// client is the underlying oracle client used to fetch prices.
	OracleClient
	// contains filtered or unexported fields
}

func NewPriceDaemon

func NewPriceDaemon(
	logger log.Logger,
	cfg config.AppConfig,
	client OracleClient,
) (*PriceDaemon, error)

NewPriceDaemon creates a new price daemon with the given configuration.

func (*PriceDaemon) Prices

func (d *PriceDaemon) Prices(
	_ context.Context,
	_ *types.QueryPricesRequest,
	_ ...grpc.CallOption,
) (*types.QueryPricesResponse, error)

Prices returns the latest price response fetched by the daemon. If the latest response is too stale, an error is returned.

func (*PriceDaemon) Start

func (d *PriceDaemon) Start(ctx context.Context) error

Start starts the price daemon. This method will block until the daemon is stopped.

func (*PriceDaemon) Stop

func (d *PriceDaemon) Stop() error

Stop stops the price daemon.

type ThreadSafeResponse

type ThreadSafeResponse struct {
	sync.Mutex
	// contains filtered or unexported fields
}

ThreadSafeResponse is a thread-safe wrapper around a QueryPricesResponse.

func NewThreadSafeResponse

func NewThreadSafeResponse() *ThreadSafeResponse

NewThreadSafeResponse creates a new thread-safe response.

func (*ThreadSafeResponse) Get

func (r *ThreadSafeResponse) Get() (*types.QueryPricesResponse, time.Time)

Get returns the response and timestamp of the thread-safe response.

func (*ThreadSafeResponse) Update

func (r *ThreadSafeResponse) Update(resp *types.QueryPricesResponse)

Update updates the response and timestamp of the thread-safe response.