RFC-0011: Contacts API by filvecchiato · Pull Request #137 · paritytech/triangle-js-sdks

filvecchiato · 2026-04-17T16:04:54Z

RFC: Contacts API

Summary

Expose the user's contact list to products. Each contact pairs local metadata with a context-scoped map keyed by DotNS path (same as Ring VRF context). Two access tiers: own-context (default) and cross-context (privileged).

Checklist

Added docs/rfcs/0011-contacts-api.md with completed frontmatter
Filled all RFC sections (Summary, Motivation, Detailed Design, Drawbacks, Alternatives, Unresolved Questions)
Updated docs/rfcs/_index.md with a link to the new RFC
Added labels: rfc, proposal

Motivation

Products need to resolve human-readable identities to accounts. The host manages a contact list but does not expose it. This RFC defines host_contacts_get and host_contacts_subscribe with a two-tier permission model that preserves unlinkability across product contexts by default.

Imod7 · 2026-04-20T08:56:00Z

+| Permission | Tier | Grants |
+|-----------|------|--------|
+| `Contacts` | 1 | Own-context entries + local info |
+| `ContactsCrossContext` | 2 | Full entries across all contexts |


Should these permissions be added in RFC-002?

BigTava

The spec would benefit from an example. Also, there is no mention of privileged access from products like Browse.

BigTava · 2026-04-20T09:39:39Z

+
+## Motivation
+
+Products need to resolve human-readable identities to accounts. Without a contacts API, users must paste raw keys or scan QR codes for every interaction.


Can products resolve any account to a human-readable identity? Or just the accounts available in the contacts?

BigTava · 2026-04-20T09:41:11Z

+
+The host already manages a contact list. Exposing it:
+
+1. **Removes friction** — products can show names instead of raw addresses.


How is this associated with the user very personal contacts list? Does it apply for any raw address?

Introduce host_contacts_get and host_contacts_subscribe methods. Contacts are scoped by DotNS path (same as Ring VRF context) with two access tiers: own-context (default) and cross-context (privileged).

- Change ContactContext from ProductAccountId to DotNsIdentifier - Clarify this is the user's address book, not a global resolver - Specify Contacts/ContactsCrossContext as DevicePermission variants - Add concrete tier 1 example - Address host-privileged product access (Browse)

DerivationIndex is needed — a product may have multiple derived accounts under the same DotNsIdentifier.

BigTava

Left some comments. Looks good for a first draft. In general, I think we are missing a bit more detail over how this fits the current Account model and chats list.

BigTava · 2026-04-27T14:21:13Z

+|                 |                                                                 |
+| --------------- | --------------------------------------------------------------- |
+| **Start Date**  | 2026-04-17                                                      |
+| **Description** | Expose the user's contact list to products via Host API         |


NIT: via TruAPI no?

BigTava · 2026-04-27T14:44:37Z

+
+## Motivation
+
+Products need to resolve human-readable identities to accounts. The host manages an address book but does not expose it. Without this API, users must paste raw keys or scan QR codes for every interaction.


I don't think this is trying to solve "human-readable identities", but letting products leverage the user' social circle to provide useful features. I think of it as Spotify connecting to your Facebook friends, or WhatsApp reading your phone's contact list.

BigTava · 2026-04-27T14:47:38Z

+
+Exposing the contact list:
+
+1. **Removes friction** — products show names instead of raw addresses.


Yes, but not of all raw addresses and names, but very specific to the host list of contacts.

BigTava · 2026-04-27T14:49:26Z

+Exposing the contact list:
+
+1. **Removes friction** — products show names instead of raw addresses.
+2. **Enables cross-product identity** — multiple products resolve the same contact within their respective contexts.


Previously we state "cross-context access is a separate privilege". I think what we are trying to unlock is "per-product views of a shared local contact".

BigTava · 2026-04-27T14:50:37Z

+
+1. **Removes friction** — products show names instead of raw addresses.
+2. **Enables cross-product identity** — multiple products resolve the same contact within their respective contexts.
+3. **Preserves user control** — the host gates access and filters responses to the requesting product's scope.


Not exclusive of this RFC. Too generic point.

BigTava · 2026-04-27T15:33:54Z

+  Unknown(GenericErr)
+}
+
+fn host_contacts_get() -> Result<Vec<Contact>, ContactsErr>;


Shouldn't this have an argument DotNS identifier. If the identifier matches the current app i.e. user is in host-playground.dot and the app calls host_contacts_get("host-playground") then it falls into tier 1 access, while if host_contacts_get("browse.dot") it falls into the tier 2 access?

BigTava · 2026-04-27T15:49:25Z

+
+### Privacy-Preserving Display
+
+The host can render a contact picker in a privileged overlay using full contact data, returning only the selected contact's own-context entry to the product. This lets users see rich details without the product receiving cross-context data. The overlay mechanism is host-specific and out of scope.


I guess this would be an implementation detail related to how the permission modal would render in the UI, no?

BigTava · 2026-04-27T15:51:15Z

+- **Full-list delivery.** No per-contact queries. The overlay pattern partially addresses this for picker UIs.
+- **Read-only.** Products cannot add contacts. Deferred intentionally.
+
+## Alternatives


Very hard to depict what these alternatives were.

BigTava · 2026-04-27T15:52:57Z

+3. **Contact mutation.** Write access deferred to a follow-up RFC.
+4. **Filtered subscriptions.** Should tier 2 `host_contacts_subscribe` accept a context filter?
+5. **Overlay specification.** The exact overlay mechanism needs its own spec.
+6. **Pagination.** May be needed for large contact lists.


Would Pagination be a problem in terms of query size?

BigTava · 2026-04-27T15:59:00Z

+
+Breaks unlinkability — any product could correlate aliases across all contexts.
+
+## Unresolved Questions


I would add "how does a contact end up in the address book to begin with?".

filvecchiato · 2026-05-07T13:55:39Z

closing in favour of paritytech/truapi#17

filvecchiato added rfc Request For Change proposal labels Apr 17, 2026

filvecchiato requested review from TorstenStueber and pgherveou April 17, 2026 16:05

TarikGul self-requested a review April 17, 2026 19:19

Imod7 reviewed Apr 20, 2026

View reviewed changes

BigTava reviewed Apr 20, 2026

View reviewed changes

filvecchiato added 2 commits April 20, 2026 16:56

docs: RFC 0011 — Contacts API

7709867

Introduce host_contacts_get and host_contacts_subscribe methods. Contacts are scoped by DotNS path (same as Ring VRF context) with two access tiers: own-context (default) and cross-context (privileged).

filvecchiato force-pushed the rfc/0011-contacts-api branch from bb78e6a to 4701598 Compare April 20, 2026 14:57

docs: revert ContactContext back to ProductAccountId

8580684

DerivationIndex is needed — a product may have multiple derived accounts under the same DotNsIdentifier.

filvecchiato mentioned this pull request Apr 23, 2026

RFC: Contacts API paritytech/truapi#17

Draft

4 tasks

BigTava reviewed Apr 27, 2026

View reviewed changes

filvecchiato closed this May 7, 2026


		## Motivation

		Products need to resolve human-readable identities to accounts. Without a contacts API, users must paste raw keys or scan QR codes for every interaction.


		The host already manages a contact list. Exposing it:

		1. Removes friction — products can show names instead of raw addresses.


		Exposing the contact list:

		1. Removes friction — products show names instead of raw addresses.


		### Privacy-Preserving Display

		The host can render a contact picker in a privileged overlay using full contact data, returning only the selected contact's own-context entry to the product. This lets users see rich details without the product receiving cross-context data. The overlay mechanism is host-specific and out of scope.


		Breaks unlinkability — any product could correlate aliases across all contexts.

		## Unresolved Questions

Uh oh!

Conversation

filvecchiato commented Apr 17, 2026

RFC: Contacts API

Summary

Checklist

Motivation

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BigTava left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BigTava left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

filvecchiato commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants