@zkp2p/pay-shared 5.0.0 → 7.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@5.0.0
+npm install @zkp2p/pay-shared@7.0.0
 ```
 
 ## Published artifacts
@@ -85,6 +85,10 @@ Core type exports:
 - `CheckoutAggregate`
 - `CheckoutQuotes`
 - `MerchantProfile`
+- `PayoutView`
+- `PayoutRailType`
+- `WebhookPayload`
+- `PayoutWebhookPayload`
 
 Core constants:
 
@@ -96,6 +100,15 @@ Core constants:
 - `ProofAttemptStatus`
 - `OrderErrorCode`
 - `MerchantEnvironment`
+- `PayoutStatus`
+- `PayoutRail`
+- `PayoutCryptoRail`
+- `PayoutProvider`
+- `PAY_CRYPTO_TOKEN_SYMBOLS`
+
+Webhook helpers:
+
+- `isPayoutWebhook(...)` — narrows `WebhookPayload` to `PayoutWebhookPayload`
 
 Chain constants and helpers:
 

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/cashoutCurrencies.d.ts

@@ -0,0 +1,109 @@
+import { type PayoutFiatRailType } from './types.js';
+/** Currency metadata in selector order. Names follow the SDK's currencyInfo. */
+export declare const PAYOUT_CURRENCY_INFO: {
+    readonly USD: {
+        readonly name: "United States Dollar";
+        readonly prefix: "$";
+        readonly minorUnits: 2;
+    };
+    readonly EUR: {
+        readonly name: "Euro";
+        readonly prefix: "€";
+        readonly minorUnits: 2;
+    };
+    readonly GBP: {
+        readonly name: "British Pound";
+        readonly prefix: "£";
+        readonly minorUnits: 2;
+    };
+    readonly AUD: {
+        readonly name: "Australian Dollar";
+        readonly prefix: "A$";
+        readonly minorUnits: 2;
+    };
+    readonly CAD: {
+        readonly name: "Canadian Dollar";
+        readonly prefix: "C$";
+        readonly minorUnits: 2;
+    };
+    readonly CHF: {
+        readonly name: "Swiss Franc";
+        readonly prefix: "CHF ";
+        readonly minorUnits: 2;
+    };
+    readonly CNY: {
+        readonly name: "Chinese Yuan";
+        readonly prefix: "CN¥";
+        readonly minorUnits: 2;
+    };
+    readonly MXN: {
+        readonly name: "Mexican Peso";
+        readonly prefix: "MX$";
+        readonly minorUnits: 2;
+    };
+    readonly NZD: {
+        readonly name: "New Zealand Dollar";
+        readonly prefix: "NZ$";
+        readonly minorUnits: 2;
+    };
+    readonly SGD: {
+        readonly name: "Singapore Dollar";
+        readonly prefix: "S$";
+        readonly minorUnits: 2;
+    };
+    readonly TRY: {
+        readonly name: "Turkish Lira";
+        readonly prefix: "₺";
+        readonly minorUnits: 2;
+    };
+    readonly ZAR: {
+        readonly name: "South African Rand";
+        readonly prefix: "R";
+        readonly minorUnits: 2;
+    };
+};
+export type PayoutCurrencyType = keyof typeof PAYOUT_CURRENCY_INFO;
+/** Every currency but USD: priced by the protocol oracle at zero spread, bound when a buyer signals. */
+export type PayoutOracleCurrencyType = Exclude<PayoutCurrencyType, 'USD'>;
+export declare const PayoutCurrency: { readonly [K in PayoutCurrencyType]: K; };
+/** Oracle currencies in catalog order; payoutCurrencies follows it. */
+export declare const PAYOUT_ORACLE_CURRENCIES: PayoutOracleCurrencyType[];
+/** Each rail's supported currencies, USD first then selector order. The API validates every pair against the SDK at boot. */
+export declare const PAYOUT_RAIL_CURRENCIES: {
+    readonly venmo: readonly ["USD"];
+    readonly cashapp: readonly ["USD"];
+    readonly paypal: readonly ["USD", "EUR", "GBP", "AUD", "CAD", "NZD", "SGD"];
+    readonly zelle: readonly ["USD"];
+    readonly revolut: readonly ["USD", "EUR", "GBP", "AUD", "CAD", "CHF", "CNY", "MXN", "NZD", "SGD", "TRY", "ZAR"];
+    readonly chime: readonly ["USD"];
+};
+export declare const PAYOUT_CURRENCY_NAMES: Readonly<Record<"USD" | "EUR" | "GBP" | "AUD" | "CAD" | "CHF" | "CNY" | "MXN" | "NZD" | "SGD" | "TRY" | "ZAR", string>>;
+export declare const PAYOUT_CURRENCY_SYMBOLS: Readonly<Record<"USD" | "EUR" | "GBP" | "AUD" | "CAD" | "CHF" | "CNY" | "MXN" | "NZD" | "SGD" | "TRY" | "ZAR", string>>;
+/** A USD listing's rate: exactly 1.00 USD per USDC in 18-decimal units; USD never uses an oracle. */
+export declare const CASHOUT_FIXED_USD_RATE: bigint;
+/** An oracle listing's fixed floor; below any market rate, so the escrow's effective rate is the oracle's (cash's ORACLE_MIN_CONVERSION_RATE_SENTINEL). */
+export declare const CASHOUT_ORACLE_MIN_RATE_SENTINEL = 1n;
+/** A fiat amount: `amount` is a decimal string with exactly 2 decimals. */
+export interface PayoutFiatValue {
+    currency: PayoutCurrencyType;
+    amount: string;
+}
+export declare function isPayoutCurrency(value: string): value is PayoutCurrencyType;
+export declare function isCashoutOracleCurrency(value: string): value is PayoutOracleCurrencyType;
+export declare function payoutRailPaysCurrency(rail: PayoutFiatRailType, currency: PayoutCurrencyType): boolean;
+/** A rail whose payout-method request carries `currency`: its catalog has more than one. */
+export declare function isPayoutMultiCurrencyRail(rail: PayoutFiatRailType): boolean;
+/**
+ * Fiat cents for `units` USDC base units at `rate` (fiat per USDC, 18 decimals), rounded up: Curator's buyer quote rule.
+ * While a USDC unit is worth less than a cent (rate below 10,000), it recovers exactly the cents a buyer paid from the
+ * attestation's floored release amount.
+ */
+export declare function payoutFiatCents(units: bigint, rate: bigint): bigint;
+export declare function formatPayoutFiatCents(cents: bigint): string;
+/** Fiat per USDC with 6 decimals, rounded half up: "0.892698". Display only. */
+export declare function formatPayoutRate(rate: bigint): string;
+/** A stored 18-decimal rate; null unless it is a positive integer string without leading zeros. */
+export declare function parseCashoutRate(value: string | null): bigint | null;
+export declare function cashoutFiatValue(currency: PayoutCurrencyType, units: bigint, rate: bigint): PayoutFiatValue;
+/** Group a non-negative fiat amount with exactly two decimals; reject malformed amounts and preserve cents beyond Number's safe range. */
+export declare function formatPayoutFiatValue(value: PayoutFiatValue): string;

package/dist/cashoutCurrencies.js

@@ -0,0 +1,94 @@
+import { PayoutFiatRail } from './types.js';
+/** Currency metadata in selector order. Names follow the SDK's currencyInfo. */
+export const PAYOUT_CURRENCY_INFO = {
+    USD: { name: 'United States Dollar', prefix: '$', minorUnits: 2 },
+    EUR: { name: 'Euro', prefix: '€', minorUnits: 2 },
+    GBP: { name: 'British Pound', prefix: '£', minorUnits: 2 },
+    AUD: { name: 'Australian Dollar', prefix: 'A$', minorUnits: 2 },
+    CAD: { name: 'Canadian Dollar', prefix: 'C$', minorUnits: 2 },
+    CHF: { name: 'Swiss Franc', prefix: 'CHF ', minorUnits: 2 },
+    CNY: { name: 'Chinese Yuan', prefix: 'CN¥', minorUnits: 2 },
+    MXN: { name: 'Mexican Peso', prefix: 'MX$', minorUnits: 2 },
+    NZD: { name: 'New Zealand Dollar', prefix: 'NZ$', minorUnits: 2 },
+    SGD: { name: 'Singapore Dollar', prefix: 'S$', minorUnits: 2 },
+    TRY: { name: 'Turkish Lira', prefix: '₺', minorUnits: 2 },
+    ZAR: { name: 'South African Rand', prefix: 'R', minorUnits: 2 },
+};
+// The keys of this local, closed catalog are exactly PayoutCurrencyType.
+const CURRENCY_CODES = Object.keys(PAYOUT_CURRENCY_INFO);
+// Every catalog key maps to itself; Object.fromEntries otherwise loses that key/value relationship.
+export const PayoutCurrency = Object.fromEntries(CURRENCY_CODES.map(code => [code, code]));
+/** Oracle currencies in catalog order; payoutCurrencies follows it. */
+export const PAYOUT_ORACLE_CURRENCIES = CURRENCY_CODES.filter((code) => code !== 'USD');
+/** Each rail's supported currencies, USD first then selector order. The API validates every pair against the SDK at boot. */
+export const PAYOUT_RAIL_CURRENCIES = {
+    [PayoutFiatRail.VENMO]: ['USD'],
+    [PayoutFiatRail.CASHAPP]: ['USD'],
+    [PayoutFiatRail.PAYPAL]: ['USD', 'EUR', 'GBP', 'AUD', 'CAD', 'NZD', 'SGD'],
+    [PayoutFiatRail.ZELLE]: ['USD'],
+    [PayoutFiatRail.REVOLUT]: ['USD', 'EUR', 'GBP', 'AUD', 'CAD', 'CHF', 'CNY', 'MXN', 'NZD', 'SGD', 'TRY', 'ZAR'],
+    [PayoutFiatRail.CHIME]: ['USD'],
+};
+function currencyLabels(field) {
+    // The mapping visits every catalog key once, preserving a complete record.
+    return Object.fromEntries(CURRENCY_CODES.map(code => [code, PAYOUT_CURRENCY_INFO[code][field]]));
+}
+export const PAYOUT_CURRENCY_NAMES = currencyLabels('name');
+export const PAYOUT_CURRENCY_SYMBOLS = currencyLabels('prefix');
+/** A USD listing's rate: exactly 1.00 USD per USDC in 18-decimal units; USD never uses an oracle. */
+export const CASHOUT_FIXED_USD_RATE = 10n ** 18n;
+/** An oracle listing's fixed floor; below any market rate, so the escrow's effective rate is the oracle's (cash's ORACLE_MIN_CONVERSION_RATE_SENTINEL). */
+export const CASHOUT_ORACLE_MIN_RATE_SENTINEL = 1n;
+const CURRENCY_SET = new Set(Object.values(PayoutCurrency));
+export function isPayoutCurrency(value) {
+    return CURRENCY_SET.has(value);
+}
+export function isCashoutOracleCurrency(value) {
+    return isPayoutCurrency(value) && value !== PayoutCurrency.USD;
+}
+export function payoutRailPaysCurrency(rail, currency) {
+    const currencies = PAYOUT_RAIL_CURRENCIES[rail];
+    return currencies.includes(currency);
+}
+/** A rail whose payout-method request carries `currency`: its catalog has more than one. */
+export function isPayoutMultiCurrencyRail(rail) {
+    return PAYOUT_RAIL_CURRENCIES[rail].length > 1;
+}
+/** 1e6 USDC units × 1e18 rate units ÷ 100 cents. */
+const CENTS_DENOMINATOR = 10n ** 22n;
+/**
+ * Fiat cents for `units` USDC base units at `rate` (fiat per USDC, 18 decimals), rounded up: Curator's buyer quote rule.
+ * While a USDC unit is worth less than a cent (rate below 10,000), it recovers exactly the cents a buyer paid from the
+ * attestation's floored release amount.
+ */
+export function payoutFiatCents(units, rate) {
+    if (units < 0n)
+        throw new Error('USDC units must not be negative');
+    if (rate <= 0n)
+        throw new Error('Rate must be positive');
+    return (units * rate + CENTS_DENOMINATOR - 1n) / CENTS_DENOMINATOR;
+}
+export function formatPayoutFiatCents(cents) {
+    return `${cents / 100n}.${(cents % 100n).toString().padStart(2, '0')}`;
+}
+/** Fiat per USDC with 6 decimals, rounded half up: "0.892698". Display only. */
+export function formatPayoutRate(rate) {
+    const micro = (rate + 500000000000n) / 1000000000000n;
+    return `${micro / 1000000n}.${(micro % 1000000n).toString().padStart(6, '0')}`;
+}
+/** A stored 18-decimal rate; null unless it is a positive integer string without leading zeros. */
+export function parseCashoutRate(value) {
+    if (value === null || !/^[1-9][0-9]{0,77}$/u.test(value))
+        return null;
+    return BigInt(value);
+}
+export function cashoutFiatValue(currency, units, rate) {
+    return { currency, amount: formatPayoutFiatCents(payoutFiatCents(units, rate)) };
+}
+/** Group a non-negative fiat amount with exactly two decimals; reject malformed amounts and preserve cents beyond Number's safe range. */
+export function formatPayoutFiatValue(value) {
+    if (!/^[0-9]+\.[0-9]{2}$/u.test(value.amount))
+        throw new Error('Fiat amount must have exactly two decimals');
+    const [whole, fraction] = value.amount.split('.');
+    return `${PAYOUT_CURRENCY_SYMBOLS[value.currency]}${whole.replace(/\B(?=(\d{3})+(?!\d))/gu, ',')}.${fraction}`;
+}

package/dist/cashoutRails.d.ts

@@ -0,0 +1,34 @@
+import { type CashoutBuyerProofRailType, type PayoutCryptoRailType, type PayoutFiatRailType, type PayoutSarRailType } 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<PayoutSarRailType>;
+/** A rail in CASHOUT_SAR_RAILS. Exact rails only; a variant such as "venmo-x" is not a payout rail. */
+export declare function isPayoutSarRail(rail: string): rail is PayoutSarRailType;
+/** 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 PAYOUT_CRYPTO_RAILS: ReadonlyArray<PayoutCryptoRailType>;
+/** An exact crypto payout rail; replaces every comparison with the retired `crypto` rail. */
+export declare function isPayoutCryptoRail(rail: string): rail is PayoutCryptoRailType;
+export declare function payoutCryptoRailChainId(rail: PayoutCryptoRailType): number;
+export declare function cashoutCryptoRailForChain(chainId: number): PayoutCryptoRailType | 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 hasPayoutCryptoRail(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 payoutAccountLabel(rail: PayoutFiatRailType, handle: string): string;

package/dist/cashoutRails.js

@@ -0,0 +1,71 @@
+import { SAR_SUPPORTED_FIAT_RAILS, parseCryptoRailChainId } from './rails.js';
+import { PayoutCryptoRail, PayoutFiatRail, PayoutRail, } from './types.js';
+const CASHOUT_FIAT_RAIL_SET = new Set(Object.values(PayoutFiatRail));
+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(PayoutFiatRail).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 payout rail. */
+export function isPayoutSarRail(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 PAYOUT_CRYPTO_RAILS = Object.values(PayoutCryptoRail);
+const CASHOUT_CRYPTO_RAIL_SET = new Set(PAYOUT_CRYPTO_RAILS);
+/** An exact crypto payout rail; replaces every comparison with the retired `crypto` rail. */
+export function isPayoutCryptoRail(rail) {
+    return CASHOUT_CRYPTO_RAIL_SET.has(rail);
+}
+export function payoutCryptoRailChainId(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(PAYOUT_CRYPTO_RAILS.map((rail) => [payoutCryptoRailChainId(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 PAYOUT_CRYPTO_RAILS.filter((rail) => rails.includes(rail)).map(payoutCryptoRailChainId);
+}
+export function hasPayoutCryptoRail(rails) {
+    return rails.some(isPayoutCryptoRail);
+}
+/**
+ * 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 = [PayoutRail.VENMO, PayoutRail.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 payoutAccountLabel(rail, handle) {
+    switch (rail) {
+        case PayoutRail.VENMO:
+        case PayoutRail.REVOLUT:
+            return `@${handle.replace(/^@/u, '')}`;
+        case PayoutRail.CASHAPP:
+            return `$${handle.replace(/^\$/u, '')}`;
+        case PayoutRail.PAYPAL:
+            return `paypal.me/${handle}`;
+        case PayoutRail.ZELLE:
+        case PayoutRail.CHIME:
+            return handle;
+    }
+}

package/dist/crypto.d.ts

@@ -1,6 +1,8 @@
 export declare const BITCOIN_CHAIN_ID = 8253038;
 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[];
@@ -21,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[];
@@ -64,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 payout can be funded from through Relay. Zcash is out: ZEC funding is out of scope (2026-10-07). */
+export declare const PAYOUT_FUNDING_CHAIN_IDS: readonly number[];
+/**
+ * The tokens a payout 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 getPayoutFundingTokenConfigs(): 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,8 +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',
@@ -52,7 +54,8 @@ 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' },
@@ -67,7 +70,7 @@ const CHAIN_TOKEN_CONFIGS = {
         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 },
@@ -296,3 +299,107 @@ export function getSupportedDestinationBalanceTokenConfigsForChain(chainId, enab
 export function resolveDestinationBalanceTokenConfig(chainId, symbol) {
     return resolvePayCryptoTokenConfig(chainId, symbol);
 }
+/** Chains a payout can be funded from through Relay. Zcash is out: ZEC funding is out of scope (2026-10-07). */
+export const PAYOUT_FUNDING_CHAIN_IDS = [
+    ETHEREUM_CHAIN_ID, 10, 56, 137, 480, HYPEREVM_CHAIN_ID, 5042, BASE_CHAIN_ID, 42161, BITCOIN_CHAIN_ID,
+];
+/**
+ * The tokens a payout 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 getPayoutFundingTokenConfigs() {
+    return getSupportedPayCryptoChainIds(PAY_CRYPTO_TOKEN_SYMBOLS)
+        .filter((chainId) => PAYOUT_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}`;
+}

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
 export * from './rails.js';
+export * from './cashoutRails.js';
+export * from './cashoutCurrencies.js';
 export * from './buyerTee.js';
 export * from './bitcoin.js';
 export * from './addressValidators.js';

package/dist/index.js

@@ -4,6 +4,8 @@ export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
 export * from './rails.js';
+export * from './cashoutRails.js';
+export * from './cashoutCurrencies.js';
 export * from './buyerTee.js';
 export * from './bitcoin.js';
 export * from './addressValidators.js';