@zkp2p/pay-shared 4.0.1 → 6.0.0

package/README.md

@@ -9,7 +9,7 @@ Shared TypeScript types, enums, and chain utilities used by ZKP2P Pay API, SDK,
 ## Install
 
 ```bash
-npm install @zkp2p/pay-shared@4.0.1
+npm install @zkp2p/pay-shared@6.0.0
 ```
 
 ## Published artifacts
@@ -85,6 +85,10 @@ Core type exports:
 - `CheckoutAggregate`
 - `CheckoutQuotes`
 - `MerchantProfile`
+- `CashoutView`
+- `CashoutRailType`
+- `WebhookPayload`
+- `CashoutWebhookPayload`
 
 Core constants:
 
@@ -96,6 +100,15 @@ Core constants:
 - `ProofAttemptStatus`
 - `OrderErrorCode`
 - `MerchantEnvironment`
+- `CashoutStatus`
+- `CashoutRail`
+- `CashoutCryptoRail`
+- `CashoutPayoutProvider`
+- `PAY_CRYPTO_TOKEN_SYMBOLS`
+
+Webhook helpers:
+
+- `isCashoutWebhook(...)` — narrows `WebhookPayload` to `CashoutWebhookPayload`
 
 Chain constants and helpers:
 
@@ -115,5 +128,5 @@ Chain constants and helpers:
 ## Notes
 
 - Amount fields are strings to preserve precision across APIs and clients.
-- Canonical order/payment amounts are available on `CheckoutOrder` and `CheckoutPayment` (for example `requestedUsdcAmount`, `remainingUsdcAmount`, `netSettledUsdcAmount`).
+- Canonical order/payment amounts are available on `CheckoutOrder` and `CheckoutPayment` (for example `requestedUsdcAmount`, `remainingUsdcAmount`, `netSettledUsdcAmount`). `CheckoutPayment.penalties` lists attestation-applied reductions (`PaymentPenalty[]`, empty when none).
 - This package is ESM-only.

package/dist/addressValidators.d.ts

@@ -1,2 +1,4 @@
+/** NEAR Intents accepts mainnet transparent Zcash refund addresses only. */
+export declare function isValidZcashAddress(value: string): boolean;
 export declare function isValidSolanaAddress(value: string): boolean;
 export declare function isValidTronAddress(value: string): boolean;

package/dist/addressValidators.js

@@ -1,4 +1,15 @@
-import { decodeBase58, encodeBase58, hasBase58CheckChecksum, } from './addressEncoding.js';
+import { decodeBase58, doubleSha256, encodeBase58, hasBase58CheckChecksum, } from './addressEncoding.js';
+/** NEAR Intents accepts mainnet transparent Zcash refund addresses only. */
+export function isValidZcashAddress(value) {
+    if (!/^t[13][1-9A-HJ-NP-Za-km-z]{33}$/.test(value))
+        return false;
+    const decoded = decodeBase58(value);
+    if (decoded === null || decoded.length !== 26 || decoded[0] !== 0x1c
+        || (decoded[1] !== 0xb8 && decoded[1] !== 0xbd))
+        return false;
+    const checksum = doubleSha256(decoded.subarray(0, 22));
+    return decoded.subarray(22).every((byte, index) => byte === checksum[index]);
+}
 export function isValidSolanaAddress(value) {
     if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value)) {
         return false;

package/dist/attribution.d.ts

@@ -1,4 +1,5 @@
 export declare enum IntentAttributionReferrer {
     PAY = "zkp2p-pay",
-    SUPPORT = "zkp2p-pay-cs"
+    SUPPORT = "zkp2p-pay-cs",
+    CASHOUT = "zkp2p-pay-cashout"
 }

package/dist/attribution.js

@@ -2,4 +2,5 @@ export var IntentAttributionReferrer;
 (function (IntentAttributionReferrer) {
     IntentAttributionReferrer["PAY"] = "zkp2p-pay";
     IntentAttributionReferrer["SUPPORT"] = "zkp2p-pay-cs";
+    IntentAttributionReferrer["CASHOUT"] = "zkp2p-pay-cashout";
 })(IntentAttributionReferrer || (IntentAttributionReferrer = {}));

package/dist/bitcoin.d.ts

@@ -1 +1,5 @@
 export declare function isValidBitcoinAddress(value: string): boolean;
+/** A Bitcoin txid as Relay writes it: 64 lower-case hex digits, no 0x prefix. */
+export declare function isBitcoinTxid(value: string): boolean;
+/** A mainnet P2WPKH address (bech32, witness version 0, lower-case) for a 20-byte witness program. */
+export declare function encodeBitcoinP2wpkhAddress(program: Uint8Array): string;

package/dist/bitcoin.js

@@ -2,6 +2,13 @@ import { hasBase58CheckChecksum } from './addressEncoding.js';
 const BECH32_ALPHABET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
 const BECH32_CHECKSUM = 1;
 const BECH32M_CHECKSUM = 0x2bc830a3;
+// The bech32 HRP "bc" expanded for the checksum: high bits, a zero, low bits.
+const BITCOIN_HRP_VALUES = [
+    ...[...'bc'].map((character) => character.charCodeAt(0) >>> 5),
+    0,
+    ...[...'bc'].map((character) => character.charCodeAt(0) & 31),
+];
+const BITCOIN_TXID_PATTERN = /^[0-9a-f]{64}$/;
 function calculatePolymod(values) {
     const generators = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
     let checksum = 1;
@@ -33,6 +40,23 @@ function convertWitnessProgram(values) {
     }
     return Uint8Array.from(decoded);
 }
+/** 8-bit bytes to 5-bit bech32 words, padding the last word with zero bits. */
+function toBech32Words(bytes) {
+    const words = [];
+    let accumulator = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        accumulator = ((accumulator << 8) | byte) & 0xffff;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            words.push((accumulator >>> bits) & 31);
+        }
+    }
+    if (bits > 0)
+        words.push((accumulator << (5 - bits)) & 31);
+    return words;
+}
 function isValidBech32Address(value) {
     if (value.length > 90 || (value !== value.toLowerCase() && value !== value.toUpperCase())) {
         return false;
@@ -47,13 +71,8 @@ function isValidBech32Address(value) {
     if (data.length < 7 || data.some((item) => item === -1)) {
         return false;
     }
-    const hrpValues = [
-        ...[...'bc'].map((character) => character.charCodeAt(0) >>> 5),
-        0,
-        ...[...'bc'].map((character) => character.charCodeAt(0) & 31),
-    ];
     const witnessVersion = data[0];
-    const polymod = calculatePolymod([...hrpValues, ...data]);
+    const polymod = calculatePolymod([...BITCOIN_HRP_VALUES, ...data]);
     if (witnessVersion > 16
         || (witnessVersion === 0 && polymod !== BECH32_CHECKSUM)
         || (witnessVersion > 0 && polymod !== BECH32M_CHECKSUM)) {
@@ -77,3 +96,16 @@ export function isValidBitcoinAddress(value) {
         && (hasBase58CheckChecksum(trimmed, 0x00)
             || hasBase58CheckChecksum(trimmed, 0x05));
 }
+/** A Bitcoin txid as Relay writes it: 64 lower-case hex digits, no 0x prefix. */
+export function isBitcoinTxid(value) {
+    return BITCOIN_TXID_PATTERN.test(value);
+}
+/** A mainnet P2WPKH address (bech32, witness version 0, lower-case) for a 20-byte witness program. */
+export function encodeBitcoinP2wpkhAddress(program) {
+    if (program.length !== 20)
+        throw new Error('A P2WPKH witness program is 20 bytes');
+    const data = [0, ...toBech32Words(program)];
+    const polymod = calculatePolymod([...BITCOIN_HRP_VALUES, ...data, 0, 0, 0, 0, 0, 0]) ^ BECH32_CHECKSUM;
+    const checksum = [0, 1, 2, 3, 4, 5].map((index) => (polymod >>> (5 * (5 - index))) & 31);
+    return `bc1${[...data, ...checksum].map((value) => BECH32_ALPHABET[value]).join('')}`;
+}

package/dist/cashoutRails.d.ts

@@ -0,0 +1,34 @@
+import { type CashoutBuyerProofRailType, type CashoutCryptoRailType, type CashoutFiatRailType, type CashoutSarRailType } from './types.js';
+/**
+ * The cashout rails SAR_SUPPORTED_FIAT_RAILS lists, in rail order: Venmo, Cash App and PayPal. Wise is SAR but not a
+ * cashout rail yet.
+ */
+export declare const CASHOUT_SAR_RAILS: ReadonlyArray<CashoutSarRailType>;
+/** A rail in CASHOUT_SAR_RAILS. Exact rails only; a variant such as "venmo-x" is not a cashout rail. */
+export declare function isCashoutSarRail(rail: string): rail is CashoutSarRailType;
+/** A cashout fiat rail with no connect step: Zelle, Revolut and Chime. */
+export declare function isCashoutBuyerProofRail(rail: string): rail is CashoutBuyerProofRailType;
+/** Every crypto payout network's rail, in rail order (checkout's relay rail order). */
+export declare const CASHOUT_CRYPTO_RAILS: ReadonlyArray<CashoutCryptoRailType>;
+/** An exact crypto payout rail; replaces every comparison with the retired `crypto` rail. */
+export declare function isCashoutCryptoRail(rail: string): rail is CashoutCryptoRailType;
+export declare function cashoutCryptoRailChainId(rail: CashoutCryptoRailType): number;
+export declare function cashoutCryptoRailForChain(chainId: number): CashoutCryptoRailType | null;
+/** The payout chains a rail list offers, in rail order; the checkout's pickers and the server's checks read it. */
+export declare function cashoutRailsChainIds(rails: ReadonlyArray<string>): number[];
+export declare function hasCashoutCryptoRail(rails: ReadonlyArray<string>): boolean;
+/**
+ * Venmo and PayPal listings get the Peer Pay merchant group. The set is @zkp2p/core's
+ * DISPUTE_PROTECTION_STAKE_PLATFORMS, which @zkp2p/sdk keeps private, and
+ * zkp2p-mobile's CHARGEBACK_PRONE_SELL_PLATFORMS. Cash App left that set on 2026-08-28.
+ */
+export declare const CASHOUT_PEER_PAY_GROUP_RAILS: readonly ["venmo", "paypal"];
+/** Rails whose listings get the Peer Pay merchant group (CASHOUT_PEER_PAY_GROUP_RAILS). */
+export type CashoutPeerPayGroupRailType = typeof CASHOUT_PEER_PAY_GROUP_RAILS[number];
+/** A rail in CASHOUT_PEER_PAY_GROUP_RAILS. */
+export declare function isCashoutPeerPayGroupRail(rail: string): rail is CashoutPeerPayGroupRailType;
+/**
+ * A payout account as its rail writes it: "@alice" (Venmo, Revolut), "$alice1" (Cash App), "paypal.me/bob" (PayPal),
+ * the email (Zelle) and "$chimesign" (Chime, whose stored handle already carries its "$").
+ */
+export declare function cashoutAccountLabel(rail: CashoutFiatRailType, handle: string): string;

package/dist/cashoutRails.js

@@ -0,0 +1,71 @@
+import { SAR_SUPPORTED_FIAT_RAILS, parseCryptoRailChainId } from './rails.js';
+import { CashoutCryptoRail, CashoutFiatRail, CashoutRail, } from './types.js';
+const CASHOUT_FIAT_RAIL_SET = new Set(Object.values(CashoutFiatRail));
+const SAR_SUPPORTED_FIAT_RAIL_SET = new Set(SAR_SUPPORTED_FIAT_RAILS);
+/**
+ * The cashout rails SAR_SUPPORTED_FIAT_RAILS lists, in rail order: Venmo, Cash App and PayPal. Wise is SAR but not a
+ * cashout rail yet.
+ */
+export const CASHOUT_SAR_RAILS = Object.values(CashoutFiatRail).filter((rail) => SAR_SUPPORTED_FIAT_RAIL_SET.has(rail));
+const CASHOUT_SAR_RAIL_SET = new Set(CASHOUT_SAR_RAILS);
+/** A rail in CASHOUT_SAR_RAILS. Exact rails only; a variant such as "venmo-x" is not a cashout rail. */
+export function isCashoutSarRail(rail) {
+    return CASHOUT_SAR_RAIL_SET.has(rail);
+}
+/** A cashout fiat rail with no connect step: Zelle, Revolut and Chime. */
+export function isCashoutBuyerProofRail(rail) {
+    return CASHOUT_FIAT_RAIL_SET.has(rail) && !CASHOUT_SAR_RAIL_SET.has(rail);
+}
+/** Every crypto payout network's rail, in rail order (checkout's relay rail order). */
+export const CASHOUT_CRYPTO_RAILS = Object.values(CashoutCryptoRail);
+const CASHOUT_CRYPTO_RAIL_SET = new Set(CASHOUT_CRYPTO_RAILS);
+/** An exact crypto payout rail; replaces every comparison with the retired `crypto` rail. */
+export function isCashoutCryptoRail(rail) {
+    return CASHOUT_CRYPTO_RAIL_SET.has(rail);
+}
+export function cashoutCryptoRailChainId(rail) {
+    const chainId = parseCryptoRailChainId(rail);
+    if (chainId === null)
+        throw new Error(`Cashout crypto rail ${rail} names no chain`);
+    return chainId;
+}
+const CASHOUT_CRYPTO_RAIL_BY_CHAIN = new Map(CASHOUT_CRYPTO_RAILS.map((rail) => [cashoutCryptoRailChainId(rail), rail]));
+export function cashoutCryptoRailForChain(chainId) {
+    return CASHOUT_CRYPTO_RAIL_BY_CHAIN.get(chainId) ?? null;
+}
+/** The payout chains a rail list offers, in rail order; the checkout's pickers and the server's checks read it. */
+export function cashoutRailsChainIds(rails) {
+    return CASHOUT_CRYPTO_RAILS.filter((rail) => rails.includes(rail)).map(cashoutCryptoRailChainId);
+}
+export function hasCashoutCryptoRail(rails) {
+    return rails.some(isCashoutCryptoRail);
+}
+/**
+ * Venmo and PayPal listings get the Peer Pay merchant group. The set is @zkp2p/core's
+ * DISPUTE_PROTECTION_STAKE_PLATFORMS, which @zkp2p/sdk keeps private, and
+ * zkp2p-mobile's CHARGEBACK_PRONE_SELL_PLATFORMS. Cash App left that set on 2026-08-28.
+ */
+export const CASHOUT_PEER_PAY_GROUP_RAILS = [CashoutRail.VENMO, CashoutRail.PAYPAL];
+const CASHOUT_PEER_PAY_GROUP_RAIL_SET = new Set(CASHOUT_PEER_PAY_GROUP_RAILS);
+/** A rail in CASHOUT_PEER_PAY_GROUP_RAILS. */
+export function isCashoutPeerPayGroupRail(rail) {
+    return CASHOUT_PEER_PAY_GROUP_RAIL_SET.has(rail);
+}
+/**
+ * A payout account as its rail writes it: "@alice" (Venmo, Revolut), "$alice1" (Cash App), "paypal.me/bob" (PayPal),
+ * the email (Zelle) and "$chimesign" (Chime, whose stored handle already carries its "$").
+ */
+export function cashoutAccountLabel(rail, handle) {
+    switch (rail) {
+        case CashoutRail.VENMO:
+        case CashoutRail.REVOLUT:
+            return `@${handle.replace(/^@/u, '')}`;
+        case CashoutRail.CASHAPP:
+            return `$${handle.replace(/^\$/u, '')}`;
+        case CashoutRail.PAYPAL:
+            return `paypal.me/${handle}`;
+        case CashoutRail.ZELLE:
+        case CashoutRail.CHIME:
+            return handle;
+    }
+}

package/dist/chains.js

@@ -88,6 +88,15 @@ export const MAINNET_CHAINS = {
         isEvm: true,
         explorerUrl: 'https://hyperscan.xyz',
     },
+    5042: {
+        chainId: 5042,
+        name: 'Arc',
+        shortName: 'ARC',
+        usdcAddress: '0x3600000000000000000000000000000000000000',
+        isOriginChain: false,
+        isEvm: true,
+        explorerUrl: 'https://explorer.arc.io',
+    },
     // Non-EVM Destination chains
     [SOLANA_CHAIN_ID]: {
         chainId: SOLANA_CHAIN_ID,

package/dist/clientTelemetry.d.ts

@@ -0,0 +1,25 @@
+/** Shared, non-secret context for the Pay browser surfaces. */
+export type PayClientSurface = 'checkout' | 'merchant-dashboard' | 'support-dashboard';
+export declare function payClientContext(input: {
+    surface: PayClientSurface;
+    hostname: string;
+    productionBuild: boolean;
+    appVersion: string;
+    merchantId?: string;
+    environment?: 'LIVE' | 'SANDBOX';
+    qaRun: boolean;
+}): {
+    merchant_id?: string | undefined;
+    product: string;
+    surface: PayClientSurface;
+    hostname: string;
+    deployment_environment: string;
+    app_version: string;
+    environment: string;
+    is_qa: boolean;
+};
+/**
+ * Route templates only: never emit customer IDs, search parameters or fragments. The support
+ * dashboard templates its routes with `supportTelemetryRoute` from the support contracts.
+ */
+export declare function payClientRoute(surface: Exclude<PayClientSurface, 'support-dashboard'>, pathname: string): string;

package/dist/clientTelemetry.js

@@ -0,0 +1,30 @@
+const PRODUCTION_HOST = {
+    checkout: 'pay.peer.xyz',
+    'merchant-dashboard': 'merchant.pay.peer.xyz',
+    'support-dashboard': 'support.pay.peer.xyz',
+};
+export function payClientContext(input) {
+    const productionHost = PRODUCTION_HOST[input.surface];
+    return {
+        product: 'pay',
+        surface: input.surface,
+        hostname: input.hostname,
+        deployment_environment: input.productionBuild && input.hostname === productionHost
+            ? 'PRODUCTION' : input.productionBuild ? 'PREPROD' : 'DEVELOPMENT',
+        app_version: input.appVersion,
+        environment: input.environment ?? 'UNKNOWN',
+        is_qa: input.qaRun || input.merchantId === 'cmrunizzo02wf3ua8t6yx1mns',
+        ...(input.merchantId ? { merchant_id: input.merchantId } : {}),
+    };
+}
+/**
+ * Route templates only: never emit customer IDs, search parameters or fragments. The support
+ * dashboard templates its routes with `supportTelemetryRoute` from the support contracts.
+ */
+export function payClientRoute(surface, pathname) {
+    const path = pathname.split(/[?#]/, 1)[0];
+    if (surface === 'checkout')
+        return path === '/' ? '/' : '/:checkout';
+    return /^\/(?:login|onboarding|orders|staking|referrals|scan-to-pay|webhooks|faq|resources|settings(?:\/(?:account|payments|checkout|developer|billing|interface|tap-to-pay))?)?$/.test(path)
+        ? path : '/:unknown';
+}

package/dist/conciergeIntake.d.ts

@@ -0,0 +1,56 @@
+export declare const CONCIERGE_QUESTIONS: readonly [{
+    readonly id: "business";
+    readonly label: "What do you sell, and what industry are you in?";
+    readonly hint: "Your products or services and industry.";
+}, {
+    readonly id: "storefront";
+    readonly label: "Where do you sell?";
+    readonly hint: "Your website, plus what it runs on: Shopify, WooCommerce, custom site, Telegram, or in person.";
+}, {
+    readonly id: "volume";
+    readonly label: "How much volume do you process today?";
+    readonly hint: "Daily, weekly, or monthly volume, plus your average order size. Include the currency.";
+}, {
+    readonly id: "customers";
+    readonly label: "Where are your customers?";
+    readonly hint: "US, UK, EU, or elsewhere. This decides which payment apps we enable.";
+}, {
+    readonly id: "apps";
+    readonly label: "Which payment apps do you want your customers paying with?";
+    readonly hint: "Venmo, Cash App, Zelle, PayPal, Revolut, Wise, or others.";
+}, {
+    readonly id: "payments";
+    readonly label: "What do you use to accept payments today?";
+    readonly hint: "Your current payment providers or methods.";
+}, {
+    readonly id: "crypto";
+    readonly label: "Do you also want to accept crypto directly?";
+    readonly hint: "Customers can pay with any coin on any network and you still settle in USDC.";
+    readonly options: readonly ["Yes", "No", "Not sure yet"];
+}, {
+    readonly id: "feePayer";
+    readonly label: "Who pays the Peer Pay fee?";
+    readonly hint: "Your customer, you, or a split between both.";
+    readonly options: readonly ["Customer", "Merchant", "Split"];
+}, {
+    readonly id: "integrator";
+    readonly label: "Who is doing the integration on your side, you or a developer?";
+    readonly hint: "We will send the right guide and set up an API key if needed.";
+}];
+export type ConciergeQuestionId = typeof CONCIERGE_QUESTIONS[number]['id'];
+export type ConciergeQuestion = {
+    readonly id: ConciergeQuestionId;
+    readonly label: string;
+    readonly hint: string;
+    readonly options?: readonly string[];
+};
+export declare const CONCIERGE_QUESTION_IDS: readonly ConciergeQuestionId[];
+export type ConciergeAnswers = Partial<Record<ConciergeQuestionId, string>>;
+export type ConciergeInquiryInput = {
+    readonly contactEmail: string;
+    readonly businessName: string;
+    readonly telegramUsername: string;
+    readonly answers: ConciergeAnswers;
+    readonly message: string;
+};
+export declare function isCompleteConciergeAnswers(value: ConciergeAnswers): boolean;

package/dist/conciergeIntake.js

@@ -0,0 +1,15 @@
+export const CONCIERGE_QUESTIONS = [
+    { id: 'business', label: 'What do you sell, and what industry are you in?', hint: 'Your products or services and industry.' },
+    { id: 'storefront', label: 'Where do you sell?', hint: 'Your website, plus what it runs on: Shopify, WooCommerce, custom site, Telegram, or in person.' },
+    { id: 'volume', label: 'How much volume do you process today?', hint: 'Daily, weekly, or monthly volume, plus your average order size. Include the currency.' },
+    { id: 'customers', label: 'Where are your customers?', hint: 'US, UK, EU, or elsewhere. This decides which payment apps we enable.' },
+    { id: 'apps', label: 'Which payment apps do you want your customers paying with?', hint: 'Venmo, Cash App, Zelle, PayPal, Revolut, Wise, or others.' },
+    { id: 'payments', label: 'What do you use to accept payments today?', hint: 'Your current payment providers or methods.' },
+    { id: 'crypto', label: 'Do you also want to accept crypto directly?', hint: 'Customers can pay with any coin on any network and you still settle in USDC.', options: ['Yes', 'No', 'Not sure yet'] },
+    { id: 'feePayer', label: 'Who pays the Peer Pay fee?', hint: 'Your customer, you, or a split between both.', options: ['Customer', 'Merchant', 'Split'] },
+    { id: 'integrator', label: 'Who is doing the integration on your side, you or a developer?', hint: 'We will send the right guide and set up an API key if needed.' },
+];
+export const CONCIERGE_QUESTION_IDS = CONCIERGE_QUESTIONS.map(({ id }) => id);
+export function isCompleteConciergeAnswers(value) {
+    return CONCIERGE_QUESTION_IDS.every((id) => Boolean(value[id]?.trim()));
+}

package/dist/crypto.d.ts

@@ -1,5 +1,9 @@
 export declare const BITCOIN_CHAIN_ID = 8253038;
-export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT", "ETH", "PYUSD", "SOL", "BNB", "HYPE", "WBTC", "USDH"];
+export declare const ZCASH_CHAIN_ID = 133701;
+export declare const ZCASH_ASSET = "nep141:zec.omft.near";
+/** NEAR Intents' asset id for USDC on Base (origin of cashout payouts, destination of Zcash checkout payments). */
+export declare const NEAR_BASE_USDC_ASSET = "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near";
+export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT", "ETH", "PYUSD", "SOL", "BNB", "HYPE", "WBTC", "USDH", "ZEC"];
 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[];
@@ -9,7 +13,7 @@ export declare const DEFAULT_ENABLED_DESTINATION_TOKENS: PayCryptoTokenSymbol[];
  * 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 declare const STABLECOIN_SYMBOLS: Set<"USDC" | "USDT" | "ETH" | "BNB" | "SOL" | "BTC" | "PYUSD" | "HYPE" | "WBTC" | "USDH" | "ZEC">;
 export interface SupportedCryptoTokenConfig {
     chainId: number;
     chainName: string;
@@ -19,6 +23,8 @@ export interface SupportedCryptoTokenConfig {
     decimals: number;
     isNative: boolean;
 }
+/** Relay's sentinel for native BTC. Its bech32 checksum verifies, but it decodes to a 19-byte witness-v0 program, so isValidBitcoinAddress rejects it and it never works as a refund address. */
+export declare const BITCOIN_NATIVE_TOKEN_ADDRESS = "bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8";
 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[];
@@ -62,3 +68,38 @@ export declare function resolvePayCryptoTokenConfig(chainId: number, symbol: str
 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;
+/** Chains a cashout can be funded from through Relay. Zcash is out: ZEC funding is out of scope (2026-10-07). */
+export declare const CASHOUT_FUNDING_CHAIN_IDS: readonly number[];
+/**
+ * The tokens a cashout can be funded with: every supported pay-crypto token on a Relay-fundable chain. An explicit list,
+ * because isEvmChain answers true for chains the table doesn't know, which let Bitcoin and Zcash in by accident.
+ */
+export declare function getCashoutFundingTokenConfigs(): SupportedCryptoTokenConfig[];
+/** The address formats a cashout address can take. */
+export declare const CashoutAddressFamily: {
+    readonly EVM: "EVM";
+    readonly SOLANA: "SOLANA";
+    readonly TRON: "TRON";
+    readonly BITCOIN: "BITCOIN";
+    readonly ZCASH: "ZCASH";
+};
+export type CashoutAddressFamilyType = (typeof CashoutAddressFamily)[keyof typeof CashoutAddressFamily];
+/**
+ * The address format a cashout address on this chain must have. Bitcoin, Solana and Tron map by id;
+ * Zcash is ZCASH (transparent addresses only, Zcash spec Z3). Every remaining chain in the pay-crypto token table
+ * is EVM; any other chain has none (null).
+ * Deliberately not isEvmChain, which answers true for unknown ids, Bitcoin's included.
+ */
+export declare function cashoutAddressFamily(chainId: number): CashoutAddressFamilyType | null;
+/** Every chain a cashout can pay out on, ascending: each pay-crypto chain, Zcash included (through NEAR Intents). */
+export declare const CASHOUT_PAYOUT_CHAIN_IDS: readonly number[];
+/** The catalog token at tokenAddress on a payout chain, spelled as the catalog spells it; null off the catalog. */
+export declare function resolveCashoutPayoutToken(chainId: number, tokenAddress: string): SupportedCryptoTokenConfig | null;
+export declare function getPayCryptoTxUrl(chainId: number, txHash: string): string | null;
+export declare function getPayCryptoAddressUrl(chainId: number, address: string): string | null;
+/**
+ * Display form of an estimate or a delivered amount (any-coin spec "Units of amounts"): stablecoins round down to two
+ * decimals, other tokens to six significant digits; trailing zeros go and the integer part is grouped with commas.
+ * The input is already exact in the token's decimals, so the result never shows more decimals than the token has.
+ */
+export declare function formatPayCryptoDisplayAmount(amount: string, symbol: PayCryptoTokenSymbol): string;

package/dist/crypto.js

@@ -1,5 +1,10 @@
-import { MAINNET_CHAINS, BASE_CHAIN_ID, ETHEREUM_CHAIN_ID, SOLANA_CHAIN_ID, TRON_CHAIN_ID, getChainName, } from './chains.js';
+import { MAINNET_CHAINS, BASE_CHAIN_ID, ETHEREUM_CHAIN_ID, HYPEREVM_CHAIN_ID, SOLANA_CHAIN_ID, TRON_CHAIN_ID, getChainName, getExplorerUrl, } from './chains.js';
 export const BITCOIN_CHAIN_ID = 8253038;
+// Synthetic network ID shared with the mobile and web NEAR Intents clients.
+export const ZCASH_CHAIN_ID = 133701;
+export const ZCASH_ASSET = 'nep141:zec.omft.near';
+/** NEAR Intents' asset id for USDC on Base (origin of cashout payouts, destination of Zcash checkout payments). */
+export const NEAR_BASE_USDC_ASSET = 'nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near';
 export const PAY_CRYPTO_TOKEN_SYMBOLS = [
     'BTC', // Kept in symbols for DB compatibility with existing sessions
     'USDC',
@@ -11,6 +16,7 @@ export const PAY_CRYPTO_TOKEN_SYMBOLS = [
     'HYPE',
     'WBTC',
     'USDH',
+    'ZEC',
 ];
 export const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS = [
     'BTC',
@@ -23,6 +29,7 @@ export const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS = [
     'HYPE',
     'WBTC',
     'USDH',
+    'ZEC',
 ];
 export const DEFAULT_ENABLED_DESTINATION_TOKENS = [
     'USDC',
@@ -47,9 +54,11 @@ export const STABLECOIN_SYMBOLS = new Set([
 ]);
 const NATIVE_ETH_ADDRESS = '0x0000000000000000000000000000000000000000';
 const NATIVE_SOL_ADDRESS = '11111111111111111111111111111111';
-const NATIVE_BTC_ADDRESS = 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8';
+/** Relay's sentinel for native BTC. Its bech32 checksum verifies, but it decodes to a 19-byte witness-v0 program, so isValidBitcoinAddress rejects it and it never works as a refund address. */
+export const BITCOIN_NATIVE_TOKEN_ADDRESS = 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8';
 const PAY_CRYPTO_CHAIN_CONFIGS = {
     ...MAINNET_CHAINS,
+    [ZCASH_CHAIN_ID]: { chainId: ZCASH_CHAIN_ID, name: 'Zcash', shortName: 'ZEC' },
     [BITCOIN_CHAIN_ID]: {
         chainId: BITCOIN_CHAIN_ID,
         name: 'Bitcoin',
@@ -57,8 +66,11 @@ const PAY_CRYPTO_CHAIN_CONFIGS = {
     },
 };
 const CHAIN_TOKEN_CONFIGS = {
+    [ZCASH_CHAIN_ID]: {
+        ZEC: { address: ZCASH_ASSET, decimals: 8, isNative: true },
+    },
     [BITCOIN_CHAIN_ID]: {
-        BTC: { address: NATIVE_BTC_ADDRESS, decimals: 8, isNative: true },
+        BTC: { address: BITCOIN_NATIVE_TOKEN_ADDRESS, decimals: 8, isNative: true },
     },
     1: {
         ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
@@ -92,6 +104,10 @@ const CHAIN_TOKEN_CONFIGS = {
         USDC: { address: '0xb88339CB7199b77E23DB6E890353E22632Ba630f', decimals: 6, isNative: false },
         USDH: { address: '0x111111a1a0667d36bd57c0a9f569b98057111111', decimals: 6, isNative: false },
     },
+    5042: {
+        // Arc's ERC-20 USDC interface has 6 decimals; native gas uses 18.
+        USDC: { address: '0x3600000000000000000000000000000000000000', decimals: 6, isNative: false },
+    },
     8453: {
         ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
         USDC: { address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', decimals: 6, isNative: false },
@@ -283,3 +299,107 @@ export function getSupportedDestinationBalanceTokenConfigsForChain(chainId, enab
 export function resolveDestinationBalanceTokenConfig(chainId, symbol) {
     return resolvePayCryptoTokenConfig(chainId, symbol);
 }
+/** Chains a cashout can be funded from through Relay. Zcash is out: ZEC funding is out of scope (2026-10-07). */
+export const CASHOUT_FUNDING_CHAIN_IDS = [
+    ETHEREUM_CHAIN_ID, 10, 56, 137, 480, HYPEREVM_CHAIN_ID, 5042, BASE_CHAIN_ID, 42161, BITCOIN_CHAIN_ID,
+];
+/**
+ * The tokens a cashout can be funded with: every supported pay-crypto token on a Relay-fundable chain. An explicit list,
+ * because isEvmChain answers true for chains the table doesn't know, which let Bitcoin and Zcash in by accident.
+ */
+export function getCashoutFundingTokenConfigs() {
+    return getSupportedPayCryptoChainIds(PAY_CRYPTO_TOKEN_SYMBOLS)
+        .filter((chainId) => CASHOUT_FUNDING_CHAIN_IDS.includes(chainId))
+        .flatMap((chainId) => getSupportedPayCryptoTokenConfigsForChain(chainId, PAY_CRYPTO_TOKEN_SYMBOLS))
+        .filter((token) => resolvePayCryptoTokenConfigByAddress(token.chainId, token.address) !== null);
+}
+/** The address formats a cashout address can take. */
+export const CashoutAddressFamily = {
+    EVM: 'EVM',
+    SOLANA: 'SOLANA',
+    TRON: 'TRON',
+    BITCOIN: 'BITCOIN',
+    ZCASH: 'ZCASH',
+};
+/**
+ * The address format a cashout address on this chain must have. Bitcoin, Solana and Tron map by id;
+ * Zcash is ZCASH (transparent addresses only, Zcash spec Z3). Every remaining chain in the pay-crypto token table
+ * is EVM; any other chain has none (null).
+ * Deliberately not isEvmChain, which answers true for unknown ids, Bitcoin's included.
+ */
+export function cashoutAddressFamily(chainId) {
+    if (chainId === BITCOIN_CHAIN_ID)
+        return CashoutAddressFamily.BITCOIN;
+    if (chainId === SOLANA_CHAIN_ID)
+        return CashoutAddressFamily.SOLANA;
+    if (chainId === TRON_CHAIN_ID)
+        return CashoutAddressFamily.TRON;
+    if (chainId === ZCASH_CHAIN_ID)
+        return CashoutAddressFamily.ZCASH;
+    if (CHAIN_TOKEN_CONFIGS[chainId] === undefined)
+        return null;
+    return CashoutAddressFamily.EVM;
+}
+/** Every chain a cashout can pay out on, ascending: each pay-crypto chain, Zcash included (through NEAR Intents). */
+export const CASHOUT_PAYOUT_CHAIN_IDS = Object.keys(CHAIN_TOKEN_CONFIGS).map(Number);
+/** The catalog token at tokenAddress on a payout chain, spelled as the catalog spells it; null off the catalog. */
+export function resolveCashoutPayoutToken(chainId, tokenAddress) {
+    if (!CASHOUT_PAYOUT_CHAIN_IDS.includes(chainId))
+        return null;
+    return resolvePayCryptoTokenConfigByAddress(chainId, tokenAddress);
+}
+/** Chains whose explorer paths differ from the EVM `{explorer}/tx/` and `{explorer}/address/` forms. */
+const PAY_CRYPTO_EXPLORER_PATHS = {
+    [SOLANA_CHAIN_ID]: { tx: 'https://solscan.io/tx/', address: 'https://solscan.io/account/' },
+    [TRON_CHAIN_ID]: { tx: 'https://tronscan.org/#/transaction/', address: 'https://tronscan.org/#/address/' },
+    [BITCOIN_CHAIN_ID]: { tx: 'https://mempool.space/tx/', address: 'https://mempool.space/address/' },
+    [ZCASH_CHAIN_ID]: { tx: 'https://blockchair.com/zcash/transaction/', address: 'https://blockchair.com/zcash/address/' },
+};
+export function getPayCryptoTxUrl(chainId, txHash) {
+    const paths = PAY_CRYPTO_EXPLORER_PATHS[chainId];
+    if (paths !== undefined)
+        return `${paths.tx}${txHash}`;
+    const explorer = getExplorerUrl(chainId);
+    return explorer === undefined ? null : `${explorer}/tx/${txHash}`;
+}
+export function getPayCryptoAddressUrl(chainId, address) {
+    const paths = PAY_CRYPTO_EXPLORER_PATHS[chainId];
+    if (paths !== undefined)
+        return `${paths.address}${address}`;
+    const explorer = getExplorerUrl(chainId);
+    return explorer === undefined ? null : `${explorer}/address/${address}`;
+}
+const DISPLAY_SIGNIFICANT_DIGITS = 6;
+/**
+ * Display form of an estimate or a delivered amount (any-coin spec "Units of amounts"): stablecoins round down to two
+ * decimals, other tokens to six significant digits; trailing zeros go and the integer part is grouped with commas.
+ * The input is already exact in the token's decimals, so the result never shows more decimals than the token has.
+ */
+export function formatPayCryptoDisplayAmount(amount, symbol) {
+    const match = /^(\d+)(?:\.(\d+))?$/u.exec(amount);
+    if (match === null)
+        throw new Error(`Not a decimal amount: ${amount}`);
+    const integer = match[1].replace(/^0+(?=\d)/u, '');
+    const fraction = match[2] ?? '';
+    let keptInteger = integer;
+    let keptFraction;
+    if (isStablecoinSymbol(symbol)) {
+        keptFraction = fraction.slice(0, 2);
+    }
+    else {
+        const first = `${integer}${fraction}`.search(/[1-9]/u);
+        if (first === -1)
+            return '0';
+        const cut = first + DISPLAY_SIGNIFICANT_DIGITS;
+        if (cut <= integer.length) {
+            keptInteger = `${integer.slice(0, cut)}${'0'.repeat(integer.length - cut)}`;
+            keptFraction = '';
+        }
+        else {
+            keptFraction = fraction.slice(0, cut - integer.length);
+        }
+    }
+    const trimmed = keptFraction.replace(/0+$/u, '');
+    const grouped = keptInteger.replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
+    return trimmed === '' ? grouped : `${grouped}.${trimmed}`;
+}