Aliases

An alias is a short, human-readable name — like john_doe — that resolves to a wallet address, the same way a person’s name in your phone’s contacts resolves to a phone number. Aliases are globally unique across the whole system (not per-domain), case-insensitive (John_Doe and john_doe are the same alias), and are lowercased and stripped of any domain suffix at creation. See Addresses for how aliases fit into the address system as a whole.

Note: creating a mailbox automatically registers your wallet’s own address string as an alias for you. This is a security measure, not just a convenience: address resolution checks the alias registry before falling back to treating the string as a raw wallet address, so if your address string were left unclaimed, a malicious user could register it as their alias and quietly receive mail addressed to your wallet. Claiming the self-alias at mailbox creation closes that spoof. Most users therefore never need to create an alias by hand — the getting-started wizard claims an optional friendlier handle as part of onboarding, and every client’s Aliases pane lists the names pointing at your wallet.¹

Listing all aliases (the alias indexer)

Alias names are not recoverable from chain state: an alias account stores only the holder’s address, and the name itself exists on-chain only as a blake3 hash inside the PDA seed. “Which aliases point at wallet X?” is therefore answered by the gRPC gateway (mail-grpc), which maintains an off-chain index of the alias program’s transaction history — every Create/Transfer/Close instruction carries the plaintext name — and serves it through the ListAliases RPC.

• Names are returned in their canonical (lowercased) form, sorted.
• The index lives in a local SQLite file beside the gateway — the operator chooses its location, and an operator who doesn’t want the feature can turn the indexer off entirely — and is fed by polling the chain every few seconds.
• On first start the gateway backfills the program’s full history; ListAliases answers UNAVAILABLE until that backfill completes, and restarts resume from a stored cursor instead of re-scanning.
• The index reads at finalized commitment, so a freshly created alias appears after finalization plus one poll interval.

Transferring an alias

Moving an alias to a new wallet is a deliberate two-party consent ceremony — the current holder initiates the offer, and it only changes hands once the named recipient separately accepts — never a unilateral push. See Trading names: aliases & domains for the escrowed-transfer-for-a-fee marketplace mechanics.

Selling an alias

A listing is a different disposal mechanism from a transfer: it puts the alias up at a fixed price that whoever pays first takes, rather than a transfer’s negotiated two-party consent naming one specific recipient. An auction is a third option: instead of one fixed price or one named recipient, buyers bid the price up over a window and the high bidder wins at the deadline. See Trading names: aliases & domains for the full marketplace mechanics — listings, auctions, and escrowed transfers alike.

1. From the terminal: Create an alias registers additional aliases, Get an alias looks one up, and Transfer an alias moves one to a new address. ↩