ve

README

Oracle Vote Extensions

This readme provides an overview of how the oracle, base app, and vote extension interact.

Overview

Each validator in the network running the slinky module either runs an oracle in process or out of process. In either case, the oracle is responsible for fetching data offchain that will include the validator's vote extension, broadcast to the network, included in a block, and subsequently committed on-chain.

The process of fetching data offchain and broadcasting it to the network is handled by the vote extension handlers. Note, when a validator broadcasts their vote extensions, they will only be available to other validators in the network at the next height. This means that oracle prices are always one height behind.

Additionally, each validator has a local view of the network's set of vote extensions, meaning there is not a canonical set of vote extensions. As such, we must utilize the next proposer's local view of the network's vote extensions as canonical in order to maintain determinism across the network.

Extend Vote Extension

The extend vote extension handler has access to the oracle service via a remote or local gRPC client. Extend vote is responsible for the following:

1. Fetching the data from the oracle service within the specified timeout period.
2. Creating a vote extension with the data fetched from the oracle service.
3. Broadcasting the vote extension to the network.

Note: In the case where the oracle service is unavailable, returns a bad response, or times out, a nil vote extension will be broadcast to the network. We do not want to halt the chain because of an oracle failure.

Verify Vote Extension

The verify vote extension handler acknowledges and verifies the vote extensions currently in transit across the network. The verify vote extension handler is responsible for the following:

1. Verifying the vote extension is valid. If the vote extension is empty, the vote extension is considered valid.
2. Verifying the vote extension is not expired. If the vote extension is expired, the vote extension is considered invalid.
3. Verifying that the prices provided in the vote extension are valid. If the prices are invalid, the vote extension is considered invalid.

Documentation

Index

• func NoOpValidateVoteExtensions(_ sdk.Context, _ cometabci.ExtendedCommitInfo) error
• func ValidateExtendedCommitAgainstLastCommit(ec cometabci.ExtendedCommitInfo, lc comet.CommitInfo) error
• func ValidateOracleVoteExtension(ctx sdk.Context, ve vetypes.OracleVoteExtension, ...) error
• func ValidateVoteExtensions(ctx sdk.Context, valStore ValidatorStore, ...) error
• func VoteExtensionsEnabled(ctx sdk.Context) bool
• type ErrPanic
  • func (e ErrPanic) Error() string
  • func (e ErrPanic) Label() string
• type OracleClientError
  • func (e OracleClientError) Error() string
  • func (e OracleClientError) Label() string
• type PreBlockError
  • func (e PreBlockError) Error() string
  • func (e PreBlockError) Label() string
• type TransformPricesError
  • func (e TransformPricesError) Error() string
  • func (e TransformPricesError) Label() string
• type ValidateVoteExtensionError
  • func (e ValidateVoteExtensionError) Error() string
  • func (e ValidateVoteExtensionError) Label() string
• type ValidateVoteExtensionsFn
  • func NewDefaultValidateVoteExtensionsFn(validatorStore ValidatorStore) ValidateVoteExtensionsFn
• type ValidatorStore
• type VoteExtensionHandler
  • func NewVoteExtensionHandler(logger log.Logger, oracleClient slinkyabci.OracleClient, timeout time.Duration, ...) *VoteExtensionHandler
  • func (h *VoteExtensionHandler) ExtendVoteHandler() sdk.ExtendVoteHandler
  • func (h *VoteExtensionHandler) VerifyVoteExtensionHandler() sdk.VerifyVoteExtensionHandler

Functions

func NoOpValidateVoteExtensions

func NoOpValidateVoteExtensions(
	_ sdk.Context,
	_ cometabci.ExtendedCommitInfo,
) error

NoOpValidateVoteExtensions is a no-op validation method (purely used for testing).

func ValidateExtendedCommitAgainstLastCommit

func ValidateExtendedCommitAgainstLastCommit(ec cometabci.ExtendedCommitInfo, lc comet.CommitInfo) error

ValidateExtendedCommitAgainstLastCommit validates an ExtendedCommitInfo against a LastCommit. Specifically, it checks that the ExtendedCommit + LastCommit (for the same height), are consistent with each other + that they are ordered correctly (by voting power) in accordance with comet(https://github.com/cometbft/cometbft/blob/4ce0277b35f31985bbf2c25d3806a184a4510010/types/validator_set.go#L784).

func ValidateOracleVoteExtension

func ValidateOracleVoteExtension(
	ctx sdk.Context,
	ve vetypes.OracleVoteExtension,
	strategy currencypair.CurrencyPairStrategy,
) error

ValidateOracleVoteExtension validates the vote extension provided by a validator.

func ValidateVoteExtensions

func ValidateVoteExtensions(
	ctx sdk.Context,
	valStore ValidatorStore,
	extCommit cometabci.ExtendedCommitInfo,
) error

ValidateVoteExtensions defines a helper function for verifying vote extension signatures that may be passed or manually injected into a block proposal from a proposer in PrepareProposal. It returns an error if any signature is invalid or if unexpected vote extensions and/or signatures are found or less than 2/3 power is received.

func VoteExtensionsEnabled

func VoteExtensionsEnabled(ctx sdk.Context) bool

VoteExtensionsEnabled determines if vote extensions are enabled for the current block. If vote extensions are enabled at height h, then a proposer will receive vote extensions in height h+1. This is primarily utilized by any module that needs to make state changes based on whether they were included in a proposal.

Types

type ErrPanic

type ErrPanic struct {
	Err error
}

ErrPanic is an error that is returned when a panic occurs in the ABCI handler.

func (ErrPanic) Error

func (e ErrPanic) Error() string

func (ErrPanic) Label

func (e ErrPanic) Label() string

type OracleClientError

type OracleClientError struct {
	Err error
}

OracleClientError is an error that is returned when the oracle client's response is invalid.

func (OracleClientError) Error

func (e OracleClientError) Error() string

func (OracleClientError) Label

func (e OracleClientError) Label() string

type PreBlockError

type PreBlockError struct {
	Err error
}

PreBlockError is an error that is returned when the pre-block simulation fails.

func (PreBlockError) Error

func (e PreBlockError) Error() string

func (PreBlockError) Label

func (e PreBlockError) Label() string

type TransformPricesError

type TransformPricesError struct {
	Err error
}

TransformPricesError is an error that is returned when there is a failure in attempting to transform the prices returned from the oracle server to the format expected by the validator set.

func (TransformPricesError) Error

func (e TransformPricesError) Error() string

func (TransformPricesError) Label

func (e TransformPricesError) Label() string

type ValidateVoteExtensionError

type ValidateVoteExtensionError struct {
	Err error
}

ValidateVoteExtensionError is an error that is returned when there is a failure in validating a vote extension.

func (ValidateVoteExtensionError) Error

func (e ValidateVoteExtensionError) Error() string

func (ValidateVoteExtensionError) Label

func (e ValidateVoteExtensionError) Label() string

type ValidateVoteExtensionsFn

type ValidateVoteExtensionsFn func(
	ctx sdk.Context,
	extInfo cometabci.ExtendedCommitInfo,
) error

ValidateVoteExtensionsFn defines the function for validating vote extensions. This function is not explicitly used to validate the oracle data but rather that the signed vote extensions included in the proposal are valid and provide a super-majority of vote extensions for the current block. This method is expected to be used in PrepareProposal and ProcessProposal.

func NewDefaultValidateVoteExtensionsFn

func NewDefaultValidateVoteExtensionsFn(validatorStore ValidatorStore) ValidateVoteExtensionsFn

NewDefaultValidateVoteExtensionsFn returns a new DefaultValidateVoteExtensionsFn.

type ValidatorStore

type ValidatorStore interface {
	GetPubKeyByConsAddr(context.Context, sdk.ConsAddress) (cmtprotocrypto.PublicKey, error)
}

ValidatorStore defines the interface contract require for verifying vote extension signatures. Typically, this will be implemented by the x/staking module, which has knowledge of the CometBFT public key.

type VoteExtensionHandler

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

VoteExtensionHandler is a handler that extends a vote with the oracle's current price feed. In the case where oracle data is unable to be fetched or correctly marshalled, the handler will return an empty vote extension to ensure liveliness.

func NewVoteExtensionHandler

func NewVoteExtensionHandler(
	logger log.Logger,
	oracleClient slinkyabci.OracleClient,
	timeout time.Duration,
	strategy currencypair.CurrencyPairStrategy,
	codec compression.VoteExtensionCodec,
	priceApplier aggregator.PriceApplier,
	metrics servicemetrics.Metrics,
) *VoteExtensionHandler

NewVoteExtensionHandler returns a new VoteExtensionHandler.

func (*VoteExtensionHandler) ExtendVoteHandler

func (h *VoteExtensionHandler) ExtendVoteHandler() sdk.ExtendVoteHandler

ExtendVoteHandler returns a handler that extends a vote with the oracle's current price feed. In the case where oracle data is unable to be fetched or correctly marshalled, the handler will return an empty vote extension to ensure liveness.

func (*VoteExtensionHandler) VerifyVoteExtensionHandler

func (h *VoteExtensionHandler) VerifyVoteExtensionHandler() sdk.VerifyVoteExtensionHandler

VerifyVoteExtensionHandler returns a handler that verifies the vote extension provided by a validator is valid. In the case when the vote extension is empty, we return ACCEPT. This means that the validator may have been unable to fetch prices from the oracle and is voting an empty vote extension. We reject any vote extensions that are not empty and fail to unmarshal or contain invalid prices.