Guide
Guide copied to clipboard
BitcoinDesign
Linking prefixes for managing inter-app payments
Zeus recently merged a novel way to deal with inter-app payments on mobile (particualry for iOS which has UX issues with handling bitcoin: URIs) using linking prefixes. @tim-edwards from THNDR games was the one to put this idea forward. Details on how this work can be found in this issue https://github.com/ZeusLN/zeus/issues/888 and this PR https://github.com/ZeusLN/zeus/pull/889.
Essentially when an app needs to present payment request the user selects the app that they want to pay with. Behind the scenes Zeus THNDR searches from a unique Zeus prefix (see PR linked above) and interacts with Zeus through that bypassing iOS's URI handling scheme.
In the image below:
- Zeus has been selected in THNDR games as the app to pay this invoice. Zeus had to add a handling prefix for this to be managed as mentioned above.
- Zeus is automatically opened when clicking claim in THNDR games
- Zeus autofills the payment request inputs and creates an invoice and shares it with THNDR to be paid.
- THNDR pays the invoice <3
Is this something we would want to cover in the guide? It isn't the most eloquent solution but iOS bitcoin app handling is probably a worse UX.
If it's useful I wrote up a case study on this "wallet messaging" mechanism
https://www.figma.com/file/80KWCeC4XWoxjfPcscPChl/Wallet-Messaging-Use-Case
It would be good to address the issue of inter-app payments. As I always say, I don't want to impose specific engineering solutions in the Guide, but I definitely think the topic of inter-app messaging is one worth talking about.
I think many apps use their own URI prefix. Makes sense, because a lot of apps fill a unique niche. I liken bitcoin to something more like email. So I would love it if iOS let you pick your default app for bitcoin the same way you can have a default app for mailto. But in the interim, custom prefixes could be a perfectly good solution.
More generally speaking, there seem to be four mechanisms for sharing invoices between apps (excluding copy and QR codes):
- Web link click via custom prefixes (BIP21)
- WebShare API
- "App link click" (iOS custom URL schemes)
- App share sheet (iOS, Android)
Two of these work via URL schemes that apps registers to, the other two let you invoke a "share" function that is then handled by the OS (I like this because the OS can show a list of apps the user has installed). From some quick testing on the web, I see very different behaviors across browsers and techniques between the WebShare API and link clicks. You think it's is worth doing testing and a write-up in detail across all these options so we can then recommend specific implementations?
Thanks @Bosch-0, maybe I can explain further the issue we had to solve at THNDR Games if it's of interest to anyone.
We give out sats as prizes in our games during a daily prize draw, and create LNURL withdraw invoices.
Previous to changing the whole system I created the URI by just prefixing the LNURL with the lightning url scheme, and attempt to open it on the OS of the players device, this would open up a wallet app capable of supporting lightning.
Unfortunately as @sbddesign has pointed out, on iOS it's not possible to pick your default app for lightning, but another huge factor leading to the development of the new system was I'm afraid CashApp, who support the lightning scheme but do not handle the invoice (at the time of writing anyway), and loads of our players were contacting support asking how they could claim as that would have been the last "wallet" app they installed.
So far using custom deep link url schemes has worked out really well and our players can now withdraw sats to their wallet of choice. Currently we support: SBW, BlueWallet, Breez, Wallet of Satoshi and Zebedee who already everything set up to work straight away.
I've also made a few feature requests for this to other wallets, Zeus being one, along with Blixt, Muun and Phoenix, all of whom have now added or are in the process of adding support, and I believe Strike are also working on a solution as well.
You think it's is worth doing testing and a write-up in detail across all these options so we can then recommend specific implementations?
Yes
@sbddesign @Bosch-0 Considering Sending page has change quite a bit since this issue was opened, is this still relevant? Can we try to scope it if so, what needs to be added here specifically? I am not sure I completely understand how important this is, even though technically it's interesting, but is it practical?
@pavlenex It's relevant still, but doesn't belong on the Sending page, IMHO. This sort of guidance would be for apps outside of the daily spending wallet.
Example:
- You're on some kind of app or website on your phone
- You have to pay for a subscription or to checkout with your cart
- App says "how you wanna pay?"
- You select "bitcoin obviously"
- And then the app has to present you with a way to pay them in bitcoin
- One way to do this is by presenting a BIP21 URI or a BOLT11, which you must copy and paste into your cool daily spending wallet. It 100% works, it just feels a little clunky.
- Another way is to just include a
lightning:or ideally abitcoin:bc1p...?lightning=lnbc...under a "tap here to pay" button. The problem is, you are hoping and praying that iOS opens the cool daily spending wallet that the user wants. But your hopes and prayers will likely fall upon deaf ears and iOS will just open the last app installed. This would be the smoothest experience imaginable if it weren't for this iOS annoyance. - And yet another way is to have some kind of dropdown menu or whatever that's like "select the wallet you want to use" and then it uses the interapp prefix instead of
bitcoin:..., and you of course include abitcoin:...as a fallback in case the user does not have any of the wallets in the dropdown. This works great, except maybe it's a privacy problem if the app developer knows what wallet every customer has, and it's a little bit of an extra step, and just by the principle it feels sort of wrong because all of this stuff should be interoperable af. But pragmatically, it gets the job done in a lot of scenarios without asking the user to copy/paste.
I think we should just do a separate page for this thing, maybe under "Designing bitcoin products" or maybe under "How it works".
I would put this in a small section in the "How it works" section for now. This is a temporary round about UX solution to iOS being crappy at link handling. Could be a similar small page to the "Sign in with bitcoin" page.
Another in Damus. I really like how you can set you default wallet in the settings so you don't have to select your wallet every time
I'll try to tackle this one in milestone 19. Thinking that it could just be a case study. We have plenty of examples in this thread that we can show and discuss. Screens based on the UI Kit could also be mixed in, but we may not need it.
Here's a first draft for this one. I still think this technique will be relevant until BOLT12 has been super broadly adopted (who knows, maybe even beyond that). My draft is narrowly focusing on this wallet selector technique. It is intended as a case study that simple documents a practical solution that has found its place in various app in the ecosystem. Please take a look.
LGTM, I like the simplicity of how it was written, very easy to understand and digestible language. Added in some minor suggestions in terms of headings and sentence structure. Other than that it's a very easy to digest and read case study.
