proposals

README

Block Proposals

Overview

There are two types of block proposals:

Vote extension enabled block proposal: When vote extensions are enabled, the proposer must include the vote extensions they received from comet within their block proposal - specifically in the first slot of the proposal. We choose to use the proposer to determine the canonical vote extensions for a height because each validator may be maintaining different vote extensions which may lead to in-deterministic results.

Vote extension disabled block proposal: When vote extensions are disabled, the proposer does not need to inject any vote extensions into their block proposal.

Prepare Proposal

When vote extensions are enabled, the proposer will then inject the vote extensions into their block proposal. The reason why this is done is to ensure that the vote extensions can be aggregated and written to state in PreBlock. PreBlock does not have access to the vote extensions used to create the block proposal, so the vote extensions must be injected into the block proposal. Additionally, this allows the network to have a canonical set of vote extensions for a given height.

In the case where the validator does not have valid vote extensions, a new round of voting will be triggered. The validator will then wait for the next round of voting to complete before creating a new block proposal.

The process of constructing the rest of the block is left to the PrepareProposalHandler which is passed into the constructor. This means that process of 'oracle' block building can be compatible with the Block-SDK, which is used to build highly custom blocks.

Process Proposal

When vote extensions are enabled, the validator will first verify that the block contains the block proposer's vote extensions. If the block does not contain the block proposer's vote extensions, the block will be rejected. If the block contains the block proposer's vote extensions, the validator will do a basic check to ensure the vote extensions are valid before verifying the rest of the proposal in accordance with the preferences of the ProcessProposalHandler which is passed into the constructor.

Documentation

Index

• type InvalidExtendedCommitInfoError
  • func (e InvalidExtendedCommitInfoError) Error() string
  • func (e InvalidExtendedCommitInfoError) Label() string
• type Option
  • func RetainOracleDataInWrappedProposalHandler() Option
• type ProposalHandler
  • func NewProposalHandler(logger log.Logger, prepareProposalHandler sdk.PrepareProposalHandler, ...) *ProposalHandler
  • func (h *ProposalHandler) PrepareProposalHandler() sdk.PrepareProposalHandler
  • func (h *ProposalHandler) ProcessProposalHandler() sdk.ProcessProposalHandler
  • func (h *ProposalHandler) PruneAndValidateExtendedCommitInfo(ctx sdk.Context, extendedCommitInfo cometabci.ExtendedCommitInfo) (cometabci.ExtendedCommitInfo, error)
  • func (h *ProposalHandler) ValidateExtendedCommitInfo(ctx sdk.Context, height int64, extendedCommitInfo cometabci.ExtendedCommitInfo) error

Types

type InvalidExtendedCommitInfoError

type InvalidExtendedCommitInfoError struct {
	Err error
}

InvalidExtendedCommitInfoError is an error that is returned when a proposed ExtendedCommitInfo is invalid.

func (InvalidExtendedCommitInfoError) Error

func (e InvalidExtendedCommitInfoError) Error() string

func (InvalidExtendedCommitInfoError) Label

func (e InvalidExtendedCommitInfoError) Label() string

type Option

type Option func(*ProposalHandler)

Option is a function that enables optional configuration of the ProposalHandler.

func RetainOracleDataInWrappedProposalHandler

func RetainOracleDataInWrappedProposalHandler() Option

RetainOracleDataInWrappedProposalHandler returns an Option that configures the ProposalHandler to pass the injected extend-commit-info to the wrapped proposal handler.

type ProposalHandler

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

ProposalHandler is responsible primarily for:

1. Filling a proposal with transactions.
2. Injecting vote extensions into the proposal (if vote extensions are enabled).
3. Verifying that the vote extensions injected are valid.

To verify the validity of the vote extensions, the proposal handler will call the validateVoteExtensionsFn. This function is responsible for verifying that the vote extensions included in the proposal are valid and compose a super-majority of signatures and vote extensions for the current block. The given VoteExtensionCodec must be the same used by the VoteExtensionHandler, the extended commit is decoded in accordance with the given ExtendedCommitCodec.

func NewProposalHandler

func NewProposalHandler(
	logger log.Logger,
	prepareProposalHandler sdk.PrepareProposalHandler,
	processProposalHandler sdk.ProcessProposalHandler,
	validateVoteExtensionsFn ve.ValidateVoteExtensionsFn,
	voteExtensionCodec codec.VoteExtensionCodec,
	extendedCommitInfoCodec codec.ExtendedCommitCodec,
	currencyPairStrategy currencypair.CurrencyPairStrategy,
	metrics servicemetrics.Metrics,
	opts ...Option,
) *ProposalHandler

NewProposalHandler returns a new ProposalHandler.

func (*ProposalHandler) PrepareProposalHandler

func (h *ProposalHandler) PrepareProposalHandler() sdk.PrepareProposalHandler

PrepareProposalHandler returns a PrepareProposalHandler that will be called by base app when a new block proposal is requested. The PrepareProposalHandler will first fill the proposal with transactions. Then, if vote extensions are enabled, the handler will inject the extended commit info into the proposal. If the size of the vote extensions exceed the requests MaxTxBytes size, this handler will fail.

func (*ProposalHandler) ProcessProposalHandler

func (h *ProposalHandler) ProcessProposalHandler() sdk.ProcessProposalHandler

ProcessProposalHandler returns a ProcessProposalHandler that will be called by base app when a new block proposal needs to be verified. The ProcessProposalHandler will verify that the vote extensions included in the proposal are valid and compose a super-majority of signatures and vote extensions for the current block.

func (*ProposalHandler) PruneAndValidateExtendedCommitInfo

func (h *ProposalHandler) PruneAndValidateExtendedCommitInfo(
	ctx sdk.Context, extendedCommitInfo cometabci.ExtendedCommitInfo,
) (cometabci.ExtendedCommitInfo, error)

PruneAndValidateExtendedCommitInfo validates each vote-extension in the extended commit, and removes any vote-extensions that are invalid. Removal will effectively treat the validator's vote as absent. This function performs all validation that ValidateExtendedCommitInfo performs.

func (*ProposalHandler) ValidateExtendedCommitInfo

func (h *ProposalHandler) ValidateExtendedCommitInfo(
	ctx sdk.Context,
	height int64,
	extendedCommitInfo cometabci.ExtendedCommitInfo,
) error

ValidateExtendedCommitInfo validates the extended commit info for a block. It first ensures that the vote extensions compose a super-majority of the signatures and voting power for the block. Then, it ensures that oracle vote extensions are correctly marshalled and contain valid prices.