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

| Package | Original ID | Description | |---------|------------|-------------| | Core (v2) | 0xd22b24490e0bae52676651b4f56660a5ff8022a2576e0089f79b3c88d44e08f0 | Registry, controller, auction, domain, name records |

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

| Module | Purpose | |--------|---------| | suins | Core shared object, AdminCap, app authorization, config/registry access | | registry | Forward/reverse name lookups, record management, NFT authorization | | controller | User-facing: set_target_address, set_reverse_lookup, set_user_data, burn_expired | | auction | Domain auctions: start, bid, claim, finalize | | suins_registration | SuinsRegistration NFT struct and accessors | | subdomain_registration | SubDomainRegistration wrapper for subdomain NFTs | | domain | Domain parsing, TLD/SLD/parent accessors, subdomain checks | | name_record | NameRecord struct: target_address, expiration, data | | pricing_config | Range-based pricing by label length | | core_config | CoreConfig: TLD validation, label length bounds, max_years | | constants | grace_period_ms, year_ms, domain length limits |

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)