@wopr-network/platform-core 1.19.0 → 1.21.0

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

@@ -20,17 +20,19 @@ function mockTransferLog(to: string, amount: bigint, blockNumber: number) {
 
 describe("EvmWatcher", () => {
   it("parses Transfer log into EvmPaymentEvent", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
     const events: { amountUsdCents: number; to: string }[] = [];
     const mockRpc = vi
       .fn()
-      .mockResolvedValueOnce(`0x${(102).toString(16)}`) // eth_blockNumber: block 102
-      .mockResolvedValueOnce([mockTransferLog(`0x${"cc".repeat(20)}`, 10_000_000n, 99)]); // eth_getLogs
+      .mockResolvedValueOnce(`0x${(102).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 99)]);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 99,
+      watchedAddresses: [toAddr],
       onPayment: (evt) => {
         events.push(evt);
       },
@@ -39,21 +41,22 @@ describe("EvmWatcher", () => {
     await watcher.poll();
 
     expect(events).toHaveLength(1);
-    expect(events[0].amountUsdCents).toBe(1000); // 10 USDC = $10 = 1000 cents
+    expect(events[0].amountUsdCents).toBe(1000);
     expect(events[0].to).toMatch(/^0x/);
   });
 
   it("advances cursor after processing", async () => {
     const mockRpc = vi
       .fn()
-      .mockResolvedValueOnce(`0x${(200).toString(16)}`) // block 200
-      .mockResolvedValueOnce([]); // no logs
+      .mockResolvedValueOnce(`0x${(200).toString(16)}`)
+      .mockResolvedValueOnce([]);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 100,
+      watchedAddresses: ["0xdeadbeef"],
       onPayment: vi.fn(),
     });
 
@@ -63,15 +66,14 @@ describe("EvmWatcher", () => {
 
   it("skips blocks not yet confirmed", async () => {
     const events: unknown[] = [];
-    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`); // current block: 50
+    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`);
 
-    // Base needs 1 confirmation, so confirmed = 50 - 1 = 49
-    // cursor starts at 50, so confirmed (49) < cursor (50) → no poll
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 50,
+      watchedAddresses: ["0xdeadbeef"],
       onPayment: (evt) => {
         events.push(evt);
       },
@@ -79,25 +81,24 @@ describe("EvmWatcher", () => {
 
     await watcher.poll();
     expect(events).toHaveLength(0);
-    // eth_getLogs should not even be called
     expect(mockRpc).toHaveBeenCalledTimes(1);
   });
 
   it("processes multiple logs in one poll", async () => {
+    const addr1 = `0x${"aa".repeat(20)}`;
+    const addr2 = `0x${"bb".repeat(20)}`;
     const events: { amountUsdCents: number }[] = [];
     const mockRpc = vi
       .fn()
-      .mockResolvedValueOnce(`0x${(110).toString(16)}`) // block 110
-      .mockResolvedValueOnce([
-        mockTransferLog(`0x${"aa".repeat(20)}`, 5_000_000n, 105), // $5
-        mockTransferLog(`0x${"bb".repeat(20)}`, 20_000_000n, 107), // $20
-      ]);
+      .mockResolvedValueOnce(`0x${(110).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(addr1, 5_000_000n, 105), mockTransferLog(addr2, 20_000_000n, 107)]);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 100,
+      watchedAddresses: [addr1, addr2],
       onPayment: (evt) => {
         events.push(evt);
       },
@@ -111,18 +112,34 @@ describe("EvmWatcher", () => {
   });
 
   it("does nothing when no new blocks", async () => {
-    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`); // block 99, confirmed = 98
+    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 100,
+      watchedAddresses: ["0xdeadbeef"],
       onPayment: vi.fn(),
     });
 
     await watcher.poll();
-    expect(watcher.cursor).toBe(100); // unchanged
-    expect(mockRpc).toHaveBeenCalledTimes(1); // only eth_blockNumber
+    expect(watcher.cursor).toBe(100);
+    expect(mockRpc).toHaveBeenCalledTimes(1);
+  });
+
+  it("early-returns when no watched addresses are set", async () => {
+    const mockRpc = vi.fn();
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 0,
+      onPayment: vi.fn(),
+    });
+
+    await watcher.poll();
+    expect(mockRpc).not.toHaveBeenCalled(); // no RPC calls at all
   });
 });

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

@@ -72,8 +72,10 @@ export async function createStablecoinCheckout(
     } catch (err: unknown) {
       // Unique constraint violation = another checkout claimed this index concurrently.
       // Retry with the next available index.
-      const msg = err instanceof Error ? err.message : "";
-      const isConflict = msg.includes("unique") || msg.includes("duplicate") || msg.includes("23505");
+      // PostgreSQL error code 23505 = unique_violation.
+      // Check structured code first, fall back to message for other drivers.
+      const code = (err as { code?: string }).code;
+      const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
       if (!isConflict || attempt === maxRetries) throw err;
     }
   }

package/src/billing/crypto/evm/config.ts

@@ -8,9 +8,31 @@ const CHAINS: Record<EvmChain, ChainConfig> = {
     blockTimeMs: 2000,
     chainId: 8453,
   },
+  ethereum: {
+    chain: "ethereum",
+    rpcUrl: process.env.EVM_RPC_ETHEREUM ?? "http://geth:8545",
+    confirmations: 12,
+    blockTimeMs: 12000,
+    chainId: 1,
+  },
+  arbitrum: {
+    chain: "arbitrum",
+    rpcUrl: process.env.EVM_RPC_ARBITRUM ?? "http://nitro:8547",
+    confirmations: 1,
+    blockTimeMs: 250,
+    chainId: 42161,
+  },
+  polygon: {
+    chain: "polygon",
+    rpcUrl: process.env.EVM_RPC_POLYGON ?? "http://bor:8545",
+    confirmations: 32,
+    blockTimeMs: 2000,
+    chainId: 137,
+  },
 };
 
 const TOKENS: Partial<Record<`${StablecoinToken}:${EvmChain}`, TokenConfig>> = {
+  // --- Base ---
   "USDC:base": {
     token: "USDC",
     chain: "base",
@@ -29,6 +51,57 @@ const TOKENS: Partial<Record<`${StablecoinToken}:${EvmChain}`, TokenConfig>> = {
     contractAddress: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
     decimals: 18,
   },
+  // --- Ethereum ---
+  "USDC:ethereum": {
+    token: "USDC",
+    chain: "ethereum",
+    contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    decimals: 6,
+  },
+  "USDT:ethereum": {
+    token: "USDT",
+    chain: "ethereum",
+    contractAddress: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    decimals: 6,
+  },
+  "DAI:ethereum": {
+    token: "DAI",
+    chain: "ethereum",
+    contractAddress: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    decimals: 18,
+  },
+  // --- Arbitrum ---
+  "USDC:arbitrum": {
+    token: "USDC",
+    chain: "arbitrum",
+    contractAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decimals: 6,
+  },
+  "USDT:arbitrum": {
+    token: "USDT",
+    chain: "arbitrum",
+    contractAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+    decimals: 6,
+  },
+  "DAI:arbitrum": {
+    token: "DAI",
+    chain: "arbitrum",
+    contractAddress: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
+    decimals: 18,
+  },
+  // --- Polygon ---
+  "USDC:polygon": {
+    token: "USDC",
+    chain: "polygon",
+    contractAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    decimals: 6,
+  },
+  "USDT:polygon": {
+    token: "USDT",
+    chain: "polygon",
+    contractAddress: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
+    decimals: 6,
+  },
 };
 
 export function getChainConfig(chain: EvmChain): ChainConfig {

package/src/billing/crypto/evm/types.ts

@@ -1,5 +1,5 @@
 /** Supported EVM chains. */
-export type EvmChain = "base";
+export type EvmChain = "base" | "ethereum" | "arbitrum" | "polygon";
 
 /** Supported stablecoin tokens. */
 export type StablecoinToken = "USDC" | "USDT" | "DAI";

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

@@ -61,6 +61,8 @@ export class EvmWatcher {
 
   /** Poll for new Transfer events. Call on an interval. */
   async poll(): Promise<void> {
+    if (this._watchedAddresses.length === 0) return; // nothing to watch
+
     const latestHex = (await this.rpc("eth_blockNumber", [])) as string;
     const latest = Number.parseInt(latestHex, 16);
     const confirmed = latest - this.confirmations;

package/src/billing/crypto/index.ts

@@ -1,9 +1,11 @@
-export type { CryptoChargeRecord, ICryptoChargeRepository, StablecoinChargeInput } from "./charge-store.js";
+export * from "./btc/index.js";
+export type { CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository } from "./charge-store.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
 export type { CryptoConfig } from "./client.js";
 export { BTCPayClient, loadCryptoConfig } from "./client.js";
 export * from "./evm/index.js";
+export * from "./oracle/index.js";
 export type {
   CryptoBillingConfig,
   CryptoCheckoutOpts,

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

@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from "vitest";
+import { ChainlinkOracle } from "../chainlink.js";
+
+/**
+ * Encode a mock latestRoundData() response.
+ * Chainlink returns 5 × 32-byte ABI-encoded words:
+ *   roundId, answer, startedAt, updatedAt, answeredInRound
+ */
+function encodeRoundData(answer: bigint, updatedAtSec: number): string {
+  const pad = (v: bigint) => v.toString(16).padStart(64, "0");
+  return (
+    "0x" +
+    pad(1n) + // roundId
+    pad(answer) + // answer (price × 10^8)
+    pad(BigInt(updatedAtSec)) + // startedAt
+    pad(BigInt(updatedAtSec)) + // updatedAt
+    pad(1n) // answeredInRound
+  );
+}
+
+describe("ChainlinkOracle", () => {
+  const nowSec = Math.floor(Date.now() / 1000);
+
+  it("decodes ETH/USD price from latestRoundData", async () => {
+    // ETH at $3,500.00 → answer = 3500 × 10^8 = 350_000_000_000
+    const rpc = vi.fn().mockResolvedValue(encodeRoundData(350_000_000_000n, nowSec));
+    const oracle = new ChainlinkOracle({ rpcCall: rpc });
+
+    const result = await oracle.getPrice("ETH");
+
+    expect(result.priceCents).toBe(350_000); // $3,500.00
+    expect(result.updatedAt).toBeInstanceOf(Date);
+    expect(rpc).toHaveBeenCalledWith("eth_call", [
+      { to: "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70", data: "0xfeaf968c" },
+      "latest",
+    ]);
+  });
+
+  it("decodes BTC/USD price from latestRoundData", async () => {
+    // BTC at $65,000.00 → answer = 65000 × 10^8 = 6_500_000_000_000
+    const rpc = vi.fn().mockResolvedValue(encodeRoundData(6_500_000_000_000n, nowSec));
+    const oracle = new ChainlinkOracle({ rpcCall: rpc });
+
+    const result = await oracle.getPrice("BTC");
+
+    expect(result.priceCents).toBe(6_500_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(345_678_000_000n, nowSec));
+    const oracle = new ChainlinkOracle({ rpcCall: rpc });
+
+    const result = await oracle.getPrice("ETH");
+
+    expect(result.priceCents).toBe(345_678); // $3,456.78
+  });
+
+  it("rejects stale prices", async () => {
+    const staleTime = nowSec - 7200; // 2 hours ago
+    const rpc = vi.fn().mockResolvedValue(encodeRoundData(350_000_000_000n, staleTime));
+    const oracle = new ChainlinkOracle({ rpcCall: rpc, maxStalenessMs: 3600_000 });
+
+    await expect(oracle.getPrice("ETH")).rejects.toThrow("stale");
+  });
+
+  it("rejects zero price", async () => {
+    const rpc = vi.fn().mockResolvedValue(encodeRoundData(0n, nowSec));
+    const oracle = new ChainlinkOracle({ rpcCall: rpc });
+
+    await expect(oracle.getPrice("ETH")).rejects.toThrow("Invalid price");
+  });
+
+  it("rejects malformed response", async () => {
+    const rpc = vi.fn().mockResolvedValue("0xdead");
+    const oracle = new ChainlinkOracle({ rpcCall: rpc });
+
+    await expect(oracle.getPrice("ETH")).rejects.toThrow("Malformed");
+  });
+
+  it("accepts custom feed addresses", async () => {
+    const customFeed = "0x1234567890abcdef1234567890abcdef12345678" as `0x${string}`;
+    const rpc = vi.fn().mockResolvedValue(encodeRoundData(350_000_000_000n, nowSec));
+    const oracle = new ChainlinkOracle({
+      rpcCall: rpc,
+      feedAddresses: { ETH: customFeed },
+    });
+
+    await oracle.getPrice("ETH");
+
+    expect(rpc).toHaveBeenCalledWith("eth_call", [{ to: customFeed, data: "0xfeaf968c" }, "latest"]);
+  });
+
+  it("respects custom staleness threshold", async () => {
+    const thirtyMinAgo = nowSec - 1800;
+    const rpc = vi.fn().mockResolvedValue(encodeRoundData(350_000_000_000n, thirtyMinAgo));
+
+    // 20-minute threshold → stale
+    const strict = new ChainlinkOracle({ rpcCall: rpc, maxStalenessMs: 20 * 60 * 1000 });
+    await expect(strict.getPrice("ETH")).rejects.toThrow("stale");
+
+    // 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);
+  });
+});

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

@@ -0,0 +1,62 @@
+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);
+    expect(wei).toBe(14_285_714_285_714_285n);
+  });
+
+  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);
+    expect(sats).toBe(76_923n);
+  });
+
+  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);
+    expect(wei).toBe(50_000_000_000_000_000n);
+  });
+
+  it("rejects non-integer amountCents", () => {
+    expect(() => centsToNative(50.5, 350_000, 18)).toThrow("positive integer");
+  });
+
+  it("rejects zero amountCents", () => {
+    expect(() => centsToNative(0, 350_000, 18)).toThrow("positive integer");
+  });
+
+  it("rejects zero priceCents", () => {
+    expect(() => centsToNative(5000, 0, 18)).toThrow("positive integer");
+  });
+
+  it("rejects negative decimals", () => {
+    expect(() => centsToNative(5000, 350_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(14_285_714_285_714_285n, 350_000, 18);
+    expect(cents).toBe(4999); // truncation from integer division
+  });
+
+  it("converts BTC sats back to cents at $65,000", () => {
+    // 76923n sats × 6500000 / 10^8 = 4999 cents (truncated)
+    const cents = nativeToCents(76_923n, 6_500_000, 8);
+    expect(cents).toBe(4999);
+  });
+
+  it("exact round-trip for clean division", () => {
+    // 0.05 ETH at $2,000 = $100
+    const cents = nativeToCents(50_000_000_000_000_000n, 200_000, 18);
+    expect(cents).toBe(10_000); // $100.00
+  });
+
+  it("rejects negative rawAmount", () => {
+    expect(() => nativeToCents(-1n, 350_000, 18)).toThrow("non-negative");
+  });
+});

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { FixedPriceOracle } from "../fixed.js";
+
+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.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
+  });
+
+  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);
+  });
+});

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

@@ -0,0 +1,85 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+
+/**
+ * Chainlink price feed addresses on Base mainnet.
+ * These are ERC-1967 proxy contracts — addresses are stable.
+ */
+const FEED_ADDRESSES: Record<PriceAsset, `0x${string}`> = {
+  ETH: "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70",
+  BTC: "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F",
+};
+
+/** Function selector for latestRoundData(). */
+const LATEST_ROUND_DATA = "0xfeaf968c";
+
+/** Default max staleness: 1 hour. */
+const DEFAULT_MAX_STALENESS_MS = 60 * 60 * 1000;
+
+type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+
+export interface ChainlinkOracleOpts {
+  rpcCall: RpcCall;
+  /** Override feed addresses (e.g. for testnet or Anvil forks). */
+  feedAddresses?: Partial<Record<PriceAsset, `0x${string}`>>;
+  /** Maximum age of price data before rejecting (ms). Default: 1 hour. */
+  maxStalenessMs?: number;
+}
+
+/**
+ * On-chain Chainlink price oracle.
+ *
+ * Reads latestRoundData() from Chainlink aggregator contracts via eth_call.
+ * 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)
+ */
+export class ChainlinkOracle implements IPriceOracle {
+  private readonly rpc: RpcCall;
+  private readonly feeds: Record<PriceAsset, `0x${string}`>;
+  private readonly maxStalenessMs: number;
+
+  constructor(opts: ChainlinkOracleOpts) {
+    this.rpc = opts.rpcCall;
+    this.feeds = { ...FEED_ADDRESSES, ...opts.feedAddresses };
+    this.maxStalenessMs = opts.maxStalenessMs ?? DEFAULT_MAX_STALENESS_MS;
+  }
+
+  async getPrice(asset: PriceAsset): Promise<PriceResult> {
+    const feedAddress = this.feeds[asset];
+    if (!feedAddress) throw new Error(`No price feed for asset: ${asset}`);
+
+    const result = (await this.rpc("eth_call", [{ to: feedAddress, data: LATEST_ROUND_DATA }, "latest"])) as string;
+
+    // ABI decode latestRoundData() return:
+    //   [0]  roundId       (uint80)  — skip
+    //   [1]  answer        (int256)  — price × 10^8
+    //   [2]  startedAt     (uint256) — skip
+    //   [3]  updatedAt     (uint256) — unix seconds
+    //   [4]  answeredInRound (uint80) — skip
+    const hex = result.slice(2);
+    if (hex.length < 320) {
+      throw new Error(`Malformed Chainlink response for ${asset}: expected 320 hex chars, got ${hex.length}`);
+    }
+
+    const answer = BigInt(`0x${hex.slice(64, 128)}`);
+    const updatedAtSec = Number(BigInt(`0x${hex.slice(192, 256)}`));
+    const updatedAt = new Date(updatedAtSec * 1000);
+
+    // Staleness guard.
+    const ageMs = Date.now() - updatedAt.getTime();
+    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 / 1_000_000n);
+    if (priceCents <= 0) {
+      throw new Error(`Invalid price for ${asset}: ${priceCents} cents`);
+    }
+
+    return { priceCents, updatedAt };
+  }
+}

package/src/billing/crypto/oracle/convert.ts

@@ -0,0 +1,38 @@
+/**
+ * Convert USD cents to native token amount using a price in cents.
+ *
+ * Formula: rawAmount = amountCents × 10^decimals / priceCents
+ *
+ * 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)
+ *
+ * Integer math only. No floating point.
+ */
+export function centsToNative(amountCents: number, priceCents: number, decimals: number): bigint {
+  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(decimals) || decimals < 0) {
+    throw new Error(`decimals must be a non-negative integer, got ${decimals}`);
+  }
+  return (BigInt(amountCents) * 10n ** BigInt(decimals)) / BigInt(priceCents);
+}
+
+/**
+ * Convert native token amount back to USD cents using a price in cents.
+ *
+ * Inverse of centsToNative. Truncates fractional cents.
+ *
+ * Integer math only.
+ */
+export function nativeToCents(rawAmount: bigint, priceCents: number, decimals: number): number {
+  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}`);
+  }
+  return Number((rawAmount * BigInt(priceCents)) / 10n ** BigInt(decimals));
+}

package/src/billing/crypto/oracle/fixed.ts

@@ -0,0 +1,23 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+
+/**
+ * Fixed-price oracle for testing and local dev (Anvil, regtest).
+ * Returns hardcoded prices — no RPC calls.
+ */
+export class FixedPriceOracle implements IPriceOracle {
+  private readonly prices: Record<string, number>;
+
+  constructor(prices: Partial<Record<PriceAsset, number>> = {}) {
+    this.prices = {
+      ETH: 350_000, // $3,500
+      BTC: 6_500_000, // $65,000
+      ...prices,
+    };
+  }
+
+  async getPrice(asset: PriceAsset): Promise<PriceResult> {
+    const priceCents = this.prices[asset];
+    if (priceCents === undefined) throw new Error(`No fixed price for ${asset}`);
+    return { priceCents, updatedAt: new Date() };
+  }
+}

package/src/billing/crypto/oracle/index.ts

@@ -0,0 +1,5 @@
+export type { ChainlinkOracleOpts } from "./chainlink.js";
+export { ChainlinkOracle } from "./chainlink.js";
+export { centsToNative, nativeToCents } from "./convert.js";
+export { FixedPriceOracle } from "./fixed.js";
+export type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";

package/src/billing/crypto/oracle/types.ts

@@ -0,0 +1,15 @@
+/** Assets with Chainlink price feeds. */
+export type PriceAsset = "ETH" | "BTC";
+
+/** Result from a price oracle query. */
+export interface PriceResult {
+  /** USD cents per 1 unit of asset (integer). */
+  priceCents: number;
+  /** When the price was last updated on-chain. */
+  updatedAt: Date;
+}
+
+/** Read-only price oracle. */
+export interface IPriceOracle {
+  getPrice(asset: PriceAsset): Promise<PriceResult>;
+}

package/src/db/schema/crypto.ts

@@ -31,7 +31,7 @@ export const cryptoCharges = pgTable(
     index("idx_crypto_charges_status").on(table.status),
     index("idx_crypto_charges_created").on(table.createdAt),
     index("idx_crypto_charges_deposit_address").on(table.depositAddress),
-    // uniqueIndex would be ideal but drizzle pgTable helper doesn't support it inline.
+    // Unique indexes use WHERE IS NOT NULL partial indexes (declared in migration SQL).
     // Enforced via migration: CREATE UNIQUE INDEX.
   ],
 );