abci

Documentation

Index

• func VoteExtensionDecomposer(part VoteExtensionPart) func([]byte) ([]byte, error)
• type IModuleManager
• type IPreBlockHandler
• type IProposalHandler
• type IVoteExtensionHandler
• type PreBlockHandler
  • func NewPreBlockHandler(logger log.Logger, bridgeSubHandler *bridgeabci.PreBlockHandler, ...) *PreBlockHandler
  • func (pbh *PreBlockHandler) PreBlocker(mm IModuleManager) sdk.PreBlocker
• type ProposalHandler
  • func NewProposalHandler(logger log.Logger, bridgeSubHandler *bridgeabci.ProposalHandler, ...) *ProposalHandler
  • func (ph *ProposalHandler) PrepareProposalHandler() sdk.PrepareProposalHandler
  • func (ph *ProposalHandler) ProcessProposalHandler() sdk.ProcessProposalHandler
  • func (ph *ProposalHandler) SetHandlers(baseApp *baseapp.BaseApp)
• type VoteExtensionHandler
  • func NewVoteExtensionHandler(logger log.Logger, bridgeSubHandler *bridgeabci.VoteExtensionHandler, ...) *VoteExtensionHandler
  • func (veh *VoteExtensionHandler) ExtendVoteHandler() sdk.ExtendVoteHandler
  • func (veh *VoteExtensionHandler) SetHandlers(baseApp *baseapp.BaseApp)
  • func (veh *VoteExtensionHandler) VerifyVoteExtensionHandler() sdk.VerifyVoteExtensionHandler
• type VoteExtensionPart
  • func (vep VoteExtensionPart) String() string

Functions

func VoteExtensionDecomposer

func VoteExtensionDecomposer(part VoteExtensionPart) func([]byte) ([]byte, error)

VoteExtensionDecomposer returns a function that decomposes a composite app-level vote extension and returns the given part.

Types

type IModuleManager

type IModuleManager interface {
	// PreBlock returns the pre-block logic for the module manager.
	PreBlock(ctx sdk.Context) (*sdk.ResponsePreBlock, error)
}

IModuleManager is an interface representing the module manager.

type IPreBlockHandler

type IPreBlockHandler interface {
	// PreBlocker returns the pre-block handler (part of the FinalizeBlock ABCI request).
	PreBlocker() sdk.PreBlocker
}

IPreBlockHandler is an interface representing the pre-block handler (part of the FinalizeBlock ABCI request).

type IProposalHandler

type IProposalHandler interface {
	// PrepareProposalHandler returns the handler for the PrepareProposal ABCI request.
	PrepareProposalHandler() sdk.PrepareProposalHandler
	// ProcessProposalHandler returns the handler for the ProcessProposal ABCI request.
	ProcessProposalHandler() sdk.ProcessProposalHandler
}

IProposalHandler is an interface representing a proposal handler.

type IVoteExtensionHandler

type IVoteExtensionHandler interface {
	// ExtendVoteHandler returns the handler for the ExtendVote ABCI request.
	ExtendVoteHandler() sdk.ExtendVoteHandler
	// VerifyVoteExtensionHandler returns the handler for the VerifyVoteExtension
	// ABCI request.
	VerifyVoteExtensionHandler() sdk.VerifyVoteExtensionHandler
}

IVoteExtensionHandler is an interface representing a vote extension handler.

type PreBlockHandler

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

PreBlockHandler is a pre-block handler (part of the FinalizeBlock ABCI request). It is designed to be used with multiple sub-handlers, each responsible for a specific part of the pre-block logic.

func NewPreBlockHandler

func NewPreBlockHandler(
	logger log.Logger,
	bridgeSubHandler *bridgeabci.PreBlockHandler,
	connectSubHandler IPreBlockHandler,
) *PreBlockHandler

NewPreBlockHandler returns a new PreBlockHandler.

func (*PreBlockHandler) PreBlocker

func (pbh *PreBlockHandler) PreBlocker(mm IModuleManager) sdk.PreBlocker

PreBlocker returns the pre-block handler (part of the FinalizeBlock ABCI request). This function starts by invoking the module manager's PreBlock method to invoke module-level pre-block logic. Next, it iterates over app-level pre-block sub-handlers, invoking each sub-handler's PreBlocker method. The app-level pre-block sub-handlers (unlike the module-level pre-block handlers) have access to the corresponding pseudo-transactions injected during the proposal phase and can perform state changes based on these transactions.

Dev note: Returning an error from this function will make the FinalizeBlock ABCI request fail and lead to an unrecoverable consensus failure. Make sure you know what you are doing before returning an error.

Invariants summary:

1. Calls only the module manager's PreBlock if vote extensions are not enabled.
2. Returns error if the module manager's PreBlock call fails.
3. Returns error if any of the sub-handlers fails.

type ProposalHandler

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

ProposalHandler is a handler for the PrepareProposal and ProcessProposal ABCI requests. It is designed to be used with multiple sub-handlers, each responsible for a specific part of the proposal. The handler itself is responsible for combining the results of the sub-handlers into a single proposal.

func NewProposalHandler

func NewProposalHandler(
	logger log.Logger,
	bridgeSubHandler *bridgeabci.ProposalHandler,
	connectSubHandler *connectproposals.ProposalHandler,
) *ProposalHandler

NewProposalHandler creates a new ProposalHandler instance.

func (*ProposalHandler) PrepareProposalHandler

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

PrepareProposalHandler returns the handler for the PrepareProposal ABCI request. It triggers the PrepareProposal sub-handlers that inject part-specific pseudo-txs and aggregates all the injections into a single app-level pseudo-tx that is put at the beginning of the proposal's transactions list. If any sub-handler fails, its error is logged and the part it was responsible for is not included in the final app-level pseudo-tx. This way, handlers can fail independently of each other. A sub-handler can decide to not inject the part-specific pseudo-tx and such an empty part is still included in the final app-level pseudo-tx. This way, presence of the given part in the app-level pseudo-tx indicates the success/failure of the corresponding sub-handler and may be used for debugging purposes.

Dev note: It is fine to return a nil response and an error from this function in case of failure. Cosmos SDK will log the error and return the original unmodified proposal's transactions list to the CometBFT engine.

Invariants summary:

1. Sub-handler's response is considered valid if no error is returned, regardless of whether the pseudo-tx was injected into the response or not.
2. Returns an error if all sub-handlers return an invalid response.
3. Injects a non-empty app-level pseudo-tx if at least one sub-handler returns a valid response.
4. Returns an error if the app-level pseudo-tx cannot be marshaled.
5. Returns the original proposal's transactions list if vote extensions are not enabled.
6. Guarantees that the final transactions list size does not exceed the maximum allowed block size.

func (*ProposalHandler) ProcessProposalHandler

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

ProcessProposalHandler returns the handler for the ProcessProposal ABCI request. It decomposes the app-level pseudo-tx injected during the PrepareProposal phase into part-specific pseudo-txs and triggers the corresponding ProcessProposal sub-handler for each part.

Dev note: It is fine to return a nil response and an error from this function in case of failure. Cosmos SDK will log the error and REJECT the app-level proposal. Rejecting the proposal is a serious event and has liveness implications for the CometBFT engine. Make sure you know what you are doing before returning an error from this function.

Invariants summary:

1. Accepts the app-level proposal if vote extensions are not enabled.
2. Rejects app-level proposal with an empty transactions vector.
3. Rejects app-level proposal with an injected pseudo-tx that cannot be unmarshaled.
4. Rejects app-level proposal with an injected pseudo-tx containing no parts.
5. Accepts app-level proposal only if each part of their injected pseudo-tx corresponds to a known sub-handler.
6. Accepts app-level proposal only if each part of their injected pseudo-tx is accepted by the corresponding sub-handler.

TODO: Currently, this function either ACCEPT the proposal or return an error - it does not REJECT anything explicitly. This is fine as Cosmos SDK handles the error gracefully by logging it on the error level and rejecting the proposal. This is fine for now, but we may consider a more granular approach and start distinguish between a case when the validation completes successfully but the proposal is invalid and a case when the validation fails (sub-handlers can distinguish between these cases by returning either REJECT + error holding the reason or nil + error, respectively). Having this distinction could allow us to log rejections on warn level and leave log errors for actual errors. The main motivation here is validator experience. Error logs should ideally lead to action items for the given validator while rejection warnings should stay informative and highlight potential misbehavior of other validators.

func (*ProposalHandler) SetHandlers

func (ph *ProposalHandler) SetHandlers(baseApp *baseapp.BaseApp)

SetHandlers sets the PrepareProposal and ProcessProposal handlers on the provided base app.

type VoteExtensionHandler

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

VoteExtensionHandler is a handler for the ExtendVote and VerifyVoteExtension ABCI requests. It is designed to be used with multiple sub-handlers, each responsible for a specific part of the vote extension. The handler itself is responsible for combining the results of the sub-handlers into a single vote extension.

func NewVoteExtensionHandler

func NewVoteExtensionHandler(
	logger log.Logger,
	bridgeSubHandler *bridgeabci.VoteExtensionHandler,
	connectVEHandler *connectve.VoteExtensionHandler,
) *VoteExtensionHandler

NewVoteExtensionHandler creates a new VoteExtensionHandler instance.

func (*VoteExtensionHandler) ExtendVoteHandler

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

ExtendVoteHandler returns the handler for the ExtendVote ABCI request. It triggers the ExtendVote sub-handlers for each part of the vote extension and combines the results into a single app-level vote extension. If any sub-handler fails, its error is logged and the part of the vote extension it was responsible for is not included in the final app-level vote extension. This way, handlers can fail independently of each other. A sub-handler can also return empty bytes for its part of the vote extension and such an empty part is included in the final app-level vote extension. This way presence of the given part in the app-level vote extension indicates the success/failure of the corresponding sub-handler and may be used for debugging purposes.

Dev note: It is fine to return a nil response and an error from this function in case of failure. Cosmos SDK will log the error and return an empty app-level vote extension to the CometBFT engine.

Invariants summary:

1. Sub-handler's response is considered valid if no error is returned, regardless of whether the vote extension part being part of the response is empty or not.
2. Returns an error if all sub-handlers return an invalid response.
3. Returns a non-empty app-level vote extension if at least one sub-handler returns a valid response.
4. Returns an error if the app-level vote extension cannot be marshaled.

func (*VoteExtensionHandler) SetHandlers

func (veh *VoteExtensionHandler) SetHandlers(baseApp *baseapp.BaseApp)

SetHandlers sets the ExtendVote and VerifyVoteExtension handlers on the provided base app.

func (*VoteExtensionHandler) VerifyVoteExtensionHandler

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

VerifyVoteExtensionHandler returns the handler for the VerifyVoteExtension ABCI request.

Dev note: It is fine to return a nil response and an error from this function in case of failure. Cosmos SDK will log the error and REJECT the app-level vote extension. Rejecting the vote extension is a serious event and has liveness implications for the CometBFT engine. Make sure you know what you are doing before returning an error from this function.

Invariants summary:

1. Accepts empty app-level vote extension.
2. Rejects app-level vote extension that cannot be unmarshaled.
3. Rejects app-level vote extension with incorrect height.
4. Rejects app-level vote extension with no parts.
5. Accepts app-level vote extension only if each part corresponds to a known sub-handler.
6. Accepts app-level vote extension only if each part is accepted by the corresponding sub-handler.

TODO: Currently, this function either ACCEPT the vote extension or return an error - it does not REJECT anything explicitly. This is fine as Cosmos SDK handles the error gracefully by logging it on the error level and rejecting the vote extension. This is fine for now, but we may consider a more granular approach and start distinguish between a case when the validation completes successfully but the vote extension is invalid and a case when the validation fails (sub-handlers can distinguish between these cases by returning either REJECT + error holding the reason or nil + error, respectively). Having this distinction could allow us to log rejections on warn level and leave log errors for actual errors. The main motivation here is validator experience. Error logs should ideally lead to action items for the given validator while rejection warnings should stay informative and highlight potential misbehavior of other validators.

type VoteExtensionPart

type VoteExtensionPart uint32

VoteExtensionPart is an enumeration of the different parts of the app-level vote extension.

const (
	// VoteExtensionPartUnknown is an unknown vote extension part.
	VoteExtensionPartUnknown VoteExtensionPart = iota
	// VoteExtensionPartBridge is the part of the vote extension that
	// is specific to the Bitcoin bridge.
	VoteExtensionPartBridge
	// VoteExtensionPartConnect is the part of the vote extension that is specific to the Connect oracle.
	VoteExtensionPartConnect
)

func (VoteExtensionPart) String

func (vep VoteExtensionPart) String() string

String returns a string representation of the vote extension part.