Rename Receiver<Monitor>::check_for_broadcast to check_for_transaction, etc.

[DanGould]

close #1656

& rename the predicate transaction_exists to find_transaction, because it's not returning a bool it's returning a TxID.

This change is done because broadcast is one possible interpretation of the success condition. Really, it's up to the wallet to determine at what point a transaction = a success for Payjoin, so the name reflects that.

But thinking about this revealed deeper problems (and some solutions to past problems) about the state machine design here which is that we're even making the check based on TxId in the first place because it limits detection to segwit transactions and we're just skipping detection otherwise (see #1214 , #1218). I don't see a good reason to force that disability to fit a particular monitor shape. There's another problem with this which is that our design treats detection from this method as the final verdict when even after broadcast detection of a payjoin it's still possible the fallback or another transaction double-spends the same outpoint used as receiver input.

The non-segwit detection issue can be solved by monitoring sender and receiver input outpoints as well as the fallback & payjoin Txids (if predictable via segwit). The monitor would then return SettlementStatus. See details below. This would let the wallet deal with reorgs and consistently return the correct SettlementStatus computed according to the wallet state, and wouldn't go stale by serializing event that's the result of a wallet snapshot as the permanent status of a particular payjoin, which is where this stands even after my proposal here.

A proposal for payjoin-2.0 monitor design

impl Receiver<Monitor> {
    fn payjoin_txid(&self) -> Txid;             // the payjoin tx
    fn fallback_txid(&self) -> Option<Txid>;         // None when non-segwit (txid unpredictable)

    // or for simplicity, do we JUST provide the OutPoints @ monitor and always ingest the Txid with whatever we detect to come up with the status?

    fn contested_outpoints(&self) -> Vec<OutPoint>; // sender inputs BOTH txs spend — the battleground
    fn receiver_input(&self) -> OutPoint;       // our contributed input — the payjoin "fingerprint"

}

The wallet reports raw facts; the payjoin library classifies

struct ChainView { spends: Vec<OutpointSpend> }
struct OutpointSpend { outpoint: OutPoint, spent_by: Option<Txid>, tx: Option<Transaction>, confirmations: u32 }

enum SettlementStatus {
    Pending,                                              // contested outpoints unspent
    Detected { outcome: Outcome, confirmations: u32 },    // confirmations == 0 means mempool
}
enum Outcome {
    Payjoin { sender_witnesses: Vec<(ScriptBuf, Witness)> }, // privacy achieved + the proof
    Fallback,                                                // original won; no privacy
    Other(Txid),                                             // outpoints spent by an unrecognized tx
}

impl Receiver<Monitor> {
    // Pure: maps observed cs/outpoints. No I/O.
    fn classify(&self, view: &ChainView) -> SettlementStatus;
}

I doubt that this updated follow-up Receiver<Monitor> change is critically necessary for 1.0. What we've shipped seems good enough for mobile wallets to get status. it seems like a critical necessity for automated exchange/service use cases to be robust enough to go prod, but ultimately I think it depends on how much bikeshedding the correct monitor requires and how much we're willing to push back an already long-passed deadline.

Pull Request Checklist

Please confirm the following before requesting review:

• I have disclosed my use of
  AI
  in the body of this PR.
• I have read CONTRIBUTING.md and rebased my branch to produce hygienic commits.

Yes indeed this was co-authored by Claude Code

[coveralls]

Coverage Report for CI Build 28235658451

Coverage remained the same at 85.517%

Details

• Coverage remained the same as the base build.
• Patch coverage: 1 uncovered change across 1 file (9 of 10 lines covered, 90.0%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
payjoin/src/core/receive/v2/mod.rs	9	8	88.89%
Total (2 files)	10	9	90.0%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	15128
Covered Lines:	12937
Line Coverage:	85.52%
Coverage Strength:	361.74 hits per line

---

💛 - Coveralls

[spacebear21]

cACK