SuiNS (Sui Name Service)

SuiNS is the naming service for Sui. Users register .sui domains (e.g., alice.sui) that resolve to addresses, store metadata, and support subdomains. Domain ownership is represented by SuinsRegistration NFTs with expiration timestamps.

Package IDs

Source Files

Decompiled Move source:

• v2: packages/mainnet_most_used/0x71/af035413ed499710980ed8adb010bbf2cc5cacf4ab37c7710a4bb87eb58ba5/decompiled_modules/
• v1: packages/mainnet_most_used/0x00/c2f85e07181b90c140b15c5ce27d863f93c4d9159d2a4e7bdaeb40e286d6f5/decompiled_modules/

Architecture

• SuiNS: Shared object holding the registry, config, and balance. Apps are authorized via dynamic fields.
• Registry: Table<Domain, NameRecord> mapping domains to name records, plus a reverse_registry: Table<address, Domain> for reverse lookups.
• SuinsRegistration: Owned NFT representing domain ownership (domain, expiration_timestamp_ms, image_url).
• SubDomainRegistration: Wrapper around SuinsRegistration for subdomain NFTs.
• AuctionHouse: Shared object managing domain auctions with bidding and claiming.
• Domain: Struct with labels: vector<String> stored in reverse order (TLD at index 0). Labels: lowercase a-z, 0-9, hyphens (not at start/end), 1-63 chars each.
• NameRecord: Maps a domain to its nft_id, target_address, expiration_timestamp_ms, and data: VecMap<String, String>.

Constants

• Grace period: 30 days (2,592,000,000 ms)
• Year: 31,536,000,000 ms
• Min domain length: 3 chars
• Max domain length: 63 chars
• Auction duration: 48 hours (172,800,000 ms)
• Auction extension: 10 minutes (600,000 ms) if bid placed near end
• User data keys: avatar, content_hash, walrus_site_id

Key Modules

Common Integration Patterns

Resolve Domain to Address

// Get the registry from SuiNS shared object
let record = registry::lookup(registry, domain::new(string::utf8(b"alice.sui")));
if (option::is_some(&record)) {
    let target = name_record::target_address(option::borrow(&record));
    // target: Option<address>
};

Reverse Lookup (Address to Domain)

let domain = registry::reverse_lookup(registry, addr);
// Returns Option<Domain>

Set Target Address (requires owning the SuinsRegistration NFT)

controller::set_target_address(suins, &nft, option::some(target_addr), clock);

Set Reverse Lookup (sender maps to domain)

controller::set_reverse_lookup(suins, string::utf8(b"alice.sui"), ctx);

Set User Data (avatar, content_hash, walrus_site_id)

controller::set_user_data(suins, &nft, string::utf8(b"avatar"), string::utf8(b"ipfs://..."), clock);

Start Auction and Bid

auction::start_auction_and_place_bid(auction_house, suins, string::utf8(b"alice.sui"), sui_coin, clock, ctx);

Place Bid on Existing Auction

auction::place_bid(auction_house, string::utf8(b"alice.sui"), sui_coin, clock, ctx);

Claim Won Auction

let nft = auction::claim(auction_house, string::utf8(b"alice.sui"), clock, ctx);

Burn Expired Registration

controller::burn_expired(suins, expired_nft, clock);

Query Auction Metadata

let (start_ts, end_ts, winner, current_bid) = auction::get_auction_metadata(auction_house, string::utf8(b"alice.sui"));
// All returned as Option<T>

Related Skills

• sui-framework -- Core Sui types (Coin, Balance, Clock, TxContext)