Skip to content

Allow a v2 receiver to explicitly decline with a persisted 'unavailable' reply #2036

Open

Description

@chavic

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 enter PendingFallback, without sending an error reply.
  • Return an ImplementationError from 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:

  1. Is explicit notification useful enough to warrant a typed API, or should applications generally use cancellation here?
  2. Should an initial API be limited to MaybeInputsOwned, or shared across appropriate validation states?
  3. Should it expose only a generic unavailable response, keeping internal failure details local?
  4. 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

  1. xstoicunicornx commented on Nov 6, 2026

    @xstoicunicornx
    Collaborator

    Is there an error that HasReplyableError reports 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 unavailable status 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.

  2. chavic commented on Nov 9, 2026

    @chavic
    CollaboratorAuthor

    Is there an error that HasReplyableError reports 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 unavailable status 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.

    @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 HasReplyableError comes from a protocol/validation failure. If the application's callback fails with an ImplementationError, 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_owned with a real answer, so it just leaves the session in MaybeInputsOwned until expiry, which is the same effect as returning an ImplementationError. He asked for a way to persist an unavailable reply from MaybeInputsOwned because that would be BTCPay saying "I'm declining this one" explicitly, using the same generic unavailable / "Receiver error" that Error::Implementation already maps to. It would keep the fallback, so the session still ends in PendingFallback.

    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.

  3. DanGould commented on Nov 9, 2026

    @DanGould
    Member

    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.

  4. xstoicunicornx commented on Nov 9, 2026

    @xstoicunicornx
    Collaborator

    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.

  5. DanGould commented on Nov 10, 2026

    @DanGould
    Member

    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

  6. DanGould commented on Nov 11, 2026

    @DanGould
    Member

    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 declined code 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions