Receive cancel()

[spacebear21]

This implements a generic cancel() method on the Receiver, following up on discussion from #1134.

As discussed on the PR review club a few weeks ago, this implementation of cancel() returns the fallback transaction as a convenience and a "hint" to broadcast it if it hasn't already been. Doing this adds quite a bit of complexity due to having to implement a fallback_tx getter for every concrete typestate, some of which return None. IMO the ergonomics are probably worth the cost of this internal ugliness, but I'm curious what other people think.

The existing flow is for implementers to call extract_tx_to_schedule_broadcast after the broadcast suitability check passes and store that somewhere for broadcasting later, or to replay events and use SessionHistory::fallback_tx to access it for broadcasting. This PR introduces a third accessor for the same data. Is there still a need for the other two getters if we aim to encourage cancel()ing?

Supersedes #1134.

Authored with Claude - who incidentally has learned to generate all downstream language bindings and run their tests in parallel in the background while doing other things.

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 24473537273

Coverage increased (+0.03%) to 84.368%

Details

• Coverage increased (+0.03%) from the base build.
• Patch coverage: 9 uncovered changes across 1 file (72 of 81 lines covered, 88.89%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
payjoin/src/core/persist.rs	16	7	43.75%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	12884
Covered Lines:	10870
Line Coverage:	84.37%
Coverage Strength:	409.85 hits per line

---

💛 - Coveralls

[DanGould]

soft/draft ACK 3f2e13e assuming mutants issues can be explained. This design is simple to understand. Draft just because it's not yet in payjoin-cli? I don't think we'll be able to confidently answer whether the ergonomics of this are correct nor if the other accessors can be deleted until the reference implementation adopts it. Not sure if that looks like #1164 or your own implementation in this PR. But I have a strong hunch this is the right direction and am comfortable even merging before we have such confidence because so much discussion around this already landed on this design.

---

Reviewing per the discussion in #1470

does cancel():

• immediately close the session with SessionOutcome(Cancel)
• return the fallback transaction to broadcast.

Ya you have tests for these

[spacebear21]

I agree on the iterative approach for ergonomics.

I should have taken this out of draft. The mutants are there because I need to test every single typestate's fallback_tx implementation, currently it just tests one that returns Some(tx) and one that returns None. Fixing this shortly since we now agree on implementation approach.

[spacebear21]

Updated the unit testing to go through every typestate and check the presence/absence of a fallback tx