add more docs

storage/txpool/Cargo.toml

@@ -11,7 +11,7 @@ keywords    = ["cuprate", "txpool", "transaction", "pool", "database"]
 [features]
 
 [dependencies]
-cuprate-database = { path = "../database" }
+cuprate-database = { path = "../database", features = ["heed"] }
 cuprate-database-service = { path = "../service" }
 cuprate-types    = { path = "../../types" }
 cuprate-helper   = { path = "../../helper" , default-features = false, features = ["constants"] }
@@ -26,3 +26,8 @@ tower            = { workspace = true }
 rayon            = { workspace = true }
 
 [dev-dependencies]
+cuprate-test-utils = { path = "../../test-utils" }
+
+tokio              = { workspace = true }
+tempfile           = { workspace = true }
+hex-literal        = { workspace = true }

storage/txpool/src/config.rs

@@ -1,7 +1,154 @@
-use cuprate_database::config::Config as DbConfig;
+use cuprate_database::config::{Config as DbConfig, SyncMode};
 use cuprate_database_service::ReaderThreads;
-use cuprate_helper::fs::cuprate_txpool_dir;
+use cuprate_helper::fs::{cuprate_blockchain_dir, cuprate_txpool_dir};
 use std::borrow::Cow;
+use std::path::Path;
+use cuprate_database::resize::ResizeAlgorithm;
+
+/// The default transaction pool weight limit.
+const DEFAULT_TXPOOL_WEIGHT_LIMIT: usize = 600 * 1024 * 1024;
+
+//---------------------------------------------------------------------------------------------------- ConfigBuilder
+/// Builder for [`Config`].
+///
+// SOMEDAY: there's are many more options to add in the future.
+#[derive(Debug, Clone, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct ConfigBuilder {
+    /// [`Config::db_directory`].
+    db_directory: Option<Cow<'static, Path>>,
+
+    /// [`Config::cuprate_database_config`].
+    db_config: cuprate_database::config::ConfigBuilder,
+
+    /// [`Config::reader_threads`].
+    reader_threads: Option<ReaderThreads>,
+
+    /// [`Config::max_txpool_weight`].
+    max_txpool_weight: Option<usize>,
+}
+
+impl ConfigBuilder {
+    /// Create a new [`ConfigBuilder`].
+    ///
+    /// [`ConfigBuilder::build`] can be called immediately
+    /// after this function to use default values.
+    pub fn new() -> Self {
+        Self {
+            db_directory: None,
+            db_config: cuprate_database::config::ConfigBuilder::new(Cow::Borrowed(
+                cuprate_blockchain_dir(),
+            )),
+            reader_threads: None,
+            max_txpool_weight: None
+        }
+    }
+
+    /// Build into a [`Config`].
+    ///
+    /// # Default values
+    /// If [`ConfigBuilder::db_directory`] was not called,
+    /// the default [`cuprate_blockchain_dir`] will be used.
+    ///
+    /// For all other values, [`Default::default`] is used.
+    pub fn build(self) -> Config {
+        // INVARIANT: all PATH safety checks are done
+        // in `helper::fs`. No need to do them here.
+        let db_directory = self
+            .db_directory
+            .unwrap_or_else(|| Cow::Borrowed(cuprate_blockchain_dir()));
+
+        let reader_threads = self.reader_threads.unwrap_or_default();
+
+        let max_txpool_weight = self.max_txpool_weight.unwrap_or(DEFAULT_TXPOOL_WEIGHT_LIMIT);
+
+        let db_config = self
+            .db_config
+            .db_directory(db_directory)
+            .reader_threads(reader_threads.as_threads())
+            .build();
+
+        Config {
+            db_config,
+            reader_threads,
+            max_txpool_weight
+        }
+    }
+
+    /// Sets a new maximum weight for the transaction pool.
+    pub const fn max_txpool_weight(mut self, max_txpool_weight: usize) -> Self {
+        self.max_txpool_weight = Some(max_txpool_weight);
+        self
+    }
+
+    /// Set a custom database directory (and file) [`Path`].
+    #[must_use]
+    pub fn db_directory(mut self, db_directory: Cow<'static, Path>) -> Self {
+        self.db_directory = Some(db_directory);
+        self
+    }
+
+    /// Calls [`cuprate_database::config::ConfigBuilder::sync_mode`].
+    #[must_use]
+    pub fn sync_mode(mut self, sync_mode: SyncMode) -> Self {
+        self.db_config = self.db_config.sync_mode(sync_mode);
+        self
+    }
+
+    /// Calls [`cuprate_database::config::ConfigBuilder::resize_algorithm`].
+    #[must_use]
+    pub fn resize_algorithm(mut self, resize_algorithm: ResizeAlgorithm) -> Self {
+        self.db_config = self.db_config.resize_algorithm(resize_algorithm);
+        self
+    }
+
+    /// Set a custom [`ReaderThreads`].
+    #[must_use]
+    pub const fn reader_threads(mut self, reader_threads: ReaderThreads) -> Self {
+        self.reader_threads = Some(reader_threads);
+        self
+    }
+
+    /// Tune the [`ConfigBuilder`] for the highest performing,
+    /// but also most resource-intensive & maybe risky settings.
+    ///
+    /// Good default for testing, and resource-available machines.
+    #[must_use]
+    pub fn fast(mut self) -> Self {
+        self.db_config =
+            cuprate_database::config::ConfigBuilder::new(Cow::Borrowed(cuprate_blockchain_dir()))
+                .fast();
+
+        self.reader_threads = Some(ReaderThreads::OnePerThread);
+        self
+    }
+
+    /// Tune the [`ConfigBuilder`] for the lowest performing,
+    /// but also least resource-intensive settings.
+    ///
+    /// Good default for resource-limited machines, e.g. a cheap VPS.
+    #[must_use]
+    pub fn low_power(mut self) -> Self {
+        self.db_config =
+            cuprate_database::config::ConfigBuilder::new(Cow::Borrowed(cuprate_blockchain_dir()))
+                .low_power();
+
+        self.reader_threads = Some(ReaderThreads::One);
+        self
+    }
+}
+
+impl Default for ConfigBuilder {
+    fn default() -> Self {
+        let db_directory = Cow::Borrowed(cuprate_blockchain_dir());
+        Self {
+            db_directory: Some(db_directory.clone()),
+            db_config: cuprate_database::config::ConfigBuilder::new(db_directory),
+            reader_threads: Some(ReaderThreads::default()),
+            max_txpool_weight: Some(DEFAULT_TXPOOL_WEIGHT_LIMIT)
+        }
+    }
+}
 
 //---------------------------------------------------------------------------------------------------- Config
 /// `cuprate_txpool` configuration.

storage/txpool/src/lib.rs

@@ -1,13 +1,16 @@
-mod config;
+pub mod config;
 mod free;
 mod ops;
-mod service;
+pub mod service;
 mod tables;
 mod types;
 
 pub use config::Config;
 pub use free::open;
 
+//re-exports
+pub use cuprate_database;
+
 #[derive(thiserror::Error, Debug)]
 pub enum TxPoolWriteError {
     /// The transaction could not be added as it double spends another tx in the pool.

storage/txpool/src/ops/key_images.rs

@@ -7,6 +7,9 @@ use crate::{tables::SpentKeyImages, types::TransactionHash, TxPoolWriteError};
 /// Adds the transaction key images to the [`SpentKeyImages`] table.
 ///
 /// This function will return an error if any of the key images are already spent.
+///
+/// # Panics
+/// This function will panic if any of the [`Input`]s are not [`Input::ToKey`]
 pub fn add_tx_key_images(
     inputs: &[Input],
     tx_hash: &TransactionHash,
@@ -24,6 +27,9 @@ pub fn add_tx_key_images(
 }
 
 /// Removes key images from the [`SpentKeyImages`] table.
+///
+/// # Panics
+/// This function will panic if any of the [`Input`]s are not [`Input::ToKey`]
 pub fn remove_tx_key_images(
     inputs: &[Input],
     kis_table: &mut impl DatabaseRw<SpentKeyImages>,
@@ -39,7 +45,6 @@ pub fn remove_tx_key_images(
 ///
 /// # Panics
 /// This function will panic if the [`Input`] is not [`Input::ToKey`]
-///
 fn ki_from_input(input: &Input) -> [u8; 32] {
     match input {
         Input::ToKey { key_image, .. } => key_image.compress().0,

storage/txpool/src/ops/tx_read.rs

@@ -1,9 +1,13 @@
-use crate::tables::{Tables, TransactionBlobs};
-use crate::types::TransactionHash;
-use cuprate_database::{DatabaseRw, RuntimeError};
+//! Transaction read ops.
+//!
+//! This module handles reading full transaction data, like getting a transaction from the pool.
+use std::sync::Mutex;
+
+use cuprate_database::RuntimeError;
 use cuprate_types::TransactionVerificationData;
 use monero_serai::transaction::Transaction;
-use std::sync::Mutex;
+
+use crate::{tables::Tables, types::TransactionHash};
 
 /// Gets the [`TransactionVerificationData`] of a transaction in the tx-pool, leaving the tx in the pool.
 pub fn get_transaction_verification_data(

storage/txpool/src/ops/tx_write.rs

@@ -1,20 +1,27 @@
-use crate::ops::key_images::{add_tx_key_images, remove_tx_key_images};
-use crate::tables::TablesMut;
-use crate::types::{TransactionHash, TransactionInfo};
-use crate::TxPoolWriteError;
+//! Transaction writing ops.
+//!
+//! This module handles writing full transaction data, like removing or adding a transaction.
+use std::sync::Arc;
+
 use bytemuck::TransparentWrapper;
+use monero_serai::transaction::{Input, Transaction};
+
 use cuprate_database::{RuntimeError, StorableVec};
 use cuprate_types::TransactionVerificationData;
-use monero_serai::transaction::{Input, Transaction};
-use std::sync::Arc;
+
+use crate::{
+    ops::key_images::{add_tx_key_images, remove_tx_key_images},
+    tables::TablesMut,
+    types::{TransactionHash, TransactionInfo},
+    TxPoolWriteError,
+};
 
 /// Adds a transaction to the tx-pool.
 ///
 /// This function fills in all tables necessary to add the transaction to the pool.
 ///
 /// # Panics
 /// This function will panic if the transactions inputs are not all of type [`Input::ToKey`].
-///
 fn add_transaction(
     tx: Arc<TransactionVerificationData>,
     state_stem: bool,
@@ -50,6 +57,9 @@ fn add_transaction(
 }
 
 /// Removes a transaction from the transaction pool.
+///
+/// # Panics
+/// This function will panic if the transactions inputs are not all of type [`Input::ToKey`].
 fn remove_transaction(
     tx_hash: &TransactionHash,
     tables: &mut impl TablesMut,