Description
Should the v2 receiver expose a typed transition for an application that decides to stop processing a request and notify the sender with unavailable?
A concrete case arose in BTCPay’s ownership-lookup work. The plugin bounds backend operations per proposal so expensive requests cannot indefinitely occupy shared receiver workers. Temporary dependency failures retry with backoff, but deterministic budget exhaustion stops further attempts.
At that point, the receiver is still in MaybeInputsOwned. Ownership remains unknown: the application has decided not to spend more resources establishing it.
The existing alternatives have different effects:
- Retain the state until expiry, without sending a prompt refusal.
- Persist
cancel()and enterPendingFallback, without sending an error reply. - Return an
ImplementationErrorfrom the ownership callback, which retains the state as a transient failure rather than persisting a replyable error.
These are valid choices. The question is whether applications should also have a supported way to decline further work and durably notify the sender, without manufacturing an ownership result or treating an application limit as a protocol violation.
This could also serve wallets enforcing resource quotas or deciding that a backend failure has exceeded their retry window. Retry and refusal policy would remain application decisions.
The existing GotReplyableError event, HasReplyableError state and error-delivery flow appear to provide the underlying machinery. Replay already accepts that event from MaybeInputsOwned, preserving the reply context and fallback transaction. The proposed addition could therefore reuse the existing persistence format.
Questions for discussion:
- Is explicit notification useful enough to warrant a typed API, or should applications generally use cancellation here?
- Should an initial API be limited to
MaybeInputsOwned, or shared across appropriate validation states? - Should it expose only a generic
unavailableresponse, keeping internal failure details local? - Is constructing the existing event through lower-level APIs an intended integration path, or should the library own this transition?
If added, the transition should follow the normal save-before-delivery contract, survive restart and transient reply-delivery failures, and preserve fallback handling. It should not automatically turn temporary callback failures into terminal refusals or broadcast the fallback.
Related: #1422 — error-handling guidance and #1213 — fallback after input-contribution failure. This discussion concerns the additional choice to notify the sender when the application declines further processing.
Activity
xstoicunicornx commentedon Nov 6, 2026
Is there an error that
HasReplyableErrorreports that is not protocol related?My thinking is that this should simply be handled as a cancel with the fallback being broadcasted. Even if the
unavailablestatus was reported back to the sender there isn't really any tangible feedback given to the sender to enable the sender could "fix" the payjoin.chavic commentedon Nov 9, 2026
@xstoicunicornx That makes sense. The idea isn't that cancel doesn't work; I think that's correct for the current API. The question is whether it's worth having an explicit error when the payjoin fails at that stage. Just needed to run the thought by someone so I'm not too conservative when it comes to additions.
To answer your question directly: no, not today. Every path into
HasReplyableErrorcomes from a protocol/validation failure. If the application's callback fails with anImplementationError, it's always treated as transient and never persisted as a reply.Where this came from is Valera's ownership-lookup work in BTCPay (#218). The plugin caps how much backend work each proposal can use, so expensive requests can't tie up shared receiver workers. Temporary dependency failures retry with backoff, but once a proposal hits that cap, the plugin stops trying. At that point the receiver is still in
MaybeInputsOwned, and ownership is simply unknown: nothing is wrong with the PSBT, BTCPay has just decided not to spend more on it.His options right now are awkward for that case. Since ownership is still unknown, the plugin can't call
check_inputs_not_ownedwith a real answer, so it just leaves the session inMaybeInputsOwneduntil expiry, which is the same effect as returning anImplementationError. He asked for a way to persist anunavailablereply fromMaybeInputsOwnedbecause that would be BTCPay saying "I'm declining this one" explicitly, using the same genericunavailable/ "Receiver error" thatError::Implementationalready maps to. It would keep the fallback, so the session still ends inPendingFallback.So it's cancel plus a notice, not a different outcome. Agreed the sender can't fix anything. The cancel path works; the only gain is that the sender learns right away to broadcast the original instead of polling until the session expires.
DanGould commentedon Nov 9, 2026
Just a quick thought for now: I think it may be worth altering the protocol with a "declined" message or some sort of response. Probably not unavailable but I have thought about this before (when doing silent payments stuff) and it's validating for you to have independently come up with it. I think it's something for us to do but I need to give it a bit more thought, especially because it's spec.
xstoicunicornx commentedon Nov 9, 2026
Thanks for additional context Chavic! I would add that I'm not against updating the spec to have some "decline" short circuit message to send back to the sender, but I think I am more against adding functionality not specified in the spec.
Chavic, just to confirm when the receiver wants to end the payjoin early the receiver is also broadcasting the fallback immediately correct? There should be no reason to have to wait until expiry.
DanGould commentedon Nov 10, 2026
A canceling receiver goes through the pending fallback state and has the transaction ready to broadcast. It should just broadcast instead. That gives the receiver the option to broadcast and if you're a automated store, you definitely want to take that option.
In general this is described in the #1950 issue as "Declining a request for the receiver's own reasons" which is useful if the receiver is NOT ever intending to broadcast, but in an automated merchant receiver case that seems less common than wanting to broadcast
DanGould commentedon Nov 11, 2026
I thought more of this today, because even though the particular BTCPayServer issue IMO SHOULD be fixed with a different approach, responding that you won't broadcast is a useful thing to spec. What I recommend:
Spec a
declinedcode with a sender rule (broadcast now if you'd like, don't continue to retry til expiration, stop polling), and have the PDK transition send it. Don't let PDK ship a typed transition that hard-codes unavailable for this purpose, because that would set the ambiguous meaning in an API before the updated bip77 spec exists so the two should roll out roughly at the same time.