sui-suins

SUI SuiNS Integration

Human-readable names for SUI addresses (like ENS for Ethereum).

SDK Versions

Targets: @mysten/suins 1.1.4 (^1.1), @mysten/sui 2.17.0 (^2.16). Tested: 2026-05-21.

Compatibility notes: @mysten/sui is a peer dependency. Use SuinsClient.getNameRecord(name): Promise<NameRecord | null> (NameRecord has targetAddress) — there is no getAddress / getName. Reverse lookup goes through client.core.defaultNameServiceName({ address }).

Overview

SuiNS provides:

• Human-readable names (alice.sui)
• Reverse address lookup
• Name ownership and trading
• Subdomains support

SUI v1.69 SuiNS API Changes

GraphQL Breaking Changes:

• Query.suinsName(name: ...) → Query.address(name: ...) for resolving SuiNS names
• IAddressable.defaultSuinsName → IAddressable.defaultNameRecord.target for reverse lookup
• New Query.nameRecord for fetching the full SuiNS NameRecord for a given name

# Old (deprecated)
query { suinsName(name: "alice.sui") { address } }

# New (v1.64+, current)
query { address(name: "alice.sui") }
query { nameRecord(name: "alice.sui") { ... } }

Use Cases

• User profiles
• Wallet address display
• Social features
• Payment requests
• Any user-facing addresses

Quick Start

Register Name

use suins::registry;

public fun register_name(
    name: String,
    duration_years: u64,
    payment: Coin<SUI>,
    ctx: &mut TxContext
) {
    registry::register(
        name,
        duration_years,
        payment,
        ctx
    );
}

Resolve Name to Address

public fun resolve(name: String): Option<address> {
    registry::lookup(name)
}

Frontend Integration

// @check:skip
import { SuinsClient } from '@mysten/suins';
import { SuiGrpcClient } from '@mysten/sui/grpc';

const client = new SuiGrpcClient({
  network: 'mainnet',
  baseUrl: 'https://fullnode.mainnet.sui.io:443',
});
const suins = new SuinsClient({ client, network: 'mainnet' });

// Resolve name to address via NameRecord
async function resolveName(name: string): Promise<string | null> {
  const record = await suins.getNameRecord(name);
  return record?.targetAddress ?? null;
}

// Reverse lookup: address to default name (provided by SuiGrpcClient core)
async function getName(address: string): Promise<string | null> {
  const res = await client.core.defaultNameServiceName({ address });
  return res.data.name;
}

// Register new name
async function registerName(name: string, years: number) {
  const tx = new Transaction();

  const [coin] = tx.splitCoins(tx.gas, [tx.pure(calculateCost(years))]);

  tx.moveCall({
    target: `${SUINS_PACKAGE}::registry::register`,
    arguments: [
      tx.pure(name),
      tx.pure(years),
      coin
    ]
  });

  return await signAndExecute({ transaction: tx });
}

Display Name in UI

// @check:skip
function AddressDisplay({ address }: { address: string }) {
  const { data: name } = useQuery({
    queryKey: ['suins', address],
    queryFn: () => getName(address)
  });

  return (
    <span>
      {name || `${address.slice(0, 6)}...${address.slice(-4)}`}
    </span>
  );
}

Best Practices

• Cache name resolutions
• Handle missing names gracefully
• Display both name and address
• Support .sui TLD
• Validate name format

Common Mistakes

❌ Not caching name resolutions

• Problem: Excessive RPC calls, slow UI, rate limiting
• Fix: Use React Query with 5-minute cache for name lookups

❌ Assuming all addresses have names

• Problem: UI breaks when address has no SuiNS name
• Fix: Fallback to truncated address if name is null

❌ Not validating name format

• Problem: Invalid names sent to contract, transaction fails
• Fix: Validate: lowercase, alphanumeric+hyphens, ends with .sui

❌ Forgetting to handle subdomain resolution

• Problem: sub.alice.sui fails to resolve
• Fix: Use SuiNS SDK which handles subdomains automatically

❌ Hard-coding name prices

• Problem: Prices change, registration fails
• Fix: Query current pricing from SuiNS contract

❌ Not showing expiration dates

• Problem: Users lose names without warning
• Fix: Display expiration, send renewal reminders

❌ Using names without ownership verification

• Problem: Phishing via name squatting
• Fix: Verify name ownership on-chain before trusting

Query SuiNS docs:

// @check:skip
const suinsInfo = await sui_docs_query({
  type: "github",
  target: "suins",
  query: "name registration and resolution API"
});

---

Make SUI addresses human-friendly!