snapsapp

package
v1.0.0-mx.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 23, 2024 License: Apache-2.0 Imports: 10 Imported by: 0

README

SnapsApp ABCI

The snapsapp package implements a multi-network ABCI application that enables consensus events mapping for the client implementation.

Application

The SnapsApp structure is configured via the following instances:

  • A Reactor contains an implementation to retrieve networks and state stores.

When the SnapsApp is created, the replicated chains configuration is read from the reactor interface and are validated upon ABCI requests at several stages of an individual consensus instance.

The state store structure, that is retrieved from the reactor, using the GetStateStore method, is expected to satisfy the state.Store interface.

The SnapsApp application enables consensus events mapping for the client implementation by running specific hooks at different stages of the consensus instance, including: CheckTx, PrepareProposal and Commit, amongst others.

ABCI Interfaces

The most prominent methods implemented with the [SnapsApp] ABCI application include, but are not limited to:

  • SnapsApp#InitChain: InitChain initializes the application's state.
  • SnapsApp#Info: Info returns information about the application.
  • SnapsApp#CheckTx: CheckTx must validate individual transaction data.
  • SnapsApp#Commit: Commit must persist relevant application data.

We also provide implementations for all other required methods, including for PrepareProposal, ProcessProposal, FinalizeBlock and Commit.

Testing

You can test the ABCI methods using the following unit test suite:

go test github.com/ice-blockchain/cometbft/multiplex/snapsapp -test.v -count=1

Note that this test suite is apart from the snapsapp package and implemented in a snapsapp_test package instead.

Documentation

Overview

The `snapsapp` package implements a multi-network ABCI application that enables consensus events mapping for the client implementation.

Application

The SnapsApp structure is configured via the following instances:

- A `Reactor` contains an implementation to retrieve networks and state stores.

When the SnapsApp is created, the replicated chains configuration is read from the reactor interface and are validated upon ABCI requests at several stages of an individual consensus instance.

The state store structure, that is retrieved from the reactor, using the [GetStateStore] method, is expected to satisfy the [state.Store] interface.

The SnapsApp application enables consensus events mapping for the client implementation by running specific hooks at different stages of the consensus instance, including: `CheckTx`, `PrepareProposal` and `Commit`, amongst others.

ABCI

The most prominent methods implemented with the SnapsApp ABCI application include, but are not limited to:

- [SnapsApp#InitChain]: InitChain initializes the application's state. - [SnapsApp#Info]: Info returns information about the application. - [SnapsApp#CheckTx]: CheckTx must validate individual transaction data. - [SnapsApp#Commit]: Commit must persist relevant application data.

We also provide implementations for all other *required* methods, including for `PrepareProposal`, `ProcessProposal`, `FinalizeBlock` and `Commit`.

Testing

You can test the ABCI methods using the following unit test suite:

```bash go test github.com/ice-blockchain/cometbft/multiplex/snapsapp -test.v -count=1 ```

Note that this test suite is apart from the `snapsapp` package and implemented in a `snapsapp_test` package instead.

Index

Constants

View Source 
const (
	// The AppVersion constant determines the current state machine version,
	// it can be increased to mark an upgrade in the State storage format.
	AppVersion = 1
)
View Source 
const (
	// Errors return codes, must be different from CodeTypeOK=0.
	CodeTypeErrCheckTxFailure = uint32(1)
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Reactor 

type Reactor interface {
	// HasNetwork should return true if a ChainID is known to a node.
	HasNetwork(chainID string) bool

	// GetNetworks should return a slice of ChainID values known to a node.
	GetNetworks() []string

	// GetStoragePaths should return storage paths mapped by ChainID.
	GetStoragePaths() map[string]string

	// GetStateStore should return a pointer to a [sm.Store].
	GetStateStore(chainID string) sm.Store
}

Reactor defines the implementation contract for the multiplex reactor that is used to retrieve `stateStore` instances and networks.

type SnapsApp 

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

---------------------------------------------------------------------------- SnapsApp

SnapsApp defines an ABCI application around a multiplex reactor, and a default or custom client implementation.

Read-write mutexes are created to track initial heights on concurrent threads, as well as for the currently working height in the process of finalizing and committing blocks.

Note that *only one instance* of the SnapsApp application must be created for node multiplexes. The SnapsApp application must keep thread-safety.

func NewSnapsApplication 

func NewSnapsApplication(
	reactor Reactor,
	logger cmtlog.Logger,
	options ...func(*SnapsApp),
) *SnapsApp

NewSnapsApplication creates a SnapsApp ABCI application instance and initializes a [snapshots.Manager] for every replicated chain.

func (*SnapsApp) ApplySnapshotChunk 

func (app *SnapsApp) ApplySnapshotChunk(
	ctx context.Context,
	req *abcitypes.ApplySnapshotChunkRequest,
) (*abcitypes.ApplySnapshotChunkResponse, error)

ApplySnapshotChunk is not supported as state-sync must be disabled.

This method is called when a peer received a snapshot chunk (downloaded). The downloaded snapshot chunk will be applied with this method, thus updating the filesystem. When all snapshot chunks have finished downloading, the snapshot will be considered fully applied.

ApplySnapshotChunk implements abcitypes.Application.

func (*SnapsApp) CheckTx 

func (app *SnapsApp) CheckTx(
	ctx context.Context,
	req *abcitypes.CheckTxRequest,
) (*abcitypes.CheckTxResponse, error)

CheckTx allows the application to validate transactions and/or discard them.

This method may execute transactions in CheckTx mode, i.e. not actually executing messages. Note also that expensive operations should not be run here but rather in the commitment stage.

CheckTx implements abcitypes.Application.

func (*SnapsApp) Commit 

func (app *SnapsApp) Commit(
	ctx context.Context,
	req *abcitypes.CommitRequest,
) (*abcitypes.CommitResponse, error)

Commit may persist the application state if any data is relevant.

This method is called after finalizing blocks.

Commit implements abcitypes.Application.

func (*SnapsApp) ExtendVote 

func (app *SnapsApp) ExtendVote(context.Context, *abcitypes.ExtendVoteRequest) (*abcitypes.ExtendVoteResponse, error)

ExtendVote implements the ExtendVote ABCI method and returns a ResponseExtendVote. It calls the application's ExtendVote handler which is responsible for performing application-specific business logic when sending a pre-commit for the NEXT block height. The extensions response may be non-deterministic but must always be returned, even if empty.

Agreed upon vote extensions are made available to the proposer of the next height and are committed in the subsequent height, i.e. H+2. An error is returned if vote extensions are not enabled or if extendVote fails or panics.

ExtendVote implements abcitypes.Application.

func (*SnapsApp) FinalizeBlock 

func (app *SnapsApp) FinalizeBlock(
	ctx context.Context,
	req *abcitypes.FinalizeBlockRequest,
) (*abcitypes.FinalizeBlockResponse, error)

FinalizeBlock will execute the block proposal provided by FinalizeBlockRequest.

Currently we do not perform any filtering with transactions, thus the transactions are all deemed to be "valid".

The finalizeBlockHeights is updated for the relevant chain such that the subsequent Commit() ABCI with the same ChainID may know which *height* is being finalized. This height is used to determine whether a snapshot must be taken or not.

FinalizeBlock implements abcitypes.Application.

func (*SnapsApp) FinalizeBlockHeight 

func (app *SnapsApp) FinalizeBlockHeight(chainID string) int64

FinalizeBlockHeight returns the latest finalizeBlock height.

func (*SnapsApp) Info 

func (app *SnapsApp) Info(
	ctx context.Context,
	req *abcitypes.InfoRequest,
) (*abcitypes.InfoResponse, error)

Info returns information about the application, including the AppHash.

This method is called upon crash-recovery and after executing state-sync to verify the loaded AppHash.

Info implements abcitypes.Application.

func (*SnapsApp) InitChain 

func (app *SnapsApp) InitChain(
	ctx context.Context,
	req *abcitypes.InitChainRequest,
) (*abcitypes.InitChainResponse, error)

InitChain initializes the application's state and sets up the initial validator set and other consensus parameters.

This method is called once before applying the genesis block and permits to overwrite an application's validator set and consensus params, as well as to set an initial state to be replicated.

InitChain implements abcitypes.Application.

func (*SnapsApp) InitialHeight 

func (app *SnapsApp) InitialHeight(chainID string) int64

InitialHeight returns the initial block height for a chainID.

func (*SnapsApp) LastBlockHeight 

func (app *SnapsApp) LastBlockHeight(chainID string) int64

LastBlockHeight returns the last block height processed for a chainID.

func (*SnapsApp) ListSnapshots 

func (app *SnapsApp) ListSnapshots(
	ctx context.Context,
	req *abcitypes.ListSnapshotsRequest,
) (*abcitypes.ListSnapshotsResponse, error)

ListSnapshots is not supported as state-sync must be disabled.

This method is called when a peer requests for snapshots. Note that the response includes only snapshot metadata, not the snapshot chunks.

ListSnapshots implements abcitypes.Application.

func (*SnapsApp) LoadSnapshotChunk 

func (app *SnapsApp) LoadSnapshotChunk(
	ctx context.Context,
	req *abcitypes.LoadSnapshotChunkRequest,
) (*abcitypes.LoadSnapshotChunkResponse, error)

LoadSnapshotChunk is not supported as state-sync must be disabled.

This method is called to retrieve snapshot chunks which may be transported to other peers, i.e. asynchronously called when a peer downloads chunks.

LoadSnapshotChunk implements abcitypes.Application.

func (*SnapsApp) OfferSnapshot 

func (app *SnapsApp) OfferSnapshot(
	ctx context.Context,
	req *abcitypes.OfferSnapshotRequest,
) (*abcitypes.OfferSnapshotResponse, error)

OfferSnapshot is not supported as state-sync must be disabled.

This method is called when a peer received a list of snapshots and chooses one to sync. It will initiate the download of snapshot chunks and restore the snapshot data. Note that this method does not *apply* the snapshot.

OfferSnapshot implements abcitypes.Application.

func (*SnapsApp) PrepareProposal 

func (app *SnapsApp) PrepareProposal(
	ctx context.Context,
	req *abcitypes.PrepareProposalRequest,
) (*abcitypes.PrepareProposalResponse, error)

PrepareProposal implements the PrepareProposal ABCI method and returns a ResponsePrepareProposal object to the client. The PrepareProposal method is responsible for allowing the block proposer to perform application-dependent work in a block before proposing it.

Transactions can be modified, removed, or added by the application. Since the application maintains its own local mempool, it will ignore the transactions provided to it in RequestPrepareProposal. Instead, it will determine which transactions to return based on the mempool's semantics and the MaxTxBytes provided by the client's request.

PrepareProposal implements abcitypes.Application.

func (*SnapsApp) ProcessProposal 

func (app *SnapsApp) ProcessProposal(
	ctx context.Context,
	req *abcitypes.ProcessProposalRequest,
) (*abcitypes.ProcessProposalResponse, error)

ProcessProposal implements the ProcessProposal ABCI method and returns a ResponseProcessProposal object to the client.

The ProcessProposal method is responsible for allowing execution of application-dependent work in a proposed block. Note, the application defines the exact implementation details of ProcessProposal. In general, the application must at the very least ensure that all transactions are valid. If all transactions are valid, then we inform CometBFT that the Status is ACCEPT. However, the application is also able to implement optimizations such as executing the entire proposed block immediately.

If a panic is detected during execution of an application's ProcessProposal handler, it will be recovered and we will reject the proposal.

ProcessProposal implements abcitypes.Application.

func (*SnapsApp) Query 

func (app *SnapsApp) Query(context.Context, *abcitypes.QueryRequest) (*abcitypes.QueryResponse, error)

TODO(midas): Query not yet supported as of v1 Query implements abcitypes.Application.

func (*SnapsApp) VerifyVoteExtension 

func (app *SnapsApp) VerifyVoteExtension(context.Context, *abcitypes.VerifyVoteExtensionRequest) (*abcitypes.VerifyVoteExtensionResponse, error)

VerifyVoteExtension implements the VerifyVoteExtension ABCI method and returns a ResponseVerifyVoteExtension. It calls the applications' VerifyVoteExtension handler which is responsible for performing application-specific business logic in verifying a vote extension from another validator during the pre-commit phase. The response MUST be deterministic. An error is returned if vote extensions are not enabled or if verifyVoteExt fails or panics. We highly recommend a size validation due to performance degradation, see more here https://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed

VerifyVoteExtension implements abcitypes.Application.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.