Add reason to `PaymentStatus` `failure`

[reez]

See the reason associated withfailed of PaymentStatus:

public enum PaymentStatus {
    case pending
    case succeeded
    case failed
}

[reez]

::Context::

Maybe there's an alternative way (let me know if so), but if a user taps on the details of a payment I'd like to show them associated info about the failure. Right now I can just show them it failed, but would like to surface other info/hints on why so that the user can understand (and possibly take an informed action).

At the moment I think I can only see the failure reason in the logs, but don't have access to the PaymentStatus's failed reason (that I know of? I might be overlooking something though) to surface to the user.

[Camillarhi]

Hi @reez,

Great point! Currently, PaymentStatus for Failed doesn’t include the failure reason, which limits what users can be shown. Since failures can happen for different reasons (routing issues, insufficient funds, etc.), it would be helpful to attach this info to the status.

@tnull could confirm if extending PaymentStatus to include failure details aligns with the project’s direction. This way, we could surface actionable feedback to users without relying on logs.

Happy to discuss approaches or help with implementation once we agree on the design!

[tnull]

@tnull could confirm if extending PaymentStatus to include failure details aligns with the project’s direction. This way, we could surface actionable feedback to users without relying on logs.

Yeah, as mentioned over at #566 (review) I kind of like the simplicity of the current enum, however, I also see that it would add utility to extend the failure case to include a reason. If we'd want to do that, we should however make it mandatory to supply the reason, i.e., create a new Failure type that would also cover any local- or BDK-specific reasons, not only the ones coming from LDK.

[Camillarhi]

@tnull could confirm if extending PaymentStatus to include failure details aligns with the project’s direction. This way, we could surface actionable feedback to users without relying on logs.

Yeah, as mentioned over at #566 (review) I kind of like the simplicity of the current enum, however, I also see that it would add utility to extend the failure case to include a reason. If we'd want to do that, we should however make it mandatory to supply the reason, i.e., create a new Failure type that would also cover any local- or BDK-specific reasons, not only the ones coming from LDK.

Thanks for the feedback! Making the failure reason mandatory makes sense - ensures we always have something meaningful to show users.
A few questions to help scope this:

1. Should the Failure type be a separate enum covering all failure categories?
2. Are you thinking high-level reasons for users ("Insufficient funds", "Route not found") or more technical details?
3. For BDK-specific reasons, would we want to reuse any existing error types, or create new ones tailored to payment failures?
4. Would you prefer an enum (for fixed error categories) or a struct with optional fields (for more flexibility)?

I'm happy to work on this once we agree on the approach.