@wopr-network/platform-core 1.20.0 → 1.22.0

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

@@ -0,0 +1,98 @@
+import { describe, expect, it, vi } from "vitest";
+import { settleEthPayment } from "../eth-settler.js";
+import type { EthPaymentEvent } from "../eth-watcher.js";
+
+function makeEvent(overrides: Partial<EthPaymentEvent> = {}): EthPaymentEvent {
+  return {
+    chain: "base",
+    from: "0xsender",
+    to: "0xdeposit",
+    valueWei: "14285714285714285",
+    amountUsdCents: 5000,
+    txHash: "0xabc123",
+    blockNumber: 100,
+    ...overrides,
+  };
+}
+
+function makeDeps(charge: { amountUsdCents: number; creditedAt: string | null } | null = null) {
+  return {
+    chargeStore: {
+      getByDepositAddress: vi.fn().mockResolvedValue(
+        charge
+          ? {
+              referenceId: "eth:base:0xdeposit",
+              tenantId: "t1",
+              amountUsdCents: charge.amountUsdCents,
+              creditedAt: charge.creditedAt,
+            }
+          : null,
+      ),
+      updateStatus: vi.fn().mockResolvedValue(undefined),
+      markCredited: vi.fn().mockResolvedValue(undefined),
+    },
+    creditLedger: {
+      credit: vi.fn().mockResolvedValue(undefined),
+      hasReferenceId: vi.fn().mockResolvedValue(false),
+    },
+  };
+}
+
+describe("settleEthPayment", () => {
+  it("returns Invalid for unknown deposit address", async () => {
+    const deps = makeDeps(null);
+    const result = await settleEthPayment(deps, makeEvent());
+    expect(result.handled).toBe(false);
+    expect(result.status).toBe("Invalid");
+  });
+
+  it("credits ledger for valid payment", async () => {
+    const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+    const result = await settleEthPayment(deps, makeEvent());
+
+    expect(result.handled).toBe(true);
+    expect(result.creditedCents).toBe(5000);
+    expect(deps.creditLedger.credit).toHaveBeenCalledOnce();
+    expect(deps.chargeStore.markCredited).toHaveBeenCalledOnce();
+  });
+
+  it("skips already-credited charge (charge-level idempotency)", async () => {
+    const deps = makeDeps({ amountUsdCents: 5000, creditedAt: "2026-01-01" });
+    const result = await settleEthPayment(deps, makeEvent());
+
+    expect(result.handled).toBe(true);
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("skips duplicate transfer (transfer-level idempotency)", async () => {
+    const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+    deps.creditLedger.hasReferenceId.mockResolvedValue(true);
+
+    const result = await settleEthPayment(deps, makeEvent());
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("rejects underpayment", async () => {
+    const deps = makeDeps({ amountUsdCents: 10000, creditedAt: null });
+    const result = await settleEthPayment(deps, makeEvent({ amountUsdCents: 5000 }));
+
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("credits charge amount, not transfer amount (overpayment safe)", async () => {
+    const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+    const result = await settleEthPayment(deps, makeEvent({ amountUsdCents: 10000 }));
+
+    expect(result.creditedCents).toBe(5000);
+  });
+
+  it("uses correct creditRef format", async () => {
+    const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+    await settleEthPayment(deps, makeEvent({ chain: "base", txHash: "0xdef" }));
+
+    expect(deps.creditLedger.hasReferenceId).toHaveBeenCalledWith("eth:base:0xdef");
+  });
+});

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

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from "vitest";
+import { EthWatcher } from "../eth-watcher.js";
+
+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() }) };
+
+describe("EthWatcher", () => {
+  it("detects native ETH transfer to watched address", async () => {
+    const onPayment = vi.fn();
+    const rpc = makeRpc({
+      eth_blockNumber: "0xb",
+      eth_getBlockByNumber: {
+        transactions: [
+          {
+            hash: "0xabc",
+            from: "0xsender",
+            to: "0xdeposit",
+            value: "0xDE0B6B3A7640000", // 1 ETH = 10^18 wei
+            blockNumber: "0xa",
+          },
+        ],
+      },
+    });
+
+    const watcher = new EthWatcher({
+      chain: "base",
+      rpcCall: rpc,
+      oracle: mockOracle,
+      fromBlock: 10,
+      onPayment,
+      watchedAddresses: ["0xDeposit"],
+    });
+
+    await watcher.poll();
+
+    expect(onPayment).toHaveBeenCalledOnce();
+    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.txHash).toBe("0xabc");
+  });
+
+  it("skips transactions not to watched addresses", async () => {
+    const onPayment = vi.fn();
+    const rpc = makeRpc({
+      eth_blockNumber: "0xb",
+      eth_getBlockByNumber: {
+        transactions: [{ hash: "0xabc", from: "0xa", to: "0xother", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
+      },
+    });
+
+    const watcher = new EthWatcher({
+      chain: "base",
+      rpcCall: rpc,
+      oracle: mockOracle,
+      fromBlock: 10,
+      onPayment,
+      watchedAddresses: ["0xDeposit"],
+    });
+
+    await watcher.poll();
+    expect(onPayment).not.toHaveBeenCalled();
+  });
+
+  it("skips zero-value transactions", async () => {
+    const onPayment = vi.fn();
+    const rpc = makeRpc({
+      eth_blockNumber: "0xb",
+      eth_getBlockByNumber: {
+        transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0x0", blockNumber: "0xa" }],
+      },
+    });
+
+    const watcher = new EthWatcher({
+      chain: "base",
+      rpcCall: rpc,
+      oracle: mockOracle,
+      fromBlock: 10,
+      onPayment,
+      watchedAddresses: ["0xDeposit"],
+    });
+
+    await watcher.poll();
+    expect(onPayment).not.toHaveBeenCalled();
+  });
+
+  it("does not double-process same txid", async () => {
+    const onPayment = vi.fn();
+    const rpc = makeRpc({
+      eth_blockNumber: "0xb",
+      eth_getBlockByNumber: {
+        transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
+      },
+    });
+
+    const watcher = new EthWatcher({
+      chain: "base",
+      rpcCall: rpc,
+      oracle: mockOracle,
+      fromBlock: 10,
+      onPayment,
+      watchedAddresses: ["0xDeposit"],
+    });
+
+    await watcher.poll();
+    // Reset cursor to re-scan same block
+    await watcher.poll();
+
+    expect(onPayment).toHaveBeenCalledOnce();
+  });
+
+  it("skips poll when no watched addresses", async () => {
+    const onPayment = vi.fn();
+    const rpc = vi.fn();
+
+    const watcher = new EthWatcher({
+      chain: "base",
+      rpcCall: rpc,
+      oracle: mockOracle,
+      fromBlock: 10,
+      onPayment,
+      watchedAddresses: [],
+    });
+
+    await watcher.poll();
+    expect(rpc).not.toHaveBeenCalled();
+  });
+
+  it("does not mark txid as processed if onPayment throws", async () => {
+    const onPayment = vi.fn().mockRejectedValueOnce(new Error("db fail")).mockResolvedValueOnce(undefined);
+    const rpc = makeRpc({
+      eth_blockNumber: "0xb",
+      eth_getBlockByNumber: {
+        transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
+      },
+    });
+
+    const watcher = new EthWatcher({
+      chain: "base",
+      rpcCall: rpc,
+      oracle: mockOracle,
+      fromBlock: 10,
+      onPayment,
+      watchedAddresses: ["0xDeposit"],
+    });
+
+    await expect(watcher.poll()).rejects.toThrow("db fail");
+
+    // Retry — should process the same tx again since it wasn't marked
+    await watcher.poll();
+    expect(onPayment).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -0,0 +1,84 @@
+import { Credit } from "../../../credits/credit.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import { centsToNative } from "../oracle/convert.js";
+import type { IPriceOracle } from "../oracle/types.js";
+import { deriveDepositAddress } from "./address-gen.js";
+import type { EvmChain } from "./types.js";
+
+export const MIN_ETH_USD = 10;
+
+export interface EthCheckoutDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+  oracle: IPriceOracle;
+  xpub: string;
+}
+
+export interface EthCheckoutOpts {
+  tenant: string;
+  amountUsd: number;
+  chain: EvmChain;
+}
+
+export interface EthCheckoutResult {
+  depositAddress: `0x${string}`;
+  amountUsd: number;
+  /** Expected ETH amount in wei (BigInt as string). */
+  expectedWei: string;
+  /** ETH price in USD cents at checkout time. */
+  priceCents: number;
+  chain: EvmChain;
+  referenceId: string;
+}
+
+/**
+ * Create an ETH checkout — derive deposit address, lock price, store charge.
+ *
+ * Uses the oracle to get live ETH/USD price and compute the expected
+ * deposit amount in wei. The charge stores amountUsdCents (not wei) —
+ * settlement always credits the USD amount, not the ETH value.
+ *
+ * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ */
+export async function createEthCheckout(deps: EthCheckoutDeps, opts: EthCheckoutOpts): Promise<EthCheckoutResult> {
+  if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_ETH_USD) {
+    throw new Error(`Minimum payment amount is $${MIN_ETH_USD}`);
+  }
+
+  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+  const { priceCents } = await deps.oracle.getPrice("ETH");
+  const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
+  const maxRetries = 3;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+    const depositAddress = deriveDepositAddress(deps.xpub, derivationIndex);
+    const referenceId = `eth:${opts.chain}:${depositAddress}`;
+
+    try {
+      await deps.chargeStore.createStablecoinCharge({
+        referenceId,
+        tenantId: opts.tenant,
+        amountUsdCents,
+        chain: opts.chain,
+        token: "ETH",
+        depositAddress,
+        derivationIndex,
+      });
+
+      return {
+        depositAddress,
+        amountUsd: opts.amountUsd,
+        expectedWei: expectedWei.toString(),
+        priceCents,
+        chain: opts.chain,
+        referenceId,
+      };
+    } catch (err: unknown) {
+      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;
+    }
+  }
+
+  throw new Error("Failed to claim derivation index after retries");
+}

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

@@ -0,0 +1,71 @@
+import { Credit } from "../../../credits/credit.js";
+import type { ILedger } from "../../../credits/ledger.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import type { CryptoWebhookResult } from "../types.js";
+import type { EthPaymentEvent } from "./eth-watcher.js";
+
+export interface EthSettlerDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getByDepositAddress" | "updateStatus" | "markCredited">;
+  creditLedger: Pick<ILedger, "credit" | "hasReferenceId">;
+  onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+
+/**
+ * Settle a native ETH payment — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as EVM stablecoin and BTC settlers:
+ *   1. Charge-level: charge.creditedAt != null → skip
+ *   2. Transfer-level: creditLedger.hasReferenceId → skip (atomic)
+ *   3. Advisory: chargeStore.markCredited
+ *
+ * Credits the CHARGE amount (not the ETH value) for overpayment safety.
+ *
+ * CRITICAL: charge.amountUsdCents is in USD cents (integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ */
+export async function settleEthPayment(deps: EthSettlerDeps, event: EthPaymentEvent): Promise<CryptoWebhookResult> {
+  const { chargeStore, creditLedger } = deps;
+
+  const charge = await chargeStore.getByDepositAddress(event.to.toLowerCase());
+  if (!charge) {
+    return { handled: false, status: "Invalid" };
+  }
+
+  await chargeStore.updateStatus(charge.referenceId, "Settled");
+
+  if (charge.creditedAt != null) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  const creditRef = `eth:${event.chain}:${event.txHash}`;
+  if (await creditLedger.hasReferenceId(creditRef)) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  if (event.amountUsdCents < charge.amountUsdCents) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  const creditCents = charge.amountUsdCents;
+  await creditLedger.credit(charge.tenantId, Credit.fromCents(creditCents), "purchase", {
+    description: `ETH credit purchase (${event.chain}, tx: ${event.txHash})`,
+    referenceId: creditRef,
+    fundingSource: "crypto",
+  });
+
+  await chargeStore.markCredited(charge.referenceId);
+
+  let reactivatedBots: string[] | undefined;
+  if (deps.onCreditsPurchased) {
+    reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger as ILedger);
+    if (reactivatedBots.length === 0) reactivatedBots = undefined;
+  }
+
+  return {
+    handled: true,
+    status: "Settled",
+    tenant: charge.tenantId,
+    creditedCents: creditCents,
+    reactivatedBots,
+  };
+}

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

@@ -0,0 +1,129 @@
+import { nativeToCents } from "../oracle/convert.js";
+import type { IPriceOracle } from "../oracle/types.js";
+import { getChainConfig } from "./config.js";
+import type { EvmChain } from "./types.js";
+
+type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+
+/** Event emitted when a native ETH deposit is detected and confirmed. */
+export interface EthPaymentEvent {
+  readonly chain: EvmChain;
+  readonly from: string;
+  readonly to: string;
+  /** Raw value in wei (BigInt as string for serialization). */
+  readonly valueWei: string;
+  /** USD cents equivalent at detection time (integer). */
+  readonly amountUsdCents: number;
+  readonly txHash: string;
+  readonly blockNumber: number;
+}
+
+export interface EthWatcherOpts {
+  chain: EvmChain;
+  rpcCall: RpcCall;
+  oracle: IPriceOracle;
+  fromBlock: number;
+  onPayment: (event: EthPaymentEvent) => void | Promise<void>;
+  watchedAddresses?: string[];
+}
+
+interface RpcTransaction {
+  hash: string;
+  from: string;
+  to: string | null;
+  value: string;
+  blockNumber: string;
+}
+
+/**
+ * Native ETH transfer watcher.
+ *
+ * Unlike the ERC-20 EvmWatcher which uses eth_getLogs for Transfer events,
+ * this scans blocks for transactions where `to` matches a watched deposit
+ * address and `value > 0`.
+ *
+ * Uses the price oracle to convert wei → USD cents at detection time.
+ */
+export class EthWatcher {
+  private _cursor: number;
+  private readonly chain: EvmChain;
+  private readonly rpc: RpcCall;
+  private readonly oracle: IPriceOracle;
+  private readonly onPayment: EthWatcherOpts["onPayment"];
+  private readonly confirmations: number;
+  private _watchedAddresses: Set<string>;
+  private readonly processedTxids = new Set<string>();
+
+  constructor(opts: EthWatcherOpts) {
+    this.chain = opts.chain;
+    this.rpc = opts.rpcCall;
+    this.oracle = opts.oracle;
+    this._cursor = opts.fromBlock;
+    this.onPayment = opts.onPayment;
+    this.confirmations = getChainConfig(opts.chain).confirmations;
+    this._watchedAddresses = new Set((opts.watchedAddresses ?? []).map((a) => a.toLowerCase()));
+  }
+
+  setWatchedAddresses(addresses: string[]): void {
+    this._watchedAddresses = new Set(addresses.map((a) => a.toLowerCase()));
+  }
+
+  get cursor(): number {
+    return this._cursor;
+  }
+
+  /**
+   * Poll for new native ETH transfers to watched addresses.
+   *
+   * Scans each confirmed block's transactions. Only processes txs
+   * where `to` is in the watched set and `value > 0`.
+   */
+  async poll(): Promise<void> {
+    if (this._watchedAddresses.size === 0) return;
+
+    const latestHex = (await this.rpc("eth_blockNumber", [])) as string;
+    const latest = Number.parseInt(latestHex, 16);
+    const confirmed = latest - this.confirmations;
+
+    if (confirmed < this._cursor) return;
+
+    const { priceCents } = await this.oracle.getPrice("ETH");
+
+    for (let blockNum = this._cursor; blockNum <= confirmed; blockNum++) {
+      const block = (await this.rpc("eth_getBlockByNumber", [`0x${blockNum.toString(16)}`, true])) as {
+        transactions: RpcTransaction[];
+      } | null;
+
+      if (!block) continue;
+
+      for (const tx of block.transactions) {
+        if (!tx.to) continue;
+        const to = tx.to.toLowerCase();
+        if (!this._watchedAddresses.has(to)) continue;
+
+        const valueWei = BigInt(tx.value);
+        if (valueWei === 0n) continue;
+
+        if (this.processedTxids.has(tx.hash)) continue;
+
+        const amountUsdCents = nativeToCents(valueWei, priceCents, 18);
+
+        const event: EthPaymentEvent = {
+          chain: this.chain,
+          from: tx.from.toLowerCase(),
+          to,
+          valueWei: valueWei.toString(),
+          amountUsdCents,
+          txHash: tx.hash,
+          blockNumber: blockNum,
+        };
+
+        await this.onPayment(event);
+        // Add to processed AFTER successful onPayment to avoid skipping on failure
+        this.processedTxids.add(tx.hash);
+      }
+    }
+
+    this._cursor = confirmed + 1;
+  }
+}

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

@@ -2,6 +2,12 @@ export { deriveDepositAddress, isValidXpub } from "./address-gen.js";
 export type { StablecoinCheckoutDeps, StablecoinCheckoutResult } from "./checkout.js";
 export { createStablecoinCheckout, MIN_STABLECOIN_USD } from "./checkout.js";
 export { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "./config.js";
+export type { EthCheckoutDeps, EthCheckoutOpts, EthCheckoutResult } from "./eth-checkout.js";
+export { createEthCheckout, MIN_ETH_USD } from "./eth-checkout.js";
+export type { EthSettlerDeps } from "./eth-settler.js";
+export { settleEthPayment } from "./eth-settler.js";
+export type { EthPaymentEvent, EthWatcherOpts } from "./eth-watcher.js";
+export { EthWatcher } from "./eth-watcher.js";
 export type { EvmSettlerDeps } from "./settler.js";
 export { settleEvmPayment } from "./settler.js";
 export type {

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

@@ -28,7 +28,7 @@ export async function settleEvmPayment(deps: EvmSettlerDeps, event: EvmPaymentEv
 
   const charge = await chargeStore.getByDepositAddress(event.to.toLowerCase());
   if (!charge) {
-    return { handled: false, status: "Settled" };
+    return { handled: false, status: "Invalid" };
   }
 
   // Update charge status to Settled.

package/src/billing/crypto/index.ts

@@ -5,6 +5,7 @@ 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);
+  });
+});