@unicitylabs/sphere-sdk 0.2.5 → 0.3.0

package/dist/core/index.js

@@ -2303,7 +2303,17 @@ var STORAGE_KEYS_GLOBAL = {
   /** Active addresses registry (JSON: TrackedAddressesStorage) */
   TRACKED_ADDRESSES: "tracked_addresses",
   /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
-  LAST_WALLET_EVENT_TS: "last_wallet_event_ts"
+  LAST_WALLET_EVENT_TS: "last_wallet_event_ts",
+  /** Group chat: joined groups */
+  GROUP_CHAT_GROUPS: "group_chat_groups",
+  /** Group chat: messages */
+  GROUP_CHAT_MESSAGES: "group_chat_messages",
+  /** Group chat: members */
+  GROUP_CHAT_MEMBERS: "group_chat_members",
+  /** Group chat: processed event IDs for deduplication */
+  GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events",
+  /** Group chat: last used relay URL (stale data detection) */
+  GROUP_CHAT_RELAY_URL: "group_chat_relay_url"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -2334,13 +2344,95 @@ function getAddressId(directAddress) {
   const last = hash.slice(-6).toLowerCase();
   return `DIRECT_${first}_${last}`;
 }
+var DEFAULT_NOSTR_RELAYS = [
+  "wss://relay.unicity.network",
+  "wss://relay.damus.io",
+  "wss://nos.lol",
+  "wss://relay.nostr.band"
+];
+var NIP29_KINDS = {
+  /** Chat message sent to group */
+  CHAT_MESSAGE: 9,
+  /** Thread root message */
+  THREAD_ROOT: 11,
+  /** Thread reply message */
+  THREAD_REPLY: 12,
+  /** User join request */
+  JOIN_REQUEST: 9021,
+  /** User leave request */
+  LEAVE_REQUEST: 9022,
+  /** Admin: add/update user */
+  PUT_USER: 9e3,
+  /** Admin: remove user */
+  REMOVE_USER: 9001,
+  /** Admin: edit group metadata */
+  EDIT_METADATA: 9002,
+  /** Admin: delete event */
+  DELETE_EVENT: 9005,
+  /** Admin: create group */
+  CREATE_GROUP: 9007,
+  /** Admin: delete group */
+  DELETE_GROUP: 9008,
+  /** Admin: create invite code */
+  CREATE_INVITE: 9009,
+  /** Relay-signed group metadata */
+  GROUP_METADATA: 39e3,
+  /** Relay-signed group admins */
+  GROUP_ADMINS: 39001,
+  /** Relay-signed group members */
+  GROUP_MEMBERS: 39002,
+  /** Relay-signed group roles */
+  GROUP_ROLES: 39003
+};
+var DEFAULT_AGGREGATOR_URL = "https://aggregator.unicity.network/rpc";
+var DEV_AGGREGATOR_URL = "https://dev-aggregator.dyndns.org/rpc";
+var TEST_AGGREGATOR_URL = "https://goggregator-test.unicity.network";
+var DEFAULT_IPFS_GATEWAYS = [
+  "https://ipfs.unicity.network",
+  "https://dweb.link",
+  "https://ipfs.io"
+];
 var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH2 = `${DEFAULT_BASE_PATH}/0/0`;
+var DEFAULT_ELECTRUM_URL = "wss://fulcrum.alpha.unicity.network:50004";
+var TEST_ELECTRUM_URL = "wss://fulcrum.alpha.testnet.unicity.network:50004";
+var TEST_NOSTR_RELAYS = [
+  "wss://nostr-relay.testnet.unicity.network"
+];
+var DEFAULT_GROUP_RELAYS = [
+  "wss://sphere-relay.unicity.network"
+];
+var NETWORKS = {
+  mainnet: {
+    name: "Mainnet",
+    aggregatorUrl: DEFAULT_AGGREGATOR_URL,
+    nostrRelays: DEFAULT_NOSTR_RELAYS,
+    ipfsGateways: DEFAULT_IPFS_GATEWAYS,
+    electrumUrl: DEFAULT_ELECTRUM_URL,
+    groupRelays: DEFAULT_GROUP_RELAYS
+  },
+  testnet: {
+    name: "Testnet",
+    aggregatorUrl: TEST_AGGREGATOR_URL,
+    nostrRelays: TEST_NOSTR_RELAYS,
+    ipfsGateways: DEFAULT_IPFS_GATEWAYS,
+    electrumUrl: TEST_ELECTRUM_URL,
+    groupRelays: DEFAULT_GROUP_RELAYS
+  },
+  dev: {
+    name: "Development",
+    aggregatorUrl: DEV_AGGREGATOR_URL,
+    nostrRelays: TEST_NOSTR_RELAYS,
+    ipfsGateways: DEFAULT_IPFS_GATEWAYS,
+    electrumUrl: TEST_ELECTRUM_URL,
+    groupRelays: DEFAULT_GROUP_RELAYS
+  }
+};
 
 // types/txf.ts
 var ARCHIVED_PREFIX = "archived-";
 var FORKED_PREFIX = "_forked_";
-var RESERVED_KEYS = ["_meta", "_nametag", "_tombstones", "_invalidatedNametags", "_outbox", "_mintOutbox", "_sent", "_invalid", "_integrity"];
+var RESERVED_KEYS = ["_meta", "_nametag", "_nametags", "_tombstones", "_invalidatedNametags", "_outbox", "_mintOutbox", "_sent", "_invalid", "_integrity"];
 function isTokenKey(key) {
   return key.startsWith("_") && !key.startsWith(ARCHIVED_PREFIX) && !key.startsWith(FORKED_PREFIX) && !RESERVED_KEYS.includes(key);
 }
@@ -2376,94 +2468,388 @@ function parseForkedKey(key) {
   };
 }
 
-// serialization/txf-serializer.ts
-function bytesToHex3(bytes) {
-  const arr = Array.isArray(bytes) ? bytes : Array.from(bytes);
-  return arr.map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-function normalizeToHex(value) {
-  if (typeof value === "string") {
-    return value;
+// registry/token-registry.testnet.json
+var token_registry_testnet_default = [
+  {
+    network: "unicity:testnet",
+    assetKind: "non-fungible",
+    name: "unicity",
+    description: "Unicity testnet token type",
+    id: "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "unicity",
+    symbol: "UCT",
+    decimals: 18,
+    description: "Unicity testnet native coin",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity_logo_32.png" }
+    ],
+    id: "455ad8720656b08e8dbd5bac1f3c73eeea5431565f6c1c3af742b1aa12d41d89"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "unicity-usd",
+    symbol: "USDU",
+    decimals: 6,
+    description: "Unicity testnet USD stablecoin",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/usdu_logo_32.png" }
+    ],
+    id: "8f0f3d7a5e7297be0ee98c63b81bcebb2740f43f616566fc290f9823a54f52d7"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "unicity-eur",
+    symbol: "EURU",
+    decimals: 6,
+    description: "Unicity testnet EUR stablecoin",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/euru_logo_32.png" }
+    ],
+    id: "5e160d5e9fdbb03b553fb9c3f6e6c30efa41fa807be39fb4f18e43776e492925"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "solana",
+    symbol: "SOL",
+    decimals: 9,
+    description: "Solana testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/sol.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/sol.png" }
+    ],
+    id: "dee5f8ce778562eec90e9c38a91296a023210ccc76ff4c29d527ac3eb64ade93"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "bitcoin",
+    symbol: "BTC",
+    decimals: 8,
+    description: "Bitcoin testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/btc.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/btc.png" }
+    ],
+    id: "86bc190fcf7b2d07c6078de93db803578760148b16d4431aa2f42a3241ff0daa"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "ethereum",
+    symbol: "ETH",
+    decimals: 18,
+    description: "Ethereum testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/eth.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/eth.png" }
+    ],
+    id: "3c2450f2fd867e7bb60c6a69d7ad0e53ce967078c201a3ecaa6074ed4c0deafb"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "alpha_test",
+    symbol: "ALPHT",
+    decimals: 8,
+    description: "ALPHA testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/alpha_coin.png" }
+    ],
+    id: "cde78ded16ef65818a51f43138031c4284e519300ab0cb60c30a8f9078080e5f"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "tether",
+    symbol: "USDT",
+    decimals: 6,
+    description: "Tether (Ethereum) testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/usdt.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/usdt.png" }
+    ],
+    id: "40d25444648418fe7efd433e147187a3a6adf049ac62bc46038bda5b960bf690"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "usd-coin",
+    symbol: "USDC",
+    decimals: 6,
+    description: "USDC (Ethereum) testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/usdc.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/usdc.png" }
+    ],
+    id: "2265121770fa6f41131dd9a6cc571e28679263d09a53eb2642e145b5b9a5b0a2"
   }
-  if (value && typeof value === "object") {
-    const obj = value;
-    if ("bytes" in obj && (Array.isArray(obj.bytes) || obj.bytes instanceof Uint8Array)) {
-      return bytesToHex3(obj.bytes);
-    }
-    if (obj.type === "Buffer" && Array.isArray(obj.data)) {
-      return bytesToHex3(obj.data);
-    }
+];
+
+// registry/TokenRegistry.ts
+var TokenRegistry = class _TokenRegistry {
+  static instance = null;
+  definitionsById;
+  definitionsBySymbol;
+  definitionsByName;
+  constructor() {
+    this.definitionsById = /* @__PURE__ */ new Map();
+    this.definitionsBySymbol = /* @__PURE__ */ new Map();
+    this.definitionsByName = /* @__PURE__ */ new Map();
+    this.loadRegistry();
   }
-  return String(value);
-}
-function normalizeSdkTokenToStorage(sdkTokenJson) {
-  const txf = JSON.parse(JSON.stringify(sdkTokenJson));
-  if (txf.genesis?.data) {
-    const data = txf.genesis.data;
-    if (data.tokenId !== void 0) {
-      data.tokenId = normalizeToHex(data.tokenId);
-    }
-    if (data.tokenType !== void 0) {
-      data.tokenType = normalizeToHex(data.tokenType);
-    }
-    if (data.salt !== void 0) {
-      data.salt = normalizeToHex(data.salt);
+  /**
+   * Get singleton instance of TokenRegistry
+   */
+  static getInstance() {
+    if (!_TokenRegistry.instance) {
+      _TokenRegistry.instance = new _TokenRegistry();
     }
+    return _TokenRegistry.instance;
   }
-  if (txf.genesis?.inclusionProof?.authenticator) {
-    const auth = txf.genesis.inclusionProof.authenticator;
-    if (auth.publicKey !== void 0) {
-      auth.publicKey = normalizeToHex(auth.publicKey);
-    }
-    if (auth.signature !== void 0) {
-      auth.signature = normalizeToHex(auth.signature);
-    }
+  /**
+   * Reset the singleton instance (useful for testing)
+   */
+  static resetInstance() {
+    _TokenRegistry.instance = null;
   }
-  if (Array.isArray(txf.transactions)) {
-    for (const tx of txf.transactions) {
-      if (tx.inclusionProof?.authenticator) {
-        const auth = tx.inclusionProof.authenticator;
-        if (auth.publicKey !== void 0) {
-          auth.publicKey = normalizeToHex(auth.publicKey);
-        }
-        if (auth.signature !== void 0) {
-          auth.signature = normalizeToHex(auth.signature);
-        }
+  /**
+   * Load registry data from bundled JSON
+   */
+  loadRegistry() {
+    const definitions = token_registry_testnet_default;
+    for (const def of definitions) {
+      const idLower = def.id.toLowerCase();
+      this.definitionsById.set(idLower, def);
+      if (def.symbol) {
+        this.definitionsBySymbol.set(def.symbol.toUpperCase(), def);
       }
+      this.definitionsByName.set(def.name.toLowerCase(), def);
     }
   }
-  return txf;
-}
-function tokenToTxf(token) {
-  const jsonData = token.sdkData;
-  if (!jsonData) {
-    return null;
-  }
-  try {
-    const txfData = normalizeSdkTokenToStorage(JSON.parse(jsonData));
-    if (!txfData.genesis || !txfData.state) {
-      return null;
-    }
-    if (!txfData.version) {
-      txfData.version = "2.0";
-    }
-    if (!txfData.transactions) {
-      txfData.transactions = [];
-    }
-    if (!txfData.nametags) {
-      txfData.nametags = [];
-    }
-    if (!txfData._integrity) {
-      txfData._integrity = {
-        genesisDataJSONHash: "0000" + "0".repeat(60)
-      };
-    }
-    return txfData;
-  } catch {
-    return null;
+  // ===========================================================================
+  // Lookup Methods
+  // ===========================================================================
+  /**
+   * Get token definition by hex coin ID
+   * @param coinId - 64-character hex string
+   * @returns Token definition or undefined if not found
+   */
+  getDefinition(coinId) {
+    if (!coinId) return void 0;
+    return this.definitionsById.get(coinId.toLowerCase());
   }
-}
-function determineTokenStatus(txf) {
+  /**
+   * Get token definition by symbol (e.g., "UCT", "BTC")
+   * @param symbol - Token symbol (case-insensitive)
+   * @returns Token definition or undefined if not found
+   */
+  getDefinitionBySymbol(symbol) {
+    if (!symbol) return void 0;
+    return this.definitionsBySymbol.get(symbol.toUpperCase());
+  }
+  /**
+   * Get token definition by name (e.g., "bitcoin", "ethereum")
+   * @param name - Token name (case-insensitive)
+   * @returns Token definition or undefined if not found
+   */
+  getDefinitionByName(name) {
+    if (!name) return void 0;
+    return this.definitionsByName.get(name.toLowerCase());
+  }
+  /**
+   * Get token symbol for a coin ID
+   * @param coinId - 64-character hex string
+   * @returns Symbol (e.g., "UCT") or truncated ID if not found
+   */
+  getSymbol(coinId) {
+    const def = this.getDefinition(coinId);
+    if (def?.symbol) {
+      return def.symbol;
+    }
+    return coinId.slice(0, 6).toUpperCase();
+  }
+  /**
+   * Get token name for a coin ID
+   * @param coinId - 64-character hex string
+   * @returns Name (e.g., "Bitcoin") or coin ID if not found
+   */
+  getName(coinId) {
+    const def = this.getDefinition(coinId);
+    if (def?.name) {
+      return def.name.charAt(0).toUpperCase() + def.name.slice(1);
+    }
+    return coinId;
+  }
+  /**
+   * Get decimal places for a coin ID
+   * @param coinId - 64-character hex string
+   * @returns Decimals or 0 if not found
+   */
+  getDecimals(coinId) {
+    const def = this.getDefinition(coinId);
+    return def?.decimals ?? 0;
+  }
+  /**
+   * Get icon URL for a coin ID
+   * @param coinId - 64-character hex string
+   * @param preferPng - Prefer PNG format over SVG
+   * @returns Icon URL or null if not found
+   */
+  getIconUrl(coinId, preferPng = true) {
+    const def = this.getDefinition(coinId);
+    if (!def?.icons || def.icons.length === 0) {
+      return null;
+    }
+    if (preferPng) {
+      const pngIcon = def.icons.find((i) => i.url.toLowerCase().includes(".png"));
+      if (pngIcon) return pngIcon.url;
+    }
+    return def.icons[0].url;
+  }
+  /**
+   * Check if a coin ID is known in the registry
+   * @param coinId - 64-character hex string
+   * @returns true if the coin is in the registry
+   */
+  isKnown(coinId) {
+    return this.definitionsById.has(coinId.toLowerCase());
+  }
+  /**
+   * Get all token definitions
+   * @returns Array of all token definitions
+   */
+  getAllDefinitions() {
+    return Array.from(this.definitionsById.values());
+  }
+  /**
+   * Get all fungible token definitions
+   * @returns Array of fungible token definitions
+   */
+  getFungibleTokens() {
+    return this.getAllDefinitions().filter((def) => def.assetKind === "fungible");
+  }
+  /**
+   * Get all non-fungible token definitions
+   * @returns Array of non-fungible token definitions
+   */
+  getNonFungibleTokens() {
+    return this.getAllDefinitions().filter((def) => def.assetKind === "non-fungible");
+  }
+  /**
+   * Get coin ID by symbol
+   * @param symbol - Token symbol (e.g., "UCT")
+   * @returns Coin ID hex string or undefined if not found
+   */
+  getCoinIdBySymbol(symbol) {
+    const def = this.getDefinitionBySymbol(symbol);
+    return def?.id;
+  }
+  /**
+   * Get coin ID by name
+   * @param name - Token name (e.g., "bitcoin")
+   * @returns Coin ID hex string or undefined if not found
+   */
+  getCoinIdByName(name) {
+    const def = this.getDefinitionByName(name);
+    return def?.id;
+  }
+};
+
+// serialization/txf-serializer.ts
+function bytesToHex3(bytes) {
+  const arr = Array.isArray(bytes) ? bytes : Array.from(bytes);
+  return arr.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function normalizeToHex(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value && typeof value === "object") {
+    const obj = value;
+    if ("bytes" in obj && (Array.isArray(obj.bytes) || obj.bytes instanceof Uint8Array)) {
+      return bytesToHex3(obj.bytes);
+    }
+    if (obj.type === "Buffer" && Array.isArray(obj.data)) {
+      return bytesToHex3(obj.data);
+    }
+  }
+  return String(value);
+}
+function normalizeSdkTokenToStorage(sdkTokenJson) {
+  const txf = JSON.parse(JSON.stringify(sdkTokenJson));
+  if (txf.genesis?.data) {
+    const data = txf.genesis.data;
+    if (data.tokenId !== void 0) {
+      data.tokenId = normalizeToHex(data.tokenId);
+    }
+    if (data.tokenType !== void 0) {
+      data.tokenType = normalizeToHex(data.tokenType);
+    }
+    if (data.salt !== void 0) {
+      data.salt = normalizeToHex(data.salt);
+    }
+  }
+  if (txf.genesis?.inclusionProof?.authenticator) {
+    const auth = txf.genesis.inclusionProof.authenticator;
+    if (auth.publicKey !== void 0) {
+      auth.publicKey = normalizeToHex(auth.publicKey);
+    }
+    if (auth.signature !== void 0) {
+      auth.signature = normalizeToHex(auth.signature);
+    }
+  }
+  if (Array.isArray(txf.transactions)) {
+    for (const tx of txf.transactions) {
+      if (tx.inclusionProof?.authenticator) {
+        const auth = tx.inclusionProof.authenticator;
+        if (auth.publicKey !== void 0) {
+          auth.publicKey = normalizeToHex(auth.publicKey);
+        }
+        if (auth.signature !== void 0) {
+          auth.signature = normalizeToHex(auth.signature);
+        }
+      }
+    }
+  }
+  return txf;
+}
+function tokenToTxf(token) {
+  const jsonData = token.sdkData;
+  if (!jsonData) {
+    return null;
+  }
+  try {
+    const txfData = normalizeSdkTokenToStorage(JSON.parse(jsonData));
+    if (!txfData.genesis || !txfData.state) {
+      return null;
+    }
+    if (!txfData.version) {
+      txfData.version = "2.0";
+    }
+    if (!txfData.transactions) {
+      txfData.transactions = [];
+    }
+    if (!txfData.nametags) {
+      txfData.nametags = [];
+    }
+    if (!txfData._integrity) {
+      txfData._integrity = {
+        genesisDataJSONHash: "0000" + "0".repeat(60)
+      };
+    }
+    return txfData;
+  } catch {
+    return null;
+  }
+}
+function determineTokenStatus(txf) {
   if (txf.transactions.length > 0) {
     const lastTx = txf.transactions[txf.transactions.length - 1];
     if (lastTx.inclusionProof === null) {
@@ -2487,12 +2873,14 @@ function txfToToken(tokenId, txf) {
   const tokenType = txf.genesis.data.tokenType;
   const isNft = tokenType === "455ad8720656b08e8dbd5bac1f3c73eeea5431565f6c1c3af742b1aa12d41d89";
   const now = Date.now();
+  const registry = TokenRegistry.getInstance();
+  const def = registry.getDefinition(coinId);
   return {
     id: tokenId,
     coinId,
-    symbol: isNft ? "NFT" : "UCT",
-    name: isNft ? "NFT" : "Token",
-    decimals: isNft ? 0 : 8,
+    symbol: isNft ? "NFT" : def?.symbol || coinId.slice(0, 8),
+    name: isNft ? "NFT" : def?.name ? def.name.charAt(0).toUpperCase() + def.name.slice(1) : "Token",
+    decimals: isNft ? 0 : def?.decimals ?? 8,
     amount: totalAmount.toString(),
     status: determineTokenStatus(txf),
     createdAt: now,
@@ -2507,6 +2895,9 @@ async function buildTxfStorageData(tokens, meta, options) {
       formatVersion: "2.0"
     }
   };
+  if (options?.nametags && options.nametags.length > 0) {
+    storageData._nametags = options.nametags;
+  }
   if (options?.tombstones && options.tombstones.length > 0) {
     storageData._tombstones = options.tombstones;
   }
@@ -2545,7 +2936,7 @@ function parseTxfStorageData(data) {
   const result = {
     tokens: [],
     meta: null,
-    nametag: null,
+    nametags: [],
     tombstones: [],
     archivedTokens: /* @__PURE__ */ new Map(),
     forkedTokens: /* @__PURE__ */ new Map(),
@@ -2562,8 +2953,20 @@ function parseTxfStorageData(data) {
   if (storageData._meta && typeof storageData._meta === "object") {
     result.meta = storageData._meta;
   }
+  const seenNames = /* @__PURE__ */ new Set();
+  if (Array.isArray(storageData._nametags)) {
+    for (const entry of storageData._nametags) {
+      if (entry && typeof entry === "object" && typeof entry.name === "string") {
+        result.nametags.push(entry);
+        seenNames.add(entry.name);
+      }
+    }
+  }
   if (storageData._nametag && typeof storageData._nametag === "object") {
-    result.nametag = storageData._nametag;
+    const legacy = storageData._nametag;
+    if (typeof legacy.name === "string" && !seenNames.has(legacy.name)) {
+      result.nametags.push(legacy);
+    }
   }
   if (storageData._tombstones && Array.isArray(storageData._tombstones)) {
     for (const entry of storageData._tombstones) {
@@ -2663,300 +3066,6 @@ function getCurrentStateHash(txf) {
   return void 0;
 }
 
-// registry/token-registry.testnet.json
-var token_registry_testnet_default = [
-  {
-    network: "unicity:testnet",
-    assetKind: "non-fungible",
-    name: "unicity",
-    description: "Unicity testnet token type",
-    id: "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "unicity",
-    symbol: "UCT",
-    decimals: 18,
-    description: "Unicity testnet native coin",
-    icons: [
-      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity_logo_32.png" }
-    ],
-    id: "455ad8720656b08e8dbd5bac1f3c73eeea5431565f6c1c3af742b1aa12d41d89"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "unicity-usd",
-    symbol: "USDU",
-    decimals: 6,
-    description: "Unicity testnet USD stablecoin",
-    icons: [
-      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/usdu_logo_32.png" }
-    ],
-    id: "8f0f3d7a5e7297be0ee98c63b81bcebb2740f43f616566fc290f9823a54f52d7"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "unicity-eur",
-    symbol: "EURU",
-    decimals: 6,
-    description: "Unicity testnet EUR stablecoin",
-    icons: [
-      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/euru_logo_32.png" }
-    ],
-    id: "5e160d5e9fdbb03b553fb9c3f6e6c30efa41fa807be39fb4f18e43776e492925"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "solana",
-    symbol: "SOL",
-    decimals: 9,
-    description: "Solana testnet coin on Unicity",
-    icons: [
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/sol.svg" },
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/sol.png" }
-    ],
-    id: "dee5f8ce778562eec90e9c38a91296a023210ccc76ff4c29d527ac3eb64ade93"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "bitcoin",
-    symbol: "BTC",
-    decimals: 8,
-    description: "Bitcoin testnet coin on Unicity",
-    icons: [
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/btc.svg" },
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/btc.png" }
-    ],
-    id: "86bc190fcf7b2d07c6078de93db803578760148b16d4431aa2f42a3241ff0daa"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "ethereum",
-    symbol: "ETH",
-    decimals: 18,
-    description: "Ethereum testnet coin on Unicity",
-    icons: [
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/eth.svg" },
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/eth.png" }
-    ],
-    id: "3c2450f2fd867e7bb60c6a69d7ad0e53ce967078c201a3ecaa6074ed4c0deafb"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "alpha_test",
-    symbol: "ALPHT",
-    decimals: 8,
-    description: "ALPHA testnet coin on Unicity",
-    icons: [
-      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/alpha_coin.png" }
-    ],
-    id: "cde78ded16ef65818a51f43138031c4284e519300ab0cb60c30a8f9078080e5f"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "tether",
-    symbol: "USDT",
-    decimals: 6,
-    description: "Tether (Ethereum) testnet coin on Unicity",
-    icons: [
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/usdt.svg" },
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/usdt.png" }
-    ],
-    id: "40d25444648418fe7efd433e147187a3a6adf049ac62bc46038bda5b960bf690"
-  },
-  {
-    network: "unicity:testnet",
-    assetKind: "fungible",
-    name: "usd-coin",
-    symbol: "USDC",
-    decimals: 6,
-    description: "USDC (Ethereum) testnet coin on Unicity",
-    icons: [
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/usdc.svg" },
-      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/usdc.png" }
-    ],
-    id: "2265121770fa6f41131dd9a6cc571e28679263d09a53eb2642e145b5b9a5b0a2"
-  }
-];
-
-// registry/TokenRegistry.ts
-var TokenRegistry = class _TokenRegistry {
-  static instance = null;
-  definitionsById;
-  definitionsBySymbol;
-  definitionsByName;
-  constructor() {
-    this.definitionsById = /* @__PURE__ */ new Map();
-    this.definitionsBySymbol = /* @__PURE__ */ new Map();
-    this.definitionsByName = /* @__PURE__ */ new Map();
-    this.loadRegistry();
-  }
-  /**
-   * Get singleton instance of TokenRegistry
-   */
-  static getInstance() {
-    if (!_TokenRegistry.instance) {
-      _TokenRegistry.instance = new _TokenRegistry();
-    }
-    return _TokenRegistry.instance;
-  }
-  /**
-   * Reset the singleton instance (useful for testing)
-   */
-  static resetInstance() {
-    _TokenRegistry.instance = null;
-  }
-  /**
-   * Load registry data from bundled JSON
-   */
-  loadRegistry() {
-    const definitions = token_registry_testnet_default;
-    for (const def of definitions) {
-      const idLower = def.id.toLowerCase();
-      this.definitionsById.set(idLower, def);
-      if (def.symbol) {
-        this.definitionsBySymbol.set(def.symbol.toUpperCase(), def);
-      }
-      this.definitionsByName.set(def.name.toLowerCase(), def);
-    }
-  }
-  // ===========================================================================
-  // Lookup Methods
-  // ===========================================================================
-  /**
-   * Get token definition by hex coin ID
-   * @param coinId - 64-character hex string
-   * @returns Token definition or undefined if not found
-   */
-  getDefinition(coinId) {
-    if (!coinId) return void 0;
-    return this.definitionsById.get(coinId.toLowerCase());
-  }
-  /**
-   * Get token definition by symbol (e.g., "UCT", "BTC")
-   * @param symbol - Token symbol (case-insensitive)
-   * @returns Token definition or undefined if not found
-   */
-  getDefinitionBySymbol(symbol) {
-    if (!symbol) return void 0;
-    return this.definitionsBySymbol.get(symbol.toUpperCase());
-  }
-  /**
-   * Get token definition by name (e.g., "bitcoin", "ethereum")
-   * @param name - Token name (case-insensitive)
-   * @returns Token definition or undefined if not found
-   */
-  getDefinitionByName(name) {
-    if (!name) return void 0;
-    return this.definitionsByName.get(name.toLowerCase());
-  }
-  /**
-   * Get token symbol for a coin ID
-   * @param coinId - 64-character hex string
-   * @returns Symbol (e.g., "UCT") or truncated ID if not found
-   */
-  getSymbol(coinId) {
-    const def = this.getDefinition(coinId);
-    if (def?.symbol) {
-      return def.symbol;
-    }
-    return coinId.slice(0, 6).toUpperCase();
-  }
-  /**
-   * Get token name for a coin ID
-   * @param coinId - 64-character hex string
-   * @returns Name (e.g., "Bitcoin") or coin ID if not found
-   */
-  getName(coinId) {
-    const def = this.getDefinition(coinId);
-    if (def?.name) {
-      return def.name.charAt(0).toUpperCase() + def.name.slice(1);
-    }
-    return coinId;
-  }
-  /**
-   * Get decimal places for a coin ID
-   * @param coinId - 64-character hex string
-   * @returns Decimals or 0 if not found
-   */
-  getDecimals(coinId) {
-    const def = this.getDefinition(coinId);
-    return def?.decimals ?? 0;
-  }
-  /**
-   * Get icon URL for a coin ID
-   * @param coinId - 64-character hex string
-   * @param preferPng - Prefer PNG format over SVG
-   * @returns Icon URL or null if not found
-   */
-  getIconUrl(coinId, preferPng = true) {
-    const def = this.getDefinition(coinId);
-    if (!def?.icons || def.icons.length === 0) {
-      return null;
-    }
-    if (preferPng) {
-      const pngIcon = def.icons.find((i) => i.url.toLowerCase().includes(".png"));
-      if (pngIcon) return pngIcon.url;
-    }
-    return def.icons[0].url;
-  }
-  /**
-   * Check if a coin ID is known in the registry
-   * @param coinId - 64-character hex string
-   * @returns true if the coin is in the registry
-   */
-  isKnown(coinId) {
-    return this.definitionsById.has(coinId.toLowerCase());
-  }
-  /**
-   * Get all token definitions
-   * @returns Array of all token definitions
-   */
-  getAllDefinitions() {
-    return Array.from(this.definitionsById.values());
-  }
-  /**
-   * Get all fungible token definitions
-   * @returns Array of fungible token definitions
-   */
-  getFungibleTokens() {
-    return this.getAllDefinitions().filter((def) => def.assetKind === "fungible");
-  }
-  /**
-   * Get all non-fungible token definitions
-   * @returns Array of non-fungible token definitions
-   */
-  getNonFungibleTokens() {
-    return this.getAllDefinitions().filter((def) => def.assetKind === "non-fungible");
-  }
-  /**
-   * Get coin ID by symbol
-   * @param symbol - Token symbol (e.g., "UCT")
-   * @returns Coin ID hex string or undefined if not found
-   */
-  getCoinIdBySymbol(symbol) {
-    const def = this.getDefinitionBySymbol(symbol);
-    return def?.id;
-  }
-  /**
-   * Get coin ID by name
-   * @param name - Token name (e.g., "bitcoin")
-   * @returns Coin ID hex string or undefined if not found
-   */
-  getCoinIdByName(name) {
-    const def = this.getDefinitionByName(name);
-    return def?.id;
-  }
-};
-
 // modules/payments/InstantSplitExecutor.ts
 import { Token as Token3 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { TokenId as TokenId3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
@@ -3990,7 +4099,7 @@ var PaymentsModule = class _PaymentsModule {
   archivedTokens = /* @__PURE__ */ new Map();
   forkedTokens = /* @__PURE__ */ new Map();
   transactionHistory = [];
-  nametag = null;
+  nametags = [];
   // Payment Requests State (Incoming)
   paymentRequests = [];
   paymentRequestHandlers = /* @__PURE__ */ new Set();
@@ -4059,7 +4168,7 @@ var PaymentsModule = class _PaymentsModule {
     this.archivedTokens.clear();
     this.forkedTokens.clear();
     this.transactionHistory = [];
-    this.nametag = null;
+    this.nametags = [];
     this.deps = deps;
     this.priceProvider = deps.price ?? null;
     if (this.l1) {
@@ -4108,8 +4217,6 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
     await this.loadPendingV5Tokens();
-    await this.loadTokensFromFileStorage();
-    await this.loadNametagFromFileStorage();
     const historyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
     if (historyData) {
       try {
@@ -4618,9 +4725,10 @@ var PaymentsModule = class _PaymentsModule {
         senderPubkey,
         {
           findNametagToken: async (proxyAddress) => {
-            if (this.nametag?.token) {
+            const currentNametag = this.getNametag();
+            if (currentNametag?.token) {
               try {
-                const nametagToken = await SdkToken2.fromJSON(this.nametag.token);
+                const nametagToken = await SdkToken2.fromJSON(currentNametag.token);
                 const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
                 const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
                 if (proxy.address === proxyAddress) {
@@ -5409,7 +5517,6 @@ var PaymentsModule = class _PaymentsModule {
           sdkData: JSON.stringify(finalizedToken.toJSON())
         };
         this.tokens.set(tokenId, confirmedToken);
-        await this.saveTokenToFileStorage(confirmedToken);
         await this.addToHistory({
           type: "RECEIVED",
           amount: confirmedToken.amount,
@@ -5498,9 +5605,10 @@ var PaymentsModule = class _PaymentsModule {
         } catch {
         }
       }
-      if (nametagTokens.length === 0 && this.nametag?.token) {
+      const localNametag = this.getNametag();
+      if (nametagTokens.length === 0 && localNametag?.token) {
         try {
-          const nametagToken = await SdkToken2.fromJSON(this.nametag.token);
+          const nametagToken = await SdkToken2.fromJSON(localNametag.token);
           const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
           const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
           if (proxy.address === recipientAddressStr) {
@@ -5661,125 +5769,16 @@ var PaymentsModule = class _PaymentsModule {
       });
     }
     await this.save();
-    if (!this.parsePendingFinalization(token.sdkData)) {
-      await this.saveTokenToFileStorage(token);
-    }
     this.log(`Added token ${token.id}, total: ${this.tokens.size}`);
     return true;
   }
   /**
-   * Save token as individual file to token storage providers
-   * Similar to lottery's saveReceivedToken() pattern
-   */
-  async saveTokenToFileStorage(token) {
-    const providers = this.getTokenStorageProviders();
-    if (providers.size === 0) return;
-    const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
-    const tokenIdPrefix = sdkTokenId ? sdkTokenId.slice(0, 16) : token.id.slice(0, 16);
-    const filename = `token-${tokenIdPrefix}-${Date.now()}`;
-    const tokenData = {
-      token: token.sdkData ? JSON.parse(token.sdkData) : null,
-      receivedAt: Date.now(),
-      meta: {
-        id: token.id,
-        coinId: token.coinId,
-        symbol: token.symbol,
-        amount: token.amount,
-        status: token.status
-      }
-    };
-    for (const [providerId, provider] of providers) {
-      try {
-        if (provider.saveToken) {
-          await provider.saveToken(filename, tokenData);
-          this.log(`Saved token file ${filename} to ${providerId}`);
-        }
-      } catch (error) {
-        console.warn(`[Payments] Failed to save token to ${providerId}:`, error);
-      }
-    }
-  }
-  /**
-   * Load tokens from file storage providers (lottery compatibility)
-   * This loads tokens from file-based storage that may have been saved
-   * by other applications using the same storage directory.
-   */
-  async loadTokensFromFileStorage() {
-    const providers = this.getTokenStorageProviders();
-    if (providers.size === 0) return;
-    for (const [providerId, provider] of providers) {
-      if (!provider.listTokenIds || !provider.getToken) continue;
-      try {
-        const allIds = await provider.listTokenIds();
-        const tokenIds = allIds.filter((id) => id.startsWith("token-"));
-        this.log(`Found ${tokenIds.length} token files in ${providerId}`);
-        for (const tokenId of tokenIds) {
-          try {
-            const fileData = await provider.getToken(tokenId);
-            if (!fileData || typeof fileData !== "object") continue;
-            const data = fileData;
-            const tokenJson = data.token;
-            if (!tokenJson) continue;
-            if (typeof tokenJson === "object" && tokenJson !== null && "_pendingFinalization" in tokenJson) {
-              continue;
-            }
-            let sdkTokenId;
-            if (typeof tokenJson === "object" && tokenJson !== null) {
-              const tokenObj = tokenJson;
-              const genesis = tokenObj.genesis;
-              const genesisData = genesis?.data;
-              sdkTokenId = genesisData?.tokenId;
-            }
-            if (sdkTokenId) {
-              let exists = false;
-              for (const existing of this.tokens.values()) {
-                const existingId = extractTokenIdFromSdkData(existing.sdkData);
-                if (existingId === sdkTokenId) {
-                  exists = true;
-                  break;
-                }
-              }
-              if (exists) continue;
-            }
-            const tokenInfo = await parseTokenInfo(tokenJson);
-            const token = {
-              id: tokenInfo.tokenId ?? tokenId,
-              coinId: tokenInfo.coinId,
-              symbol: tokenInfo.symbol,
-              name: tokenInfo.name,
-              decimals: tokenInfo.decimals,
-              iconUrl: tokenInfo.iconUrl,
-              amount: tokenInfo.amount,
-              status: "confirmed",
-              createdAt: data.receivedAt || Date.now(),
-              updatedAt: Date.now(),
-              sdkData: typeof tokenJson === "string" ? tokenJson : JSON.stringify(tokenJson)
-            };
-            const loadedTokenId = extractTokenIdFromSdkData(token.sdkData);
-            const loadedStateHash = extractStateHashFromSdkData(token.sdkData);
-            if (loadedTokenId && loadedStateHash && this.isStateTombstoned(loadedTokenId, loadedStateHash)) {
-              this.log(`Skipping tombstoned token file ${tokenId} (${loadedTokenId.slice(0, 8)}...)`);
-              continue;
-            }
-            this.tokens.set(token.id, token);
-            this.log(`Loaded token from file: ${tokenId}`);
-          } catch (tokenError) {
-            console.warn(`[Payments] Failed to load token ${tokenId}:`, tokenError);
-          }
-        }
-      } catch (error) {
-        console.warn(`[Payments] Failed to load tokens from ${providerId}:`, error);
-      }
-    }
-    this.log(`Loaded ${this.tokens.size} tokens from file storage`);
-  }
-  /**
-   * Update an existing token or add it if not found.
-   *
-   * Looks up the token by genesis `tokenId` (from `sdkData`) first, then by
-   * `token.id`. If no match is found, falls back to {@link addToken}.
-   *
-   * @param token - The token with updated data. Must include a valid `id`.
+   * Update an existing token or add it if not found.
+   *
+   * Looks up the token by genesis `tokenId` (from `sdkData`) first, then by
+   * `token.id`. If no match is found, falls back to {@link addToken}.
+   *
+   * @param token - The token with updated data. Must include a valid `id`.
    */
   async updateToken(token) {
     this.ensureInitialized();
@@ -5831,7 +5830,6 @@ var PaymentsModule = class _PaymentsModule {
       this.log(`Warning: Could not create tombstone for token ${tokenId.slice(0, 8)}... (missing tokenId or stateHash)`);
     }
     this.tokens.delete(tokenId);
-    await this.deleteTokenFiles(token);
     if (!skipHistory && token.coinId && token.amount) {
       await this.addToHistory({
         type: "SENT",
@@ -5844,31 +5842,6 @@ var PaymentsModule = class _PaymentsModule {
     }
     await this.save();
   }
-  /**
-   * Delete physical token file(s) from all storage providers.
-   * Finds files by matching the SDK token ID prefix in the filename.
-   */
-  async deleteTokenFiles(token) {
-    const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
-    if (!sdkTokenId) return;
-    const tokenIdPrefix = sdkTokenId.slice(0, 16);
-    const providers = this.getTokenStorageProviders();
-    for (const [providerId, provider] of providers) {
-      if (!provider.listTokenIds || !provider.deleteToken) continue;
-      try {
-        const allIds = await provider.listTokenIds();
-        const matchingFiles = allIds.filter(
-          (id) => id.startsWith(`token-${tokenIdPrefix}`)
-        );
-        for (const fileId of matchingFiles) {
-          await provider.deleteToken(fileId);
-          this.log(`Deleted token file ${fileId} from ${providerId}`);
-        }
-      } catch (error) {
-        console.warn(`[Payments] Failed to delete token files from ${providerId}:`, error);
-      }
-    }
-  }
   // ===========================================================================
   // Public API - Tombstones
   // ===========================================================================
@@ -6124,18 +6097,30 @@ var PaymentsModule = class _PaymentsModule {
    */
   async setNametag(nametag) {
     this.ensureInitialized();
-    this.nametag = nametag;
+    const idx = this.nametags.findIndex((n) => n.name === nametag.name);
+    if (idx >= 0) {
+      this.nametags[idx] = nametag;
+    } else {
+      this.nametags.push(nametag);
+    }
     await this.save();
-    await this.saveNametagToFileStorage(nametag);
     this.log(`Nametag set: ${nametag.name}`);
   }
   /**
-   * Get the current nametag data.
+   * Get the current (first) nametag data.
    *
    * @returns The nametag data, or `null` if no nametag is set.
    */
   getNametag() {
-    return this.nametag;
+    return this.nametags[0] ?? null;
+  }
+  /**
+   * Get all nametag data entries.
+   *
+   * @returns A copy of the nametags array.
+   */
+  getNametags() {
+    return [...this.nametags];
   }
   /**
    * Check whether a nametag is currently set.
@@ -6143,77 +6128,16 @@ var PaymentsModule = class _PaymentsModule {
    * @returns `true` if nametag data is present.
    */
   hasNametag() {
-    return this.nametag !== null;
+    return this.nametags.length > 0;
   }
   /**
-   * Remove the current nametag data from memory and storage.
+   * Remove all nametag data from memory and storage.
    */
   async clearNametag() {
     this.ensureInitialized();
-    this.nametag = null;
+    this.nametags = [];
     await this.save();
   }
-  /**
-   * Save nametag to file storage for lottery compatibility
-   * Creates file: nametag-{name}.json
-   */
-  async saveNametagToFileStorage(nametag) {
-    const providers = this.getTokenStorageProviders();
-    if (providers.size === 0) return;
-    const filename = `nametag-${nametag.name}`;
-    const fileData = {
-      nametag: nametag.name,
-      token: nametag.token,
-      timestamp: nametag.timestamp || Date.now()
-    };
-    for (const [providerId, provider] of providers) {
-      try {
-        if (provider.saveToken) {
-          await provider.saveToken(filename, fileData);
-          this.log(`Saved nametag file ${filename} to ${providerId}`);
-        }
-      } catch (error) {
-        console.warn(`[Payments] Failed to save nametag to ${providerId}:`, error);
-      }
-    }
-  }
-  /**
-   * Load nametag from file storage (lottery compatibility)
-   * Looks for file: nametag-{name}.json
-   */
-  async loadNametagFromFileStorage() {
-    if (this.nametag) return;
-    const providers = this.getTokenStorageProviders();
-    if (providers.size === 0) return;
-    for (const [providerId, provider] of providers) {
-      if (!provider.listTokenIds || !provider.getToken) continue;
-      try {
-        const tokenIds = await provider.listTokenIds();
-        const nametagFiles = tokenIds.filter((id) => id.startsWith("nametag-"));
-        for (const nametagFile of nametagFiles) {
-          try {
-            const fileData = await provider.getToken(nametagFile);
-            if (!fileData || typeof fileData !== "object") continue;
-            const data = fileData;
-            if (!data.token || !data.nametag) continue;
-            this.nametag = {
-              name: data.nametag,
-              token: data.token,
-              timestamp: data.timestamp || Date.now(),
-              format: "lottery",
-              version: "1.0"
-            };
-            this.log(`Loaded nametag from file: ${nametagFile}`);
-            return;
-          } catch (fileError) {
-            console.warn(`[Payments] Failed to load nametag file ${nametagFile}:`, fileError);
-          }
-        }
-      } catch (error) {
-        console.warn(`[Payments] Failed to search nametag files in ${providerId}:`, error);
-      }
-    }
-  }
   /**
    * Mint a nametag token on-chain (like Sphere wallet and lottery)
    * This creates the nametag token required for receiving tokens via PROXY addresses
@@ -6701,10 +6625,11 @@ var PaymentsModule = class _PaymentsModule {
     let nametagTokens = [];
     if (addressScheme === AddressScheme.PROXY) {
       const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
-      if (!this.nametag?.token) {
+      const proxyNametag = this.getNametag();
+      if (!proxyNametag?.token) {
         throw new Error("Cannot finalize PROXY transfer - no nametag token");
       }
-      const nametagToken = await SdkToken2.fromJSON(this.nametag.token);
+      const nametagToken = await SdkToken2.fromJSON(proxyNametag.token);
       const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
       if (proxy.address !== recipientAddress.address) {
         throw new Error(
@@ -6765,7 +6690,6 @@ var PaymentsModule = class _PaymentsModule {
       };
       this.tokens.set(tokenId, finalizedToken);
       await this.save();
-      await this.saveTokenToFileStorage(finalizedToken);
       this.log(`NOSTR-FIRST: Token ${tokenId.slice(0, 8)}... finalized and confirmed`);
       this.deps.emitEvent("transfer:confirmed", {
         id: crypto.randomUUID(),
@@ -6809,9 +6733,6 @@ var PaymentsModule = class _PaymentsModule {
       if (instantBundle) {
         this.log("Processing INSTANT_SPLIT bundle...");
         try {
-          if (!this.nametag) {
-            await this.loadNametagFromFileStorage();
-          }
           const result = await this.processInstantSplitBundle(
             instantBundle,
             transfer.senderTransportPubkey
@@ -7011,6 +6932,7 @@ var PaymentsModule = class _PaymentsModule {
         ipnsName: this.deps.identity.ipnsName ?? ""
       },
       {
+        nametags: this.nametags,
         tombstones: this.tombstones,
         archivedTokens: this.archivedTokens,
         forkedTokens: this.forkedTokens
@@ -7032,9 +6954,7 @@ var PaymentsModule = class _PaymentsModule {
     }
     this.archivedTokens = parsed.archivedTokens;
     this.forkedTokens = parsed.forkedTokens;
-    if (parsed.nametag !== null) {
-      this.nametag = parsed.nametag;
-    }
+    this.nametags = parsed.nametags;
   }
   // ===========================================================================
   // Private: NOSTR-FIRST Proof Polling
@@ -7252,228 +7172,1609 @@ var CommunicationsModule = class {
     this.broadcastSubscriptions.clear();
   }
   // ===========================================================================
-  // Public API - Direct Messages
+  // Public API - Direct Messages
+  // ===========================================================================
+  /**
+   * Send direct message
+   */
+  async sendDM(recipient, content) {
+    this.ensureInitialized();
+    const recipientPubkey = await this.resolveRecipient(recipient);
+    const eventId = await this.deps.transport.sendMessage(recipientPubkey, content);
+    const message = {
+      id: eventId,
+      senderPubkey: this.deps.identity.chainPubkey,
+      senderNametag: this.deps.identity.nametag,
+      recipientPubkey,
+      content,
+      timestamp: Date.now(),
+      isRead: true
+    };
+    this.messages.set(message.id, message);
+    if (this.config.autoSave) {
+      await this.save();
+    }
+    return message;
+  }
+  /**
+   * Get conversation with peer
+   */
+  getConversation(peerPubkey) {
+    return Array.from(this.messages.values()).filter(
+      (m) => m.senderPubkey === peerPubkey || m.recipientPubkey === peerPubkey
+    ).sort((a, b) => a.timestamp - b.timestamp);
+  }
+  /**
+   * Get all conversations grouped by peer
+   */
+  getConversations() {
+    const conversations = /* @__PURE__ */ new Map();
+    for (const message of this.messages.values()) {
+      const peer = message.senderPubkey === this.deps?.identity.chainPubkey ? message.recipientPubkey : message.senderPubkey;
+      if (!conversations.has(peer)) {
+        conversations.set(peer, []);
+      }
+      conversations.get(peer).push(message);
+    }
+    for (const msgs of conversations.values()) {
+      msgs.sort((a, b) => a.timestamp - b.timestamp);
+    }
+    return conversations;
+  }
+  /**
+   * Mark messages as read
+   */
+  async markAsRead(messageIds) {
+    for (const id of messageIds) {
+      const msg = this.messages.get(id);
+      if (msg) {
+        msg.isRead = true;
+      }
+    }
+    if (this.config.autoSave) {
+      await this.save();
+    }
+  }
+  /**
+   * Get unread count
+   */
+  getUnreadCount(peerPubkey) {
+    let messages = Array.from(this.messages.values()).filter(
+      (m) => !m.isRead && m.senderPubkey !== this.deps?.identity.chainPubkey
+    );
+    if (peerPubkey) {
+      messages = messages.filter((m) => m.senderPubkey === peerPubkey);
+    }
+    return messages.length;
+  }
+  /**
+   * Subscribe to incoming DMs
+   */
+  onDirectMessage(handler) {
+    this.dmHandlers.add(handler);
+    return () => this.dmHandlers.delete(handler);
+  }
+  // ===========================================================================
+  // Public API - Broadcasts
+  // ===========================================================================
+  /**
+   * Publish broadcast message
+   */
+  async broadcast(content, tags) {
+    this.ensureInitialized();
+    const eventId = await this.deps.transport.publishBroadcast?.(content, tags);
+    const message = {
+      id: eventId ?? crypto.randomUUID(),
+      authorPubkey: this.deps.identity.chainPubkey,
+      authorNametag: this.deps.identity.nametag,
+      content,
+      timestamp: Date.now(),
+      tags
+    };
+    this.broadcasts.set(message.id, message);
+    return message;
+  }
+  /**
+   * Subscribe to broadcasts with tags
+   */
+  subscribeToBroadcasts(tags) {
+    this.ensureInitialized();
+    const key = tags.sort().join(":");
+    if (this.broadcastSubscriptions.has(key)) {
+      return () => {
+      };
+    }
+    const unsub = this.deps.transport.subscribeToBroadcast?.(tags, (broadcast2) => {
+      this.handleIncomingBroadcast(broadcast2);
+    });
+    if (unsub) {
+      this.broadcastSubscriptions.set(key, unsub);
+    }
+    return () => {
+      const sub = this.broadcastSubscriptions.get(key);
+      if (sub) {
+        sub();
+        this.broadcastSubscriptions.delete(key);
+      }
+    };
+  }
+  /**
+   * Get broadcasts
+   */
+  getBroadcasts(limit) {
+    const messages = Array.from(this.broadcasts.values()).sort((a, b) => b.timestamp - a.timestamp);
+    return limit ? messages.slice(0, limit) : messages;
+  }
+  /**
+   * Subscribe to incoming broadcasts
+   */
+  onBroadcast(handler) {
+    this.broadcastHandlers.add(handler);
+    return () => this.broadcastHandlers.delete(handler);
+  }
+  // ===========================================================================
+  // Private: Message Handling
+  // ===========================================================================
+  handleIncomingMessage(msg) {
+    if (msg.senderTransportPubkey === this.deps?.identity.chainPubkey) return;
+    const message = {
+      id: msg.id,
+      senderPubkey: msg.senderTransportPubkey,
+      senderNametag: msg.senderNametag,
+      recipientPubkey: this.deps.identity.chainPubkey,
+      content: msg.content,
+      timestamp: msg.timestamp,
+      isRead: false
+    };
+    this.messages.set(message.id, message);
+    this.deps.emitEvent("message:dm", message);
+    for (const handler of this.dmHandlers) {
+      try {
+        handler(message);
+      } catch (error) {
+        console.error("[Communications] Handler error:", error);
+      }
+    }
+    if (this.config.autoSave) {
+      this.save();
+    }
+    this.pruneIfNeeded();
+  }
+  handleIncomingBroadcast(incoming) {
+    const message = {
+      id: incoming.id,
+      authorPubkey: incoming.authorTransportPubkey,
+      content: incoming.content,
+      timestamp: incoming.timestamp,
+      tags: incoming.tags
+    };
+    this.broadcasts.set(message.id, message);
+    this.deps.emitEvent("message:broadcast", message);
+    for (const handler of this.broadcastHandlers) {
+      try {
+        handler(message);
+      } catch (error) {
+        console.error("[Communications] Handler error:", error);
+      }
+    }
+  }
+  // ===========================================================================
+  // Private: Storage
+  // ===========================================================================
+  async save() {
+    const messages = Array.from(this.messages.values());
+    await this.deps.storage.set("direct_messages", JSON.stringify(messages));
+  }
+  pruneIfNeeded() {
+    if (this.messages.size <= this.config.maxMessages) return;
+    const sorted = Array.from(this.messages.entries()).sort(([, a], [, b]) => a.timestamp - b.timestamp);
+    const toRemove = sorted.slice(0, sorted.length - this.config.maxMessages);
+    for (const [id] of toRemove) {
+      this.messages.delete(id);
+    }
+  }
+  // ===========================================================================
+  // Private: Helpers
+  // ===========================================================================
+  async resolveRecipient(recipient) {
+    if (recipient.startsWith("@")) {
+      const pubkey = await this.deps.transport.resolveNametag?.(recipient.slice(1));
+      if (!pubkey) {
+        throw new Error(`Nametag not found: ${recipient}`);
+      }
+      return pubkey;
+    }
+    return recipient;
+  }
+  ensureInitialized() {
+    if (!this.deps) {
+      throw new Error("CommunicationsModule not initialized");
+    }
+  }
+};
+function createCommunicationsModule(config) {
+  return new CommunicationsModule(config);
+}
+
+// modules/groupchat/GroupChatModule.ts
+import {
+  NostrClient,
+  NostrKeyManager,
+  Filter
+} from "@unicitylabs/nostr-js-sdk";
+
+// modules/groupchat/types.ts
+var GroupRole = {
+  ADMIN: "ADMIN",
+  MODERATOR: "MODERATOR",
+  MEMBER: "MEMBER"
+};
+var GroupVisibility = {
+  PUBLIC: "PUBLIC",
+  PRIVATE: "PRIVATE"
+};
+
+// modules/groupchat/GroupChatModule.ts
+function createNip29Filter(data) {
+  return new Filter(data);
+}
+var GroupChatModule = class {
+  config;
+  deps = null;
+  // Nostr connection (separate from wallet relay)
+  client = null;
+  keyManager = null;
+  connected = false;
+  connecting = false;
+  connectPromise = null;
+  reconnectAttempts = 0;
+  reconnectTimer = null;
+  // Subscription tracking (for cleanup)
+  subscriptionIds = [];
+  // In-memory state
+  groups = /* @__PURE__ */ new Map();
+  messages = /* @__PURE__ */ new Map();
+  // groupId -> messages
+  members = /* @__PURE__ */ new Map();
+  // groupId -> members
+  processedEventIds = /* @__PURE__ */ new Set();
+  pendingLeaves = /* @__PURE__ */ new Set();
+  // Persistence debounce
+  persistTimer = null;
+  persistPromise = null;
+  // Relay admin cache
+  relayAdminPubkeys = null;
+  relayAdminFetchPromise = null;
+  // Listeners
+  messageHandlers = /* @__PURE__ */ new Set();
+  constructor(config) {
+    this.config = {
+      relays: config?.relays ?? [],
+      defaultMessageLimit: config?.defaultMessageLimit ?? 50,
+      maxPreviousTags: config?.maxPreviousTags ?? 3,
+      reconnectDelayMs: config?.reconnectDelayMs ?? 3e3,
+      maxReconnectAttempts: config?.maxReconnectAttempts ?? 5
+    };
+  }
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+  initialize(deps) {
+    if (this.deps) {
+      this.destroyConnection();
+    }
+    this.deps = deps;
+    const secretKey = Buffer.from(deps.identity.privateKey, "hex");
+    this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
+  }
+  async load() {
+    this.ensureInitialized();
+    const storage = this.deps.storage;
+    const groupsJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_GROUPS);
+    if (groupsJson) {
+      try {
+        const parsed = JSON.parse(groupsJson);
+        this.groups.clear();
+        for (const g of parsed) {
+          this.groups.set(g.id, g);
+        }
+      } catch {
+      }
+    }
+    const messagesJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MESSAGES);
+    if (messagesJson) {
+      try {
+        const parsed = JSON.parse(messagesJson);
+        this.messages.clear();
+        for (const m of parsed) {
+          const groupId = m.groupId;
+          if (!this.messages.has(groupId)) {
+            this.messages.set(groupId, []);
+          }
+          this.messages.get(groupId).push(m);
+        }
+      } catch {
+      }
+    }
+    const membersJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MEMBERS);
+    if (membersJson) {
+      try {
+        const parsed = JSON.parse(membersJson);
+        this.members.clear();
+        for (const m of parsed) {
+          const groupId = m.groupId;
+          if (!this.members.has(groupId)) {
+            this.members.set(groupId, []);
+          }
+          this.members.get(groupId).push(m);
+        }
+      } catch {
+      }
+    }
+    const processedJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_PROCESSED_EVENTS);
+    if (processedJson) {
+      try {
+        const parsed = JSON.parse(processedJson);
+        this.processedEventIds = new Set(parsed);
+      } catch {
+      }
+    }
+  }
+  destroy() {
+    this.destroyConnection();
+    this.groups.clear();
+    this.messages.clear();
+    this.members.clear();
+    this.processedEventIds.clear();
+    this.pendingLeaves.clear();
+    this.messageHandlers.clear();
+    this.relayAdminPubkeys = null;
+    this.relayAdminFetchPromise = null;
+    if (this.persistTimer) {
+      clearTimeout(this.persistTimer);
+      this.persistTimer = null;
+    }
+    this.deps = null;
+  }
+  destroyConnection() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.client) {
+      for (const subId of this.subscriptionIds) {
+        try {
+          this.client.unsubscribe(subId);
+        } catch {
+        }
+      }
+      this.subscriptionIds = [];
+      try {
+        this.client.disconnect();
+      } catch {
+      }
+      this.client = null;
+    }
+    this.connected = false;
+    this.connecting = false;
+    this.connectPromise = null;
+    this.reconnectAttempts = 0;
+    this.keyManager = null;
+  }
+  // ===========================================================================
+  // Connection
+  // ===========================================================================
+  async connect() {
+    if (this.connected) return;
+    if (this.connectPromise) {
+      return this.connectPromise;
+    }
+    this.connecting = true;
+    this.connectPromise = this.doConnect().finally(() => {
+      this.connecting = false;
+      this.connectPromise = null;
+    });
+    return this.connectPromise;
+  }
+  getConnectionStatus() {
+    return this.connected;
+  }
+  async doConnect() {
+    this.ensureInitialized();
+    if (!this.keyManager) {
+      const secretKey = Buffer.from(this.deps.identity.privateKey, "hex");
+      this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
+    }
+    const primaryRelay = this.config.relays[0];
+    if (primaryRelay) {
+      await this.checkAndClearOnRelayChange(primaryRelay);
+    }
+    this.client = new NostrClient(this.keyManager);
+    try {
+      await this.client.connect(...this.config.relays);
+      this.connected = true;
+      this.reconnectAttempts = 0;
+      this.deps.emitEvent("groupchat:connection", { connected: true });
+      if (this.groups.size === 0) {
+        await this.restoreJoinedGroups();
+      } else {
+        await this.subscribeToJoinedGroups();
+      }
+    } catch (error) {
+      console.error("[GroupChat] Failed to connect to relays", error);
+      this.deps.emitEvent("groupchat:connection", { connected: false });
+      this.scheduleReconnect();
+    }
+  }
+  scheduleReconnect() {
+    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      console.error("[GroupChat] Max reconnection attempts reached");
+      return;
+    }
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.deps) {
+        this.connect().catch(console.error);
+      }
+    }, this.config.reconnectDelayMs);
+  }
+  // ===========================================================================
+  // Subscription Management
+  // ===========================================================================
+  async subscribeToJoinedGroups() {
+    if (!this.client) return;
+    const groupIds = Array.from(this.groups.keys());
+    if (groupIds.length === 0) return;
+    this.trackSubscription(
+      createNip29Filter({
+        kinds: [NIP29_KINDS.CHAT_MESSAGE, NIP29_KINDS.THREAD_ROOT, NIP29_KINDS.THREAD_REPLY],
+        "#h": groupIds
+      }),
+      { onEvent: (event) => this.handleGroupEvent(event) }
+    );
+    this.trackSubscription(
+      createNip29Filter({
+        kinds: [NIP29_KINDS.GROUP_METADATA, NIP29_KINDS.GROUP_MEMBERS, NIP29_KINDS.GROUP_ADMINS],
+        "#d": groupIds
+      }),
+      { onEvent: (event) => this.handleMetadataEvent(event) }
+    );
+    this.trackSubscription(
+      createNip29Filter({
+        kinds: [NIP29_KINDS.DELETE_EVENT, NIP29_KINDS.REMOVE_USER, NIP29_KINDS.DELETE_GROUP],
+        "#h": groupIds
+      }),
+      { onEvent: (event) => this.handleModerationEvent(event) }
+    );
+  }
+  subscribeToGroup(groupId) {
+    if (!this.client) return;
+    this.trackSubscription(
+      createNip29Filter({
+        kinds: [NIP29_KINDS.CHAT_MESSAGE, NIP29_KINDS.THREAD_ROOT, NIP29_KINDS.THREAD_REPLY],
+        "#h": [groupId]
+      }),
+      { onEvent: (event) => this.handleGroupEvent(event) }
+    );
+    this.trackSubscription(
+      createNip29Filter({
+        kinds: [NIP29_KINDS.DELETE_EVENT, NIP29_KINDS.REMOVE_USER, NIP29_KINDS.DELETE_GROUP],
+        "#h": [groupId]
+      }),
+      { onEvent: (event) => this.handleModerationEvent(event) }
+    );
+  }
+  // ===========================================================================
+  // Event Handlers
+  // ===========================================================================
+  handleGroupEvent(event) {
+    if (this.processedEventIds.has(event.id)) return;
+    const groupId = this.getGroupIdFromEvent(event);
+    if (!groupId) return;
+    const group = this.groups.get(groupId);
+    if (!group) return;
+    const { text: content, senderNametag } = this.unwrapMessageContent(event.content);
+    const message = {
+      id: event.id,
+      groupId,
+      content,
+      timestamp: event.created_at * 1e3,
+      senderPubkey: event.pubkey,
+      senderNametag: senderNametag || void 0,
+      replyToId: this.extractReplyTo(event),
+      previousIds: this.extractPreviousIds(event)
+    };
+    this.saveMessageToMemory(message);
+    this.addProcessedEventId(event.id);
+    if (senderNametag) {
+      this.updateMemberNametag(groupId, event.pubkey, senderNametag, event.created_at * 1e3);
+    }
+    this.updateGroupLastMessage(groupId, content.slice(0, 100), message.timestamp);
+    const myPubkey = this.getMyPublicKey();
+    if (event.pubkey !== myPubkey) {
+      group.unreadCount = (group.unreadCount || 0) + 1;
+    }
+    this.deps.emitEvent("groupchat:message", message);
+    this.deps.emitEvent("groupchat:updated", {});
+    for (const handler of this.messageHandlers) {
+      try {
+        handler(message);
+      } catch {
+      }
+    }
+    this.schedulePersist();
+  }
+  handleMetadataEvent(event) {
+    const groupId = this.getGroupIdFromMetadataEvent(event);
+    if (!groupId) return;
+    const group = this.groups.get(groupId);
+    if (!group) return;
+    if (event.kind === NIP29_KINDS.GROUP_METADATA) {
+      if (!event.content || event.content.trim() === "") return;
+      try {
+        const metadata = JSON.parse(event.content);
+        group.name = metadata.name || group.name;
+        group.description = metadata.about || group.description;
+        group.picture = metadata.picture || group.picture;
+        group.updatedAt = event.created_at * 1e3;
+        this.groups.set(groupId, group);
+        this.persistGroups();
+      } catch {
+      }
+    } else if (event.kind === NIP29_KINDS.GROUP_MEMBERS) {
+      this.updateMembersFromEvent(groupId, event);
+    } else if (event.kind === NIP29_KINDS.GROUP_ADMINS) {
+      this.updateAdminsFromEvent(groupId, event);
+    }
+  }
+  handleModerationEvent(event) {
+    const groupId = this.getGroupIdFromEvent(event);
+    if (!groupId) return;
+    const group = this.groups.get(groupId);
+    if (!group) return;
+    if (event.kind === NIP29_KINDS.DELETE_EVENT) {
+      const eTags = event.tags.filter((t) => t[0] === "e");
+      for (const tag of eTags) {
+        const messageId = tag[1];
+        if (messageId) {
+          this.deleteMessageFromMemory(groupId, messageId);
+        }
+      }
+      this.deps.emitEvent("groupchat:updated", {});
+      this.persistMessages();
+    } else if (event.kind === NIP29_KINDS.REMOVE_USER) {
+      if (this.processedEventIds.has(event.id)) return;
+      const eventTimestampMs = event.created_at * 1e3;
+      if (group.localJoinedAt && eventTimestampMs < group.localJoinedAt) {
+        this.addProcessedEventId(event.id);
+        return;
+      }
+      this.addProcessedEventId(event.id);
+      const pTags = event.tags.filter((t) => t[0] === "p");
+      const myPubkey = this.getMyPublicKey();
+      for (const tag of pTags) {
+        const removedPubkey = tag[1];
+        if (!removedPubkey) continue;
+        if (removedPubkey === myPubkey) {
+          if (this.pendingLeaves.has(groupId)) {
+            this.pendingLeaves.delete(groupId);
+            this.deps.emitEvent("groupchat:updated", {});
+          } else {
+            const groupName = group.name || groupId;
+            this.removeGroupFromMemory(groupId);
+            this.deps.emitEvent("groupchat:kicked", { groupId, groupName });
+            this.deps.emitEvent("groupchat:updated", {});
+          }
+        } else {
+          this.removeMemberFromMemory(groupId, removedPubkey);
+        }
+      }
+      this.schedulePersist();
+    } else if (event.kind === NIP29_KINDS.DELETE_GROUP) {
+      if (this.processedEventIds.has(event.id)) return;
+      const deleteTimestampMs = event.created_at * 1e3;
+      if (deleteTimestampMs < group.createdAt) {
+        this.addProcessedEventId(event.id);
+        return;
+      }
+      this.addProcessedEventId(event.id);
+      const groupName = group.name || groupId;
+      this.removeGroupFromMemory(groupId);
+      this.deps.emitEvent("groupchat:group_deleted", { groupId, groupName });
+      this.deps.emitEvent("groupchat:updated", {});
+      this.schedulePersist();
+    }
+  }
+  updateMembersFromEvent(groupId, event) {
+    const pTags = event.tags.filter((t) => t[0] === "p");
+    const existingMembers = this.members.get(groupId) || [];
+    for (const tag of pTags) {
+      const pubkey = tag[1];
+      const roleFromTag = tag[3];
+      const existing = existingMembers.find((m) => m.pubkey === pubkey);
+      const role = roleFromTag || existing?.role || GroupRole.MEMBER;
+      const member = {
+        pubkey,
+        groupId,
+        role,
+        nametag: existing?.nametag,
+        joinedAt: existing?.joinedAt || event.created_at * 1e3
+      };
+      this.saveMemberToMemory(member);
+    }
+    this.persistMembers();
+  }
+  updateAdminsFromEvent(groupId, event) {
+    const pTags = event.tags.filter((t) => t[0] === "p");
+    const existingMembers = this.members.get(groupId) || [];
+    for (const tag of pTags) {
+      const pubkey = tag[1];
+      const existing = existingMembers.find((m) => m.pubkey === pubkey);
+      if (existing) {
+        existing.role = GroupRole.ADMIN;
+        this.saveMemberToMemory(existing);
+      } else {
+        this.saveMemberToMemory({
+          pubkey,
+          groupId,
+          role: GroupRole.ADMIN,
+          joinedAt: event.created_at * 1e3
+        });
+      }
+    }
+    this.persistMembers();
+  }
+  // ===========================================================================
+  // Group Membership Restoration
+  // ===========================================================================
+  async restoreJoinedGroups() {
+    if (!this.client) return [];
+    const myPubkey = this.getMyPublicKey();
+    if (!myPubkey) return [];
+    const groupIdsWithMembership = /* @__PURE__ */ new Set();
+    await this.oneshotSubscription(
+      new Filter({ kinds: [NIP29_KINDS.GROUP_MEMBERS] }),
+      {
+        onEvent: (event) => {
+          const groupId = this.getGroupIdFromMetadataEvent(event);
+          if (!groupId) return;
+          const pTags = event.tags.filter((t) => t[0] === "p");
+          if (pTags.some((tag) => tag[1] === myPubkey)) {
+            groupIdsWithMembership.add(groupId);
+          }
+        },
+        onComplete: () => {
+        },
+        timeoutMs: 15e3
+      }
+    );
+    if (groupIdsWithMembership.size === 0) return [];
+    const restoredGroups = [];
+    for (const groupId of groupIdsWithMembership) {
+      if (this.groups.has(groupId)) continue;
+      try {
+        const group = await this.fetchGroupMetadataInternal(groupId);
+        if (group) {
+          this.groups.set(groupId, group);
+          restoredGroups.push(group);
+          await Promise.all([
+            this.fetchAndSaveMembers(groupId),
+            this.fetchMessages(groupId)
+          ]);
+        }
+      } catch {
+      }
+    }
+    if (restoredGroups.length > 0) {
+      await this.subscribeToJoinedGroups();
+      this.deps.emitEvent("groupchat:updated", {});
+      this.schedulePersist();
+    }
+    return restoredGroups;
+  }
+  // ===========================================================================
+  // Public API — Groups
+  // ===========================================================================
+  async fetchAvailableGroups() {
+    await this.ensureConnected();
+    if (!this.client) return [];
+    const groupsMap = /* @__PURE__ */ new Map();
+    const memberCountsMap = /* @__PURE__ */ new Map();
+    await Promise.all([
+      this.oneshotSubscription(
+        new Filter({ kinds: [NIP29_KINDS.GROUP_METADATA] }),
+        {
+          onEvent: (event) => {
+            const group = this.parseGroupMetadata(event);
+            if (group && group.visibility === GroupVisibility.PUBLIC) {
+              const existing = groupsMap.get(group.id);
+              if (!existing || group.createdAt > existing.createdAt) {
+                groupsMap.set(group.id, group);
+              }
+            }
+          },
+          onComplete: () => {
+          },
+          timeoutMs: 1e4
+        }
+      ),
+      this.oneshotSubscription(
+        new Filter({ kinds: [NIP29_KINDS.GROUP_MEMBERS] }),
+        {
+          onEvent: (event) => {
+            const groupId = this.getGroupIdFromMetadataEvent(event);
+            if (groupId) {
+              const pTags = event.tags.filter((t) => t[0] === "p");
+              memberCountsMap.set(groupId, pTags.length);
+            }
+          },
+          onComplete: () => {
+          },
+          timeoutMs: 1e4
+        }
+      )
+    ]);
+    for (const [groupId, count] of memberCountsMap) {
+      const group = groupsMap.get(groupId);
+      if (group) group.memberCount = count;
+    }
+    return Array.from(groupsMap.values());
+  }
+  async joinGroup(groupId, inviteCode) {
+    await this.ensureConnected();
+    if (!this.client) return false;
+    try {
+      let group = await this.fetchGroupMetadataInternal(groupId);
+      if (!group && !inviteCode) return false;
+      const tags = [["h", groupId]];
+      if (inviteCode) tags.push(["code", inviteCode]);
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.JOIN_REQUEST,
+        tags,
+        content: ""
+      });
+      if (eventId) {
+        if (!group) {
+          group = await this.fetchGroupMetadataInternal(groupId);
+          if (!group) return false;
+        }
+        group.localJoinedAt = Date.now();
+        this.groups.set(groupId, group);
+        this.subscribeToGroup(groupId);
+        await Promise.all([
+          this.fetchMessages(groupId),
+          this.fetchAndSaveMembers(groupId)
+        ]);
+        this.deps.emitEvent("groupchat:joined", { groupId, groupName: group.name });
+        this.deps.emitEvent("groupchat:updated", {});
+        this.persistAll();
+        return true;
+      }
+      return false;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes("already a member")) {
+        const group = await this.fetchGroupMetadataInternal(groupId);
+        if (group) {
+          group.localJoinedAt = Date.now();
+          this.groups.set(groupId, group);
+          this.subscribeToGroup(groupId);
+          await Promise.all([
+            this.fetchMessages(groupId),
+            this.fetchAndSaveMembers(groupId)
+          ]);
+          this.deps.emitEvent("groupchat:joined", { groupId, groupName: group.name });
+          this.deps.emitEvent("groupchat:updated", {});
+          this.persistAll();
+          return true;
+        }
+      }
+      console.error("[GroupChat] Failed to join group", error);
+      return false;
+    }
+  }
+  async leaveGroup(groupId) {
+    await this.ensureConnected();
+    if (!this.client) return false;
+    try {
+      this.pendingLeaves.add(groupId);
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.LEAVE_REQUEST,
+        tags: [["h", groupId]],
+        content: ""
+      });
+      if (eventId) {
+        this.removeGroupFromMemory(groupId);
+        this.deps.emitEvent("groupchat:left", { groupId });
+        this.deps.emitEvent("groupchat:updated", {});
+        this.persistAll();
+        return true;
+      }
+      this.pendingLeaves.delete(groupId);
+      return false;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes("group not found") || msg.includes("not a member")) {
+        this.removeGroupFromMemory(groupId);
+        this.persistAll();
+        return true;
+      }
+      console.error("[GroupChat] Failed to leave group", error);
+      return false;
+    }
+  }
+  async createGroup(options) {
+    await this.ensureConnected();
+    if (!this.client) return null;
+    const creatorPubkey = this.getMyPublicKey();
+    if (!creatorPubkey) return null;
+    const proposedGroupId = options.name.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 20) || this.randomId();
+    try {
+      const isPrivate = options.visibility === GroupVisibility.PRIVATE;
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.CREATE_GROUP,
+        tags: [["h", proposedGroupId]],
+        content: JSON.stringify({
+          name: options.name,
+          about: options.description,
+          picture: options.picture,
+          closed: true,
+          private: isPrivate,
+          hidden: isPrivate
+        })
+      });
+      if (!eventId) return null;
+      let group = await this.fetchGroupMetadataInternal(proposedGroupId);
+      if (!group) {
+        group = {
+          id: proposedGroupId,
+          relayUrl: this.config.relays[0] || "",
+          name: options.name,
+          description: options.description,
+          visibility: options.visibility || GroupVisibility.PUBLIC,
+          createdAt: Date.now(),
+          memberCount: 1
+        };
+      }
+      if (!group.name || group.name === "Unnamed Group") {
+        group.name = options.name;
+      }
+      if (options.description && !group.description) {
+        group.description = options.description;
+      }
+      group.visibility = options.visibility || GroupVisibility.PUBLIC;
+      group.memberCount = 1;
+      this.groups.set(group.id, group);
+      this.subscribeToGroup(group.id);
+      this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.JOIN_REQUEST,
+        tags: [["h", group.id]],
+        content: ""
+      }).catch(() => {
+      });
+      await this.fetchAndSaveMembers(group.id).catch(() => {
+      });
+      this.saveMemberToMemory({
+        pubkey: creatorPubkey,
+        groupId: group.id,
+        role: GroupRole.ADMIN,
+        joinedAt: Date.now()
+      });
+      this.deps.emitEvent("groupchat:joined", { groupId: group.id, groupName: group.name });
+      this.deps.emitEvent("groupchat:updated", {});
+      this.schedulePersist();
+      return group;
+    } catch (error) {
+      console.error("[GroupChat] Failed to create group", error);
+      return null;
+    }
+  }
+  async deleteGroup(groupId) {
+    await this.ensureConnected();
+    if (!this.client) return false;
+    const group = this.groups.get(groupId);
+    if (!group) return false;
+    const canDelete = await this.canModerateGroup(groupId);
+    if (!canDelete) return false;
+    try {
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.DELETE_GROUP,
+        tags: [["h", groupId]],
+        content: ""
+      });
+      if (eventId) {
+        const groupName = group.name || groupId;
+        this.removeGroupFromMemory(groupId);
+        this.deps.emitEvent("groupchat:group_deleted", { groupId, groupName });
+        this.deps.emitEvent("groupchat:updated", {});
+        this.persistAll();
+        return true;
+      }
+      return false;
+    } catch (error) {
+      console.error("[GroupChat] Failed to delete group", error);
+      return false;
+    }
+  }
+  async createInvite(groupId) {
+    await this.ensureConnected();
+    if (!this.client) return null;
+    if (!this.isCurrentUserAdmin(groupId)) return null;
+    try {
+      const inviteCode = this.randomId();
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.CREATE_INVITE,
+        tags: [
+          ["h", groupId],
+          ["code", inviteCode]
+        ],
+        content: ""
+      });
+      return eventId ? inviteCode : null;
+    } catch (error) {
+      console.error("[GroupChat] Failed to create invite", error);
+      return null;
+    }
+  }
+  // ===========================================================================
+  // Public API — Messages
+  // ===========================================================================
+  async sendMessage(groupId, content, replyToId) {
+    await this.ensureConnected();
+    if (!this.client) return null;
+    const group = this.groups.get(groupId);
+    if (!group) return null;
+    try {
+      const senderNametag = this.deps.identity.nametag || null;
+      const kind = replyToId ? NIP29_KINDS.THREAD_REPLY : NIP29_KINDS.CHAT_MESSAGE;
+      const tags = [["h", groupId]];
+      const groupMessages = this.messages.get(groupId) || [];
+      const recentIds = groupMessages.slice(-this.config.maxPreviousTags).map((m) => (m.id || "").slice(0, 8)).filter(Boolean);
+      if (recentIds.length > 0) {
+        tags.push(["previous", ...recentIds]);
+      }
+      if (replyToId) {
+        tags.push(["e", replyToId, "", "reply"]);
+      }
+      const wrappedContent = this.wrapMessageContent(content, senderNametag);
+      const eventId = await this.client.createAndPublishEvent({
+        kind,
+        tags,
+        content: wrappedContent
+      });
+      if (eventId) {
+        const myPubkey = this.getMyPublicKey();
+        const message = {
+          id: eventId,
+          groupId,
+          content,
+          timestamp: Date.now(),
+          senderPubkey: myPubkey || "",
+          senderNametag: senderNametag || void 0,
+          replyToId,
+          previousIds: recentIds
+        };
+        this.saveMessageToMemory(message);
+        this.addProcessedEventId(eventId);
+        this.updateGroupLastMessage(groupId, content.slice(0, 100), message.timestamp);
+        this.persistAll();
+        return message;
+      }
+      return null;
+    } catch (error) {
+      console.error("[GroupChat] Failed to send message", error);
+      return null;
+    }
+  }
+  async fetchMessages(groupId, since, limit) {
+    await this.ensureConnected();
+    if (!this.client) return [];
+    const fetchedMessages = [];
+    const filterData = {
+      kinds: [NIP29_KINDS.CHAT_MESSAGE, NIP29_KINDS.THREAD_ROOT, NIP29_KINDS.THREAD_REPLY],
+      "#h": [groupId]
+    };
+    if (since) filterData.since = Math.floor(since / 1e3);
+    if (limit) filterData.limit = limit;
+    if (!limit && !since) filterData.limit = this.config.defaultMessageLimit;
+    return this.oneshotSubscription(createNip29Filter(filterData), {
+      onEvent: (event) => {
+        const { text: content, senderNametag } = this.unwrapMessageContent(event.content);
+        const message = {
+          id: event.id,
+          groupId,
+          content,
+          timestamp: event.created_at * 1e3,
+          senderPubkey: event.pubkey,
+          senderNametag: senderNametag || void 0,
+          replyToId: this.extractReplyTo(event),
+          previousIds: this.extractPreviousIds(event)
+        };
+        fetchedMessages.push(message);
+        this.saveMessageToMemory(message);
+        this.addProcessedEventId(event.id);
+        if (senderNametag) {
+          this.updateMemberNametag(groupId, event.pubkey, senderNametag, event.created_at * 1e3);
+        }
+      },
+      onComplete: () => {
+        this.schedulePersist();
+        return fetchedMessages;
+      },
+      timeoutMs: 1e4
+    });
+  }
+  // ===========================================================================
+  // Public API — Queries (from local state)
+  // ===========================================================================
+  getGroups() {
+    return Array.from(this.groups.values()).sort((a, b) => (b.lastMessageTime || 0) - (a.lastMessageTime || 0));
+  }
+  getGroup(groupId) {
+    return this.groups.get(groupId) || null;
+  }
+  getMessages(groupId) {
+    return (this.messages.get(groupId) || []).sort((a, b) => a.timestamp - b.timestamp);
+  }
+  getMembers(groupId) {
+    return (this.members.get(groupId) || []).sort((a, b) => a.joinedAt - b.joinedAt);
+  }
+  getMember(groupId, pubkey) {
+    const members = this.members.get(groupId) || [];
+    return members.find((m) => m.pubkey === pubkey) || null;
+  }
+  getTotalUnreadCount() {
+    let total = 0;
+    for (const group of this.groups.values()) {
+      total += group.unreadCount || 0;
+    }
+    return total;
+  }
+  markGroupAsRead(groupId) {
+    const group = this.groups.get(groupId);
+    if (group && (group.unreadCount || 0) > 0) {
+      group.unreadCount = 0;
+      this.groups.set(groupId, group);
+      this.persistGroups();
+    }
+  }
+  // ===========================================================================
+  // Public API — Admin
+  // ===========================================================================
+  async kickUser(groupId, userPubkey, reason) {
+    await this.ensureConnected();
+    if (!this.client) return false;
+    const canModerate = await this.canModerateGroup(groupId);
+    if (!canModerate) return false;
+    const myPubkey = this.getMyPublicKey();
+    if (myPubkey === userPubkey) return false;
+    try {
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.REMOVE_USER,
+        tags: [["h", groupId], ["p", userPubkey]],
+        content: reason || ""
+      });
+      if (eventId) {
+        this.removeMemberFromMemory(groupId, userPubkey);
+        this.deps.emitEvent("groupchat:updated", {});
+        this.persistMembers();
+        return true;
+      }
+      return false;
+    } catch (error) {
+      console.error("[GroupChat] Failed to kick user", error);
+      return false;
+    }
+  }
+  async deleteMessage(groupId, messageId) {
+    await this.ensureConnected();
+    if (!this.client) return false;
+    const canModerate = await this.canModerateGroup(groupId);
+    if (!canModerate) return false;
+    try {
+      const eventId = await this.client.createAndPublishEvent({
+        kind: NIP29_KINDS.DELETE_EVENT,
+        tags: [["h", groupId], ["e", messageId]],
+        content: ""
+      });
+      if (eventId) {
+        this.deleteMessageFromMemory(groupId, messageId);
+        this.deps.emitEvent("groupchat:updated", {});
+        this.persistMessages();
+        return true;
+      }
+      return false;
+    } catch (error) {
+      console.error("[GroupChat] Failed to delete message", error);
+      return false;
+    }
+  }
+  isCurrentUserAdmin(groupId) {
+    const myPubkey = this.getMyPublicKey();
+    if (!myPubkey) return false;
+    const member = this.getMember(groupId, myPubkey);
+    return member?.role === GroupRole.ADMIN;
+  }
+  isCurrentUserModerator(groupId) {
+    const myPubkey = this.getMyPublicKey();
+    if (!myPubkey) return false;
+    const member = this.getMember(groupId, myPubkey);
+    return member?.role === GroupRole.ADMIN || member?.role === GroupRole.MODERATOR;
+  }
+  /**
+   * Check if current user can moderate a group:
+   * - Group admin/moderator can always moderate their group
+   * - Relay admins can moderate public groups
+   */
+  async canModerateGroup(groupId) {
+    if (this.isCurrentUserAdmin(groupId) || this.isCurrentUserModerator(groupId)) {
+      return true;
+    }
+    const group = this.groups.get(groupId);
+    if (group && group.visibility === GroupVisibility.PUBLIC) {
+      return this.isCurrentUserRelayAdmin();
+    }
+    return false;
+  }
+  async isCurrentUserRelayAdmin() {
+    const myPubkey = this.getMyPublicKey();
+    if (!myPubkey) return false;
+    const admins = await this.fetchRelayAdmins();
+    return admins.has(myPubkey);
+  }
+  getCurrentUserRole(groupId) {
+    const myPubkey = this.getMyPublicKey();
+    if (!myPubkey) return null;
+    const member = this.getMember(groupId, myPubkey);
+    return member?.role || null;
+  }
+  // ===========================================================================
+  // Public API — Listeners
+  // ===========================================================================
+  onMessage(handler) {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+  // ===========================================================================
+  // Public API — Utilities
+  // ===========================================================================
+  getRelayUrls() {
+    return this.config.relays;
+  }
+  getMyPublicKey() {
+    return this.keyManager?.getPublicKeyHex() || null;
+  }
+  // ===========================================================================
+  // Private — Relay Admin
+  // ===========================================================================
+  async fetchRelayAdmins() {
+    if (this.relayAdminPubkeys) return this.relayAdminPubkeys;
+    if (this.relayAdminFetchPromise) return this.relayAdminFetchPromise;
+    this.relayAdminFetchPromise = this.doFetchRelayAdmins();
+    const result = await this.relayAdminFetchPromise;
+    this.relayAdminFetchPromise = null;
+    return result;
+  }
+  async doFetchRelayAdmins() {
+    await this.ensureConnected();
+    if (!this.client) return /* @__PURE__ */ new Set();
+    const adminPubkeys = /* @__PURE__ */ new Set();
+    return this.oneshotSubscription(
+      new Filter({ kinds: [NIP29_KINDS.GROUP_ADMINS], "#d": ["", "_"] }),
+      {
+        onEvent: (event) => {
+          const pTags = event.tags.filter((t) => t[0] === "p");
+          for (const tag of pTags) {
+            if (tag[1]) adminPubkeys.add(tag[1]);
+          }
+        },
+        onComplete: () => {
+          this.relayAdminPubkeys = adminPubkeys;
+          return adminPubkeys;
+        }
+      }
+    );
+  }
+  // ===========================================================================
+  // Private — Fetch Helpers
+  // ===========================================================================
+  async fetchGroupMetadataInternal(groupId) {
+    if (!this.client) return null;
+    let result = null;
+    return this.oneshotSubscription(
+      new Filter({ kinds: [NIP29_KINDS.GROUP_METADATA], "#d": [groupId] }),
+      {
+        onEvent: (event) => {
+          if (!result) result = this.parseGroupMetadata(event);
+        },
+        onComplete: () => result
+      }
+    );
+  }
+  async fetchAndSaveMembers(groupId) {
+    const [members, adminPubkeys] = await Promise.all([
+      this.fetchGroupMembersInternal(groupId),
+      this.fetchGroupAdminsInternal(groupId)
+    ]);
+    for (const member of members) {
+      if (adminPubkeys.includes(member.pubkey)) {
+        member.role = GroupRole.ADMIN;
+      }
+      this.saveMemberToMemory(member);
+    }
+    for (const pubkey of adminPubkeys) {
+      const existing = (this.members.get(groupId) || []).find((m) => m.pubkey === pubkey);
+      if (!existing) {
+        this.saveMemberToMemory({
+          pubkey,
+          groupId,
+          role: GroupRole.ADMIN,
+          joinedAt: Date.now()
+        });
+      }
+    }
+    this.persistMembers();
+  }
+  async fetchGroupMembersInternal(groupId) {
+    if (!this.client) return [];
+    const members = [];
+    return this.oneshotSubscription(
+      new Filter({ kinds: [NIP29_KINDS.GROUP_MEMBERS], "#d": [groupId] }),
+      {
+        onEvent: (event) => {
+          const pTags = event.tags.filter((t) => t[0] === "p");
+          for (const tag of pTags) {
+            members.push({
+              pubkey: tag[1],
+              groupId,
+              role: tag[3] || GroupRole.MEMBER,
+              joinedAt: event.created_at * 1e3
+            });
+          }
+        },
+        onComplete: () => members
+      }
+    );
+  }
+  async fetchGroupAdminsInternal(groupId) {
+    if (!this.client) return [];
+    const adminPubkeys = [];
+    return this.oneshotSubscription(
+      new Filter({ kinds: [NIP29_KINDS.GROUP_ADMINS], "#d": [groupId] }),
+      {
+        onEvent: (event) => {
+          const pTags = event.tags.filter((t) => t[0] === "p");
+          for (const tag of pTags) {
+            if (tag[1] && !adminPubkeys.includes(tag[1])) {
+              adminPubkeys.push(tag[1]);
+            }
+          }
+        },
+        onComplete: () => adminPubkeys
+      }
+    );
+  }
+  // ===========================================================================
+  // Private — In-Memory State Helpers
   // ===========================================================================
-  /**
-   * Send direct message
-   */
-  async sendDM(recipient, content) {
-    this.ensureInitialized();
-    const recipientPubkey = await this.resolveRecipient(recipient);
-    const eventId = await this.deps.transport.sendMessage(recipientPubkey, content);
-    const message = {
-      id: eventId,
-      senderPubkey: this.deps.identity.chainPubkey,
-      senderNametag: this.deps.identity.nametag,
-      recipientPubkey,
-      content,
-      timestamp: Date.now(),
-      isRead: true
-    };
-    this.messages.set(message.id, message);
-    if (this.config.autoSave) {
-      await this.save();
+  saveMessageToMemory(message) {
+    const groupId = message.groupId;
+    if (!this.messages.has(groupId)) {
+      this.messages.set(groupId, []);
+    }
+    const msgs = this.messages.get(groupId);
+    const idx = msgs.findIndex((m) => m.id === message.id);
+    if (idx >= 0) {
+      msgs[idx] = message;
+    } else {
+      msgs.push(message);
+      const maxMessages = this.config.defaultMessageLimit * 2;
+      if (msgs.length > maxMessages) {
+        msgs.splice(0, msgs.length - maxMessages);
+      }
     }
-    return message;
   }
-  /**
-   * Get conversation with peer
-   */
-  getConversation(peerPubkey) {
-    return Array.from(this.messages.values()).filter(
-      (m) => m.senderPubkey === peerPubkey || m.recipientPubkey === peerPubkey
-    ).sort((a, b) => a.timestamp - b.timestamp);
+  deleteMessageFromMemory(groupId, messageId) {
+    const msgs = this.messages.get(groupId);
+    if (msgs) {
+      const idx = msgs.findIndex((m) => m.id === messageId);
+      if (idx >= 0) msgs.splice(idx, 1);
+    }
   }
-  /**
-   * Get all conversations grouped by peer
-   */
-  getConversations() {
-    const conversations = /* @__PURE__ */ new Map();
-    for (const message of this.messages.values()) {
-      const peer = message.senderPubkey === this.deps?.identity.chainPubkey ? message.recipientPubkey : message.senderPubkey;
-      if (!conversations.has(peer)) {
-        conversations.set(peer, []);
-      }
-      conversations.get(peer).push(message);
+  saveMemberToMemory(member) {
+    const groupId = member.groupId;
+    if (!this.members.has(groupId)) {
+      this.members.set(groupId, []);
     }
-    for (const msgs of conversations.values()) {
-      msgs.sort((a, b) => a.timestamp - b.timestamp);
+    const mems = this.members.get(groupId);
+    const idx = mems.findIndex((m) => m.pubkey === member.pubkey);
+    if (idx >= 0) {
+      mems[idx] = member;
+    } else {
+      mems.push(member);
     }
-    return conversations;
   }
-  /**
-   * Mark messages as read
-   */
-  async markAsRead(messageIds) {
-    for (const id of messageIds) {
-      const msg = this.messages.get(id);
-      if (msg) {
-        msg.isRead = true;
-      }
+  removeMemberFromMemory(groupId, pubkey) {
+    const mems = this.members.get(groupId);
+    if (mems) {
+      const idx = mems.findIndex((m) => m.pubkey === pubkey);
+      if (idx >= 0) mems.splice(idx, 1);
     }
-    if (this.config.autoSave) {
-      await this.save();
+    const group = this.groups.get(groupId);
+    if (group) {
+      group.memberCount = (this.members.get(groupId) || []).length;
+      this.groups.set(groupId, group);
     }
   }
-  /**
-   * Get unread count
-   */
-  getUnreadCount(peerPubkey) {
-    let messages = Array.from(this.messages.values()).filter(
-      (m) => !m.isRead && m.senderPubkey !== this.deps?.identity.chainPubkey
-    );
-    if (peerPubkey) {
-      messages = messages.filter((m) => m.senderPubkey === peerPubkey);
+  removeGroupFromMemory(groupId) {
+    this.groups.delete(groupId);
+    this.messages.delete(groupId);
+    this.members.delete(groupId);
+  }
+  updateGroupLastMessage(groupId, text, timestamp) {
+    const group = this.groups.get(groupId);
+    if (group && timestamp >= (group.lastMessageTime || 0)) {
+      group.lastMessageText = text;
+      group.lastMessageTime = timestamp;
+      this.groups.set(groupId, group);
     }
-    return messages.length;
   }
-  /**
-   * Subscribe to incoming DMs
-   */
-  onDirectMessage(handler) {
-    this.dmHandlers.add(handler);
-    return () => this.dmHandlers.delete(handler);
+  updateMemberNametag(groupId, pubkey, nametag, joinedAt) {
+    const members = this.members.get(groupId) || [];
+    const existing = members.find((m) => m.pubkey === pubkey);
+    if (existing) {
+      if (existing.nametag !== nametag) {
+        existing.nametag = nametag;
+        this.saveMemberToMemory(existing);
+      }
+    } else {
+      this.saveMemberToMemory({
+        pubkey,
+        groupId,
+        role: GroupRole.MEMBER,
+        nametag,
+        joinedAt
+      });
+    }
+  }
+  addProcessedEventId(eventId) {
+    this.processedEventIds.add(eventId);
+    if (this.processedEventIds.size > 1e4) {
+      const arr = Array.from(this.processedEventIds);
+      this.processedEventIds = new Set(arr.slice(arr.length - 1e4));
+    }
   }
   // ===========================================================================
-  // Public API - Broadcasts
+  // Private — Persistence
   // ===========================================================================
-  /**
-   * Publish broadcast message
-   */
-  async broadcast(content, tags) {
-    this.ensureInitialized();
-    const eventId = await this.deps.transport.publishBroadcast?.(content, tags);
-    const message = {
-      id: eventId ?? crypto.randomUUID(),
-      authorPubkey: this.deps.identity.chainPubkey,
-      authorNametag: this.deps.identity.nametag,
-      content,
-      timestamp: Date.now(),
-      tags
-    };
-    this.broadcasts.set(message.id, message);
-    return message;
+  /** Schedule a debounced persist (coalesces rapid event bursts). */
+  schedulePersist() {
+    if (this.persistTimer) return;
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null;
+      this.persistPromise = this.doPersistAll().catch((err) => {
+        console.error("[GroupChat] Persistence error:", err);
+      }).finally(() => {
+        this.persistPromise = null;
+      });
+    }, 200);
   }
-  /**
-   * Subscribe to broadcasts with tags
-   */
-  subscribeToBroadcasts(tags) {
-    this.ensureInitialized();
-    const key = tags.sort().join(":");
-    if (this.broadcastSubscriptions.has(key)) {
-      return () => {
-      };
+  /** Persist immediately (for explicit flush points). */
+  async persistAll() {
+    if (this.persistTimer) {
+      clearTimeout(this.persistTimer);
+      this.persistTimer = null;
     }
-    const unsub = this.deps.transport.subscribeToBroadcast?.(tags, (broadcast2) => {
-      this.handleIncomingBroadcast(broadcast2);
-    });
-    if (unsub) {
-      this.broadcastSubscriptions.set(key, unsub);
+    if (this.persistPromise) {
+      await this.persistPromise;
     }
-    return () => {
-      const sub = this.broadcastSubscriptions.get(key);
-      if (sub) {
-        sub();
-        this.broadcastSubscriptions.delete(key);
-      }
-    };
+    await this.doPersistAll();
   }
-  /**
-   * Get broadcasts
-   */
-  getBroadcasts(limit) {
-    const messages = Array.from(this.broadcasts.values()).sort((a, b) => b.timestamp - a.timestamp);
-    return limit ? messages.slice(0, limit) : messages;
+  async doPersistAll() {
+    await Promise.all([
+      this.persistGroups(),
+      this.persistMessages(),
+      this.persistMembers(),
+      this.persistProcessedEvents()
+    ]);
   }
-  /**
-   * Subscribe to incoming broadcasts
-   */
-  onBroadcast(handler) {
-    this.broadcastHandlers.add(handler);
-    return () => this.broadcastHandlers.delete(handler);
+  async persistGroups() {
+    if (!this.deps) return;
+    const data = Array.from(this.groups.values());
+    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_GROUPS, JSON.stringify(data));
+  }
+  async persistMessages() {
+    if (!this.deps) return;
+    const allMessages = [];
+    for (const msgs of this.messages.values()) {
+      allMessages.push(...msgs);
+    }
+    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MESSAGES, JSON.stringify(allMessages));
+  }
+  async persistMembers() {
+    if (!this.deps) return;
+    const allMembers = [];
+    for (const mems of this.members.values()) {
+      allMembers.push(...mems);
+    }
+    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MEMBERS, JSON.stringify(allMembers));
+  }
+  async persistProcessedEvents() {
+    if (!this.deps) return;
+    const arr = Array.from(this.processedEventIds);
+    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_PROCESSED_EVENTS, JSON.stringify(arr));
   }
   // ===========================================================================
-  // Private: Message Handling
+  // Private — Relay URL Change Detection
   // ===========================================================================
-  handleIncomingMessage(msg) {
-    if (msg.senderTransportPubkey === this.deps?.identity.chainPubkey) return;
-    const message = {
-      id: msg.id,
-      senderPubkey: msg.senderTransportPubkey,
-      senderNametag: msg.senderNametag,
-      recipientPubkey: this.deps.identity.chainPubkey,
-      content: msg.content,
-      timestamp: msg.timestamp,
-      isRead: false
-    };
-    this.messages.set(message.id, message);
-    this.deps.emitEvent("message:dm", message);
-    for (const handler of this.dmHandlers) {
-      try {
-        handler(message);
-      } catch (error) {
-        console.error("[Communications] Handler error:", error);
+  async checkAndClearOnRelayChange(currentRelayUrl) {
+    if (!this.deps) return;
+    const stored = await this.deps.storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_RELAY_URL);
+    if (stored && stored !== currentRelayUrl) {
+      this.groups.clear();
+      this.messages.clear();
+      this.members.clear();
+      this.processedEventIds.clear();
+      await this.persistAll();
+    }
+    if (!stored) {
+      for (const group of this.groups.values()) {
+        if (group.relayUrl && group.relayUrl !== currentRelayUrl) {
+          this.groups.clear();
+          this.messages.clear();
+          this.members.clear();
+          this.processedEventIds.clear();
+          await this.persistAll();
+          break;
+        }
       }
     }
-    if (this.config.autoSave) {
-      this.save();
+    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_RELAY_URL, currentRelayUrl);
+  }
+  // ===========================================================================
+  // Private — Message Content Wrapping
+  // ===========================================================================
+  wrapMessageContent(content, senderNametag) {
+    if (senderNametag) {
+      return JSON.stringify({ senderNametag, text: content });
     }
-    this.pruneIfNeeded();
+    return content;
   }
-  handleIncomingBroadcast(incoming) {
-    const message = {
-      id: incoming.id,
-      authorPubkey: incoming.authorTransportPubkey,
-      content: incoming.content,
-      timestamp: incoming.timestamp,
-      tags: incoming.tags
-    };
-    this.broadcasts.set(message.id, message);
-    this.deps.emitEvent("message:broadcast", message);
-    for (const handler of this.broadcastHandlers) {
-      try {
-        handler(message);
-      } catch (error) {
-        console.error("[Communications] Handler error:", error);
+  unwrapMessageContent(content) {
+    try {
+      const parsed = JSON.parse(content);
+      if (typeof parsed === "object" && parsed.text !== void 0) {
+        return { text: parsed.text, senderNametag: parsed.senderNametag || null };
       }
+    } catch {
     }
+    return { text: content, senderNametag: null };
   }
   // ===========================================================================
-  // Private: Storage
+  // Private — Event Tag Helpers
   // ===========================================================================
-  async save() {
-    const messages = Array.from(this.messages.values());
-    await this.deps.storage.set("direct_messages", JSON.stringify(messages));
+  getGroupIdFromEvent(event) {
+    const hTag = event.tags.find((t) => t[0] === "h");
+    return hTag ? hTag[1] : null;
   }
-  pruneIfNeeded() {
-    if (this.messages.size <= this.config.maxMessages) return;
-    const sorted = Array.from(this.messages.entries()).sort(([, a], [, b]) => a.timestamp - b.timestamp);
-    const toRemove = sorted.slice(0, sorted.length - this.config.maxMessages);
-    for (const [id] of toRemove) {
-      this.messages.delete(id);
+  getGroupIdFromMetadataEvent(event) {
+    const dTag = event.tags.find((t) => t[0] === "d");
+    if (dTag?.[1]) return dTag[1];
+    const hTag = event.tags.find((t) => t[0] === "h");
+    return hTag?.[1] ?? null;
+  }
+  extractReplyTo(event) {
+    const eTag = event.tags.find((t) => t[0] === "e" && t[3] === "reply");
+    return eTag ? eTag[1] : void 0;
+  }
+  extractPreviousIds(event) {
+    const previousTag = event.tags.find((t) => t[0] === "previous");
+    return previousTag ? previousTag.slice(1) : void 0;
+  }
+  parseGroupMetadata(event) {
+    try {
+      const groupId = this.getGroupIdFromMetadataEvent(event);
+      if (!groupId) return null;
+      let name = "Unnamed Group";
+      let description;
+      let picture;
+      let isPrivate = false;
+      if (event.content && event.content.trim()) {
+        try {
+          const metadata = JSON.parse(event.content);
+          name = metadata.name || name;
+          description = metadata.about || metadata.description;
+          picture = metadata.picture;
+          isPrivate = metadata.private === true;
+        } catch {
+        }
+      }
+      for (const tag of event.tags) {
+        if (tag[0] === "name" && tag[1]) name = tag[1];
+        if (tag[0] === "about" && tag[1]) description = tag[1];
+        if (tag[0] === "picture" && tag[1]) picture = tag[1];
+        if (tag[0] === "private") isPrivate = true;
+        if (tag[0] === "public" && tag[1] === "false") isPrivate = true;
+      }
+      return {
+        id: groupId,
+        relayUrl: this.config.relays[0] || "",
+        name,
+        description,
+        picture,
+        visibility: isPrivate ? GroupVisibility.PRIVATE : GroupVisibility.PUBLIC,
+        createdAt: event.created_at * 1e3
+      };
+    } catch {
+      return null;
     }
   }
   // ===========================================================================
-  // Private: Helpers
+  // Private — Utility
   // ===========================================================================
-  async resolveRecipient(recipient) {
-    if (recipient.startsWith("@")) {
-      const pubkey = await this.deps.transport.resolveNametag?.(recipient.slice(1));
-      if (!pubkey) {
-        throw new Error(`Nametag not found: ${recipient}`);
-      }
-      return pubkey;
-    }
-    return recipient;
+  /** Subscribe and track the subscription ID for cleanup. */
+  trackSubscription(filter, handlers) {
+    const subId = this.client.subscribe(filter, {
+      onEvent: handlers.onEvent,
+      onEndOfStoredEvents: handlers.onEndOfStoredEvents ?? (() => {
+      })
+    });
+    this.subscriptionIds.push(subId);
+    return subId;
+  }
+  /** Subscribe for a one-shot fetch, auto-unsubscribe on EOSE or timeout. */
+  oneshotSubscription(filter, opts) {
+    return new Promise((resolve) => {
+      let done = false;
+      let subId;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        if (subId) {
+          try {
+            this.client.unsubscribe(subId);
+          } catch {
+          }
+          const idx = this.subscriptionIds.indexOf(subId);
+          if (idx >= 0) this.subscriptionIds.splice(idx, 1);
+        }
+        resolve(opts.onComplete());
+      };
+      subId = this.client.subscribe(filter, {
+        onEvent: (event) => {
+          if (!done) opts.onEvent(event);
+        },
+        onEndOfStoredEvents: finish
+      });
+      this.subscriptionIds.push(subId);
+      setTimeout(finish, opts.timeoutMs ?? 5e3);
+    });
   }
   ensureInitialized() {
     if (!this.deps) {
-      throw new Error("CommunicationsModule not initialized");
+      throw new Error("GroupChatModule not initialized");
+    }
+  }
+  async ensureConnected() {
+    if (!this.connected) {
+      await this.connect();
+    }
+  }
+  randomId() {
+    const bytes = new Uint8Array(8);
+    if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.getRandomValues) {
+      globalThis.crypto.getRandomValues(bytes);
+    } else {
+      for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = Math.floor(Math.random() * 256);
+      }
     }
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
   }
 };
-function createCommunicationsModule(config) {
-  return new CommunicationsModule(config);
+function createGroupChatModule(config) {
+  return new GroupChatModule(config);
 }
 
 // core/encryption.ts
@@ -8389,12 +9690,13 @@ var Sphere = class _Sphere {
   // Modules
   _payments;
   _communications;
+  _groupChat = null;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
   // ===========================================================================
   // Constructor (private)
   // ===========================================================================
-  constructor(storage, transport, oracle, tokenStorage, l1Config, priceProvider) {
+  constructor(storage, transport, oracle, tokenStorage, l1Config, priceProvider, groupChatConfig) {
     this._storage = storage;
     this._transport = transport;
     this._oracle = oracle;
@@ -8404,6 +9706,7 @@ var Sphere = class _Sphere {
     }
     this._payments = createPaymentsModule({ l1: l1Config });
     this._communications = createCommunicationsModule();
+    this._groupChat = groupChatConfig ? createGroupChatModule(groupChatConfig) : null;
   }
   // ===========================================================================
   // Static Methods - Wallet Management
@@ -8451,6 +9754,7 @@ var Sphere = class _Sphere {
    * ```
    */
   static async init(options) {
+    const groupChat = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const walletExists = await _Sphere.exists(options.storage);
     if (walletExists) {
       const sphere2 = await _Sphere.load({
@@ -8459,7 +9763,8 @@ var Sphere = class _Sphere {
         oracle: options.oracle,
         tokenStorage: options.tokenStorage,
         l1: options.l1,
-        price: options.price
+        price: options.price,
+        groupChat
       });
       return { sphere: sphere2, created: false };
     }
@@ -8484,10 +9789,34 @@ var Sphere = class _Sphere {
       derivationPath: options.derivationPath,
       nametag: options.nametag,
       l1: options.l1,
-      price: options.price
+      price: options.price,
+      groupChat
     });
     return { sphere, created: true, generatedMnemonic };
   }
+  /**
+   * Resolve groupChat config from init/create/load options.
+   * - `true` → use network-default relays
+   * - `GroupChatModuleConfig` → pass through
+   * - `undefined` → no groupchat
+   */
+  /**
+   * Resolve GroupChat config from Sphere.init() options.
+   * Note: impl/shared/resolvers.ts has a similar resolver for provider-level config
+   * (different input shape: { enabled?, relays? }). Both fill relay URLs from network defaults.
+   */
+  static resolveGroupChatConfig(config, network) {
+    if (!config) return void 0;
+    if (config === true) {
+      const netConfig = network ? NETWORKS[network] : NETWORKS.mainnet;
+      return { relays: [...netConfig.groupRelays] };
+    }
+    if (!config.relays || config.relays.length === 0) {
+      const netConfig = network ? NETWORKS[network] : NETWORKS.mainnet;
+      return { ...config, relays: [...netConfig.groupRelays] };
+    }
+    return config;
+  }
   /**
    * Create new wallet with mnemonic
    */
@@ -8498,13 +9827,15 @@ var Sphere = class _Sphere {
     if (await _Sphere.exists(options.storage)) {
       throw new Error("Wallet already exists. Use Sphere.load() or Sphere.clear() first.");
     }
+    const groupChatConfig = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const sphere = new _Sphere(
       options.storage,
       options.transport,
       options.oracle,
       options.tokenStorage,
       options.l1,
-      options.price
+      options.price,
+      groupChatConfig
     );
     await sphere.storeMnemonic(options.mnemonic, options.derivationPath);
     await sphere.initializeIdentityFromMnemonic(options.mnemonic, options.derivationPath);
@@ -8529,13 +9860,15 @@ var Sphere = class _Sphere {
     if (!await _Sphere.exists(options.storage)) {
       throw new Error("No wallet found. Use Sphere.create() to create a new wallet.");
     }
+    const groupChatConfig = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const sphere = new _Sphere(
       options.storage,
       options.transport,
       options.oracle,
       options.tokenStorage,
       options.l1,
-      options.price
+      options.price,
+      groupChatConfig
     );
     await sphere.loadIdentityFromStorage();
     await sphere.initializeProviders();
@@ -8574,13 +9907,15 @@ var Sphere = class _Sphere {
       await options.storage.connect();
       console.log("[Sphere.import] Storage reconnected");
     }
+    const groupChatConfig = _Sphere.resolveGroupChatConfig(options.groupChat);
     const sphere = new _Sphere(
       options.storage,
       options.transport,
       options.oracle,
       options.tokenStorage,
       options.l1,
-      options.price
+      options.price,
+      groupChatConfig
     );
     if (options.mnemonic) {
       if (!_Sphere.validateMnemonic(options.mnemonic)) {
@@ -8740,6 +10075,10 @@ var Sphere = class _Sphere {
     this.ensureReady();
     return this._communications;
   }
+  /** Group chat module (NIP-29). Null if not configured. */
+  get groupChat() {
+    return this._groupChat;
+  }
   // ===========================================================================
   // Public Properties - State
   // ===========================================================================
@@ -9610,8 +10949,14 @@ var Sphere = class _Sphere {
       transport: this._transport,
       emitEvent
     });
+    this._groupChat?.initialize({
+      identity: this._identity,
+      storage: this._storage,
+      emitEvent
+    });
     await this._payments.load();
     await this._communications.load();
+    await this._groupChat?.load();
   }
   /**
    * Derive address at a specific index
@@ -10214,6 +11559,7 @@ var Sphere = class _Sphere {
   async destroy() {
     this._payments.destroy();
     this._communications.destroy();
+    this._groupChat?.destroy();
     await this._transport.disconnect();
     await this._storage.disconnect();
     await this._oracle.disconnect();
@@ -10434,8 +11780,14 @@ var Sphere = class _Sphere {
       transport: this._transport,
       emitEvent
     });
+    this._groupChat?.initialize({
+      identity: this._identity,
+      storage: this._storage,
+      emitEvent
+    });
     await this._payments.load();
     await this._communications.load();
+    await this._groupChat?.load();
   }
   // ===========================================================================
   // Private: Helpers