> For the complete documentation index, see [llms.txt](https://bsv.brc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bsv.brc.dev/payments/0235.md).

# Paymail Public Profile Lookup

Deggen (<deggen@kschw.com>)

## Abstract

We specify two Paymail capabilities that bind a human-readable `handle@domain` to an identity key, in both directions. The forward capability, **public profile lookup** (`0ace65da5987`), takes a full or partial handle and returns matching public profiles. The reverse capability, **public profile reverse lookup** (`43dcf83ddc5f`), takes an identity key and returns its profile. Every profile is a self-signed [BRC-52](https://bsv.brc.dev/peer-to-peer/0052.md) certificate in which `subject` and `certifier` are both the holder's identity key, so a client verifies what the host returns rather than trusting it. The identity key obtained is the recipient for [BRC-29](https://bsv.brc.dev/payments/0029.md) payments; the reverse capability lets interfaces show `alice@example.com` where they would otherwise show 66 hex characters.

Discovery is unchanged from Paymail: DNS SRV `_bsvalias._tcp` for the host, then the `/.well-known/bsvalias` capability document. A host may publish these two capabilities and nothing else.

## Motivation

Paymail ([BRC-28](https://bsv.brc.dev/payments/0028.md)) solved addressing with `user@domain`, resolved at the domain, and that deployment model is still the right one: operators already run DNS, SRV records and `.well-known/bsvalias`, and users already recognize the format. What has aged is what the address resolves to. Legacy capabilities hand out a public key for a script or a payment destination per request; identity-based wallets ([BRC-100](https://bsv.brc.dev/wallet/0100.md)) want one thing instead: the recipient's **identity key**, from which [BRC-42](https://bsv.brc.dev/key-derivation/0042.md) derivation and BRC-29 payment take over without further help from the host.

Two problems follow from asking a host for an identity key:

1. **Trust.** A host that answers "this handle is this key" in plain JSON can substitute its own key. Here the host returns a certificate the holder signed, naming the handle and domain, so the host cannot forge a profile or move one to another handle. It still decides which key holds a handle; that residue is inherent to any domain-scoped name and is stated under Security Considerations.
2. **Hex in interfaces.** Wallets that receive a BRC-29 payment, or list contacts by key, have no name to show. A reverse lookup at the payer's domain recovers one.

These capabilities deliberately need none of the legacy ones. A modern wallet operator should be able to serve `.well-known/bsvalias` with exactly these two entries, and a client should be able to resolve against such a host.

### Relation to BRC-169

[BRC-169](https://bsv.brc.dev/peer-to-peer/0169.md) specifies a broader addressing system, `@handle@ecosystem`, discovered through a [BRC-68](https://bsv.brc.dev/peer-to-peer/0068.md) manifest, with handles attested by the ecosystem's certifier key, on-chain revocation, messaging, reachability policy and delegation. This document is narrower and differs in two ways:

|                       | BRC-169                                   | BRC-235                                                   |
| --------------------- | ----------------------------------------- | --------------------------------------------------------- |
| Discovery             | BRC-68 `manifest.json`, `metanet.handles` | Paymail SRV + `.well-known/bsvalias` capability (BRFC id) |
| Who signs the binding | Ecosystem host (`certifier` = host key)   | The holder (`subject` = `certifier`)                      |
| Revocation            | Spend of a certifier outpoint             | None on chain; replace or tombstone                       |
| Address syntax        | `@handle@ecosystem`                       | `handle@domain`                                           |

A host MAY implement both. The certificate types differ, so a client never mistakes one for the other.

## Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

### 1. Terminology

* **Handle**: the local part of a paymail, unique within its domain.
* **Paymail**: `handle@domain`, always lowercase in a profile.
* **Host**: the HTTPS origin that serves a domain's capabilities, found by discovery (section 3).
* **Profile**: a profile certificate (section 5) that passed client verification (section 8).
* **Tombstone**: a profile carrying `released: "true"`; it announces that the holder gave the handle up.

### 2. Capability identifiers

Both identifiers are BRFC ids: the first 12 hex characters of the byte-reversed double SHA-256 of `title + author + version`, each trimmed, as in the existing Paymail BRFC scheme.

```yaml
brfcid: 0ace65da5987
title: public profile lookup
author: Deggen
version: v1.0.0
```

```yaml
brfcid: 43dcf83ddc5f
title: public profile reverse lookup
author: Deggen
version: v1.0.0
```

The leading `v` in the version is part of the hashed input; without it the forward id would be `b78c0cbacf47`.

### 3. Discovery

A client resolving `domain`:

1. MUST query the SRV record `_bsvalias._tcp.<domain>`. If the answer names a target other than `domain` itself, the client MUST require that the answer is DNSSEC-authenticated (for example, the AD bit from a validating resolver), and MUST otherwise treat discovery as failed rather than falling back. When there is no SRV record (NXDOMAIN or an empty NOERROR answer), the host is `https://<domain>` on port 443. A resolver failure such as SERVFAIL is a failure, not an absence: under DNSSEC it is what a bogus zone produces.
2. MUST fetch `https://<target>[:<port>]/.well-known/bsvalias` and read `capabilities`.
3. MUST treat the capability as unavailable unless its value is an absolute `https://` URL containing the placeholder this document names for it.
4. SHOULD refuse a template, or an SRV target, whose host is an IP literal, `localhost`, or a private or link-local name. A domain's own document names where later requests go, and nothing else binds that destination to the domain.
5. MAY cache a successful discovery for a bounded period (ten minutes is typical) and a failed one for less.

A client configured with a fixed host for one domain (its own operator's, for instance) MAY skip discovery for that domain.

A host:

1. MUST list each capability it offers in `capabilities` under its BRFC id.
2. MAY list only these two capabilities. The well-known document below is complete:

```json
{
  "bsvalias": "1.0",
  "capabilities": {
    "0ace65da5987": "https://paymail.example.com/api/handle/{query}",
    "43dcf83ddc5f": "https://paymail.example.com/api/identityKey/{pubkey}"
  }
}
```

Clients MUST NOT require any other capability, including `pki` or `paymentDestination`, before using these two. Paths are the host's choice; only the placeholders are fixed.

### 4. Handle syntax

A handle is 1 to 32 characters matching:

```
^[a-z0-9]([a-z0-9._-]{0,30}[a-z0-9])?$
```

A host MAY impose a higher minimum length and MAY reserve names (`admin`, `postmaster`, `bsvalias`, …). A host SHOULD refuse to register a handle that is confusable with an existing one: for example by comparing a skeleton that removes `.`, `_` and `-`, folds `rn`→`m`, `vv`→`w`, `0`→`o`, `1`→`l`, `i`→`l`, `5`→`s`, `2`→`z`, `8`→`b`, and collapses repeated characters. The skeleton is a registration rule; clients need not compute it.

### 5. Profile certificate

A profile certificate is a BRC-52 certificate in its JSON form:

```json
{
  "type": "...",
  "serialNumber": "...",
  "subject": "...",
  "certifier": "...",
  "revocationOutpoint": "...",
  "fields": { "...": "..." },
  "signature": "..."
}
```

with these rules:

1. `type` MUST be `SbatVXXssDW3AO0J9bxIljkHGbPBGCVAXg94gXFf0cE=`, the base64 of SHA-256 of the UTF-8 string `public profile lookup`.
2. `subject` MUST equal `certifier`, compared as public keys (hex case-insensitively). That key is the holder's identity key. A signature that verifies against `certifier` says nothing about `subject` unless this equality is checked separately.
3. `signature` MUST verify per BRC-52 against `certifier`, counterparty `anyone`.
4. `revocationOutpoint` MUST be the zero outpoint, `0000000000000000000000000000000000000000000000000000000000000000.0`. There is no on-chain revocation: a holder replaces a profile with a newer one or publishes a tombstone.
5. `serialNumber` MUST be 32 bytes in canonical base64. A holder MUST use a fresh serial for every profile it issues.
6. `fields` values are **plaintext** UTF-8 strings. BRC-52 field encryption and keyrings are not used; a profile is public by definition.
   * `paymail` (required): `handle@domain`, all lowercase, with `domain` the domain the profile is published under.
   * `issuedAt` (required): an RFC 3339 timestamp. A later profile for the same handle MUST carry a later `issuedAt`; hosts use it to refuse replays of older profiles.
   * `released` (optional): `"true"` marks a tombstone. Any other value, or absence, means not released.
   * `displayName` (optional): a name to show alongside the paymail. It is not unique and MUST NOT be used to identify anyone.
   * Any other field name is free-form (avatar, bio, …) and MAY be ignored.
7. Limits: at most 32 fields; each field name under 50 bytes; each value at most 1024 bytes; the serialized certificate at most 16384 bytes.

How a holder submits a profile to its host (registration, update, release, account recovery) is outside this specification. A host that accepts submissions SHOULD verify rules 1 to 7 on write, SHOULD bound `issuedAt` to a few minutes ahead of its own clock (a far-future value would win every later comparison and freeze the handle), and SHOULD serve tombstoned handles from neither capability.

### 6. Public profile lookup (`0ace65da5987`)

**Request.** The client replaces `{query}` in the template with the URL-encoded query and performs `GET`.

The query is what a user has typed: `al`, `alice`, or `alice@example.com`. The client SHOULD lowercase and trim it and SHOULD NOT send a query the host would not search: one shorter than 2 or longer than 32 characters after any `@domain` suffix is removed, or containing characters outside `[a-z0-9._-]`. A client MUST NOT send a query that is a path segment with special meaning to URL parsers (`.`, `..`).

**Host behavior.** The host:

1. lowercases the query and strips an `@<domain>` suffix. A suffix that is a prefix of the domain the host serves is a domain still being typed and is accepted; any other suffix matches nothing.
2. returns an empty result for a query outside the length and character limits above, rather than an error.
3. matches on the handle only. It MUST NOT match on `displayName` or other free-form fields: those are not unique and searching them invites impersonation.
4. ranks results best first. RECOMMENDED order: the exact handle; handles with the query as prefix; handles whose confusable skeleton has the query's skeleton as prefix; handles containing the query (queries of 3 or more characters only).
5. returns at most 10 results and no tombstones.

**Response.** `200` with a JSON array of profile certificates, possibly empty:

```json
[ { "type": "SbatVXXssDW3AO0J9bxIljkHGbPBGCVAXg94gXFf0cE=", "...": "..." } ]
```

No match is `[]`, never `404` and never `null`.

### 7. Public profile reverse lookup (`43dcf83ddc5f`)

**Request.** The client replaces `{pubkey}` with a 33-byte compressed public key as 66 lowercase hex characters and performs `GET`.

**Response.** `200` with the single current profile certificate (a JSON object, not an array) of that key at this host, or `404` when the key holds no handle here. A key that does not match `^0[23][0-9a-f]{64}$` is `400`.

A host answers only for handles it hosts; there is no cross-domain index. A host holds at most one active handle per identity key.

### 8. Client verification

The host is a directory and a cache, not an authority on what a profile says. A client MUST apply every rule below to every certificate it receives, from either capability, before showing or using any field, and MUST discard a certificate that fails any rule, not the whole response.

1. Rules 1 to 7 of section 5, except freshness of `issuedAt`.
2. `fields.paymail` ends with `@<domain>`, where `domain` is the one the client resolved, compared case-sensitively against the lowercase form.
3. `fields.released` is not `"true"`.
4. A client SHOULD process at most 10 results from a lookup, since each one costs a signature verification and the response size is set by a host the client may not control. A client SHOULD bound response size and time.

For **lookup**:

5. Results are suggestions. A client MUST show the full `fields.paymail` of each and let the user choose, and MUST NOT select a result on the user's behalf by position.
6. When the user entered a complete `handle@domain`, the client MUST accept only a certificate whose `fields.paymail` equals it exactly.

For **reverse lookup**:

7. `subject` MUST equal the queried key (hex case-insensitively).
8. A client MAY forward-resolve `fields.paymail` and check that it returns the same key, which detects a host serving a stale profile.

The verified `subject` is the identity key to pay. A client SHOULD remember the key it paid under a paymail and warn when a later lookup returns a different one.

### 9. Errors

Errors other than the empty lookup result use a non-2xx status: `404` for a reverse lookup of a key with no handle, `400` for a malformed key. Clients act on the status alone; the error body is the host's choice, and MAY be a JSON object with a machine-readable code. A host SHOULD rate-limit both capabilities per client. A client MUST NOT treat any error as a lookup result.

## Security Considerations

**What the host cannot do.** Without the holder's private key, the host cannot alter a profile's fields, move a profile to another handle or domain, or forge a profile for a key it does not hold. Each of those breaks the signature or rule 2 of section 8.

**What the host still decides.** Which key holds a handle at its domain is the host's decision, as it is for every domain-scoped name: a host can register a handle to its own key first, or reassign a handle after a recovery process. It can also serve an older profile of the same key, or withhold one. Clients that pin keys per paymail (section 8) detect reassignment after first contact.

**Lookalikes.** A handle that resembles another (`a1ice` and `alice`) is a different handle with a different key and a valid certificate. Hosts SHOULD refuse confusable registrations (section 4); clients MUST show the full paymail and require exact equality where the user typed one.

**Reverse lookup links keys to names.** An identity key appears in BRC-29 remittances, in certificates, and wherever the holder has authenticated. Reverse lookup turns any such sighting into a name. Holders who want contexts kept apart SHOULD use separate identity keys, not separate handles, and payers who want neither direction SHOULD use [BRC-228](https://bsv.brc.dev/payments/0228.md).

**Discovery.** An SRV answer that moves resolution to another host is trusted only under DNSSEC (section 3). The capability template is attacker-controlled for an attacker's own domain, so clients restrict its destination (section 3, client rule 4).

**Resource bounds.** Lookup results come from hosts the client does not control; the result cap and size bounds of section 8 keep one response from becoming an unbounded amount of signature verification.

## Test Vectors

**BRFC ids.** `BRFCID("public profile lookup", "Deggen", "v1.0.0") = 0ace65da5987`; `BRFCID("public profile reverse lookup", "Deggen", "v1.0.0") = 43dcf83ddc5f`.

**Certificate type.** `base64(SHA-256("public profile lookup")) = SbatVXXssDW3AO0J9bxIljkHGbPBGCVAXg94gXFf0cE=`.

**Profile certificate.** Signed with the test-only private key `6a2991c9de20e38b31d7ea147bf55f5039e4bbc073160f5e0d541d1f17e321b8` and serial bytes `01 02 … 20`. It passes every rule of section 8 for domain `example.com` and, for reverse lookup, queried key `025ad43a22ac38d0bc1f8bacaabb323b5d634703b7a774c4268f6a09e4ddf79097`.

```json
{
  "type": "SbatVXXssDW3AO0J9bxIljkHGbPBGCVAXg94gXFf0cE=",
  "serialNumber": "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA=",
  "subject": "025ad43a22ac38d0bc1f8bacaabb323b5d634703b7a774c4268f6a09e4ddf79097",
  "certifier": "025ad43a22ac38d0bc1f8bacaabb323b5d634703b7a774c4268f6a09e4ddf79097",
  "revocationOutpoint": "0000000000000000000000000000000000000000000000000000000000000000.0",
  "fields": {
    "displayName": "Alice",
    "issuedAt": "2026-10-29T12:00:00.000Z",
    "paymail": "alice@example.com"
  },
  "signature": "304402201433492b6713a2f210bbd75c5d57de1085b92193f868e1add7785d35e55fc602022032ee8493f6e7d2273164c22c9ae8d8e59419e56d7ba0445663a17a9513c84c19"
}
```

The same certificate fails verification for domain `example.org` (rule 2), and fails reverse lookup for any other queried key (rule 7). Changing any field value invalidates the signature.

## Implementations

* [go-message-box-server](https://github.com/bsv-blockchain/go-message-box-server) hosts both capabilities (`pkg/handlers/lookup.go`) with registration, release and confusable-handle rules.
* Client and host support is in progress for [`@bsv/paymail`](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/ts-paymail) (`ProfileLookupRoute`, `PaymailClient.lookupProfiles`) and [go-paymail](https://github.com/bsv-blockchain/go-paymail) (`WithProfileLookupCapabilities`, `Client.LookupProfiles`). Both verify the test vector below.

## References

* [BRC-28: Paymail Payment Destinations](https://bsv.brc.dev/payments/0028.md)
* [BRC-29: Simple Authenticated BSV P2PKH Payment Protocol](https://bsv.brc.dev/payments/0029.md)
* [BRC-42: BSV Key Derivation Scheme (BKDS)](https://bsv.brc.dev/key-derivation/0042.md)
* [BRC-52: Identity Certificates](https://bsv.brc.dev/peer-to-peer/0052.md)
* [BRC-100: Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface](https://bsv.brc.dev/wallet/0100.md)
* [BRC-169: Universal Handle Addressing and Resolution for the Metanet](https://bsv.brc.dev/peer-to-peer/0169.md)
* [BRC-228: Unlinkable Payments under the Identity Paradigm](https://bsv.brc.dev/payments/0228.md)
* RFC 2782: A DNS RR for specifying the location of services (DNS SRV)
* RFC 3339: Date and Time on the Internet: Timestamps


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://bsv.brc.dev/payments/0235.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
