Receiver fallback typestate

[spacebear21]

Supersedes #1542.

Receiver counterpart to #1557 . It's a much bigger PR because a) the receiver state machine is more complicated than the sender's, and b) it also implements the "protocol failure" fallback path (i.e. not a manually-initiated cancel, but an irrecoverable error that would also warrant broadcasting the fallback tx).

stateDiagram-v2
      [*] --> Initialized

      Initialized --> UncheckedOriginalPayload: RetrievedOriginalPayload
      UncheckedOriginalPayload --> MaybeInputsOwned: CheckedBroadcastSuitability

      state "9 HasFallbackTx in-protocol states" as InProtocol {
          MaybeInputsOwned --> MaybeInputsSeen: CheckedInputsNotOwned
          MaybeInputsSeen --> OutputsUnknown: CheckedNoInputsSeenBefore
          OutputsUnknown --> WantsOutputs: IdentifiedReceiverOutputs
          WantsOutputs --> WantsInputs: CommittedOutputs
          WantsInputs --> WantsFeeRange: CommittedInputs
          WantsFeeRange --> ProvisionalProposal: AppliedFeeRange
          ProvisionalProposal --> PayjoinProposal: FinalizedProposal
          PayjoinProposal --> Monitor: PostedPayjoinProposal
      }

      UncheckedOriginalPayload --> HasReplyableError: GotReplyableError, fallback_tx is None (broadcast unverified)
      InProtocol --> HasReplyableError: GotReplyableError, fallback_tx is Some

      InProtocol --> PendingFallback: Cancelled (cancel from any HasFallbackTx state)
      PayjoinProposal --> PendingFallback: ProtocolFailed (fatal process_response)
      HasReplyableError --> PendingFallback: Cancelled or ProtocolFailed, when fallback_tx is Some

      Initialized --> Closed: Closed(Cancel) on cancel, or Closed(Failure) on fatal process_response
      UncheckedOriginalPayload --> Closed: Closed(Cancel) on cancel
      HasReplyableError --> Closed: Closed(Cancel) on cancel, or Closed(Failure) on process_error_response, when fallback_tx is None
      Monitor --> Closed: check_payment observes Success, FallbackBroadcasted, or PayjoinProposalSent

      PendingFallback --> Closed: close() emits Closed(Cancel) after Cancelled entry, or Closed(Failure) after ProtocolFailed entry

      Closed --> [*]

      note right of PendingFallback
          Holds the wallet's obligation to broadcast
          or explicitly discard the original tx.
          Stays active until close() so it survives
          resume cycles.
      end note

Loading

Planned with Claude Opus 4.7, implemented by Codex 5.5

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 26202708607

Coverage increased (+0.04%) to 85.179%

Details

• Coverage increased (+0.04%) from the base build.
• Patch coverage: 110 uncovered changes across 3 files (691 of 801 lines covered, 86.27%).
• 21 coverage regressions across 3 files.

Uncovered Changes

File	Changed	Covered	%
payjoin/src/core/receive/v2/mod.rs	515	447	86.8%
payjoin-cli/src/app/v2/mod.rs	54	13	24.07%
payjoin-cli/src/db/v2.rs	1	0	0.0%

Coverage Regressions

21 previously-covered lines in 3 files lost coverage.

File	Lines Losing Coverage	Coverage
payjoin-cli/src/app/v2/mod.rs	14	51.29%
payjoin/src/core/receive/v2/mod.rs	6	90.76%
payjoin-cli/src/app/v1.rs	1	69.33%

---

Coverage Stats

Relevant Lines:	14378
Covered Lines:	12247
Line Coverage:	85.18%
Coverage Strength:	377.71 hits per line

---

💛 - Coveralls

[DanGould]

I read the writeups and concept ACK. I wonder if MayBroadcastFallback is a more appropriate name that implies an action than HasFallback.

[spacebear21]

I wonder if MayBroadcastFallback is a more appropriate name that implies an action than HasFallback.

In the latest iteration of this PR the typestate is called PendingFallback and HasFallbackTx is a sealed marker trait for receiver states that hold a verified broadcastable fallback tx. Does that sound better?