sc_transaction_pool/

builder.rs

// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0

// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.

// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.

// You should have received a copy of the GNU General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.

//! Utility for building substrate transaction pool trait object.

use crate::{
	fork_aware_txpool::ForkAwareTxPool as ForkAwareFullPool,
	graph::{base_pool::Transaction, IsValidator, Options},
	single_state_txpool::BasicPool as SingleStateFullPool,
	LOG_TARGET,
};
use prometheus_endpoint::Registry as PrometheusRegistry;
use sc_transaction_pool_api::{LocalTransactionPool, MaintainedTransactionPool};
use sp_core::traits::SpawnEssentialNamed;
use sp_runtime::traits::Block as BlockT;
use std::{marker::PhantomData, sync::Arc, time::Duration};

/// The type of transaction pool.
#[derive(Debug, Clone)]
pub enum TransactionPoolType {
	/// Single-state transaction pool
	SingleState,
	/// Fork-aware transaction pool
	ForkAware,
}

/// Transaction pool options.
#[derive(Debug, Clone)]
pub struct TransactionPoolOptions {
	txpool_type: TransactionPoolType,
	options: Options,
	/// If `true`, the pool is only maintained on best blocks (legacy behavior).
	///
	/// Only relevant for the fork-aware pool.
	best_blocks_only: bool,
}

impl Default for TransactionPoolOptions {
	fn default() -> Self {
		Self {
			txpool_type: TransactionPoolType::SingleState,
			options: Default::default(),
			best_blocks_only: false,
		}
	}
}

impl TransactionPoolOptions {
	/// Creates the options for the transaction pool using given parameters.
	pub fn new_with_params(
		pool_limit: usize,
		pool_bytes: usize,
		tx_ban_seconds: Option<u64>,
		txpool_type: TransactionPoolType,
		is_dev: bool,
		best_blocks_only: bool,
	) -> TransactionPoolOptions {
		let mut options = Options::default();

		// ready queue
		options.ready.count = pool_limit;
		options.ready.total_bytes = pool_bytes;

		// future queue
		let factor = 10;
		options.future.count = pool_limit / factor;
		options.future.total_bytes = pool_bytes / factor;

		options.ban_time = if let Some(ban_seconds) = tx_ban_seconds {
			Duration::from_secs(ban_seconds)
		} else if is_dev {
			Duration::from_secs(0)
		} else {
			Duration::from_secs(30 * 60)
		};

		TransactionPoolOptions { options, txpool_type, best_blocks_only }
	}

	/// Creates predefined options for benchmarking
	pub fn new_for_benchmarks() -> TransactionPoolOptions {
		TransactionPoolOptions {
			options: Options {
				ready: crate::graph::base_pool::Limit {
					count: 100_000,
					total_bytes: 100 * 1024 * 1024,
				},
				future: crate::graph::base_pool::Limit {
					count: 100_000,
					total_bytes: 100 * 1024 * 1024,
				},
				reject_future_transactions: false,
				ban_time: Duration::from_secs(30 * 60),
			},
			txpool_type: TransactionPoolType::SingleState,
			best_blocks_only: false,
		}
	}

	/// Returns whether the transaction pool should be notified about *every* imported block.
	pub fn use_all_block_notifications(&self) -> bool {
		matches!(self.txpool_type, TransactionPoolType::ForkAware) && !self.best_blocks_only
	}
}

/// The client capabilities the transaction pool of a full node relies on.
///
/// It is blanket implemented, so every client able to validate transactions against the runtime
/// qualifies. Only the code that actually builds a pool needs it: the [`Builder`] and the
/// [`crate::FullChainApi`] it wires up. Holding a [`TransactionPoolHandle`] requires no client
/// bound at all, since the handle is parameterized by the block type alone.
pub trait ClientForTransactionPool<Block: BlockT>:
	sp_api::ProvideRuntimeApi<
		Block,
		Api: sp_transaction_pool::runtime_api::TaggedTransactionQueue<Block>,
	> + sc_client_api::BlockBackend<Block>
	+ sc_client_api::blockchain::HeaderBackend<Block>
	+ sp_runtime::traits::BlockIdTo<Block>
	+ sp_blockchain::HeaderMetadata<Block, Error = sp_blockchain::Error>
	+ 'static
{
}

impl<Block: BlockT, T> ClientForTransactionPool<Block> for T where
	T: sp_api::ProvideRuntimeApi<
			Block,
			Api: sp_transaction_pool::runtime_api::TaggedTransactionQueue<Block>,
		> + sc_client_api::BlockBackend<Block>
		+ sc_client_api::blockchain::HeaderBackend<Block>
		+ sp_runtime::traits::BlockIdTo<Block>
		+ sp_blockchain::HeaderMetadata<Block, Error = sp_blockchain::Error>
		+ 'static
{
}

/// `FullClientTransactionPool` is a trait that combines the functionality of
/// `MaintainedTransactionPool` and `LocalTransactionPool` for a given `Block`.
///
/// This trait defines the requirements for a full client transaction pool, ensuring
/// that it can handle transactions submission and maintenance.
///
/// The associated types are fully determined by `Block`, so the client used to build the pool does
/// not appear here.
pub trait FullClientTransactionPool<Block>: MaintainedTransactionPool<
		Block = Block,
		Hash = <Block as BlockT>::Hash,
		InPoolTransaction = Transaction<<Block as BlockT>::Hash, Arc<<Block as BlockT>::Extrinsic>>,
		Error = crate::error::Error,
	> + LocalTransactionPool<Block = Block, Hash = <Block as BlockT>::Hash, Error = crate::error::Error>
where
	Block: BlockT,
{
}

impl<Block, P> FullClientTransactionPool<Block> for P
where
	Block: BlockT,
	P: MaintainedTransactionPool<
			Block = Block,
			Hash = <Block as BlockT>::Hash,
			InPoolTransaction = Transaction<
				<Block as BlockT>::Hash,
				Arc<<Block as BlockT>::Extrinsic>,
			>,
			Error = crate::error::Error,
		> + LocalTransactionPool<
			Block = Block,
			Hash = <Block as BlockT>::Hash,
			Error = crate::error::Error,
		>,
{
}

/// The public type alias for the trait object providing the implementation of
/// `FullClientTransactionPool` for the given `Block` type.
///
/// This handle abstracts away the specific type of the transaction pool, e.g. fork-aware or
/// single-state. It is unsized, so it is always used behind an `Arc`.
pub type TransactionPoolHandle<Block> = dyn FullClientTransactionPool<Block>;

/// Builder allowing to create specific instance of transaction pool.
pub struct Builder<'a, Block, Client> {
	options: TransactionPoolOptions,
	is_validator: IsValidator,
	prometheus: Option<&'a PrometheusRegistry>,
	client: Arc<Client>,
	spawner: Box<dyn SpawnEssentialNamed>,
	_phantom: PhantomData<(Client, Block)>,
}

impl<'a, Client, Block> Builder<'a, Block, Client>
where
	Block: BlockT,
	Client: ClientForTransactionPool<Block>
		+ sc_client_api::ExecutorProvider<Block>
		+ sc_client_api::UsageProvider<Block>,
	<Block as BlockT>::Hash: std::marker::Unpin,
{
	/// Creates new instance of `Builder`
	pub fn new(
		spawner: impl SpawnEssentialNamed + 'static,
		client: Arc<Client>,
		is_validator: IsValidator,
	) -> Builder<'a, Block, Client> {
		Builder {
			options: Default::default(),
			_phantom: Default::default(),
			spawner: Box::new(spawner),
			client,
			is_validator,
			prometheus: None,
		}
	}

	/// Sets the options used for creating a transaction pool instance.
	pub fn with_options(mut self, options: TransactionPoolOptions) -> Self {
		self.options = options;
		self
	}

	/// Sets the prometheus endpoint used in a transaction pool instance.
	pub fn with_prometheus(mut self, prometheus: Option<&'a PrometheusRegistry>) -> Self {
		self.prometheus = prometheus;
		self
	}

	/// Creates an instance of transaction pool.
	pub fn build(self) -> Arc<TransactionPoolHandle<Block>> {
		tracing::info!(
			target: LOG_TARGET,
			txpool_type = ?self.options.txpool_type,
			ready = ?self.options.options.ready,
			future = ?self.options.options.future,
			"Creating transaction pool"
		);
		match self.options.txpool_type {
			TransactionPoolType::SingleState => Arc::new(SingleStateFullPool::new_full(
				self.options.options,
				self.is_validator,
				self.prometheus,
				self.spawner,
				self.client,
			)),
			TransactionPoolType::ForkAware => Arc::new(ForkAwareFullPool::new_full(
				self.options.options,
				self.is_validator,
				self.prometheus,
				self.spawner,
				self.client,
			)),
		}
	}
}