README
¶
Aggregating Oracle Prices On-Chain
Overview
Definitions
- Price: The price of an asset at a given time.
- Delta: The difference between the current price and the previous price. This can be positive or negative.
- Aggregation Strategy: The method by which the deltas are aggregated across multiple oracle sources.
Note: The price aggregation strategy might vary based on the currency pair strategy utilized by the vote extension handler. For example, if the vote extension is implemented to submit a delta, the aggregation strategy must aggregate deltas. If the vote extension is implemented to submit a price, the aggregation strategy must aggregate prices. By default, the vote extension handler will submit deltas which are converted to real prices before being aggregated. This is the recommended approach.
This module provides the default implementation for a price aggregation strategy across multiple oracle sources on-chain. It is designed to be used as the aggregation function for the PreBlock handler. This implementation can be used as a reference for other implementations. For a reference as to how these strategies can be implemented, please reference the aggregator module.
Implementation
The PreBlock handler is implemented in preblock.go. This handler is registered with the application in app.go. The handler is called by the ABCI application before the block is committed to the chain - in PreBlock during FinalizeBlock.
This implementation will first associate the relative voting power of each validator given the price update that they have submitted through their vote extensions. After the voting power is calculated, the price information is aggregated across all validators by first sorting the prices in ascending order and then taking the stake weighted median of the prices.
For example, if there are 3 validators with the following prices:
Validator 1: 100
Validator 2: 200
Validator 3: 300
Assume the validators have the following voting power:
Validator 1: 10
Validator 2: 20
Validator 3: 20
The final aggregated price will be 200 which is the median of the sorted prices.
Another example, if there are 3 validators with the following prices:
Validator 1: 100
Validator 2: 200
Validator 3: 300
Assume the validators have the following voting power:
Validator 1: 10
Validator 2: 20
Validator 3: 30
The final aggregated price will be 250 which is the median of the sorted prices. Notice, that the price aggregation strategy selects the price update where the voting power is greater than or equal to 50%. In this case, the price update from Validator 2 is selected.
As a final example, if there are 3 validators with the following prices:
Validator 1: 100
Validator 2: 200
Validator 3: 300
Assume the validators have the following voting power:
Validator 1: 10
Validator 2: 10
Validator 3: 100
The final aggregated price will be 300 which is the median of the sorted prices.
Documentation
¶
Index ¶
- Variables
- func ComputeMedian(priceInfo PriceInfo) *big.Int
- func Median(ctx sdk.Context, logger log.Logger, validatorStore ValidatorStore, ...) aggregator.AggregateFn[string, map[slinkytypes.CurrencyPair]*big.Int]
- func MedianFromContext(logger log.Logger, validatorStore ValidatorStore, threshold math.LegacyDec) ...
- type PriceInfo
- type PricePerValidator
- type ValidatorStore
Constants ¶
This section is empty.
Variables ¶
var DefaultPowerThreshold = math.LegacyNewDecWithPrec(667, 3)
DefaultPowerThreshold defines the total voting power % that must be submitted in order for a currency pair to be considered for the final oracle price. We provide a default supermajority threshold of 2/3+.
Functions ¶
func ComputeMedian ¶
ComputeMedian computes the stake-weighted median price for a given asset.
func Median ¶
func Median( ctx sdk.Context, logger log.Logger, validatorStore ValidatorStore, threshold math.LegacyDec, ) aggregator.AggregateFn[string, map[slinkytypes.CurrencyPair]*big.Int]
Median returns an aggregation function that computes the stake weighted median price as the final deterministic oracle price for any qualifying currency pair (base, quote). There are a few things to note about the implementation:
- Price updates for a given currency pair will only be written to state if the power % threshold is met. The threshold is determined by the total voting power of all validators that submitted a price update for a given currency pair divided by the total network voting power. The threshold to meet is configurable by developers.
- In the case where there are not enough price updates for a given currency pair, the price will not be included in the final set of oracle prices.
- Given the threshold is met, the final oracle price for a given currency pair is the median price weighted by the stake of each validator that submitted a price.
func MedianFromContext ¶
func MedianFromContext( logger log.Logger, validatorStore ValidatorStore, threshold math.LegacyDec, ) aggregator.AggregateFnFromContext[string, map[slinkytypes.CurrencyPair]*big.Int]
MedianFromContext returns a new Median aggregate function that is parametrized by the latest state of the application.
Types ¶
type PriceInfo ¶
type PriceInfo struct {
Prices []PricePerValidator
TotalWeight math.Int
}
VoteWeightPriceInfo tracks the stake weight(s) + price(s) for a given currency pair.
type PricePerValidator ¶
VoteWeightPrice defines a price update that includes the stake weight of the validator.
type ValidatorStore ¶
type ValidatorStore interface {
ValidatorByConsAddr(ctx context.Context, addr sdk.ConsAddress) (stakingtypes.ValidatorI, error)
TotalBondedTokens(ctx context.Context) (math.Int, error)
}
ValidatorStore defines the interface contract required for calculating stake-weighted median prices + total voting power for a given currency pair.
Source Files
Directories