Module inbox_handles 

Inbox handles on the client.

A handle is a short public name that an inbox claims in its identity log (xmtp_id::associations::handle). Only the backend answers which inbox holds a handle or an account, so every path from a handle or an account to an inbox goes through one resolver. It looks the target up, loads the answered inbox’s identity updates, and keeps the answer only when the newest state the client derived holds the target. The client reports a changed display handle with the handle.changed event (identity_updates::store_association_state), and group members carry the handles of the newest state the client holds.

The client applies no handle policy. The backend alone refuses reserved, short, taken, or too frequent claims, and the client never applies the published minimum name length.

Enums

HandleError

A handle operation that the client refuses.

IdentityTarget

Someone a caller wants to reach: an account identifier or a handle. Either resolves to an inbox only through the verified resolver.

Constants

HANDLE_SEARCH_CODES

How many random codes xmtp_mls::Client::available_handles checks for a name without a code. With the name itself, one lookup holds 101 handles.

Functions

account_targets

accounts as targets, in order.

available_handles

The handles for input that no inbox holds. input is a handle as a user typed it; its ASCII capitals become lowercase. Input with a code checks only that handle. A name without a code checks the name and HANDLE_SEARCH_CODES distinct random codes in one lookup, and the name comes first in the result. Text outside the handle grammar fails before any request. No policy applies here, so a returned handle can still be refused when it is claimed.

claim_handle

Claim handle for this client’s inbox, signed by this installation’s key. A claim of a handle the inbox already holds makes it the display handle again. The backend refuses a taken, reserved, short, or too frequent claim with ApiError::HandleRejected. After the publish, the client has stored the inbox’s new identity update.

ensure_claim_allowed

Fail with HandleError::LimitReached when state has made as many claims as one identity log can hold. A validator rejects one more, so the client does not sign it.

handle_targets

handles as targets, in order.

handles_have_owner

Whether the backend names an inbox for each handle, in order. This checks no association state: use it only where a wrong answer costs a candidate, never to reach an inbox.

resolve_targets

The inbox of each target, in order, from one call. Fails when any target has no inbox: an account as find_or_create_dm_by_identity does, and a handle with HandleError::NotFound.

resolve_targets_in

The inbox of each target, in order, from one verified lookup. A handle that no inbox holds fails with HandleError::NotFound. An account with no inbox is None, so each route treats it as its account-only path does.

resolve_verified_in

The verified resolver, the only reader of a GetInboxIds answer that picks an inbox: look the targets up in one request, load the identity updates of every answered inbox in one incremental batch, derive each inbox’s newest state, at most IDENTITY_DEPENDENCY_CONCURRENCY at once, and drop any answer whose state does not hold its target.

resolve_verified_with_verifier

The verified resolver for a caller with no client, such as an SDK static helper. It stores the states it derives, with no event.