oracle

README

Oracle PreBlock Handler

Overview

Writing vote extensions to state is possible using the SDK's PreBlocker - which allows you to modify the state before the block is executed and committed. Since the vote extensions not directly accesible from the PreBlocker, we inject the vote extensions in PrepareProposal and verify them in ProcessProposal before a block is accepted by the network.

The PreBlockHandler assumes that the vote extensions are already verified by validators in the network and are ready to be aggregated. A bad vote extension included in a proposal implies that the network has accepted a bad proposal.

Usage

To use the preblock handler, you need to initialize the preblock handler in your app.go file. By default, we encourage users to use the aggregation function defined in abci/preblock/math to aggregate the votes. This will aggregate all of the prices and calculate a stake-weighted median for each supported asset.

The PreBlockHandler currently only supports assets that are initialized in the oracle keeper. However, allowing any type of asset can be supported with a small modification to WritePrices (TBD whether we will support this).

Documentation

Index

• type Keeper
• type PreBlockHandler
  • func NewOraclePreBlockHandler(logger log.Logger, ...) *PreBlockHandler
  • func (h *PreBlockHandler) AggregateOracleVotes(ctx sdk.Context, votes []Vote) (map[oracletypes.CurrencyPair]*big.Int, error)
  • func (h *PreBlockHandler) PreBlocker() sdk.PreBlocker
  • func (h *PreBlockHandler) WritePrices(ctx sdk.Context, prices map[oracletypes.CurrencyPair]*big.Int) error
• type Vote
  • func GetOracleVotes(proposal [][]byte, veCodec compression.VoteExtensionCodec, ...) ([]Vote, error)

Types

type Keeper

type Keeper interface {
	GetAllCurrencyPairs(ctx sdk.Context) []oracletypes.CurrencyPair
	SetPriceForCurrencyPair(ctx sdk.Context, cp oracletypes.CurrencyPair, qp oracletypes.QuotePrice) error
}

Keeper defines the interface that must be fulfilled by the oracle keeper. This interface is utilized by the PreBlock handler to write oracle data to state for the supported assets.

type PreBlockHandler

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

PreBlockHandler is responsible for aggregating oracle data from each validator and writing the oracle data into the store before any transactions are executed/finalized for a given block.

func NewOraclePreBlockHandler

func NewOraclePreBlockHandler(
	logger log.Logger,
	aggregateFn aggregator.AggregateFnFromContext[string, map[oracletypes.CurrencyPair]*big.Int],
	oracleKeeper Keeper,
	validatorConsAddress sdk.ConsAddress,
	metrics servicemetrics.Metrics,
	strategy currencypair.CurrencyPairStrategy,
	veCodec codec.VoteExtensionCodec,
	ecCodec codec.ExtendedCommitCodec,
) *PreBlockHandler

NewOraclePreBlockHandler returns a new PreBlockHandler. The handler is responsible for writing oracle data included in vote extensions to state.

func (*PreBlockHandler) AggregateOracleVotes

func (h *PreBlockHandler) AggregateOracleVotes(
	ctx sdk.Context,
	votes []Vote,
) (map[oracletypes.CurrencyPair]*big.Int, error)

AggregateOracleVotes ingresses vote information which contains all of the vote extensions each validator extended in the previous block. it is important to note that

1. The vote extension may be nil, in which case the validator is not providing any oracle data for the current block. This could have occurred because the validator was offline, or its local oracle service was down.
2. The vote extension may contain prices updates for only a subset of currency pairs. This could have occurred because the price providers for the validator were offline, or the price providers did not provide a price update for a given currency pair.

In order for a currency pair to be included in the final oracle price, the currency pair must be provided by a supermajority (2/3+) of validators. This is enforced by the price aggregator but can be replaced by the application.

func (*PreBlockHandler) PreBlocker

func (h *PreBlockHandler) PreBlocker() sdk.PreBlocker

PreBlocker is called by the base app before the block is finalized. It is responsible for aggregating oracle data from each validator and writing the oracle data to the store.

func (*PreBlockHandler) WritePrices

func (h *PreBlockHandler) WritePrices(ctx sdk.Context, prices map[oracletypes.CurrencyPair]*big.Int) error

WritePrices writes the oracle data to state. Note, this will only write prices that are already present in state.

type Vote

type Vote struct {
	// ConsAddress is the validator that submitted the vote extension.
	ConsAddress sdk.ConsAddress
	// OracleVoteExtension
	OracleVoteExtension types.OracleVoteExtension
}

Vote encapsulates the validator and oracle data contained within a vote extension.

func GetOracleVotes

func GetOracleVotes(
	proposal [][]byte,
	veCodec compression.VoteExtensionCodec,
	extCommitCodec compression.ExtendedCommitCodec,
) ([]Vote, error)

GetOracleVotes returns all of the oracle vote extensions that were injected into the block. Note that all of the vote extensions included are necessarily valid at this point because the vote extensions were validated by the vote extension and proposal handlers.