Smart Contract Architecture

Elysium Names is built around three primary smart contracts, each responsible for a distinct part of the naming protocol.

The architecture separates NFT ownership and name records from registration operations and auction management. These contracts interact to provide a unified naming system.

​

1. Architecture Overview

The protocol consists of:

Contract	Primary responsibility
ElyNamesMainnet	ERC-721 ownership, name records, expiry, resolution and royalties
ElyControllerMain	Registration, pricing, renewals, referrals, discounts and partner programmes
ElyAuction	Single-character name auctions, bids, refunds and settlement

Each contract has a defined role, reducing the need to place every protocol operation inside one contract.

​

2. ElyNamesMainnet

ElyNamesMainnet is the core name and NFT contract.

Every successfully registered name is represented by an ERC-721 NFT. Ownership of this NFT determines ownership of the corresponding name.

Its responsibilities include:

• Minting and managing name NFTs.
• Tracking name ownership and expiry.
• Supporting NFT transfers.
• Managing address records.
• Managing text records.
• Setting and retrieving primary names.
• Appointing and removing name managers.
• Resolving names to wallet addresses.
• Providing NFT metadata.
• Exposing ERC-2981 royalty information.

​

Name identity

Each name has a token ID derived from its label:

uint256 tokenId = uint256(
    keccak256(bytes(label))
);

This provides a deterministic identifier for each name label.

​

Ownership and permissions

The NFT owner retains ownership rights over the name.

An appointed manager can perform permitted record-management actions, but does not receive ownership of the NFT.

The contract also handles the effects of NFT transfers, including clearing the previous manager and resetting the relevant records for the new owner.

​

3. ElyControllerMain

ElyControllerMain handles registration and the operational logic of the protocol.

Rather than placing registration payments, pricing and eligibility rules inside the NFT contract, these functions are managed through the controller.

Its responsibilities include:

• Commit-reveal registration.
• Registration pricing.
• Registration duration.
• Renewals.
• Expiry and grace-period handling.
• Expired-name premiums.
• Referral discounts and rewards.
• Partner discounts and eligibility.
• Reserved-name registration.
• Payment processing and treasury routing.

​

Registration

The controller validates the registration commitment, label, payment and applicable eligibility conditions before coordinating registration with the core name contract.

The registration commitment is bound to the intended receiving owner. This allows the wallet paying for registration to differ from the wallet receiving the name NFT.

​

Renewals

The controller processes renewal requests, validates the applicable duration and payment, and updates the name’s expiry through the core contract.

​

Discounts and referrals

The controller handles supported registration discounts, partner eligibility and referral accounting.

These mechanisms follow their configured rules and do not automatically apply to renewals or expired-name premiums.

​

4. ElyAuction

ElyAuction manages the auction distribution of reserved single-character names.

All 36 single-character labels are reserved for this distribution mechanism.

The contract handles:

• Auction scheduling.
• Opening bids.
• Bid validation.
• Minimum bid increases.
• Outbid refunds.
• Auction settlement.
• Registration for winning bidders.
• Proceeds routing to the treasury.

​

Auction lifecycle

A typical auction follows this sequence:

1. An auction is scheduled for a reserved single-character label.
2. Participants submit bids that satisfy the auction rules.
3. Outbid participants can withdraw their refundable bids.
4. After the auction ends, anyone can call the settlement function.
5. The winning bid is processed and the name is registered for the winning bidder.
6. Auction proceeds are directed to the configured treasury.

If registration cannot be completed, the winning bid becomes withdrawable under the contract’s refund mechanism.

​

5. Contract Interactions

The three contracts work together through authorised contract calls.

For example, during a normal registration:

1. The user interacts with ElyControllerMain.
2. The controller validates the commitment and registration conditions.
3. The controller processes the required payment.
4. The controller calls ElyNamesMainnet to create the name NFT and assign its intended owner.
5. The core contract records the name and its expiry information.

During a single-character auction, ElyAuction manages the bidding and settlement process before coordinating registration through the core naming contract.

This separation allows the NFT contract to focus on name ownership and records while the controller and auction contract handle their respective protocol operations.

​

6. Administrative Access and Permissions

The protocol uses controlled administrative permissions for sensitive operations.

The contracts use OpenZeppelin’s Ownable2Step ownership model.

Under this model, transferring contract ownership requires the proposed new owner to accept the transfer. This reduces the risk of accidentally transferring administrative control to an incorrect address.

Contract ownership and operational permissions should be treated separately:

• Contract ownership: Controls owner-restricted administrative functions.
• Controller authorisation: Allows the designated controller to perform its permitted operations on the core name contract.
• Auction authorisation: Allows the auction contract to perform its permitted registration operations.
• Name ownership: Belongs to the wallet holding the corresponding ERC-721 NFT.

Administrative ownership does not automatically grant ownership of individual registered names.

​

7. Technical Stack

The protocol’s development configuration includes:

Component	Configuration
Language	Solidity
Compiler version	0.8.28
Optimizer runs	200
EVM target	Paris
ERC-721 implementation	OpenZeppelin
OpenZeppelin version	5.1.0
Ownership model	Ownable2Step

These details describe the documented development configuration. Developers should consult the repository and verified deployed source when checking a specific deployment.

​

8. Deployment and Initialisation

The deployment process uses dedicated scripts to deploy and initialise the protocol contracts.

The main deployment script is:

script/mainnet/DeployMainnet.s.sol

It deploys the three primary contracts, configures the required authorisations and reserves designated names.

The auction scheduling script is:

script/mainnet/ScheduleAuctions.s.sol

It schedules the 36 single-character auctions according to the configured auction parameters.

Deployment configuration should be reviewed carefully before execution, particularly:

• Contract addresses and constructor arguments.
• Controller and auction authorisations.
• Reserved-name configuration.
• Treasury and royalty settings.
• Final ownership and administrative addresses.

Developers should never assume that testnet addresses or settings apply to mainnet.

​

9. Source Code and Verification

The smart contract implementation and deployment scripts are available in the project repository:

https://github.com/bonaventure001/ely-names

Developers should use the source code and verified contract deployments to confirm function signatures, permissions and configuration before integrating with the protocol.

For testing and security information, see Security & Testing.

​

10. Summary

The Elysium Names architecture separates three key responsibilities:

• ElyNamesMainnet manages name NFTs, ownership, records and resolution.
• ElyControllerMain manages registration, pricing, renewals and protocol operations.
• ElyAuction manages single-character name auctions.

Together, they provide the onchain foundation for registration, ownership, resolution and ecosystem integrations across Elysium Names.