@wopr-network/platform-core 1.48.0 → 1.49.1

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

@@ -0,0 +1,67 @@
+import { AssetNotSupportedError } from "./types.js";
+/**
+ * Token symbol → CoinGecko API ID mapping.
+ * CoinGecko uses lowercase slugs, not ticker symbols.
+ */
+const COINGECKO_IDS = {
+    BTC: "bitcoin",
+    ETH: "ethereum",
+    DOGE: "dogecoin",
+    LTC: "litecoin",
+    SOL: "solana",
+    LINK: "chainlink",
+    UNI: "uniswap",
+    AERO: "aerodrome-finance",
+};
+/** Default cache TTL: 60 seconds. CoinGecko free tier allows 10-30 req/min. */
+const DEFAULT_CACHE_TTL_MS = 60_000;
+/**
+ * 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 class CoinGeckoOracle {
+    ids;
+    cacheTtlMs;
+    fetchFn;
+    cache = new Map();
+    constructor(opts = {}) {
+        this.ids = { ...COINGECKO_IDS, ...opts.tokenIds };
+        this.cacheTtlMs = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.fetchFn = opts.fetchFn ?? fetch;
+    }
+    async getPrice(asset, _feedAddress) {
+        const cached = this.cache.get(asset);
+        if (cached && Date.now() - cached.fetchedAt < this.cacheTtlMs) {
+            return { priceMicros: cached.priceMicros, updatedAt: cached.updatedAt };
+        }
+        const coinId = this.ids[asset];
+        if (!coinId)
+            throw new AssetNotSupportedError(asset);
+        const url = `https://api.coingecko.com/api/v3/simple/price?ids=${coinId}&vs_currencies=usd`;
+        try {
+            const res = await this.fetchFn(url);
+            if (!res.ok) {
+                throw new Error(`CoinGecko API error for ${asset}: ${res.status} ${res.statusText}`);
+            }
+            const data = (await res.json());
+            const usdPrice = data[coinId]?.usd;
+            if (usdPrice === undefined || usdPrice <= 0) {
+                throw new Error(`Invalid CoinGecko price for ${asset}: ${usdPrice}`);
+            }
+            const priceMicros = Math.round(usdPrice * 1_000_000);
+            const updatedAt = new Date();
+            this.cache.set(asset, { priceMicros, updatedAt, fetchedAt: Date.now() });
+            return { priceMicros, updatedAt };
+        }
+        catch (err) {
+            // Serve stale cache on transient failure (rate limit, network error).
+            // A slightly old price is better than rejecting the charge entirely.
+            const stale = this.cache.get(asset);
+            if (stale) {
+                return { priceMicros: stale.priceMicros, updatedAt: stale.updatedAt };
+            }
+            throw err;
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+/**
+ * Composite oracle — tries primary (Chainlink on-chain), falls back to secondary (CoinGecko).
+ *
+ * When a feedAddress is provided (from payment_methods.oracle_address), the primary
+ * oracle is used with that address. When no feed exists or the primary fails,
+ * the fallback oracle is consulted.
+ */
+export declare class CompositeOracle implements IPriceOracle {
+    private readonly primary;
+    private readonly fallback;
+    constructor(primary: IPriceOracle, fallback: IPriceOracle);
+    getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult>;
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,5 +1,21 @@
 /** BTCPay Server invoice states (Greenfield API v1). */
 export type CryptoPaymentState = "New" | "Processing" | "Expired" | "Invalid" | "Settled";
+/** Charge status for the UI-facing payment lifecycle. */
+export type CryptoChargeStatus = "pending" | "partial" | "confirmed" | "expired" | "failed";
+/** Full charge record for UI display — includes partial payment progress and confirmations. */
+export interface CryptoCharge {
+    id: string;
+    tenantId: string;
+    chain: string;
+    status: CryptoChargeStatus;
+    amountExpectedCents: number;
+    amountReceivedCents: number;
+    confirmations: number;
+    confirmationsRequired: number;
+    txHash?: string;
+    credited: boolean;
+    createdAt: Date;
+}
 /** Options for creating a crypto payment session. */
 export interface CryptoCheckoutOpts {
     /** Internal tenant ID. */

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

@@ -1,14 +1,7 @@
-import type { ICryptoChargeRepository } from "./charge-store.js";
-import type { IPriceOracle } from "./oracle/types.js";
-import type { PaymentMethodRecord } from "./payment-method-store.js";
+import type { CryptoServiceClient } from "./client.js";
 export declare const MIN_CHECKOUT_USD = 10;
 export interface UnifiedCheckoutDeps {
-    chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
-    oracle: IPriceOracle;
-    evmXpub: string;
-    btcXpub?: string;
-    /** UTXO network override (auto-detected from node in production). Default: "mainnet". */
-    utxoNetwork?: "mainnet" | "testnet" | "regtest";
+    cryptoService: CryptoServiceClient;
 }
 export interface UnifiedCheckoutResult {
     depositAddress: string;
@@ -18,20 +11,18 @@ export interface UnifiedCheckoutResult {
     token: string;
     chain: string;
     referenceId: string;
-    /** For volatile assets: price at checkout time (USD cents per unit). */
-    priceCents?: number;
+    /** For volatile assets: price at checkout time (microdollars per unit, 10^-6 USD). */
+    priceMicros?: number;
 }
 /**
- * Unified checkout — one entry point for all payment methods.
+ * Unified checkout — delegates to CryptoServiceClient.createCharge().
  *
- * Looks up the method record, routes by type:
- *   - erc20: derives EVM address, computes token amount (1:1 USD for stablecoins)
- *   - native (ETH): derives EVM address, oracle-priced
- *   - native (BTC): derives BTC address, oracle-priced
- *
- * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ * The pay server handles xpub management, address derivation, and charge
+ * creation. This function is a thin wrapper that validates the amount
+ * and maps the response to `UnifiedCheckoutResult`.
  */
-export declare function createUnifiedCheckout(deps: UnifiedCheckoutDeps, method: PaymentMethodRecord, opts: {
+export declare function createUnifiedCheckout(deps: UnifiedCheckoutDeps, chain: string, opts: {
     tenant: string;
     amountUsd: number;
+    callbackUrl?: string;
 }): Promise<UnifiedCheckoutResult>;

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

@@ -1,141 +1,27 @@
-import { Credit } from "../../credits/credit.js";
-import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
-import { deriveDepositAddress } from "./evm/address-gen.js";
-import { centsToNative } from "./oracle/convert.js";
 export const MIN_CHECKOUT_USD = 10;
 /**
- * Unified checkout — one entry point for all payment methods.
+ * Unified checkout — delegates to CryptoServiceClient.createCharge().
  *
- * Looks up the method record, routes by type:
- *   - erc20: derives EVM address, computes token amount (1:1 USD for stablecoins)
- *   - native (ETH): derives EVM address, oracle-priced
- *   - native (BTC): derives BTC address, oracle-priced
- *
- * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ * The pay server handles xpub management, address derivation, and charge
+ * creation. This function is a thin wrapper that validates the amount
+ * and maps the response to `UnifiedCheckoutResult`.
  */
-export async function createUnifiedCheckout(deps, method, opts) {
+export async function createUnifiedCheckout(deps, chain, opts) {
     if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_CHECKOUT_USD) {
         throw new Error(`Minimum payment amount is $${MIN_CHECKOUT_USD}`);
     }
-    const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
-    if (method.type === "erc20") {
-        return handleErc20(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-    }
-    if (method.type === "native" && method.chain === "base") {
-        return handleNativeEvm(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-    }
-    if (method.type === "native") {
-        return handleNativeUtxo(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-    }
-    throw new Error(`Unsupported payment method type: ${method.type}/${method.token}`);
-}
-async function handleErc20(deps, method, tenant, amountUsdCents, amountUsd) {
-    const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
-    return {
-        depositAddress,
-        displayAmount: `${amountUsd} ${method.token}`,
-        amountUsd,
-        token: method.token,
-        chain: method.chain,
-        referenceId: `erc20:${method.chain}:${depositAddress}`,
-    };
-}
-async function handleNativeEvm(deps, method, tenant, amountUsdCents, amountUsd) {
-    const { priceCents } = await deps.oracle.getPrice("ETH");
-    const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
-    const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
-    const divisor = BigInt("1000000000000000000");
-    const whole = expectedWei / divisor;
-    const frac = (expectedWei % divisor).toString().padStart(18, "0").slice(0, 6);
+    const result = await deps.cryptoService.createCharge({
+        chain,
+        amountUsd: opts.amountUsd,
+        callbackUrl: opts.callbackUrl,
+    });
     return {
-        depositAddress,
-        displayAmount: `${whole}.${frac} ETH`,
-        amountUsd,
-        token: "ETH",
-        chain: method.chain,
-        referenceId: `${method.type}:${method.chain}:${depositAddress}`,
-        priceCents,
+        depositAddress: result.address,
+        displayAmount: result.displayAmount ?? `${opts.amountUsd} ${result.token}`,
+        amountUsd: opts.amountUsd,
+        token: result.token,
+        chain: result.chain,
+        referenceId: result.chargeId,
+        priceMicros: result.priceMicros,
     };
 }
-/**
- * Handle native UTXO coins (BTC, LTC, DOGE, BCH, etc.).
- * Uses the xpub from the payment method record (DB-driven).
- * Derives bech32 addresses for BTC/LTC, Base58 P2PKH for DOGE.
- */
-async function handleNativeUtxo(deps, method, tenant, amountUsdCents, amountUsd) {
-    const xpub = method.xpub ?? deps.btcXpub;
-    if (!xpub)
-        throw new Error(`${method.token} payments not configured (no xpub)`);
-    const { priceCents } = await deps.oracle.getPrice(method.token);
-    const rawAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
-    const maxRetries = 3;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-        // Derive address by chain type
-        let depositAddress;
-        if (method.chain === "dogecoin") {
-            depositAddress = deriveP2pkhAddress(xpub, derivationIndex, "dogecoin");
-        }
-        else {
-            depositAddress = deriveAddress(xpub, derivationIndex, deps.utxoNetwork ?? "mainnet", method.chain);
-        }
-        const referenceId = `${method.token.toLowerCase()}:${depositAddress}`;
-        try {
-            await deps.chargeStore.createStablecoinCharge({
-                referenceId,
-                tenantId: tenant,
-                amountUsdCents,
-                chain: method.chain,
-                token: method.token,
-                depositAddress,
-                derivationIndex,
-            });
-            const divisor = 10 ** method.decimals;
-            const displayAmt = (Number(rawAmount) / divisor).toFixed(method.decimals);
-            return {
-                depositAddress,
-                displayAmount: `${displayAmt} ${method.token}`,
-                amountUsd,
-                token: method.token,
-                chain: method.chain,
-                referenceId,
-                priceCents,
-            };
-        }
-        catch (err) {
-            const code = err.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");
-}
-/** Derive an EVM deposit address and store the charge. Retries on unique conflict. */
-async function deriveAndStore(deps, method, tenant, amountUsdCents) {
-    const maxRetries = 3;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-        const depositAddress = deriveDepositAddress(deps.evmXpub, derivationIndex);
-        const referenceId = `${method.type}:${method.chain}:${depositAddress}`;
-        try {
-            await deps.chargeStore.createStablecoinCharge({
-                referenceId,
-                tenantId: tenant,
-                amountUsdCents,
-                chain: method.chain,
-                token: method.token,
-                depositAddress,
-                derivationIndex,
-            });
-            return depositAddress;
-        }
-        catch (err) {
-            const code = err.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/dist/billing/crypto/watcher-service.d.ts

@@ -4,8 +4,8 @@
  * Payment flow:
  *   1. Watcher detects payment → handlePayment()
  *   2. Accumulate native amount (supports partial payments)
- *   3. When totalReceived >= expectedAmount → settle + credit
- *   4. Every payment (partial or full) enqueues a webhook delivery
+ *   3. When totalReceived >= expectedAmount AND confirmations >= required → confirmed + credit
+ *   4. Every payment/confirmation change enqueues a webhook delivery
  *   5. Outbox processor retries failed deliveries with exponential backoff
  *
  * Amount comparison is ALWAYS in native crypto units (sats, wei, token base units).
@@ -30,4 +30,24 @@ export interface WatcherServiceOpts {
     /** Allowed callback URL prefixes. Default: ["https://"] — enforces HTTPS. */
     allowedCallbackPrefixes?: string[];
 }
+export interface PaymentPayload {
+    txHash: string;
+    confirmations: number;
+    confirmationsRequired: number;
+    amountReceivedCents: number;
+    [key: string]: unknown;
+}
+/**
+ * Handle a payment event. Accumulates partial payments in native units.
+ * Fires webhook on every payment/confirmation change with canonical statuses.
+ *
+ * 3-phase webhook lifecycle:
+ *   1. Tx first seen -> status: "partial", confirmations: 0
+ *   2. Each new block -> status: "partial", confirmations: current
+ *   3. Threshold reached + full payment -> status: "confirmed"
+ *
+ * @param nativeAmount — received amount in native base units (sats for BTC/DOGE, raw token units for ERC20).
+ *                        Pass "0" for confirmation-only updates (no new payment, just more confirmations).
+ */
+export declare function handlePayment(db: DrizzleDb, chargeStore: ICryptoChargeRepository, address: string, nativeAmount: string, payload: PaymentPayload, log: (msg: string, meta?: Record<string, unknown>) => void): Promise<void>;
 export declare function startWatchers(opts: WatcherServiceOpts): Promise<() => void>;