@zkp2p/pay-shared 0.0.2 → 2.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/fiatAmount.d.ts

@@ -0,0 +1,19 @@
+export interface DisplayedFiatAmountInput {
+    readonly feePayer: 'MERCHANT' | 'PAYEE';
+    readonly signalIntentAmountBaseUnits: string | null;
+    readonly conversionRateDecimal: string | null;
+    readonly remainingUsdcAmount: string;
+    readonly currencyPerUsdRate: string;
+    readonly paymentAmountFallback: string;
+}
+/**
+ * The exact fiat amount the buyer is instructed to pay, as a decimal string.
+ * BYTE-IDENTICAL to checkoutData.ts mapCheckoutPaymentToQuote (lines 336-351):
+ *   quotedFiatAmount (PAYEE ceil-cents, else null)
+ *     ?? (validRemaining&Rate ? (remaining*rate).toFixed(2) : paymentAmount)
+ * Always returns a string; the API caller passes it to fiatMinorUnitsFromDisplayedAmount,
+ * which returns null for an unusable "0"/malformed value so the API fails SAR closed.
+ */
+export declare function computeDisplayedFiatAmount(input: DisplayedFiatAmountInput): string;
+/** Parse a 2-decimal (or fewer) positive decimal string to integer minor units. Null if non-positive/malformed/>2dp. */
+export declare function fiatMinorUnitsFromDisplayedAmount(displayed: string): bigint | null;

package/dist/fiatAmount.js

@@ -0,0 +1,58 @@
+const USDC_SCALE = 1000000n;
+const RATE_SCALE = 10n ** 18n;
+const CENT_SCALE = 100n;
+const QUOTE_DENOMINATOR = USDC_SCALE * RATE_SCALE; // 1e6 * 1e18
+function parseDecimalToScaledUnits(value, decimals) {
+    const normalized = value.trim();
+    if (!/^\d+(\.\d+)?$/.test(normalized))
+        return null;
+    const [whole, fraction = ''] = normalized.split('.');
+    const base = 10n ** BigInt(decimals);
+    const scaledFraction = fraction.slice(0, decimals).padEnd(decimals, '0');
+    return BigInt(whole) * base + BigInt(scaledFraction);
+}
+function ceilCentsFromSignalIntent(amountBaseUnits, conversionRateDecimal) {
+    if (!/^\d+$/.test(amountBaseUnits))
+        return null;
+    const units = BigInt(amountBaseUnits);
+    const rate = parseDecimalToScaledUnits(conversionRateDecimal, 18);
+    if (rate === null || rate <= 0n || units <= 0n)
+        return null;
+    const numerator = units * rate * CENT_SCALE;
+    return (numerator + QUOTE_DENOMINATOR - 1n) / QUOTE_DENOMINATOR; // ceil
+}
+function centsToDecimalString(cents) {
+    const whole = cents / CENT_SCALE;
+    const fraction = (cents % CENT_SCALE).toString().padStart(2, '0');
+    return `${whole.toString()}.${fraction}`;
+}
+/**
+ * The exact fiat amount the buyer is instructed to pay, as a decimal string.
+ * BYTE-IDENTICAL to checkoutData.ts mapCheckoutPaymentToQuote (lines 336-351):
+ *   quotedFiatAmount (PAYEE ceil-cents, else null)
+ *     ?? (validRemaining&Rate ? (remaining*rate).toFixed(2) : paymentAmount)
+ * Always returns a string; the API caller passes it to fiatMinorUnitsFromDisplayedAmount,
+ * which returns null for an unusable "0"/malformed value so the API fails SAR closed.
+ */
+export function computeDisplayedFiatAmount(input) {
+    const quotedCents = input.feePayer === 'PAYEE' && input.signalIntentAmountBaseUnits !== null && input.conversionRateDecimal !== null
+        ? ceilCentsFromSignalIntent(input.signalIntentAmountBaseUnits, input.conversionRateDecimal)
+        : null;
+    if (quotedCents !== null)
+        return centsToDecimalString(quotedCents);
+    const remainingUsdc = Number(input.remainingUsdcAmount);
+    const rate = Number(input.currencyPerUsdRate);
+    if (Number.isFinite(remainingUsdc) && Number.isFinite(rate) && remainingUsdc > 0 && rate > 0) {
+        return (remainingUsdc * rate).toFixed(2);
+    }
+    return input.paymentAmountFallback;
+}
+/** Parse a 2-decimal (or fewer) positive decimal string to integer minor units. Null if non-positive/malformed/>2dp. */
+export function fiatMinorUnitsFromDisplayedAmount(displayed) {
+    const normalized = displayed.trim();
+    if (!/^\d+(\.\d{1,2})?$/.test(normalized))
+        return null;
+    const [whole, fraction = ''] = normalized.split('.');
+    const cents = BigInt(whole) * CENT_SCALE + BigInt(fraction.padEnd(2, '0'));
+    return cents > 0n ? cents : null;
+}

package/dist/index.d.ts

@@ -1,3 +1,10 @@
 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 './buyerTee.js';
+export * from './bitcoin.js';
+export * from './fiatAmount.js';
+export * from './paypalSarPhase.js';
+export * from './paypalSarVerify.js';

package/dist/index.js

@@ -1,2 +1,10 @@
 export * from './types.js';
 export * from './chains.js';
+export * from './fees.js';
+export * from './crypto.js';
+export * from './rails.js';
+export * from './buyerTee.js';
+export * from './bitcoin.js';
+export * from './fiatAmount.js';
+export * from './paypalSarPhase.js';
+export * from './paypalSarVerify.js';

package/dist/paypalSarPhase.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a name-mode SAR verify poll outcome is worth retrying. Only a "no receipt found yet" (404)
+ * may resolve on a later poll; every other terminal status is deterministic and must fail fast.
+ */
+export declare function isRetryableSarPollStatus(statusCode: number): boolean;

package/dist/paypalSarPhase.js

@@ -0,0 +1,8 @@
+const NO_RECEIPT_STATUS = 404; // SELLER_TXID_NOT_FOUND — the only status worth re-polling
+/**
+ * Whether a name-mode SAR verify poll outcome is worth retrying. Only a "no receipt found yet" (404)
+ * may resolve on a later poll; every other terminal status is deterministic and must fail fast.
+ */
+export function isRetryableSarPollStatus(statusCode) {
+    return statusCode === NO_RECEIPT_STATUS;
+}

package/dist/paypalSarVerify.d.ts

@@ -0,0 +1,41 @@
+export type SarAttemptOutcome = {
+    kind: 'success';
+    proofAttemptId: string;
+} | {
+    kind: 'unavailable';
+} | {
+    kind: 'error';
+    errorCode: string;
+    errorMessage: string;
+    statusCode: number;
+};
+export type SarVerifyResult = {
+    kind: 'success';
+    proofAttemptId: string;
+} | {
+    kind: 'unavailable';
+} | {
+    kind: 'error';
+    errorCode: string;
+    errorMessage: string;
+} | {
+    kind: 'aborted';
+};
+export interface RunPaypalSarNameVerifyDeps {
+    /** POST a name-mode attempt. attemptNumber is 1-based and increments per name poll. */
+    submitNameAttempt: (attemptNumber: number) => Promise<SarAttemptOutcome>;
+    sleep: (ms: number) => Promise<void>;
+    /** Re-checked after every await; returning false short-circuits to { kind: 'aborted' }. */
+    isMounted: () => boolean;
+    now: () => number;
+    retryIntervalMs: number;
+    retryDurationMs: number;
+}
+/**
+ * Name-only PayPal SAR verification.
+ * Polls name-mode verify (retrying only on retryable poll statuses until the deadline). Terminal
+ * name failures surface directly. Success / unavailable short-circuit. The caller maps the returned
+ * result to its own UI side effects; 'aborted' means the component unmounted and the caller should
+ * do nothing.
+ */
+export declare function runPaypalSarNameVerify(deps: RunPaypalSarNameVerifyDeps): Promise<SarVerifyResult>;

package/dist/paypalSarVerify.js

@@ -0,0 +1,31 @@
+import { isRetryableSarPollStatus } from './paypalSarPhase.js';
+/**
+ * Name-only PayPal SAR verification.
+ * Polls name-mode verify (retrying only on retryable poll statuses until the deadline). Terminal
+ * name failures surface directly. Success / unavailable short-circuit. The caller maps the returned
+ * result to its own UI side effects; 'aborted' means the component unmounted and the caller should
+ * do nothing.
+ */
+export async function runPaypalSarNameVerify(deps) {
+    const { submitNameAttempt, sleep, isMounted, now, retryIntervalMs, retryDurationMs } = deps;
+    const deadline = now() + retryDurationMs;
+    let attemptNumber = 1;
+    while (true) {
+        const outcome = await submitNameAttempt(attemptNumber);
+        if (!isMounted())
+            return { kind: 'aborted' };
+        if (outcome.kind === 'success')
+            return { kind: 'success', proofAttemptId: outcome.proofAttemptId };
+        if (outcome.kind === 'unavailable')
+            return { kind: 'unavailable' };
+        const deadlineReached = now() + retryIntervalMs > deadline;
+        if (isRetryableSarPollStatus(outcome.statusCode) && !deadlineReached) {
+            await sleep(retryIntervalMs);
+            if (!isMounted())
+                return { kind: 'aborted' };
+            attemptNumber += 1;
+            continue;
+        }
+        return { kind: 'error', errorCode: outcome.errorCode, errorMessage: outcome.errorMessage };
+    }
+}

package/dist/rails.d.ts

@@ -0,0 +1,137 @@
+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[];
+export declare const FIAT_SUPPORTED_RAILS: readonly ["venmo", "cashapp", "revolut", "wise", "zelle", "paypal", "monzo", "n26", "chime"];
+export type FiatSupportedRail = typeof FIAT_SUPPORTED_RAILS[number];
+export declare const PAYMENT_PLATFORM_LABELS: Record<string, string>;
+export declare const FIAT_RAIL_DISPLAY_NAMES: Record<FiatSupportedRail, string>;
+export declare const ORDER_SEARCH_MIN_QUERY_LENGTH = 3;
+export declare function railKeysForQuery(query: string): string[];
+export declare const RELAY_CHAIN_DISPLAY_NAMES: Record<number, string>;
+/**
+ * Surfaces crypto-settled orders for token, chain, and "crypto" prefix queries.
+ */
+export declare function isCryptoMethodQuery(query: string): boolean;
+/**
+ * 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;
+export declare function isFiatSupportedRail(rail: string): rail is FiatSupportedRail;
+/** Returns false for rails that remain recognized but are disabled at runtime. */
+export declare function isRailRuntimeEnabled(rail: string | null | undefined): boolean;
+/** Filters out globally disabled runtime rails while preserving caller ordering. */
+export declare function filterRuntimeEnabledRails<T extends string>(rails: readonly T[]): T[];
+/**
+ * Replaces the set of globally runtime-disabled fiat rails. Only EXACT base
+ * fiat rails are honored (e.g. `venmo`, `paypal`, `zelle`); rail variants
+ * (e.g. `zelle-chase`, or an env typo like `paypal-test`), crypto/relay rails,
+ * and unknown strings are ignored so a malformed env value cannot silently
+ * disable a live rail. Disable is base-granular: disabling `zelle` also
+ * disables its variants at check time (isRailRuntimeEnabled normalizes the
+ * checked rail to its base). Backend-only: the API applies the `DISABLED_RAILS`
+ * env at boot; the frontend never calls this, so its disabled set stays empty.
+ */
+export declare function setRuntimeDisabledFiatRails(rails: readonly string[]): void;
+/** Returns the currently runtime-disabled fiat rails (canonical base rails). */
+export declare function getRuntimeDisabledFiatRails(): string[];
+/** 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;
+/** Returns the canonical base fiat rail for base rails and supported variants such as `zelle-chase`. */
+export declare function normalizeFiatRail(rail: string | null | undefined): string | null;
+/**
+ * Fiat rails that support Seller Automated Release (SAR). Merchants in
+ * EXCLUSIVE_SAR mode may only offer these rails; every other fiat rail is
+ * force-disabled in the merchant and admin dashboards.
+ */
+export declare const SAR_SUPPORTED_FIAT_RAILS: readonly ["venmo", "cashapp", "wise", "paypal"];
+export type SarSupportedFiatRail = typeof SAR_SUPPORTED_FIAT_RAILS[number];
+/** Returns true when the fiat rail (incl. variants like `zelle-chase`) supports SAR. */
+export declare function isSarSupportedFiatRail(rail: string | null | undefined): boolean;
+/**
+ * Returns `rails` with non-SAR fiat rails removed, preserving crypto/relay rails,
+ * SAR-supported fiat rails, and original ordering. Used to keep an EXCLUSIVE_SAR
+ * merchant's `enabledRails` in sync with their quote preference: non-SAR fiat
+ * rails (e.g. `zelle`, `revolut`, incl. variants like `zelle-chase`) are dropped
+ * while crypto rails and SAR rails (venmo/cashapp/wise/paypal) are kept.
+ */
+export declare function filterRailsForExclusiveSar(rails: readonly string[]): string[];
+/** Canonical Zelle paymentMethodId -> attestation-service actionType suffix. */
+export declare const ZELLE_METHOD_ACTION_SUFFIX: Record<string, string>;
+/** Strict create-boundary set for Zelle method ids and transitional variant rails. */
+export declare const ZELLE_PAYMENT_METHOD_IDS: ReadonlySet<string>;
+/** Bank-qualified buyer TEE action types accepted for generic Zelle proofs. */
+export declare const ZELLE_BUYER_TEE_ACTION_TYPES: ReadonlySet<string>;
+export type AttestationRoute = {
+    readonly platform: string;
+    readonly actionType: string;
+};
+/**
+ * Resolves the attestation-service verifier route (`platform` + `actionType`)
+ * for a persisted `payment.rail` value.
+ *
+ * Zelle variants map to the new generic `zelle` platform with a bank-qualified
+ * actionType. Legacy bank-specific verifier routes are drain-only and should
+ * stay outside shared core. Non-Zelle fiat rails use the base rail as platform
+ * and `transfer_{rail}` as actionType. Unknown / crypto rails fall back to the
+ * raw trimmed rail so callers still surface a verifier mismatch via the
+ * attestation response rather than silently mis-routing.
+ */
+export declare function resolveAttestationRoute(rail: string | null | undefined): AttestationRoute;
+/** Canonical generic Zelle on-chain method hash: keccak256("zelle"), lowercase. */
+export declare const GENERIC_ZELLE_PAYMENT_METHOD_HASH = "0xf752c7d19698ecb0bb8988abf9b9a53a4c3657f3bc8850a6fb59fdf3e3ce8cd3";
+/** Case-insensitive check that a hash is the canonical generic Zelle on-chain method hash. */
+export declare function isGenericZellePaymentMethodHash(hash: string | null | undefined): boolean;
+/** True when the rail is Zelle (generic or a bank variant). */
+export declare function isZelleRail(rail: string | null | undefined): boolean;
+/** Formats a rail value for human-readable UI labels. */
+export declare function getRailDisplayName(rail: string | null | undefined): string;