@wopr-network/platform-core 1.19.0 → 1.20.0

package/dist/billing/crypto/evm/__tests__/watcher.test.js

@@ -17,35 +17,38 @@ function mockTransferLog(to, amount, blockNumber) {
 }
 describe("EvmWatcher", () => {
     it("parses Transfer log into EvmPaymentEvent", async () => {
+        const toAddr = `0x${"cc".repeat(20)}`;
         const events = [];
         const mockRpc = vi
             .fn()
-            .mockResolvedValueOnce(`0x${(102).toString(16)}`) // eth_blockNumber: block 102
-            .mockResolvedValueOnce([mockTransferLog(`0x${"cc".repeat(20)}`, 10000000n, 99)]); // eth_getLogs
+            .mockResolvedValueOnce(`0x${(102).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(toAddr, 10000000n, 99)]);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 99,
+            watchedAddresses: [toAddr],
             onPayment: (evt) => {
                 events.push(evt);
             },
         });
         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(),
         });
         await watcher.poll();
@@ -53,37 +56,35 @@ describe("EvmWatcher", () => {
     });
     it("skips blocks not yet confirmed", async () => {
         const events = [];
-        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`); // current block: 50
-        // Base needs 1 confirmation, so confirmed = 50 - 1 = 49
-        // cursor starts at 50, so confirmed (49) < cursor (50) → no poll
+        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 50,
+            watchedAddresses: ["0xdeadbeef"],
             onPayment: (evt) => {
                 events.push(evt);
             },
         });
         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 = [];
         const mockRpc = vi
             .fn()
-            .mockResolvedValueOnce(`0x${(110).toString(16)}`) // block 110
-            .mockResolvedValueOnce([
-            mockTransferLog(`0x${"aa".repeat(20)}`, 5000000n, 105), // $5
-            mockTransferLog(`0x${"bb".repeat(20)}`, 20000000n, 107), // $20
-        ]);
+            .mockResolvedValueOnce(`0x${(110).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(addr1, 5000000n, 105), mockTransferLog(addr2, 20000000n, 107)]);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 100,
+            watchedAddresses: [addr1, addr2],
             onPayment: (evt) => {
                 events.push(evt);
             },
@@ -94,16 +95,29 @@ describe("EvmWatcher", () => {
         expect(events[1].amountUsdCents).toBe(2000);
     });
     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/dist/billing/crypto/evm/checkout.js

@@ -47,8 +47,10 @@ export async function createStablecoinCheckout(deps, opts) {
         catch (err) {
             // 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.code;
+            const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
             if (!isConflict || attempt === maxRetries)
                 throw err;
         }

package/dist/billing/crypto/evm/config.js

@@ -6,8 +6,30 @@ const CHAINS = {
         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 = {
+    // --- Base ---
     "USDC:base": {
         token: "USDC",
         chain: "base",
@@ -26,6 +48,57 @@ const TOKENS = {
         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) {
     const cfg = CHAINS[chain];

package/dist/billing/crypto/evm/types.d.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";
 /** Chain configuration. */

package/dist/billing/crypto/evm/watcher.js

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

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

@@ -1,4 +1,5 @@
-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";

package/dist/billing/crypto/index.js

@@ -1,3 +1,4 @@
+export * from "./btc/index.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
 export { BTCPayClient, loadCryptoConfig } from "./client.js";

package/dist/db/schema/crypto.js

@@ -27,6 +27,6 @@ export const cryptoCharges = pgTable("crypto_charges", {
     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.
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -128,8 +128,10 @@
   },
   "packageManager": "pnpm@10.31.0",
   "dependencies": {
+    "@noble/hashes": "^2.0.1",
     "@scure/base": "^2.0.0",
     "@scure/bip32": "^2.0.1",
+    "@scure/bip39": "^2.0.1",
     "js-yaml": "^4.1.1",
     "viem": "^2.47.4",
     "yaml": "^2.8.2"

package/src/billing/crypto/btc/__tests__/address-gen.test.ts

@@ -0,0 +1,53 @@
+import { HDKey } from "@scure/bip32";
+import { describe, expect, it } from "vitest";
+import { deriveBtcAddress, deriveBtcTreasury } from "../address-gen.js";
+
+function makeTestXpub(): string {
+  const seed = new Uint8Array(32);
+  seed[0] = 1;
+  const master = HDKey.fromMasterSeed(seed);
+  return master.derive("m/44'/0'/0'").publicExtendedKey;
+}
+
+const TEST_XPUB = makeTestXpub();
+
+describe("deriveBtcAddress", () => {
+  it("derives a valid bech32 address", () => {
+    const addr = deriveBtcAddress(TEST_XPUB, 0);
+    expect(addr).toMatch(/^bc1q[a-z0-9]+$/);
+  });
+
+  it("derives different addresses for different indices", () => {
+    const a = deriveBtcAddress(TEST_XPUB, 0);
+    const b = deriveBtcAddress(TEST_XPUB, 1);
+    expect(a).not.toBe(b);
+  });
+
+  it("is deterministic", () => {
+    const a = deriveBtcAddress(TEST_XPUB, 42);
+    const b = deriveBtcAddress(TEST_XPUB, 42);
+    expect(a).toBe(b);
+  });
+
+  it("uses tb prefix for testnet/regtest", () => {
+    const addr = deriveBtcAddress(TEST_XPUB, 0, "testnet");
+    expect(addr).toMatch(/^tb1q[a-z0-9]+$/);
+  });
+
+  it("rejects negative index", () => {
+    expect(() => deriveBtcAddress(TEST_XPUB, -1)).toThrow("Invalid");
+  });
+});
+
+describe("deriveBtcTreasury", () => {
+  it("derives a valid bech32 address", () => {
+    const addr = deriveBtcTreasury(TEST_XPUB);
+    expect(addr).toMatch(/^bc1q[a-z0-9]+$/);
+  });
+
+  it("differs from deposit address at index 0", () => {
+    const deposit = deriveBtcAddress(TEST_XPUB, 0);
+    const treasury = deriveBtcTreasury(TEST_XPUB);
+    expect(deposit).not.toBe(treasury);
+  });
+});

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { centsToSats, satsToCents } from "../config.js";
+
+describe("centsToSats", () => {
+  it("converts $10 at $100k BTC", () => {
+    // $10 = 1000 cents, BTC at $100,000
+    // 10 / 100000 = 0.0001 BTC = 10000 sats
+    expect(centsToSats(1000, 100_000)).toBe(10000);
+  });
+
+  it("converts $100 at $50k BTC", () => {
+    // $100 = 10000 cents, BTC at $50,000
+    // 100 / 50000 = 0.002 BTC = 200000 sats
+    expect(centsToSats(10000, 50_000)).toBe(200000);
+  });
+});
+
+describe("satsToCents", () => {
+  it("converts 10000 sats at $100k BTC", () => {
+    // 10000 sats = 0.0001 BTC, at $100k = $10 = 1000 cents
+    expect(satsToCents(10000, 100_000)).toBe(1000);
+  });
+
+  it("rounds to nearest cent", () => {
+    // 15000 sats at $100k = 0.00015 BTC = $15 = 1500 cents
+    expect(satsToCents(15000, 100_000)).toBe(1500);
+  });
+});

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

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from "vitest";
+import { settleBtcPayment } from "../settler.js";
+import type { BtcPaymentEvent } from "../types.js";
+
+const mockEvent: BtcPaymentEvent = {
+  address: "bc1qtest",
+  txid: "abc123",
+  amountSats: 15000,
+  amountUsdCents: 1000,
+  confirmations: 6,
+};
+
+describe("settleBtcPayment", () => {
+  it("credits ledger when charge found", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "btc:test",
+          tenantId: "t1",
+          amountUsdCents: 1000,
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+      onCreditsPurchased: vi.fn().mockResolvedValue([]),
+    };
+
+    const result = await settleBtcPayment(deps as never, mockEvent);
+    expect(result.handled).toBe(true);
+    expect(result.creditedCents).toBe(1000);
+    expect(deps.creditLedger.credit).toHaveBeenCalledOnce();
+
+    // Verify Credit.fromCents was used
+    const creditArg = deps.creditLedger.credit.mock.calls[0][1];
+    expect(creditArg.toCentsRounded()).toBe(1000);
+  });
+
+  it("rejects double-credit on already-credited charge", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "btc:test",
+          tenantId: "t1",
+          amountUsdCents: 1000,
+          creditedAt: "2026-01-01",
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn(),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn(),
+      },
+    };
+
+    const result = await settleBtcPayment(deps as never, mockEvent);
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("rejects underpayment", async () => {
+    const underpaid = { ...mockEvent, amountUsdCents: 500 };
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "btc:test",
+          tenantId: "t1",
+          amountUsdCents: 1000,
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn(),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn(),
+      },
+    };
+
+    const result = await settleBtcPayment(deps as never, underpaid);
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("returns handled:false when no charge found", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue(null),
+        updateStatus: vi.fn(),
+        markCredited: vi.fn(),
+      },
+      creditLedger: { hasReferenceId: vi.fn(), credit: vi.fn() },
+    };
+
+    const result = await settleBtcPayment(deps as never, mockEvent);
+    expect(result.handled).toBe(false);
+  });
+});

package/src/billing/crypto/btc/address-gen.ts

@@ -0,0 +1,41 @@
+import { ripemd160 } from "@noble/hashes/legacy.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bech32 } from "@scure/base";
+import { HDKey } from "@scure/bip32";
+
+/**
+ * Derive a native segwit (bech32, bc1q...) BTC address from an xpub at a given index.
+ * Path: xpub / 0 / index (external chain).
+ * No private keys involved.
+ */
+export function deriveBtcAddress(
+  xpub: string,
+  index: number,
+  network: "mainnet" | "testnet" | "regtest" = "mainnet",
+): string {
+  if (!Number.isInteger(index) || index < 0) throw new Error(`Invalid derivation index: ${index}`);
+
+  const master = HDKey.fromExtendedKey(xpub);
+  const child = master.deriveChild(0).deriveChild(index);
+  if (!child.publicKey) throw new Error("Failed to derive public key");
+
+  // HASH160 = RIPEMD160(SHA256(compressedPubKey))
+  const hash160 = ripemd160(sha256(child.publicKey));
+
+  // Bech32 encode: witness version 0 + 20-byte hash
+  const prefix = network === "mainnet" ? "bc" : "tb";
+  const words = bech32.toWords(hash160);
+  return bech32.encode(prefix, [0, ...words]);
+}
+
+/** Derive the BTC treasury address (internal chain, index 0). */
+export function deriveBtcTreasury(xpub: string, network: "mainnet" | "testnet" | "regtest" = "mainnet"): string {
+  const master = HDKey.fromExtendedKey(xpub);
+  const child = master.deriveChild(1).deriveChild(0); // internal chain
+  if (!child.publicKey) throw new Error("Failed to derive public key");
+
+  const hash160 = ripemd160(sha256(child.publicKey));
+  const prefix = network === "mainnet" ? "bc" : "tb";
+  const words = bech32.toWords(hash160);
+  return bech32.encode(prefix, [0, ...words]);
+}

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

@@ -0,0 +1,61 @@
+import { Credit } from "../../../credits/credit.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import { deriveBtcAddress } from "./address-gen.js";
+import type { BtcCheckoutOpts } from "./types.js";
+
+export const MIN_BTC_USD = 10;
+
+export interface BtcCheckoutDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+  xpub: string;
+  network?: "mainnet" | "testnet" | "regtest";
+}
+
+export interface BtcCheckoutResult {
+  depositAddress: string;
+  amountUsd: number;
+  referenceId: string;
+}
+
+/**
+ * Create a BTC checkout — derive a unique deposit address, store the charge.
+ *
+ * Same pattern as stablecoin checkout: HD derivation + charge store + retry on conflict.
+ *
+ * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ */
+export async function createBtcCheckout(deps: BtcCheckoutDeps, opts: BtcCheckoutOpts): Promise<BtcCheckoutResult> {
+  if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_BTC_USD) {
+    throw new Error(`Minimum payment amount is $${MIN_BTC_USD}`);
+  }
+
+  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+  const network = deps.network ?? "mainnet";
+  const maxRetries = 3;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+    const depositAddress = deriveBtcAddress(deps.xpub, derivationIndex, network);
+    const referenceId = `btc:${depositAddress}`;
+
+    try {
+      await deps.chargeStore.createStablecoinCharge({
+        referenceId,
+        tenantId: opts.tenant,
+        amountUsdCents,
+        chain: "bitcoin",
+        token: "BTC",
+        depositAddress,
+        derivationIndex,
+      });
+
+      return { depositAddress, amountUsd: opts.amountUsd, 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/btc/config.ts

@@ -0,0 +1,33 @@
+import type { BitcoindConfig } from "./types.js";
+
+export function loadBitcoindConfig(): BitcoindConfig | null {
+  const rpcUrl = process.env.BITCOIND_RPC_URL;
+  const rpcUser = process.env.BITCOIND_RPC_USER;
+  const rpcPassword = process.env.BITCOIND_RPC_PASSWORD;
+  if (!rpcUrl || !rpcUser || !rpcPassword) return null;
+
+  const network = (process.env.BITCOIND_NETWORK ?? "mainnet") as BitcoindConfig["network"];
+  const confirmations = network === "regtest" ? 1 : 6;
+
+  return { rpcUrl, rpcUser, rpcPassword, network, confirmations };
+}
+
+/**
+ * Convert USD cents to satoshis given a BTC/USD price.
+ * Integer math only.
+ */
+export function centsToSats(cents: number, btcPriceUsd: number): number {
+  // 1 BTC = 100_000_000 sats, price is in dollars
+  // cents / 100 = dollars, dollars / btcPrice = BTC, BTC * 1e8 = sats
+  // To avoid float: (cents * 1e8) / (btcPrice * 100)
+  return Math.round((cents * 100_000_000) / (btcPriceUsd * 100));
+}
+
+/**
+ * Convert satoshis to USD cents given a BTC/USD price.
+ * Integer math only (rounds to nearest cent).
+ */
+export function satsToCents(sats: number, btcPriceUsd: number): number {
+  // sats / 1e8 = BTC, BTC * btcPrice = dollars, dollars * 100 = cents
+  return Math.round((sats * btcPriceUsd * 100) / 100_000_000);
+}

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

@@ -0,0 +1,9 @@
+export { deriveBtcAddress, deriveBtcTreasury } from "./address-gen.js";
+export type { BtcCheckoutDeps, BtcCheckoutResult } from "./checkout.js";
+export { createBtcCheckout, MIN_BTC_USD } from "./checkout.js";
+export { centsToSats, loadBitcoindConfig, satsToCents } from "./config.js";
+export type { BtcSettlerDeps } from "./settler.js";
+export { settleBtcPayment } from "./settler.js";
+export type { BitcoindConfig, BtcCheckoutOpts, BtcPaymentEvent } from "./types.js";
+export type { BtcWatcherOpts } from "./watcher.js";
+export { BtcWatcher, createBitcoindRpc } from "./watcher.js";