Skip to content
LogoLogo

Claim your username

In MIP 4, canonical username is not profile metadata.

Username is claimed through a dedicated USERNAME_CREATE message and replaced through USERNAME_UPDATE. STORAGE_CLAIM funds raw storage only — it does not assign a username.

To try this interactively, follow the account registration guide which includes the full wallet-connected flow with username selection.

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 that no username is currently assigned.
  2. USERNAME_UPDATE — replaces the existing canonical username with a new one. 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 manually submit STORAGE_CLAIM first. 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

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, but they must lowercase and validate it before signing or submission. Validators reject non-canonical usernames on the wire.

Username lifetime

  • username is active while the account has both active storage and an active username assignment
  • username is released when effective active storage drops to zero
  • USERNAME_UPDATE replaces the current username with a new one 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 still mutable profile metadata.

It is distinct from canonical username because display name is:

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

Learn more

Edit this page on GitHub