Expand description
General-purpose transactions pool.
The transactions pool is a complex data structure that holds a list of pending transactions, in other words transactions that should later be included in blocks, and a list of transactions that have been included in non-finalized blocks.
See the parent module’s documentation for an overview of transactions.
§Overview
The transactions pool stores a list of transactions that the local node desires to include in blocks, and a list of transactions that have already been included in blocks. Each of these transactions is either validated or not. A transaction in a block is assumed to always succeed validation. A validated transaction that isn’t present in any block is a transaction that is assumed to be includable in a block in the future.
The order in which transactions can be included in a block follows a complex system of “provided” and “required” tags. A transaction that requires some tags can only be included after all these tags have been provided by transactions earlier in the chain.
The transactions pool isn’t only about deciding which transactions to include in a block when authoring, but also about tracking the status of interesting transactions between the moment they become interesting and the moment the block they are included in becomes finalized. This is relevant both if the local node can potentially author blocks or not.
The transactions pool tracks the height of the best chain, and only of the best chain. More precisely, it is aware of the height of the current best block. Forks are tracked.
§Usage
A Pool is a collection of transactions. Each transaction in the pool exposes three
properties:
- Whether or not it has been validated, and if yes, the block against which it has been
validated and the characteristics of the transaction (as provided by the runtime). These
characterstics are: the tags it provides and requires, its longevity, and its priority.
See the
validatemodule for more information. - The height of the block, if any, in which the transaction has been included.
- A so-called user data, an opaque field controlled by the API user.
Use Pool::add_unvalidated to add to the pool a transaction that should be included in a
block at a later point in time.
When a new block is considered as best, use Pool::retract_blocks to remove all the re-orged
blocks, then Pool::append_empty_block and
Pool::best_block_add_transaction_by_scale_encoding to add the new block(s). The
transactions that are passed to Pool::best_block_add_transaction_by_scale_encoding are
added to the pool.
Use Pool::unvalidated_transactions to obtain the list of transactions that should be
validated. Validation should be performed using the validate module, and
the result reported with Pool::set_validation_result.
Use Pool::remove_included when a block has been finalized to remove from the pool the
transactions that are present in the finalized block and below.
When authoring a block, use Pool::append_empty_block and
Pool::best_block_includable_transactions to determine which transaction to include
next. Use Pool::best_block_add_transaction_by_id when the transaction has been included.
§Out of scope
The following are examples of things that are related transactions pool to but out of scope of this data structure:
- Watching the state of transactions.
- Sending transactions to other peers.
Re-exports§
pub use super::validate::ValidTransaction;
Structs§
- Configuration for
Pool::new. - Data structure containing transactions. See the module-level documentation for more info.
- Identifier of a transaction stored within the
Pool.