@waiaas/daemon 2.0.0-rc.1

package/dist/infrastructure/oracle/forex-currencies.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Fiat currency metadata for 43 supported display currencies.
+ *
+ * Used by:
+ * - Admin UI: currency dropdown (name, symbol)
+ * - Intl.NumberFormat: locale-aware formatting (decimals, locale)
+ * - ForexRateService: validation of currency codes
+ *
+ * Decimals follow ISO 4217:
+ * - 0: KRW, JPY, VND, CLP, HUF, PKR
+ * - 2: Most currencies (USD, EUR, GBP, ...)
+ * - 3: KWD, BHD (1/1000 subunit)
+ */
+/** Metadata for a fiat currency. */
+export interface CurrencyMeta {
+    /** ISO 4217 currency code (e.g. 'KRW'). */
+    code: string;
+    /** English display name (e.g. 'Korean Won'). */
+    name: string;
+    /** Currency symbol (e.g. '\u20A9'). */
+    symbol: string;
+    /** Decimal places per ISO 4217 (0, 2, or 3). */
+    decimals: number;
+    /** Preferred locale for Intl.NumberFormat (e.g. 'ko-KR'). */
+    locale: string;
+}
+/** 43 supported fiat currencies with metadata. Ordered by CurrencyCodeSchema enum. */
+export declare const CURRENCY_META: readonly CurrencyMeta[];
+/**
+ * Get metadata for a currency code.
+ *
+ * @param code - ISO 4217 currency code (e.g. 'KRW').
+ * @returns CurrencyMeta or undefined if not supported.
+ */
+export declare function getCurrencyMeta(code: string): CurrencyMeta | undefined;
+//# sourceMappingURL=forex-currencies.d.ts.map

package/dist/infrastructure/oracle/forex-currencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forex-currencies.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/oracle/forex-currencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sFAAsF;AACtF,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EA4CvC,CAAC;AAOX;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE"}

package/dist/infrastructure/oracle/forex-currencies.js

@@ -0,0 +1,71 @@
+/**
+ * Fiat currency metadata for 43 supported display currencies.
+ *
+ * Used by:
+ * - Admin UI: currency dropdown (name, symbol)
+ * - Intl.NumberFormat: locale-aware formatting (decimals, locale)
+ * - ForexRateService: validation of currency codes
+ *
+ * Decimals follow ISO 4217:
+ * - 0: KRW, JPY, VND, CLP, HUF, PKR
+ * - 2: Most currencies (USD, EUR, GBP, ...)
+ * - 3: KWD, BHD (1/1000 subunit)
+ */
+/** 43 supported fiat currencies with metadata. Ordered by CurrencyCodeSchema enum. */
+export const CURRENCY_META = [
+    { code: 'USD', name: 'US Dollar', symbol: '$', decimals: 2, locale: 'en-US' },
+    { code: 'KRW', name: 'Korean Won', symbol: '\u20A9', decimals: 0, locale: 'ko-KR' },
+    { code: 'JPY', name: 'Japanese Yen', symbol: '\u00A5', decimals: 0, locale: 'ja-JP' },
+    { code: 'EUR', name: 'Euro', symbol: '\u20AC', decimals: 2, locale: 'de-DE' },
+    { code: 'GBP', name: 'British Pound', symbol: '\u00A3', decimals: 2, locale: 'en-GB' },
+    { code: 'CNY', name: 'Chinese Yuan', symbol: '\u00A5', decimals: 2, locale: 'zh-CN' },
+    { code: 'CAD', name: 'Canadian Dollar', symbol: 'CA$', decimals: 2, locale: 'en-CA' },
+    { code: 'AUD', name: 'Australian Dollar', symbol: 'A$', decimals: 2, locale: 'en-AU' },
+    { code: 'CHF', name: 'Swiss Franc', symbol: 'CHF', decimals: 2, locale: 'de-CH' },
+    { code: 'SGD', name: 'Singapore Dollar', symbol: 'S$', decimals: 2, locale: 'en-SG' },
+    { code: 'HKD', name: 'Hong Kong Dollar', symbol: 'HK$', decimals: 2, locale: 'en-HK' },
+    { code: 'INR', name: 'Indian Rupee', symbol: '\u20B9', decimals: 2, locale: 'en-IN' },
+    { code: 'TWD', name: 'Taiwan Dollar', symbol: 'NT$', decimals: 2, locale: 'zh-TW' },
+    { code: 'THB', name: 'Thai Baht', symbol: '\u0E3F', decimals: 2, locale: 'th-TH' },
+    { code: 'MYR', name: 'Malaysian Ringgit', symbol: 'RM', decimals: 2, locale: 'ms-MY' },
+    { code: 'IDR', name: 'Indonesian Rupiah', symbol: 'Rp', decimals: 2, locale: 'id-ID' },
+    { code: 'PHP', name: 'Philippine Peso', symbol: '\u20B1', decimals: 2, locale: 'en-PH' },
+    { code: 'VND', name: 'Vietnamese Dong', symbol: '\u20AB', decimals: 0, locale: 'vi-VN' },
+    { code: 'BRL', name: 'Brazilian Real', symbol: 'R$', decimals: 2, locale: 'pt-BR' },
+    { code: 'MXN', name: 'Mexican Peso', symbol: 'MX$', decimals: 2, locale: 'es-MX' },
+    { code: 'CLP', name: 'Chilean Peso', symbol: 'CL$', decimals: 0, locale: 'es-CL' },
+    { code: 'TRY', name: 'Turkish Lira', symbol: '\u20BA', decimals: 2, locale: 'tr-TR' },
+    { code: 'PLN', name: 'Polish Zloty', symbol: 'z\u0142', decimals: 2, locale: 'pl-PL' },
+    { code: 'CZK', name: 'Czech Koruna', symbol: 'K\u010D', decimals: 2, locale: 'cs-CZ' },
+    { code: 'HUF', name: 'Hungarian Forint', symbol: 'Ft', decimals: 0, locale: 'hu-HU' },
+    { code: 'SEK', name: 'Swedish Krona', symbol: 'kr', decimals: 2, locale: 'sv-SE' },
+    { code: 'NOK', name: 'Norwegian Krone', symbol: 'kr', decimals: 2, locale: 'nb-NO' },
+    { code: 'DKK', name: 'Danish Krone', symbol: 'kr', decimals: 2, locale: 'da-DK' },
+    { code: 'NZD', name: 'New Zealand Dollar', symbol: 'NZ$', decimals: 2, locale: 'en-NZ' },
+    { code: 'ZAR', name: 'South African Rand', symbol: 'R', decimals: 2, locale: 'en-ZA' },
+    { code: 'ILS', name: 'Israeli Shekel', symbol: '\u20AA', decimals: 2, locale: 'he-IL' },
+    { code: 'SAR', name: 'Saudi Riyal', symbol: 'SR', decimals: 2, locale: 'ar-SA' },
+    { code: 'AED', name: 'UAE Dirham', symbol: 'AED', decimals: 2, locale: 'ar-AE' },
+    { code: 'KWD', name: 'Kuwaiti Dinar', symbol: 'KD', decimals: 3, locale: 'ar-KW' },
+    { code: 'BHD', name: 'Bahraini Dinar', symbol: 'BD', decimals: 3, locale: 'ar-BH' },
+    { code: 'NGN', name: 'Nigerian Naira', symbol: '\u20A6', decimals: 2, locale: 'en-NG' },
+    { code: 'RUB', name: 'Russian Ruble', symbol: '\u20BD', decimals: 2, locale: 'ru-RU' },
+    { code: 'UAH', name: 'Ukrainian Hryvnia', symbol: '\u20B4', decimals: 2, locale: 'uk-UA' },
+    { code: 'PKR', name: 'Pakistani Rupee', symbol: 'Rs', decimals: 0, locale: 'ur-PK' },
+    { code: 'BDT', name: 'Bangladeshi Taka', symbol: '\u09F3', decimals: 2, locale: 'bn-BD' },
+    { code: 'LKR', name: 'Sri Lankan Rupee', symbol: 'Rs', decimals: 2, locale: 'si-LK' },
+    { code: 'MMK', name: 'Myanmar Kyat', symbol: 'K', decimals: 2, locale: 'my-MM' },
+    { code: 'GEL', name: 'Georgian Lari', symbol: '\u20BE', decimals: 2, locale: 'ka-GE' },
+];
+/** Map from currency code to metadata for O(1) lookup. */
+const CURRENCY_MAP = new Map(CURRENCY_META.map((c) => [c.code, c]));
+/**
+ * Get metadata for a currency code.
+ *
+ * @param code - ISO 4217 currency code (e.g. 'KRW').
+ * @returns CurrencyMeta or undefined if not supported.
+ */
+export function getCurrencyMeta(code) {
+    return CURRENCY_MAP.get(code);
+}
+//# sourceMappingURL=forex-currencies.js.map

package/dist/infrastructure/oracle/forex-currencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forex-currencies.js","sourceRoot":"","sources":["../../../src/infrastructure/oracle/forex-currencies.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/oracle/forex-rate-service.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ForexRateService: IForexRateService implementation with caching.
+ *
+ * Uses CoinGeckoForexProvider for rate fetching and a dedicated
+ * InMemoryPriceCache instance (30-minute TTL) for caching.
+ *
+ * Cache key pattern: `forex:USD/{currency}` -- avoids collision with
+ * crypto cache keys (`chain:address`).
+ *
+ * Graceful fallback: getRate() returns null on any error (caller shows USD).
+ * getRates() omits failed currencies from result Map.
+ */
+import type { CurrencyCode, ForexRate, IForexRateService } from '@waiaas/core';
+import type { CoinGeckoForexProvider } from './coingecko-forex.js';
+import type { InMemoryPriceCache } from './price-cache.js';
+/** Dependency injection for ForexRateService. */
+export interface ForexRateServiceDeps {
+    /** CoinGecko forex rate provider. */
+    forexProvider: CoinGeckoForexProvider;
+    /** Dedicated cache instance (30-min TTL, separate from crypto cache). */
+    cache: InMemoryPriceCache;
+}
+/**
+ * Forex rate service with CoinGecko provider and InMemoryPriceCache.
+ *
+ * - getRate('USD') returns rate=1 immediately (no API call).
+ * - getRate(other) checks cache first, then fetches from CoinGecko.
+ * - All errors caught and returned as null (graceful fallback).
+ */
+export declare class ForexRateService implements IForexRateService {
+    private readonly provider;
+    private readonly cache;
+    constructor(deps: ForexRateServiceDeps);
+    /**
+     * Get exchange rate from USD to target currency.
+     *
+     * @param to - Target currency code.
+     * @returns ForexRate or null on failure (graceful fallback).
+     */
+    getRate(to: CurrencyCode): Promise<ForexRate | null>;
+    /**
+     * Get exchange rates for multiple currencies.
+     *
+     * Batch-optimized: only fetches cache-miss currencies from CoinGecko.
+     *
+     * @param currencies - Array of target currency codes.
+     * @returns Map from currency code to ForexRate. Missing rates omitted.
+     */
+    getRates(currencies: CurrencyCode[]): Promise<Map<CurrencyCode, ForexRate>>;
+}
+//# sourceMappingURL=forex-rate-service.d.ts.map

package/dist/infrastructure/oracle/forex-rate-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forex-rate-service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/oracle/forex-rate-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAa,MAAM,cAAc,CAAC;AAC1F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAM3D,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,aAAa,EAAE,sBAAsB,CAAC;IACtC,yEAAyE;IACzE,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAqDD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,IAAI,EAAE,oBAAoB;IAKtC;;;;;OAKG;IACG,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA0C1D;;;;;;;OAOG;IACG,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;CA8ClF"}

package/dist/infrastructure/oracle/forex-rate-service.js

@@ -0,0 +1,149 @@
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Cache key prefix for forex rates. */
+const FOREX_KEY_PREFIX = 'forex:USD/';
+/** ForexRate TTL in milliseconds (30 minutes). */
+const FOREX_TTL_MS = 30 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Build cache key for a forex rate. */
+function forexCacheKey(currency) {
+    return `${FOREX_KEY_PREFIX}${currency}`;
+}
+/** Convert a PriceInfo (from cache) back to ForexRate. */
+function priceInfoToForexRate(to, price, source) {
+    return {
+        from: 'USD',
+        to,
+        rate: price.usdPrice, // We store rate in usdPrice field
+        source,
+        fetchedAt: price.fetchedAt,
+        expiresAt: price.expiresAt,
+    };
+}
+/** Create a PriceInfo wrapper for storing a forex rate in the cache. */
+function rateToPriceInfo(rate) {
+    const now = Date.now();
+    return {
+        usdPrice: rate, // Store exchange rate in usdPrice field
+        source: 'coingecko',
+        fetchedAt: now,
+        expiresAt: now + FOREX_TTL_MS,
+        isStale: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// ForexRateService
+// ---------------------------------------------------------------------------
+/**
+ * Forex rate service with CoinGecko provider and InMemoryPriceCache.
+ *
+ * - getRate('USD') returns rate=1 immediately (no API call).
+ * - getRate(other) checks cache first, then fetches from CoinGecko.
+ * - All errors caught and returned as null (graceful fallback).
+ */
+export class ForexRateService {
+    provider;
+    cache;
+    constructor(deps) {
+        this.provider = deps.forexProvider;
+        this.cache = deps.cache;
+    }
+    /**
+     * Get exchange rate from USD to target currency.
+     *
+     * @param to - Target currency code.
+     * @returns ForexRate or null on failure (graceful fallback).
+     */
+    async getRate(to) {
+        try {
+            // USD -> USD is always 1 (no API call needed)
+            if (to === 'USD') {
+                const now = Date.now();
+                return {
+                    from: 'USD',
+                    to: 'USD',
+                    rate: 1,
+                    source: 'cache',
+                    fetchedAt: now,
+                    expiresAt: now + FOREX_TTL_MS,
+                };
+            }
+            const cacheKey = forexCacheKey(to);
+            // Check cache first
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return priceInfoToForexRate(to, cached, 'cache');
+            }
+            // Fetch from CoinGecko
+            const rates = await this.provider.getRates([to]);
+            const rate = rates.get(to);
+            if (rate === undefined) {
+                return null;
+            }
+            // Store in cache
+            const priceInfo = rateToPriceInfo(rate);
+            this.cache.set(cacheKey, priceInfo);
+            return priceInfoToForexRate(to, priceInfo, 'coingecko');
+        }
+        catch {
+            // Graceful fallback: any error -> null
+            return null;
+        }
+    }
+    /**
+     * Get exchange rates for multiple currencies.
+     *
+     * Batch-optimized: only fetches cache-miss currencies from CoinGecko.
+     *
+     * @param currencies - Array of target currency codes.
+     * @returns Map from currency code to ForexRate. Missing rates omitted.
+     */
+    async getRates(currencies) {
+        const result = new Map();
+        const toFetch = [];
+        // Phase 1: Check cache, collect misses
+        for (const currency of currencies) {
+            if (currency === 'USD') {
+                const now = Date.now();
+                result.set('USD', {
+                    from: 'USD',
+                    to: 'USD',
+                    rate: 1,
+                    source: 'cache',
+                    fetchedAt: now,
+                    expiresAt: now + FOREX_TTL_MS,
+                });
+                continue;
+            }
+            const cached = this.cache.get(forexCacheKey(currency));
+            if (cached) {
+                result.set(currency, priceInfoToForexRate(currency, cached, 'cache'));
+            }
+            else {
+                toFetch.push(currency);
+            }
+        }
+        // Phase 2: Batch fetch cache misses
+        if (toFetch.length > 0) {
+            try {
+                const rates = await this.provider.getRates(toFetch);
+                for (const currency of toFetch) {
+                    const rate = rates.get(currency);
+                    if (rate !== undefined) {
+                        const priceInfo = rateToPriceInfo(rate);
+                        this.cache.set(forexCacheKey(currency), priceInfo);
+                        result.set(currency, priceInfoToForexRate(currency, priceInfo, 'coingecko'));
+                    }
+                }
+            }
+            catch {
+                // Graceful: batch fetch failure -> cached results only
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=forex-rate-service.js.map

package/dist/infrastructure/oracle/forex-rate-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forex-rate-service.js","sourceRoot":"","sources":["../../../src/infrastructure/oracle/forex-rate-service.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/oracle/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Oracle infrastructure module barrel export.
+ *
+ * Re-exports price age classification, cache utilities, error classes,
+ * Pyth oracle, CoinGecko oracle, and feed/platform ID helpers.
+ */
+export { classifyPriceAge, PriceAgeEnum, PRICE_AGE_THRESHOLDS, PRICE_AGES, type PriceAge, } from './price-age.js';
+export { InMemoryPriceCache, buildCacheKey } from './price-cache.js';
+export { PriceNotAvailableError, CoinGeckoNotConfiguredError, ForexNotAvailableError } from './oracle-errors.js';
+export { PythOracle } from './pyth-oracle.js';
+export { PYTH_FEED_IDS, getFeedId, getNativeFeedId, } from './pyth-feed-ids.js';
+export { CoinGeckoOracle } from './coingecko-oracle.js';
+export { COINGECKO_PLATFORM_MAP, getCoinGeckoPlatform, type CoinGeckoPlatform, } from './coingecko-platform-ids.js';
+export { OracleChain, type OracleChainDeps } from './oracle-chain.js';
+export { CoinGeckoForexProvider } from './coingecko-forex.js';
+export { ForexRateService, type ForexRateServiceDeps } from './forex-rate-service.js';
+export { CURRENCY_META, getCurrencyMeta, type CurrencyMeta } from './forex-currencies.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/infrastructure/oracle/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/oracle/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,UAAU,EACV,KAAK,QAAQ,GACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,aAAa,EACb,SAAS,EACT,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,iBAAiB,GACvB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/infrastructure/oracle/index.js

@@ -0,0 +1,19 @@
+/**
+ * Oracle infrastructure module barrel export.
+ *
+ * Re-exports price age classification, cache utilities, error classes,
+ * Pyth oracle, CoinGecko oracle, and feed/platform ID helpers.
+ */
+export { classifyPriceAge, PriceAgeEnum, PRICE_AGE_THRESHOLDS, PRICE_AGES, } from './price-age.js';
+export { InMemoryPriceCache, buildCacheKey } from './price-cache.js';
+export { PriceNotAvailableError, CoinGeckoNotConfiguredError, ForexNotAvailableError } from './oracle-errors.js';
+export { PythOracle } from './pyth-oracle.js';
+export { PYTH_FEED_IDS, getFeedId, getNativeFeedId, } from './pyth-feed-ids.js';
+export { CoinGeckoOracle } from './coingecko-oracle.js';
+export { COINGECKO_PLATFORM_MAP, getCoinGeckoPlatform, } from './coingecko-platform-ids.js';
+export { OracleChain } from './oracle-chain.js';
+// v1.5.3 Forex rate service
+export { CoinGeckoForexProvider } from './coingecko-forex.js';
+export { ForexRateService } from './forex-rate-service.js';
+export { CURRENCY_META, getCurrencyMeta } from './forex-currencies.js';
+//# sourceMappingURL=index.js.map

package/dist/infrastructure/oracle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/infrastructure/oracle/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,UAAU,GAEX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,aAAa,EACb,SAAS,EACT,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EACL,sBAAsB,EACtB,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,WAAW,EAAwB,MAAM,mBAAmB,CAAC;AAEtE,4BAA4B;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAA6B,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAqB,MAAM,uBAAuB,CAAC"}

package/dist/infrastructure/oracle/oracle-chain.d.ts

@@ -0,0 +1,101 @@
+/**
+ * OracleChain: Composite IPriceOracle with 3-stage fallback + cross-validation.
+ *
+ * Stage 1: Primary oracle (PythOracle) -- always tried first.
+ * Stage 2: Fallback oracle (CoinGeckoOracle) -- tried when primary fails;
+ *          also used for cross-validation when both succeed.
+ * Stage 3: Stale cache -- used when all oracles fail (within staleMax window).
+ *
+ * Cross-validation (when fallback is configured):
+ * - Both primary and fallback succeed -> compare prices.
+ * - Deviation > threshold (default 5%) -> degrade to isStale=true.
+ * - Deviation <= threshold -> adopt primary price (isStale=false).
+ * - Fallback failure during cross-validation -> trust primary as-is.
+ *
+ * Cache management: OracleChain owns InMemoryPriceCache exclusively.
+ * Individual oracles (PythOracle, CoinGeckoOracle) do NOT cache internally.
+ * Uses cache.getOrFetch() for stampede prevention.
+ */
+import type { ChainType, PriceInfo, CacheStats, IPriceOracle, TokenRef } from '@waiaas/core';
+import type { InMemoryPriceCache } from './price-cache.js';
+/** Dependency injection interface for OracleChain constructor. */
+export interface OracleChainDeps {
+    /** Primary oracle (PythOracle). Always tried first. */
+    primary: IPriceOracle;
+    /** Optional fallback oracle (CoinGeckoOracle). Used for fallback + cross-validation. */
+    fallback?: IPriceOracle;
+    /** Shared price cache (InMemoryPriceCache). OracleChain manages cache exclusively. */
+    cache: InMemoryPriceCache;
+    /** Cross-validation deviation threshold in percent. Default: 5. */
+    crossValidationThreshold?: number;
+}
+/**
+ * Composite price oracle with fallback chain and cross-validation.
+ *
+ * Implements IPriceOracle. Uses InMemoryPriceCache.getOrFetch() for
+ * cache-first access with stampede prevention.
+ */
+export declare class OracleChain implements IPriceOracle {
+    private readonly primary;
+    private readonly fallback;
+    private readonly cache;
+    private readonly threshold;
+    constructor(deps: OracleChainDeps);
+    /**
+     * Get price for a single token.
+     *
+     * Flow:
+     * 1. Check cache (via getOrFetch stampede prevention).
+     * 2. Try primary oracle (Pyth).
+     * 3. If primary succeeds and fallback exists, cross-validate.
+     * 4. If primary fails, try fallback oracle (CoinGecko).
+     * 5. If all fail, try stale cache.
+     * 6. If nothing available, throw PriceNotAvailableError.
+     *
+     * @param token - Token reference for price lookup.
+     * @returns PriceInfo from best available source.
+     * @throws PriceNotAvailableError when no source can provide a price.
+     */
+    getPrice(token: TokenRef): Promise<PriceInfo>;
+    /**
+     * Get prices for multiple tokens.
+     *
+     * Each token is queried individually via getPrice() (which handles
+     * cache, fallback, and cross-validation per token). Failed tokens
+     * are silently excluded from the result Map.
+     *
+     * @param tokens - Array of token references.
+     * @returns Map from cache key to PriceInfo.
+     */
+    getPrices(tokens: TokenRef[]): Promise<Map<string, PriceInfo>>;
+    /**
+     * Get native token price (SOL or ETH).
+     *
+     * Delegates to getPrice() with address='native' and chain-appropriate decimals.
+     *
+     * @param chain - Chain type ('solana' or 'ethereum').
+     * @returns PriceInfo for the native token.
+     */
+    getNativePrice(chain: ChainType): Promise<PriceInfo>;
+    /**
+     * Get cache statistics from InMemoryPriceCache.
+     *
+     * @returns Current cache hit/miss/stale/size/eviction counts.
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Core fallback + cross-validation logic.
+     *
+     * Called by cache.getOrFetch() on cache miss. This function:
+     * 1. Tries primary oracle.
+     * 2. On primary success, cross-validates with fallback (if available).
+     * 3. On primary failure, tries fallback as data source.
+     * 4. On all failures, checks stale cache.
+     * 5. If everything fails, throws PriceNotAvailableError.
+     *
+     * Note: stale fallback is handled inside the fetcher so it can
+     * return stale data that gets re-cached (intentional: oracle outage survival).
+     */
+    private fetchWithFallback;
+}
+//# sourceMappingURL=oracle-chain.d.ts.map

package/dist/infrastructure/oracle/oracle-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oracle-chain.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/oracle/oracle-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQ3D,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,OAAO,EAAE,YAAY,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,sFAAsF;IACtF,KAAK,EAAE,kBAAkB,CAAC;IAC1B,mEAAmE;IACnE,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAqBD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE,eAAe;IAOjC;;;;;;;;;;;;;;OAcG;IACG,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IAQnD;;;;;;;;;OASG;IACG,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAiBpE;;;;;;;OAOG;IACG,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAK1D;;;;OAIG;IACH,aAAa,IAAI,UAAU;IAQ3B;;;;;;;;;;;;OAYG;YACW,iBAAiB;CA4ChC"}

package/dist/infrastructure/oracle/oracle-chain.js

@@ -0,0 +1,163 @@
+import { buildCacheKey } from './price-cache.js';
+import { PriceNotAvailableError } from './oracle-errors.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Calculate percentage deviation between two prices.
+ *
+ * Formula: |primary - fallback| / primary * 100
+ * Returns 0 when primary is 0 (avoid division by zero).
+ */
+function calculateDeviation(primary, fallback) {
+    if (primary === 0)
+        return 0;
+    return (Math.abs(primary - fallback) / primary) * 100;
+}
+// ---------------------------------------------------------------------------
+// OracleChain
+// ---------------------------------------------------------------------------
+/**
+ * Composite price oracle with fallback chain and cross-validation.
+ *
+ * Implements IPriceOracle. Uses InMemoryPriceCache.getOrFetch() for
+ * cache-first access with stampede prevention.
+ */
+export class OracleChain {
+    primary;
+    fallback;
+    cache;
+    threshold;
+    constructor(deps) {
+        this.primary = deps.primary;
+        this.fallback = deps.fallback;
+        this.cache = deps.cache;
+        this.threshold = deps.crossValidationThreshold ?? 5;
+    }
+    /**
+     * Get price for a single token.
+     *
+     * Flow:
+     * 1. Check cache (via getOrFetch stampede prevention).
+     * 2. Try primary oracle (Pyth).
+     * 3. If primary succeeds and fallback exists, cross-validate.
+     * 4. If primary fails, try fallback oracle (CoinGecko).
+     * 5. If all fail, try stale cache.
+     * 6. If nothing available, throw PriceNotAvailableError.
+     *
+     * @param token - Token reference for price lookup.
+     * @returns PriceInfo from best available source.
+     * @throws PriceNotAvailableError when no source can provide a price.
+     */
+    async getPrice(token) {
+        const cacheKey = buildCacheKey(token.chain, token.address);
+        return this.cache.getOrFetch(cacheKey, async () => {
+            return this.fetchWithFallback(token, cacheKey);
+        });
+    }
+    /**
+     * Get prices for multiple tokens.
+     *
+     * Each token is queried individually via getPrice() (which handles
+     * cache, fallback, and cross-validation per token). Failed tokens
+     * are silently excluded from the result Map.
+     *
+     * @param tokens - Array of token references.
+     * @returns Map from cache key to PriceInfo.
+     */
+    async getPrices(tokens) {
+        const result = new Map();
+        const promises = tokens.map(async (token) => {
+            try {
+                const price = await this.getPrice(token);
+                const key = buildCacheKey(token.chain, token.address);
+                result.set(key, price);
+            }
+            catch {
+                // Skip failed tokens
+            }
+        });
+        await Promise.all(promises);
+        return result;
+    }
+    /**
+     * Get native token price (SOL or ETH).
+     *
+     * Delegates to getPrice() with address='native' and chain-appropriate decimals.
+     *
+     * @param chain - Chain type ('solana' or 'ethereum').
+     * @returns PriceInfo for the native token.
+     */
+    async getNativePrice(chain) {
+        const decimals = chain === 'solana' ? 9 : 18;
+        return this.getPrice({ address: 'native', decimals, chain });
+    }
+    /**
+     * Get cache statistics from InMemoryPriceCache.
+     *
+     * @returns Current cache hit/miss/stale/size/eviction counts.
+     */
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+    // ---------------------------------------------------------------------------
+    // Private: Fetch with fallback and cross-validation
+    // ---------------------------------------------------------------------------
+    /**
+     * Core fallback + cross-validation logic.
+     *
+     * Called by cache.getOrFetch() on cache miss. This function:
+     * 1. Tries primary oracle.
+     * 2. On primary success, cross-validates with fallback (if available).
+     * 3. On primary failure, tries fallback as data source.
+     * 4. On all failures, checks stale cache.
+     * 5. If everything fails, throws PriceNotAvailableError.
+     *
+     * Note: stale fallback is handled inside the fetcher so it can
+     * return stale data that gets re-cached (intentional: oracle outage survival).
+     */
+    async fetchWithFallback(token, cacheKey) {
+        // Stage 1: Try primary oracle (Pyth)
+        let primaryResult = null;
+        try {
+            primaryResult = await this.primary.getPrice(token);
+        }
+        catch {
+            // Primary failed, continue to fallback
+        }
+        // Stage 2a: Primary succeeded -> cross-validate with fallback
+        if (primaryResult) {
+            if (this.fallback) {
+                try {
+                    const fallbackResult = await this.fallback.getPrice(token);
+                    const deviation = calculateDeviation(primaryResult.usdPrice, fallbackResult.usdPrice);
+                    if (deviation > this.threshold) {
+                        // Deviation too high -- degrade to stale
+                        return { ...primaryResult, isStale: true };
+                    }
+                }
+                catch {
+                    // Fallback failed during cross-validation -- trust primary as-is
+                }
+            }
+            return primaryResult;
+        }
+        // Stage 2b: Primary failed -> try fallback as data source
+        if (this.fallback) {
+            try {
+                return await this.fallback.getPrice(token);
+            }
+            catch {
+                // Fallback also failed
+            }
+        }
+        // Stage 3: All oracles failed -> try stale cache
+        const stale = this.cache.getStale(cacheKey);
+        if (stale) {
+            return { ...stale, isStale: true, source: 'cache' };
+        }
+        // Stage 4: Nothing available
+        throw new PriceNotAvailableError(cacheKey);
+    }
+}
+//# sourceMappingURL=oracle-chain.js.map