You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Initially, a wallet's contact list is empty. Importing them from the device can be made available.
file
modalImage
alt
caption
manual-add-first-contact-name
manual-add-first-contact-name-big
Screen asking the user to enter a name for a new contact
All a new contact needs is a name. Other information can be added later.
file
modalImage
alt
caption
manual-add-contact-no-addresses
manual-add-contact-no-addresses-big
A contact with no added information
New contacts can already be assigned to outgoing invoices. But since no address is assigned, no outgoing payments can be made yet.
file
modalImage
alt
caption
manual-add-contact-add-address
manual-add-contact-add-address-big
Screen asking the user to enter a bitcoin address
Users can manually enter addresses to add.
file
modalImage
alt
caption
manual-add-contact-add-address-details
manual-add-contact-add-address-details-big
Address entry screen with expanded information about supported addresses
Information about supported address formats should be readily available.
file
modalImage
alt
caption
manual-add-contact-add-address-valid
manual-add-contact-add-address-valid-big
Address entry screen with inline validation for a lightning address
Inline validation lets users know about if addresses are accepted.
file
modalImage
alt
caption
manual-add-contact-with-address
manual-add-contact-with-address-big
A contact with a lightning address assigned
A contact with a lightning address associated.
file
modalImage
alt
caption
manual-add-contact-add-address-valid-on-chain
manual-add-contact-add-address-valid-on-chain-big
Address entry screen with inline validation for an on-chain address
Particular properties of address types can be pointed out right away.
file
modalImage
alt
caption
manual-add-contact-with-on-chain-address
manual-add-contact-with-on-chain-address-big
A contact with an on-chain address assigned
A contact with an on-chain address attached. Once a payment is made to the address, it disappears from this list as it should only be used once for best privacy.
file
modalImage
alt
caption
manual-add-contact-add-address-xpub-toggle
manual-add-contact-add-address-xpub-toggle-big
Add address screen with a warning users need to accept
You may want to support certain address formats to give users flexibility, but ensure they understand the implications.
file
modalImage
alt
caption
manual-add-contact-add-address-xpub-error
manual-add-contact-add-address-xpub-error-big
Add address screen showing that an address can't be used
Alternatively, you may not want to support certain formats. Be conscious not to lock users out of making important payments when they need to.
file
modalImage
alt
caption
manual-add-contact-add-address-not-supported
manual-add-contact-add-address-not-supported-big
Add address screen indicating that an address format is not supported
Make sure to recognize unsupported formats with appropriate messaging.
file
modalImage
alt
caption
multi-address-contact
multi-address-contact-big
Contact screen with multiple transactions and addresses
Example of a contact with multiple transactions and addresses.
file
modalImage
alt
caption
multi-address-contact-options
multi-address-contact-options-big
Options for editing a contacts screen
Options for editing and organizing the contact.
file
modalImage
alt
caption
multi-address-contact-edit-labels
multi-address-contact-edit-labels-big
Contacts screen in edit mode
Edit mode allows for re-ordering, deleting and renaming addresses.
file
modalImage
alt
caption
multi-address-contact-address-detail
multi-address-contact-address-detail-big
Contact screen with an address details modal
Address details and options can be available on tap.
file
modalImage
alt
caption
lightning-address-input
lightning-address-input-big
Modal showing that a lightning address was detected on the clipboard
A modal is shown when an address has been imported via the clipboard or other methods.
file
modalImage
alt
caption
lightning-address-input-add-contact
lightning-address-input-add-contact-big
Screen for selecting a contact
The user has tapped "Add contact" and then taps "+" to add a new contact.
file
modalImage
alt
caption
lightning-address-input-new-contact
lightning-address-input-new-contact-big
Contact screen with the lightning address assigned
The new contact is created with the address associated.
file
modalImage
alt
caption
pay-invoice-with-details
pay-invoice-with-details-big
Invoice modal with rich details
This invoice includes rich data and the included address was automatically matched to an existing contact.
file
modalImage
alt
caption
pay-invoice
pay-invoice-big
Invoice modal with minimal payment details
This is a minimal invoice, no matching contact could be identified.
file
modalImage
alt
caption
sending-pick-contact
sending-pick-contact-big
Screen with a list of contacts to choose from
Tapping "Link contact" presents the user with a contact list modal.
file
modalImage
alt
caption
pay-invoice-with-contact
pay-invoice-with-contact-big
Invoice screen with a contact assigned
A basic invoice with an assigned contact.
file
modalImage
alt
caption
pay-invoice-contact-with-tx
pay-invoice-contact-with-tx-big
Contact with a single transaction assigned
A contact with an assigned transaction, but no re-usable addresses.
file
modalImage
alt
caption
pay-invoice-contact-with-tx-and-address
pay-invoice-contact-with-tx-and-address-big
Contact with a transaction and an address assigned
A contact with an assigned transaction and a re-usable address.
file
modalImage
alt
caption
sending-home
sending-home-big
Home screen with amount input
The user enters an amount and taps "Pay".
file
modalImage
alt
caption
sending-pick-contact
sending-pick-contact-big
Screen with a list of contacts to choose from
Next, the user is asked to choose a contact to send to.
file
modalImage
alt
caption
sending-review
sending-review-big
Invoice screen with a contact assigned
Final review of the payment before sending it.
file
modalImage
alt
caption
receive-home
receive-home-big
Home screen with amount input
The user enters an amount and taps "Request".
file
modalImage
alt
caption
receive-qr
receive-qr-big
Payment request screen
An invoice screen with minimal information.
file
modalImage
alt
caption
receive-qr-with-contact
receive-qr-with-contact-big
Payment request screen with a contact assigned
The same invoice with a contact assigned.
file
modalImage
alt
caption
activity
activity-big
Activity screen showing transactions with minimal information
By default, payments contain little to no contextual information.
file
modalImage
alt
caption
activity-annotated
activity-annotated-big
Activity screen showing transactions with assigned contacts
Assigning contacts to payments makes them much easier to understand and work with.
file
modalImage
alt
caption
activity-transaction
activity-transaction-big
Transaction details
Transaction detail screens should have convenient options to assign a contact.
file
modalImage
alt
caption
sending-pick-contact
sending-pick-contact-big
Screen with a list of contacts to choose from
The user picks a contact in a slide-up modal.
file
modalImage
alt
caption
activity-transaction-annotated
activity-transaction-annotated-big
Transaction details with assigned contact
A payment with an assigned contact.
file
modalImage
alt
caption
owner-list
owner-list-big
Contact list screen
The wallet owners contact card is shown at the top of the contact list.
file
modalImage
alt
caption
owner-entry
owner-entry-big
Contact card with internal and external addresses
The card lists addresses provided by the wallet, and allows the user to track external addresses for sharing.
{% include picture.html
image = "/assets/images/guide/daily-spending-wallet/contacts/contacts-header.jpg"
retina = "/assets/images/guide/daily-spending-wallet/contacts/contacts-header@2x.jpg"
mobile = "/assets/images/guide/daily-spending-wallet/contacts/contacts-header-mobile.jpg"
mobileRetina = "/assets/images/guide/daily-spending-wallet/contacts/contacts-header-mobile@2x.jpg"
alt-text = "Illustration of large contact cards"
width = 1600
height = 400
layout = "full-width"
%}
Contacts
{:.no_toc}
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.
* Table of contents
{:toc}
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.
Contact editing
The contacts screen should offer various features for editing and organization.
{% include image-gallery.html pages = page.imagesMultiAddressContact %}
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.
{% 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.
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.
{% include image-gallery.html pages = page.imagesPayInvoice %}
Note that automating matching of contacts to payment requests is a sensitive matter. If it cannot be based on unspoofable identifiers, then users should have to review and approve the match.
Sending from the home screen
Initiating a payment can be as simple as entering an amount and tapping a contact that has a re-usable address associated. Otherwise, an extra step is needed to manually enter a destination address.
{% include image-gallery.html pages = page.imagesHome %}
Adding a contact to an outgoing invoice
Contacts can also be assigned to invoices that will be paid by others.
{% include image-gallery.html pages = page.imagesReceive %}
Adding a contact to a completed payment
When browsing the [activity]({{ '/guide/daily-spending-wallet/activity/' | relative_url }}) screen, users may come across payments they want to assign contacts to. While applications should try to automatically make connections between payments and contacts by matching addresses, this is not possible oftentimes.
{% include image-gallery.html pages = page.imagesActivity %}
A contact card for the wallet owner
Most contact books include a special card for the user. It is typically shown at the top of the contact list, and used for quick sharing with others. In addition to listing any addresses your wallet provides, you might choose to let users enter external addresses from other wallets for convenience.
{% include image-gallery.html pages = page.imagesOwner %}
Using contacts in context
Contacts are closely intertwined with [sending]({{ '/guide/daily-spending-wallet/sending/' | relative_url }}), [requesting]({{ '/guide/daily-spending-wallet/requesting/' | relative_url }}), and the [activity]({{ '/guide/daily-spending-wallet/activity/' | relative_url }}) screen. When designing these user flows, pay close attention to how they connect. The less convenient it is for users to assign contacts, the less likely they are to use this feature and the higher the chance that they are exposed to the complexities of the various payment request formats.
Your application should also try to provide convenient backup for contacts, for example, via [automatic cloud backup]({{ '/guide/daily-spending-wallet/backup-and-recovery/cloud-backup/' | relative_url }}).
Supporting various payment request formats
Based on your use case, your application may choose to only support certain payment request formats. It should still recognize all formats, and provide the user with appropriate feedback. You may also choose to add warnings before permitting use of certain formats if there are privacy and security risks the user should be aware of.
Below are different examples of how you can communicate around the type of support your application provides for different formats.
{% include image-gallery.html pages = page.imagesSupportedFormats %}
The next section looks at [security considerations]({{ '/guide/daily-spending-wallet/privacy/' | relative_url }}) when designing a daily spending wallet.
