@monadns/sdk 2.1.0 → 2.2.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
 
@@ -15,10 +15,10 @@ import { resolveName, lookupAddress } from '@monadns/sdk';
 
 // Forward: name → address
 const address = await resolveName('alice.mon');
-// '0xa05a8BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47'
+// '0xa1238BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47'
 
 // Reverse: address → name
-const name = await lookupAddress('0xa05a8BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47');
+const name = await lookupAddress('0xa1238BF1eda5bbC2b3aCAF03D04f77bD7d66Cc47');
 // 'alice.mon'
 ```
 
@@ -303,6 +303,126 @@ function ProfileEditor({ name }: { name: string }) {
 }
 ```
 
+## 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 +471,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 +481,9 @@ 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 |
+| `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 +500,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,6 +546,23 @@ const name = await lookupAddress('0x...', { client });
 
 **Chain:** Monad Mainnet (Chain ID 143)
 
+## Migrating from v2.1 to v2.2
+
+### 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
+
+- 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
+
 ## Migrating from v2.0 to v2.1
 
 ### Breaking Changes
@@ -427,7 +578,7 @@ if (registered) {
 }
 ```
 
-**After (v2.1):**
+**After (v2.1+):**
 
 ```typescript
 const available = await getAvailable('alice.mon');
@@ -438,16 +589,6 @@ if (available) {
 }
 ```
 
-### 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
 
 - **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,9 @@ __export(src_exports, {
   lookupAddress: () => lookupAddress,
   resolveInput: () => resolveInput,
   resolveName: () => resolveName,
-  resolverWriteAbi: () => resolverWriteAbi
+  resolverWriteAbi: () => resolverWriteAbi,
+  validateAvatarFull: () => validateAvatarFull,
+  validateAvatarUri: () => validateAvatarUri
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -77,6 +82,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 +292,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 +341,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 +359,102 @@ function clearCache() {
 
 // src/write.ts
 var import_viem3 = require("viem");
+
+// src/utils.ts
+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",
@@ -460,6 +571,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 +615,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 +633,7 @@ var TEXT_RECORD_KEYS = {
   getOwner,
   getRegisterTx,
   getRegistrationInfo,
+  getRemoteAvatarSize,
   getResolver,
   getSetAddrTx,
   getSetTextTx,
@@ -516,6 +641,8 @@ var TEXT_RECORD_KEYS = {
   lookupAddress,
   resolveInput,
   resolveName,
-  resolverWriteAbi
+  resolverWriteAbi,
+  validateAvatarFull,
+  validateAvatarUri
 });
 //# sourceMappingURL=index.cjs.map