@unicitylabs/sphere-sdk 0.3.4 → 0.3.6

package/dist/impl/nodejs/index.d.cts

@@ -1112,6 +1112,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -1120,6 +1121,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly dev: {
         readonly name: "Development";
@@ -1128,6 +1130,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -1312,6 +1315,15 @@ interface BasePriceConfig {
     /** Enable debug logging */
     debug?: boolean;
 }
+/**
+ * Base market module configuration
+ */
+interface BaseMarketConfig {
+    /** Market API base URL (default: https://market-api.unicity.network) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
 /**
  * Base providers result
  * Common structure for all platforms
@@ -1327,6 +1339,13 @@ interface BaseProviders {
     price?: PriceProvider;
 }
 
+interface MarketModuleConfig {
+    /** Market API base URL (default: https://market-api.unicity.network) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+
 /** IPFS storage provider configuration */
 interface IpfsStorageConfig {
     /** Gateway URLs for HTTP API (defaults to Unicity dedicated nodes) */
@@ -1419,6 +1438,8 @@ interface NodeProvidersConfig {
         enabled?: boolean;
         relays?: string[];
     } | boolean;
+    /** Market module configuration. true = enable with defaults, object = custom config */
+    market?: BaseMarketConfig | boolean;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1433,6 +1454,8 @@ interface NodeProviders {
     ipfsTokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
     /** Group chat config (resolved, for passing to Sphere.init) */
     groupChat?: GroupChatModuleConfig | boolean;
+    /** Market module config (resolved, for passing to Sphere.init) */
+    market?: MarketModuleConfig | boolean;
 }
 /**
  * Create all Node.js providers with default configuration

package/dist/impl/nodejs/index.d.ts

@@ -1112,6 +1112,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -1120,6 +1121,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly dev: {
         readonly name: "Development";
@@ -1128,6 +1130,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -1312,6 +1315,15 @@ interface BasePriceConfig {
     /** Enable debug logging */
     debug?: boolean;
 }
+/**
+ * Base market module configuration
+ */
+interface BaseMarketConfig {
+    /** Market API base URL (default: https://market-api.unicity.network) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
 /**
  * Base providers result
  * Common structure for all platforms
@@ -1327,6 +1339,13 @@ interface BaseProviders {
     price?: PriceProvider;
 }
 
+interface MarketModuleConfig {
+    /** Market API base URL (default: https://market-api.unicity.network) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+
 /** IPFS storage provider configuration */
 interface IpfsStorageConfig {
     /** Gateway URLs for HTTP API (defaults to Unicity dedicated nodes) */
@@ -1419,6 +1438,8 @@ interface NodeProvidersConfig {
         enabled?: boolean;
         relays?: string[];
     } | boolean;
+    /** Market module configuration. true = enable with defaults, object = custom config */
+    market?: BaseMarketConfig | boolean;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1433,6 +1454,8 @@ interface NodeProviders {
     ipfsTokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
     /** Group chat config (resolved, for passing to Sphere.init) */
     groupChat?: GroupChatModuleConfig | boolean;
+    /** Market module config (resolved, for passing to Sphere.init) */
+    market?: MarketModuleConfig | boolean;
 }
 /**
  * Create all Node.js providers with default configuration

package/dist/impl/nodejs/index.js

@@ -37,7 +37,11 @@ var STORAGE_KEYS_GLOBAL = {
   /** 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"
+  GROUP_CHAT_RELAY_URL: "group_chat_relay_url",
+  /** Cached token registry JSON (fetched from remote) */
+  TOKEN_REGISTRY_CACHE: "token_registry_cache",
+  /** Timestamp of last token registry cache update (ms since epoch) */
+  TOKEN_REGISTRY_CACHE_TS: "token_registry_cache_ts"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -113,6 +117,8 @@ var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH = `${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 TOKEN_REGISTRY_URL = "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
+var TOKEN_REGISTRY_REFRESH_INTERVAL = 36e5;
 var TEST_NOSTR_RELAYS = [
   "wss://nostr-relay.testnet.unicity.network"
 ];
@@ -126,7 +132,8 @@ var NETWORKS = {
     nostrRelays: DEFAULT_NOSTR_RELAYS,
     ipfsGateways: DEFAULT_IPFS_GATEWAYS,
     electrumUrl: DEFAULT_ELECTRUM_URL,
-    groupRelays: DEFAULT_GROUP_RELAYS
+    groupRelays: DEFAULT_GROUP_RELAYS,
+    tokenRegistryUrl: TOKEN_REGISTRY_URL
   },
   testnet: {
     name: "Testnet",
@@ -134,7 +141,8 @@ var NETWORKS = {
     nostrRelays: TEST_NOSTR_RELAYS,
     ipfsGateways: DEFAULT_IPFS_GATEWAYS,
     electrumUrl: TEST_ELECTRUM_URL,
-    groupRelays: DEFAULT_GROUP_RELAYS
+    groupRelays: DEFAULT_GROUP_RELAYS,
+    tokenRegistryUrl: TOKEN_REGISTRY_URL
   },
   dev: {
     name: "Development",
@@ -142,7 +150,8 @@ var NETWORKS = {
     nostrRelays: TEST_NOSTR_RELAYS,
     ipfsGateways: DEFAULT_IPFS_GATEWAYS,
     electrumUrl: TEST_ELECTRUM_URL,
-    groupRelays: DEFAULT_GROUP_RELAYS
+    groupRelays: DEFAULT_GROUP_RELAYS,
+    tokenRegistryUrl: TOKEN_REGISTRY_URL
   }
 };
 var TIMEOUTS = {
@@ -157,6 +166,7 @@ var TIMEOUTS = {
   /** Sync interval */
   SYNC_INTERVAL: 6e4
 };
+var DEFAULT_MARKET_API_URL = "https://market-api.unicity.network";
 
 // impl/nodejs/storage/FileStorageProvider.ts
 var FileStorageProvider = class {
@@ -4831,6 +4841,363 @@ function createPriceProvider(config) {
   }
 }
 
+// registry/TokenRegistry.ts
+var FETCH_TIMEOUT_MS = 1e4;
+var TokenRegistry = class _TokenRegistry {
+  static instance = null;
+  definitionsById;
+  definitionsBySymbol;
+  definitionsByName;
+  // Remote refresh state
+  remoteUrl = null;
+  storage = null;
+  refreshIntervalMs = TOKEN_REGISTRY_REFRESH_INTERVAL;
+  refreshTimer = null;
+  lastRefreshAt = 0;
+  refreshPromise = null;
+  constructor() {
+    this.definitionsById = /* @__PURE__ */ new Map();
+    this.definitionsBySymbol = /* @__PURE__ */ new Map();
+    this.definitionsByName = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get singleton instance of TokenRegistry
+   */
+  static getInstance() {
+    if (!_TokenRegistry.instance) {
+      _TokenRegistry.instance = new _TokenRegistry();
+    }
+    return _TokenRegistry.instance;
+  }
+  /**
+   * Configure remote registry refresh with persistent caching.
+   *
+   * On first call:
+   * 1. Loads cached data from StorageProvider (if available and fresh)
+   * 2. Starts periodic remote fetch (if autoRefresh is true, which is default)
+   *
+   * @param options - Configuration options
+   * @param options.remoteUrl - Remote URL to fetch definitions from
+   * @param options.storage - StorageProvider for persistent caching
+   * @param options.refreshIntervalMs - Refresh interval in ms (default: 1 hour)
+   * @param options.autoRefresh - Start auto-refresh immediately (default: true)
+   */
+  static configure(options) {
+    const instance = _TokenRegistry.getInstance();
+    if (options.remoteUrl !== void 0) {
+      instance.remoteUrl = options.remoteUrl;
+    }
+    if (options.storage !== void 0) {
+      instance.storage = options.storage;
+    }
+    if (options.refreshIntervalMs !== void 0) {
+      instance.refreshIntervalMs = options.refreshIntervalMs;
+    }
+    if (instance.storage) {
+      instance.loadFromCache();
+    }
+    const autoRefresh = options.autoRefresh ?? true;
+    if (autoRefresh && instance.remoteUrl) {
+      instance.startAutoRefresh();
+    }
+  }
+  /**
+   * Reset the singleton instance (useful for testing).
+   * Stops auto-refresh if running.
+   */
+  static resetInstance() {
+    if (_TokenRegistry.instance) {
+      _TokenRegistry.instance.stopAutoRefresh();
+    }
+    _TokenRegistry.instance = null;
+  }
+  /**
+   * Destroy the singleton: stop auto-refresh and reset.
+   */
+  static destroy() {
+    _TokenRegistry.resetInstance();
+  }
+  // ===========================================================================
+  // Cache (StorageProvider)
+  // ===========================================================================
+  /**
+   * Load definitions from StorageProvider cache.
+   * Only applies if cache exists and is fresh (within refreshIntervalMs).
+   */
+  async loadFromCache() {
+    if (!this.storage) return false;
+    try {
+      const [cached, cachedTs] = await Promise.all([
+        this.storage.get(STORAGE_KEYS_GLOBAL.TOKEN_REGISTRY_CACHE),
+        this.storage.get(STORAGE_KEYS_GLOBAL.TOKEN_REGISTRY_CACHE_TS)
+      ]);
+      if (!cached || !cachedTs) return false;
+      const ts = parseInt(cachedTs, 10);
+      if (isNaN(ts)) return false;
+      const age = Date.now() - ts;
+      if (age > this.refreshIntervalMs) return false;
+      if (this.lastRefreshAt > ts) return false;
+      const data = JSON.parse(cached);
+      if (!this.isValidDefinitionsArray(data)) return false;
+      this.applyDefinitions(data);
+      this.lastRefreshAt = ts;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Save definitions to StorageProvider cache.
+   */
+  async saveToCache(definitions) {
+    if (!this.storage) return;
+    try {
+      await Promise.all([
+        this.storage.set(STORAGE_KEYS_GLOBAL.TOKEN_REGISTRY_CACHE, JSON.stringify(definitions)),
+        this.storage.set(STORAGE_KEYS_GLOBAL.TOKEN_REGISTRY_CACHE_TS, String(Date.now()))
+      ]);
+    } catch {
+    }
+  }
+  // ===========================================================================
+  // Remote Refresh
+  // ===========================================================================
+  /**
+   * Apply an array of token definitions to the internal maps.
+   * Clears existing data before applying.
+   */
+  applyDefinitions(definitions) {
+    this.definitionsById.clear();
+    this.definitionsBySymbol.clear();
+    this.definitionsByName.clear();
+    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);
+    }
+  }
+  /**
+   * Validate that data is an array of objects with 'id' field
+   */
+  isValidDefinitionsArray(data) {
+    return Array.isArray(data) && data.every((item) => item && typeof item === "object" && "id" in item);
+  }
+  /**
+   * Fetch token definitions from the remote URL and update the registry.
+   * On success, also persists to StorageProvider cache.
+   * Returns true on success, false on failure. On failure, existing data is preserved.
+   * Concurrent calls are deduplicated — only one fetch runs at a time.
+   */
+  async refreshFromRemote() {
+    if (!this.remoteUrl) {
+      return false;
+    }
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+    this.refreshPromise = this.doRefresh();
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+  async doRefresh() {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+      let response;
+      try {
+        response = await fetch(this.remoteUrl, {
+          headers: { Accept: "application/json" },
+          signal: controller.signal
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+      if (!response.ok) {
+        console.warn(
+          `[TokenRegistry] Remote fetch failed: HTTP ${response.status} ${response.statusText}`
+        );
+        return false;
+      }
+      const data = await response.json();
+      if (!this.isValidDefinitionsArray(data)) {
+        console.warn("[TokenRegistry] Remote data is not a valid token definitions array");
+        return false;
+      }
+      const definitions = data;
+      this.applyDefinitions(definitions);
+      this.lastRefreshAt = Date.now();
+      this.saveToCache(definitions);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[TokenRegistry] Remote refresh failed: ${message}`);
+      return false;
+    }
+  }
+  /**
+   * Start periodic auto-refresh from the remote URL.
+   * Does an immediate fetch, then repeats at the configured interval.
+   */
+  startAutoRefresh(intervalMs) {
+    this.stopAutoRefresh();
+    if (intervalMs !== void 0) {
+      this.refreshIntervalMs = intervalMs;
+    }
+    this.refreshFromRemote();
+    this.refreshTimer = setInterval(() => {
+      this.refreshFromRemote();
+    }, this.refreshIntervalMs);
+  }
+  /**
+   * Stop periodic auto-refresh
+   */
+  stopAutoRefresh() {
+    if (this.refreshTimer !== null) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  /**
+   * Timestamp of the last successful remote refresh (0 if never refreshed)
+   */
+  getLastRefreshAt() {
+    return this.lastRefreshAt;
+  }
+  // ===========================================================================
+  // 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;
+  }
+};
+
 // impl/shared/resolvers.ts
 function getNetworkConfig(network = "mainnet") {
   return NETWORKS[network];
@@ -4906,6 +5273,16 @@ function resolveGroupChatConfig(network, config) {
     relays: config.relays ?? [...netConfig.groupRelays]
   };
 }
+function resolveMarketConfig(config) {
+  if (!config) return void 0;
+  if (config === true) {
+    return { apiUrl: DEFAULT_MARKET_API_URL };
+  }
+  return {
+    apiUrl: config.apiUrl ?? DEFAULT_MARKET_API_URL,
+    timeout: config.timeout
+  };
+}
 
 // impl/nodejs/index.ts
 function createNodeProviders(config) {
@@ -4921,9 +5298,13 @@ function createNodeProviders(config) {
   const ipfsSync = config?.tokenSync?.ipfs;
   const ipfsTokenStorage = ipfsSync?.enabled ? createNodeIpfsStorageProvider(ipfsSync.config, storage) : void 0;
   const groupChat = resolveGroupChatConfig(network, config?.groupChat);
+  const networkConfig = getNetworkConfig(network);
+  TokenRegistry.configure({ remoteUrl: networkConfig.tokenRegistryUrl, storage });
+  const market = resolveMarketConfig(config?.market);
   return {
     storage,
     groupChat,
+    market,
     tokenStorage: createFileTokenStorageProvider({
       tokensDir: config?.tokensDir ?? "./sphere-tokens"
     }),