Compute (potentially reorging) Settlement Status From Wallet Data

[DanGould]

This is following up on #1684 where I figured out Monitor's status can go stale in the case of a reorg. Instead, we can run a classifier that can always classify the status based on mempool+chain state data instead.

This classification, that tracks OutPoint status also makes the #1218 workaround that skips monitoring the status of non-segwit outputs obsolete and can actually monitor non-segwit spending Payjoin cooperative txs.

Sessions still close once a Receiver<Monitor> detects a transaction but the actual SettlementStatus is determined by calling classify on chain state each time.

Co-authored by Claude code

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.

[coveralls]

Coverage Report for CI Build 28389258738

Coverage increased (+0.3%) to 85.769%

Details

• Coverage increased (+0.3%) from the base build.
• Patch coverage: 27 uncovered changes across 2 files (461 of 488 lines covered, 94.47%).
• 2 coverage regressions across 2 files.

Uncovered Changes

File	Changed	Covered	%
payjoin-cli/src/app/v2/mod.rs	59	36	61.02%
payjoin/src/core/receive/v2/mod.rs	408	404	99.02%
Total (4 files)	488	461	94.47%

Coverage Regressions

2 previously-covered lines in 2 files lost coverage.

File	Lines Losing Coverage	Coverage
payjoin-cli/src/app/v2/mod.rs	1	51.94%
payjoin/src/core/receive/v2/mod.rs	1	92.78%

---

Coverage Stats

Relevant Lines:	15565
Covered Lines:	13350
Line Coverage:	85.77%
Coverage Strength:	351.75 hits per line

---

💛 - Coveralls

[spacebear21]

IMO such an API change should wait until after 1.0 release and is a candidate for a 2.0 API:

• Like you said in Rename Receiver<Monitor>::check_for_broadcast to check_for_transaction, etc. #1684: "I doubt that this updated follow-up Receiver change is critically necessary for 1.0. What we've shipped seems good enough for mobile wallets to get status". We already have plenty of demand from mobile wallets and releasing a stable API now seems like a bigger win than pushing that deadline further while we debate the exact monitor shape.
• We already have a big breaking API rewrite in the works with Non-blocking Interface for Payjoin State Machine  #1446, that would abandon the callback pattern for advancing the state machine in favor of a validator pattern where the typestate machine is advanced explicitly by providing the result of the check explicitly. That seems more inline with the Monitor approach in this PR and those changes can all be bundled into a comprehensive, well thought-out 2.0 follow-up.

In the meantime, I think it's sufficient to add a big disclaimer in the check_for_transaction making it clear that it:

• doesn't properly support non-segwit inputs (see also discussion in General question on receiver's ProvisionalProposal and Monitor typestates #1548 (comment))
• checks for transaction finality however the implementer chooses to define that (e.g. could check on 6-conf to be reorg safe).

[chavic]

Field evidence in favor of this direction, from the BTCPay Server payjoin plugin (a settlement-accounting receiver over payjoin-ffi): we independently hit both flaws this PR identifies. Our accounting layer pins the proposal's expected transaction ID at hand-out time for exact reconciliation, which is silently wrong for non-SegWit senders (we currently reject them as policy, ValeraFinebits/btcpayserver-payjoin-plugin#78), and our stored reconciliation verdict shares the stale-on-reorg problem — a re-runnable classify() over contested outpoints would replace both host-side workarounds, and the Cooperative cut-through recognition covers a case txid-pinning can't see at all.

In the meantime, for whatever it's worth to the 1.0 discussion: #1718 proposes the machine-readable version of the disclaimer suggested above — proposal_txid_is_stable() on the fallback-holding states, additive-only and shape-neutral with respect to this PR; it degrades into a convenience if this lands.