@monadns/sdk 2.0.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'
 ```
 
@@ -92,6 +92,34 @@ function Twitter({ name }: { name: string }) {
 }
 ```
 
+### 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`:
@@ -275,6 +303,163 @@ 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
+
+```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 (`@monadns/sdk`)
@@ -286,28 +471,48 @@ function ProfileEditor({ name }: { name: string }) {
 | `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)  |
-| `isRegistered(name)`                  | Check if a name is taken                      |
+| `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             |
+| `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 |
+| `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`)
 
-| 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           |
-| `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     |
+| 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, 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
 
@@ -341,6 +546,49 @@ 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
+
+**`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');
+}
+```
+
 ## Compatibility
 
 - **Frameworks:** React 17+, Next.js (App Router & Pages), Remix, Vite, CRA
@@ -350,4 +598,4 @@ const name = await lookupAddress('0x...', { client });
 
 ## License
 
-[Unlicense](https://unlicense.org) — public domain, no attribution required.
+[Unlicense](https://unlicense.org) – public domain, no attribution required.

package/dist/index.cjs

@@ -20,6 +20,9 @@ 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,
   MNS_REGISTRY: () => MNS_REGISTRY,
@@ -27,19 +30,25 @@ __export(src_exports, {
   clearCache: () => clearCache,
   controllerReadAbi: () => controllerReadAbi,
   controllerWriteAbi: () => controllerWriteAbi,
+  getAvailable: () => getAvailable,
   getAvatarUrl: () => getAvatarUrl,
   getDisplayName: () => getDisplayName,
+  getExpiry: () => getExpiry,
   getMNSClient: () => getMNSClient,
+  getOwner: () => getOwner,
   getRegisterTx: () => getRegisterTx,
   getRegistrationInfo: () => getRegistrationInfo,
+  getRemoteAvatarSize: () => getRemoteAvatarSize,
+  getResolver: () => getResolver,
   getSetAddrTx: () => getSetAddrTx,
   getSetTextTx: () => getSetTextTx,
   getTextRecord: () => getTextRecord,
-  isRegistered: () => isRegistered,
   lookupAddress: () => lookupAddress,
   resolveInput: () => resolveInput,
   resolveName: () => resolveName,
-  resolverWriteAbi: () => resolverWriteAbi
+  resolverWriteAbi: () => resolverWriteAbi,
+  validateAvatarFull: () => validateAvatarFull,
+  validateAvatarUri: () => validateAvatarUri
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -71,7 +80,10 @@ function getMNSClient(config) {
 var MNS_REGISTRY = "0x13f963486e741c8d3fcdc0a34a910920339a19ce";
 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",
@@ -79,6 +91,13 @@ var registryAbi = [
     inputs: [{ name: "node", type: "bytes32" }],
     outputs: [{ name: "", type: "address" }],
     stateMutability: "view"
+  },
+  {
+    name: "owner",
+    type: "function",
+    inputs: [{ name: "node", type: "bytes32" }],
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view"
   }
 ];
 var resolverAbi = [
@@ -203,6 +222,64 @@ async function getTextRecord(name, key, config) {
     return null;
   }
 }
+async function getOwner(name, config) {
+  try {
+    const client = getMNSClient(config);
+    const node = (0, import_viem2.namehash)(name.toLowerCase());
+    const owner = await client.readContract({
+      address: MNS_REGISTRY,
+      abi: registryAbi,
+      functionName: "owner",
+      args: [node]
+    });
+    return owner === ZERO_ADDRESS ? null : owner;
+  } catch {
+    return null;
+  }
+}
+async function getResolver(name, config) {
+  try {
+    const client = getMNSClient(config);
+    const node = (0, import_viem2.namehash)(name.toLowerCase());
+    const resolver = await client.readContract({
+      address: MNS_REGISTRY,
+      abi: registryAbi,
+      functionName: "resolver",
+      args: [node]
+    });
+    return resolver === ZERO_ADDRESS ? null : resolver;
+  } catch {
+    return null;
+  }
+}
+async function getExpiry(name, config) {
+  try {
+    const client = getMNSClient(config);
+    const label = name.replace(".mon", "");
+    const labelHash = (0, import_viem2.keccak256)((0, import_viem2.toBytes)(label));
+    const expiry = await client.readContract({
+      address: MNS_BASE_REGISTRAR,
+      abi: [
+        {
+          name: "nameExpires",
+          type: "function",
+          inputs: [{ name: "id", type: "uint256" }],
+          outputs: [{ name: "", type: "uint256" }],
+          stateMutability: "view"
+        }
+      ],
+      functionName: "nameExpires",
+      args: [BigInt(labelHash)]
+    });
+    return Number(expiry);
+  } catch {
+    return null;
+  }
+}
+async function getAvailable(name, config) {
+  const addr = await resolveName(name, config);
+  return addr === null;
+}
 async function getDisplayName(address, config) {
   const name = await lookupAddress(address, config);
   if (name) return name;
@@ -215,25 +292,28 @@ async function resolveInput(input, config) {
   if (trimmed.endsWith(".mon")) return resolveName(trimmed, config);
   return resolveName(`${trimmed}.mon`, config);
 }
-async function isRegistered(name, config) {
-  const addr = await resolveName(name, config);
-  return addr !== null;
-}
-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]);
@@ -261,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();
@@ -278,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",
@@ -394,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`
   );
@@ -427,6 +615,9 @@ 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,
   MNS_REGISTRY,
@@ -434,18 +625,24 @@ var TEXT_RECORD_KEYS = {
   clearCache,
   controllerReadAbi,
   controllerWriteAbi,
+  getAvailable,
   getAvatarUrl,
   getDisplayName,
+  getExpiry,
   getMNSClient,
+  getOwner,
   getRegisterTx,
   getRegistrationInfo,
+  getRemoteAvatarSize,
+  getResolver,
   getSetAddrTx,
   getSetTextTx,
   getTextRecord,
-  isRegistered,
   lookupAddress,
   resolveInput,
   resolveName,
-  resolverWriteAbi
+  resolverWriteAbi,
+  validateAvatarFull,
+  validateAvatarUri
 });
 //# sourceMappingURL=index.cjs.map