Claim your username

Claim a canonical username with USERNAME_CREATE. Replace it later with USERNAME_UPDATE. Username is not profile metadata — STORAGE_CLAIM funds raw storage only and does not assign a username.

For the full wallet-connected flow with username selection, see the account registration guide.

How username is assigned

Username assignment uses two dedicated message types:

  1. USERNAME_CREATE — claims the first canonical username for an account. Requires active storage and no currently assigned username.
  2. USERNAME_UPDATE — replaces the existing canonical username. Requires an active username and active storage.

Both messages require a delegated Ed25519 key on owner_address with scope SIGNING.

In the recommended client flow, do not submit STORAGE_CLAIM manually. Instead:

  1. rent storage with rentStorage()
  2. wait until raw storage is visible with waitForStorageClaim(), or inspect snapshot state with getRegistrationStatus()
  3. submit USERNAME_CREATE or USERNAME_UPDATE

Username-bearing quota requires both active storage and an active username. Storage alone is not sufficient.

Canonical username format

The canonical protocol form is:

  • lowercase ASCII only
  • length 3 through 32
  • characters limited to a-z, 0-9, -
  • first and last characters must be alphanumeric

Canonical regex:

^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$

Clients may accept mixed-case input for UX. They must lowercase and validate it before signing or submission. Validators reject non-canonical usernames on the wire.

Username lifetime

  • a username is active while the account has both active storage and an active username assignment
  • a username is released when effective active storage drops to zero
  • USERNAME_UPDATE replaces the current username while storage remains active

Read surfaces

GetAccountResponse.username returns:

  • the canonical username when both effective active storage and an active username are present
  • the empty string when the account has no active username

Profile metadata stays separate

ACCOUNT_DATA(DISPLAY_NAME) is mutable profile metadata. It is distinct from the canonical username because a display name is:

  • not globally unique
  • not storage-backed
  • not released on storage expiry
  • updated through ordinary LWW ACCOUNT_DATA semantics

Learn more