suins

name	suins
description	This skill should be used when the user asks about SuiNS, Sui Name Service, .sui domains, domain registration, name resolution, reverse lookup, or wants to integrate with SuiNS on Sui. Covers domain registration, auctions, name records, target address resolution, subdomains, and reverse lookups.

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)