diff --git a/_sass/minima/_article.scss b/_sass/minima/_article.scss index 0a46be9b1..fd7fa70d6 100644 --- a/_sass/minima/_article.scss +++ b/_sass/minima/_article.scss @@ -224,6 +224,16 @@ article.guide { } } + span { + &.-blue { + color: $blue; + } + + &.-green { + color: $green; + } + } + > iframe { display: block; } diff --git a/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile.png new file mode 100644 index 000000000..d25c53dfa Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile@2x.png new file mode 100644 index 000000000..c98d42d36 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/clipboard.png b/assets/images/guide/how-it-works/human-readable-addresses/clipboard.png new file mode 100644 index 000000000..93eca5310 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/clipboard.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/clipboard@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/clipboard@2x.png new file mode 100644 index 000000000..d79bc3135 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/clipboard@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile.jpg b/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile.jpg new file mode 100644 index 000000000..c2e49d093 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile@2x.jpg b/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile@2x.jpg new file mode 100644 index 000000000..745854a59 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile@2x.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/contact-card.jpg b/assets/images/guide/how-it-works/human-readable-addresses/contact-card.jpg new file mode 100644 index 000000000..9ca503911 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/contact-card.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/contact-card@2x.jpg b/assets/images/guide/how-it-works/human-readable-addresses/contact-card@2x.jpg new file mode 100644 index 000000000..6cf7f5424 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/contact-card@2x.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile.png new file mode 100644 index 000000000..67f3bcdea Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile@2x.png new file mode 100644 index 000000000..3513c4fbe Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries.png new file mode 100644 index 000000000..8fc91d2ae Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries@2x.png new file mode 100644 index 000000000..59443e827 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile.png new file mode 100644 index 000000000..9865209b9 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile@2x.png new file mode 100644 index 000000000..a41d16e33 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping.png new file mode 100644 index 000000000..f22162f52 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping@2x.png new file mode 100644 index 000000000..1823d8bd6 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile.png new file mode 100644 index 000000000..87aa2b70a Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile@2x.png new file mode 100644 index 000000000..3eff237af Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust.png new file mode 100644 index 000000000..b4cf8d3fc Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust@2x.png new file mode 100644 index 000000000..5a1434078 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/education-mobile.jpg b/assets/images/guide/how-it-works/human-readable-addresses/education-mobile.jpg new file mode 100644 index 000000000..8b7e496cd Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/education-mobile.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/education-mobile@2x.jpg b/assets/images/guide/how-it-works/human-readable-addresses/education-mobile@2x.jpg new file mode 100644 index 000000000..2213ab2b5 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/education-mobile@2x.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/education.jpg b/assets/images/guide/how-it-works/human-readable-addresses/education.jpg new file mode 100644 index 000000000..10bf2a36d Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/education.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/education@2x.jpg b/assets/images/guide/how-it-works/human-readable-addresses/education@2x.jpg new file mode 100644 index 000000000..216e6d29b Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/education@2x.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile.jpg b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile.jpg new file mode 100644 index 000000000..c6bf3149b Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile@2x.jpg b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile@2x.jpg new file mode 100644 index 000000000..7d96bf247 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile@2x.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-preview.jpg b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-preview.jpg new file mode 100644 index 000000000..2fb73d7cf Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-preview.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses.jpg b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses.jpg new file mode 100644 index 000000000..7e054e889 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses@2x.jpg b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses@2x.jpg new file mode 100644 index 000000000..e43f7ab48 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses@2x.jpg differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/input-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/input-mobile.png new file mode 100644 index 000000000..8c840c91c Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/input-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/input-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/input-mobile@2x.png new file mode 100644 index 000000000..86846cfc9 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/input-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/input.png b/assets/images/guide/how-it-works/human-readable-addresses/input.png new file mode 100644 index 000000000..6802ac9a6 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/input.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/input@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/input@2x.png new file mode 100644 index 000000000..27a9a4b33 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/input@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile.png new file mode 100644 index 000000000..d31e9caa9 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile@2x.png new file mode 100644 index 000000000..d70306f26 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries.png new file mode 100644 index 000000000..83af45a92 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries@2x.png new file mode 100644 index 000000000..59c3cec17 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile.png new file mode 100644 index 000000000..6ff6bbe04 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile@2x.png new file mode 100644 index 000000000..0e5b16c2e Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping.png new file mode 100644 index 000000000..d1e8344c8 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping@2x.png new file mode 100644 index 000000000..df89181b9 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile.png new file mode 100644 index 000000000..2eb2d21d9 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile@2x.png new file mode 100644 index 000000000..a67169bbf Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/mapping.png b/assets/images/guide/how-it-works/human-readable-addresses/mapping.png new file mode 100644 index 000000000..c6eff8fdb Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/mapping.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/mapping@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/mapping@2x.png new file mode 100644 index 000000000..5408fca2d Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/mapping@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/setup-big.png b/assets/images/guide/how-it-works/human-readable-addresses/setup-big.png new file mode 100644 index 000000000..568e4b82f Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/setup-big.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile.png new file mode 100644 index 000000000..26f8536bc Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile@2x.png new file mode 100644 index 000000000..cab62f206 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/setup.png b/assets/images/guide/how-it-works/human-readable-addresses/setup.png new file mode 100644 index 000000000..5f6581f9c Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/setup.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/setup@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/setup@2x.png new file mode 100644 index 000000000..71dd0505e Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/setup@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/update-mobile.png b/assets/images/guide/how-it-works/human-readable-addresses/update-mobile.png new file mode 100644 index 000000000..786ad6ce0 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/update-mobile.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/update-mobile@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/update-mobile@2x.png new file mode 100644 index 000000000..890d00f56 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/update-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/update.png b/assets/images/guide/how-it-works/human-readable-addresses/update.png new file mode 100644 index 000000000..895b7dab8 Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/update.png differ diff --git a/assets/images/guide/how-it-works/human-readable-addresses/update@2x.png b/assets/images/guide/how-it-works/human-readable-addresses/update@2x.png new file mode 100644 index 000000000..8d1ebd04f Binary files /dev/null and b/assets/images/guide/how-it-works/human-readable-addresses/update@2x.png differ diff --git a/guide/how-it-works/human-readable-addresses.md b/guide/how-it-works/human-readable-addresses.md new file mode 100644 index 000000000..1d54626d4 --- /dev/null +++ b/guide/how-it-works/human-readable-addresses.md @@ -0,0 +1,283 @@ +--- +layout: guide +title: Human readable addresses +description: Easy-to-use bitcoin addresses via DNS payment instructions and the lightning address protocol. +nav_order: 1 +parent: Payment request formats +grand_parent: How it works +permalink: /guide/how-it-works/human-readable-addresses/ +main_classes: -no-top-padding +image: /assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-preview.jpg + +--- + + + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses.jpg" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses@2x.jpg" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile.jpg" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/human-readable-addresses-mobile@2x.jpg" + alt-text = "The word bitcoin address written in binary and plain text" + width = 1600 + height = 400 + layout = "full-width" +%} + +# Human readable addresses + +[Bitcoin addresses]({{'/guide/glossary/address/' | relative_url}}) and [payment requests]({{'/guide/how-it-works/payment-request-formats/' | relative_url}}) are long and cryptic, practically impossible to read, memorize, pronounce, understand, or type. We are used to being able to communicate our social media handles and email addresses easily. That expectation has also extended to transacting value with neo-banking and payment applications. There have been multiple attempts at making human-readable addresses a reality in bitcoin. + +The benefits to the user experience include: + +- Familiarity: A format that feels more human and familiar to users +- Ease of sharing: A format that is easier to remember and recall and share in a social setting + +Ideally human-readable addresses should only be used for direct communication. Whenever payment information is communicated digitally (copy & paste, links, QR codes, messaging, etc), cryptographic formats should be used for the best security and privacy. + +On this page, we focus primarily on the [BIP353 for DNS Payment Instructions](https://github.com/bitcoin/bips/blob/master/bip-0353.mediawiki), with some information about [Lightning Addresses](https://lightningaddress.com). They pursue similar goals, but in very different ways. + +### The basic idea + +Bitcoin transactions always rely on long and cryptic addresses and payment formats, consisting of numbers and letters. Human-readable addresses are a means for wallets to retrieve these regular addresses. In other words they act as pointers. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/mapping.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/mapping@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/mapping-mobile@2x.png" + alt-text = "Diagram showing an email address pointing to a bitcoin address" + width = 800 + height = 141 +%} + +There are various technical approaches to resolve addresses. We’ll learn more about the different benefits and drawbacks below. + +### Security & privacy + +Every approach requires at least one intermediary that is being contacted to serve the payment information. + +This brings up important questions around privacy and security. Intermediaries can potentially serve up different payment information than a user specified. Or they can track requests and metadata to build profiles of users and user behavior. If these intermediate hops are not controlled by the user, the address should be considered custodial. To be clear, intermediaries cannot move funds at the user-provided address. They can only re-route incoming funds or prevent payment information retrieval. + +### Address format basics + +From email and social media, we are familiar with addresses consisting of a local and a global part. The local part is typically a username, and the global part identifies a domain or service. + +- *“My email is alice@domain.com.”* +- *“I am alice on [social media service].”* +- *“Pay me at ₿alice@domain.com.”* + +For social media, users know to navigate to the respective website or app and look up the username there. Applications rely on domains (via the [Domain Name System](https://en.wikipedia.org/wiki/Domain_Name_System), or DNS) to resolve the global part. In physical addresses, we have more hierarchical parts - country, state, city, street, house number and apartment. It is a familiar system. + +## BIP353: DNS Payment Instructions + +This [proposal](https://github.com/bitcoin/bips/blob/master/bip-0353.mediawiki) only relies on the Domain Name System (DNS) to retrieve payment information. It is a decentralized hierarchical naming system used to translate human-friendly domain names (like *www.example.com*) into IP addresses (like *192.0.2.1*) that computers use to identify each other on the network. Anytime we type in a domain into a browser, we rely on this system. + +{% include tip/open.html color="blue" label="Note" icon="info" %} + +This is a new proposal. It is still being discussed, and not widely implemented. + +{% include tip/close.html %} + +### Address format + +This proposal uses the formats *“username@domain.com”* and *“₿username@domain.com”*. This is similar to the email address format, which makes it familiar and easy to use. The *₿* prefix is an important addition for display purposes, to make it distinctly a bitcoin payment address. This provides clarity and trust to users, which is important when it comes to financial transactions. + +### 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 only be static payment codes (like [silent payment codes](https://silentpayments.xyz/) and [BOLT12](https://bolt12.org/) offers). Single-use addresses can be used if needed, but a mechanism to rotate them should be in place. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-mapping-mobile@2x.png" + alt-text = "Diagram showing how a bitcoin address is resolved to a payment URL" + width = 800 + height = 221 +%} + +Wallets look up the payment information when first exposed to a human-readable address. Then they rely on the retrieved information to initiate transactions. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-intermediaries-mobile@2x.png" + alt-text = "Diagram showing how the involved parties interact with each other" + width = 800 + height = 357 +%} + +### Trust + +Setting this up requires a user to own a domain, and trust the domain provider and DNS system to truthfully communicate their payment information. If the user does not own the domain but uses a third-party service instead, then another intermediary is in play. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/dns-payment-instructions-trust-mobile@2x.png" + alt-text = "Diagram showing who the user trusts when owning a domain, or hosting their address with a third party" + width = 800 + height = 383 +%} + +### Design patterns + +#### Educating users + +Framing the correct use of the address should be done right away and as early in the user flow as possible. This allows them to make informed decisions as to how and when to use it. Users should be informed that: + +- The purpose of the address is for verbally sharing their bitcoin address in a social setting. +- That the address is public, which carries a clear directional understanding about privacy. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/education.jpg" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/education@2x.jpg" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/education-mobile.jpg" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/education-mobile@2x.jpg" + alt-text = "UI mock-up of a feature intro screen presenting bitcoin addresses for verbal communication" + width = 800 + height = 608 +%} + +#### Setup + +Hosting human-readable addresses carries a responsibility, and non-custodial wallets that don't provide additional services outside of the software may not want to offer this feature. However, they should still make it easy to copy payment information for setting up addresses on domains owned by the user or a third party of the user's choice. + +It is important to provide users with a simple setup experience for human-readable addresses. They are likely to use them for a long time, and need to be able to trust that everything is set up correctly. + +Scenarios to consider: + +- The user owns a domain they would like to use with the payment information the wallet provides +- The user does not have a domain, but the wallet developer offers DNS entries to users at a given domain + +There may also be a situation where the user wants to bundle payment information from several wallets. The best candidates for address types to use are BOLT12 offers and silent payment addresses. Those are not broadly established, so a user may rely on different wallets for each type. + +Below is a conceptual setup flow for setting up a DNS-based payment address both with a user-owned domain and a wallet-provided domain. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/setup.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/setup@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/setup-mobile@2x.png" + modalImage = "/assets/images/guide/how-it-works/human-readable-addresses/setup-big.png" + alt-text = "6 screen user flow showing setup of a bitcoin address" + width = 1200 + height = 830 + layout = "full-width" +%} + +Wallets should also verify resolved payment information. For example, a user who tries to use a regular onchain address can be informed that is a bad practice due to the privacy implications. + +#### Sharing + +Users should have quick access to their payment addresses. However, since they should not be shared electronically, there should not be options to copy or share them. Instead, users should be able to directly share the payment information that is connected to their public addresses. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/contact-card.jpg" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/contact-card@2x.jpg" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile.jpg" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/contact-card-mobile@2x.jpg" + alt-text = "A visual contact card showing a bitcoin address and a separate button for sharing payment information" + width = 800 + height = 405 +%} + +#### Entering + +Input fields for addresses typically need to accommodate various address types. Whenever possible, addresses should be pre-filled from the clipboard, contacts, or previously clicked links. This is more convenient for users and reduces manual input errors. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/clipboard.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/clipboard@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/clipboard-mobile@2x.png" + alt-text = "A modal notifying the user of a bitcoin address on their clipboard and offering appropriate options" + width = 800 + height = 334 +%} + +While it is unlikely that users will type in the more complex address types, an address input field should not be restricted to only accepting a single address type. In this example, a single input field is capable of accepting a variety of different formats, and it provides feedback to the user about what they have entered. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/input.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/input@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/input-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/input-mobile@2x.png" + alt-text = "Several states of an address input field showing how a user might enter bitcoin addresses" + width = 800 + height = 452 +%} + +#### Keeping users informed + +The payment information associated with addresses in contacts may change or even become invalid. Wallets should ensure to inform the user of updates to review or act on. This is best done at the time the user wants to initiate a payment to a contact. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/update.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/update@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/update-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/update-mobile@2x.png" + alt-text = "Two modals notifying the user of changed and disabled bitcoin addresses" + width = 800 + height = 277 +%} + +## Lightning Address + +Compared to DNS Payment Instructions, [Lightning Addresses](http://lightningaddress.com) are focused on the lightning network only. They bring another intermediary into play, and allow for much more dynamic functionality. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-mapping-mobile@2x.png" + alt-text = "Diagram showing how a lightning address is transformed to a URL" + width = 800 + height = 157 +%} + +### How it works + +Lightning addresses look like traditional emails. Under the hood, a wallet that uses a lightning address reformats it to a URL. It then looks for information about a [LNURL](https://github.com/lnurl/luds) web-server at that location (more on that [here](https://github.com/lnurl/luds/blob/luds/16.md)). That server handles the communication with the lightning node and passes messages back and forth. This allows for complex interactions (like authentication and withdrawals), but also requires trusting the web server. + +{% include picture.html + image = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries.png" + retina = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries@2x.png" + mobile = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/human-readable-addresses/lightning-address-intermediaries-mobile@2x.png" + alt-text = "Diagram showing the parties involved in communicating payment information" + width = 800 + height = 165 +%} + +In a similar vein, [UMA](https://www.uma.me) is based on LNURL and Lightning Address, with modified functionality and the *"$alice@domain.com"* address format. The *$* prefix was chosen to represent both fiat and crypto currencies. + +## [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/username"* and users can simply be referred to by their usernames. The directory code is not open-source. + +--- + +Next, we will learn about the different [private key schemes]({{ '/guide/how-it-works/private-key-management/introduction/' | relative_url }}) used to secure your bitcoin. + +{% include next-previous.html + previousUrl = "/guide/how-it-works/payment-request-formats/" + previousName = "Payment request formats" + nextUrl = "/guide/how-it-works/private-key-management/introduction/" + nextName = "Private key management" +%} diff --git a/guide/how-it-works/introduction.md b/guide/how-it-works/introduction.md index c10828c0c..1334f7a9b 100644 --- a/guide/how-it-works/introduction.md +++ b/guide/how-it-works/introduction.md @@ -58,7 +58,7 @@ Learn about how nodes help keep bitcoin decentralized and enforce its rules. ### [Payment request formats]({{ '/guide/how-it-works/payment-request-formats/' | relative_url }}) -Learn about the different types of payment request formats, from a standard on-chain address to a lightning address, that exist in bitcoin. +Learn about the different formats for payment information that exist in bitcoin, from standard on-chain to lightning, and [human readable addresses]({{ '/guide/how-it-works/human-readable-addresses/' | relative_url }}). --- diff --git a/guide/how-it-works/payment-request-formats.md b/guide/how-it-works/payment-request-formats.md index 5d6d788b0..0936d90f0 100644 --- a/guide/how-it-works/payment-request-formats.md +++ b/guide/how-it-works/payment-request-formats.md @@ -4,6 +4,7 @@ title: Payment request formats description: An introduction to the different bitcoin payment request formats. nav_order: 6 parent: How it works +has_children: true permalink: /guide/how-it-works/payment-request-formats/ redirect_from: - /guide/payments/send/payment-request-formats/ @@ -138,7 +139,7 @@ LNURL-Pay allows senders to dynamically request an invoice from the receiver to ##### Lightning address -[Lightning addresses](https://lightningaddress.com) build on top of LNURL-Pay and give users a more human-readable payment address. They use the very familiar email format (user@bitcoin.design) to request payments. +[Lightning addresses](https://lightningaddress.com) build on top of LNURL-Pay and give users a more [human readable payment address]({{ '/guide/how-it-works/human-readable-addresses/' | relative_url }}). They use the very familiar email format (_username@domain.com_) to request payments. ##### Withdraw @@ -235,7 +236,7 @@ Payment codes have been popularised in wallets such as [Samourai](https://samour A downside to payment codes is that they require an additional on-chain transaction each time two users want to connect and use them. [Silent payments](https://gist.github.com/RubenSomsen/c43b79517e7cb701ebf77eec6dbb46b8?permalink_comment_id=4113680) are a new experimental proposal that prevents the need for this additional on-chain transaction at the cost of extra bandwidth for receivers. -Some wallets use what is called a [PayNym](https://paynym.is/) to abstract payment codes into more human readable payment request formats. However, this is not standardized, directories are not open-source, and currently Samourai is the only operator running a directory. +Static payment codes are great for use with [DNS-based human readable addresses]({{ '/guide/how-it-works/human-readable-addresses/#dns-payment-instructions' | relative_url }}). @@ -262,11 +263,11 @@ You can learn more about unified payment requests [here](https://bitcoinqr.dev/) --- -Next, we will learn about the different [private key schemes]({{ '/guide/how-it-works/private-key-management/introduction/' | relative_url }}) used to secure your bitcoin. +As you noticed, these formats are impossible to memorize and pronounce. That is what [human readable addresses]({{ '/guide/how-it-works/human-readable-addresses/' | relative_url }}) aim to solve. {% include next-previous.html previousUrl = "/guide/how-it-works/nodes/" previousName = "Nodes" - nextUrl = "/guide/how-it-works/private-key-management/introduction/" - nextName = "Private key management" + nextUrl = "/guide/how-it-works/human-readable-addresses/" + nextName = "Human readable addresses" %}