@zkp2p/pay-shared 0.0.2 → 2.0.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 ZKP2P
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary and confidential.
+Unauthorized copying, modification, distribution, sublicensing, or use of the Software, via any medium, is strictly prohibited without prior written permission from ZKP2P.

package/README.md

@@ -9,13 +9,18 @@ Shared TypeScript types, enums, and chain utilities used by ZKP2P Pay API, SDK,
 ## Install
 
 ```bash
-npm install @zkp2p/pay-shared
+npm install @zkp2p/pay-shared@2.0.0
 ```
 
+## Published artifacts
+
+- Includes compiled ESM JavaScript and `.d.ts` type declarations.
+- Does not publish declaration maps (`.d.ts.map`) or JavaScript source maps (`.js.map`).
+
 ## What This Package Includes
 
-- Checkout/session/order types (`CreateSessionRequest`, `CheckoutSession`, `Order`, `Quote`, etc.)
-- Canonical constants (`PaymentPlatform`, `CheckoutMode`, `SessionStatus`, `OrderStatus`, `OrderErrorCode`)
+- Checkout API types (`CreateOrderRequest`, `CheckoutOrder`, `CheckoutPayment`, `CheckoutAggregate`, etc.)
+- Canonical constants (`PaymentPlatform`, `FeePayer`, `CheckoutOrderStatus`, `CheckoutPaymentStatus`, `OrderErrorCode`)
 - Merchant model types and environment constants (`Merchant`, `MerchantEnvironment`)
 - Central chain/token helpers for supported destination chains and token aliases
 
@@ -24,30 +29,28 @@ npm install @zkp2p/pay-shared
 ### Shared API Types
 
 ```ts
-import type { CreateSessionRequest, CheckoutSession } from '@zkp2p/pay-shared';
+import type { CreateOrderRequest, CheckoutOrder } from '@zkp2p/pay-shared';
 
-const request: CreateSessionRequest = {
-  merchantId: '<merchant-id>',
-  checkoutMode: 'exact-token',
-  amountUsdc: '25.00',
+const request: CreateOrderRequest = {
+  requestedUsdcAmount: '25.00',
   destinationChainId: 8453,
   destinationToken: 'USDC',
-  recipientAddress: '0xYourRecipientAddress',
+  destinationAddress: '0xYourRecipientAddress',
 };
 
-function readSession(session: CheckoutSession) {
-  console.log(session.status, session.amountUsdc, session.netAmountUsdc);
+function readOrder(order: CheckoutOrder) {
+  console.log(order.status, order.requestedUsdcAmount, order.remainingUsdcAmount);
 }
 ```
 
 ### Constants and Enums
 
 ```ts
-import { CheckoutMode, PaymentPlatform, SessionStatus } from '@zkp2p/pay-shared';
+import { FeePayer, PaymentPlatform, CheckoutOrderStatus } from '@zkp2p/pay-shared';
 
-console.log(CheckoutMode.EXACT_TOKEN); // "exact-token"
+console.log(FeePayer.MERCHANT); // "MERCHANT"
 console.log(PaymentPlatform.VENMO); // "venmo"
-console.log(SessionStatus.ACTIVE); // "ACTIVE"
+console.log(CheckoutOrderStatus.CREATED); // "CREATED"
 ```
 
 ### Chain and Token Utilities
@@ -63,7 +66,7 @@ import {
 
 const chainId = parseSupportedChainSelection('polygon'); // 137
 const usdc = resolveDestinationTokenAddress('USDC', 137); // Chain-specific USDC address
-const supportedAliases = getSupportedDestinationTokenAliasesForChain(BASE_CHAIN_ID); // ["USDC"]
+const supportedAliases = getSupportedDestinationTokenAliasesForChain(BASE_CHAIN_ID); // ["USDC", "USDT"]
 
 console.log(getSupportedChainIds(), chainId, usdc, supportedAliases);
 ```
@@ -72,20 +75,21 @@ console.log(getSupportedChainIds(), chainId, usdc, supportedAliases);
 
 Core type exports:
 
-- `CreateSessionRequest`
-- `CreateSessionResponse`
-- `CheckoutSession`
-- `Order`
-- `Quote`
-- `ProofAttempt`
-- `Merchant`
-- `BridgeInfo`
+- `CreateOrderRequest`
+- `CreateOrderResponse`
+- `CreatePaymentRequest`
+- `CheckoutOrder`
+- `CheckoutPayment`
+- `CheckoutAggregate`
+- `CheckoutQuotes`
+- `MerchantProfile`
 
 Core constants:
 
 - `PaymentPlatform`
-- `CheckoutMode`
-- `SessionStatus`
+- `FeePayer`
+- `CheckoutOrderStatus`
+- `CheckoutPaymentStatus`
 - `OrderStatus`
 - `ProofAttemptStatus`
 - `OrderErrorCode`
@@ -108,5 +112,5 @@ Chain constants and helpers:
 ## Notes
 
 - Amount fields are strings to preserve precision across APIs and clients.
-- `CheckoutSession.netAmountUsdc` represents the merchant net amount and may fall back to gross `amountUsdc` when fee configuration is unavailable.
+- Canonical order/payment amounts are available on `CheckoutOrder` and `CheckoutPayment` (for example `requestedUsdcAmount`, `remainingUsdcAmount`, `netSettledUsdcAmount`).
 - This package is ESM-only.

package/dist/bitcoin.d.ts

@@ -0,0 +1 @@
+export declare function isValidBitcoinAddress(value: string): boolean;

package/dist/bitcoin.js

@@ -0,0 +1,13 @@
+const BITCOIN_BASE58_ADDRESS_REGEX = /^[13][1-9A-HJ-NP-Za-km-z]{25,34}$/;
+const BITCOIN_BECH32_ADDRESS_REGEX = /^(bc1)[ac-hj-np-z02-9]{11,71}$/i;
+export function isValidBitcoinAddress(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (trimmed.toLowerCase().startsWith('bc1')) {
+        const isUniformCase = trimmed === trimmed.toLowerCase() || trimmed === trimmed.toUpperCase();
+        return isUniformCase && BITCOIN_BECH32_ADDRESS_REGEX.test(trimmed);
+    }
+    return BITCOIN_BASE58_ADDRESS_REGEX.test(trimmed);
+}

package/dist/buyerTee.d.ts

@@ -0,0 +1,4 @@
+export declare const ProofMode: {
+    readonly BUYER_TEE: "buyerTee";
+};
+export type ProofMode = typeof ProofMode[keyof typeof ProofMode];

package/dist/buyerTee.js

@@ -0,0 +1,3 @@
+export const ProofMode = {
+    BUYER_TEE: 'buyerTee',
+};

package/dist/chains.d.ts

@@ -5,16 +5,16 @@
  * Import this module instead of duplicating chain configs in each app.
  */
 export declare const BASE_CHAIN_ID = 8453;
+export declare const ETHEREUM_CHAIN_ID = 1;
 export declare const HYPEREVM_CHAIN_ID = 999;
-export declare const SOLANA_CHAIN_ID = 34268394551451;
+export declare const SOLANA_CHAIN_ID = 792703809;
 export declare const SUPPORTED_DESTINATION_TOKEN_ALIASES: readonly ["USDC", "USDT"];
 export type DestinationTokenAlias = (typeof SUPPORTED_DESTINATION_TOKEN_ALIASES)[number];
 export declare const DEFAULT_DESTINATION_TOKEN_ALIAS: DestinationTokenAlias;
 /**
  * Chain configuration interface.
  *
- * Note: We don't store spokePoolAddress for each chain because bridging
- * always originates from Base, and the hook contract handles the Base SpokePool.
+ * Bridging always originates from Base settlement and is routed through Relay.
  */
 export interface ChainConfig {
     chainId: number;
@@ -76,6 +76,21 @@ export declare function getUsdcAddress(chainId: number): string | undefined;
  * - fallback: return token string as provided (for explicit token addresses)
  */
 export declare function resolveDestinationTokenAddress(destinationToken: string, destinationChainId: number): string | null;
+/**
+ * Check whether the final payout destination is native Base USDC.
+ * Any other token or chain requires a Relay / Privy payout conversion step.
+ */
+export declare function isBaseUsdcDestination(destinationChainId: number | bigint | null | undefined, destinationToken: string | null | undefined): boolean;
+/**
+ * Determine whether a payout needs Relay / Privy after Base settlement.
+ * This is true for every destination except native Base USDC.
+ */
+export declare function requiresRelayPayout(destinationChainId: number | bigint | null | undefined, destinationToken: string | null | undefined): boolean;
+/**
+ * Resolve a destination token value into its canonical symbol for display.
+ * Known aliases and configured chain token addresses map to USDC/USDT.
+ */
+export declare function resolveDestinationTokenSymbol(destinationToken: string | null | undefined, destinationChainId?: number | bigint | null): string;
 /**
  * Get supported destination token aliases for a destination chain.
  * Token support is derived from resolvable token addresses for the chain.
@@ -134,4 +149,3 @@ export declare const DESTINATION_CHAINS: {
  * Mapping of chain ID to name for backward compatibility.
  */
 export declare const SupportedChainsMap: Record<number, string>;
-//# sourceMappingURL=chains.d.ts.map

package/dist/chains.js

@@ -6,8 +6,9 @@
  */
 // Chain IDs
 export const BASE_CHAIN_ID = 8453;
+export const ETHEREUM_CHAIN_ID = 1;
 export const HYPEREVM_CHAIN_ID = 999;
-export const SOLANA_CHAIN_ID = 34268394551451;
+export const SOLANA_CHAIN_ID = 792703809;
 export const SUPPORTED_DESTINATION_TOKEN_ALIASES = ['USDC', 'USDT'];
 export const DEFAULT_DESTINATION_TOKEN_ALIAS = 'USDC';
 // Mainnet chain configurations
@@ -120,8 +121,8 @@ const CHAIN_SELECTION_ALIASES = {
     hyperliquid: 999,
     hyperevm: 999,
     hl: 999,
-    solana: 34268394551451,
-    sol: 34268394551451,
+    solana: 792703809,
+    sol: 792703809,
 };
 for (const chainId of SUPPORTED_CHAIN_IDS) {
     const chainConfig = MAINNET_CHAINS[chainId];
@@ -135,6 +136,10 @@ for (const chainId of SUPPORTED_CHAIN_IDS) {
     }
 }
 const DESTINATION_TOKEN_ADDRESSES = {
+    // Base
+    8453: {
+        usdt: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
+    },
     // Ethereum
     1: {
         usdt: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
@@ -265,6 +270,63 @@ export function resolveDestinationTokenAddress(destinationToken, destinationChai
     }
     return token;
 }
+/**
+ * Check whether the final payout destination is native Base USDC.
+ * Any other token or chain requires a Relay / Privy payout conversion step.
+ */
+export function isBaseUsdcDestination(destinationChainId, destinationToken) {
+    if (destinationChainId === null || destinationChainId === undefined) {
+        return false;
+    }
+    const chainId = Number(destinationChainId);
+    const token = destinationToken?.trim();
+    if (!token) {
+        return false;
+    }
+    if (chainId !== BASE_CHAIN_ID) {
+        return false;
+    }
+    const resolvedTokenAddress = resolveDestinationTokenAddress(token, chainId);
+    const baseUsdcAddress = getUsdcAddress(BASE_CHAIN_ID);
+    return Boolean(resolvedTokenAddress &&
+        baseUsdcAddress &&
+        resolvedTokenAddress.toLowerCase() === baseUsdcAddress.toLowerCase());
+}
+/**
+ * Determine whether a payout needs Relay / Privy after Base settlement.
+ * This is true for every destination except native Base USDC.
+ */
+export function requiresRelayPayout(destinationChainId, destinationToken) {
+    return !isBaseUsdcDestination(destinationChainId, destinationToken);
+}
+/**
+ * Resolve a destination token value into its canonical symbol for display.
+ * Known aliases and configured chain token addresses map to USDC/USDT.
+ */
+export function resolveDestinationTokenSymbol(destinationToken, destinationChainId) {
+    const token = destinationToken?.trim();
+    if (!token) {
+        return DEFAULT_DESTINATION_TOKEN_ALIAS;
+    }
+    const tokenAlias = normalizeDestinationTokenAlias(token);
+    if (tokenAlias) {
+        return tokenAlias;
+    }
+    const chainId = destinationChainId === null || destinationChainId === undefined
+        ? null
+        : Number(destinationChainId);
+    if (chainId !== null) {
+        const usdcAddress = getUsdcAddress(chainId);
+        if (usdcAddress && usdcAddress.toLowerCase() === token.toLowerCase()) {
+            return 'USDC';
+        }
+        const usdtAddress = DESTINATION_TOKEN_ADDRESSES[chainId]?.usdt;
+        if (usdtAddress && usdtAddress.toLowerCase() === token.toLowerCase()) {
+            return 'USDT';
+        }
+    }
+    return token.toUpperCase();
+}
 /**
  * Get supported destination token aliases for a destination chain.
  * Token support is derived from resolvable token addresses for the chain.

package/dist/crypto.d.ts

@@ -0,0 +1,65 @@
+export declare const BITCOIN_CHAIN_ID = 8253038;
+export declare const TRON_CHAIN_ID = 728126428;
+export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT", "ETH", "PYUSD", "SOL", "BNB", "HYPE", "WBTC", "USDH"];
+export type PayCryptoTokenSymbol = (typeof PAY_CRYPTO_TOKEN_SYMBOLS)[number];
+export declare const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS: PayCryptoTokenSymbol[];
+export declare const DEFAULT_ENABLED_DESTINATION_TOKENS: PayCryptoTokenSymbol[];
+/**
+ * Display-order priority for the "Pay with crypto" chain dropdown.
+ * Chains not in this list fall back to the existing numeric chain-ID
+ * iteration order of PAY_CRYPTO_CHAIN_CONFIGS as a stable tiebreaker.
+ */
+export declare const PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY: readonly number[];
+export declare const STABLECOIN_SYMBOLS: Set<"USDC" | "USDT" | "ETH" | "BNB" | "SOL" | "BTC" | "PYUSD" | "HYPE" | "WBTC" | "USDH">;
+export interface SupportedCryptoTokenConfig {
+    chainId: number;
+    chainName: string;
+    chainShortName: string;
+    symbol: PayCryptoTokenSymbol;
+    address: string;
+    decimals: number;
+    isNative: boolean;
+}
+export declare function normalizePayCryptoTokenSymbol(value: string | null | undefined): PayCryptoTokenSymbol | null;
+export declare function isStablecoinSymbol(symbol: string | null | undefined): boolean;
+export declare function getSupportedPayCryptoTokenConfigsForChain(chainId: number, enabledSymbols?: readonly string[] | null): SupportedCryptoTokenConfig[];
+export declare function getSupportedPayCryptoChainIds(enabledSymbols?: readonly string[] | null): number[];
+/**
+ * Returns the union of tokens supported by any of `enabledChainIds`,
+ * sorted by the canonical pay-crypto display order
+ * (DEFAULT_ENABLED_PAY_CRYPTO_TOKENS order).
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export declare function getAvailablePayCryptoTokens(enabledChainIds?: readonly number[]): PayCryptoTokenSymbol[];
+/**
+ * Returns the chain IDs that support `symbol`, optionally filtered
+ * to `enabledChainIds`, sorted by PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY
+ * with ascending numeric chain-ID order as the stable tiebreaker.
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export declare function getSupportedPayCryptoChainIdsForToken(symbol: PayCryptoTokenSymbol, enabledChainIds?: readonly number[]): number[];
+/**
+ * Returns the display name for a chain used by the "Pay with crypto"
+ * flow. Resolves through PAY_CRYPTO_CHAIN_CONFIGS first so Bitcoin
+ * and Tron (which are not in MAINNET_CHAINS) get the correct label.
+ * Falls back to getChainName for chains not registered here.
+ */
+export declare function getPayCryptoChainName(chainId: number): string;
+export declare function resolvePayCryptoTokenConfig(chainId: number, symbol: string | null | undefined): SupportedCryptoTokenConfig | null;
+/**
+ * Reverse lookup of a token config by contract address on a specific chain.
+ * Address comparison is case-insensitive. Returns null if the chain is unknown
+ * or if no token at that address is registered for the chain.
+ *
+ * Used by the crypto fulfillment resolver to translate a Relay request's inTx
+ * tokenAddress (lowercased, chain-qualified) into a human-readable symbol and
+ * decimals, so payment.currency and payment.paymentAmount can be written
+ * correctly for whatever token the customer actually deposited.
+ */
+export declare function resolvePayCryptoTokenConfigByAddress(chainId: number, address: string | null | undefined): SupportedCryptoTokenConfig | null;
+export declare function getSupportedDestinationBalanceTokenConfigsForChain(chainId: number, enabledSymbols?: readonly string[] | null): SupportedCryptoTokenConfig[];
+export declare function resolveDestinationBalanceTokenConfig(chainId: number, symbol: string | null | undefined): SupportedCryptoTokenConfig | null;

package/dist/crypto.js

@@ -0,0 +1,291 @@
+import { MAINNET_CHAINS, BASE_CHAIN_ID, ETHEREUM_CHAIN_ID, SOLANA_CHAIN_ID, getChainName, } from './chains.js';
+export const BITCOIN_CHAIN_ID = 8253038;
+export const TRON_CHAIN_ID = 728126428;
+export const PAY_CRYPTO_TOKEN_SYMBOLS = [
+    'BTC', // Kept in symbols for DB compatibility with existing sessions
+    'USDC',
+    'USDT',
+    'ETH',
+    'PYUSD',
+    'SOL',
+    'BNB',
+    'HYPE',
+    'WBTC',
+    'USDH',
+];
+export const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS = [
+    'BTC',
+    'ETH',
+    'USDT',
+    'USDC',
+    'PYUSD',
+    'SOL',
+    'BNB',
+    'HYPE',
+    'WBTC',
+    'USDH',
+];
+export const DEFAULT_ENABLED_DESTINATION_TOKENS = [
+    'USDC',
+    'USDT',
+];
+/**
+ * Display-order priority for the "Pay with crypto" chain dropdown.
+ * Chains not in this list fall back to the existing numeric chain-ID
+ * iteration order of PAY_CRYPTO_CHAIN_CONFIGS as a stable tiebreaker.
+ */
+export const PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY = [
+    BITCOIN_CHAIN_ID,
+    ETHEREUM_CHAIN_ID,
+    SOLANA_CHAIN_ID,
+    BASE_CHAIN_ID,
+];
+export const STABLECOIN_SYMBOLS = new Set([
+    'USDC',
+    'USDT',
+    'PYUSD',
+    'USDH',
+]);
+const NATIVE_ETH_ADDRESS = '0x0000000000000000000000000000000000000000';
+const NATIVE_SOL_ADDRESS = '11111111111111111111111111111111';
+const NATIVE_BTC_ADDRESS = 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8';
+const PAY_CRYPTO_CHAIN_CONFIGS = {
+    ...MAINNET_CHAINS,
+    [BITCOIN_CHAIN_ID]: {
+        chainId: BITCOIN_CHAIN_ID,
+        name: 'Bitcoin',
+        shortName: 'BTC',
+    },
+    [TRON_CHAIN_ID]: {
+        chainId: TRON_CHAIN_ID,
+        name: 'Tron',
+        shortName: 'TRON',
+    },
+};
+const CHAIN_TOKEN_CONFIGS = {
+    [BITCOIN_CHAIN_ID]: {
+        BTC: { address: NATIVE_BTC_ADDRESS, decimals: 8, isNative: true },
+    },
+    1: {
+        ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', decimals: 6, isNative: false },
+        USDT: { address: '0xdAC17F958D2ee523a2206206994597C13D831ec7', decimals: 6, isNative: false },
+        PYUSD: { address: '0x6c3ea9036406852006290770bedfcaba0e23a0e8', decimals: 6, isNative: false },
+        WBTC: { address: '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599', decimals: 8, isNative: false },
+    },
+    10: {
+        ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85', decimals: 6, isNative: false },
+        USDT: { address: '0x94b008aA00579c1307B0EF2c499aD98a8ce58e58', decimals: 6, isNative: false },
+    },
+    56: {
+        BNB: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', decimals: 18, isNative: false },
+        USDT: { address: '0x55d398326f99059fF775485246999027B3197955', decimals: 18, isNative: false },
+        WBTC: { address: '0x0555e30da8f98308edb960aa94c0db47230d2b9c', decimals: 8, isNative: false },
+    },
+    137: {
+        USDC: { address: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359', decimals: 6, isNative: false },
+        USDT: { address: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F', decimals: 6, isNative: false },
+        WBTC: { address: '0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6', decimals: 8, isNative: false },
+    },
+    480: {
+        ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1', decimals: 6, isNative: false },
+    },
+    999: {
+        HYPE: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0xb88339CB7199b77E23DB6E890353E22632Ba630f', decimals: 6, isNative: false },
+        USDH: { address: '0x111111a1a0667d36bd57c0a9f569b98057111111', decimals: 6, isNative: false },
+    },
+    8453: {
+        ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', decimals: 6, isNative: false },
+        USDT: { address: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', decimals: 6, isNative: false },
+        SOL: { address: '0x311935cd80b76769bf2ecc9d8ab7635b2139cf82', decimals: 9, isNative: false },
+        WBTC: { address: '0x0555e30da8f98308edb960aa94c0db47230d2b9c', decimals: 8, isNative: false },
+    },
+    42161: {
+        ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
+        USDC: { address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', decimals: 6, isNative: false },
+        USDT: { address: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9', decimals: 6, isNative: false },
+        WBTC: { address: '0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f', decimals: 8, isNative: false },
+    },
+    [TRON_CHAIN_ID]: {
+        USDT: { address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', decimals: 6, isNative: false },
+    },
+    792703809: {
+        SOL: { address: NATIVE_SOL_ADDRESS, decimals: 9, isNative: true },
+        USDC: { address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', decimals: 6, isNative: false },
+        USDT: { address: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', decimals: 6, isNative: false },
+        PYUSD: { address: '2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo', decimals: 6, isNative: false },
+    },
+};
+function isPayCryptoTokenSymbol(value) {
+    return PAY_CRYPTO_TOKEN_SYMBOLS.includes(value);
+}
+export function normalizePayCryptoTokenSymbol(value) {
+    const normalized = value?.trim().toUpperCase();
+    if (!normalized) {
+        return null;
+    }
+    return isPayCryptoTokenSymbol(normalized) ? normalized : null;
+}
+export function isStablecoinSymbol(symbol) {
+    const normalizedSymbol = normalizePayCryptoTokenSymbol(symbol);
+    return Boolean(normalizedSymbol && STABLECOIN_SYMBOLS.has(normalizedSymbol));
+}
+function normalizeEnabledSymbols(enabledSymbols, fallback) {
+    const normalized = (enabledSymbols ?? [])
+        .map((value) => normalizePayCryptoTokenSymbol(value))
+        .filter((value) => value !== null);
+    return normalized.length > 0 ? normalized : [...fallback];
+}
+function buildSupportedCryptoTokenConfig(chain, symbol) {
+    const config = CHAIN_TOKEN_CONFIGS[chain.chainId]?.[symbol];
+    if (!config) {
+        return null;
+    }
+    return {
+        chainId: chain.chainId,
+        chainName: chain.name,
+        chainShortName: chain.shortName,
+        symbol,
+        address: config.address,
+        decimals: config.decimals,
+        isNative: config.isNative,
+    };
+}
+export function getSupportedPayCryptoTokenConfigsForChain(chainId, enabledSymbols) {
+    const chain = PAY_CRYPTO_CHAIN_CONFIGS[chainId];
+    if (!chain) {
+        return [];
+    }
+    const allowedSymbols = normalizeEnabledSymbols(enabledSymbols, DEFAULT_ENABLED_PAY_CRYPTO_TOKENS);
+    return allowedSymbols
+        .map((symbol) => buildSupportedCryptoTokenConfig(chain, symbol))
+        .filter((value) => value !== null);
+}
+export function getSupportedPayCryptoChainIds(enabledSymbols) {
+    return Object.keys(PAY_CRYPTO_CHAIN_CONFIGS)
+        .map(Number)
+        .filter((chainId) => getSupportedPayCryptoTokenConfigsForChain(chainId, enabledSymbols).length > 0);
+}
+/**
+ * Returns the union of tokens supported by any of `enabledChainIds`,
+ * sorted by the canonical pay-crypto display order
+ * (DEFAULT_ENABLED_PAY_CRYPTO_TOKENS order).
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export function getAvailablePayCryptoTokens(enabledChainIds) {
+    const chainIds = enabledChainIds === undefined
+        ? Object.keys(CHAIN_TOKEN_CONFIGS).map(Number)
+        : enabledChainIds;
+    const available = new Set();
+    for (const chainId of chainIds) {
+        const chainTokens = CHAIN_TOKEN_CONFIGS[chainId];
+        if (chainTokens === undefined)
+            continue;
+        for (const symbol of Object.keys(chainTokens)) {
+            available.add(symbol);
+        }
+    }
+    return DEFAULT_ENABLED_PAY_CRYPTO_TOKENS.filter((symbol) => available.has(symbol));
+}
+/**
+ * Returns the chain IDs that support `symbol`, optionally filtered
+ * to `enabledChainIds`, sorted by PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY
+ * with ascending numeric chain-ID order as the stable tiebreaker.
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export function getSupportedPayCryptoChainIdsForToken(symbol, enabledChainIds) {
+    const candidateChainIds = enabledChainIds === undefined
+        ? Object.keys(CHAIN_TOKEN_CONFIGS).map(Number)
+        : Array.from(new Set(enabledChainIds));
+    const supporting = candidateChainIds.filter((chainId) => (CHAIN_TOKEN_CONFIGS[chainId]?.[symbol] !== undefined));
+    const supportingSet = new Set(supporting);
+    const priorityPortion = PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY
+        .filter((chainId) => supportingSet.has(chainId));
+    const prioritySet = new Set(PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY);
+    const restPortion = supporting
+        .filter((chainId) => !prioritySet.has(chainId))
+        .sort((a, b) => a - b);
+    return [...priorityPortion, ...restPortion];
+}
+/**
+ * Returns the display name for a chain used by the "Pay with crypto"
+ * flow. Resolves through PAY_CRYPTO_CHAIN_CONFIGS first so Bitcoin
+ * and Tron (which are not in MAINNET_CHAINS) get the correct label.
+ * Falls back to getChainName for chains not registered here.
+ */
+export function getPayCryptoChainName(chainId) {
+    return PAY_CRYPTO_CHAIN_CONFIGS[chainId]?.name ?? getChainName(chainId);
+}
+export function resolvePayCryptoTokenConfig(chainId, symbol) {
+    const normalizedSymbol = normalizePayCryptoTokenSymbol(symbol);
+    if (!normalizedSymbol) {
+        return null;
+    }
+    const chain = PAY_CRYPTO_CHAIN_CONFIGS[chainId];
+    if (!chain) {
+        return null;
+    }
+    return buildSupportedCryptoTokenConfig(chain, normalizedSymbol);
+}
+/**
+ * Reverse lookup of a token config by contract address on a specific chain.
+ * Address comparison is case-insensitive. Returns null if the chain is unknown
+ * or if no token at that address is registered for the chain.
+ *
+ * Used by the crypto fulfillment resolver to translate a Relay request's inTx
+ * tokenAddress (lowercased, chain-qualified) into a human-readable symbol and
+ * decimals, so payment.currency and payment.paymentAmount can be written
+ * correctly for whatever token the customer actually deposited.
+ */
+export function resolvePayCryptoTokenConfigByAddress(chainId, address) {
+    if (typeof address !== 'string')
+        return null;
+    const needle = address.trim().toLowerCase();
+    if (needle === '')
+        return null;
+    const chainTokens = CHAIN_TOKEN_CONFIGS[chainId];
+    if (chainTokens === undefined)
+        return null;
+    const chain = PAY_CRYPTO_CHAIN_CONFIGS[chainId];
+    if (chain === undefined)
+        return null;
+    for (const symbolKey of Object.keys(chainTokens)) {
+        const cfg = chainTokens[symbolKey];
+        if (cfg === undefined)
+            continue;
+        if (cfg.address.toLowerCase() === needle) {
+            return {
+                chainId: chain.chainId,
+                chainName: chain.name,
+                chainShortName: chain.shortName,
+                symbol: symbolKey,
+                address: cfg.address,
+                decimals: cfg.decimals,
+                isNative: cfg.isNative,
+            };
+        }
+    }
+    return null;
+}
+export function getSupportedDestinationBalanceTokenConfigsForChain(chainId, enabledSymbols) {
+    const chain = MAINNET_CHAINS[chainId];
+    if (!chain) {
+        return [];
+    }
+    const allowedSymbols = normalizeEnabledSymbols(enabledSymbols, DEFAULT_ENABLED_DESTINATION_TOKENS);
+    return allowedSymbols
+        .map((symbol) => buildSupportedCryptoTokenConfig(chain, symbol))
+        .filter((value) => value !== null);
+}
+export function resolveDestinationBalanceTokenConfig(chainId, symbol) {
+    return resolvePayCryptoTokenConfig(chainId, symbol);
+}

package/dist/fees.d.ts

@@ -0,0 +1,27 @@
+import type { FeeTranche, MaxFeeConfig, ReferralFeeConfig } from './types.js';
+declare const TRANCHE_SCALE_BY_CURRENCY: {
+    readonly USD: 2;
+    readonly USDC: 2;
+};
+type TrancheCurrency = keyof typeof TRANCHE_SCALE_BY_CURRENCY;
+export type FeeSource = 'default' | 'merchant' | 'exempt';
+export declare function parseBoundaryUnits(raw: number, currency: TrancheCurrency): bigint;
+export declare function parseLookupUnits(raw: string, currency: TrancheCurrency): bigint;
+export declare function parseUsdcUnits(raw: string): bigint;
+export declare function formatUsdcUnits(units: bigint): string;
+export declare function calculateGrossFromNetUnits(netAmountUnits: bigint, feeBps: number): bigint;
+export declare function validateTranches(tranches: FeeTranche[], currency: TrancheCurrency): void;
+export declare function getMatchingTrancheIndex(tranches: FeeTranche[], amount: string, currency: TrancheCurrency): number;
+export declare function resolveReferralFeeConfig(config: ReferralFeeConfig, amountUsdc: string, options?: {
+    defaultFeeBps?: number;
+}): {
+    feeSource: FeeSource;
+    referralFeeBps: number;
+};
+export declare function resolveExactTokenGrossAmountUsdc(config: ReferralFeeConfig, requestedNetAmountUsdc: string, options?: {
+    defaultFeeBps?: number;
+}): string;
+export declare function resolveMaxFeeConfig(config: MaxFeeConfig, amountUsd: string): {
+    maxFeePercentage: number;
+};
+export {};