@wopr-network/platform-core 1.49.0 → 1.49.2

package/dist/billing/crypto/oracle/composite.js

@@ -0,0 +1,34 @@
+/**
+ * Composite oracle — tries primary (Chainlink on-chain), falls back to secondary (CoinGecko).
+ *
+ * When a feedAddress is provided (from payment_methods.oracle_address), the primary
+ * oracle is used with that address. When no feed exists or the primary fails,
+ * the fallback oracle is consulted.
+ */
+export class CompositeOracle {
+    primary;
+    fallback;
+    constructor(primary, fallback) {
+        this.primary = primary;
+        this.fallback = fallback;
+    }
+    async getPrice(asset, feedAddress) {
+        // If a specific feed address is provided, try the primary (Chainlink) first
+        if (feedAddress) {
+            try {
+                return await this.primary.getPrice(asset, feedAddress);
+            }
+            catch {
+                // Primary failed (stale, network error) — fall through to fallback
+            }
+        }
+        // Try primary without explicit feed (uses built-in feed map for BTC/ETH)
+        try {
+            return await this.primary.getPrice(asset);
+        }
+        catch {
+            // No feed configured or call failed — use fallback
+        }
+        return this.fallback.getPrice(asset);
+    }
+}

package/dist/billing/crypto/oracle/convert.d.ts

@@ -1,20 +1,30 @@
 /**
- * Convert USD cents to native token amount using a price in cents.
+ * Price units: **microdollars** (1 microdollar = $0.000001 = 10^-6 USD).
  *
- * Formula: rawAmount = amountCents × 10^decimals / priceCents
+ * Why not cents? DOGE at $0.094 rounds to 9 cents — 6% error.
+ * Microdollars give 6 decimal places: $0.094147 = 94,147 microdollars.
+ *
+ * Chainlink feeds: 8 decimals → answer / 100 = microdollars.
+ * CoinGecko: Math.round(usd * 1_000_000) = microdollars.
+ * All math is integer bigint — no floating point.
+ */
+/**
+ * Convert USD cents to native token amount using a price in microdollars.
+ *
+ * Formula: rawAmount = (amountCents × 10_000) × 10^decimals / priceMicros
  *
  * Examples:
- *   $50 in ETH at $3,500:  centsToNative(5000, 350000, 18) = 14285714285714285n (≈0.01429 ETH)
- *   $50 in BTC at $65,000: centsToNative(5000, 6500000, 8)  = 76923n (76,923 sats ≈ 0.00077 BTC)
+ *   $50 in BTC at $70,315:  centsToNative(5000, 70_315_000_000, 8) = 71,119 sats
+ *   $50 in DOGE at $0.094:  centsToNative(5000, 94_147, 8) = 53,107,898,982 base units (531.08 DOGE)
  *
  * Integer math only. No floating point.
  */
-export declare function centsToNative(amountCents: number, priceCents: number, decimals: number): bigint;
+export declare function centsToNative(amountCents: number, priceMicros: number, decimals: number): bigint;
 /**
- * Convert native token amount back to USD cents using a price in cents.
+ * Convert native token amount back to USD cents using a price in microdollars.
  *
  * Inverse of centsToNative. Truncates fractional cents.
  *
  * Integer math only.
  */
-export declare function nativeToCents(rawAmount: bigint, priceCents: number, decimals: number): number;
+export declare function nativeToCents(rawAmount: bigint, priceMicros: number, decimals: number): number;

package/dist/billing/crypto/oracle/convert.js

@@ -1,38 +1,51 @@
 /**
- * Convert USD cents to native token amount using a price in cents.
+ * Price units: **microdollars** (1 microdollar = $0.000001 = 10^-6 USD).
  *
- * Formula: rawAmount = amountCents × 10^decimals / priceCents
+ * Why not cents? DOGE at $0.094 rounds to 9 cents — 6% error.
+ * Microdollars give 6 decimal places: $0.094147 = 94,147 microdollars.
+ *
+ * Chainlink feeds: 8 decimals → answer / 100 = microdollars.
+ * CoinGecko: Math.round(usd * 1_000_000) = microdollars.
+ * All math is integer bigint — no floating point.
+ */
+/** Microdollars per cent. Multiply amountCents by this to get microdollars. */
+const MICROS_PER_CENT = 10000n;
+/**
+ * Convert USD cents to native token amount using a price in microdollars.
+ *
+ * Formula: rawAmount = (amountCents × 10_000) × 10^decimals / priceMicros
  *
  * Examples:
- *   $50 in ETH at $3,500:  centsToNative(5000, 350000, 18) = 14285714285714285n (≈0.01429 ETH)
- *   $50 in BTC at $65,000: centsToNative(5000, 6500000, 8)  = 76923n (76,923 sats ≈ 0.00077 BTC)
+ *   $50 in BTC at $70,315:  centsToNative(5000, 70_315_000_000, 8) = 71,119 sats
+ *   $50 in DOGE at $0.094:  centsToNative(5000, 94_147, 8) = 53,107,898,982 base units (531.08 DOGE)
  *
  * Integer math only. No floating point.
  */
-export function centsToNative(amountCents, priceCents, decimals) {
+export function centsToNative(amountCents, priceMicros, decimals) {
     if (!Number.isInteger(amountCents) || amountCents <= 0) {
         throw new Error(`amountCents must be a positive integer, got ${amountCents}`);
     }
-    if (!Number.isInteger(priceCents) || priceCents <= 0) {
-        throw new Error(`priceCents must be a positive integer, got ${priceCents}`);
+    if (!Number.isInteger(priceMicros) || priceMicros <= 0) {
+        throw new Error(`priceMicros must be a positive integer, got ${priceMicros}`);
     }
     if (!Number.isInteger(decimals) || decimals < 0) {
         throw new Error(`decimals must be a non-negative integer, got ${decimals}`);
     }
-    return (BigInt(amountCents) * 10n ** BigInt(decimals)) / BigInt(priceCents);
+    // Convert amountCents to microdollars to match priceMicros units
+    return (BigInt(amountCents) * MICROS_PER_CENT * 10n ** BigInt(decimals)) / BigInt(priceMicros);
 }
 /**
- * Convert native token amount back to USD cents using a price in cents.
+ * Convert native token amount back to USD cents using a price in microdollars.
  *
  * Inverse of centsToNative. Truncates fractional cents.
  *
  * Integer math only.
  */
-export function nativeToCents(rawAmount, priceCents, decimals) {
+export function nativeToCents(rawAmount, priceMicros, decimals) {
     if (rawAmount < 0n)
         throw new Error("rawAmount must be non-negative");
-    if (!Number.isInteger(priceCents) || priceCents <= 0) {
-        throw new Error(`priceCents must be a positive integer, got ${priceCents}`);
+    if (!Number.isInteger(priceMicros) || priceMicros <= 0) {
+        throw new Error(`priceMicros must be a positive integer, got ${priceMicros}`);
     }
-    return Number((rawAmount * BigInt(priceCents)) / 10n ** BigInt(decimals));
+    return Number((rawAmount * BigInt(priceMicros)) / (MICROS_PER_CENT * 10n ** BigInt(decimals)));
 }

package/dist/billing/crypto/oracle/fixed.d.ts

@@ -1,10 +1,10 @@
 import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
 /**
  * Fixed-price oracle for testing and local dev (Anvil, regtest).
- * Returns hardcoded prices — no RPC calls.
+ * Returns hardcoded prices in microdollars — no RPC calls.
  */
 export declare class FixedPriceOracle implements IPriceOracle {
     private readonly prices;
     constructor(prices?: Partial<Record<PriceAsset, number>>);
-    getPrice(asset: PriceAsset): Promise<PriceResult>;
+    getPrice(asset: PriceAsset, _feedAddress?: `0x${string}`): Promise<PriceResult>;
 }

package/dist/billing/crypto/oracle/fixed.js

@@ -1,20 +1,22 @@
 /**
  * Fixed-price oracle for testing and local dev (Anvil, regtest).
- * Returns hardcoded prices — no RPC calls.
+ * Returns hardcoded prices in microdollars — no RPC calls.
  */
 export class FixedPriceOracle {
     prices;
     constructor(prices = {}) {
         this.prices = {
-            ETH: 350_000, // $3,500
-            BTC: 6_500_000, // $65,000
+            ETH: 3_500_000_000, // $3,500 in microdollars
+            BTC: 65_000_000_000, // $65,000 in microdollars
+            DOGE: 94_000, // $0.094 in microdollars
+            LTC: 55_000_000, // $55 in microdollars
             ...prices,
         };
     }
-    async getPrice(asset) {
-        const priceCents = this.prices[asset];
-        if (priceCents === undefined)
+    async getPrice(asset, _feedAddress) {
+        const priceMicros = this.prices[asset];
+        if (priceMicros === undefined)
             throw new Error(`No fixed price for ${asset}`);
-        return { priceCents, updatedAt: new Date() };
+        return { priceMicros, updatedAt: new Date() };
     }
 }

package/dist/billing/crypto/oracle/index.d.ts

@@ -1,5 +1,9 @@
 export type { ChainlinkOracleOpts } from "./chainlink.js";
 export { ChainlinkOracle } from "./chainlink.js";
+export type { CoinGeckoOracleOpts } from "./coingecko.js";
+export { CoinGeckoOracle } from "./coingecko.js";
+export { CompositeOracle } from "./composite.js";
 export { centsToNative, nativeToCents } from "./convert.js";
 export { FixedPriceOracle } from "./fixed.js";
 export type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+export { AssetNotSupportedError } from "./types.js";

package/dist/billing/crypto/oracle/index.js

@@ -1,3 +1,6 @@
 export { ChainlinkOracle } from "./chainlink.js";
+export { CoinGeckoOracle } from "./coingecko.js";
+export { CompositeOracle } from "./composite.js";
 export { centsToNative, nativeToCents } from "./convert.js";
 export { FixedPriceOracle } from "./fixed.js";
+export { AssetNotSupportedError } from "./types.js";

package/dist/billing/crypto/oracle/types.d.ts

@@ -1,13 +1,22 @@
 /** Assets with Chainlink price feeds. */
 export type PriceAsset = string;
+/** Thrown when no oracle supports a given asset (not a transient failure). */
+export declare class AssetNotSupportedError extends Error {
+    constructor(asset: string);
+}
 /** Result from a price oracle query. */
 export interface PriceResult {
-    /** USD cents per 1 unit of asset (integer). */
-    priceCents: number;
+    /** Microdollars per 1 unit of asset (integer, 10^-6 USD). */
+    priceMicros: number;
     /** When the price was last updated on-chain. */
     updatedAt: Date;
 }
 /** Read-only price oracle. */
 export interface IPriceOracle {
-    getPrice(asset: PriceAsset): Promise<PriceResult>;
+    /**
+     * Get the current USD price for an asset.
+     * @param asset — token symbol (e.g. "BTC", "DOGE")
+     * @param feedAddress — optional Chainlink feed address override (from payment_methods.oracle_address)
+     */
+    getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult>;
 }

package/dist/billing/crypto/oracle/types.js

@@ -1 +1,7 @@
-export {};
+/** Thrown when no oracle supports a given asset (not a transient failure). */
+export class AssetNotSupportedError extends Error {
+    constructor(asset) {
+        super(`No price oracle supports asset: ${asset}`);
+        this.name = "AssetNotSupportedError";
+    }
+}

package/dist/billing/crypto/unified-checkout.d.ts

@@ -11,8 +11,8 @@ export interface UnifiedCheckoutResult {
     token: string;
     chain: string;
     referenceId: string;
-    /** For volatile assets: price at checkout time (USD cents per unit). */
-    priceCents?: number;
+    /** For volatile assets: price at checkout time (microdollars per unit, 10^-6 USD). */
+    priceMicros?: number;
 }
 /**
  * Unified checkout — delegates to CryptoServiceClient.createCharge().

package/dist/billing/crypto/unified-checkout.js

@@ -22,6 +22,6 @@ export async function createUnifiedCheckout(deps, chain, opts) {
         token: result.token,
         chain: result.chain,
         referenceId: result.chargeId,
-        priceCents: result.priceCents,
+        priceMicros: result.priceMicros,
     };
 }

package/drizzle/migrations/0017_fix_derivation_index_constraint.sql

@@ -0,0 +1,7 @@
+-- Fix: derivation_index unique constraint was global, not per-chain.
+-- DOGE index 1 collided with BTC index 1. Must be (chain, derivation_index).
+
+DROP INDEX IF EXISTS "uq_crypto_charges_derivation_index";
+--> statement-breakpoint
+
+CREATE UNIQUE INDEX IF NOT EXISTS "uq_crypto_charges_chain_derivation" ON "crypto_charges" ("chain", "derivation_index") WHERE "chain" IS NOT NULL AND "derivation_index" IS NOT NULL;

package/drizzle/migrations/meta/_journal.json

@@ -120,6 +120,13 @@
       "when": 1743004800000,
       "tag": "0016_charge_progress_columns",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1743091200000,
+      "tag": "0017_fix_derivation_index_constraint",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.49.0",
+  "version": "1.49.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/__tests__/key-server.test.ts

@@ -110,7 +110,7 @@ function mockDeps(): KeyServerDeps & {
     db: createMockDb() as never,
     chargeStore: chargeStore as never,
     methodStore: methodStore as never,
-    oracle: { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000, updatedAt: new Date() }) } as never,
+    oracle: { getPrice: vi.fn().mockResolvedValue({ priceMicros: 65_000_000_000, updatedAt: new Date() }) } as never,
   };
 }
 

package/src/billing/crypto/btc/__tests__/watcher.test.ts

@@ -23,7 +23,7 @@ function makeCursorStore() {
 }
 
 function makeOracle() {
-  return { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000 }) };
+  return { getPrice: vi.fn().mockResolvedValue({ priceMicros: 65_000_000_000 }) };
 }
 
 describe("BtcWatcher — intermediate confirmations", () => {

package/src/billing/crypto/btc/watcher.ts

@@ -1,4 +1,5 @@
 import type { IWatcherCursorStore } from "../cursor-store.js";
+import { nativeToCents } from "../oracle/convert.js";
 import type { IPriceOracle } from "../oracle/types.js";
 import type { BitcoindConfig, BtcPaymentEvent } from "./types.js";
 
@@ -90,7 +91,7 @@ export class BtcWatcher {
       true, // include_watchonly
     ])) as ReceivedByAddress[];
 
-    const { priceCents } = await this.oracle.getPrice("BTC");
+    const { priceMicros } = await this.oracle.getPrice("BTC");
 
     for (const entry of received) {
       if (!this.addresses.has(entry.address)) continue;
@@ -113,7 +114,8 @@ export class BtcWatcher {
         if (lastSeen !== null && tx.confirmations <= lastSeen) continue; // No change
 
         const amountSats = Math.round(detail.amount * 100_000_000);
-        const amountUsdCents = Math.round((amountSats * priceCents) / 100_000_000);
+        // priceMicros is microdollars per 1 BTC. Convert sats→USD cents via nativeToCents.
+        const amountUsdCents = nativeToCents(BigInt(amountSats), priceMicros, 8);
 
         const event: BtcPaymentEvent = {
           address: entry.address,

package/src/billing/crypto/client.ts

@@ -30,7 +30,7 @@ export interface CreateChargeResult {
   derivationIndex: number;
   expiresAt: string;
   displayAmount?: string;
-  priceCents?: number;
+  priceMicros?: number;
 }
 
 export interface ChargeStatus {

package/src/billing/crypto/evm/__tests__/eth-checkout.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { createEthCheckout, MIN_ETH_USD } from "../eth-checkout.js";
 
-const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceMicros: 3_500_000_000, updatedAt: new Date() }) };
 
 function makeDeps(derivationIndex = 0) {
   return {
@@ -20,9 +20,9 @@ describe("createEthCheckout", () => {
     const result = await createEthCheckout(deps, { tenant: "t1", amountUsd: 50, chain: "base" });
 
     expect(result.amountUsd).toBe(50);
-    expect(result.priceCents).toBe(350_000);
+    expect(result.priceMicros).toBe(3_500_000_000);
     expect(result.chain).toBe("base");
-    // $50 = 5000 cents. 5000 × 10^18 / 350000 = 14285714285714285n
+    // $50 = 5000 cents × 10000 micros/cent × 10^18 / 3_500_000_000 micros = 14285714285714285n
     expect(result.expectedWei).toBe("14285714285714285");
     expect(result.depositAddress).toMatch(/^0x/);
     expect(result.referenceId).toMatch(/^eth:base:0x/);

package/src/billing/crypto/evm/__tests__/eth-watcher.test.ts

@@ -5,7 +5,7 @@ function makeRpc(responses: Record<string, unknown>) {
   return vi.fn(async (method: string) => responses[method]);
 }
 
-const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceMicros: 3_500_000_000, updatedAt: new Date() }) };
 
 describe("EthWatcher", () => {
   it("detects native ETH transfer to watched address", async () => {
@@ -41,7 +41,7 @@ describe("EthWatcher", () => {
     const event = onPayment.mock.calls[0][0];
     expect(event.to).toBe("0xdeposit");
     expect(event.valueWei).toBe("1000000000000000000");
-    expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500
+    expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500 = $3,500 = 350,000 cents
     expect(event.txHash).toBe("0xabc");
     expect(event.confirmations).toBe(0);
     expect(event.confirmationsRequired).toBe(1);

package/src/billing/crypto/evm/eth-checkout.ts

@@ -24,8 +24,8 @@ export interface EthCheckoutResult {
   amountUsd: number;
   /** Expected ETH amount in wei (BigInt as string). */
   expectedWei: string;
-  /** ETH price in USD cents at checkout time. */
-  priceCents: number;
+  /** ETH price in microdollars at checkout time (10^-6 USD). */
+  priceMicros: number;
   chain: EvmChain;
   referenceId: string;
 }
@@ -45,8 +45,8 @@ export async function createEthCheckout(deps: EthCheckoutDeps, opts: EthCheckout
   }
 
   const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
-  const { priceCents } = await deps.oracle.getPrice("ETH");
-  const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
+  const { priceMicros } = await deps.oracle.getPrice("ETH");
+  const expectedWei = centsToNative(amountUsdCents, priceMicros, 18);
   const maxRetries = 3;
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -69,7 +69,7 @@ export async function createEthCheckout(deps: EthCheckoutDeps, opts: EthCheckout
         depositAddress,
         amountUsd: opts.amountUsd,
         expectedWei: expectedWei.toString(),
-        priceCents,
+        priceMicros,
         chain: opts.chain,
         referenceId,
       };

package/src/billing/crypto/evm/eth-watcher.ts

@@ -105,7 +105,7 @@ export class EthWatcher {
 
     if (latest < this._cursor) return;
 
-    const { priceCents } = await this.oracle.getPrice("ETH");
+    const { priceMicros } = await this.oracle.getPrice("ETH");
 
     // Scan up to latest (not just confirmed) to detect pending txs
     for (let blockNum = this._cursor; blockNum <= latest; blockNum++) {
@@ -131,7 +131,7 @@ export class EthWatcher {
           if (lastConf !== null && confs <= lastConf) continue;
         }
 
-        const amountUsdCents = nativeToCents(valueWei, priceCents, 18);
+        const amountUsdCents = nativeToCents(valueWei, priceMicros, 18);
 
         const event: EthPaymentEvent = {
           chain: this.chain,

package/src/billing/crypto/key-server-entry.ts

@@ -17,6 +17,8 @@ import { DrizzleWatcherCursorStore } from "./cursor-store.js";
 import { createRpcCaller } from "./evm/watcher.js";
 import { createKeyServerApp } from "./key-server.js";
 import { ChainlinkOracle } from "./oracle/chainlink.js";
+import { CoinGeckoOracle } from "./oracle/coingecko.js";
+import { CompositeOracle } from "./oracle/composite.js";
 import { FixedPriceOracle } from "./oracle/fixed.js";
 import { DrizzlePaymentMethodStore } from "./payment-method-store.js";
 import { startWatchers } from "./watcher-service.js";
@@ -48,10 +50,13 @@ async function main(): Promise<void> {
   const chargeStore = new DrizzleCryptoChargeRepository(db);
   const methodStore = new DrizzlePaymentMethodStore(db);
 
-  // Chainlink on-chain oracle for volatile assets (BTC, ETH).
-  const oracle = BASE_RPC_URL
+  // Composite oracle: Chainlink on-chain (BTC, ETH on Base) + CoinGecko fallback (DOGE, LTC, etc.)
+  // Every volatile asset needs reliable USD pricing — the ledger credits nanodollars.
+  const chainlink = BASE_RPC_URL
     ? new ChainlinkOracle({ rpcCall: createRpcCaller(BASE_RPC_URL) })
     : new FixedPriceOracle();
+  const coingecko = new CoinGeckoOracle();
+  const oracle = new CompositeOracle(chainlink, coingecko);
 
   const app = createKeyServerApp({
     db,

package/src/billing/crypto/key-server.ts

@@ -16,6 +16,7 @@ import type { ICryptoChargeRepository } from "./charge-store.js";
 import { deriveDepositAddress } from "./evm/address-gen.js";
 import { centsToNative } from "./oracle/convert.js";
 import type { IPriceOracle } from "./oracle/types.js";
+import { AssetNotSupportedError } from "./oracle/types.js";
 import type { IPaymentMethodStore } from "./payment-method-store.js";
 
 export interface KeyServerDeps {
@@ -157,13 +158,22 @@ export function createKeyServerApp(deps: KeyServerDeps): Hono {
     // Compute expected crypto amount in native base units.
     // Price is locked NOW — this is what the user must send.
     let expectedAmount: bigint;
-    if (method.oracleAddress) {
-      // Volatile asset (BTC, ETH, DOGE) — oracle-priced
-      const { priceCents } = await deps.oracle.getPrice(token);
-      expectedAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
-    } else {
-      // Stablecoin (1:1 USD) — e.g. $50 USDC = 50_000_000 base units (6 decimals)
-      expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+    const feedAddress = method.oracleAddress ? (method.oracleAddress as `0x${string}`) : undefined;
+    try {
+      // Try oracle pricing (Chainlink for BTC/ETH, CoinGecko for DOGE/LTC).
+      // feedAddress is a hint for Chainlink — undefined is fine, CompositeOracle
+      // falls through to CoinGecko or built-in feed maps.
+      const { priceMicros } = await deps.oracle.getPrice(token, feedAddress);
+      expectedAmount = centsToNative(amountUsdCents, priceMicros, method.decimals);
+    } catch (err) {
+      if (err instanceof AssetNotSupportedError) {
+        // No oracle knows this token (e.g. USDC, DAI) — stablecoin 1:1 USD.
+        expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+      } else {
+        // Transient oracle failure (network, rate limit, stale feed).
+        // Reject the charge — silently pricing BTC at $1 would be catastrophic.
+        return c.json({ error: `Price oracle unavailable for ${token}: ${(err as Error).message}` }, 503);
+      }
     }
 
     const referenceId = `${token.toLowerCase()}:${address.toLowerCase()}`;

package/src/billing/crypto/oracle/__tests__/chainlink.test.ts

@@ -28,7 +28,7 @@ describe("ChainlinkOracle", () => {
 
     const result = await oracle.getPrice("ETH");
 
-    expect(result.priceCents).toBe(350_000); // $3,500.00
+    expect(result.priceMicros).toBe(3_500_000_000); // $3,500.00
     expect(result.updatedAt).toBeInstanceOf(Date);
     expect(rpc).toHaveBeenCalledWith("eth_call", [
       { to: "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70", data: "0xfeaf968c" },
@@ -43,7 +43,7 @@ describe("ChainlinkOracle", () => {
 
     const result = await oracle.getPrice("BTC");
 
-    expect(result.priceCents).toBe(6_500_000); // $65,000.00
+    expect(result.priceMicros).toBe(65_000_000_000); // $65,000.00
   });
 
   it("handles fractional dollar prices correctly", async () => {
@@ -53,7 +53,7 @@ describe("ChainlinkOracle", () => {
 
     const result = await oracle.getPrice("ETH");
 
-    expect(result.priceCents).toBe(345_678); // $3,456.78
+    expect(result.priceMicros).toBe(3_456_780_000); // $3,456.78
   });
 
   it("rejects stale prices", async () => {
@@ -102,6 +102,6 @@ describe("ChainlinkOracle", () => {
     // 60-minute threshold → fresh
     const relaxed = new ChainlinkOracle({ rpcCall: rpc, maxStalenessMs: 60 * 60 * 1000 });
     const result = await relaxed.getPrice("ETH");
-    expect(result.priceCents).toBe(350_000);
+    expect(result.priceMicros).toBe(3_500_000_000);
   });
 });

package/src/billing/crypto/oracle/__tests__/coingecko.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+import { CoinGeckoOracle } from "../coingecko.js";
+
+describe("CoinGeckoOracle", () => {
+  const mockFetch = (price: number) =>
+    vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ bitcoin: { usd: price } }),
+    });
+
+  it("returns price in microdollars from CoinGecko API", async () => {
+    const oracle = new CoinGeckoOracle({ fetchFn: mockFetch(84_532.17) as unknown as typeof fetch });
+    const result = await oracle.getPrice("BTC");
+    expect(result.priceMicros).toBe(84_532_170_000);
+    expect(result.updatedAt).toBeInstanceOf(Date);
+  });
+
+  it("caches prices within TTL", async () => {
+    const fn = mockFetch(84_532.17);
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch, cacheTtlMs: 60_000 });
+    await oracle.getPrice("BTC");
+    await oracle.getPrice("BTC");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-fetches after cache expires", async () => {
+    const fn = mockFetch(84_532.17);
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch, cacheTtlMs: 0 });
+    await oracle.getPrice("BTC");
+    await oracle.getPrice("BTC");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws for unknown asset", async () => {
+    const oracle = new CoinGeckoOracle({ fetchFn: mockFetch(100) as unknown as typeof fetch });
+    await expect(oracle.getPrice("UNKNOWN")).rejects.toThrow("No price oracle supports asset: UNKNOWN");
+  });
+
+  it("throws on API error", async () => {
+    const fn = vi.fn().mockResolvedValue({ ok: false, status: 429, statusText: "Too Many Requests" });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    await expect(oracle.getPrice("BTC")).rejects.toThrow("CoinGecko API error");
+  });
+
+  it("throws on zero price", async () => {
+    const fn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ bitcoin: { usd: 0 } }),
+    });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    await expect(oracle.getPrice("BTC")).rejects.toThrow("Invalid CoinGecko price");
+  });
+
+  it("resolves DOGE via coingecko ID mapping", async () => {
+    const fn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ dogecoin: { usd: 0.1742 } }),
+    });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    const result = await oracle.getPrice("DOGE");
+    expect(result.priceMicros).toBe(174_200);
+    expect(fn).toHaveBeenCalledWith(expect.stringContaining("ids=dogecoin"));
+  });
+
+  it("resolves LTC via coingecko ID mapping", async () => {
+    const fn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ litecoin: { usd: 92.45 } }),
+    });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    const result = await oracle.getPrice("LTC");
+    expect(result.priceMicros).toBe(92_450_000);
+    expect(fn).toHaveBeenCalledWith(expect.stringContaining("ids=litecoin"));
+  });
+});