@unicitylabs/sphere-sdk 0.3.6 → 0.3.8

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

@@ -1190,6 +1190,7 @@ declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvide
  * Platform-independent abstraction for fetching token market prices.
  * Does not extend BaseProvider — stateless HTTP client with internal caching.
  */
+
 /**
  * Supported price provider platforms
  */
@@ -1234,7 +1235,7 @@ interface PriceProvider {
     /**
      * Get price for a single token
      * @param tokenName - Token name (e.g., 'bitcoin')
-     * @returns Token price or null if not available
+     * @returns Token price (zero-price entry for tokens not listed on the platform), or null on network error with no cache
      */
     getPrice(tokenName: string): Promise<TokenPrice | null>;
     /**
@@ -1315,15 +1316,6 @@ 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
@@ -1339,13 +1331,6 @@ 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) */
@@ -1438,8 +1423,6 @@ interface NodeProvidersConfig {
         enabled?: boolean;
         relays?: string[];
     } | boolean;
-    /** Market module configuration. true = enable with defaults, object = custom config */
-    market?: BaseMarketConfig | boolean;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1454,8 +1437,6 @@ 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

@@ -1190,6 +1190,7 @@ declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvide
  * Platform-independent abstraction for fetching token market prices.
  * Does not extend BaseProvider — stateless HTTP client with internal caching.
  */
+
 /**
  * Supported price provider platforms
  */
@@ -1234,7 +1235,7 @@ interface PriceProvider {
     /**
      * Get price for a single token
      * @param tokenName - Token name (e.g., 'bitcoin')
-     * @returns Token price or null if not available
+     * @returns Token price (zero-price entry for tokens not listed on the platform), or null on network error with no cache
      */
     getPrice(tokenName: string): Promise<TokenPrice | null>;
     /**
@@ -1315,15 +1316,6 @@ 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
@@ -1339,13 +1331,6 @@ 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) */
@@ -1438,8 +1423,6 @@ interface NodeProvidersConfig {
         enabled?: boolean;
         relays?: string[];
     } | boolean;
-    /** Market module configuration. true = enable with defaults, object = custom config */
-    market?: BaseMarketConfig | boolean;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1454,8 +1437,6 @@ 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

@@ -41,7 +41,11 @@ var STORAGE_KEYS_GLOBAL = {
   /** 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"
+  TOKEN_REGISTRY_CACHE_TS: "token_registry_cache_ts",
+  /** Cached price data JSON (from CoinGecko or other provider) */
+  PRICE_CACHE: "price_cache",
+  /** Timestamp of last price cache update (ms since epoch) */
+  PRICE_CACHE_TS: "price_cache_ts"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -166,7 +170,6 @@ 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 {
@@ -3002,6 +3005,7 @@ async function loadIpnsModule() {
 async function createSignedRecord(keyPair, cid, sequenceNumber, lifetimeMs = DEFAULT_LIFETIME_MS) {
   const { createIPNSRecord, marshalIPNSRecord } = await loadIpnsModule();
   const record = await createIPNSRecord(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     keyPair,
     `/ipfs/${cid}`,
     sequenceNumber,
@@ -4743,26 +4747,37 @@ var CoinGeckoPriceProvider = class {
   timeout;
   debug;
   baseUrl;
+  storage;
+  /** In-flight fetch promise for deduplication of concurrent getPrices() calls */
+  fetchPromise = null;
+  /** Token names being fetched in the current in-flight request */
+  fetchNames = null;
+  /** Whether persistent cache has been loaded into memory */
+  persistentCacheLoaded = false;
+  /** Promise for loading persistent cache (deduplication) */
+  loadCachePromise = null;
   constructor(config) {
     this.apiKey = config?.apiKey;
     this.cacheTtlMs = config?.cacheTtlMs ?? 6e4;
     this.timeout = config?.timeout ?? 1e4;
     this.debug = config?.debug ?? false;
+    this.storage = config?.storage ?? null;
     this.baseUrl = config?.baseUrl ?? (this.apiKey ? "https://pro-api.coingecko.com/api/v3" : "https://api.coingecko.com/api/v3");
   }
   async getPrices(tokenNames) {
     if (tokenNames.length === 0) {
       return /* @__PURE__ */ new Map();
     }
+    if (!this.persistentCacheLoaded && this.storage) {
+      await this.loadFromStorage();
+    }
     const now = Date.now();
     const result = /* @__PURE__ */ new Map();
     const uncachedNames = [];
     for (const name of tokenNames) {
       const cached = this.cache.get(name);
       if (cached && cached.expiresAt > now) {
-        if (cached.price !== null) {
-          result.set(name, cached.price);
-        }
+        result.set(name, cached.price);
       } else {
         uncachedNames.push(name);
       }
@@ -4770,6 +4785,41 @@ var CoinGeckoPriceProvider = class {
     if (uncachedNames.length === 0) {
       return result;
     }
+    if (this.fetchPromise && this.fetchNames) {
+      const allCovered = uncachedNames.every((n) => this.fetchNames.has(n));
+      if (allCovered) {
+        if (this.debug) {
+          console.log(`[CoinGecko] Deduplicating request, reusing in-flight fetch`);
+        }
+        const fetched = await this.fetchPromise;
+        for (const name of uncachedNames) {
+          const price = fetched.get(name);
+          if (price) {
+            result.set(name, price);
+          }
+        }
+        return result;
+      }
+    }
+    const fetchPromise = this.doFetch(uncachedNames);
+    this.fetchPromise = fetchPromise;
+    this.fetchNames = new Set(uncachedNames);
+    try {
+      const fetched = await fetchPromise;
+      for (const [name, price] of fetched) {
+        result.set(name, price);
+      }
+    } finally {
+      if (this.fetchPromise === fetchPromise) {
+        this.fetchPromise = null;
+        this.fetchNames = null;
+      }
+    }
+    return result;
+  }
+  async doFetch(uncachedNames) {
+    const result = /* @__PURE__ */ new Map();
+    const now = Date.now();
     try {
       const ids = uncachedNames.join(",");
       const url = `${this.baseUrl}/simple/price?ids=${encodeURIComponent(ids)}&vs_currencies=usd,eur&include_24hr_change=true`;
@@ -4785,6 +4835,9 @@ var CoinGeckoPriceProvider = class {
         signal: AbortSignal.timeout(this.timeout)
       });
       if (!response.ok) {
+        if (response.status === 429) {
+          this.extendCacheOnRateLimit(uncachedNames);
+        }
         throw new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
       }
       const data = await response.json();
@@ -4803,25 +4856,113 @@ var CoinGeckoPriceProvider = class {
       }
       for (const name of uncachedNames) {
         if (!result.has(name)) {
-          this.cache.set(name, { price: null, expiresAt: now + this.cacheTtlMs });
+          const zeroPrice = {
+            tokenName: name,
+            priceUsd: 0,
+            priceEur: 0,
+            change24h: 0,
+            timestamp: now
+          };
+          this.cache.set(name, { price: zeroPrice, expiresAt: now + this.cacheTtlMs });
+          result.set(name, zeroPrice);
         }
       }
       if (this.debug) {
         console.log(`[CoinGecko] Fetched ${result.size} prices`);
       }
+      this.saveToStorage();
     } catch (error) {
       if (this.debug) {
         console.warn("[CoinGecko] Fetch failed, using stale cache:", error);
       }
       for (const name of uncachedNames) {
         const stale = this.cache.get(name);
-        if (stale?.price) {
+        if (stale) {
           result.set(name, stale.price);
         }
       }
     }
     return result;
   }
+  // ===========================================================================
+  // Persistent Storage
+  // ===========================================================================
+  /**
+   * Load cached prices from StorageProvider into in-memory cache.
+   * Only loads entries that are still within cacheTtlMs.
+   */
+  async loadFromStorage() {
+    if (this.loadCachePromise) {
+      return this.loadCachePromise;
+    }
+    this.loadCachePromise = this.doLoadFromStorage();
+    try {
+      await this.loadCachePromise;
+    } finally {
+      this.loadCachePromise = null;
+    }
+  }
+  async doLoadFromStorage() {
+    this.persistentCacheLoaded = true;
+    if (!this.storage) return;
+    try {
+      const [cached, cachedTs] = await Promise.all([
+        this.storage.get(STORAGE_KEYS_GLOBAL.PRICE_CACHE),
+        this.storage.get(STORAGE_KEYS_GLOBAL.PRICE_CACHE_TS)
+      ]);
+      if (!cached || !cachedTs) return;
+      const ts = parseInt(cachedTs, 10);
+      if (isNaN(ts)) return;
+      const age = Date.now() - ts;
+      if (age > this.cacheTtlMs) return;
+      const data = JSON.parse(cached);
+      const expiresAt = ts + this.cacheTtlMs;
+      for (const [name, price] of Object.entries(data)) {
+        if (!this.cache.has(name)) {
+          this.cache.set(name, { price, expiresAt });
+        }
+      }
+      if (this.debug) {
+        console.log(`[CoinGecko] Loaded ${Object.keys(data).length} prices from persistent cache`);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Save current prices to StorageProvider (fire-and-forget).
+   */
+  saveToStorage() {
+    if (!this.storage) return;
+    const data = {};
+    for (const [name, entry] of this.cache) {
+      data[name] = entry.price;
+    }
+    Promise.all([
+      this.storage.set(STORAGE_KEYS_GLOBAL.PRICE_CACHE, JSON.stringify(data)),
+      this.storage.set(STORAGE_KEYS_GLOBAL.PRICE_CACHE_TS, String(Date.now()))
+    ]).catch(() => {
+    });
+  }
+  // ===========================================================================
+  // Rate-limit handling
+  // ===========================================================================
+  /**
+   * On 429 rate-limit, extend stale cache entries so subsequent calls
+   * don't immediately retry and hammer the API.
+   */
+  extendCacheOnRateLimit(names) {
+    const backoffMs = 6e4;
+    const extendedExpiry = Date.now() + backoffMs;
+    for (const name of names) {
+      const existing = this.cache.get(name);
+      if (existing) {
+        existing.expiresAt = Math.max(existing.expiresAt, extendedExpiry);
+      }
+    }
+    if (this.debug) {
+      console.warn(`[CoinGecko] Rate-limited (429), extended cache TTL by ${backoffMs / 1e3}s`);
+    }
+  }
   async getPrice(tokenName) {
     const prices = await this.getPrices([tokenName]);
     return prices.get(tokenName) ?? null;
@@ -4855,6 +4996,7 @@ var TokenRegistry = class _TokenRegistry {
   refreshTimer = null;
   lastRefreshAt = 0;
   refreshPromise = null;
+  initialLoadPromise = null;
   constructor() {
     this.definitionsById = /* @__PURE__ */ new Map();
     this.definitionsBySymbol = /* @__PURE__ */ new Map();
@@ -4893,13 +5035,8 @@ var TokenRegistry = class _TokenRegistry {
     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();
-    }
+    instance.initialLoadPromise = instance.performInitialLoad(autoRefresh);
   }
   /**
    * Reset the singleton instance (useful for testing).
@@ -4917,6 +5054,53 @@ var TokenRegistry = class _TokenRegistry {
   static destroy() {
     _TokenRegistry.resetInstance();
   }
+  /**
+   * Wait for the initial data load (cache or remote) to complete.
+   * Returns true if data was loaded, false if not (timeout or no data source).
+   *
+   * @param timeoutMs - Maximum wait time in ms (default: 10s). Set to 0 for no timeout.
+   */
+  static async waitForReady(timeoutMs = 1e4) {
+    const instance = _TokenRegistry.getInstance();
+    if (!instance.initialLoadPromise) {
+      return instance.definitionsById.size > 0;
+    }
+    if (timeoutMs <= 0) {
+      return instance.initialLoadPromise;
+    }
+    return Promise.race([
+      instance.initialLoadPromise,
+      new Promise((resolve) => setTimeout(() => resolve(false), timeoutMs))
+    ]);
+  }
+  // ===========================================================================
+  // Initial Load
+  // ===========================================================================
+  /**
+   * Perform initial data load: try cache first, fall back to remote fetch.
+   * After initial data is available, start periodic auto-refresh if configured.
+   */
+  async performInitialLoad(autoRefresh) {
+    let loaded = false;
+    if (this.storage) {
+      loaded = await this.loadFromCache();
+    }
+    if (loaded) {
+      if (autoRefresh && this.remoteUrl) {
+        this.startAutoRefresh();
+      }
+      return true;
+    }
+    if (autoRefresh && this.remoteUrl) {
+      loaded = await this.refreshFromRemote();
+      this.stopAutoRefresh();
+      this.refreshTimer = setInterval(() => {
+        this.refreshFromRemote();
+      }, this.refreshIntervalMs);
+      return loaded;
+    }
+    return false;
+  }
   // ===========================================================================
   // Cache (StorageProvider)
   // ===========================================================================
@@ -5246,7 +5430,7 @@ function resolveL1Config(network, config) {
     enableVesting: config.enableVesting
   };
 }
-function resolvePriceConfig(config) {
+function resolvePriceConfig(config, storage) {
   if (config === void 0) {
     return void 0;
   }
@@ -5256,7 +5440,8 @@ function resolvePriceConfig(config) {
     baseUrl: config.baseUrl,
     cacheTtlMs: config.cacheTtlMs,
     timeout: config.timeout,
-    debug: config.debug
+    debug: config.debug,
+    storage
   };
 }
 function resolveGroupChatConfig(network, config) {
@@ -5273,16 +5458,6 @@ 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) {
@@ -5290,21 +5465,19 @@ function createNodeProviders(config) {
   const transportConfig = resolveTransportConfig(network, config?.transport);
   const oracleConfig = resolveOracleConfig(network, config?.oracle);
   const l1Config = resolveL1Config(network, config?.l1);
-  const priceConfig = resolvePriceConfig(config?.price);
   const storage = createFileStorageProvider({
     dataDir: config?.dataDir ?? "./sphere-data",
     ...config?.walletFileName ? { fileName: config.walletFileName } : {}
   });
+  const priceConfig = resolvePriceConfig(config?.price, storage);
   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"
     }),