@monadns/sdk 1.0.0 → 2.1.0

package/LICENSE

@@ -1,21 +1,24 @@
-MIT License
+This is free and unencumbered software released into the public domain.
 
-Copyright (c) 2026 Monad Name Service
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,6 +1,6 @@
 # @monadns/sdk
 
-Resolve **.mon** names on the Monad network. The official SDK for the Monad Name Service.
+Resolve and register **.mon** names on the Monad network. The official SDK for the [Monad Name Service](https://monadscan.com).
 
 ## Install
 
@@ -15,31 +15,45 @@ import { resolveName, lookupAddress } from '@monadns/sdk';
 
 // Forward: name → address
 const address = await resolveName('alice.mon');
-// '0xa0123BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47'
+// '0xa05a8BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47'
 
 // Reverse: address → name
-const name = await lookupAddress('0xa0123BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47');
+const name = await lookupAddress('0xa05a8BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47');
 // 'alice.mon'
 ```
 
 ## React Hooks
 
+All hooks are compatible with Next.js App Router, Remix, and any React 17+ framework. The `'use client'` directive is included in the build.
+
 ```bash
 npm install @monadns/sdk viem react
 ```
 
+### Display .mon names
+
 ```tsx
-import { useMNSDisplay, useMNSResolve } from '@monadns/sdk/react';
+import { useMNSDisplay } from '@monadns/sdk/react';
 
-// Display .mon name instead of address
 function UserBadge({ address }: { address: string }) {
-  const { displayName, monName } = useMNSDisplay(address);
-  return <span className={monName ? 'font-bold' : ''}>{displayName}</span>;
+  const { displayName, monName, loading } = useMNSDisplay(address);
+
+  return (
+    <span className={monName ? 'text-purple-400 font-bold' : 'text-gray-400'}>
+      {loading ? '...' : displayName}
+    </span>
+  );
 }
+```
+
+### Resolve input (name or address)
+
+```tsx
+import { useMNSResolve } from '@monadns/sdk/react';
 
-// Input field that accepts names or addresses
 function RecipientInput() {
-  const { resolve, address, loading, error } = useMNSResolve();
+  const { resolve, address, name, loading, error } = useMNSResolve();
+
   return (
     <div>
       <input
@@ -47,36 +61,324 @@ function RecipientInput() {
         onChange={(e) => resolve(e.target.value)}
       />
       {loading && <span>Resolving...</span>}
-      {address && <span>→ {address}</span>}
-      {error && <span>{error}</span>}
+      {error && <span className="text-red-500">{error}</span>}
+      {address && <span className="text-green-500">→ {address}</span>}
+    </div>
+  );
+}
+```
+
+### Get avatar
+
+```tsx
+import { useMNSAvatar } from '@monadns/sdk/react';
+
+function Avatar({ name }: { name: string }) {
+  const { url, loading } = useMNSAvatar(name);
+  if (loading)
+    return <div className="animate-pulse w-10 h-10 rounded-full bg-gray-700" />;
+  return url ? <img src={url} className="w-10 h-10 rounded-full" /> : null;
+}
+```
+
+### Get text records
+
+```tsx
+import { useMNSText } from '@monadns/sdk/react';
+
+function Twitter({ name }: { name: string }) {
+  const { value: handle } = useMNSText(name, 'com.twitter');
+  return handle ? <a href={`https://x.com/${handle}`}>@{handle}</a> : null;
+}
+```
+
+### Check ownership and expiry
+
+```tsx
+import { useMNSOwner, useMNSExpiry } from '@monadns/sdk/react';
+
+function NameInfo({ name }: { name: string }) {
+  const { owner, loading: ownerLoading } = useMNSOwner(name);
+  const {
+    daysUntilExpiry,
+    isExpired,
+    loading: expiryLoading,
+  } = useMNSExpiry(name);
+
+  if (ownerLoading || expiryLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>Owner: {owner}</p>
+      {isExpired ? (
+        <p className="text-red-500">This name has expired!</p>
+      ) : (
+        <p>Expires in {daysUntilExpiry} days</p>
+      )}
     </div>
   );
 }
 ```
 
+## Registration (with wagmi)
+
+The SDK returns transaction parameters that work directly with wagmi's `useWriteContract`:
+
+```bash
+npm install @monadns/sdk viem wagmi @tanstack/react-query
+```
+
+### Full Registration Page
+
+```tsx
+import { useState } from 'react';
+import {
+  useAccount,
+  useWriteContract,
+  useWaitForTransactionReceipt,
+} from 'wagmi';
+import { formatEther } from 'viem';
+import { useRegistrationInfo, useMNSRegister } from '@monadns/sdk/react';
+import { clearCache } from '@monadns/sdk';
+
+function RegisterPage() {
+  const [label, setLabel] = useState('');
+  const { address } = useAccount();
+  const { info, loading: checking } = useRegistrationInfo(label, address);
+  const { prepare, loading: preparing, error } = useMNSRegister();
+  const { writeContract, data: hash } = useWriteContract();
+  const { isLoading: confirming, isSuccess } = useWaitForTransactionReceipt({
+    hash,
+  });
+
+  const handleRegister = async () => {
+    const tx = await prepare(label, address!);
+    if (tx) writeContract(tx);
+  };
+
+  // Clear cache after successful registration so lookups reflect new state
+  if (isSuccess) clearCache();
+
+  return (
+    <div className="max-w-md mx-auto p-6">
+      <h1 className="text-2xl font-bold mb-4">Register a .mon name</h1>
+
+      <input
+        className="w-full p-3 border rounded-lg mb-4"
+        placeholder="Search for a name..."
+        value={label}
+        onChange={(e) => setLabel(e.target.value)}
+      />
+
+      {checking && <p className="text-gray-400">Checking availability...</p>}
+
+      {info && !checking && (
+        <div className="space-y-2">
+          <p>{info.available ? '✅ Available!' : '❌ Already taken'}</p>
+
+          {info.available && (
+            <>
+              <p className="text-lg">
+                {info.isFreebie
+                  ? '🎉 FREE for 100 years!'
+                  : `${formatEther(info.price)} MON / year`}
+              </p>
+
+              <button
+                className="w-full bg-purple-600 text-white p-3 rounded-lg disabled:opacity-50"
+                onClick={handleRegister}
+                disabled={preparing || confirming}
+              >
+                {confirming
+                  ? 'Confirming...'
+                  : preparing
+                    ? 'Preparing...'
+                    : `Register ${label}.mon`}
+              </button>
+            </>
+          )}
+        </div>
+      )}
+
+      {error && <p className="text-red-500 mt-2">❌ {error}</p>}
+      {isSuccess && (
+        <p className="text-green-500 mt-4">🎉 {label}.mon is yours!</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Profile Editor (Avatar, Twitter, Bio)
+
+```tsx
+import { useState } from 'react';
+import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
+import { useMNSText, useMNSTextRecords } from '@monadns/sdk/react';
+
+function ProfileEditor({ name }: { name: string }) {
+  const { value: currentAvatar } = useMNSText(name, 'avatar');
+  const { value: currentTwitter } = useMNSText(name, 'com.twitter');
+  const { value: currentBio } = useMNSText(name, 'description');
+
+  const { setAvatar, setTwitter, setDescription } = useMNSTextRecords();
+  const { writeContract, data: hash } = useWriteContract();
+  const { isLoading: saving, isSuccess } = useWaitForTransactionReceipt({
+    hash,
+  });
+
+  const [avatar, setAvatarUrl] = useState('');
+  const [twitter, setTwitterHandle] = useState('');
+  const [bio, setBio] = useState('');
+
+  return (
+    <div className="max-w-md mx-auto p-6 space-y-4">
+      <h2 className="text-xl font-bold">Edit {name} Profile</h2>
+
+      {currentAvatar && (
+        <img src={currentAvatar} className="w-20 h-20 rounded-full" />
+      )}
+
+      <div>
+        <label className="block text-sm font-medium mb-1">Avatar URL</label>
+        <div className="flex gap-2">
+          <input
+            className="flex-1 p-2 border rounded"
+            placeholder={currentAvatar || 'https://example.com/avatar.png'}
+            value={avatar}
+            onChange={(e) => setAvatarUrl(e.target.value)}
+          />
+          <button
+            className="px-4 py-2 bg-purple-600 text-white rounded disabled:opacity-50"
+            onClick={() => writeContract(setAvatar(name, avatar))}
+            disabled={saving || !avatar}
+          >
+            Save
+          </button>
+        </div>
+      </div>
+
+      <div>
+        <label className="block text-sm font-medium mb-1">Twitter</label>
+        <div className="flex gap-2">
+          <input
+            className="flex-1 p-2 border rounded"
+            placeholder={currentTwitter || '@handle'}
+            value={twitter}
+            onChange={(e) => setTwitterHandle(e.target.value)}
+          />
+          <button
+            className="px-4 py-2 bg-purple-600 text-white rounded disabled:opacity-50"
+            onClick={() => writeContract(setTwitter(name, twitter))}
+            disabled={saving || !twitter}
+          >
+            Save
+          </button>
+        </div>
+      </div>
+
+      <div>
+        <label className="block text-sm font-medium mb-1">Bio</label>
+        <div className="flex gap-2">
+          <input
+            className="flex-1 p-2 border rounded"
+            placeholder={currentBio || 'Tell the world about yourself'}
+            value={bio}
+            onChange={(e) => setBio(e.target.value)}
+          />
+          <button
+            className="px-4 py-2 bg-purple-600 text-white rounded disabled:opacity-50"
+            onClick={() => writeContract(setDescription(name, bio))}
+            disabled={saving || !bio}
+          >
+            Save
+          </button>
+        </div>
+      </div>
+
+      {saving && <p className="text-gray-400">⏳ Saving to blockchain...</p>}
+      {isSuccess && <p className="text-green-500">✅ Profile updated!</p>}
+    </div>
+  );
+}
+```
+
+## Advanced Usage
+
+### Check Name Ownership & Expiry
+
+```typescript
+import { getOwner, getExpiry, getResolver } from '@monadns/sdk';
+
+// Check who owns a name
+const owner = await getOwner('alice.mon');
+console.log('Owner:', owner);
+
+// Check when it expires
+const expiry = await getExpiry('alice.mon');
+const expiryDate = new Date(expiry * 1000);
+const daysLeft = Math.floor(
+  (expiry * 1000 - Date.now()) / (1000 * 60 * 60 * 24),
+);
+console.log(`Expires: ${expiryDate.toLocaleDateString()} (${daysLeft} days)`);
+
+// Get resolver contract
+const resolver = await getResolver('alice.mon');
+console.log('Resolver:', resolver);
+```
+
+### Check Availability Before Registration
+
+```typescript
+import { getAvailable } from '@monadns/sdk';
+
+const available = await getAvailable('alice.mon');
+if (available) {
+  console.log('alice.mon is available for registration!');
+} else {
+  console.log('alice.mon is already taken');
+}
+```
+
 ## API Reference
 
-### Core Functions
+### Core Functions (`@monadns/sdk`)
 
-| Function                   | Description                              |
-| -------------------------- | ---------------------------------------- |
-| `resolveName(name)`        | Forward resolve: `alice.mon` → `0x...`   |
-| `lookupAddress(address)`   | Reverse resolve: `0x...` → `alice.mon`   |
-| `getDisplayName(address)`  | Returns `.mon` name or truncated address |
-| `resolveInput(input)`      | Accepts name or address, returns address |
-| `getTextRecord(name, key)` | Get text record (avatar, url, etc.)      |
-| `isRegistered(name)`       | Check if a name is taken                 |
-| `clearCache()`             | Clear the resolution cache               |
+| Function                              | Description                                   |
+| ------------------------------------- | --------------------------------------------- |
+| `resolveName(name)`                   | Forward resolve: `alice.mon` → `0x...`        |
+| `lookupAddress(address)`              | Reverse resolve: `0x...` → `alice.mon`        |
+| `getDisplayName(address)`             | Returns `.mon` name or truncated address      |
+| `resolveInput(input)`                 | Accepts name or address, returns address      |
+| `getTextRecord(name, key)`            | Get text record (avatar, url, etc.)           |
+| `getAvatarUrl(name)`                  | Get resolved avatar URL (handles IPFS, NFTs)  |
+| `getAvailable(name)`                  | Check if a name is available for registration |
+| `getOwner(name)`                      | Get the owner address of a name               |
+| `getResolver(name)`                   | Get the resolver contract address             |
+| `getExpiry(name)`                     | Get expiry timestamp (Unix seconds)           |
+| `clearCache()`                        | Clear the resolution cache                    |
+| `getRegistrationInfo(label, address)` | Get price, availability, freebie status       |
+| `getRegisterTx(label, address)`       | Get tx params for registration                |
+| `getSetTextTx(name, key, value)`      | Get tx params for setting a text record       |
+| `getSetAddrTx(name, address)`         | Get tx params for updating the address record |
 
-### React Hooks
+### React Hooks (`@monadns/sdk/react`)
 
-| Hook                     | Description                                  |
-| ------------------------ | -------------------------------------------- |
-| `useMNSName(address)`    | `{ name, loading, error }`                   |
-| `useMNSAddress(name)`    | `{ address, loading, error }`                |
-| `useMNSDisplay(address)` | `{ displayName, monName, loading }`          |
-| `useMNSResolve()`        | `{ resolve, address, name, loading, error }` |
-| `useMNSText(name, key)`  | `{ value, loading, error }`                  |
+| Hook                                  | Returns                                                              | Description                   |
+| ------------------------------------- | -------------------------------------------------------------------- | ----------------------------- |
+| `useMNSName(address)`                 | `{ name, loading, error }`                                           | Reverse resolution            |
+| `useMNSAddress(name)`                 | `{ address, loading, error }`                                        | Forward resolution            |
+| `useMNSDisplay(address)`              | `{ displayName, monName, loading }`                                  | Display-ready name            |
+| `useMNSResolve()`                     | `{ resolve, address, name, loading, error }`                         | On-demand resolver for inputs |
+| `useMNSText(name, key)`               | `{ value, loading, error }`                                          | Read text records             |
+| `useMNSAvatar(name)`                  | `{ url, loading, error }`                                            | Resolved avatar URL           |
+| `useMNSOwner(name)`                   | `{ owner, loading, error }`                                          | Get name owner                |
+| `useMNSResolver(name)`                | `{ resolver, loading, error }`                                       | Get resolver address          |
+| `useMNSExpiry(name)`                  | `{ expiry, expiryDate, daysUntilExpiry, isExpired, loading, error }` | Get expiration info           |
+| `useRegistrationInfo(label, address)` | `{ info, loading, error }`                                           | Pre-registration data         |
+| `useMNSRegister()`                    | `{ prepare, tx, loading, error }`                                    | Prepare registration tx       |
+| `useMNSTextRecords()`                 | `{ setAvatar, setTwitter, ... }`                                     | Prepare text record txs       |
+| `useMNSAddr()`                        | `{ setAddr }`                                                        | Prepare address update tx     |
 
 ### Custom RPC
 
@@ -100,13 +402,59 @@ const name = await lookupAddress('0x...', { client });
 
 ## Contracts
 
-| Contract        | Address                                      |
-| --------------- | -------------------------------------------- |
-| Registry        | `0x13f963486e741c8d3fcdc0a34a910920339a19ce` |
-| Public Resolver | `0xa2eb94c88e55d944aced2066c5cec9b759801f97` |
+| Contract          | Address                                      |
+| ----------------- | -------------------------------------------- |
+| Registry          | `0x13f963486e741c8d3fcdc0a34a910920339a19ce` |
+| Public Resolver   | `0xa2eb94c88e55d944aced2066c5cec9b759801f97` |
+| Controller        | `0x98866c55adbc73ec6c272bb3604ddbdee3f282a8` |
+| Base Registrar    | `0x104a49db9318c284d462841b6940bdb46624ca55` |
+| Reverse Registrar | `0x6fff58419ad964f2357590c3f1bae576ebe45f52` |
+
+**Chain:** Monad Mainnet (Chain ID 143)
+
+## Migrating from v2.0 to v2.1
+
+### Breaking Changes
+
+**`isRegistered()` has been renamed to `getAvailable()` with inverted logic**
+
+**Before (v2.0):**
+
+```typescript
+const registered = await isRegistered('alice.mon');
+if (registered) {
+  console.log('Name is taken');
+}
+```
+
+**After (v2.1):**
+
+```typescript
+const available = await getAvailable('alice.mon');
+if (available) {
+  console.log('Name is available for registration');
+} else {
+  console.log('Name is taken');
+}
+```
+
+### New Features
+
+- `getOwner(name)` - Get the owner of a name
+- `getResolver(name)` - Get the resolver contract
+- `getExpiry(name)` - Get expiration timestamp
+- `useMNSOwner(name)` - React hook for ownership info
+- `useMNSResolver(name)` - React hook for resolver info
+- `useMNSExpiry(name)` - React hook for expiry info with computed fields
+- `MNS_BASE_REGISTRAR` constant now exported
+
+## Compatibility
 
-Chain: Monad Mainnet (Chain ID 143)
+- **Frameworks:** React 17+, Next.js (App Router & Pages), Remix, Vite, CRA
+- **Wallet libraries:** wagmi, RainbowKit, ConnectKit, Privy, or any viem-based client
+- **Non-React:** All core functions work without React in any JS/TS environment
+- **Server-side:** Core functions can run in Node.js, edge functions, or API routes
 
 ## License
 
-MIT
+[Unlicense](https://unlicense.org) – public domain, no attribution required.