base

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 20, 2023 License: Apache-2.0 Imports: 13 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsEmpty 

func IsEmpty[C comparable](mempool sdkmempool.Mempool) error

Types

type BaseLane 

type BaseLane struct {

	// LaneMempool is the mempool that is responsible for storing transactions
	// that are waiting to be processed.
	block.LaneMempool
	// contains filtered or unexported fields
}

BaseLane is a generic implementation of a lane. It is meant to be used as a base for other lanes to be built on top of. It provides a default implementation of the MatchHandler, PrepareLaneHandler, ProcessLaneHandler, and CheckOrderHandler. To extend this lane, you must either utilize the default handlers or construct your own that you pass into the base/setters.

func NewBaseLane 

func NewBaseLane(
	cfg LaneConfig,
	laneName string,
	laneMempool block.LaneMempool,
	matchHandlerFn MatchHandler,
) *BaseLane

NewBaseLane returns a new lane base. When creating this lane, the type of the lane must be specified. The type of the lane is directly associated with the type of the mempool that is used to store transactions that are waiting to be processed.

func (*BaseLane) CheckIgnoreList 

func (l *BaseLane) CheckIgnoreList(ctx sdk.Context, tx sdk.Tx) bool

CheckIgnoreList returns true if the transaction is on the ignore list. The ignore list is utilized to prevent transactions that should be considered in other lanes from being considered from this lane.

func (*BaseLane) DefaultPrepareLaneHandler 

func (l *BaseLane) DefaultPrepareLaneHandler() PrepareLaneHandler

DefaultPrepareLaneHandler returns a default implementation of the PrepareLaneHandler. It selects all transactions in the mempool that are valid and not already in the partial proposal. It will continue to reap transactions until the maximum blockspace/gas for this lane has been reached. Additionally, any transactions that are invalid will be returned.

func (*BaseLane) DefaultProcessLaneHandler 

func (l *BaseLane) DefaultProcessLaneHandler() ProcessLaneHandler

DefaultProcessLaneHandler returns a default implementation of the ProcessLaneHandler. It verifies the following invariants: 1. All transactions belong to this lane. 2. All transactions respect the priority defined by the mempool. 3. All transactions are valid respecting the verification logic of the lane.

func (*BaseLane) GetMaxBlockSpace 

func (l *BaseLane) GetMaxBlockSpace() math.LegacyDec

GetMaxBlockSpace returns the maximum amount of block space that the lane is allowed to consume as a percentage of the total block space.

func (*BaseLane) Logger 

func (l *BaseLane) Logger() log.Logger

Logger returns the logger for the lane.

func (*BaseLane) Match 

func (l *BaseLane) Match(ctx sdk.Context, tx sdk.Tx) bool

Match returns true if the transaction should be processed by this lane. This function first determines if the transaction matches the lane and then checks if the transaction is on the ignore list. If the transaction is on the ignore list, it returns false.

func (*BaseLane) Name 

func (l *BaseLane) Name() string

Name returns the name of the lane.

func (*BaseLane) PrepareLane 

func (l *BaseLane) PrepareLane(
	ctx sdk.Context,
	proposal proposals.Proposal,
	next block.PrepareLanesHandler,
) (proposals.Proposal, error)

PrepareLane will prepare a partial proposal for the lane. It will select transactions from the lane respecting the selection logic of the prepareLaneHandler. It will then update the partial proposal with the selected transactions. If the proposal is unable to be updated, we return an error. The proposal will only be modified if it passes all of the invariant checks.

func (*BaseLane) ProcessLane 

func (l *BaseLane) ProcessLane(
	ctx sdk.Context,
	proposal proposals.Proposal,
	txs [][]byte,
	next block.ProcessLanesHandler,
) (proposals.Proposal, error)

ProcessLane verifies that the transactions included in the block proposal are valid respecting the verification logic of the lane (processLaneHandler). If any of the transactions are invalid, we return an error. If all of the transactions are valid, we return the updated proposal.

func (*BaseLane) SetAnteHandler 

func (l *BaseLane) SetAnteHandler(anteHandler sdk.AnteHandler)

SetAnteHandler sets the ante handler for the lane.

func (*BaseLane) SetIgnoreList 

func (l *BaseLane) SetIgnoreList(lanes []block.Lane)

SetIgnoreList sets the ignore list for the lane. The ignore list is a list of lanes that the lane should ignore when processing transactions.

func (*BaseLane) SetPrepareLaneHandler 

func (l *BaseLane) SetPrepareLaneHandler(prepareLaneHandler PrepareLaneHandler)

SetPrepareLaneHandler sets the prepare lane handler for the lane. This handler is called when a new proposal is being requested and the lane needs to submit transactions it wants included in the block.

func (*BaseLane) SetProcessLaneHandler 

func (l *BaseLane) SetProcessLaneHandler(processLaneHandler ProcessLaneHandler)

SetProcessLaneHandler sets the process lane handler for the lane. This handler is called when a new proposal is being verified and the lane needs to verify that the transactions included in the proposal are valid respecting the verification logic of the lane.

func (*BaseLane) TxDecoder 

func (l *BaseLane) TxDecoder() sdk.TxDecoder

TxDecoder returns the tx decoder for the lane.

func (*BaseLane) TxEncoder 

func (l *BaseLane) TxEncoder() sdk.TxEncoder

TxEncoder returns the tx encoder for the lane.

func (*BaseLane) ValidateBasic 

func (l *BaseLane) ValidateBasic() error

ValidateBasic ensures that the lane was constructed properly. In the case that the lane was not constructed with proper handlers, default handlers are set.

func (*BaseLane) VerifyTx added in v1.1.0 

func (l *BaseLane) VerifyTx(ctx sdk.Context, tx sdk.Tx, simulate bool) error

VerifyTx verifies that the transaction is valid respecting the ante verification logic of of the antehandler chain.

type LaneConfig 

type LaneConfig struct {
	Logger      log.Logger
	TxEncoder   sdk.TxEncoder
	TxDecoder   sdk.TxDecoder
	AnteHandler sdk.AnteHandler

	// SignerExtractor defines the interface used for extracting the expected signers of a transaction
	// from the transaction.
	SignerExtractor signer_extraction.Adapter

	// MaxBlockSpace defines the relative percentage of block space that can be
	// used by this lane. NOTE: If this is set to zero, then there is no limit
	// on the number of transactions that can be included in the block for this
	// lane (up to maxTxBytes as provided by the request). This is useful for the default lane.
	MaxBlockSpace math.LegacyDec

	// IgnoreList defines the list of lanes to ignore when processing transactions. This
	// is useful for when you want lanes to exist after the default lane. For example,
	// say there are two lanes: default and free. The free lane should be processed after
	// the default lane. In this case, the free lane should be added to the ignore list
	// of the default lane. Otherwise, the transactions that belong to the free lane
	// will be processed by the default lane (which accepts all transactions by default).
	IgnoreList []block.Lane

	// MaxTxs sets the maximum number of transactions allowed in the mempool with
	// the semantics:
	// - if MaxTx == 0, there is no cap on the number of transactions in the mempool
	// - if MaxTx > 0, the mempool will cap the number of transactions it stores,
	//   and will prioritize transactions by their priority and sender-nonce
	//   (sequence number) when evicting transactions.
	// - if MaxTx < 0, `Insert` is a no-op.
	MaxTxs int
}

LaneConfig defines the basic configurations needed for a lane.

func NewLaneConfig 

func NewLaneConfig(
	logger log.Logger,
	txEncoder sdk.TxEncoder,
	txDecoder sdk.TxDecoder,
	anteHandler sdk.AnteHandler,
	signerExtractor signer_extraction.Adapter,
	maxBlockSpace math.LegacyDec,
) LaneConfig

NewLaneConfig returns a new LaneConfig. This will be embedded in a lane.

func (*LaneConfig) ValidateBasic 

func (c *LaneConfig) ValidateBasic() error

ValidateBasic validates the lane configuration.

type MatchHandler 

type MatchHandler func(ctx sdk.Context, tx sdk.Tx) bool

MatchHandler is utilized to determine if a transaction should be included in the lane. This function can be a stateless or stateful check on the transaction.

func DefaultMatchHandler 

func DefaultMatchHandler() MatchHandler

DefaultMatchHandler returns a default implementation of the MatchHandler. It matches all transactions.

type Mempool 

type Mempool[C comparable] struct {
	// contains filtered or unexported fields
}

Mempool defines a mempool that orders transactions based on the txPriority. The mempool is a wrapper on top of the SDK's Priority Nonce mempool. It include's additional helper functions that allow users to determine if a transaction is already in the mempool and to compare the priority of two transactions.

func NewMempool 

func NewMempool[C comparable](txPriority TxPriority[C], txEncoder sdk.TxEncoder, extractor signer_extraction.Adapter, maxTx int) *Mempool[C]

NewMempool returns a new Mempool.

func (*Mempool[C]) Compare 

func (cm *Mempool[C]) Compare(ctx sdk.Context, this sdk.Tx, other sdk.Tx) (int, error)

Compare determines the relative priority of two transactions belonging in the same lane. There are two cases to consider:

  1. The transactions have the same signer. In this case, we compare the sequence numbers.
  2. The transactions have different signers. In this case, we compare the priorities of the transactions.

Compare will return -1 if this transaction has a lower priority than the other transaction, 0 if they have the same priority, and 1 if this transaction has a higher priority than the other transaction.

func (*Mempool[C]) Contains 

func (cm *Mempool[C]) Contains(tx sdk.Tx) bool

Contains returns true if the transaction is contained in the mempool.

func (*Mempool[C]) CountTx 

func (cm *Mempool[C]) CountTx() int

CountTx returns the number of transactions in the mempool.

func (*Mempool[C]) Insert 

func (cm *Mempool[C]) Insert(ctx context.Context, tx sdk.Tx) error

Insert inserts a transaction into the mempool.

func (*Mempool[C]) Remove 

func (cm *Mempool[C]) Remove(tx sdk.Tx) error

Remove removes a transaction from the mempool.

func (*Mempool[C]) Select 

func (cm *Mempool[C]) Select(ctx context.Context, txs [][]byte) sdkmempool.Iterator

Select returns an iterator of all transactions in the mempool. NOTE: If you remove a transaction from the mempool while iterating over the transactions, the iterator will not be aware of the removal and will continue to iterate over the removed transaction. Be sure to reset the iterator if you remove a transaction.

type PrepareLaneHandler 

type PrepareLaneHandler func(
	ctx sdk.Context,
	proposal proposals.Proposal,
	limit proposals.LaneLimits,
) (txsToInclude []sdk.Tx, txsToRemove []sdk.Tx, err error)

PrepareLaneHandler is responsible for preparing transactions to be included in the block from a given lane. Given a lane, this function should return the transactions to include in the block, the transactions that must be removed from the lane, and an error if one occurred.

func NoOpPrepareLaneHandler 

func NoOpPrepareLaneHandler() PrepareLaneHandler

NoOpPrepareLaneHandler returns a no-op prepare lane handler. This should only be used for testing.

func PanicPrepareLaneHandler 

func PanicPrepareLaneHandler() PrepareLaneHandler

PanicPrepareLaneHandler returns a prepare lane handler that panics. This should only be used for testing.

type PriorityNonceIterator 

type PriorityNonceIterator[C comparable] struct {
	// contains filtered or unexported fields
}

PriorityNonceIterator defines an iterator that is used for mempool iteration on Select().

func (*PriorityNonceIterator[C]) Next 

func (i *PriorityNonceIterator[C]) Next() sdkmempool.Iterator

func (*PriorityNonceIterator[C]) Tx 

func (i *PriorityNonceIterator[C]) Tx() sdk.Tx

type PriorityNonceMempool 

type PriorityNonceMempool[C comparable] struct {
	// contains filtered or unexported fields
}

PriorityNonceMempool is a mempool implementation that stores txs in a partially ordered set by 2 dimensions: priority, and sender-nonce (sequence number). Internally it uses one priority ordered skip list and one skip list per sender ordered by sender-nonce (sequence number). When there are multiple txs from the same sender, they are not always comparable by priority to other sender txs and must be partially ordered by both sender-nonce and priority.

func DefaultPriorityMempool 

func DefaultPriorityMempool(extractor signer_extraction.DefaultAdapter) *PriorityNonceMempool[int64]

DefaultPriorityMempool returns a priorityNonceMempool with no options.

func NewPriorityMempool 

func NewPriorityMempool[C comparable](cfg PriorityNonceMempoolConfig[C], extractor signer_extraction.Adapter) *PriorityNonceMempool[C]

NewPriorityMempool returns the SDK's default mempool implementation which returns txs in a partial order by 2 dimensions; priority, and sender-nonce.

func (*PriorityNonceMempool[C]) CountTx 

func (mp *PriorityNonceMempool[C]) CountTx() int

CountTx returns the number of transactions in the mempool.

func (*PriorityNonceMempool[C]) Insert 

func (mp *PriorityNonceMempool[C]) Insert(ctx context.Context, tx sdk.Tx) error

Insert attempts to insert a Tx into the app-side mempool in O(log n) time, returning an error if unsuccessful. Sender and nonce are derived from the transaction's first signature.

Transactions are unique by sender and nonce. Inserting a duplicate tx is an O(log n) no-op.

Inserting a duplicate tx with a different priority overwrites the existing tx, changing the total order of the mempool.

func (*PriorityNonceMempool[C]) NextSenderTx 

func (mp *PriorityNonceMempool[C]) NextSenderTx(sender string) sdk.Tx

NextSenderTx returns the next transaction for a given sender by nonce order, i.e. the next valid transaction for the sender. If no such transaction exists, nil will be returned.

func (*PriorityNonceMempool[C]) Remove 

func (mp *PriorityNonceMempool[C]) Remove(tx sdk.Tx) error

Remove removes a transaction from the mempool in O(log n) time, returning an error if unsuccessful.

func (*PriorityNonceMempool[C]) Select 

func (mp *PriorityNonceMempool[C]) Select(_ context.Context, _ [][]byte) sdkmempool.Iterator

Select returns a set of transactions from the mempool, ordered by priority and sender-nonce in O(n) time. The passed in list of transactions are ignored. This is a readonly operation, the mempool is not modified.

The maxBytes parameter defines the maximum number of bytes of transactions to return.

type PriorityNonceMempoolConfig 

type PriorityNonceMempoolConfig[C comparable] struct {
	// TxPriority defines the transaction priority and comparator.
	TxPriority TxPriority[C]

	// OnRead is a callback to be called when a tx is read from the mempool.
	OnRead func(tx sdk.Tx)

	// TxReplacement is a callback to be called when duplicated transaction nonce
	// detected during mempool insert. An application can define a transaction
	// replacement rule based on tx priority or certain transaction fields.
	TxReplacement func(op, np C, oTx, nTx sdk.Tx) bool

	// MaxTx sets the maximum number of transactions allowed in the mempool with
	// the semantics:
	// - if MaxTx == 0, there is no cap on the number of transactions in the mempool
	// - if MaxTx > 0, the mempool will cap the number of transactions it stores,
	//   and will prioritize transactions by their priority and sender-nonce
	//   (sequence number) when evicting transactions.
	// - if MaxTx < 0, `Insert` is a no-op.
	MaxTx int
}

PriorityNonceMempoolConfig defines the configuration used to configure the PriorityNonceMempool.

func DefaultPriorityNonceMempoolConfig 

func DefaultPriorityNonceMempoolConfig() PriorityNonceMempoolConfig[int64]

type ProcessLaneHandler 

type ProcessLaneHandler func(ctx sdk.Context, partialProposal []sdk.Tx) error

ProcessLaneHandler is responsible for processing transactions that are included in a block and belong to a given lane. This handler must return an error if the transactions are not correctly ordered, do not belong to this lane, or any other relevant error.

func NoOpProcessLaneHandler 

func NoOpProcessLaneHandler() ProcessLaneHandler

NoOpProcessLaneHandler returns a no-op process lane handler. This should only be used for testing.

func PanicProcessLaneHandler 

func PanicProcessLaneHandler() ProcessLaneHandler

PanicProcessLanesHandler returns a process lanes handler that panics. This should only be used for testing.

type TxPriority 

type TxPriority[C comparable] struct {
	// GetTxPriority returns the priority of the transaction. A priority must be
	// comparable via Compare.
	GetTxPriority func(ctx context.Context, tx sdk.Tx) C

	// CompareTxPriority compares two transaction priorities. The result should be
	// 0 if a == b, -1 if a < b, and +1 if a > b.
	Compare func(a, b C) int

	// MinValue defines the minimum priority value, e.g. MinInt64. This value is
	// used when instantiating a new iterator and comparing weights.
	MinValue C
}

TxPriority defines a type that is used to retrieve and compare transaction priorities. Priorities must be comparable.

func DefaultTxPriority 

func DefaultTxPriority() TxPriority[string]

DefaultTxPriority returns a default implementation of the TxPriority. It prioritizes transactions by their fee.

func NewDefaultTxPriority 

func NewDefaultTxPriority() TxPriority[int64]

NewDefaultTxPriority returns a TxPriority comparator using ctx.Priority as the defining transaction priority.

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.