Support for Child Pay For Parent (CPFP) #15

aagbotemi · 2025-07-23T21:38:25Z

This PR introduces Child-Pays-For-Parent (CPFP) support to bdk-tx by implementing a new CPFPSet struct, CPFPParams and cpfp_candidates function.
It also add the ancestor fee calculation for CPFP.

This implementation supports:

bumping multiple parent transaction with a single CPFP transaction
Unconfirmed ancestors are considered in fee rate calculation
Added cpfp_candidates
Mempool compliance of ≤25 ancestors count
I've signed all my commits
I ran cargo fmt and cargo clippy before committing

Fixes #14

evanlinjin

Thanks for starting on this!

evanlinjin · 2025-07-23T23:27:30Z

examples/cpfp.rs

+        .into_selection(
+            selection_algorithm_lowest_fee_bnb(FeeRate::from_sat_per_vb_unchecked(1), 100_000),
+            SelectorParams::new(
+                FeeRate::from_sat_per_vb_unchecked(30), // Higher fee rate for 10 sat/vB combined


The API should figure out a package feerate. What we have here is the feerate of the single transaction at the end.

CPFP doesn't actually need any "coin selection". We already know the inputs and outputs, we just need to figure out the fee needed to satisfy a given package feerate.

Thank you for the review, I'll fix the package feerate.

…rate

…nce and fee efficiency

evanlinjin

Thank you for working on this!

Looking through the PR, I realized that I’m not entirely happy with the current state of CanonicalUnspents. Trying to build a CPFP API around it feels a bit clunky. I’m planning to replace this structure with bdk_chain::CanonicalView (WIP), which should make things cleaner.

To move forward with this PR, I suggest the following plan:

Step 1 - Introduce standalone CPFP logic

Let’s first implement standalone CPFP logic that is decoupled from CanonicalUnspents.

pub struct CpfpParams {
    pub package_fee: Amount,
    pub package_weight: Weight,
    pub inputs: Vec<Input>,
    pub target_package_feerate: FeeRate,
    pub output_script: ScriptSource,
}

impl CpfpParams {
    fn into_selection(self) -> Result<Selection, CPFPError> {
        todo!("complete me")
    }
}

Here, CpfpParams assumes the caller has constructed it correctly. We should document this clearly, and later (in a separate PR) introduce helper methods to construct it more safely.

The implementation of CpfpParams::into_selection will likely benefit from using bdk_coin_select::CoinSelector with [select_all](https://docs.rs/bdk_coin_select/latest/bdk_coin_select/struct.CoinSelector.html#method.select_all). You'll still need to do some math to determine the correct parameters. If you discover any missing functionality in bdk_coin_select`, feel free to upstream improvements.

Step 2 - Rebuild the example

Let's then rewrite common::Wallet::create_cpfp_tx using the CpfpParams logic. For simplicity, (since it's just an example), we can:

Select the first owned output from each tx in parent_txids.
Return an error if no owned outputs are found.

Step 3 - Add tests

I recommend starting with a few simple tests:

Given one original tx with feerate x, create CPFP tx with target_package_feerate of x. The resultant CPFP tx feerate should have feerate x.
Given one original tx with feerate x, create a CPFP tx with target_package_feerate of x + y. The resulting package feerate should have a total feerate of x + y (weight(original_tx + CPFP_tx) / fee(original_tx + CPFP_tx)).

After this PR lands, we can start discussing ways to make the API less manual and more ergonomic.

evanlinjin · 2025-08-07T05:24:16Z

src/cpfp.rs

+        canon_utxos: &CanonicalUnspents,
+        target_package_feerate: FeeRate,
+        script_pubkey: &ScriptBuf,
+        plans: impl IntoIterator<Item = Plan>,


This API is a bit confusing. It implicitly requires the plans to be in the same order as selected_outpoints, introducing a hidden ordering invariant. This coupling feels unnecessary and makes the API harder to reason about.

Additionally, this couples the CPFPSet API with CanonicalUnspents...

Okay. I will fix it

evanlinjin · 2025-08-07T05:33:02Z

src/canonical_unspents.rs

+        const MAX_ANCESTORS: usize = 25;
+        if parent_txids.len() > MAX_ANCESTORS {
+            return Err(CPFPError::ExcessUnconfirmedAncestor);
+        }


This implies that parent_txids should be a linked chain of direct spends. This is not what we are going for. We really want parent_txids to be an arbitrary list of txids that we wish to fee-bump.

We want to iterate the ancestors of these parent_txids to accumulate the total fee of all unconfirmed txs. Confirmation status can be accessed via CanonicalUnspents::statuses.

Okay, noted.

aagbotemi · 2025-08-07T09:02:22Z

After this PR lands, we can start discussing ways to make the API less manual and more ergonomic.

Thank you for the review. I'll make the necessary fixes.

…cpfp_tx example

evanlinjin · 2025-08-28T06:56:53Z

src/cpfp.rs

+    /// Create a new [CpfpParams] instance.
+    pub fn new(
+        package_fee: Amount,
+        package_weight: Weight,
+        inputs: impl IntoIterator<Item = impl Into<Input>>,
+        target_package_feerate: FeeRate,
+        output_script: crate::ScriptSource,
+    ) -> Self {
+        Self {
+            package_fee,
+            package_weight,
+            inputs: inputs.into_iter().map(Into::into).collect(),
+            target_package_feerate,
+            output_script,
+        }
+    }


I don't think we should have this as it's not adding any convenience.

Alright, I have fixed that

evanlinjin · 2025-09-09T01:34:33Z

src/cpfp.rs

+pub enum CpfpError {
+    /// Output value is below the dust threshold.
+    OutputBelowDustLimit,
+    /// Total input value is insufficient.
+    InsufficientInputValue,
+    /// No spendable outputs were found.
+    NoSpendableOutputs,
+    /// Failed to compute a valid fee for the child transaction.
+    InvalidFeeCalculation,
+    /// The package feerate (parent + child) is lower than the target feerate.
+    InsufficientPackageFeerate {
+        /// The actual feerate of the package.
+        actual: FeeRate,
+        /// The target feerate that the package should meet or exceed.
+        target: FeeRate,
+    },
+    /// Output script is invalid
+    InvalidOutputScript,
+}


InsufficientInputValue seem to be the only necessary error variant here.

OutputBelowDustLimit is essentially the same thing as InsufficientInputValue.

NoSpendableOutputs can be replaced by InsufficientInputValue.

InvalidFeeCalculation should never happen since we are the ones calculating it. We just don't have enough input value.

InsufficientPackageFeerate should also never happen since we are the ones calculating it. The actual feerate and the target should be exactly the same.

InvalidOutputScript is out of scope here imo.

I think it will be useful to let the caller know how much value is missing. Let me know if you have any thoughts on this.

I agree that InsufficientInputValue can cover all the error cases, and I've updated CpfpParams::into_selection to use a single InsufficientInputValue error variant with a missing field to indicate how much additional value is needed.

evanlinjin · 2025-09-09T02:32:15Z

src/cpfp.rs

+    /// This method calculates the required child transaction fee to achieve the
+    /// target package feerate and creates a selection with the appropriate inputs
+    /// and outputs.
+    pub fn into_selection(self) -> Result<Selection, CpfpError> {


Use the CoinSelector to calculate the cpfp_tx_weight. Everything else can be done with a simple formula:

cpfp_tx_fee = target_fee_rate * (package_weight + cpfp_tx_weight) - package_fee

Okay, I have made the fix

# Conflicts: # examples/common.rs

aagbotemi added 2 commits July 21, 2025 15:21

cpfp support and target feerate added

ef97e0b

cpfp candidates and set

2820fa0

aagbotemi force-pushed the feature/cpfp_support branch from 92150b5 to 5ad7b68 Compare July 24, 2025 09:53

chore: example for cpfp support

b39710f

aagbotemi force-pushed the feature/cpfp_support branch from 5ad7b68 to b39710f Compare July 24, 2025 23:03

evanlinjin requested changes Jul 24, 2025

View reviewed changes

refactor(cpfp): remove coin selection and calculate fee from package …

f22b3bd

…rate

aagbotemi requested a review from evanlinjin July 29, 2025 22:28

refactor(cpfp): improve owned output selection to balance dust avoida…

204e0b5

…nce and fee efficiency

aagbotemi force-pushed the feature/cpfp_support branch from 736ef39 to 204e0b5 Compare July 31, 2025 20:47

evanlinjin requested changes Aug 7, 2025

View reviewed changes

aagbotemi added 2 commits August 24, 2025 14:54

standalone cpfp logic using CpfpParams and rebuilding Wallet::create_…

ebe46b8

…cpfp_tx example

Add CPFP feerate tests for same and higher target feerates

e6ebdc0

aagbotemi requested a review from evanlinjin August 24, 2025 15:21

evanlinjin requested changes Sep 9, 2025

View reviewed changes

unify CpfpError to InsufficientInputValue, use CoinSelector for weight

e986959

aagbotemi requested a review from evanlinjin September 9, 2025 23:14

Merge branch 'master' into feature/cpfp_support

31cd70f

# Conflicts: # examples/common.rs

Support for Child Pay For Parent (CPFP) #15

Are you sure you want to change the base?

Support for Child Pay For Parent (CPFP) #15

Uh oh!

Conversation

aagbotemi commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

evanlinjin left a comment

Choose a reason for hiding this comment

Uh oh!

evanlinjin Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanlinjin left a comment

Choose a reason for hiding this comment

Step 1 - Introduce standalone CPFP logic

Step 2 - Rebuild the example

Step 3 - Add tests

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aagbotemi commented Aug 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanlinjin Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aagbotemi commented Jul 23, 2025 •

edited

Loading

evanlinjin Jul 23, 2025 •

edited

Loading

evanlinjin Sep 9, 2025 •

edited

Loading