From cc2b6b86aee6f4377d25d3315523e090c2ed11c4 Mon Sep 17 00:00:00 2001 From: Ross Savage Date: Wed, 15 Jan 2025 12:14:31 +0100 Subject: [PATCH] Adds event flows tables for each send/receive payment method --- src/guide/receive_payment.md | 32 +++++++++++++++++++++++++++----- src/guide/send_payment.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 5 deletions(-) diff --git a/src/guide/receive_payment.md b/src/guide/receive_payment.md index 2adfb86c..b24d672d 100644 --- a/src/guide/receive_payment.md +++ b/src/guide/receive_payment.md @@ -251,11 +251,6 @@ receive method, optionally specifying a description. - For Bitcoin/Liquid BIP21 payments, it will be encoded in the URI as the `message` field. - For plain Liquid payments, the description has no effect. -
-

Developer note

-When waiting for a payment to be received, it is enough to wait for a PaymentWaitingConfirmation event before displaying a successful payment feedback in the UI. At this point the transaction is broadcast and will be shortly confirmed. -
-
Rust
@@ -321,3 +316,30 @@ When waiting for a payment to be received, it is enough to wait for a Paym ```
+ +## Event Flows +Once a receive payment is initiated, you can follow and react to the different payment events using the guide below for each payment method. See [Listening to events](/guide/events.html) for how to subscribe to events. + +### Lightning +| Event | Description | UX Suggestion | +| --- | --- | --- | +| **PaymentPending** | The swap service has intercepted a HTLC for the Lightning invoice and broadcast a lockup transaction. The SDK has seen the lockup transaction and will broadcast the claim transaction, either when the lockup transaction is confirmed or if it is accepted as a zero-conf payment. | Show payment as pending. | +| **PaymentWaitingConfirmation** | The claim transaction has been broadcast or a direct Liquid transaction (MRH) has been seen. | Display successful payment feedback. | +| **PaymentSucceeded** | The claim transaction or direct Liquid transaction (MRH) is confirmed. | Show payment as complete. | +| **PaymentFailed** | The swap has failed from one of several reasons. Either the swap/invoice has expired or the lockup transaction failed to broadcast. | | + +### Bitcoin +| Event | Description | UX Suggestion | +| --- | --- | --- | +| **PaymentWaitingFeeAcceptance** | The swap service has seen the Bitcoin lockup transaction. If there was no amount set for this swap or the Bitcoin lockup transaction contains a different amount, the fee has to be accepted, see [Amountless Bitcoin Payments](#amountless-bitcoin-payments). If the fee is within the configured leeway, the swap will be automatically accepted. | Allow the user to review fees for this payment. | +| **PaymentPending** | The swap service has seen the Bitcoin lockup transaction and the amount is accepted. Once the SDK has seen the Liquid lockup transaction it will broadcast the Liquid claim transaction, either when the Liquid lockup transaction is confirmed or if it is accepted as a zero-conf payment. | Show payment as pending. | +| **PaymentWaitingConfirmation** | The Liquid claim transaction has been broadcast and is waiting confirmation. | Display successful payment feedback. | +| **PaymentSucceeded** | The Liquid claim transaction is confirmed. | Show payment as complete. | +| **PaymentFailed** | The swap has failed from one of several reasons. Either the swap has expired, the fee was not accepted or the Liquid lockup transaction failed to broadcast. If a Bitcoin lockup transaction was broadcast then the funds will need to be refunded, see [Refunding payments](/guide/refund_payment.html). | | +| **PaymentRefundPending** | A Bitcoin refund transaction has been broadcast and is waiting confirmation. | | + +### Liquid +| Event | Description | UX Suggestion | +| --- | --- | --- | +| **PaymentWaitingConfirmation** | The transaction has been seen. | Display successful payment feedback. | +| **PaymentSucceeded** | The transaction is confirmed. | Show payment as complete. | diff --git a/src/guide/send_payment.md b/src/guide/send_payment.md index 1d646112..30067cc7 100644 --- a/src/guide/send_payment.md +++ b/src/guide/send_payment.md @@ -385,3 +385,32 @@ send method. ``` + +## Event Flows +Once a send payment is initiated, you can follow and react to the different payment events using the guide below for each payment method. See [Listening to events](/guide/events.html) for how to subscribe to events. + +### Lightning +| Event | Description | UX Suggestion | +| --- | --- | --- | +| **PaymentPending** | The SDK has broadcast the lockup transaction for the swap. | Show payment as pending. | +| **PaymentWaitingConfirmation** | If the Lightning invoice contains an MRH, the SDK will instead broadcast a direct Liquid transaction. | Display successful payment feedback. | +| **PaymentSucceeded** | The swap service has seen the lockup transaction and broadcast the claim transaction, or the direct Liquid transaction (MRH) is confirmed. | Show payment as complete. | +| **PaymentFailed** | The swap has expired without a lockup transaction. | | +| **PaymentRefundPending** | The swap can be refunded for several reasons. Either the swap/invoice has expired or the swap service failed to pay the invoice. In this case the SDK will broadcast a refund transaction. | | +| **PaymentRefunded** | The refund transaction is confirmed. | | + +### Bitcoin +| Event | Description | UX Suggestion | +| --- | --- | --- | +| **PaymentPending** | The SDK has broadcast the Liquid lockup transaction. Once the SDK has seen the Bitcoin lockup transaction it will broadcast the Bitcoin claim transaction, either when the Bitcoin lockup transaction is confirmed or if it is accepted as a zero-conf payment. | Show payment as pending. | +| **PaymentWaitingConfirmation** | The Bitcoin claim transaction has been broadcast and is waiting confirmation. | Display successful payment feedback. | +| **PaymentSucceeded** | The Bitcoin claim transaction is confirmed. | Show payment as complete. | +| **PaymentFailed** | The swap has expired without a Liquid lockup transaction. | | +| **PaymentRefundPending** | The swap can be refunded for several reasons. Either the swap has expired or the Bitcoin lockup transaction failed to broadcast. In this case the SDK will broadcast a Liquid refund transaction. | | +| **PaymentRefunded** | The Liquid refund transaction is confirmed. | | + +### Liquid +| Event | Description | UX Suggestion | +| --- | --- | --- | +| **PaymentWaitingConfirmation** | The transaction has been seen. | Display successful payment feedback. | +| **PaymentSucceeded** | The transaction is confirmed. | Show payment as complete. |