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. An alias is yours outright: it never expires and carries no renewal fee, and it is a transferable on-chain asset you can sell — through an escrowed offer, a fixed-price listing, or an auction — keeping 90% of the proceeds (see Trading names). Short names are explicitly scarce: there will only ever be 36 one-character aliases, and the one- to four-character tiers carry scarcity-priced claim fees. 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 namespace reservation: the alias namespace is global and case-folded, and the self-alias keeps anyone else from holding a name that reads as your wallet. It is not what protects your mail — resolution is literal-first: a string that already is a wallet address names that wallet, full stop, and the alias registry is only consulted for text that is not an address. So an alias registered under an address’s lowercased spelling can never redirect mail sent to the address, whether or not the owner claimed the self-alias. Most users 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.¹

One namespace, and why

There is exactly one alias namespace, and it is domain-blind: any @domain suffix is parsed off and discarded before resolution, so alice, alice@acme.com, and alice@anything.example all resolve to whoever holds the global alice. Assigning your address to a domain binds which MX relays your mail; it confers no claim on any name. Only you can repoint a name you hold.

That is a deliberate guarantee, not a simplification. Because lockbox sealing follows resolution in the sender’s browser, anyone who could redefine which wallet an address names would thereby choose which key a sender seals to — reaching inside an end-to-end-encrypted body. Keeping one holder-controlled namespace is what forecloses that.

Issuing addresses to an organization’s staff therefore works by handing over real ownership rather than by carving out a suffix: reserve the names in bulk with alias create, then transfer each to its holder — a two-party consent hand-off, after which the employee holds the name outright and the organization cannot silently take it back.

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. ↩