Skip to content

Contact page updates to mention new protocols #1173

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.

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

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
28 changes: 16 additions & 12 deletions guide/daily-spending-wallet/contacts.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,10 +185,6 @@ imagesOwner:
layout = "full-width"
%}


# Contacts
{:.no_toc}

<!--

This page describes a UI system and user flows to handle contacts in a mobile bitcoin wallet.
Expand All @@ -201,12 +197,9 @@ https://www.figma.com/file/lf2Xyw2I2OXPsHiFQVQdiG/Daily-spending-wallet-prototyp

-->

Whether we’re sending emails, physical mail, or following someone on social media, we primarily think in terms of names and faces, and not the respective address or user ID.

Invoices, node IDs and other transaction endpoints in bitcoin and lightning are highly unintuitive. Abstracting them via a contact list can create a much smoother user experience. There are many [payment request formats]({{ '/guide/how-it-works/payment-request-formats/' | relative_url }}), each with unique properties and varying levels of maturity and adoption, requiring unique design solutions. This page uses the more approachable term "address", along with various UI techniques, to abstract these complexities for users.

Let's go over common user interactions around managing contacts. This will illustrate how such a feature could work, and helps explain the underlying design problems and decisions.

# Contacts
{:.no_toc}
---

<div class="glossary-toc" markdown="1">
Expand All @@ -216,13 +209,24 @@ Let's go over common user interactions around managing contacts. This will illus

---

Whether we’re sending emails, physical mail, or following someone on social media, we primarily think in terms of names and faces, and not the respective address or user ID.

Addresses, invoices, node IDs and other transaction endpoints in bitcoin and lightning are highly unintuitive. Abstracting them via a contact list can create a much smoother user experience. With the advent & growing popularity of reusable payment request formats such as [silent payments]({{ '/guide/how-it-works/silent-payments' | relative_url }}), [bolt-12]({{ '/guide/how-it-works/payment-request-formats/#offers' | relative_url }}) and [BIP-353]({{ '/guide/how-it-works/human-readable-addresses/#bip-353-dns-payment-instructions' | relative_url }}), bitcoin's interaction model itself can be centred around contacts. There are many [formats]({{ '/guide/how-it-works/payment-request-formats/' | relative_url }}), each with unique properties and varying levels of maturity and adoption, requiring unique design solutions. This page uses the more approachable term "address", along with various UI techniques, to abstract these complexities for users.
Copy link
Collaborator

Choose a reason for hiding this comment

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

bolt-12 is all lower case here and has a dash, but in the payment request formats it's displayed as BOLT 12. I think it's usually stylized like BOLT 12.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Not sure about the user of the ampersand in "advent & growing". It stuck out to me as odd. I would look into the suggestions on when to use that instead of and and see if it makes sense.

Copy link
Collaborator

@swedishfrenchpress swedishfrenchpress Jun 7, 2025

Choose a reason for hiding this comment

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

Some copilot feedback, feel free to use what you like or just discard it if you don't like the suggestions.

Suggestions for improvement:

  1. Replace "&" with "and" for formal writing.
  2. "Centred" is correct in British English, but "centered" is American English (choose based on your audience).
  3. Consider breaking up the third sentence, as it is quite long.
  4. Clarify "bitcoin's interaction model itself can be centred around contacts"—it can be reworded for clarity.
  5. The last sentence is a bit wordy. Consider making it more concise.

Revised version:
Addresses, invoices, node IDs, and other transaction endpoints in Bitcoin and Lightning are highly unintuitive. Abstracting them via a contact list can create a much smoother user experience. With the advent and growing popularity of reusable payment request formats—such as [silent payments]({{ '/guide/how-it-works/silent-payments' | relative_url }}), [BOLT-12]({{ '/guide/how-it-works/payment-request-formats/#offers' | relative_url }}), and [BIP-353]({{ '/guide/how-it-works/human-readable-addresses/#bip-353-dns-payment-instructions' | relative_url }})—Bitcoin’s user interactions are increasingly focused on contacts rather than technical addresses. There are many [payment request formats]({{ '/guide/how-it-works/payment-request-formats/' | relative_url }}), each with unique properties and varying levels of maturity and adoption, requiring specific design solutions. Throughout this page, we use the more approachable term “address” and various UI techniques to help abstract these complexities for users.


Let's go over common user interactions around managing contacts. This will illustrate how such a feature could work, and helps explain the underlying design problems and decisions.


### Adding a contact

The most basic interaction is that a user manually adds a contact by entering their name and an address. This is likely not the most common user flow, as most contacts will be created with incoming payment requests, as illustrated further below. But wallets should generally support manual options, as users may not be able to avoid them.

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

You may choose to require [user verification]({{ '/guide/daily-spending-wallet/security/#preventing-unwanted-access' | relative_url }}) (like PIN entry) when adding or updating contacts. This reduces the risk that contact information is tampered with and payments are sent to wrong addresses.
{% include tip/tip.html %}

Consider requiring [user verification]({{ '/guide/daily-spending-wallet/security/#preventing-unwanted-access' | relative_url }}) (like PIN entry) when adding or updating contacts. This reduces the risk that contact information is tampered with and payments are sent to wrong destination, especially with re-usable addresses.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I don’t agree with this tip. I actually think it’s a suboptimal UX practice. Introducing PIN verification for adding or updating contacts seems like a very odd convention and adds a lot of unnecessary friction.

If I understand the threat model correctly: someone gains access to your unlocked phone, opens your Bitcoin wallet, and attempts to do something malicious. In that scenario, the most likely threat is that they would simply send the funds to their own wallet. Requiring a PIN to confirm a fund transfer would be a useful security measure. But the idea that an attacker would instead go through the process of editing your contacts so that a future payment gets misdirected seems far less plausible.

I don’t think that attack vector justifies the added friction of requiring a PIN or user verification for adding or updating contacts. Labeling this as a “tip” feels misguided imo.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

hmm if the app entry itself is protected by a PIN or biometrics, this might not be needed at all...but yeah adding/edit contact is a one-time thing but I see your point about friction. pinging @GBKS

Copy link
Contributor

Choose a reason for hiding this comment

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

I agree with the criticism in the context of the daily spending wallet. This may be relevant in a treasury setup or so where there are huge amounts at stake. Editing a contact there may be the simpler route to cause mischief, than figuring out how to do a multi-sig approval.


{% include tip/close.html %}

### Contact editing

Expand All @@ -232,15 +236,15 @@ The contacts screen should offer various features for editing and organization.

### Importing an address

This scenario can be initiated by copying a lightning address to the clipboard, scanning a QR code, or tapping a payment link (see [payment entry points]({{ '/guide/daily-spending-wallet/sending/#payment-entry-points' | relative_url }})). An address is passed into the application and, where it's recognized and appropriate options are shown to the user. In the example below, the user adds the address as a new contact.
This scenario can be initiated by copying an address to the clipboard, scanning a QR code, or tapping a payment link (see [payment entry points]({{ '/guide/daily-spending-wallet/sending/#payment-entry-points' | relative_url }})). An address is passed into the application and, where it's recognized and appropriate options are shown to the user. In the example below, the user adds the address as a new contact.

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

### Importing a payment request

This sequence is similar to the one above. The difference is that a payment request was passed into the application, which contains different data and also includes a specific user action, and therefore requires different user flows. The one below shows how a user has scanned a payment request and assigns a contact to the payment.

Some payment request formats may include an address that can receive repeatedly. In this case, the address is added to the contact for future use. For [single use payment requests]({{ '/guide/daily-spending-wallet/requesting/' | relative_url }}), only the payment is linked.
Some payment request formats such as silent payment addresses and BIP-353 may include an address that can be repeatedly used without privacy compromises. In such cases, the address is added to the contact for future use. For [single use payment requests]({{ '/guide/daily-spending-wallet/requesting/' | relative_url }}), only the payment is linked.

Payment requests may also contain recipient names. These can be used to suggest the name for a new contact to the user. Names can be spoofed, so they should not be automatically assigned without user approval.

Expand Down