Canonical Usernames & Display Handles

[salmad3]

Context:

Canonical usernames with case-preserving handles so the product can retire raw wallet addresses.

Memo Actions

• dither.Register(handle): registers a new handle or updates display casing if already owned by signer
• dither.Transfer(handle, address): initiates transfer, locks handle until resolved
• dither.Accept(handle): confirms transfer before expiry; ownership updates and lock clears
• ADR-36 session wallet/AuthZ signs the memos; no new on-chain module needed

Acceptance Criteria

• Add username (normalized, unique, ≤30 chars) and display_handle columns; backfill current users with NULL
• Return both fields on all user payloads (/profile, /feed, /followers, /following, /search, wallet lookup)
• Endpoints issue handle memos via reader; enforce ≤2 successful claims per rolling 7-day window
• Reject reserved names or malformed input with structured errors surfaced in the wizard
• Log every register/update/transfer (actor, previous value, new value, timestamp)
• Reader consumes Register, Transfer, Accept memos with normalization, reserved-word, uniqueness, and expiry checks
• Reader publishes handle state (owner, display handle, pending transfer metadata) via API/WebSocket; backend job hydrates existing users once data is live
• Wizard copy shows “Handle appears available” with pending state; surface success/failure when confirmation arrives (poll or WebSocket)
• Render @display_handle across profile header, feed bylines, mentions, notifications with address fallback
• Tests cover normalization collisions, reserved names, transfers (accept + expiry), rate limits, wizard flow; telemetry emits counters and alerts

[salmad3]

[10-11-25]:
Team discussed handles and decided on memo flow (HANDLE_CLAIM, HANDLE_TRANSFER, HANDLE_ACCEPT_TRANSFER) + “handle appears available” UX copy; we'll proceed with two-step transfer implementation.

[jeronimoalbi]

@salmad3 why do we need a nonce when registering a handle? Also, do we need a display name, wouldn't the handle be enough, to keep the protocol leaner? Otherwise we would probably need to introduce support for changing the display name.

I'm wondering if register might be more appropriate than claim 🤔, any thoughts?

[jeronimoalbi]

New protocol functions:

• dither.Register(handle)
• dither.Transfer(handle, address)
• dither.Accept(handle)

Or:

• dither.RegisterHandle(handle)
• dither.TransferHandle(handle, address)
• dither.AcceptHandle(handle)

@salmad3 @ilgooz @luciorubeens any thoughts?

Currently the protocol is very minimalist in general, including names which are Post(), Like(), Follow(), Unfollow() ... etc, all single word actions.

I think it would be good to stick to that idea, as long as is possible and makes sense, so personally I lean towards the first list of function names.

[salmad3]

thanks @jeronimoalbi

why do we need a nonce when registering a handle?

Oh, earlier version, we can omit that's true.

Also, do we need a display name, wouldn't the handle be enough, to keep the protocol leaner? Otherwise we would probably need to introduce support for changing the display name.

The handle (e.g., @alice) is the unique identifier that doesn’t change; it’s what people mention and what we store in canonical lookups. Display name (“Alice Bob”) is just the cosmetic label. Users expect to tweak casing, add emojis, etc. without breaking mentions or the handle.

New protocol functions:

Good point. The single-word function names are good practice.

[jeronimoalbi]

@salmad3 @luciorubeens @alanrsoares the backend part is implemented in #468, I just have to live tests the protocol and generate a database migration for the PR changes, but the frontend part can be done already I think.

Relevant endpoints are returning the handle and display fields.
These two fields can be null if there is no handle (or display text) registered.

The protocol, so far:

• dither.Register('handle', 'display text')
• dither.Transfer('handle', '0xabc123...')
• dither.Accept('handle')
• dither.Display('display text')

Register takes the handle and an optional display text, it can be an empty display text string.

Handle can be transferred, with the assigned display text, to another address using Transfer and then from another account Accept to reassign the handle to that account.

The display text can be changed, only when the address have a registered handle, using Display.

There is no concept of expiration right now.

User handle or address can also be getted using the API endpoint /v1/handle. It supports two GET arguments, name or address.