@monadns/sdk 2.1.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @monadns/sdk
 
-Resolve and register **.mon** names on the Monad network. The official SDK for the [Monad Name Service](https://monadscan.com).
+Resolve and register **.mon** names on the Monad network. The official SDK for the [Monad Name Service](https://monadscan.com/address/0x98866c55adbc73ec6c272bb3604ddbdee3f282a8#readContract).
 
 ## Install
 
@@ -144,7 +144,11 @@ import { clearCache } from '@monadns/sdk';
 function RegisterPage() {
   const [label, setLabel] = useState('');
   const { address } = useAccount();
-  const { info, loading: checking } = useRegistrationInfo(label, address);
+  const {
+    info,
+    loading: checking,
+    error: checkError,
+  } = useRegistrationInfo(label, address);
   const { prepare, loading: preparing, error } = useMNSRegister();
   const { writeContract, data: hash } = useWriteContract();
   const { isLoading: confirming, isSuccess } = useWaitForTransactionReceipt({
@@ -171,8 +175,9 @@ function RegisterPage() {
       />
 
       {checking && <p className="text-gray-400">Checking availability...</p>}
+      {checkError && <p className="text-red-500">❌ {checkError}</p>}
 
-      {info && !checking && (
+      {info && !checking && !checkError && (
         <div className="space-y-2">
           <p>{info.available ? '✅ Available!' : '❌ Already taken'}</p>
 
@@ -303,6 +308,152 @@ function ProfileEditor({ name }: { name: string }) {
 }
 ```
 
+## Name Validation
+
+The SDK automatically validates names and provides clear error messages:
+
+```typescript
+import { validateMonName } from '@monadns/sdk';
+
+const validation = validateMonName('alice');
+if (!validation.valid) {
+  console.error(validation.error);
+}
+
+// Invalid examples that are rejected:
+validateMonName('0x123'); // ❌ "Name cannot start with "0x" (reserved for addresses)"
+validateMonName('hello--world'); // ❌ "Name cannot contain consecutive hyphens"
+validateMonName('-alice'); // ❌ "Name can only contain lowercase letters..."
+validateMonName('a'.repeat(64)); // ❌ "Name must be 63 characters or less"
+validateMonName(''); // ❌ "Name cannot be empty"
+
+// Valid examples:
+validateMonName('alice'); // ✅
+validateMonName('a'); // ✅ 1-character names allowed
+validateMonName('ab'); // ✅ 2-character names allowed
+validateMonName('web3-name'); // ✅ Hyphens allowed (not at start/end)
+```
+
+## Avatar Best Practices
+
+### Recommended Workflow (Enforced by SDK)
+
+```tsx
+import {
+  validateAvatarFull,
+  useMNSTextRecords,
+  MAX_AVATAR_BYTES,
+} from '@monadns/sdk/react';
+import { useWriteContract } from 'wagmi';
+
+function AvatarUploader({ name }: { name: string }) {
+  const [error, setError] = useState('');
+  const { setAvatarValidated } = useMNSTextRecords();
+  const { writeContract } = useWriteContract();
+
+  const handleUpload = async (url: string) => {
+    try {
+      setError('');
+
+      // SDK validates size automatically (throws if > 50KB)
+      const tx = await setAvatarValidated(name, url);
+      writeContract(tx);
+    } catch (e: any) {
+      setError(e.message);
+      // "Avatar file size (125.3KB) exceeds 50KB limit. Please optimize..."
+    }
+  };
+
+  return (
+    <div>
+      <input onChange={(e) => handleUpload(e.target.value)} />
+      {error && <p className="text-red-500">{error}</p>}
+      <p className="text-sm text-gray-500">
+        Max size: {(MAX_AVATAR_BYTES / 1024).toFixed(0)}KB (WebP/SVG
+        recommended)
+      </p>
+    </div>
+  );
+}
+```
+
+### Size Limits (Automatically Enforced)
+
+- **Data URIs**: Strict 50KB limit (enforced immediately)
+- **Remote URLs** (IPFS/HTTP): Validated when using `setAvatarValidated()`
+- **NFT avatars**: No size check (resolved at display time)
+
+### Supported Avatar Formats
+
+```typescript
+// ✅ HTTPS URLs
+setAvatar('alice.mon', 'https://example.com/avatar.png');
+
+// ✅ IPFS with protocol
+setAvatar('alice.mon', 'ipfs://QmX...');
+
+// ✅ Raw IPFS CID (auto-converted)
+setAvatar('alice.mon', 'QmX...'); // → ipfs://QmX...
+
+// ✅ Arweave
+setAvatar('alice.mon', 'ar://abc123...');
+
+// ✅ NFT avatar
+setAvatar('alice.mon', 'eip155:1/erc721:0x.../123');
+
+// ✅ Data URI (with size check)
+setAvatar('alice.mon', 'data:image/svg+xml;base64,...');
+```
+
+### Manual Validation (Advanced)
+
+```typescript
+import { validateAvatarUri, validateAvatarFull } from '@monadns/sdk';
+
+// Quick format check (synchronous)
+const validation = validateAvatarUri(avatarUrl);
+if (!validation.valid) {
+  console.error(validation.error);
+}
+
+// Full validation including size check (async)
+try {
+  await validateAvatarFull(avatarUrl);
+  // Safe to use
+} catch (error) {
+  console.error(error.message);
+  // "Avatar file size (65.3KB) exceeds 50KB limit..."
+}
+
+// Check remote file size
+import { getRemoteAvatarSize, MAX_AVATAR_BYTES } from '@monadns/sdk';
+
+const size = await getRemoteAvatarSize('https://example.com/avatar.png');
+if (size && size > MAX_AVATAR_BYTES) {
+  alert(`Avatar too large: ${(size / 1024).toFixed(1)}KB. Max is 50KB.`);
+}
+```
+
+### Fallback Avatars
+
+```typescript
+import { getAvatarUrl, DEFAULT_AVATAR_PLACEHOLDER } from '@monadns/sdk';
+
+// Use fallback if avatar not set or fails to resolve
+const avatar = await getAvatarUrl('alice.mon', undefined, {
+  fallback: DEFAULT_AVATAR_PLACEHOLDER,
+});
+```
+
+### Override Validation (Not Recommended)
+
+If you need to bypass validation (not recommended for production):
+
+```typescript
+// Use basic setAvatar() - only validates data URIs
+const tx = setAvatar(name, largeAvatarUrl); // Logs warning
+```
+
 ## Advanced Usage
 
 ### Check Name Ownership & Expiry
@@ -351,7 +502,7 @@ if (available) {
 | `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)  |
+| `getAvatarUrl(name, config, options)` | 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             |
@@ -361,6 +512,10 @@ if (available) {
 | `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 |
+| `validateMonName(label)`              | Validate .mon name format and rules           |
+| `validateAvatarUri(uri)`              | Validate avatar format and data URI size      |
+| `validateAvatarFull(uri)`             | Async validation including remote file size   |
+| `getRemoteAvatarSize(url)`            | Get file size of remote URL (helper for UI)   |
 
 ### React Hooks (`@monadns/sdk/react`)
 
@@ -377,9 +532,20 @@ if (available) {
 | `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       |
+| `useMNSTextRecords()`                 | `{ setAvatar, setAvatarValidated, setTwitter, ... }`                 | Prepare text record txs       |
 | `useMNSAddr()`                        | `{ setAddr }`                                                        | Prepare address update tx     |
 
+### Constants
+
+| Constant                     | Value                                        |
+| ---------------------------- | -------------------------------------------- |
+| `MAX_AVATAR_BYTES`           | `51200` (50KB)                               |
+| `DEFAULT_AVATAR_PLACEHOLDER` | Transparent 1x1 SVG data URI                 |
+| `MNS_REGISTRY`               | `0x13f963486e741c8d3fcdc0a34a910920339a19ce` |
+| `MNS_PUBLIC_RESOLVER`        | `0xa2eb94c88e55d944aced2066c5cec9b759801f97` |
+| `MNS_CONTROLLER`             | `0x98866c55adbc73ec6c272bb3604ddbdee3f282a8` |
+| `MNS_BASE_REGISTRAR`         | `0x104a49db9318c284d462841b6940bdb46624ca55` |
+
 ### Custom RPC
 
 All functions accept an optional config object:
@@ -412,33 +578,43 @@ const name = await lookupAddress('0x...', { client });
 
 **Chain:** Monad Mainnet (Chain ID 143)
 
-## Migrating from v2.0 to v2.1
+## Changelog
 
-### Breaking Changes
+### v2.3.0
 
-**`isRegistered()` has been renamed to `getAvailable()` with inverted logic**
+**New Features:**
 
-**Before (v2.0):**
+- **Name validation**: Added `validateMonName()` function with comprehensive validation rules
+- **1 & 2-character names**: Removed artificial 3-character minimum - all lengths now supported
+- **0x prefix protection**: Names cannot start with "0x" to prevent confusion with addresses
+- **Automatic validation**: `useRegistrationInfo()` and write functions now validate names automatically
 
-```typescript
-const registered = await isRegistered('alice.mon');
-if (registered) {
-  console.log('Name is taken');
-}
-```
+**Improvements:**
 
-**After (v2.1):**
+- Better error messages for invalid names
+- Validation happens client-side before RPC calls (faster feedback)
+- Consistent validation across all entry points
 
-```typescript
-const available = await getAvailable('alice.mon');
-if (available) {
-  console.log('Name is available for registration');
-} else {
-  console.log('Name is taken');
-}
-```
+### v2.2.0
+
+**New Features:**
+
+- **Avatar validation**: `validateAvatarUri()` and `validateAvatarFull()` for size checking
+- **Avatar constants**: `MAX_AVATAR_BYTES` (50KB limit) and `DEFAULT_AVATAR_PLACEHOLDER`
+- **Enhanced avatar resolution**: Support for raw IPFS CIDs and Arweave URIs
+- **Validated avatar setter**: `setAvatarValidated()` hook with automatic size validation
+- **Size helper**: `getRemoteAvatarSize()` for checking remote file sizes
+- **Fallback support**: `getAvatarUrl()` now accepts fallback option
+
+**Behavior Changes:**
 
-### New Features
+- Data URI avatars are now strictly limited to 50KB (throws error if exceeded)
+- Setting non-data-URI avatars without validation logs a warning
+- `getAvatarUrl()` now handles raw IPFS CIDs (e.g., `QmX...`) automatically
+
+### v2.1.0
+
+**New Features:**
 
 - `getOwner(name)` - Get the owner of a name
 - `getResolver(name)` - Get the resolver contract
@@ -448,6 +624,10 @@ if (available) {
 - `useMNSExpiry(name)` - React hook for expiry info with computed fields
 - `MNS_BASE_REGISTRAR` constant now exported
 
+**Breaking Changes:**
+
+- `isRegistered()` → `getAvailable()` (inverted boolean logic)
+
 ## Compatibility
 
 - **Frameworks:** React 17+, Next.js (App Router & Pages), Remix, Vite, CRA

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  DEFAULT_AVATAR_PLACEHOLDER: () => DEFAULT_AVATAR_PLACEHOLDER,
+  MAX_AVATAR_BYTES: () => MAX_AVATAR_BYTES,
   MNS_BASE_REGISTRAR: () => MNS_BASE_REGISTRAR,
   MNS_CONTROLLER: () => MNS_CONTROLLER,
   MNS_PUBLIC_RESOLVER: () => MNS_PUBLIC_RESOLVER,
@@ -36,6 +38,7 @@ __export(src_exports, {
   getOwner: () => getOwner,
   getRegisterTx: () => getRegisterTx,
   getRegistrationInfo: () => getRegistrationInfo,
+  getRemoteAvatarSize: () => getRemoteAvatarSize,
   getResolver: () => getResolver,
   getSetAddrTx: () => getSetAddrTx,
   getSetTextTx: () => getSetTextTx,
@@ -43,7 +46,10 @@ __export(src_exports, {
   lookupAddress: () => lookupAddress,
   resolveInput: () => resolveInput,
   resolveName: () => resolveName,
-  resolverWriteAbi: () => resolverWriteAbi
+  resolverWriteAbi: () => resolverWriteAbi,
+  validateAvatarFull: () => validateAvatarFull,
+  validateAvatarUri: () => validateAvatarUri,
+  validateMonName: () => validateMonName
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -77,6 +83,8 @@ var MNS_PUBLIC_RESOLVER = "0xa2eb94c88e55d944aced2066c5cec9b759801f97";
 var MNS_CONTROLLER = "0x98866c55adbc73ec6c272bb3604ddbdee3f282a8";
 var MNS_BASE_REGISTRAR = "0x104a49db9318c284d462841b6940bdb46624ca55";
 var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var MAX_AVATAR_BYTES = 51200;
+var DEFAULT_AVATAR_PLACEHOLDER = 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg"%3E%3C/svg%3E';
 var registryAbi = [
   {
     name: "resolver",
@@ -285,21 +293,28 @@ async function resolveInput(input, config) {
   if (trimmed.endsWith(".mon")) return resolveName(trimmed, config);
   return resolveName(`${trimmed}.mon`, config);
 }
-async function getAvatarUrl(name, config) {
+async function getAvatarUrl(name, config, options) {
   const raw = await getTextRecord(name, "avatar", config);
-  if (!raw) return null;
-  if (raw.startsWith("http://") || raw.startsWith("https://")) {
-    return raw;
-  }
-  if (raw.startsWith("ipfs://")) {
-    const hash = raw.slice(7);
-    return `https://ipfs.io/ipfs/${hash}`;
-  }
-  const nftMatch = raw.match(
-    /^eip155:(\d+)\/(erc721|erc1155):0x([a-fA-F0-9]{40})\/(\d+)$/
-  );
-  if (nftMatch) {
-    try {
+  if (!raw) return options?.fallback || null;
+  try {
+    if (raw.startsWith("http://") || raw.startsWith("https://")) {
+      return raw;
+    }
+    if (raw.startsWith("ipfs://")) {
+      const hash = raw.slice(7);
+      return `https://ipfs.io/ipfs/${hash}`;
+    }
+    if (/^(Qm[1-9A-HJ-NP-Za-km-z]{44}|bafy[0-9A-Za-z]{50,})/.test(raw)) {
+      return `https://ipfs.io/ipfs/${raw}`;
+    }
+    if (raw.startsWith("ar://")) {
+      const hash = raw.slice(5);
+      return `https://arweave.net/${hash}`;
+    }
+    const nftMatch = raw.match(
+      /^eip155:(\d+)\/(erc721|erc1155):0x([a-fA-F0-9]{40})\/(\d+)$/
+    );
+    if (nftMatch) {
       const client = getMNSClient(config);
       const contract = `0x${nftMatch[3]}`;
       const tokenId = BigInt(nftMatch[4]);
@@ -327,15 +342,16 @@ async function getAvatarUrl(name, config) {
       if (image && image.startsWith("ipfs://")) {
         image = `https://ipfs.io/ipfs/${image.slice(7)}`;
       }
-      return image;
-    } catch {
-      return null;
+      return image || options?.fallback || null;
     }
+    if (raw.startsWith("data:")) {
+      return raw;
+    }
+    return options?.fallback || null;
+  } catch (error) {
+    console.warn("Failed to resolve avatar:", error);
+    return options?.fallback || null;
   }
-  if (raw.startsWith("data:")) {
-    return raw;
-  }
-  return null;
 }
 function clearCache() {
   nameCache.clear();
@@ -344,6 +360,127 @@ function clearCache() {
 
 // src/write.ts
 var import_viem3 = require("viem");
+
+// src/utils.ts
+function validateMonName(label) {
+  if (!label || label.trim().length === 0) {
+    return { valid: false, error: "Name cannot be empty" };
+  }
+  const trimmed = label.trim().toLowerCase();
+  if (trimmed.startsWith("0x")) {
+    return {
+      valid: false,
+      error: 'Name cannot start with "0x" (reserved for addresses)'
+    };
+  }
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(trimmed)) {
+    return {
+      valid: false,
+      error: "Name can only contain lowercase letters, numbers, and hyphens (not at start/end)"
+    };
+  }
+  if (trimmed.includes("--")) {
+    return { valid: false, error: "Name cannot contain consecutive hyphens" };
+  }
+  if (trimmed.length > 63) {
+    return { valid: false, error: "Name must be 63 characters or less" };
+  }
+  return { valid: true };
+}
+function validateAvatarUri(uri) {
+  if (!uri) {
+    return { valid: false, error: "Avatar URI is required" };
+  }
+  if (uri.startsWith("data:")) {
+    const sizeBytes = new Blob([uri]).size;
+    if (sizeBytes > MAX_AVATAR_BYTES) {
+      return {
+        valid: false,
+        error: `Avatar size (${(sizeBytes / 1024).toFixed(1)}KB) exceeds ${MAX_AVATAR_BYTES / 1024}KB limit. Please optimize as WebP or SVG for better performance.`,
+        sizeBytes
+      };
+    }
+    return { valid: true, sizeBytes };
+  }
+  const validSchemes = ["http://", "https://", "ipfs://", "eip155:", "ar://"];
+  const hasValidScheme = validSchemes.some((scheme) => uri.startsWith(scheme));
+  if (!hasValidScheme) {
+    if (/^(Qm[1-9A-HJ-NP-Za-km-z]{44}|bafy[0-9A-Za-z]{50,})/.test(uri)) {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: "Avatar must be a valid HTTP, IPFS, Arweave, or NFT URI"
+    };
+  }
+  return { valid: true };
+}
+async function validateAvatarFull(uri, options) {
+  const maxBytes = options?.maxBytes || MAX_AVATAR_BYTES;
+  const timeout = options?.timeout || 5e3;
+  const formatValidation = validateAvatarUri(uri);
+  if (!formatValidation.valid) {
+    throw new Error(formatValidation.error);
+  }
+  if (uri.startsWith("data:")) {
+    return { valid: true, sizeBytes: formatValidation.sizeBytes };
+  }
+  if (uri.startsWith("eip155:")) {
+    return { valid: true };
+  }
+  let checkUrl = uri;
+  if (uri.startsWith("ipfs://")) {
+    checkUrl = `https://ipfs.io/ipfs/${uri.slice(7)}`;
+  } else if (/^(Qm[1-9A-HJ-NP-Za-km-z]{44}|bafy[0-9A-Za-z]{50,})/.test(uri)) {
+    checkUrl = `https://ipfs.io/ipfs/${uri}`;
+  } else if (uri.startsWith("ar://")) {
+    checkUrl = `https://arweave.net/${uri.slice(5)}`;
+  }
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const response = await fetch(checkUrl, {
+      method: "HEAD",
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    const contentLength = response.headers.get("content-length");
+    if (contentLength) {
+      const sizeBytes = parseInt(contentLength, 10);
+      if (sizeBytes > maxBytes) {
+        throw new Error(
+          `Avatar file size (${(sizeBytes / 1024).toFixed(1)}KB) exceeds ${maxBytes / 1024}KB limit. Please optimize as WebP or SVG for better performance.`
+        );
+      }
+      return { valid: true, sizeBytes };
+    }
+    console.warn(
+      `Could not determine avatar size for ${uri}. Ensure it's under ${maxBytes / 1024}KB.`
+    );
+    return { valid: true };
+  } catch (error) {
+    if (error.name === "AbortError") {
+      console.warn(`Avatar size check timed out for ${uri}`);
+      return { valid: true };
+    }
+    if (error.message.includes("exceeds")) {
+      throw error;
+    }
+    console.warn(`Could not check avatar size: ${error.message}`);
+    return { valid: true };
+  }
+}
+async function getRemoteAvatarSize(url) {
+  try {
+    const response = await fetch(url, { method: "HEAD" });
+    const contentLength = response.headers.get("content-length");
+    return contentLength ? parseInt(contentLength, 10) : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/write.ts
 var controllerReadAbi = [
   {
     name: "available",
@@ -408,6 +545,10 @@ var resolverWriteAbi = [
 ];
 var ONE_YEAR = BigInt(365 * 24 * 60 * 60);
 async function getRegistrationInfo(label, userAddress, durationYears = 1, config) {
+  const validation = validateMonName(label);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
   const client = getMNSClient(config);
   const duration = ONE_YEAR * BigInt(durationYears);
   const [available, price, hasClaimed, balance] = await Promise.all([
@@ -435,6 +576,10 @@ async function getRegistrationInfo(label, userAddress, durationYears = 1, config
   return { available, price, isFreebie, hasClaimed, duration, label };
 }
 async function getRegisterTx(label, ownerAddress, durationYears = 1, config) {
+  const validation = validateMonName(label);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
   const info = await getRegistrationInfo(
     label,
     ownerAddress,
@@ -460,6 +605,17 @@ async function getRegisterTx(label, ownerAddress, durationYears = 1, config) {
   };
 }
 function getSetTextTx(name, key, value) {
+  if (key === "avatar" && value.startsWith("data:")) {
+    const validation = validateAvatarUri(value);
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+  }
+  if (key === "avatar" && !value.startsWith("data:")) {
+    console.warn(
+      "\u26A0\uFE0F Avatar set without size validation. For best practices, use setAvatarValidated() or validateAvatarFull() before calling setAvatar()."
+    );
+  }
   const node = (0, import_viem3.namehash)(
     name.endsWith(".mon") ? name : `${name}.mon`
   );
@@ -493,6 +649,8 @@ var TEXT_RECORD_KEYS = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_AVATAR_PLACEHOLDER,
+  MAX_AVATAR_BYTES,
   MNS_BASE_REGISTRAR,
   MNS_CONTROLLER,
   MNS_PUBLIC_RESOLVER,
@@ -509,6 +667,7 @@ var TEXT_RECORD_KEYS = {
   getOwner,
   getRegisterTx,
   getRegistrationInfo,
+  getRemoteAvatarSize,
   getResolver,
   getSetAddrTx,
   getSetTextTx,
@@ -516,6 +675,9 @@ var TEXT_RECORD_KEYS = {
   lookupAddress,
   resolveInput,
   resolveName,
-  resolverWriteAbi
+  resolverWriteAbi,
+  validateAvatarFull,
+  validateAvatarUri,
+  validateMonName
 });
 //# sourceMappingURL=index.cjs.map