@wopr-network/platform-core 1.48.0 → 1.49.1

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

@@ -1,5 +1,5 @@
 export * from "./btc/index.js";
-export type { CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository } from "./charge-store.js";
+export type { CryptoChargeProgressUpdate, CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository, } from "./charge-store.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export type { ChainInfo, ChargeStatus, CreateChargeResult, CryptoConfig, CryptoServiceConfig, DeriveAddressResult, } from "./client.js";
 export { CryptoServiceClient, loadCryptoConfig } from "./client.js";
@@ -9,10 +9,10 @@ export * from "./evm/index.js";
 export type { KeyServerDeps } from "./key-server.js";
 export { createKeyServerApp } from "./key-server.js";
 export type { KeyServerWebhookDeps as CryptoWebhookDeps, KeyServerWebhookPayload as CryptoWebhookPayload, KeyServerWebhookResult as CryptoWebhookResult, } from "./key-server-webhook.js";
-export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook } from "./key-server-webhook.js";
+export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook, normalizeStatus, } from "./key-server-webhook.js";
 export * from "./oracle/index.js";
 export type { IPaymentMethodStore, PaymentMethodRecord } from "./payment-method-store.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
-export type { CryptoPaymentState } from "./types.js";
+export type { CryptoCharge, CryptoChargeStatus, CryptoPaymentState } from "./types.js";
 export type { UnifiedCheckoutDeps, UnifiedCheckoutResult } from "./unified-checkout.js";
 export { createUnifiedCheckout, MIN_CHECKOUT_USD as MIN_PAYMENT_USD, MIN_CHECKOUT_USD } from "./unified-checkout.js";

package/dist/billing/crypto/index.js

@@ -4,7 +4,7 @@ export { CryptoServiceClient, loadCryptoConfig } from "./client.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.js";
 export { createKeyServerApp } from "./key-server.js";
-export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook } from "./key-server-webhook.js";
+export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook, normalizeStatus, } from "./key-server-webhook.js";
 export * from "./oracle/index.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
 export { createUnifiedCheckout, MIN_CHECKOUT_USD as MIN_PAYMENT_USD, MIN_CHECKOUT_USD } from "./unified-checkout.js";

package/dist/billing/crypto/key-server-entry.js

@@ -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";
@@ -41,10 +43,13 @@ async function main() {
     const db = drizzle(pool, { schema });
     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,
         chargeStore,

package/dist/billing/crypto/key-server-webhook.d.ts

@@ -1,15 +1,19 @@
 import type { ILedger } from "../../credits/ledger.js";
 import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
 import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { CryptoChargeStatus } from "./types.js";
 export interface KeyServerWebhookPayload {
     chargeId: string;
     chain: string;
     address: string;
-    amountUsdCents: number;
+    /** @deprecated Use amountReceivedCents instead. Kept for one release cycle. */
+    amountUsdCents?: number;
+    amountReceivedCents?: number;
     status: string;
     txHash?: string;
     amountReceived?: string;
     confirmations?: number;
+    confirmationsRequired?: number;
 }
 export interface KeyServerWebhookDeps {
     chargeStore: ICryptoChargeRepository;
@@ -23,11 +27,20 @@ export interface KeyServerWebhookResult {
     tenant?: string;
     creditedCents?: number;
     reactivatedBots?: string[];
+    status?: CryptoChargeStatus;
+    confirmations?: number;
+    confirmationsRequired?: number;
 }
 /**
- * Process a payment confirmation from the crypto key server.
+ * Map legacy/watcher status strings to canonical CryptoChargeStatus.
+ * Accepts both old BTCPay-style ("Settled", "Processing") and new canonical ("confirmed", "partial").
+ */
+export declare function normalizeStatus(raw: string): CryptoChargeStatus;
+/**
+ * Process a payment webhook from the crypto key server.
  *
- * Credits the ledger when status is "confirmed".
- * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ * Idempotency: deduplicate by chargeId + status + confirmations so that
+ * multiple progress updates (0→1→2→...→6 confirmations) each get through,
+ * but exact duplicates are rejected.
  */
 export declare function handleKeyServerWebhook(deps: KeyServerWebhookDeps, payload: KeyServerWebhookPayload): Promise<KeyServerWebhookResult>;

package/dist/billing/crypto/key-server-webhook.js

@@ -1,32 +1,76 @@
 /**
- * Key Server webhook handler — processes payment confirmations from the
+ * Key Server webhook handler — processes payment events from the
  * centralized crypto key server.
  *
+ * Called on EVERY status update (not just terminal):
+ *   - "partial" / "Processing" → update progress, no credit
+ *   - "confirmed" / "Settled" → update progress + credit ledger
+ *   - "expired" / "failed" → update progress, no credit
+ *
  * Payload shape (from watcher-service.ts):
  * {
  *   chargeId: "btc:bc1q...",
  *   chain: "bitcoin",
  *   address: "bc1q...",
- *   amountUsdCents: 5000,
+ *   amountReceivedCents: 5000,
  *   status: "confirmed",
  *   txHash: "abc123...",
  *   amountReceived: "50000 sats",
- *   confirmations: 6
+ *   confirmations: 6,
+ *   confirmationsRequired: 6
  * }
  *
  * Replaces handleCryptoWebhook() for products using the key server.
  */
 import { Credit } from "../../credits/credit.js";
 /**
- * Process a payment confirmation from the crypto key server.
+ * Map legacy/watcher status strings to canonical CryptoChargeStatus.
+ * Accepts both old BTCPay-style ("Settled", "Processing") and new canonical ("confirmed", "partial").
+ */
+export function normalizeStatus(raw) {
+    switch (raw) {
+        case "confirmed":
+        case "Settled":
+        case "InvoiceSettled":
+            return "confirmed";
+        case "partial":
+        case "Processing":
+        case "InvoiceProcessing":
+        case "InvoiceReceivedPayment":
+            return "partial";
+        case "expired":
+        case "Expired":
+        case "InvoiceExpired":
+            return "expired";
+        case "failed":
+        case "Invalid":
+        case "InvoiceInvalid":
+            return "failed";
+        case "pending":
+        case "New":
+        case "InvoiceCreated":
+            return "pending";
+        default:
+            return "pending";
+    }
+}
+/**
+ * Process a payment webhook from the crypto key server.
  *
- * Credits the ledger when status is "confirmed".
- * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ * Idempotency: deduplicate by chargeId + status + confirmations so that
+ * multiple progress updates (0→1→2→...→6 confirmations) each get through,
+ * but exact duplicates are rejected.
  */
 export async function handleKeyServerWebhook(deps, payload) {
     const { chargeStore, creditLedger } = deps;
-    // Replay guard: deduplicate by chargeId
-    const dedupeKey = `ks:${payload.chargeId}`;
+    const status = normalizeStatus(payload.status);
+    const confirmations = payload.confirmations ?? 0;
+    const confirmationsRequired = payload.confirmationsRequired ?? 1;
+    // Support deprecated amountUsdCents field as fallback
+    const amountReceivedCents = payload.amountReceivedCents ?? payload.amountUsdCents ?? 0;
+    // Replay guard: deduplicate by chargeId + status + confirmations
+    // This allows multiple progress updates for the same charge
+    const dedupeKey = `ks:${payload.chargeId}:${status}:${confirmations}`;
     if (await deps.replayGuard.isDuplicate(dedupeKey, "crypto")) {
         return { handled: true, duplicate: true };
     }
@@ -35,14 +79,29 @@ export async function handleKeyServerWebhook(deps, payload) {
     if (!charge) {
         return { handled: false };
     }
-    if (payload.status === "confirmed") {
-        // Only settle when payment is confirmed
-        await chargeStore.updateStatus(payload.chargeId, "Settled", charge.token ?? undefined, payload.amountReceived);
+    // Always update progress on every webhook
+    await chargeStore.updateProgress(payload.chargeId, {
+        status,
+        amountReceivedCents,
+        confirmations,
+        confirmationsRequired,
+        txHash: payload.txHash,
+    });
+    // Also call deprecated updateStatus for backward compat with downstream consumers
+    const legacyStatusMap = {
+        pending: "New",
+        partial: "Processing",
+        confirmed: "Settled",
+        expired: "Expired",
+        failed: "Invalid",
+    };
+    await chargeStore.updateStatus(payload.chargeId, legacyStatusMap[status], charge.token ?? undefined, payload.amountReceived);
+    if (status === "confirmed") {
         // Idempotency: check ledger referenceId (atomic, same as BTCPay handler)
         const creditRef = `crypto:${payload.chargeId}`;
         if (await creditLedger.hasReferenceId(creditRef)) {
             await deps.replayGuard.markSeen(dedupeKey, "crypto");
-            return { handled: true, duplicate: true, tenant: charge.tenantId };
+            return { handled: true, duplicate: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
         }
         // Credit the original USD amount requested.
         // charge.amountUsdCents is integer cents. Credit.fromCents() → nanodollars.
@@ -64,10 +123,12 @@ export async function handleKeyServerWebhook(deps, payload) {
             tenant: charge.tenantId,
             creditedCents: charge.amountUsdCents,
             reactivatedBots,
+            status,
+            confirmations,
+            confirmationsRequired,
         };
     }
-    // Non-confirmed status — update status but don't settle or credit
-    await chargeStore.updateStatus(payload.chargeId, payload.status, charge.token ?? undefined, payload.amountReceived);
+    // Non-confirmed status — progress already updated above, no credit
     await deps.replayGuard.markSeen(dedupeKey, "crypto");
-    return { handled: true, tenant: charge.tenantId };
+    return { handled: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
 }

package/dist/billing/crypto/key-server.js

@@ -13,6 +13,7 @@ import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/sche
 import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
 import { deriveDepositAddress } from "./evm/address-gen.js";
 import { centsToNative } from "./oracle/convert.js";
+import { AssetNotSupportedError } from "./oracle/types.js";
 /**
  * Derive the next unused address for a chain.
  * Atomically increments next_index and records address in a single transaction.
@@ -120,14 +121,24 @@ export function createKeyServerApp(deps) {
         // Compute expected crypto amount in native base units.
         // Price is locked NOW — this is what the user must send.
         let expectedAmount;
-        if (method.oracleAddress) {
-            // Volatile asset (BTC, ETH, DOGE) — oracle-priced
-            const { priceCents } = await deps.oracle.getPrice(token);
-            expectedAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
+        const feedAddress = method.oracleAddress ? method.oracleAddress : 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);
         }
-        else {
-            // Stablecoin (1:1 USD) — e.g. $50 USDC = 50_000_000 base units (6 decimals)
-            expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+        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.message}` }, 503);
+            }
         }
         const referenceId = `${token.toLowerCase()}:${address.toLowerCase()}`;
         await deps.chargeStore.createStablecoinCharge({

package/dist/billing/crypto/oracle/__tests__/chainlink.test.js

@@ -22,7 +22,7 @@ describe("ChainlinkOracle", () => {
         const rpc = vi.fn().mockResolvedValue(encodeRoundData(350000000000n, nowSec));
         const oracle = new ChainlinkOracle({ rpcCall: rpc });
         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" },
@@ -34,14 +34,14 @@ describe("ChainlinkOracle", () => {
         const rpc = vi.fn().mockResolvedValue(encodeRoundData(6500000000000n, nowSec));
         const oracle = new ChainlinkOracle({ rpcCall: rpc });
         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 () => {
         // ETH at $3,456.78 → answer = 345_678_000_000
         const rpc = vi.fn().mockResolvedValue(encodeRoundData(345678000000n, nowSec));
         const oracle = new ChainlinkOracle({ rpcCall: rpc });
         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 () => {
         const staleTime = nowSec - 7200; // 2 hours ago
@@ -78,6 +78,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/dist/billing/crypto/oracle/__tests__/coingecko.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/crypto/oracle/__tests__/coingecko.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+import { CoinGeckoOracle } from "../coingecko.js";
+describe("CoinGeckoOracle", () => {
+    const mockFetch = (price) => 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) });
+        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, 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, 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) });
+        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 });
+        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 });
+        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 });
+        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 });
+        const result = await oracle.getPrice("LTC");
+        expect(result.priceMicros).toBe(92_450_000);
+        expect(fn).toHaveBeenCalledWith(expect.stringContaining("ids=litecoin"));
+    });
+});

package/dist/billing/crypto/oracle/__tests__/composite.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import { CompositeOracle } from "../composite.js";
+function mockOracle(priceMicros) {
+    return { getPrice: vi.fn().mockResolvedValue({ priceMicros, updatedAt: new Date() }) };
+}
+function failingOracle(msg = "no feed") {
+    return { getPrice: vi.fn().mockRejectedValue(new Error(msg)) };
+}
+describe("CompositeOracle", () => {
+    it("uses primary when feedAddress is provided and primary succeeds", async () => {
+        const primary = mockOracle(8_500_000);
+        const fallback = mockOracle(8_400_000);
+        const oracle = new CompositeOracle(primary, fallback);
+        const result = await oracle.getPrice("BTC", "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F");
+        expect(result.priceMicros).toBe(8_500_000);
+        expect(primary.getPrice).toHaveBeenCalledWith("BTC", "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F");
+        expect(fallback.getPrice).not.toHaveBeenCalled();
+    });
+    it("falls back when primary fails with feedAddress", async () => {
+        const primary = failingOracle("stale");
+        const fallback = mockOracle(8_400_000);
+        const oracle = new CompositeOracle(primary, fallback);
+        const result = await oracle.getPrice("BTC", "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F");
+        expect(result.priceMicros).toBe(8_400_000);
+    });
+    it("tries primary without feed, then falls back for unknown assets", async () => {
+        const primary = failingOracle("No price feed for asset: DOGE");
+        const fallback = mockOracle(17);
+        const oracle = new CompositeOracle(primary, fallback);
+        const result = await oracle.getPrice("DOGE");
+        expect(result.priceMicros).toBe(17);
+    });
+    it("uses primary built-in feeds for BTC/ETH without explicit feedAddress", async () => {
+        const primary = mockOracle(8_500_000);
+        const fallback = mockOracle(8_400_000);
+        const oracle = new CompositeOracle(primary, fallback);
+        const result = await oracle.getPrice("BTC");
+        expect(result.priceMicros).toBe(8_500_000);
+        expect(primary.getPrice).toHaveBeenCalledWith("BTC");
+        expect(fallback.getPrice).not.toHaveBeenCalled();
+    });
+    it("propagates fallback errors when both fail", async () => {
+        const primary = failingOracle("no chainlink");
+        const fallback = failingOracle("no coingecko");
+        const oracle = new CompositeOracle(primary, fallback);
+        await expect(oracle.getPrice("UNKNOWN")).rejects.toThrow("no coingecko");
+    });
+});

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

@@ -2,50 +2,60 @@ import { describe, expect, it } from "vitest";
 import { centsToNative, nativeToCents } from "../convert.js";
 describe("centsToNative", () => {
     it("converts $50 to ETH wei at $3,500", () => {
-        // 5000 cents × 10^18 / 350000 cents = 14285714285714285n wei
-        const wei = centsToNative(5000, 350_000, 18);
+        // 5000 cents × 10000 × 10^18 / 3_500_000_000 micros = 14285714285714285n wei
+        const wei = centsToNative(5000, 3_500_000_000, 18);
         expect(wei).toBe(14285714285714285n);
     });
     it("converts $50 to BTC sats at $65,000", () => {
-        // 5000 cents × 10^8 / 6500000 cents = 76923n sats
-        const sats = centsToNative(5000, 6_500_000, 8);
+        // 5000 cents × 10000 × 10^8 / 65_000_000_000 micros = 76923n sats
+        const sats = centsToNative(5000, 65_000_000_000, 8);
         expect(sats).toBe(76923n);
     });
+    it("converts $50 to DOGE at $0.094147", () => {
+        // 5000 cents × 10000 × 10^8 / 94_147 micros = 53_107_898_982n base units (531.08 DOGE)
+        const dogeUnits = centsToNative(5000, 94_147, 8);
+        expect(Number(dogeUnits) / 1e8).toBeCloseTo(531.08, 0);
+    });
+    it("converts $50 to LTC at $55.79", () => {
+        // 5000 cents × 10000 × 10^8 / 55_790_000 micros = 89_622_512n base units (0.896 LTC)
+        const ltcUnits = centsToNative(5000, 55_790_000, 8);
+        expect(Number(ltcUnits) / 1e8).toBeCloseTo(0.896, 2);
+    });
     it("converts $100 to ETH wei at $2,000", () => {
-        // 10000 cents × 10^18 / 200000 cents = 50000000000000000n wei (0.05 ETH)
-        const wei = centsToNative(10_000, 200_000, 18);
+        // 10000 cents × 10000 × 10^18 / 2_000_000_000 micros = 50_000_000_000_000_000n (0.05 ETH)
+        const wei = centsToNative(10_000, 2_000_000_000, 18);
         expect(wei).toBe(50000000000000000n);
     });
     it("rejects non-integer amountCents", () => {
-        expect(() => centsToNative(50.5, 350_000, 18)).toThrow("positive integer");
+        expect(() => centsToNative(50.5, 3_500_000_000, 18)).toThrow("positive integer");
     });
     it("rejects zero amountCents", () => {
-        expect(() => centsToNative(0, 350_000, 18)).toThrow("positive integer");
+        expect(() => centsToNative(0, 3_500_000_000, 18)).toThrow("positive integer");
     });
-    it("rejects zero priceCents", () => {
+    it("rejects zero priceMicros", () => {
         expect(() => centsToNative(5000, 0, 18)).toThrow("positive integer");
     });
     it("rejects negative decimals", () => {
-        expect(() => centsToNative(5000, 350_000, -1)).toThrow("non-negative integer");
+        expect(() => centsToNative(5000, 3_500_000_000, -1)).toThrow("non-negative integer");
     });
 });
 describe("nativeToCents", () => {
     it("converts ETH wei back to cents at $3,500", () => {
-        // 14285714285714285n wei × 350000 / 10^18 = 4999 cents (truncated)
-        const cents = nativeToCents(14285714285714285n, 350_000, 18);
-        expect(cents).toBe(4999); // truncation from integer division
+        // 14285714285714285n × 3_500_000_000 / (10000 × 10^18) = 4999 cents (truncated)
+        const cents = nativeToCents(14285714285714285n, 3_500_000_000, 18);
+        expect(cents).toBe(4999);
     });
     it("converts BTC sats back to cents at $65,000", () => {
-        // 76923n sats × 6500000 / 10^8 = 4999 cents (truncated)
-        const cents = nativeToCents(76923n, 6_500_000, 8);
+        // 76923n × 65_000_000_000 / (10000 × 10^8) = 4999 cents
+        const cents = nativeToCents(76923n, 65_000_000_000, 8);
         expect(cents).toBe(4999);
     });
     it("exact round-trip for clean division", () => {
         // 0.05 ETH at $2,000 = $100
-        const cents = nativeToCents(50000000000000000n, 200_000, 18);
+        const cents = nativeToCents(50000000000000000n, 2_000_000_000, 18);
         expect(cents).toBe(10_000); // $100.00
     });
     it("rejects negative rawAmount", () => {
-        expect(() => nativeToCents(-1n, 350_000, 18)).toThrow("non-negative");
+        expect(() => nativeToCents(-1n, 3_500_000_000, 18)).toThrow("non-negative");
     });
 });

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

@@ -4,17 +4,17 @@ describe("FixedPriceOracle", () => {
     it("returns default ETH price", async () => {
         const oracle = new FixedPriceOracle();
         const result = await oracle.getPrice("ETH");
-        expect(result.priceCents).toBe(350_000); // $3,500
+        expect(result.priceMicros).toBe(3_500_000_000); // $3,500
         expect(result.updatedAt).toBeInstanceOf(Date);
     });
     it("returns default BTC price", async () => {
         const oracle = new FixedPriceOracle();
         const result = await oracle.getPrice("BTC");
-        expect(result.priceCents).toBe(6_500_000); // $65,000
+        expect(result.priceMicros).toBe(65_000_000_000); // $65,000
     });
     it("accepts custom prices", async () => {
-        const oracle = new FixedPriceOracle({ ETH: 200_000, BTC: 5_000_000 });
-        expect((await oracle.getPrice("ETH")).priceCents).toBe(200_000);
-        expect((await oracle.getPrice("BTC")).priceCents).toBe(5_000_000);
+        const oracle = new FixedPriceOracle({ ETH: 2_000_000_000, BTC: 50_000_000_000 });
+        expect((await oracle.getPrice("ETH")).priceMicros).toBe(2_000_000_000);
+        expect((await oracle.getPrice("BTC")).priceMicros).toBe(50_000_000_000);
     });
 });

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

@@ -14,13 +14,13 @@ export interface ChainlinkOracleOpts {
  * No API key, no rate limits — just an RPC call to our own node.
  *
  * Chainlink USD feeds use 8 decimals. We convert to integer USD cents:
- *   priceCents = answer / 10^6  (i.e. answer / 10^8 * 100)
+ *   priceMicros = answer / 100  (i.e. answer / 10^8 * 10^6)
  */
 export declare class ChainlinkOracle implements IPriceOracle {
     private readonly rpc;
     private readonly feeds;
     private readonly maxStalenessMs;
     constructor(opts: ChainlinkOracleOpts);
-    getPrice(asset: PriceAsset): Promise<PriceResult>;
+    getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult>;
 }
 export {};

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

@@ -17,7 +17,7 @@ const DEFAULT_MAX_STALENESS_MS = 60 * 60 * 1000;
  * No API key, no rate limits — just an RPC call to our own node.
  *
  * Chainlink USD feeds use 8 decimals. We convert to integer USD cents:
- *   priceCents = answer / 10^6  (i.e. answer / 10^8 * 100)
+ *   priceMicros = answer / 100  (i.e. answer / 10^8 * 10^6)
  */
 export class ChainlinkOracle {
     rpc;
@@ -28,11 +28,11 @@ export class ChainlinkOracle {
         this.feeds = new Map(Object.entries({ ...FEED_ADDRESSES, ...opts.feedAddresses }));
         this.maxStalenessMs = opts.maxStalenessMs ?? DEFAULT_MAX_STALENESS_MS;
     }
-    async getPrice(asset) {
-        const feedAddress = this.feeds.get(asset);
-        if (!feedAddress)
+    async getPrice(asset, feedAddress) {
+        const resolvedFeed = feedAddress ?? this.feeds.get(asset);
+        if (!resolvedFeed)
             throw new Error(`No price feed for asset: ${asset}`);
-        const result = (await this.rpc("eth_call", [{ to: feedAddress, data: LATEST_ROUND_DATA }, "latest"]));
+        const result = (await this.rpc("eth_call", [{ to: resolvedFeed, data: LATEST_ROUND_DATA }, "latest"]));
         // ABI decode latestRoundData() return:
         //   [0]  roundId       (uint80)  — skip
         //   [1]  answer        (int256)  — price × 10^8
@@ -51,11 +51,12 @@ export class ChainlinkOracle {
         if (ageMs > this.maxStalenessMs) {
             throw new Error(`Price feed for ${asset} is stale (${Math.round(ageMs / 1000)}s old, max ${Math.round(this.maxStalenessMs / 1000)}s)`);
         }
-        // Chainlink USD feeds: 8 decimals. answer / 10^6 = cents (integer).
-        const priceCents = Number(answer / 1000000n);
-        if (priceCents <= 0) {
-            throw new Error(`Invalid price for ${asset}: ${priceCents} cents`);
+        // Chainlink USD feeds: 8 decimals. answer / 100 = microdollars (10^-6 USD).
+        // e.g. BTC at $70,315 → answer = 7_031_500_000_000 → 70_315_000_000 microdollars
+        const priceMicros = Number(answer / 100n);
+        if (priceMicros <= 0) {
+            throw new Error(`Invalid price for ${asset}: ${priceMicros} microdollars`);
         }
-        return { priceCents, updatedAt };
+        return { priceMicros, updatedAt };
     }
 }

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

@@ -0,0 +1,22 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+export interface CoinGeckoOracleOpts {
+    /** Override token→id mapping. */
+    tokenIds?: Record<string, string>;
+    /** Cache TTL in ms. Default: 60s. */
+    cacheTtlMs?: number;
+    /** Custom fetch function (for testing). */
+    fetchFn?: typeof fetch;
+}
+/**
+ * CoinGecko price oracle — free API, no key required.
+ * Used for assets without Chainlink on-chain feeds (DOGE, LTC).
+ * Caches prices to stay within rate limits.
+ */
+export declare class CoinGeckoOracle implements IPriceOracle {
+    private readonly ids;
+    private readonly cacheTtlMs;
+    private readonly fetchFn;
+    private readonly cache;
+    constructor(opts?: CoinGeckoOracleOpts);
+    getPrice(asset: PriceAsset, _feedAddress?: `0x${string}`): Promise<PriceResult>;
+}