Skip to content

Fix outputs exceed inputs - #1988

Open
Hardeezah wants to merge 1 commit into
payjoin:masterfrom
Hardeezah:fix-outputs-exceed-inputs
Open

Hardeezah wants to merge 1 commit into
payjoin:masterfrom
Hardeezah:fix-outputs-exceed-inputs

Conversation

@Hardeezah

Copy link
Copy Markdown
Contributor

Fixes #1939

Summary

The receiver must cover any increase in total output value with their own inputs, or the proposal's absolute fee would fall below the original transaction's and the sender would reject it. This adds a check at the fee range calculation step so both v1 and v2 paths reject proposals where outputs exceed inputs.

Reviewer

Requested reviewer: @xstoicunicornx

Changes

  • Add shared helper receiver_min_input_amount to compute the minimum input value the receiver must contribute (computed as max(0, proposal outputs - original outputs)).
  • Enforce the check in WantsFeeRange::calculate_psbt_with_fee_range: if receiver input sum is less than the required minimum, return InternalPayloadError::OutputsExceedInputs.
  • Add InternalPayloadError::OutputsExceedInputs, map it to JsonReply::NotEnoughMoney, and add a Display message.
  • Add regression tests in payjoin/src/core/receive/common/mod.rs: rejection when outputs exceed inputs without receiver inputs, and acceptance when the increase is covered by a contributed receiver input.
  • Add v2 regression test receiver_rejects_proposal_with_outputs_exceeding_inputs in payjoin/src/core/receive/v2/mod.rs.
  • Update payjoin/CHANGELOG.md under ## Unreleased -> ### Bug Fixes referencing Proposal outputs can exceed inputs #1939.

Rationale

The check is placed in WantsFeeRange::calculate_psbt_with_fee_range because both v1 and v2 reach this point, and it is the right spot to catch the fee inconsistency before producing a proposal. Output increases covered by contributed receiver inputs are allowed; the check ensures coverage.

Testing

  • cargo test -p payjoin --all-features --lib: all pass (291 passed, 1 ignored)
  • cargo test -p payjoin --all-features --test integration: all pass (16 passed)
  • cargo test -p payjoin --all-features --doc: all pass (2 passed, 1 ignored)
  • cargo fmt --all -- --check: clean
  • cargo clippy -p payjoin --all-features -- -D warnings: clean
  • RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features --document-private-items -p payjoin: clean

This is non-breaking (only a crate-private error variant was added).

AI Disclosure

This pull request description is AI-assisted and reviewed by me. Local AI review was completed locally in accordance with AGENTS.md.

Pull Request Checklist

Please confirm the following before requesting review:

@coveralls

coveralls commented Oct 17, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Report for CI Build 41922852427

Coverage increased (+0.04%) to 87.566%

Details

  • Coverage increased (+0.04%) from the base build.
  • Patch coverage: 6 uncovered changes across 2 files (83 of 89 lines covered, 93.26%).
  • No coverage regressions found.

Uncovered Changes

File Changed Covered %
payjoin/src/core/receive/error.rs 4 0 0.0%
payjoin/src/core/receive/common/mod.rs 53 51 96.23%
Total (3 files) 89 83 93.26%

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 18031
Covered Lines: 15789
Line Coverage: 87.57%
Coverage Strength: 319.33 hits per line

💛 - Coveralls

@xstoicunicornx xstoicunicornx self-assigned this Oct 19, 2026

@caarloshenriq caarloshenriq left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concept ACK a3bd660

The check placement matches what was agreed in #1939, and the tests pass locally. Left some questions inline

Also, the branch has a merge commit from upstream/master. Could you rebase instead?

Comment thread payjoin/src/core/receive/common/mod.rs Outdated
self.proposal.receiver_inputs.iter().map(|input| input.previous_txout().value),
)
.map_err(|_| InternalPayloadError::FeeCalculationOverflow)?;
if receiver_input_amount < self.receiver_min_input_amount()? {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is “outputs exceed inputs” what this condition actually checks? What happens if the receiver raises its output by 1 sat without contributing inputs? Do the proposal’s outputs exceed its inputs in that case?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The name OutputsExceedInputs came directly from the title of issue #1939 where receiver output additions exceed input contributions. You are right that with a 1 sat increase total outputs do not exceed total inputs, but the fee still drops below the original fee. If preferred, I can rename the error to something like AbsoluteFeeDecreased to be more precise.

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated
wants_inputs.commit_inputs().save(&persister).expect("Inputs should be committed");
let result = wants_fee_range.apply_fee_range(None, None).save(&persister);

assert!(result.is_err(), "A proposal whose outputs exceed its inputs must be rejected");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

apply_fee_range maps this to a transient error and returns the receiver in WantsFeeRange. From that state, is there anything the receiver can do to recover, given inputs are already committed? Should this be fatal instead? Also, could this assert the specific error rather than just is_err()?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is transient because apply_fee_range uniformly maps all calculate_psbt payload errors to transient for consistency across the v2 typestate machine. You are right that the receiver cannot recover once inputs are committed, so I can look into making it fatal if we want to change that pattern, and I will update the test to assert the specific error variant.

Comment thread payjoin/src/core/receive/common/mod.rs Outdated
let original = original_from_test_vector();
let original_fee = original.psbt.fee().expect("Original PSBT should have a valid fee");
let original_output = original.psbt.unsigned_tx.output[1].clone();
// Raise the receiver's output by more than the original fee so the

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does the increase need to be larger than the original fee for this test? Would the check behave differently with a smaller increase?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That test setup came directly from the reproduction test provided in issue #1939 to test the negative fee case. The check behaves the exact same way with a 1 sat increase because any unbacked increase triggers it, so I can update the test to use a 1 sat bump to make that clear.

@Hardeezah
Hardeezah force-pushed the fix-outputs-exceed-inputs branch from a3bd660 to 7ce2ca1 Compare October 20, 2026 20:52

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was envisioning just having a simple check at the start of calculate_psbt_with_fee_range which ensures that the proposal fee >= original fee (note that this is not fee rate). I think this would be a lot simpler and should effectively mimic what WantsInputs::contribute_inputs ensures when adding inputs to the proposal. What do you think?

Also lets try to address failing changelog CI job.

@Hardeezah

Hardeezah commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor Author

@xstoicunicornx I used receiver_min_input_amount because it was already the established helper in WantsInputs::contribute_inputs, so it kept the delta logic consistent. However, checking proposal fee >= original fee is very clean and directly mirrors Sender::check_fees, so I am happy to switch to that. I will also make sure the diff against master satisfies the changelog CI job.

@Christopherdominic Christopherdominic left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we handle OutputsExceedInputs as a fatal error in apply_fee_range? It currently becomes transient and returns the receiver in WantsFeeRange, but inputs and outputs are already committed, and changing fee parameters cannot resolve this check. The v2 regression test should assert the fatal outcome rather than only is_err().

@xstoicunicornx

Copy link
Copy Markdown
Collaborator

Could we handle OutputsExceedInputs as a fatal error in apply_fee_range?

Good call, agree this would be good idea.

@Hardeezah
Hardeezah force-pushed the fix-outputs-exceed-inputs branch from 7ce2ca1 to 2929d8b Compare October 23, 2026 16:57
@Hardeezah

Copy link
Copy Markdown
Contributor Author

Could we handle OutputsExceedInputs as a fatal error in apply_fee_range? It currently becomes transient and returns the receiver in WantsFeeRange, but inputs and outputs are already committed, and changing fee parameters cannot resolve this check. The v2 regression test should assert the fatal outcome rather than only is_err().

Updated apply_fee_range to handle OutputsExceedInputs as fatal (SessionEvent::Closed(SessionOutcome::Aborted)), and updated the v2 regression test to assert that fatal outcome and the specific error variant.

@Hardeezah

Copy link
Copy Markdown
Contributor Author

I was envisioning just having a simple check at the start of calculate_psbt_with_fee_range which ensures that the proposal fee >= original fee (note that this is not fee rate).

Updated in the latest push. calculate_psbt_with_fee_range now verifies proposal_fee >= original_fee upfront.

@Christopherdominic Christopherdominic left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 2929d8b. My concern is addressed: OutputsExceedInputs now causes a fatal transition, and the regression test checks both the fatal outcome and specific error. No further blocking concerns from me. I haven’t run the updated tests locally.

@codaMW codaMW left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tACK 2929d8b

Reviewed the fee-conservation fix end to end, including a mutation to confirm the new guard is load-bearing.

The check in WantsFeeRange::calculate_psbt_with_fee_range now enforces the BIP 78 invariant directly instead of via an output-sum proxy: the proposal's absolute fee must not fall below the original transaction's. Using Psbt::fee() is the right tool here. It computes inputs minus outputs, so the Err(NegativeFee) arm catches the literal outputs-exceed-inputs case and the proposal_fee < original_fee guard catches a merely reduced fee, both mapping to OutputsExceedInputs (NotEnoughMoney to the sender), while a genuine arithmetic failure routes to FeeCalculationOverflow.

Placement is correct. The check runs before the fee-contribution step, and that step only ever decreases outputs (which raises the fee), so a pre-adjustment pass is conservative: if the invariant holds here it still holds after. I also confirmed next to the diff that this is the only path where a raised output reaches the fee stage without the WantsInputs floor, so the gap being closed is the no-contribute_inputs path (commit_outputs then commit_inputs with no receiver inputs).

The v2 fatal transition is the right severity. A receiver that constructs outputs exceeding inputs has a build error, not a transient condition, so Closed(Aborted) beats a transient retry. The v2 test pins is_fatal(), !is_transient(), and the exact OutputsExceedInputs variant.

Tested on 2929d8b, repo-pinned nightly, --all-features:

  • receiver_rejects_proposal_with_outputs_exceeding_inputs (common and v2): pass
  • receiver_accepts_output_increase_covered_by_receiver_input: pass

Mutation: flipping proposal_fee < original_fee to proposal_fee > original_fee makes both reject tests fail. The v2 failure shows the receiver reaching ProvisionalProposal with payjoin output 95983069 sat versus the original 95983068 sat (proposal fee 331 versus original 332), i.e. the one-sat-under-fee proposal was accepted instead of rejected. Restoring the guard makes all three pass again.

One non-blocking note: the Err(NegativeFee) => OutputsExceedInputs arm has no direct coverage. Both reject tests raise the output by a single sat, so proposal_fee stays positive and only the proposal_fee < original_fee branch fires. A test that raises an output past total input value would exercise the NegativeFee path and lock in that arm too.

@caarloshenriq caarloshenriq left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 2929d8b

Thanks for addressing the feedback. The direct fee comparison is cleaner than the min-input helper, and making this fatal in v2 resolves the unrecoverable transient state. Tests pass locally, and both rejection tests fail without the check.

Non-blocking, could be a follow-up: the variant name no longer matches the condition being checked (inline).

Comment thread payjoin/src/core/receive/error.rs Outdated
FeeCalculationOverflow,
/// The proposal's total output value exceeds its input value. Receiver
/// inputs must cover any increase in the original output value.
OutputsExceedInputs,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: now that the check compares absolute fees directly, OutputsExceedInputs no longer describes it. The 1-sat test in common hits this error while outputs are still below inputs. Something like ProposalFeeBelowOriginal would match the condition. Fine as a follow-up.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree the error now needs tweaking, my suggestion would be AbsoluteFeeDecreased.

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your patience @Hardeezah ! I am finally back "in office" now so should be able to provide much more timely review. Despite all my comments I do think this is looking pretty good.

This will also need a rebase due to the merge conflicts.

Comment thread payjoin/src/core/receive/error.rs Outdated
FeeCalculationOverflow,
/// The proposal's total output value exceeds its input value. Receiver
/// inputs must cover any increase in the original output value.
OutputsExceedInputs,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree the error now needs tweaking, my suggestion would be AbsoluteFeeDecreased.

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated
Err(e) =>
MaybeFatalTransition::transient(ProtocolError::OriginalPayload(e.into()), self),
Err(e) => match e {
InternalPayloadError::OutputsExceedInputs => MaybeFatalTransition::fatal(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fatal transition should send to PendingFallback state not directly to closed. See here (I know it says MaybeFatalTransition::replyable_error but it actually takes whatever the next state should be):

if e.is_fatal() {
MaybeFatalTransition::replyable_error(
SessionEvent::ProtocolFailed,
Receiver {
state: PendingFallback { fallback_tx: self.state.fallback_tx() },
session_context: self.session_context.clone(),
},
ProtocolError::V2(InternalSessionError::DirectoryResponse(e).into()),
)
:

Comment thread payjoin/src/core/receive/error.rs Outdated

FeeTooHigh(_, _) => JsonReply::new(NotEnoughMoney, e),

OutputsExceedInputs => JsonReply::new(NotEnoughMoney, e),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably map this to Unavailable instead of NotEnoughMoney which implicates a sender side error. Overall this error is only meant for sender side issues and this is being shoehorned into representing a receiver side error but its the best we can do for now.

Might be worth fixing for v2.0 API.

Suggested change
OutputsExceedInputs => JsonReply::new(NotEnoughMoney, e),
OutputsExceedInputs => JsonReply::new(Unavailable, "Receiver error"),

Comment thread payjoin/src/core/receive/common/mod.rs Outdated
Comment on lines +489 to +497
let proposal_fee = match self.proposal.payjoin_psbt.fee() {
Ok(fee) => fee,
Err(bitcoin::psbt::Error::NegativeFee) =>
return Err(InternalPayloadError::OutputsExceedInputs),
Err(_) => return Err(InternalPayloadError::FeeCalculationOverflow),
};
if proposal_fee < original_fee {
return Err(InternalPayloadError::OutputsExceedInputs);
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After chatting with Sol it convinced me that we might want to move this down to the end of the function so that it accounts for fees from contributed inputs/outputs as well. So right before we return Ok(payjoin_psbt). Do you see any pitfalls with this? It seems like the more strictly accurate way to validate and will guarantee the proposal has strictly higher fee than original.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see any pitfalls. The sender fee contribution is already capped at the sender's output value and the receiver change deduction uses checked_sub, so nothing in between can underflow. Moved the check right before Ok(payjoin_psbt) in 6ed8a9d.

Comment thread payjoin/src/core/receive/error.rs Outdated
FeeCalculationOverflow => write!(f, "Fee arithmetic overflow."),
OutputsExceedInputs => write!(
f,
"The proposal's output value exceeds its inputs; receiver inputs must cover any increase in output value."

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment string probably needs some tweaking to, and say something about "absolute fee cannot decrease".

@Hardeezah
Hardeezah force-pushed the fix-outputs-exceed-inputs branch from 2929d8b to 6ed8a9d Compare November 4, 2026 14:03
@Hardeezah

Copy link
Copy Markdown
Contributor Author

Thanks for the review @xstoicunicornx, Rebased and addressed all feedback in 6ed8a9d:

  • Renamed OutputsExceedInputs to AbsoluteFeeDecreased, updated its Display string, and mapped it to JsonReply::new(Unavailable, "Receiver error").
  • Moved the proposal_fee < original_fee check to the end of calculate_psbt_with_fee_range right before Ok(payjoin_psbt).
  • Updated v2 apply_fee_range to transition to PendingFallback (SessionEvent::ProtocolFailed) on AbsoluteFeeDecreased and updated the v2 test to assert the fallback_tx.

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple more changes needed.

};
if proposal_fee < original_fee {
return Err(InternalPayloadError::AbsoluteFeeDecreased);
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude found issue with this strategy, if the witness-utxo and non-witness-utxo fields are missing from any inputs in the psbt this will error (and the error will be mislabeled as FeeCalculationOverflow). To avoid this we can instead check that receiver_inputs >= proposal_outputs - original_outputs. This should effectively be the same as checking proposal_fee >= original_fee and we should have all the utxo data for all receiver inputs.

Here is an untested code snippet from claude.

        let sum_outputs = |psbt: &Psbt| {
            psbt.unsigned_tx.output.iter().try_fold(Amount::ZERO, |acc, o| acc.checked_add(o.value))
        };
        let receiver_input_amount = self
            .proposal
            .receiver_inputs
            .iter()
            .try_fold(Amount::ZERO, |acc, input| acc.checked_add(input.previous_txout().value))
            .ok_or(InternalPayloadError::FeeCalculationOverflow)?;
        let original_output_amount = sum_outputs(&self.original.original_psbt)
            .ok_or(InternalPayloadError::FeeCalculationOverflow)?;
        let proposal_output_amount =
            sum_outputs(&payjoin_psbt).ok_or(InternalPayloadError::FeeCalculationOverflow)?;
        // The sender's inputs are identical in both transactions, so the absolute fee
        // does not decrease as long as receiver inputs cover any output increase.
        let output_increase =
            proposal_output_amount.checked_sub(original_output_amount).unwrap_or(Amount::ZERO);
        if receiver_input_amount < output_increase {
            return Err(InternalPayloadError::AbsoluteFeeDecreased);
        }

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in 06d30e4 to check receiver_input_amount < output_increase using the existing checked_sum helper in common/mod.rs.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for being so on top of it! Apparently claude was wrong and this path would actually get vetted for missing utxo data and so .fee() would be fine to use here. This current check would also introduce a new potential panic path with input.previous_txout() so the original strategy is preferable. Sigh. Apologies for the misdirection.

If you could revert this in your PR that would be much appreciated otherwise I'm happy to do as a follow up.

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated
Comment on lines +1469 to +1475
) -> MaybeFatalTransition<
SessionEvent,
Receiver<ProvisionalProposal>,
ProtocolError,
Receiver<PendingFallback>,
Self,
> {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gahh sorry I overlooked that this would technically result in public API change! Can you please change this error back to transient error?

We can slate this for updating in v2.0 api.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reverted back to transient in 06d30e4.

@Hardeezah
Hardeezah force-pushed the fix-outputs-exceed-inputs branch from 6ed8a9d to 06d30e4 Compare November 4, 2026 20:12
xstoicunicornx
xstoicunicornx previously approved these changes Nov 4, 2026

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tACK 06d30e4

This is a straightforward change to prevent proposals where absolute fee decreased from proceeding.

This is one change listed below that I can take as a follow up, basically feedback that I took from the bot wasn't quite accurate.

One general follow up for v2.0 api will be to change the absolute fee decrease error to a fatal error. This cannot be done now because it is breaking change to public api.

};
if proposal_fee < original_fee {
return Err(InternalPayloadError::AbsoluteFeeDecreased);
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for being so on top of it! Apparently claude was wrong and this path would actually get vetted for missing utxo data and so .fee() would be fine to use here. This current check would also introduce a new potential panic path with input.previous_txout() so the original strategy is preferable. Sigh. Apologies for the misdirection.

If you could revert this in your PR that would be much appreciated otherwise I'm happy to do as a follow up.

Add AbsoluteFeeDecreased error and enforce that the post-adjustment
proposal fee is at least the original fee in fee range calculation.
Add regression tests and update changelog.
@Hardeezah

Copy link
Copy Markdown
Contributor Author

@xstoicunicornx Reverted back to .fee() in b01e905.

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re-ACK b01e905

Thank you for your patience @Hardeezah !

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal outputs can exceed inputs

6 participants