Name Resolution

Name resolution allows applications to translate human-readable .ely names into wallet addresses.

Instead of requiring users to copy and share long hexadecimal addresses, an application can accept a .ely name and query the Elysium Names protocol to retrieve its associated address.

The protocol also supports reverse lookup, allowing applications to retrieve the primary .ely name associated with a wallet.

​

1. How Name Resolution Works

Each registered .ely name has an associated address record.

When an application needs to resolve a name, it calls the core name contract with the name label, without the .ely suffix.

For example, to resolve yourname.ely, the application passes:

yourname

The contract checks the name and returns its associated wallet address if the name is registered and active.

If the name is not registered or has expired, resolution returns the zero address.

​

2. Resolving a Name

The core resolution function is:

resolve(string label)

Input:

• label: The registered name label, without the .ely suffix.

Returns:

• The wallet address associated with the name, if it is valid and active.
• The zero address if the name cannot be resolved.

Example:

address resolvedAddress = names.resolve("yourname");

Applications should check the returned address before using it. A zero address means the lookup did not produce a valid active destination.

​

3. Reverse Resolution

The protocol provides a reverse lookup function:

primaryNameOf(address account)

This returns the primary .ely name associated with a wallet address.

Example:

string memory primaryName = names.primaryNameOf(userAddress);

If the wallet has a primary name set, the function returns the full name, including the .ely suffix.

If no primary name is set, it returns an empty string.

This is useful for displaying readable identities in applications, transaction histories, profiles and community interfaces.

​

4. Address Records

Address records determine the wallet address returned when a name is resolved.

The name owner can update the address record through the protocol’s record-management functionality.

An appointed manager can also update address records within the permissions granted to them.

Updating an address record does not transfer ownership of the name NFT. The NFT owner remains the name owner unless the NFT itself is transferred.

Applications should therefore distinguish between:

• NFT ownership: The wallet that owns the .ely name.
• Resolved address: The address currently associated with the name.
• Manager: An account authorised to perform specific record-management actions.

These values may belong to different wallets.

​

5. Text Records

Elysium Names also supports text records for storing additional information associated with a name.

The core contract exposes:

text(string label, string key)

This allows an application to retrieve a text record using the name label and record key.

Example:

string memory value = names.text("yourname", "description");

Text records can support application-specific profile information and other integrations.

The availability of a particular record depends on whether the name owner or authorised manager has set it.

​

6. Other Useful Read Functions

The core name contract exposes additional read functions that developers can use when building integrations.

Function	Purpose
available(label)	Checks whether a label is available for registration
nameExpires(label)	Retrieves the name’s expiry timestamp
idOf(label)	Retrieves the token ID associated with a label
labelOf(tokenId)	Retrieves the label associated with a token ID
ownerOf(tokenId)	Retrieves the ERC-721 owner of a name NFT
managerOf(label)	Retrieves the appointed manager
isValidLabel(label)	Checks whether a label meets the protocol’s format rules
tokenURI(tokenId)	Retrieves the NFT metadata URI

These functions provide useful information for wallets, explorers, marketplaces and other applications.

​

7. Name Format and Normalisation

Elysium Names uses a standard label format.

A valid label must:

• Contain between 1 and 63 characters.
• Use lowercase letters (a-z).
• Allow numbers (0-9).
• Allow hyphens (-).
• Not begin or end with a hyphen.

Applications should normalise user input before submitting it for resolution.

The expected format is the name label without the .ely suffix. For a user-facing input that includes .ely, integrations should remove the suffix and convert the label to lowercase before calling the resolution function.

Applications should also validate the label and handle unsuccessful lookups gracefully.

​

8. Important Integration Considerations

When implementing .ely resolution:

• Confirm that the name is active before using its resolved address.
• Do not assume NFT ownership and the resolved wallet address are identical.
• Do not treat an empty reverse-lookup result as an error; the wallet may simply have no primary name.
• Account for name expiry when caching or displaying resolved addresses.
• Use the official deployed contract address and correct network configuration.
• Do not assume every wallet or application supports .ely natively.

The protocol provides the onchain resolution functionality, but individual wallets and applications must integrate it to offer native .ely name lookup.

​

9. Summary

Elysium Names provides forward and reverse name resolution alongside address and text records.

Developers can use these interfaces to:

• Resolve a .ely name to a wallet address.
• Retrieve a wallet’s primary .ely name.
• Read address and text records.
• Check ownership, manager permissions and expiry.
• Validate labels and retrieve NFT metadata.

These interfaces provide the foundation for integrating .ely names into wallets, explorers, marketplaces, DeFi applications and other Elysium ecosystem services.