Adds new page about human readable addresses #1082
Conversation
This is something we've discussed for a few weeks in the UX channel in Discord and turns the findings into a page. I think there's more work to do in cross-linking this from all the right places. I updated a few spots, but there's probably more. The UI mock-ups are more directional than implementation-ready, which I think is fine. But we could flesh this out further in a revision at a later point.
GBKS
added
Copy
✅ Deploy Preview for bitcoin-design-site ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Hi, Chris! Looks great so far, but I have a few issues:
|
Co-authored-by: Johns Beharry <[email protected]>
|
Thank you for the super-fast feedback.
Thanks for pointing that out. I just pushed a commit updating the sample domains. I had checked whether there are official .btc domains, but was not aware of this "other" use.
There was a lot of discussion around the Also, did you just mention using a sat symbol? 😉
True, it is pretty dismissive. But PayNyms is basically a single database, while the other proposals do their best to decentralize, but are bound by the "basic infrastructure of the internet". Ver different ends of the spectrum to me. But if it is too dismissive, then it should be revised.
Agree, this needs more fleshing out. I mention in the page that the UI mocks are conceptual, and I'd like to take more time to discuss and sort this out. I still have some open questions, but also wanted to get this page out. How do you think this will play out? Dedicated bitcoin address services like we have in Nostr for NIP-05 identifiers? Thanks again for the feedback. |
|
With Paynyms, I'm a bit too ignorant, but I'm skeptical they are any more centralized than DNS. All namespaces require an authoritative list to exist somewhere. And anyone can host a new list, or query any existing list they want to. Centralized/decentralized isn't really the correct paradigm for namespaces. Regarding how I think this will all play out, well, I think it is all moot tbh, and that such things are a fad born of ignorance. No one needs nicknames at a protocol level, they are app-level concerns and thus should be rendered in contact list UX. Domain names are a scam, and thus pay-names follow in kind. This is my, likely unpopular, opinion, so it could also be wrong :) Think of DNS more like a list of phone numbers. I can either make a list myself, or trust someone else to provide a list (like a phone book/directory), but the difference is all about there being a trusted authority, thus solutions that do not require such an authority are more interesting, or, solutions that aggregate many lists, etc. If a user wants to pay "Mom" they should be able to just tap on Mom's face, not type in her fake email address into some novel UX. |
|
I don't see the value in using the B symbol (which I frankly don't even know how to make with my keyboard). Can somebody educate me on the dangers of mixing up an email address and a bitcoin payment identifier? |
Co-authored-by: Johns Beharry <[email protected]>
Co-authored-by: Johns Beharry <[email protected]>
To be clear, the keyboard issue shouldn't be an issue - it should be displayed and in a copy (if wallets allow copying the human-readable names directly, though generally they should prefer to copy the underlying payment instructions for noncustodial wallets), but users shouldn't need to type it. The reason its there is because payment instructions are a different namespace from email. We've already seen at least one case where a company uses their domain for emails and also to provide users with lnaddresses, with someone having the lnaddress who doesn't work for the company and doesn't have the corresponding email. @moneyball thought we should have some suggestions to cache name -> (reusable) payment instructions mappings. Sadly, in some protocols (at least DNS) we have pretty tight timeouts for the data itself (eg the domain might expire tomorrow!), so it'd need to be a cache with a notice on changes rather than not doing further lookups. Can happen separately, but something to think about. |
|
The "B" symbol is a recipe for frustration, and setting up normies for failure.
Why limit the design space of what users can, and can't do?
That's fine - add some other way instead of an impossible to type "B" symbol. There's "human readable", and there should be, in my view, "human typable". These are the most basic human machine interface requirements. Normies will not memorize the special character shortcut for "B". We don't have "B" on keyboards today. Really, anything else on the keyboard, or perhaps even on the more difficult to access emoji keyboard reduces user friction. The designers I'm sure can come up with something better. Examples: BTC.name@domain |
To keep things a bit orderly, I'd like to ask for criticism of the proposal to be posted on the original proposal pull request. This new page in the guide is a reflection of the logic in that proposal. I'll also add this note to the PR description. Proposal criticism is not really something that can be resolved in comments here.
Totally. The page mentions "read, memorize, pronounce, understand, and type". |
- Added note about the DNS proposal still being in discussion - Updated general how it works image to use [prefix] instead of ₿ - Added note about PayNym directory not being open-source, and removed note about not using it due to centralization (should be clear from reading the text whether to use it or not)
assets/images/guide/how-it-works/human-readable-addresses/[email protected]
Outdated
Show resolved
Hide resolved
assets/images/guide/how-it-works/human-readable-addresses/setup.png
Outdated
Show resolved
Hide resolved
assets/images/guide/how-it-works/human-readable-addresses/[email protected]
Outdated
Show resolved
Hide resolved
|
Adding in some birds eye view ideas as well. More on the overarching structure of the content, less about the copy itself. Reading through the content it forms 4 larger chunks:
|
Co-authored-by: Stephen DeLorme <[email protected]>
- The proposal has been assigned a BIP number in the mean time, so I updated the URL - Clarified the use of the term custody as it relates to addresses - Removed an incorrect sentence about caching - Clarified that the proposal supports two formats, due to the optional ₿ prefix - Added note how single-use addresses can be used, as long as there's a rotation mechanism in place - Simplified note about responsibility to be more general, rather than mentioning legal and financial aspects. Lightened up that sentence generally - Added note about informing user of changed payment info at time of initiating a payment - Minor copy tweak in lightning address intro paragraph
|
I think I addressed all feedback. There are some points around the UI visuals that I will address in a follow-up in #1083. Please take a look and let me know how it looks know. Now that conference season is over, I'd like to wrap this PR up at a good pace. Thanks in advance. |
|
Strike now supports BOLT12 and DNS-based human readable addresses, along with Zeus, Phoenix and others (full list on bolt12.org). Posting this here, due to the editorial question about proposals with little or no adoption. More adoption over time speaks in favor of this content. |
Concur with Phoenix and Strike support, BIP-353, has decent adoption now. I'd go further and say Proton Wallet's "Bitcoin via email" is the biggest step thus far in the direction of human-readable addresses and should be added to this page as an example. |
|
Selfie Records extends BIP353 with additional data types. Another sign of adoption. Nonetheless by Synonym, so it sounds like @BitcoinErrorLog may have embraced it as well.
@yashrajd, this seems like an internal solution by a private company, and not an open standard, right? Not sure that really belongs on the page, unless there's more to their way of doing things. |
|
fwiw we are not currently pro- or anti-Selfie Records. The project was made by a motivated team member and we thought it was a good way to express capabilities DNS always had, to frame the design space clearly. All namespaces that want to enforce uniqueness (squatting) require a central authority, but that does not negate that some people find it useful and are willing to take that risk to solve what they consider to be problems, despite its censorability and difficulty for individuals to self-manage. Our actual love letter to decentralized identity, routing & payment coordination is PKARR (and Paykit, but R&D for that is paused til January) https://github.com/pubky/pkarr -- All of the public keys and endpoint records people want to be putting in DNS or relays or such should be put into Mainline DHT with PKARR. Because it is objectively the most decentralized and resilient network on the internet afaik. Projects like Iroh and Web5 are already using this setup, but Bitcoiners typically prefer bitcoin/LN-dedicated solutions. PKARR doesnt need blockchains or bitcoin keys. We still arent sure whether/how we might support Selfies in our own products, but we have a bookmark on approaching the "nickname" problem ideally/holistically someday if it seems needed. Sorry for shilling, but we wouldn't be building these things if we didn't think they were the best solutions :) |
|
The self-hosted/DIY path will add a lot of friction, and I don't think many people own personal domains. It may be something more suited to people running businesses/merchants/freelancers etc. Feedback from the Phoneix implementation suggests users are having a few issues https://x.com/methobit/status/1811496354549760022 |
|
What's the latest thinking on naming conventions for the BIP353 address and BOLT 12 offers? |
This update should address a lot of the feedback that has come up in the past months. - Revision of the address setup flow (which I thought I'd do in #1083, but here it is) - Added notes about user-facing naming (probs will end up in discussion, as naming tends to do) - Lots of small copy tweaks and additions - Added a table of contents at the top - Revision of diagrams for clarity - Change b12 to lno to match the updated convention - Updated backlink from the private key management intro page Would be amazing to get some fresh reviews on this. There may also have been other changes to the proposal or learnings from real-world implementations that should be considered.
|
I just pushed an update to this page with lots of changes to address various points of feedback from the past months.
Would be amazing to get some fresh reviews on this. There may also have been other changes to the proposal or learnings from real-world implementations that should be considered. Let me know if you are aware of anything. @ConorOkus I added a paragraph about naming, and some of the mock-ups also include specific choices of labels. I'll also point to a recent update I posted with some thoughts around naming, mostly to point out that naming is a highly contextual thing and cannot just be "solved globally" like 2 + 2. Please take a look and let me know what you think (about this page, not necessarily the linked post). Happy 2025 everyone 🕺💃🪩 |
Saving 4.2 of 6.8 MB.
There was a problem hiding this comment.
Lots of great additions over previous version of this PR, this is turning out to be a fantastic page with great explanations, mockups and advice!
This is not great protocol for privacy or self-sovereignty but pretty good from a usability angle, the evergreen tradeoff.
assets/images/guide/how-it-works/human-readable-addresses/mapping.png
Outdated
Show resolved
Hide resolved
|
|
||
| The additional configuration is important, to account for the diversity of features that different wallets offer. There are likely to be situations where the user wants to bundle payment information from several wallets. The best candidates for address types to use (due to their re-usability) are BOLT12 offers and silent payment addresses. Those are not broadly established, so a user may rely on different wallets for each type. | ||
|
|
||
| #### Sharing |
There was a problem hiding this comment.
This is great advice. It also fits very well with contacts, we should mention it here and link to the guidance on Contacts!
| height = 159 | ||
| %} | ||
|
|
||
| In a similar vein, [UMA](https://www.uma.me) is based on LNURL and Lightning Address, with modified functionality and the *"$<span class="-green">alice</span>@<span class="-blue">domain.com</span>"* address format. The *$* prefix was chosen to represent both fiat and crypto currencies. |
There was a problem hiding this comment.
I oppose mentioning this protocol since it amounts to promoting it. It supports shitcoinery, compliance garbage, is connected to threat actors, and is generally bad IMO. Perhaps somebody can articulate the criticism better...
|
|
||
| ## [Paynyms](http://paynym.is) | ||
|
|
||
| This approach relies on a single directory provider, which maps a human readable name with a [BIP-47](https://github.com/bitcoin/bips/blob/master/bip-0047.mediawiki) payment code. Having a single provider allows for the omission of the global part, in this case *"my.paynym.is/<span class="-green">username</span>"* and users can simply be referred to by their usernames. The directory code is not open-source. |
There was a problem hiding this comment.
Perhaps it is unwise to mention it if it's open-source? If we're mentioning non-open-source stuff, might be a good idea to mention Proton's "bitcoin via email" as well.
Co-authored-by: Max <[email protected]>
|
Thank you, @yashrajd. I accepted most of your tweaks and left a few comments. Whether to include UMA and Paynyms in this page is a good question. I'd be happy to remove them as I don't think they add very much value. What do others think? |
|
|
||
| ### How it works | ||
|
|
||
| Users create DNS entries with payment information, which can be one or more addresses of different formats, combined to a [BIP 21 URI](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki). Since address reuse is best avoided for privacy reasons, the included addresses should be reusable (like [silent payments]({{ '/guide/how-it-works/silent-payments/' | relative_url }}) and [BOLT12](https://bolt12.org/) offers). Single-use addresses can be used if needed, but a mechanism to rotate them should be in place. |
There was a problem hiding this comment.
How does a user create a DNS entry? What does that mean? Do they do that in their bitcoin wallet? Or is that something they do with the on their website domain via DNS settings? Some more detail would help me understand this.
There was a problem hiding this comment.
This manual setup is something they would do with their domain name registrar. Typically looks something like this. It's something for the more technical crowed that is comfortable owning and managing domains.
| - Services can potentially serve different payment information than specified | ||
|
|
||
| If the domain (website) where the payment information is stored, is not controlled by the user, we will refer to the address as "_managed_". To be clear, intermediaries cannot move funds at the user-provided address. They can only prevent payment information retrieval, or re-route funds by returning different payment information. | ||
|
|
There was a problem hiding this comment.
Providing this as an alternative to the "important note" earlier in the page, mentioned in this comment thread
| {% include tip/open.html color="blue" label="Tip" icon="info" %} | |
| Inform the user that there is a privacy & security trade-off involved in setting up a managed address. If the application supports a user-provided domain, explain that this method minimises the risk and help them set it up with detailed instructions. | |
| {% include tip/close.html %} | |
There was a problem hiding this comment.
Hm, so I am not sure it is the wallet's responsibility to provide instructions for setting things up in third-party domain registrars. Maybe a link out to a website with more info could be an option? This might be good to have either way for users to learn a bit more about the feature before they decide whether to use it.
But the way I thought about this is that the user can skip setup of the Bubble Wallet address and just enter their own human-readable address in their own profile in contacts. If this address is meant to be communicated verbally, then there's not a huge benefit of having it stored in your wallet (maybe so you don't forget it).
There was a problem hiding this comment.
Why not? That way they don't even have to support BIP-353 themselves, but if they do it serves as a cool feature. Since the TXT record on the domain have to contain all the payment info (bolt-12 and/or silent payments addresses etc.) potentially provided by the wallet using the BIP-21 format (see Phoenix instructions to BTCSessions), it seems prudent to have this. Having a third-party generate/provide these might be risky...what do you think?
There was a problem hiding this comment.
My point still stands:
Maybe a link out to a website with more info could be an option? This might be good to have either way for users to learn a bit more about the feature before they decide whether to use it.
|
Looking good @GBKS . I like rolling with bitcoin address. The address settings page is a little confusing to me though. We have Bubble address, Primary bitcoin address, Bubble wallet lightning address, Backup bitcoin address. I like [third party] bitcoin address (Bubble bitcoin address). Since we default to the wallet-provided BOLT 12 offer perhaps that can just be hidden, but in the event a user wants to change/edit that or add an sp address they can be referred to as "payment codes". Maybe primary and secondary payment codes? |
|
@ConorOkus I agree that the screen could become a little simpler. Take a look at the attached variation, which is a bit simpler and more like what a user would see the first time they enter this screen.
It's a bit like when you come to the address tab when making an online purchase and need to define both a billing address and a shipping address. Overall, I really think that we can (and should) avoid any additional terms (like payment code) with just the right tweaks to usability and copywriting. After all, if you include a new term, then you have to explain that one, too, and address it in all the other relevant screens. |
Replace regular bitcoin address with silent payments address, per Yashraj's feedback.
|
I can't think of many places other than hidden in settings where we would surface the "reusable payment codes"? Feels like we should only use the term "bitcoin address/bitcoin [third party] address" when referring to the actual human-readable name. The second screen with the bottom sheet "choose a bitcoin address" is referring to the payment codes and not the human-readable name. Given it's editable, people can copy/paste, send these out of band etc we still need a name for them. I'm not sure how much explaining it would need though, traditional banks don't seem to bother explaining the differences between "the long card number", "account number", "sort code", "security code", "verification number" etc |
Do you mean just in the context of this imaginary wallet or the whole ecosystem?
Yes, re-usable address, or just address. Nice and easy.
Those are all different types of information. What we're talking about in the context of this page is different variations of the same type. Human-readable address, bitcoin address, re-usable address, are all things I can enter into the same input field to make a payment. They just have some different properties. My general proposal is that we call it all "address" and use "modifiers" to highlight the most relevant property in the context (re-usable, lightning, etc). |
The naming conventions in the mock-ups seem to be throwing people off (which is not a first in the history of all the discussions we have had around the guide). This commit adds a special note above the first visual mock-up to explain the naming logic, and how other wallets can make different decisions. Mock-ups are tweaked accordingly.
|
Just pushed another update. @ConorOkus and I had a call last week about naming. The gist is that where you end up with naming has a lot to do with your starting assumptions. Conor's approach is pretty forward-looking, using the assumption that human-readable addresses will be the default (and therefore will be called bitcoin addresses), payment codes will be the term for the underlying re-usable address types (BOLT-12, BIP-47, BIP-352), and onchain bitcoin address will stand for P2TR, etc. It is pretty straightforward for us to individually come up with naming conventions that make sense to us. It's a lot harder and more squishy to reason about ecosystem-wide conventions, especially ones in the future. To navigate that in this PR, I created a special note that explains the naming rationale used in the mock-ups and states that wallets can come up with their own approaches. I hope that adds clarity, so a reader can understand the mock-ups for what they are meant to convey. Let me know if that makes sense. I appreciate all the input and conversations. |
This is something we've discussed for a few weeks in the this issue and the UX channel in Discord and turns the findings into a page.
Primary focus of the page is on the DNS-based payment information proposal, with an additional paragraph about Lightning Address and a small note about PayNyms.
The UI mock-ups are more directional than implementation-ready, which I think is fine. But we could flesh this out further in a revision at a later point.
I think there's more work to do in cross-linking this from all the right places. I updated a few spots, but there's probably more. The page is at a point where more review and public feedback would be helpful in identifying missing and incorrect bits.
If you have criticism of the DNS-based payment information proposal, please post it in that PR, and not here. This page is a reflection of the logic described in that PR.
🧐Check the preview🧐