Skip to content

Classify Payjoin settlements on the Monitor typestate - #1971

Merged
spacebear21 merged 5 commits into
payjoin:masterfrom
xstoicunicornx:monitor-revamp
Nov 5, 2026
Merged

spacebear21 merged 5 commits into
payjoin:masterfrom
xstoicunicornx:monitor-revamp

Conversation

@xstoicunicornx

@xstoicunicornx xstoicunicornx commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Supersedes #1692 .

After posting a proposal, the receiver has to find out whether the Payjoin, the fallback, or some other transaction spent the sender's inputs. Today check_for_transaction handles this by probing two predicted txids and closing the session on the first match. It writes a verdict a reorg can reverse, it never sees an unrelated spend, and it closes non-SegWit sessions without checking at all.

This PR gives the wallet what it needs to answer the question, and lets the wallet decide when the answer is final.

Much of the design iteration and rationale for this implementation lives in #1692.

Changes

Core

  • Every receive::v2::Receiver state that holds a fallback transaction and is advancing the Payjoin protocol, from MaybeInputsOwned through Monitor, gains:
    • classify_tx(tx), which returns a Resolution for a transaction spending any of the sender's original inputs, or None if it spends none of them. Resolution::resolved_by() returns a ResolvedBy of Payjoin, Fallback or Unrecognized. The match ignores script_sig, so a non-SegWit signature or third-party malleation doesn't hide the proposal or the fallback. Any other change, such as a fee bump, reordered outputs or a sender double-spend, is Unrecognized. States before PayjoinProposal never report Payjoin.
    • close(resolution), which ends the session once the wallet decides the transaction has enough confirmations. It classifies the resolution's transaction again against the closing state, so a resolution from a stale copy of the session can't record a stale outcome. It records PayjoinProposalSent from Monitor, and from PayjoinProposal when the Payjoin resolved it, and Aborted otherwise. No settlement verdict is ever persisted.
  • ReceiveSession::classify_tx and ReceiveSession::close do the same for a session in any state, so a wallet replaying its open sessions doesn't have to match on every state. States that don't support classification return None, and closing them fails.
  • close rejects a Resolution classified against a different original transaction with a transient error that returns the session and persists nothing. Only classify_tx makes a Resolution.
  • check_for_transaction is deprecated in favor of classify_tx and close, and now goes through the classifier. proposal_txid_is_stable is deprecated too, since it checks only the sender's inputs. Both use a placeholder since until the release version is set.
  • SessionOutcome and SessionStatus docs now describe what the protocol did, not how the payment settled.

FFI

  • Exposes classify_tx and close_session on each of those states, plus classify_receiver_tx and close_receiver_session for a ReceiveSession in any state. Transactions are passed consensus-encoded, and bytes that don't decode return TransactionParseError.
  • Adds the Resolution object, the ResolvedBy enum and CloseTransition.
  • Removes Monitor.check_for_transaction, with its TransactionFinder callback and MonitorTransition, and removes proposal_txid_is_stable.

CLI

  • resume looks in its wallet for transactions paying the receiver's address, classifies them against every open receiver session in any state, and closes a session once its resolving transaction has one confirmation. Before, it closed on the first mempool sighting. An unresolved session stays open across resumes, and sessions with non-SegWit senders are now tracked too.
  • When cancel fails to broadcast the fallback, it says the session is still open and points to cancel --no-broadcast to close it.

Assigning to @spacebear21 for review.


Disclosure: This description and the code changes were written with Claude Code.

Pull Request Checklist

Please confirm the following before requesting review:

@coveralls

coveralls commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Report for CI Build 42100353006

Coverage increased (+0.3%) to 87.778%

Details

  • Coverage increased (+0.3%) from the base build.
  • Patch coverage: 50 uncovered changes across 3 files (575 of 625 lines covered, 92.0%).
  • 3 coverage regressions across 1 file.

Uncovered Changes

File Changed Covered %
payjoin/src/core/receive/v2/mod.rs 462 435 94.16%
payjoin-cli/src/app/v2/mod.rs 73 52 71.23%
payjoin-cli/src/app/wallet.rs 24 22 91.67%
Total (4 files) 625 575 92.0%

Coverage Regressions

3 previously-covered lines in 1 file lost coverage.

File Lines Losing Coverage Coverage
payjoin-cli/src/app/v2/mod.rs 3 58.18%

Coverage Stats

Coverage Status
Relevant Lines: 18466
Covered Lines: 16209
Line Coverage: 87.78%
Coverage Strength: 316.45 hits per line

💛 - Coveralls

@DanGould DanGould left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

My main issues are allow(deprecated) in tests without exercising the new interface where the opportunity exists, deprecating proposal_txid_is_stable for the new behavior, and getting the fallback_txid through #1949 instead of an extra method.

proposal_txid_is_stable can be deprecated here in favor of classify, too. Ignores receiver inputs anyway, which is a problem for actually classifying as stable.

Monitor -> cancel() -> close() writes Aborted after the proposal was posted. Both docs need to drop the "before posting" claim.

Comment thread payjoin/src/core/receive/v2/session.rs Resolved
Comment thread payjoin-ffi/src/receive/mod.rs Resolved
Comment thread payjoin-ffi/src/receive/mod.rs Resolved
Comment thread payjoin/tests/integration.rs Resolved
Comment thread payjoin/tests/integration.rs Resolved
Comment thread payjoin-ffi/src/receive/mod.rs Resolved
Comment thread payjoin/src/core/receive/v2/mod.rs Resolved
Comment thread payjoin/src/core/receive/v2/mod.rs Resolved
@DanGould DanGould added this to the payjoin-1.3 milestone Oct 13, 2026
@xstoicunicornx
xstoicunicornx force-pushed the monitor-revamp branch 3 times, most recently from 5ca8c70 to 3cbff7b Compare October 14, 2026 17:24
@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

I think I got all follow ups, ready for re-review.

@DanGould DanGould left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

incomplete review, but thoughts that came up while reading rust-bitcoin's policy re: deprecation & versioning

Comment thread payjoin-ffi/src/receive/mod.rs Outdated
/// match. When [`expected_payjoin_txid`](Monitor::expected_payjoin_txid)
/// is [`ExpectedTxid::Unstable`] it closes the session without checking.
///
/// Deprecated since payjoin 1.3.0: use [`classify`](Monitor::classify) and

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

this is gonna go stale immediatel and should be left out of comments

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I didn't remove the full deprecation comment (since I think that this is the only indicator of deprecation for check_for_transaction in ffi) but just removed the payjoin version.

Comment thread payjoin-ffi/src/receive/mod.rs Outdated
/// transaction ID: any ID derived from the proposal before the sender
/// signs will never appear on the network, and monitoring concludes the
/// session without checking.
/// Deprecated since payjoin 1.3.0: use `expected_payjoin_txid` on

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

remove

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Again, just removed the version.

Comment thread payjoin/src/core/receive/v2/mod.rs Resolved
DanGould
DanGould previously approved these changes Oct 16, 2026

@DanGould DanGould left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thank you for addressing my prior concerns. Your thinking around proposal_txid_is_stable sounds right to me as well.

One thing before merge. Master now wants a payjoin-ffi/CHANGELOG.md line under Unreleased whenever payjoin-ffi/src changes (5db2b57), so this would fail CI rebased on master as-is today even though the rebase is otherwise clean.

The Monitor docs tell the wallet to watch contested_prevouts (mod.rs#L1830-L1834, #L1855-L1863). Most wallets don't need to. The fallback pays the receiver's address, and the proposal spends the receiver's inputs or pays its output, so ordinary wallet sync by script finds both. Your find_settlement doc says the same (v2/mod.rs#L1244-L1248), which contradicts "this is the only way to find the proposal" in the contested_prevouts doc. contested_prevouts is needed when the proposal pays only substituted outputs and spends no receiver input, and to catch a sender spend that is neither transaction. Could the docs lead with passing what the wallet finds to classify, and describe contested_prevouts for those cases? The bindings carry the same text (ffi#L2001-L2006, #L2023-L2032).

Since this needs to be rebased to satisfy the ffi changelog thing, perhaps you could change the deprecation notice to use TBD as well when addressing these nits? This is money. Almost there!

@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

I think CI is failing for this issue: #1985

Otherwise I think ready for re-review. Sorry the rebase commit got lost here, you can find it on my branch https://github.com/xstoicunicornx/rust-payjoin/tree/monitor-revamp-rebase

@spacebear21 spacebear21 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.

cACK, this is finally looking like the right shape for the Monitor API. I have some code feedback, and I'm not totally sure what to do about the SessionOutcome change. The current approach of always closing with PayjoinProposalSent feels a bit hacky, but I don't want to force a breaking change now.

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated
Comment on lines +1847 to +1859
pub fn expected_payjoin_txid(&self) -> ExpectedTxid {
if !self.sender_script_sigs_are_empty() {
return ExpectedTxid::Unstable;
}
// The posted proposal carries the receiver's finalized inputs and no sender signatures,
// and the sender adds only witnesses, so extracting it yields the broadcast script_sigs.
let payjoin_tx =
self.state.psbt_context.payjoin_psbt.clone().extract_tx_unchecked_fee_rate();
ExpectedTxid::Stable(payjoin_tx.compute_txid())
}

/// The sender's original transaction, which it may broadcast instead of the proposal.
pub fn fallback_tx(&self) -> bitcoin::Transaction { self.state.fallback_tx() }

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'm not sure we need to make either of these helpers pub, since classify takes care of classification and it's already mentioned that the wallet would automatically detect either a fallback or payjoin tx anyway?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Yes a wallet can detect a receive, but that doesn't mean the wallet can detect which payjoin session the tx relates to, or that it relates to a payjoin receive at all. Is it acceptable to force wallets to run all received txs through all active Monitor payjoin session's classify method?

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated
let unsigned_txid = unsigned_tx.compute_txid();
let psbt_context = &self.state.psbt_context;

if unsigned_txid == psbt_context.original_psbt.unsigned_tx.compute_txid() {

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.

could we use self.state.fallback_tx.compute_txid()?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I don't think so because we need to strip the sigs out before comparing the txids to account for non-segwit sender inputs where sender could re-sign same fallback tx (and we probably don't want to classify these as Unrecognized).

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated

/// Close the session once the wallet no longer needs to track settlement.
pub fn close(self) -> TerminalTransition<SessionEvent, ()> {
TerminalTransition::new(SessionEvent::Closed(SessionOutcome::PayjoinProposalSent), ())

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 guess this will result in some unused SessionOutcome variants? I also wonder if we might want to rename this one, but am aware that's a breaking change.

close() could take a SettlementOutcome to turn into a SessionOutcome? IDK if that's desirable.

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.

Actually I think SessionOutcome::Unrecognized(Txid) would be the right shape for closing the session, so that there is a permanent record of the txid that settled it regardless of what it was. But Unrecognized is even more misleading than PayjoinProposalSent and renaming it is a breaking change even if it's never written as of today.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I think one of the guiding principles for this API change is that we explicitly avoid storing any permanent settlement outcome information. Settlement should strictly be handled by the wallet and we should avoid trying to insert ourselves in that process.

See #1692 (comment) for background on this direction regarding approach.

Comment thread payjoin/src/core/receive/v2/mod.rs Resolved
@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

Rebasing to resolve merge conflict

@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

Ready for re-review.

@xstoicunicornx
xstoicunicornx force-pushed the monitor-revamp branch 3 times, most recently from 2e84523 to 8c1da26 Compare October 22, 2026 08:36
@spacebear21 spacebear21 mentioned this pull request Oct 22, 2026
3 tasks done
xstoicunicornx pushed a commit to xstoicunicornx/rust-payjoin that referenced this pull request Oct 22, 2026
The staged Dart package takes payjoin-ffi from the pinned revision but
payjoin and payjoin-mailroom from crates.io. Staging only switched a
crate to the revision when its required version was missing from
crates.io. A pull request that changes core without a version bump,
which is how core changes normally land, kept the crates.io core, so
the reproducible-linux job compiled the pull request's payjoin-ffi
against an older payjoin and failed. payjoin#1971 hits this with new
Monitor receiver methods.

Add a --core-from-revision option that always patches the sibling
release crates to the pinned revision and writes the UNPUBLISHED_CORE
marker publish.sh refuses, and pass it on pull
request runs only. Release runs keep staging against crates.io, so
an unpublished core still fails there before anything is published.
This also drops the crates.io API probing.
@xstoicunicornx
xstoicunicornx force-pushed the monitor-revamp branch 2 times, most recently from 6f369bd to 902166e Compare October 22, 2026 12:32

@spacebear21 spacebear21 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 had my bot review this closely and posted the most relevant findings here

Comment on lines +340 to +348
fn original_psbt(&self) -> &bitcoin::Psbt;

impl FallbackTx for super::MaybeInputsOwned {
fn fallback_tx(&self) -> bitcoin::Transaction {
self.original.psbt.clone().extract_tx_unchecked_fee_rate()
self.original_psbt().clone().extract_tx_unchecked_fee_rate()
}

/// The finalized Payjoin proposal, once the sender may have received it.
fn payjoin_psbt(&self) -> Option<&bitcoin::Psbt> { None }
}

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 extends the sealed trait leak from #1994 with original_psbt and payjoin_psbt now also being unintentionally exposed in the public API. These all build in a downstream crate:

  pub fn fallback<S: HasFallbackTx>(r: &Receiver<S>) -> Transaction { r.fallback_tx() }
  pub fn original<S: HasFallbackTx>(r: &Receiver<S>) -> Psbt { r.original_psbt().clone() }
  pub fn proposal<S: HasFallbackTx>(r: &Receiver<S>) -> Option<Psbt> { r.payjoin_psbt().cloned() }

I'm also not sure original is necessary, since it's only used for getting the fallback which is already exposed here.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Good catch. I pulled the seal commit from #1994 into the base of this branch unchanged, so FallbackTx is pub(crate) here too. It's the same patch, so it drops out when this rebases onto master after #1994 merges. I also added compile_fail doctests for original_psbt and payjoin_psbt next to the one for fallback_tx. They're separate tests because one test with all three calls would still pass if only one leaked.

On original_psbt not being necessary: classify_tx uses it to read the contested prevouts and the original's unsigned txid. Getting those from fallback_tx() would clone and extract the whole PSBT on every call, and the script_sigs would need stripping again. With the trait sealed it's no longer public, so it just stays as an internal accessor.

Drafted with AI assistance.

Comment thread payjoin/src/core/receive/v2/session.rs Outdated
Comment on lines +34 to +37
// A session that posted its proposal is exempt too, whether still in Monitor or cancelled from
// it into PendingFallback: it has no protocol work left, the transaction it awaits can confirm
// long after the mailbox is gone, and a wallet gives up on it by cancelling past expiration.
if !matches!(receiver, ReceiveSession::Closed(_)) && !history.posted_proposal() {

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.

A side effect of this a wallet that relied on the previous behavior to cancel the transaction and broadcast (like the LDK PR does now) would now never know that it needs to cancel and broadcast the transaction. I think the way to address this is to have check_for_transaction keep the old outcome by returning a fatal transition to PendingFallback if the expiration has passed, and only callers that migrate take on the new responsibility.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I didn't like this option very much because even though it didn't result in an API change it still resulted in a change in how it would need to be handled, which is arguably worse because there is no indicator at compile time that this is the case. So it feels a little dishonest.

I opted to just retain the current deficiency in master which means expired PayjoinProposal and Monitor typestates will error on replay and produce the fallback. I tried many other options to trying to make replaying event log only hit expiration error for the applicable Monitor flows but each had its own slightly messy warts. I think it will be cleaner to add this expiration exclusion with the next major version bump.

Follow up uncovered during this review, FFI's ReceiverReplayError exposes is_expired() but not expiry_fallback_tx(), so binding users can't get the fallback from an expired replay. I'll open a separate PR for it.

Comment thread payjoin-ffi/src/receive/mod.rs Outdated
};
}

macro_rules! impl_settlement_classification_for_receiver {

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 now realize that for FFI, callers would need to write a classify_tx match over all 9 Receiver variants... this is not ideal.

Perhaps classify_tx should live on SessionHistory after all?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I opted to move this to the general ReceiverSession and have classify_tx return a new Settlement which allows for direct closing of the session. This allows the caller to classify the settlement outcome without consuming the session and gating the closing of the session on the predicate that some settlement outcome was actually reached.

Without the coupled Settlement::close() method, the caller still would need to match on the replayed state to act on the result. Classification becomes uniform, but closing and cancelling don't. The previous match over every variant just moves from classifying to acting. For example if classify_tx was implemented on replay_event_log:

let (session, history) = replay_event_log(&persister)?;
let Some(outcome) = history.classify_tx(&tx) else { return Ok(()) };
if confirmations < MY_BAR { return Ok(()) }

match session {
    ReceiveSession::Monitor(r) => r.close().save(&persister)?,
    ReceiveSession::MaybeInputsOwned(r) => r.cancel().save(&persister)?.close().save(&persister)?,
    ReceiveSession::MaybeInputsSeen(r) => r.cancel().save(&persister)?.close().save(&persister)?,
    // ...OutputsUnknown, WantsOutputs, WantsInputs, WantsFeeRange, ProvisionalProposal, PayjoinProposal
    ReceiveSession::HasReplyableError(r) => match r.cancel().save(&persister)? {
        // MaybeTerminalTransition: PendingFallback if the original arrived, otherwise closed
        ...
    },
    ReceiveSession::PendingFallback(r) => r.close().save(&persister)?,
    // classify_tx returns None for these, so they can't get here
    ReceiveSession::Initialized(_) | ReceiveSession::UncheckedOriginalPayload(_) | ReceiveSession::Closed(_) => {}
}

Comment thread payjoin/src/core/receive/v2/mod.rs Outdated
let unsigned_txid = unsigned_tx.compute_txid();

if unsigned_txid == self.state.original_psbt().unsigned_tx.compute_txid() {
return Some(SettlementOutcome::Fallback);

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.

classify_tx returning Fallback before Monitor is new and useful. But nothing tells the wallet what to do next. The answer is cancel(), then close(), with no broadcast because the fallback is already out. The CLI doesn't do it either; its commit says that's left for later.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

With the new API the next step is much clearer - use Settlement::close() to close the session.

///
/// Returns a [`MonitorTransition`] that, once persisted, completes
/// the session if a transaction is found.
pub fn check_for_transaction(

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.

It seems acceptable to break payjoin-ffi only since it's <1.0.

@xstoicunicornx
xstoicunicornx force-pushed the monitor-revamp branch 2 times, most recently from 78dd6a8 to c48f054 Compare October 27, 2026 05:15
@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

I have not had a chance to fully review the changes but I wanted to push them out incase there was any immediate feedback since there are significant changes (though I do think the changes remove a lot of the inconsistencies and clarify the flow). Will be afk for large part of the day tomorrow but trying to keep this PR moving forward.

@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

Ok ready for re-review.

/// Returns the class of transaction that spent the sender's original inputs.
pub fn classification(&self) -> ResolutionClass { self.classification }
}

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.

The Resolution struct and classification() are new public API since the last round. AFAICT close(&self, tx: &Transaction) would enforce the same evidence requirement without the wrapper type, the session binding by original txid, or the mismatch error path. Is there a guarantee Resolution gives that I'm missing?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

The only thing it guarantees really is consumption of the receiver session on close() which the previous API didn't.

Other than that, no it doesn't guarantee much more than the previous api. I mostly just didn't like that the previous API was effectuating a state change from something that wasn't actually the receiver session. Felt like a weird anti-pattern. I strongly prefer the receiver session to be the only way to move the state machine and not have a weird proxy object that can indirectly effectuate change on the state machine.

Happy to consider changing it back if you prefer the previous version though.

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 think close(self, tx: &Transaction) would work just as well, it still consumes the session the same way and keeps the receiver as the only thing that moves the state machine, so I think it satisfies both of your points. To be clear, I'm not suggesting going back to the no-argument close().

One concrete reason to prefer taking the transaction: a Resolution carries a classification computed by whichever state produced it, while close decides the outcome from the state that closes. For PayjoinProposal that outcome depends on the stored classification, so a wallet that classified with a stale snapshot (say ProvisionalProposal, which reports the Payjoin as Unrecognized) and then closes the advanced session gets Aborted where a fresh classification would record PayjoinProposalSent. Both states share the original txid, so the session check accepts it. close(self, tx) reclassifies against the closing state, so that can't happen.

Given that, and that Resolution otherwise adds a public struct, an accessor, an FFI object, an original-txid session binding that two sessions with the same original can share, and an extra error path, I'd lean toward classify_tx(&self, tx) -> Option<ResolutionClass> plus close(self, tx: &Transaction) that returns the same transient error when tx spends none of the contested prevouts. And I'd maybe revert the name of the enum to SettlementOutcome, that seems clearer to me.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Ahh ok sorry I misunderstood. The reason I was leaning against putting the tx as an argument is that it makes close much more fallible. Using Resolution as the argument means that the tx always results in a resolution, whereas that is not the case if you take tx as the argument. This would mean handling the non-classifiable case using a transition with stasis or by wrapping the transition in a Result, both which felt a bit hacky and anti-pattern-ish. I also did not like that intuitively the caller would assume that the tx would be stored as part of the resolution, though this was more of a gut nit.

As for SettlementOutcome I agree its much clearer if it were actually storing the settlement outcome, however what we are storing is essentially just "payjoin was sent and session was closed" or "payjoin was not sent and session was closed". But happy to change this back if you still disagree.

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.

That's fair, having close take the Resolution means "close with an unrelated transaction" can't even be written, and I agree that's nicer than a runtime error on close.

I think the stale classification issue is actually fixable while keeping this design. It needs an integrator caching bug plus a crash between posting and processing the response, so it's an edge case, but having Resolution hold the actual Transaction and close reclassify it against the closing state would rule it out without changing the API shape.

Not to bikeshed the naming too much but I think I like Resolution, ResolvedBy and resolved_by() as you had it on a previous push. I lean towards keeping it #[non_exhaustive] because it's not going to be persisted anyway, and new variants would likely only refine the catch-all Unrecognized so I don't think forcing a breaking change would be necessary.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I couldn't quite reason about the flow that would resolve by re-checking classify for a stale classification, as re-classifying would still return the same stale result, but I added in the re-classification anyway as it can't hurt. Could you walk me through the flow that would cause a stale classification?

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.

The case is when the Resolution and the receiver you call close on are different objects. Re-classifying on the same object would give the same answer, but close now classifies against self, the state that is closing, not the state that minted the resolution. This is what test_close_reclassifies_against_closing_state guards against: the resolution comes from MaybeInputsOwned, which can't recognize the Payjoin and says Unrecognized, and the close happens on PayjoinProposal, which now records PayjoinProposalSent instead of Aborted.

In practice that needs a wallet that keeps an outdated copy of the session around, for example a settlement watcher task that cached the session before it reached PayjoinProposal, while a driver task advances it, posts the proposal, and crashes before persisting PostedPayjoinProposal. The sender then broadcasts the Payjoin, the watcher classifies it with its old copy, and the replayed PayjoinProposal session is closed with that resolution. It needs an integrator bug plus that crash window, so it's an edge case, and only PayjoinProposal cares since Monitor and the earlier states ignore the classification. With the tx carried in the resolution it's now ruled out entirely, which I think is worth the small cost.

@spacebear21

Copy link
Copy Markdown
Collaborator

approach ACK

My bot found a few messaging discrepancies I'll re-post here but none seem blocking:

  1. Restore test_classify_tx_reordered_outputs_is_unrecognized. It was removed in the last push, but it pins exact transaction matching, which the commit message still argues for.
  2. Update the PR description. It still lists contested_prevouts, classify, expected_payjoin_txid, fallback_txid, receiver_prevouts, SettlementOutcome and ExpectedTxid, and says posted sessions are exempt from expiry, which the current version reverted.
  3. Claims that don't match the code:
    • The d598a4ae message says "wallets already broadcast on that error", but payjoin-cli prints the fallback for a manual broadcast.
    • SessionStatus::Failed says only Aborted, but Unrecognized(_) maps to Failed too.
    • Resolution::original_txid is documented as identifying the session, but two sessions built from the same original share it.
    • Both changelogs say classify_tx covers every state that holds a fallback, but HasReplyableError can hold one and returns None.
    • Aborted now reads "ended without sending the Payjoin proposal", but a PayjoinProposal session resolved by its fallback records Aborted even though the post may have reached the sender.

@xstoicunicornx
xstoicunicornx force-pushed the monitor-revamp branch 2 times, most recently from fef5691 to 26c8315 Compare November 5, 2026 18:25
After posting the proposal the receiver still does not know how the
sender's inputs were spent. The proposal and the fallback double-spend
them, so the receiver holds the only record that can tell which
transaction represents which. Expose that as a pure classify_tx over a
transaction the wallet found.

Wallets should pass every transaction they receive to classify_tx on
each open session, rather than probing for predicted txids. A session
in any state with a fallback can see the fallback or a re-spend of the
sender's inputs, not only one in Monitor. A transaction unrelated to a
session is rejected by an outpoint comparison before any hashing, so
checking it against every session is cheap.

So classify_tx lives on every HasFallbackTx state. The sealed
FallbackTx trait now returns a borrowed original PSBT, with fallback_tx
derived from it as a default method, and a payjoin_psbt that defaults
to None. PayjoinProposal and Monitor return their finalized proposal.
PayjoinProposal counts because a post can reach the sender even when
persisting the transition out of that state fails. ProvisionalProposal
returns None: its unsigned transaction matches what finalization
produces, but the sender cannot have it yet. Before PayjoinProposal,
classify_tx never reports Payjoin.

The trait is pub(crate), so generic code bounded on HasFallbackTx
cannot call original_psbt or payjoin_psbt from outside the crate any
more than fallback_tx. Add a compile_fail doctest for each next to the
one guarding fallback_tx. Each needs its own, since one test with
several calls would pass while any one of them still failed to compile.

classify_tx answers which of this session's transactions spent the
contested prevouts. It returns a Resolution whose ResolvedBy is Payjoin
for the proposal, Fallback for the fallback, and Unrecognized for any
other transaction that spends a contested prevout. A transaction
spending none of them says nothing about the session, so it gets None
rather than Unrecognized. The Resolution exposes no txid, since the
caller passed in the transaction and already has it.

Identity compares the transaction's txid, with its script_sigs
cleared, against each PSBT's unsigned transaction. Signing fills only
script_sig and witness, and the txid already excludes the witness, so
for a stable session this is the plain txid check. It also recognizes
the proposal after a non-SegWit sender's signature changed its txid,
and the fallback after a third party malleated it. Matching on the
receiver's inputs or the proposal's output set would also accept a
different transaction that happens to share them. A reordered output
set is a different transaction no receiver signature covers.

The fallback is checked first. The two only coincide when the proposal
is the original unchanged, and then no cooperation happened. Because
every candidate spends the contested prevouts, one transaction is the
whole answer, and choosing which to ask about is the wallet's job.

Keep the contested prevouts private. A wallet that classifies every
transaction it receives does not need to watch them: sync by script
finds the fallback, which pays the receiver, and the proposal, which
spends the receiver's inputs or pays its outputs. The one proposal sync
misses pays only scripts the wallet does not own, as when it forwards
the payment to a third party. The wallet chose those scripts itself, so
it is the wallet's job to watch them. Document that on
substitute_receiver_script.

A wallet that classifies what it receives has no use for a predicted
txid, the fallback, or the receiver's prevouts, and
SessionHistory::fallback_tx already returns the fallback for a caller
that wants it. It does need a deadline: nothing else ends a session the
sender never settles, or settles with a re-spend the wallet never sees.
The session's expiration stays that deadline. Past it, replay returns
the expired error carrying the fallback, as for any open session, and a
wallet can broadcast it from there. payjoin-cli prints it for a manual
broadcast. Document it on Monitor and pin it with a test.

check_for_transaction still probes by txid, so compute the proposal's
txid privately from the posted proposal. Its txid then includes the
script_sigs of the receiver's finalized inputs. The proposal carries
no sender signatures, and a SegWit sender adds only witnesses, so this
is the txid the broadcast transaction has. Hashing the unsigned
proposal instead misses a legacy or P2SH-wrapped receiver input and
predicts a txid that never appears on chain.

proposal_txid_is_stable checks only the sender's inputs, so it has the
same flaw. Before the receiver signs there is no script_sig to read,
and fixing it there would mean inferring from script types. Deprecate
it in favor of classify_tx, which recognizes the proposal whatever its
txid, and narrow its doc to what it checks.

Add close to the same states. It takes the Resolution and ends the
session once the wallet's confirmation bar is met. Resolution has
private fields and no constructor, so only classify_tx makes one, and a
session can close this way only after a transaction spent its
contested prevouts. Then no fallback needs broadcasting: the fallback
is that transaction or conflicts with it. Closing without that evidence
would let a wallet end a session holding a fallback it never saw, so
every other way out still goes through cancel, which hands the fallback
over. Resolution is not Serialize, so it cannot be forged by
deserializing.

close lives on the receiver, as every other transition does, so only
receivers write session events and a Resolution is only evidence handed
back to one. It records the original transaction's txid, and close
rejects a Resolution classified from another session the way the input
checklists reject items marked for a different receiver: with a
transient error that returns the receiver and persists nothing. The
Resolution also carries the transaction, and close classifies it again
against the state it closes from, not the one that classified. A stale
copy of the session from before the proposal calls the Payjoin
Unrecognized, and closing PayjoinProposal with that verdict would record
Aborted although the proposal reached the sender.

ResolvedBy is never persisted: only confirmation resolves a double-spend
race and a reorg can always reverse it, while the log is append-only and
Closed is terminal, so a verdict written there would be permanent and
could later be wrong. Closing records what the protocol did. A Monitor
session closes as PayjoinProposalSent whichever transaction resolved it.
A PayjoinProposal session resolved by its Payjoin closes the same way:
the sender signing the proposal proves the post reached it, and a reorg
cannot undo that. Any other resolution before the handoff closes as
Aborted. Keeping the session open until the wallet closes it also makes
the log the record of which sessions still owe an answer, which a
wallet-side cache cannot replace because a restored backup brings the
logs back without it. A wallet that gives up on a session nothing
resolved cancels it and broadcasts the fallback.

Add ReceiveSession::classify_tx and ReceiveSession::close, which
dispatch to the state's receiver. classify_tx returns None for the
states that do not support classification, and close rejects a
Resolution in those states, since none of them can have produced it. A
wallet that replays its open sessions then classifies and closes without
matching on every state.

Re-express check_for_transaction over the classifier so a found
transaction is confirmed as the proposal rather than trusted from the
txid probe alone, and route its non-SegWit exit through the private
txid helper. Deprecate it in favor of classify_tx and close. It closes
on first sight rather than at a confirmation bar, never sees a spend
that is neither transaction, and closes an unstable session without
checking at all. The binding and the CLI still call the deprecated
methods, so allow the deprecation at those call sites.

Both deprecations use since = "0.0.0-unreleased", a placeholder the
release replaces with the real version rather than this commit
guessing it.

The existing Monitor tests keep covering check_for_transaction, its
early exit for non-SegWit senders included, under allow(deprecated). New
regression tests cover its probe of a txid with a receiver script_sig,
and proposal_txid_is_stable, until both are removed. The new tests
classify each kind of spend and close with the Resolution from
MaybeInputsOwned, PayjoinProposal and Monitor, checking the outcome each
writes, check that close classifies again against the state it closes
from, and check that close rejects a Resolution from another session,
including one whose transaction spends this session's inputs, or in a
state without a fallback.
Every terminal outcome reads as a payment verdict today. Aborted says
the payjoin "was not successful" when a fallback may well have been
broadcast and confirmed, and PayjoinProposalSent still describes
non-SegWit senders as unmonitorable, which classify_tx now makes
untrue.

Say what each outcome means for the protocol. Aborted is a session that
ended without acknowledgement that the directory received its proposal,
or was cancelled, and the fallback may still have paid. That can happen
after the proposal was posted, since Monitor can still cancel into
PendingFallback and close from there. PayjoinProposalSent is a session
whose proposal was sent. Note on Success and FallbackBroadcasted that
only the deprecated check_for_transaction produces them, so sessions
closed with classify_tx and close never carry them.

SessionStatus matters more, since wallet UIs read status(). Document
every variant in one line. Completed is a session that closed after its
proposal was sent, without saying which transaction resolved it, and
FallbackBroadcasted, like its SessionOutcome, comes only from the
deprecated check_for_transaction.

Record on Unrecognized that nothing produces it. The variant was
reserved for a classifier that would have persisted its verdict. It
stays because the enum is exhaustive, so removing it is a semver break.
The receiver gained a classifier on every state with a fallback, and a
close that takes its Resolution, but bindings could still only call
check_for_transaction, which probes two predicted txids and closes on
the first match. Wallets built on the bindings had no way to apply
their own confirmation bar or to recognize a Payjoin whose txid a
non-SegWit sender changed.

Expose classify_tx and close_session on every state from
MaybeInputsOwned through Monitor, the same states that cancel into
PendingFallback, through one macro like the cancel methods. Wallets are
meant to classify every received transaction against each open session,
so the binding needs both wherever core has them. Expose Resolution as
an object with resolved_by, ResolvedBy as a uniffi enum, and a
CloseTransition to persist the close. A uniffi object has no constructor
unless one is exported, so foreign code cannot make a Resolution either,
which keeps the guard that core's private fields give Rust callers.

Name the method close_session rather than close. Kotlin objects are
AutoCloseable, whose close() drops the Rust handle, so a close on nine
state objects would need nine renames in uniffi.toml and would leave
close() and closeSession() side by side on each.

Expose ReceiveSession::classify_tx and ReceiveSession::close as the
top-level functions classify_receiver_tx and close_receiver_session
rather than as methods on the ReceiveSession enum. uniffi-dart 0.2.1
renders methods only on objects, so an enum method would be missing from
the Dart bindings, and uniffi-bindgen-react-native would render it as a
static function taking the enum anyway. Both convert the binding's
session back to core's and dispatch there. classify_receiver_tx decodes
the transaction in every state, so bad bytes fail the same way whatever
the session's state. A Resolution from another session, or a state that
cannot be closed via resolution, fails CloseTransition.save with the
transient ReceiverPersistedError that saving already returns.

Carry core's note on watching forwarded outputs over to
substitute_receiver_script.

classify_tx takes consensus-encoded bytes like the rest of the binding,
so it returns a TransactionParseError when they do not decode. The core
ResolvedBy is non_exhaustive; a value this binding does not know maps to
Unrecognized rather than panicking.

Remove check_for_transaction, with the TransactionFinder callback and
MonitorTransition it needed, and proposal_txid_is_stable from every
receiver state, rather than deprecating them as core does. payjoin-ffi
is not yet 1.0, so it can drop them now, and uniffi cannot carry
note binding users may never see.

Record the additions and removals under Unreleased in the FFI changelog,
as the changelog check requires for a change to payjoin-ffi/src.

Exercise the new API in every binding's tests. The v2 integration test
saves the receiver's Monitor, classifies the broadcast Payjoin with
Monitor.classify_tx and with classify_receiver_tx on the replayed
session, and closes the replayed session with close_receiver_session. A
unit test checks that classify_receiver_tx returns nothing for a
session without a fallback and rejects bytes that are not a
transaction.
After posting its proposal the receiver polled the mempool for a
predicted txid for a few seconds and closed on first sight. It closed
sessions with non-SegWit senders without checking at all.

Have resume check the wallet once for each open receiver session, in
any state, before driving it. Every wallet transaction paying the
session's address is classified against the session. The CLI never
substitutes the receiver output, so both the fallback and the Payjoin
pay that address. Once the most-confirmed transaction spending the
sender's inputs has one confirmation, close the session with its
Resolution. With fewer, leave the session open without advancing its
protocol. Otherwise drive the session as before; it stops at Monitor
until a later resume finds a transaction that resolves it.

bitcoind-async-client has no wrapper for listreceivedbyaddress, so
enable its raw_rpc feature and call it directly.

Stop printing the proposal txid for the user to watch. It was the
unsigned proposal's, which is wrong for non-SegWit senders.
cancel saves the Cancelled event before it broadcasts the fallback, so
a failed broadcast leaves the session in PendingFallback. That happens
when the Payjoin or the fallback is already on chain. Every later
resume then repeats the hint to run cancel, and cancel fails the same
way each time. cancel --no-broadcast closes the session from that
state, but nothing told the user about it.

Say the session is still open when the broadcast fails and point to
cancel --no-broadcast. Mention the flag in the PendingFallback hint too,
which a session reaches after handle_error prints the fallback for a
manual broadcast. Sender and receiver share the same cancel flow, so
change both.
@xstoicunicornx

Copy link
Copy Markdown
Collaborator Author

Ok ready for re-review.

@spacebear21 spacebear21 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.

utACK 71f0a1b - I mostly focused my review on the API design which I think is the right shape now. I didn't look at payjoin-cli very closely but it seems sane at a glance and the new e2e test is a good addition.

Some follow-ups to consider but non-blocking for this PR:

  • Expose contested_prevouts: this would be useful for wallets to build an index of their sessions. IIRC we had decided to ship this step improvement and see what API demands come up, before committing to a new public interface.
  • A classifier on SessionHistory that also works for closed and canceled sessions. Same as above, I'm not convinced it's a strict requirement for the next release.
  • close docstring should say closing from Monitor records PayjoinProposalSent whichever transaction resolved it, and that the classification isn't persisted.
  • cancel --no-broadcast still prints "Broadcast the original transaction manually", which contradicts the new hint pointing there when the fallback is already on chain. Maybe "Session closed without broadcasting the fallback. If it isn't already on chain and its inputs are unspent, broadcast it yourself:".
  • FFI migration notes:
    • close_session records PayjoinProposalSent for every resolution, where check_for_transaction recorded Success(txid) or FallbackBroadcasted, so apps should store resolved_by and the txid themselves.
    • classify_tx resolves unconfirmed transactions too, so close only after the wallet's confirmation depth.
    • Non-SegWit senders no longer need special handling.
    • Resolution can't be persisted, so reclassify after a restart.
    • Bad bytes raise TransactionParseError.

@spacebear21
spacebear21 merged commit 256fa2d into payjoin:master Nov 5, 2026
41 checks passed
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.

4 participants