@zkp2p/pay-shared 0.0.1 → 1.0.0

package/dist/fees.js

@@ -0,0 +1,195 @@
+const TRANCHE_SCALE_BY_CURRENCY = {
+    USD: 2,
+    USDC: 2,
+};
+const USDC_DECIMALS = 6;
+const USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
+const BASIS_POINTS_SCALE = 10000n;
+function normalizeBoundary(raw) {
+    if (!Number.isFinite(raw) || raw < 0) {
+        throw new Error(`Invalid tranche boundary: ${raw}`);
+    }
+    const normalized = String(raw);
+    if (normalized.includes('e') || normalized.includes('E')) {
+        throw new Error(`Invalid tranche boundary: ${raw}`);
+    }
+    return normalized;
+}
+export function parseBoundaryUnits(raw, currency) {
+    const normalized = normalizeBoundary(raw);
+    if (!/^\d+(\.\d+)?$/.test(normalized)) {
+        throw new Error(`Invalid tranche boundary: ${raw}`);
+    }
+    const decimals = TRANCHE_SCALE_BY_CURRENCY[currency];
+    const [whole, fraction = ''] = normalized.split('.');
+    if (fraction.length > decimals) {
+        throw new Error(`Too many decimal places for ${currency}: ${raw}`);
+    }
+    return BigInt(whole) * 10n ** BigInt(decimals) + BigInt(fraction.padEnd(decimals, '0'));
+}
+export function parseLookupUnits(raw, currency) {
+    const normalized = raw.trim();
+    if (!/^\d+(\.\d+)?$/.test(normalized)) {
+        throw new Error(`Invalid lookup amount: ${raw}`);
+    }
+    const decimals = TRANCHE_SCALE_BY_CURRENCY[currency];
+    const [whole, fraction = ''] = normalized.split('.');
+    const keptFraction = fraction.slice(0, decimals).padEnd(decimals, '0');
+    const firstDiscardedDigit = fraction[decimals];
+    const shouldRoundUp = firstDiscardedDigit !== undefined && firstDiscardedDigit >= '5';
+    return BigInt(whole) * 10n ** BigInt(decimals)
+        + BigInt(keptFraction)
+        + (shouldRoundUp ? 1n : 0n);
+}
+export function parseUsdcUnits(raw) {
+    const normalized = raw.trim();
+    if (!/^\d+(\.\d+)?$/.test(normalized)) {
+        throw new Error(`Invalid USDC amount: ${raw}`);
+    }
+    const [whole, fraction = ''] = normalized.split('.');
+    if (fraction.length > USDC_DECIMALS) {
+        throw new Error(`USDC amount supports at most ${USDC_DECIMALS} decimals`);
+    }
+    return BigInt(whole) * USDC_SCALE + BigInt(fraction.padEnd(USDC_DECIMALS, '0'));
+}
+export function formatUsdcUnits(units) {
+    const whole = units / USDC_SCALE;
+    const fraction = units % USDC_SCALE;
+    return `${whole.toString()}.${fraction.toString().padStart(USDC_DECIMALS, '0')}`;
+}
+export function calculateGrossFromNetUnits(netAmountUnits, feeBps) {
+    if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps >= 10000) {
+        throw new Error(`Invalid referral fee bps: ${feeBps}`);
+    }
+    if (feeBps === 0) {
+        return netAmountUnits;
+    }
+    const denominator = BASIS_POINTS_SCALE - BigInt(feeBps);
+    const numerator = netAmountUnits * BASIS_POINTS_SCALE;
+    return (numerator + (denominator / 2n)) / denominator;
+}
+export function validateTranches(tranches, currency) {
+    if (tranches.length === 0) {
+        throw new Error('At least one tranche is required');
+    }
+    let expectedMinUnits = 0n;
+    tranches.forEach((tranche, index) => {
+        const minUnits = parseBoundaryUnits(tranche.min, currency);
+        if (minUnits !== expectedMinUnits) {
+            throw new Error('Tranche ranges must be contiguous and start at zero');
+        }
+        if (tranche.max === null) {
+            if (index !== tranches.length - 1) {
+                throw new Error('Only the final tranche may be open-ended');
+            }
+            return;
+        }
+        const maxUnits = parseBoundaryUnits(tranche.max, currency);
+        if (maxUnits < minUnits) {
+            throw new Error('Tranche max must be greater than or equal to min');
+        }
+        expectedMinUnits = maxUnits + 1n;
+    });
+    if (tranches[tranches.length - 1]?.max !== null) {
+        throw new Error('The final tranche must be open-ended');
+    }
+}
+export function getMatchingTrancheIndex(tranches, amount, currency) {
+    validateTranches(tranches, currency);
+    const amountUnits = parseLookupUnits(amount, currency);
+    const index = tranches.findIndex((tranche) => {
+        const minUnits = parseBoundaryUnits(tranche.min, currency);
+        const maxUnits = tranche.max === null ? null : parseBoundaryUnits(tranche.max, currency);
+        return amountUnits >= minUnits && (maxUnits === null || amountUnits <= maxUnits);
+    });
+    if (index === -1) {
+        throw new Error(`No tranche found for ${amount} ${currency}`);
+    }
+    return index;
+}
+export function resolveReferralFeeConfig(config, amountUsdc, options = {}) {
+    if (config.mode === 'default') {
+        return {
+            feeSource: 'default',
+            referralFeeBps: options.defaultFeeBps ?? 0,
+        };
+    }
+    if (config.mode === 'exempt') {
+        return {
+            feeSource: 'exempt',
+            referralFeeBps: 0,
+        };
+    }
+    if (config.mode === 'flat') {
+        return {
+            feeSource: 'merchant',
+            referralFeeBps: config.valueBps,
+        };
+    }
+    const matchedTrancheIndex = getMatchingTrancheIndex(config.tranches, amountUsdc, 'USDC');
+    return {
+        feeSource: 'merchant',
+        referralFeeBps: config.tranches[matchedTrancheIndex].value,
+    };
+}
+export function resolveExactTokenGrossAmountUsdc(config, requestedNetAmountUsdc, options = {}) {
+    const netAmountUnits = parseUsdcUnits(requestedNetAmountUsdc);
+    if (config.mode === 'default') {
+        return formatUsdcUnits(calculateGrossFromNetUnits(netAmountUnits, options.defaultFeeBps ?? 0));
+    }
+    if (config.mode === 'exempt') {
+        return formatUsdcUnits(netAmountUnits);
+    }
+    if (config.mode === 'flat') {
+        if (config.valueBps >= 10000) {
+            throw new Error('Referral fee must be less than 100% for exact-token requests');
+        }
+        return formatUsdcUnits(calculateGrossFromNetUnits(netAmountUnits, config.valueBps));
+    }
+    validateTranches(config.tranches, 'USDC');
+    let resolvedGrossAmountUnits = null;
+    let snappedGrossAmountUnits = null;
+    let smallestSnapFloorUnits = null;
+    for (const tranche of config.tranches) {
+        if (tranche.value >= 10000) {
+            continue;
+        }
+        const impliedGrossAmountUnits = calculateGrossFromNetUnits(netAmountUnits, tranche.value);
+        const impliedGrossLookupUnits = parseLookupUnits(formatUsdcUnits(impliedGrossAmountUnits), 'USDC');
+        const trancheMinUnits = parseBoundaryUnits(tranche.min, 'USDC');
+        if (impliedGrossLookupUnits < trancheMinUnits) {
+            if (smallestSnapFloorUnits === null || trancheMinUnits < smallestSnapFloorUnits) {
+                smallestSnapFloorUnits = trancheMinUnits;
+                snappedGrossAmountUnits = parseUsdcUnits(normalizeBoundary(tranche.min));
+            }
+            continue;
+        }
+        const trancheMaxUnits = tranche.max === null ? null : parseBoundaryUnits(tranche.max, 'USDC');
+        const isSelfConsistent = impliedGrossLookupUnits >= trancheMinUnits
+            && (trancheMaxUnits === null || impliedGrossLookupUnits <= trancheMaxUnits);
+        if (!isSelfConsistent) {
+            continue;
+        }
+        if (resolvedGrossAmountUnits === null || impliedGrossAmountUnits < resolvedGrossAmountUnits) {
+            resolvedGrossAmountUnits = impliedGrossAmountUnits;
+        }
+    }
+    if (resolvedGrossAmountUnits !== null) {
+        return formatUsdcUnits(resolvedGrossAmountUnits);
+    }
+    if (snappedGrossAmountUnits !== null) {
+        return formatUsdcUnits(snappedGrossAmountUnits);
+    }
+    throw new Error('Unable to resolve referral fee tranche for exact-token request amount');
+}
+export function resolveMaxFeeConfig(config, amountUsd) {
+    if (config.mode === 'flat') {
+        return {
+            maxFeePercentage: config.valuePercentage,
+        };
+    }
+    const matchedTrancheIndex = getMatchingTrancheIndex(config.tranches, amountUsd, 'USD');
+    return {
+        maxFeePercentage: config.tranches[matchedTrancheIndex].value,
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export * from './types.js';
 export * from './chains.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './fees.js';
+export * from './crypto.js';
+export * from './rails.js';
+export * from './bitcoin.js';

package/dist/index.js

@@ -1,2 +1,6 @@
 export * from './types.js';
 export * from './chains.js';
+export * from './fees.js';
+export * from './crypto.js';
+export * from './rails.js';
+export * from './bitcoin.js';

package/dist/rails.d.ts

@@ -0,0 +1,61 @@
+export declare enum SupportedRail {
+    VENMO = "venmo",
+    CASHAPP = "cashapp",
+    REVOLUT = "revolut",
+    ZELLE = "zelle",
+    PAYPAL = "paypal",
+    WISE = "wise",
+    MONZO = "monzo",
+    N26 = "n26",
+    CHIME = "chime",
+    RELAY_1 = "relay_1",
+    RELAY_10 = "relay_10",
+    RELAY_56 = "relay_56",
+    RELAY_137 = "relay_137",
+    RELAY_480 = "relay_480",
+    RELAY_999 = "relay_999",
+    RELAY_8453 = "relay_8453",
+    RELAY_42161 = "relay_42161",
+    RELAY_8253038 = "relay_8253038",
+    RELAY_728126428 = "relay_728126428",
+    RELAY_792703809 = "relay_792703809"
+}
+/**
+ * Canonical relay rails currently supported by zkp2p/pay.
+ *
+ * Chain id source reference:
+ * https://docs.relay.link/references/api/api_resources/supported-chains
+ */
+export declare enum SupportedRelayRail {
+    RELAY_1 = "relay_1",
+    RELAY_10 = "relay_10",
+    RELAY_56 = "relay_56",
+    RELAY_137 = "relay_137",
+    RELAY_480 = "relay_480",
+    RELAY_999 = "relay_999",
+    RELAY_8453 = "relay_8453",
+    RELAY_42161 = "relay_42161",
+    RELAY_8253038 = "relay_8253038",
+    RELAY_728126428 = "relay_728126428",
+    RELAY_792703809 = "relay_792703809"
+}
+export declare const DEFAULT_FIAT_RAILS: readonly SupportedRail[];
+export declare const SUPPORTED_RAILS: readonly SupportedRail[];
+export declare const SUPPORTED_RELAY_RAILS: readonly SupportedRelayRail[];
+/**
+ * Normalizes a rail string into a crypto chain id.
+ *
+ * Supports both:
+ * - legacy numeric format: "8453"
+ * - canonical relay format: "relay_8453"
+ */
+export declare function parseCryptoRailChainId(rail: string | null | undefined): number | null;
+export declare function isSupportedRail(rail: string): rail is SupportedRail;
+/** Returns true when the rail targets a crypto chain (legacy numeric or relay-prefixed format). */
+export declare function isCryptoRail(rail: string | null | undefined): boolean;
+/** Formats a chain id into the canonical relay rail string: `relay_<chainId>`. */
+export declare function formatRelayRail(chainId: number): string;
+/** Normalizes any crypto rail into canonical relay format (or null for non-crypto rails). */
+export declare function normalizeCryptoRail(rail: string | null | undefined): string | null;
+/** Formats a rail value for human-readable UI labels. */
+export declare function getRailDisplayName(rail: string | null | undefined): string;

package/dist/rails.js

@@ -0,0 +1,144 @@
+const RELAY_RAIL_PREFIX = 'relay_';
+export var SupportedRail;
+(function (SupportedRail) {
+    SupportedRail["VENMO"] = "venmo";
+    SupportedRail["CASHAPP"] = "cashapp";
+    SupportedRail["REVOLUT"] = "revolut";
+    SupportedRail["ZELLE"] = "zelle";
+    SupportedRail["PAYPAL"] = "paypal";
+    SupportedRail["WISE"] = "wise";
+    SupportedRail["MONZO"] = "monzo";
+    SupportedRail["N26"] = "n26";
+    SupportedRail["CHIME"] = "chime";
+    SupportedRail["RELAY_1"] = "relay_1";
+    SupportedRail["RELAY_10"] = "relay_10";
+    SupportedRail["RELAY_56"] = "relay_56";
+    SupportedRail["RELAY_137"] = "relay_137";
+    SupportedRail["RELAY_480"] = "relay_480";
+    SupportedRail["RELAY_999"] = "relay_999";
+    SupportedRail["RELAY_8453"] = "relay_8453";
+    SupportedRail["RELAY_42161"] = "relay_42161";
+    SupportedRail["RELAY_8253038"] = "relay_8253038";
+    SupportedRail["RELAY_728126428"] = "relay_728126428";
+    SupportedRail["RELAY_792703809"] = "relay_792703809";
+})(SupportedRail || (SupportedRail = {}));
+/**
+ * Canonical relay rails currently supported by zkp2p/pay.
+ *
+ * Chain id source reference:
+ * https://docs.relay.link/references/api/api_resources/supported-chains
+ */
+export var SupportedRelayRail;
+(function (SupportedRelayRail) {
+    SupportedRelayRail["RELAY_1"] = "relay_1";
+    SupportedRelayRail["RELAY_10"] = "relay_10";
+    SupportedRelayRail["RELAY_56"] = "relay_56";
+    SupportedRelayRail["RELAY_137"] = "relay_137";
+    SupportedRelayRail["RELAY_480"] = "relay_480";
+    SupportedRelayRail["RELAY_999"] = "relay_999";
+    SupportedRelayRail["RELAY_8453"] = "relay_8453";
+    SupportedRelayRail["RELAY_42161"] = "relay_42161";
+    SupportedRelayRail["RELAY_8253038"] = "relay_8253038";
+    SupportedRelayRail["RELAY_728126428"] = "relay_728126428";
+    SupportedRelayRail["RELAY_792703809"] = "relay_792703809";
+})(SupportedRelayRail || (SupportedRelayRail = {}));
+export const DEFAULT_FIAT_RAILS = [
+    SupportedRail.VENMO,
+    SupportedRail.CASHAPP,
+    SupportedRail.PAYPAL,
+    SupportedRail.WISE,
+];
+export const SUPPORTED_RAILS = Object.values(SupportedRail);
+export const SUPPORTED_RELAY_RAILS = Object.values(SupportedRelayRail);
+const SUPPORTED_RAIL_SET = new Set(SUPPORTED_RAILS);
+const FIAT_RAIL_DISPLAY_NAMES = {
+    [SupportedRail.VENMO]: 'Venmo',
+    [SupportedRail.CASHAPP]: 'Cash App',
+    [SupportedRail.REVOLUT]: 'Revolut',
+    [SupportedRail.ZELLE]: 'Zelle',
+    [SupportedRail.PAYPAL]: 'PayPal',
+    [SupportedRail.WISE]: 'Wise',
+    [SupportedRail.MONZO]: 'Monzo',
+    [SupportedRail.N26]: 'N26',
+    [SupportedRail.CHIME]: 'Chime',
+};
+const RELAY_CHAIN_DISPLAY_NAMES = {
+    1: 'Ethereum',
+    10: 'Optimism',
+    56: 'BNB Smart Chain',
+    137: 'Polygon',
+    480: 'World Chain',
+    999: 'Hyperliquid',
+    8453: 'Base',
+    42161: 'Arbitrum',
+    8253038: 'Bitcoin',
+    728126428: 'Tron',
+    792703809: 'Solana',
+};
+/**
+ * Normalizes a rail string into a crypto chain id.
+ *
+ * Supports both:
+ * - legacy numeric format: "8453"
+ * - canonical relay format: "relay_8453"
+ */
+export function parseCryptoRailChainId(rail) {
+    if (typeof rail !== 'string') {
+        return null;
+    }
+    const trimmed = rail.trim();
+    if (trimmed === '') {
+        return null;
+    }
+    const numericMatch = /^\d+$/.exec(trimmed);
+    if (numericMatch !== null) {
+        const parsed = Number(trimmed);
+        return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+    }
+    const prefixedMatch = /^relay_(\d+)$/i.exec(trimmed);
+    if (prefixedMatch === null) {
+        return null;
+    }
+    const parsed = Number(prefixedMatch[1]);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+export function isSupportedRail(rail) {
+    return SUPPORTED_RAIL_SET.has(rail);
+}
+/** Returns true when the rail targets a crypto chain (legacy numeric or relay-prefixed format). */
+export function isCryptoRail(rail) {
+    return parseCryptoRailChainId(rail) !== null;
+}
+/** Formats a chain id into the canonical relay rail string: `relay_<chainId>`. */
+export function formatRelayRail(chainId) {
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+        throw new Error(`Invalid chain id for relay rail: ${chainId}`);
+    }
+    return `${RELAY_RAIL_PREFIX}${chainId}`;
+}
+/** Normalizes any crypto rail into canonical relay format (or null for non-crypto rails). */
+export function normalizeCryptoRail(rail) {
+    const chainId = parseCryptoRailChainId(rail);
+    return chainId === null ? null : formatRelayRail(chainId);
+}
+/** Formats a rail value for human-readable UI labels. */
+export function getRailDisplayName(rail) {
+    if (typeof rail !== 'string') {
+        return 'Unknown';
+    }
+    const trimmed = rail.trim();
+    if (trimmed === '') {
+        return 'Unknown';
+    }
+    const normalized = trimmed.toLowerCase();
+    const fiatDisplayName = FIAT_RAIL_DISPLAY_NAMES[normalized];
+    if (fiatDisplayName) {
+        return fiatDisplayName;
+    }
+    const chainId = parseCryptoRailChainId(trimmed);
+    if (chainId !== null) {
+        const chainName = RELAY_CHAIN_DISPLAY_NAMES[chainId] ?? `Chain ${chainId}`;
+        return `Relay (${chainName})`;
+    }
+    return trimmed.toUpperCase();
+}