voteweighted

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[connecttypes.CurrencyPair]*big.Int]
• func MedianFromContext(logger log.Logger, validatorStore ValidatorStore, threshold math.LegacyDec) ...
• type CCVCompat
  • func (c CCVCompat) GetBondedTokens() math.Int
• type CCVConsumerCompatKeeper
  • func NewCCVConsumerCompatKeeper(ccvStore CCValidatorStore) CCVConsumerCompatKeeper
  • func (c CCVConsumerCompatKeeper) GetPubKeyByConsAddr(ctx context.Context, consAddr sdk.ConsAddress) (cmtprotocrypto.PublicKey, error)
  • func (c CCVConsumerCompatKeeper) TotalBondedTokens(ctx context.Context) (math.Int, error)
  • func (c CCVConsumerCompatKeeper) ValidatorByConsAddr(ctx context.Context, addr sdk.ConsAddress) (stakingtypes.ValidatorI, error)
• type CCValidatorStore
• type PriceInfo
• type PricePerValidator
• type ValidatorStore

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

func ComputeMedian(priceInfo PriceInfo) *big.Int

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[connecttypes.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:

1. 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.
2. 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.
3. 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[connecttypes.CurrencyPair]*big.Int]

MedianFromContext returns a new Median aggregate function that is parametrized by the latest state of the application.

Types

type CCVCompat

type CCVCompat struct {
	stakingtypes.ValidatorI
	// contains filtered or unexported fields
}

CCVCompat is used for compatibility between stakingtypes.ValidatorI and CrossChainValidator.

func (CCVCompat) GetBondedTokens

func (c CCVCompat) GetBondedTokens() math.Int

GetBondedTokens returns the power of the validator as math.Int.

type CCVConsumerCompatKeeper

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

CCVConsumerCompatKeeper is used for compatibility between the consumer keeper and the ValidatorStore interface.

func NewCCVConsumerCompatKeeper

func NewCCVConsumerCompatKeeper(ccvStore CCValidatorStore) CCVConsumerCompatKeeper

NewCCVConsumerCompatKeeper constructs a CCVConsumerCompatKeeper from a consumer keeper.

func (CCVConsumerCompatKeeper) GetPubKeyByConsAddr

func (c CCVConsumerCompatKeeper) GetPubKeyByConsAddr(ctx context.Context, consAddr sdk.ConsAddress) (cmtprotocrypto.PublicKey, error)

GetPubKeyByConsAddr returns the public key of a validator given the consensus addr.

func (CCVConsumerCompatKeeper) TotalBondedTokens

func (c CCVConsumerCompatKeeper) TotalBondedTokens(ctx context.Context) (math.Int, error)

TotalBondedTokens iterates through all CCVs and returns the sum of all validator power.

func (CCVConsumerCompatKeeper) ValidatorByConsAddr

func (c CCVConsumerCompatKeeper) ValidatorByConsAddr(ctx context.Context, addr sdk.ConsAddress) (stakingtypes.ValidatorI, error)

ValidatorByConsAddr returns a compat validator from the consumer keeper.

type CCValidatorStore

type CCValidatorStore interface {
	GetAllCCValidator(ctx sdk.Context) []types.CrossChainValidator
	GetCCValidator(ctx sdk.Context, addr []byte) (types.CrossChainValidator, bool)
}

CCValidatorStore defines the interface contract required for the cross chain validator consumer store.

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

type PricePerValidator struct {
	VoteWeight math.Int
	Price      *big.Int
}

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.