Skip to main content

Aliases

An alias is a human-readable on-chain name attached to a Substrate account. It serves as the anchor for the entire identity system: chain links, private links, and profile metadata all require the account to own an alias first.

Format rules​

Aliases follow strict encoding rules enforced on-chain:

RuleValue
Allowed characters[a-z0-9_] (lowercase letters, digits, underscore)
Minimum length3 bytes
Maximum lengthConfigured by T::MaxAliasLength (runtime parameter)
EncodingUTF-8, no uppercase, no spaces, no special characters

Examples of valid aliases: alice, bob_99, dao_treasury.

Registering an alias​

pallet: AccountMapping (index 14)
call:   register_alias (index 2)
args:   alias: Vec<u8>
origin: Signed

The call:

  1. Validates the alias format (returns AliasTooShort or InvalidAliasCharacters on failure).
  2. Checks that the alias is not already taken (AliasTaken).
  3. Checks that the caller does not already own an alias (AlreadyHasAlias).
  4. Reserves a deposit from the caller's balance.
  5. Stores the IdentityRecord keyed by the alias and the reverse mapping keyed by AccountId32.

On success, emits:

AliasRegistered { account, alias, evm_address: Option<H160> }

The evm_address field is populated only if the account has an active EVM mapping.

info

One account, one alias. An account can only hold a single alias at a time. To switch, release the current alias first.

Releasing an alias​

pallet: AccountMapping (index 14)
call:   release_alias (index 3)
origin: Signed (alias owner)

Releasing:

  • Returns the reserved deposit.
  • Removes the IdentityRecord (including all public chain links that were attached to it).
  • Removes private chain links stored under the alias.
  • The alias becomes available for re-registration by any account.

Emits: AliasReleased { account, alias }.

warning

Releasing an alias is destructive. All chain links attached to that alias are permanently removed.

Transferring an alias​

pallet: AccountMapping (index 14)
call:   transfer_alias (index 4)
args:   new_owner: AccountId32
origin: Signed (current owner)

Transfers the alias to new_owner without a payment. Constraints:

  • new_owner must not already have an alias (NewOwnerAlreadyHasAlias).
  • Cannot transfer to yourself (CannotTransferToSelf).
  • The deposit moves from sender to receiver.

After transfer, all previously attached chain links (public) are preserved under the alias for the new owner. Private links are also transferred.

Emits: AliasTransferred { from, to, alias }.

On-chain alias marketplace​

Aliases can be listed for sale and purchased without a third party.

Listing for sale​

pallet: AccountMapping (index 14)
call:   put_alias_on_sale (index 5)
args:   price: Balance, allowed_buyers: Option<Vec<AccountId32>>
origin: Signed (alias owner)
  • price must be greater than zero (PriceCannotBeZero).
  • allowed_buyers creates a private (OTC) whitelist. Omitting it accepts any buyer. Maximum whitelist size: 20 accounts (WhitelistTooLarge if exceeded).

Emits: AliasListedForSale { seller, alias, price, private: bool }.

Cancelling a listing​

pallet: AccountMapping (index 14)
call:   cancel_sale (index 6)
origin: Signed (alias owner)

Emits: AliasSaleCancelled { seller, alias }.

Buying an alias​

pallet: AccountMapping (index 14)
call:   buy_alias (index 7)
args:   alias: Vec<u8>
origin: Signed (prospective buyer)

Constraints:

  • The alias must be listed for sale (NotForSale).
  • If a whitelist is set, the buyer must be in it (NotInWhitelist).
  • The buyer must not already own an alias (BuyerAlreadyHasAlias).
  • The buyer must have sufficient balance to cover price plus the alias deposit.

On success, the price is transferred to the seller, the deposit reserved by the seller is returned to them, and a new deposit is reserved from the buyer. The alias and all its attached chain links transfer to the buyer.

Emits: AliasSold { seller, buyer, alias, price }.

Relationship to the rest of the identity system​

The alias is the on-chain key under which the IdentityRecord is stored. This record contains:

  • chain_links: list of verified public cross-chain addresses.
  • (Private links are stored separately in PrivateChainLinks<T>, also keyed by alias.)

Without an alias, an account cannot register chain links, private links, or profile metadata. This design prevents unbounded state growth from undeposited accounts.

Proxy dispatch via linked accounts​

Once chain links are attached (see Chain links), the alias also enables a proxy signing feature:

pallet: AccountMapping (index 14)
call:   dispatch_as_linked_account (index 13)

This allows an external wallet (e.g. Phantom on Solana) to authorize and dispatch a Substrate call on behalf of the Orbinum account, without that wallet holding any ORB for gas. A relayer can pay the fee. See Chain links for details.