Skip to content

Adds daily spending receive guidance for BOLT 12 and splicing #1194

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Adds daily spending receive guidance for BOLT 12 and splicing #1194

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54040b7
Adds wallet guidance bolt 12 and splicing for payment requests
ConorOkus Sep 11, 2025
5b75c39
Update guide/daily-spending-wallet/requesting/requesting.md
ConorOkus Sep 12, 2025
aa624c9
Update guide/daily-spending-wallet/requesting/requesting.md
ConorOkus Sep 12, 2025
73ae18a
Update guide/daily-spending-wallet/requesting/requesting.md
ConorOkus Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions guide/daily-spending-wallet/requesting/requesting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,13 +155,14 @@ Moreover, users have the option to skip entering an amount. This flexibility cat

After entering an amount, the user taps the 'Request' button. The app then generates and presents a payment request.

This wallet defaults to a [unified payment request]({{ "/guide/how-it-works/payment-request-formats/#unified-payment-requests" | relative_url }}). These combine a [lightning invoice]({{ "/guide/how-it-works/payment-request-formats/#invoice" | relative_url }}) and an [on-chain address]({{ "/guide/how-it-works/payment-request-formats/#addresses" | relative_url }}) into a single payment request using BIP21.
This wallet defaults to a [unified payment request]({{ "/guide/how-it-works/payment-request-formats/#unified-payment-requests" | relative_url }}). This combines a [lightning invoice]({{ "/guide/how-it-works/payment-request-formats/#invoice" | relative_url }}), an [offer]({{ "/guide/how-it-works/payment-request-formats/#offers" | relative_url }}) and an [on-chain address]({{ "/guide/how-it-works/payment-request-formats/#addresses" | relative_url }}) into a single payment request using BIP(3)21.

Unified requests eliminate the hassle for users of choosing between requesting payment via the lightning network or on-chain. This choice can often be confusing, particularly for newcomers.

This wallet utilizes 'swap addresses' for all on-chain transactions. These are used to facilitate the transfer of received Bitcoin into the user's Lightning balance. Consequently, the wallet maintains a single Lightning balance, avoiding the need for a separate on-chain balance. This simplifies the user experience and is trust-minimized and non-custodial, courtesy of [submarine swaps](https://thebitcoinmanual.com/articles/btc-submarine-swaps/). We cover these more in our [lightning services]({{ "/guide/how-it-works/lightning-services/#swaps" | relative_url }}) and receiving pages.

As unified requests [aren't widely supported yet](https://bitcoinqr.dev/), and users may want to request just from lightning or on-chain, they have options to share the lightning invoice or on-chain address independently.
This wallet utilizes **splicing** for all on-chain transactions. Splicing allows the seamless transfer of received Bitcoin into the user's Lightning balance without maintaining a separate on-chain balance. As a result, the wallet presents a single Lightning balance, greatly simplifying the user experience. This approach is trust-minimized and non-custodial, as channel capacity can be increased or decreased directly on-chain without relying on external swap services. We cover these more in our [lightning liquidity]({{ "/guide/how-it-works/liquidity" | relative_url }}) and receiving pages.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is existing language, but "for all on-chain transactions" tripped me up. I assume it only means receive-only?

Since added text mentions lightning liquidity and receiving pages, content will also have to be added/updated on those pages.

Suggested change
This wallet utilizes **splicing** for all on-chain transactions. Splicing allows the seamless transfer of received Bitcoin into the user's Lightning balance without maintaining a separate on-chain balance. As a result, the wallet presents a single Lightning balance, greatly simplifying the user experience. This approach is trust-minimized and non-custodial, as channel capacity can be increased or decreased directly on-chain without relying on external swap services. We cover these more in our [lightning liquidity]({{ "/guide/how-it-works/liquidity" | relative_url }}) and receiving pages.
This wallet utilizes **splicing** for on-chain transactions. Splicing allows the seamless transfer of received Bitcoin into the user's Lightning balance without maintaining a separate on-chain balance. As a result, the wallet presents a single Lightning balance, greatly simplifying the user experience. This approach is trust-minimized and non-custodial, as channel capacity can be increased or decreased directly on-chain without relying on external swap services. We cover this in detail in our [lightning liquidity]({{ "/guide/how-it-works/liquidity" | relative_url }}) and receiving pages.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, if the full balance is always on lightning, then a splice would also be needed for sending, no? To get the ₿ out of the channel?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. This being the Requesting page, shouldn't the commentary be restricted to receiving anyways? On this front, this is a bit of a nit.

(disclaimer: lightning is not my wheelhouse, so I'd love to know what you and others who understand this better, think.)

Re: the meat of your question:

My understanding is that one of the main benefits of splicing for on-chain, is that it increases your channel size, which is strictly good, which also benefits other use cases. But using splicing for on-chain sends will reduce channel size, which is not desirable. For e.g. this might make subsequent lightning receives (use case 2 above) more likely, to require splicing with associated on-chain cost.

Perhaps swaps is an alternative approach that could be used (retained?) for on-chain sends. I know there are issues (costs, third party reliance?) with this too. I've asked Phoenix on twitter, let's see if they respond.

Copy link
Contributor

@yashrajd yashrajd Sep 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

update: phoenix uses splice outs, but also – https://x.com/phoenixwallet/status/1970891555704799740

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reducing channel size can be desirable, no? When I have a big balance and want to move it to cold storage or so?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point, and a proper splice out use-case... (i wonder if there should be a proper flow for this to allow users to do this?)..,


As unified requests [aren't widely supported yet](https://bitcoinqr.dev/), and users may want to request just from lightning or on-chain, they have options to share the lightning invoice or offer or on-chain address independently.

Receiving payments to this wallet requires users to be online. This wallet notifies users that their wallet should remain open until the payment is received. We cover this more on our [receiving]({{ "/guide/daily-spending-wallet/requesting/receiving/#receiving-offline" | relative_url }}) and [lighting services]({{ "/guide/how-it-works/lightning-services/#receive-payments-offline" | relative_url }}) pages.

Expand Down Expand Up @@ -223,7 +224,7 @@ Requests can be shared wirelessly over short distances using [near-field communi

### Payment link

Payment links use a BIP21 [URI]({{ "/guide/how-it-works/payment-request-formats/#uniform-resource-identifier-uris-schemes" | relative_url }}) `bitcoin:` which makes these readable by other bitcoin applications. These can be included as part of a button or hyperlink. Also see the [wallet selector UI pattern]({{ "/guide/how-it-works/wallet-selector/" | relative_url }}).
Payment links use a BIP(3)21 [URI]({{ "/guide/how-it-works/payment-request-formats/#uniform-resource-identifier-uris-schemes" | relative_url }}) `bitcoin:` which makes these readable by other bitcoin applications. These can be included as part of a button or hyperlink. Also see the [wallet selector UI pattern]({{ "/guide/how-it-works/wallet-selector/" | relative_url }}).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"BIP(3)21" tripped me up since I didn't know about BIP321, but it might be just me.

The linked page (payment request formats) only mentions BIP21, so this could be updated to mention and link to BIP321.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably fine to just write BIP21 here. The (3) part reads funny, and BIP21 covers the relevant functionality.


{% include image-gallery.html pages = page.images_link %}

Expand Down