Discussion: Enhancing the "Swap" lifecycle

[KanziHanzi]

As of now the Breez SDK allows us to fetch only currently ongoing swaps. However in the past we experienced an issue with our users where an ongoing swap wasn't returned anymore from the SDK method (considering it as complete) but the associated LN payment to the user’s wallet either hasn’t occurred or has potentially failed. At this stage we are basically clueless as to what happened, eventually a user will be able to claim a refund but in the meanwhile there is just nothing for us to tell them.

To improve the user experience, we want to ensure that our users can always see the status of their swaps. After a swap is fully completed, it would also be beneficial to retain the swap data for display in the wallet history (e.g. via SDK method to get the list of past swaps). This data should include various timestamps throughout the swap’s lifecycle (e.g., swap requested, on-chain transaction confirmed, LN payment sent, LN payment received by the recipient).

Please share your thoughts in this thread.

[alessandro-saglimbeni]

always see the status of their swaps […] (e.g. via SDK method to get the list of past swaps). . This data should include various timestamps throughout the swap’s lifecycle (e.g., swap requested, on-chain transaction confirmed, LN payment sent, LN payment received by the recipient).

• If a swap fails and the user triggers the refund, once the process is finished the failed swap is no longer returned, unless AFAIR you pass a flag to return also failed swaps. I have a wallet, currently empty, that shows no transaction, but which I previously tried to fund via a swap-in, it's confusing to see it empty TBH, and it makes investigating issues w/ users harder. The swap-in failures now happen more rarely, thanks to the push notifications, but maybe we should enable the optional flag in production (even though we're not receiving confused reports about swap-ins any longer…I guess until they start failing again for whatever reason)
• if a swap succeeds there's no indication (or we're not properly shoing on Green?) that the money was received from a swap-in, I can't reconstruct on which onchain address I sent originally (or the swap in txid), which would be useful for me to figure out which onchain wallet I used to originate the swap-in tx

[ok300]

@KanziHanzi good question, let me try to address both parts.

First, to your specific case:

Our docs describe the high-level view of the swap lifecycle:

The process of receiving funds via an on-chain address is trustless and uses a submarine swap. This means there are two ways to spend the sent funds:

• Either by a preimage that is exposed when the Lightning payment is completed - this is the positive case where the swap was successful.
• Or by your node when the swap didn't complete within a certain timeout (216 blocks) - this is the negative case where your node will execute a refund (funds become refundable after 288 blocks). Refund will also be available in case the amount sent wasn't within the limits.

https://sdk-doc-greenlight.breez.technology/guide/receive_onchain.html

This means that, once it's in progress, it can either succeed or become refundable.

From your description, it seems you're likely in the second scenario. If so, you can see all refundable swaps with list_refundables and can initiate a refund using refund. More details are here: https://sdk-doc-greenlight.breez.technology/guide/receive_onchain.html#refund-a-swap

To your second point about tracking the swap through it's lifecycle:

The best way to track the progression through different states is by listening for events. For swaps, we emit a SwapUpdated event each time it's status changes. Logging these events, optionally with their payload, can be useful when tracking the changes through time.

Separate from this, list_payments should show all payments with their current status: Pending, Complete or Failed. By default, it doesn't include failed payments, but the caller can set that flag in the list_payments argument in order to show all known payments. So when in doubt, you can always use this to get a current view of all known payments and their status.

[ok300]

@alessandro-saglimbeni to your points:

• Correct, list_payments doesn't include failed payments by default, but that can be enabled with a flag.
• If a payment came from a swap, you can tell which swap it's associated with by looking at the payment's details field (of type LnPaymentDetails) which contains either a swap_info or a reverse_swap_info field. Those include the relevant onchain addresses from which you can then trace back the payment.

[KanziHanzi]

@ok300

This means that, once it's in progress, it can either succeed or become refundable.

In our experience this only happens delayed though. Correct me if I'm wrong but the swap only becomes refundable after a certain waiting time passed (I believe ~48 hours). The issue I'm talking about is that the swap is neither returned as ongoing nor as refundable from the respective SDK methods.

I think it would be very helpful if you guys could share how you are showcasing a given swap throughout it's lifespan in the app UI (from initiation to LN payment received)

[roeierez]

@KanziHanzi I think it is indeed a gap we need to address. We are thinking on adding list_swaps function to return swaps with their status. We can also add filters by specific statuses. Do you think that will cover your use case?

[KanziHanzi]

@roeierez Yes that sounds good. If that covers all swap statuses from initiation to completion would be very helpful indeed

[KanziHanzi]

Hey @roeierez what's the status on this topic? Did you guys already had a chance to work on the proposed list_swaps SDK function?

[JssDWt]

The list_swaps function was just merged into main. It should be part of the next release.