Add first-class Package type

Author: rustaceanrob

src/error.rs

@@ -75,3 +75,30 @@ impl core::fmt::Display for FetchBlockError {
 }
 
 impl_sourceless_error!(FetchBlockError);
+
+/// Errors when constructing transaction packages.
+#[derive(Debug)]
+pub enum InvalidPackageError {
+    /// Packages may not include more than two transactions and must include at least one
+    /// transaction.
+    InvalidPackageLength(usize),
+    /// Child transactions must spend an output from the parent.
+    UnrelatedTransactions,
+}
+
+impl core::fmt::Display for InvalidPackageError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            InvalidPackageError::InvalidPackageLength(s) => {
+                write!(
+                    f,
+                    "package must include at most two transactions, got {}",
+                    s
+                )
+            }
+            InvalidPackageError::UnrelatedTransactions => {
+                write!(f, "packages must have dependent inputs and outputs.")
+            }
+        }
+    }
+}

src/lib.rs

@@ -60,7 +60,9 @@ pub mod messages;
 /// The structure that communicates with the Bitcoin P2P network and collects data.
 pub mod node;
 
+use bitcoin::OutPoint;
 use chain::Filter;
+use package_type::{OneParentOneChild, Single};
 
 use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::path::PathBuf;
@@ -431,6 +433,190 @@ impl Dialog {
     }
 }
 
+/// Types of packages valid for package relay.
+pub mod package_type {
+    /// Single transaction.
+    pub struct Single;
+    /// Exactly two transactions, one spending from the other.
+    pub struct OneParentOneChild;
+}
+
+mod sealed {
+    pub trait Sealed {}
+}
+
+impl sealed::Sealed for package_type::Single {}
+impl sealed::Sealed for package_type::OneParentOneChild {}
+
+/// Types of packages valid for package relay.
+pub trait PackageType: sealed::Sealed {}
+
+impl PackageType for package_type::Single {}
+impl PackageType for package_type::OneParentOneChild {}
+
+/// Build transaction packages to submit to the network.
+#[derive(Debug)]
+pub struct PackageBuilder<P: PackageType> {
+    package: Vec<Transaction>,
+    _marker: core::marker::PhantomData<P>,
+}
+
+impl<P: PackageType> PackageBuilder<P> {
+    /// Create a package from a single transaction.
+    pub fn new_single(parent: Transaction) -> PackageBuilder<Single> {
+        PackageBuilder {
+            package: vec![parent],
+            _marker: core::marker::PhantomData,
+        }
+    }
+
+    /// Create a package from a single parent and child relationship.
+    ///
+    /// # Errors
+    ///
+    /// If the package is invalid for mempool submission.
+    pub fn new_one_parent_one_child(
+        parent: Transaction,
+        child: Transaction,
+    ) -> Result<PackageBuilder<OneParentOneChild>, error::InvalidPackageError> {
+        let outpoints = {
+            let txid = parent.compute_txid();
+            let mut outpoints = Vec::with_capacity(parent.output.len());
+            for vout in 0..parent.output.len() {
+                outpoints.push(OutPoint {
+                    txid,
+                    vout: vout as u32,
+                });
+            }
+            outpoints
+        };
+        if !child
+            .input
+            .iter()
+            .any(|input| outpoints.contains(&input.previous_output))
+        {
+            return Err(error::InvalidPackageError::UnrelatedTransactions);
+        }
+        Ok(PackageBuilder {
+            package: vec![parent, child],
+            _marker: core::marker::PhantomData,
+        })
+    }
+
+    /// Create a package from an unchecked list of transactions.
+    ///
+    /// # Errors
+    ///
+    /// If the package is invalid for mempool submission.
+    pub fn new_unchecked(package: Vec<Transaction>) -> Result<Package, error::InvalidPackageError> {
+        if package.len() > 2 {
+            return Err(error::InvalidPackageError::InvalidPackageLength(
+                package.len(),
+            ));
+        }
+        if package.is_empty() {
+            return Err(error::InvalidPackageError::InvalidPackageLength(0));
+        }
+        let mut tx_iter = package.into_iter();
+        let parent = tx_iter.next().expect("at least one transaction exists.");
+        let outpoints = {
+            let txid = parent.compute_txid();
+            let mut outpoints = Vec::with_capacity(parent.output.len());
+            for vout in 0..parent.output.len() {
+                outpoints.push(OutPoint {
+                    txid,
+                    vout: vout as u32,
+                });
+            }
+            outpoints
+        };
+        let child = tx_iter.next();
+        // Replace with `let` chain in Rust version 2024
+        if let Some(child) = child {
+            if !child
+                .input
+                .iter()
+                .any(|input| outpoints.contains(&input.previous_output))
+            {
+                return Err(error::InvalidPackageError::UnrelatedTransactions);
+            }
+        }
+        Ok(Package {
+            parent,
+            child: tx_iter.next(),
+        })
+    }
+}
+
+impl PackageBuilder<package_type::Single> {
+    /// Build a package from a single transaction.
+    pub fn build(self) -> Package {
+        Package {
+            parent: self
+                .package
+                .into_iter()
+                .next()
+                .expect("at least one transaction exists."),
+            child: None,
+        }
+    }
+
+    /// Add a dependent transaction to the package.
+    pub fn add_child(mut self, child: Transaction) -> PackageBuilder<OneParentOneChild> {
+        self.package.push(child);
+        PackageBuilder {
+            package: self.package,
+            _marker: core::marker::PhantomData,
+        }
+    }
+}
+
+impl PackageBuilder<package_type::OneParentOneChild> {
+    /// Build a package from a one-parent-one-child topology.
+    pub fn build(self) -> Package {
+        let mut tx_iter = self.package.into_iter();
+        let parent = tx_iter.next().expect("at least two transactions exist");
+        let child = tx_iter.next().expect("at least two transactions exit");
+        Package {
+            parent,
+            child: Some(child),
+        }
+    }
+}
+
+/// A package is a set of dependent transactions to submit to the mempool.
+#[derive(Debug, Clone)]
+pub struct Package {
+    parent: Transaction,
+    child: Option<Transaction>,
+}
+
+impl Package {
+    fn advertise_package(&self) -> Wtxid {
+        match &self.child {
+            Some(child) => child.compute_wtxid(),
+            None => self.parent.compute_wtxid(),
+        }
+    }
+
+    fn parent(&self) -> Transaction {
+        self.parent.clone()
+    }
+
+    fn child(&self) -> Option<Transaction> {
+        self.child.clone()
+    }
+}
+
+impl From<Transaction> for Package {
+    fn from(value: Transaction) -> Self {
+        Package {
+            parent: value,
+            child: None,
+        }
+    }
+}
+
 macro_rules! impl_sourceless_error {
     ($e:ident) => {
         impl std::error::Error for $e {