/suins-integration

name: suins-integration
description: Integrate SuiNS names into a Sui dapp. Use when the user mentions SuiNS or wants name resolution on Sui.

Preamble (run first)

# Suiperpower telemetry. Routes through the CLI so projects.json + Convex stay in sync.
# Silent on failure so the skill never blocks. Opt out: SUIPERPOWER_TELEMETRY=off.
#
# AGENT NOTE: when this skill finishes, run the matching completion command:
#   suiperpower track suins-integration build completed
# Or use "failed" / "aborted" if it ended that way.
command -v suiperpower >/dev/null 2>&1 && suiperpower track suins-integration build started >/dev/null 2>&1 &
true

If `TEL_PROMPTED` is `no`, before doing real work, ask the user:

> Help suiperpower get better. We track which skills get used and how long they take. No code, no file paths, no PII. Change anytime in `~/.suiperpower/config.json`. > > A) Sure, anonymous > B) No thanks

Write the answer to `~/.suiperpower/config.json` `telemetryTier` field and create `~/.suiperpower/.telemetry-prompted`. Then continue.

What this skill does

Integrates SuiNS name resolution and/or Move Registry (MVR) named packages into a Sui project. On the resolution side: resolve `.sui` names to addresses, reverse-lookup addresses to names, and read name metadata. On the registration side: register names, set target addresses, set default names, and attach user data (e.g., Walrus site IDs). On the MVR side: replace raw package addresses with human-readable `@org/package` names in Move dependencies and TypeScript transaction builds.

When to use it

• The project needs to resolve `.sui` names to Sui addresses (forward lookup).
• The project needs to display a `.sui` name for a given address (reverse lookup).
• The user wants to register a `.sui` name programmatically.
• The user wants to set user data on a SuiNS name (avatar, Walrus site, custom fields).
• The user wants to use MVR named packages instead of raw hex addresses in Move or TypeScript.
• The user is building a profile page, social feature, or any UI where addresses should be human-readable.

When NOT to use it

• If the user has not picked a project yet, use `find-next-sui-idea` first.
• If the user has not scaffolded a project, use `scaffold-project` first.
• If the user wants to build a full name service from scratch (not integrate SuiNS), use `build-with-move`.
• If the user only needs to deploy a package and does not care about named packages, use `deploy-to-testnet`.

If you activated this and the user actually wants something else, consult `skills/SKILL_ROUTER.md` and hand off.

Inputs

• A Sui project with a TypeScript frontend or backend, OR a Move package that needs MVR dependencies.
• Optional: `.suiperpower/build-context.md` from `scaffold-project`. Read it if present.
• The user's intent: name resolution, name registration, MVR integration, or a combination.

If unclear, interview the user for:

• Do you need to resolve names (read), register names (write), or both?
• Is this for a frontend (display names) or backend (programmatic lookup)?
• Do you want to use MVR named packages in your Move dependencies or TypeScript builds?
• Which network: mainnet, testnet?

Outputs

• TypeScript integration code using `@mysten/suins` for resolution and/or registration.
• Optional: MVR CLI setup and `namedPackagesPlugin` wiring for TypeScript transaction builds.
• Optional: `Move.toml` updates for MVR-resolved dependencies via `mvr add`.
• Append to `.suiperpower/build-context.md`:

  ## suins-integration session, <timestamp>
  - features: <resolution | registration | mvr | combination>
  - package: @mysten/suins
  - network: <mainnet | testnet>
  - mvr packages added: <list or none>
  - open issues: <list>

Workflow

1. **Context gathering**

• Read `.suiperpower/build-context.md` if it exists.
• Confirm the user's intent: resolution, registration, MVR, or all three.
• Check if the project already has `@mysten/sui` installed (peer dependency for `@mysten/suins`).

2. **Install dependencies**

• `npm install @mysten/suins` (or pnpm/yarn equivalent).
• Confirm `@mysten/sui` is already installed as a peer dependency. If not, install it.
• For MVR: `npm install -g @aspect-run/mvr` for the CLI, or `@mysten/sui` already includes `namedPackagesPlugin`.

3. **Name resolution (if needed)**

• Initialize `SuinsClient` with the user's `SuiClient` and target network.
• Wire forward lookup: `suinsClient.getNameRecord('name.sui')` returns a `NameRecord` with `targetAddress`, `expirationTimestampMs`, `avatar`, `walrusSiteId`, and other metadata. Returns `null` if the name does not exist or is expired.
• The SDK does not expose standalone `getAddress()` or `getName()` methods. Use `getNameRecord()` for all resolution.
• See `references/suins-quickstart.md` for the full API surface.

4. **Name registration (if needed)**

• Use `SuinsTransaction` for registration mutations.
• Wire `register()` with domain, years, `coinConfig` (SUI, USDC, or NS), payment coin, `maxAmount`, and `priceInfoObjectId` (required for SUI/NS, not USDC).
• Wire `renew()` to extend an existing name's registration period.
• Wire `setTargetAddress()` to point the name at a Sui address.
• Wire `setDefault()` to set the reverse-lookup name for the signer.
• Wire `setUserData()` for custom key-value pairs (Walrus site, avatar, etc.).
• Wire `burnExpired()` to destroy expired names and recover storage deposits.
• See `references/suins-quickstart.md` for registration patterns and pricing.

5. **MVR integration (if needed)**

• For Move: run `mvr add @org/package --network mainnet` to add named dependencies.
• For TypeScript: use `namedPackagesPlugin` from `@mysten/sui/transactions` to resolve `@org/package` in PTBs at build time or runtime.
• For build-time resolution (no runtime network call): use `@mysten/mvr-static`.
• See `references/suins-quickstart.md` for M