Contacts
People and apps the user pays more than once. The feature that stops them typing handles, and the one that warns them when a key changes.
Contacts look like a convenience and are mostly a security feature. A saved contact means no typing, and no typing means no near-miss handle, which is one of the commonest ways a payment goes to the wrong person.
They are also where identity lives in a consumer product. A handle resolves to a profile name, an avatar and a key, so saving one saves a relationship, not an address.
What a contact is
| Field | Where it comes from |
|---|---|
| Name | The profile the handle resolved to, or what the user typed over it |
| Avatar | The profile, or a generated fallback |
| Handle | What the user entered or scanned |
| Identity key | The resolution, and the thing the wallet actually checks |
| Last paid | The wallet's own records |
| Note | What the user wrote about them |
The identity key is the part that matters. A contact is a remembered key, with a human label on it.
Do
Let the user rename a contact to whatever they call that person. "Mum" beats the profile name the handle returned, and it is what they will search for.
Adding one
Three routes, and the best one is automatic:
After paying someone new. The information is already there, so offer to save it in the success state. This should be where most contacts come from.
By scanning. In person, a code carries the handle with nothing to mistype.
By typing a handle. The manual route. Resolve it and show the profile before saving, so the user is confirming a person rather than a string.
Do
Offer "save as contact" in the success state of a first payment. One tap at the moment the information is in front of the user beats a form they have to go and find.
Don't
Ask for a name before resolving the handle. The resolution usually supplies one, and asking first makes the user invent a label for someone the wallet is about to identify.
When the key changes
The single most valuable thing contacts do.
A contact whose identity key differs from the stored one is either a legitimate rotation (a new device, a recovered wallet) or an attempt to redirect payments to somebody else.
Do
Warn before any payment to a contact whose key has changed, and require acknowledgement: "Anna's wallet key has changed since you last paid her. If you weren't expecting this, check with her another way first."
Silently accepting the new key removes the whole benefit of having saved the old one.
Do
Record when the key last changed on the contact, so a user who is unsure can see whether this is the third change this month.
Passes
A contact may carry a Pass proving something about them: a business registration, a social account, a verified name. Passes are the difference between "someone who says they are the Corner Café" and the Corner Café. See Identity.
Do
Show a Pass as what it proves and who vouched for it, not as a generic tick. "Business name verified by Example Registry" is checkable; a blue badge is not.
Don't
Imply a Pass means the person is trustworthy. It means an issuer attested to one attribute, which is a much smaller claim.
Apps as contacts
An app the user has connected is a relationship with a key and a permission set, which is nearly the same object as a contact. Whether to put them in the same list is a real design question.
Recommendation
Keep them in separate lists but make them feel related. What a user does with a person is pay them; what they do with an app is review and revoke what it may do. Those are different enough that one combined list serves neither. See Security.
Searching and organising
Do
Search across the name, the handle and the note. Users search for how they think of someone, which is rarely the exact stored name.
Do
Order by recently paid rather than alphabetically. A wallet's contact list is short and heavily weighted to a handful of people.
Don't
Import the phone's address book by default. It is a large privacy ask for a feature most users do not need on day one, and it takes names out of the wallet's control.
Deleting one
Do
Name what is lost in the confirmation: the saved key, and therefore the warning if it changes. Payment history stays.
Don't
Remove payment history when a contact is deleted. The money moved; that is a fact about the user's finances, not about the contact.
Open questions
- How often do legitimate key changes happen, and does the warning survive people seeing it for ordinary rotations? Paying by handle asks the same question.
- Should apps and people share one search?
Related
- Sending
- Identity
- Paying by handle
- Recovery: a recovered wallet triggers this warning for others
- Security
Written from: BRC-29, BRC-42, BRC-52, BRC-169.
Checklist
The rules on this page, in a form you can work through.
13 rules