@zkp2p/pay-shared 5.0.0 → 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@5.0.0
+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:
 

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/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 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,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 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}`;
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { PayCryptoTokenSymbol } from './crypto.js';
 import type { ProofMode } from './buyerTee.js';
 import type { OnboardingStepIdValue } from './onboarding.js';
+import type { SarSupportedFiatRail } from './rails.js';
 export declare const PaymentPlatform: {
     readonly VENMO: "venmo";
     readonly CASHAPP: "cashapp";
@@ -1043,8 +1044,21 @@ export declare const WebhookEventType: {
     readonly PAYMENT_CHARGEBACKED: "PAYMENT_CHARGEBACKED";
     readonly ORDER_PARTIALLY_CHARGEBACKED: "ORDER_PARTIALLY_CHARGEBACKED";
     readonly ORDER_CHARGEBACKED: "ORDER_CHARGEBACKED";
+    readonly CASHOUT_ORDER_CREATED: "CASHOUT_ORDER_CREATED";
+    readonly CASHOUT_ORDER_CANCELLED: "CASHOUT_ORDER_CANCELLED";
+    readonly CASHOUT_ORDER_PARTIALLY_FUNDED: "CASHOUT_ORDER_PARTIALLY_FUNDED";
+    readonly CASHOUT_ORDER_FUNDED: "CASHOUT_ORDER_FUNDED";
+    readonly CASHOUT_ORDER_MATCHED: "CASHOUT_ORDER_MATCHED";
+    readonly CASHOUT_ORDER_PARTIALLY_PAID: "CASHOUT_ORDER_PARTIALLY_PAID";
+    readonly CASHOUT_ORDER_SETTLED: "CASHOUT_ORDER_SETTLED";
+    readonly CASHOUT_ORDER_EXPIRED: "CASHOUT_ORDER_EXPIRED";
 };
 export type WebhookEventTypeValue = typeof WebhookEventType[keyof typeof WebhookEventType];
+/** Cashout events carry a CashoutView, not the order envelope. */
+export declare const CASHOUT_WEBHOOK_EVENT_TYPES: readonly ["CASHOUT_ORDER_CREATED", "CASHOUT_ORDER_CANCELLED", "CASHOUT_ORDER_PARTIALLY_FUNDED", "CASHOUT_ORDER_FUNDED", "CASHOUT_ORDER_MATCHED", "CASHOUT_ORDER_PARTIALLY_PAID", "CASHOUT_ORDER_SETTLED", "CASHOUT_ORDER_EXPIRED"];
+export type CashoutWebhookEventTypeValue = typeof CASHOUT_WEBHOOK_EVENT_TYPES[number];
+export type OrderWebhookEventTypeValue = Exclude<WebhookEventTypeValue, CashoutWebhookEventTypeValue>;
+export declare function isCashoutWebhookEventType(type: string): type is CashoutWebhookEventTypeValue;
 export declare const WebhookDeliveryStatus: {
     readonly PENDING: "PENDING";
     readonly DELIVERED: "DELIVERED";
@@ -1077,9 +1091,9 @@ export type WebhookDelivery = {
     responseCode?: number | null;
     createdAt: string;
 };
-export type WebhookPayload = {
+export type OrderWebhookPayload = {
     id: string;
-    type: WebhookEventTypeValue;
+    type: OrderWebhookEventTypeValue;
     timestamp: string;
     data: {
         order: CheckoutOrder | null;
@@ -1101,6 +1115,45 @@ export type WebhookPayload = {
         amountChange?: OrderAmountChange;
     };
 };
+/** Bumped only on a breaking change to a cashout payload. */
+export declare const CASHOUT_WEBHOOK_VERSION = 1;
+/** One buyer payment that left part of the cashout unpaid; decimal USDC. */
+export interface CashoutPartialPayment {
+    /** The cashout's depositAmount: what buyers can pay in total. */
+    expectedAmount: string;
+    /** What buyers have paid so far, this fill included. */
+    paidAmount: string;
+    /** expectedAmount − paidAmount. */
+    remainingAmount: string;
+    fill: {
+        amount: string;
+        txHash: string;
+    };
+}
+export type CashoutWebhookEventData = {
+    readonly type: Exclude<CashoutWebhookEventTypeValue, typeof WebhookEventType.CASHOUT_ORDER_PARTIALLY_PAID>;
+    readonly data: CashoutView;
+} | {
+    readonly type: typeof WebhookEventType.CASHOUT_ORDER_PARTIALLY_PAID;
+    readonly data: CashoutView;
+    readonly partialPayment: CashoutPartialPayment;
+};
+export type CashoutWebhookPayload = {
+    id: string;
+    type: Exclude<CashoutWebhookEventTypeValue, typeof WebhookEventType.CASHOUT_ORDER_PARTIALLY_PAID>;
+    timestamp: string;
+    version: typeof CASHOUT_WEBHOOK_VERSION;
+    data: CashoutView;
+} | {
+    id: string;
+    type: typeof WebhookEventType.CASHOUT_ORDER_PARTIALLY_PAID;
+    timestamp: string;
+    version: typeof CASHOUT_WEBHOOK_VERSION;
+    data: CashoutView;
+    partialPayment: CashoutPartialPayment;
+};
+export type WebhookPayload = OrderWebhookPayload | CashoutWebhookPayload;
+export declare function isCashoutWebhook(payload: WebhookPayload): payload is CashoutWebhookPayload;
 export type CreateWebhookRequest = {
     url: string;
     events?: WebhookEventTypeValue[];
@@ -1201,4 +1254,614 @@ export type OwnershipTransferMasterMerchantPermissionType = typeof OwnershipTran
 export declare const OWNERSHIP_TRANSFER_MASTER_MERCHANT_PERMISSIONS: readonly OwnershipTransferMasterMerchantPermissionType[];
 /** "alice@example.com" → "a•••@example.com". The input is a validated, lowercased address. */
 export declare function maskOwnershipTransferEmail(email: string): string;
+export declare const CashoutStatus: {
+    readonly AWAITING_FUNDING: "AWAITING_FUNDING";
+    readonly FUNDED: "FUNDED";
+    readonly READY: "READY";
+    readonly LISTING: "LISTING";
+    readonly PAYING: "PAYING";
+    readonly SETTLED: "SETTLED";
+    readonly CANCELLING: "CANCELLING";
+    readonly CANCELLED: "CANCELLED";
+    readonly EXPIRED: "EXPIRED";
+};
+export type CashoutStatusType = typeof CashoutStatus[keyof typeof CashoutStatus];
+export declare const CashoutFundingStatus: {
+    readonly AWAITING_FUNDING: "AWAITING_FUNDING";
+    readonly PARTIALLY_FUNDED: "PARTIALLY_FUNDED";
+    readonly FUNDED: "FUNDED";
+    readonly FUNDING_EXPIRED: "FUNDING_EXPIRED";
+};
+export type CashoutFundingStatusType = typeof CashoutFundingStatus[keyof typeof CashoutFundingStatus];
+export declare const CashoutCancelSource: {
+    readonly CHECKOUT: "CHECKOUT";
+    readonly MERCHANT: "MERCHANT";
+    readonly PEER_APP: "PEER_APP";
+};
+export type CashoutCancelSourceType = typeof CashoutCancelSource[keyof typeof CashoutCancelSource];
+export declare const CashoutPayoutKind: {
+    readonly ESCROW: "ESCROW";
+    readonly CRYPTO: "CRYPTO";
+};
+export type CashoutPayoutKindType = typeof CashoutPayoutKind[keyof typeof CashoutPayoutKind];
+export declare const CashoutAttemptStatus: {
+    readonly ACTIVE: "ACTIVE";
+    readonly CLOSED: "CLOSED";
+    readonly SETTLED: "SETTLED";
+    readonly FAILED: "FAILED";
+};
+export type CashoutAttemptStatusType = typeof CashoutAttemptStatus[keyof typeof CashoutAttemptStatus];
+/** Fiat payout methods, in the order players see them: SAR rails, then buyer-proof rails. */
+export declare const CashoutFiatRail: {
+    readonly VENMO: "venmo";
+    readonly CASHAPP: "cashapp";
+    readonly PAYPAL: "paypal";
+    readonly ZELLE: "zelle";
+    readonly REVOLUT: "revolut";
+    readonly CHIME: "chime";
+};
+export type CashoutFiatRailType = typeof CashoutFiatRail[keyof typeof CashoutFiatRail];
+/** One rail per crypto payout network, with checkout's rail ids (any-coin spec "Cashout rails"); the player sees them as one "Crypto" option. */
+export declare const CashoutCryptoRail: {
+    readonly RELAY_1: "relay_1";
+    readonly RELAY_10: "relay_10";
+    readonly RELAY_56: "relay_56";
+    readonly RELAY_137: "relay_137";
+    readonly RELAY_480: "relay_480";
+    readonly RELAY_999: "relay_999";
+    readonly RELAY_5042: "relay_5042";
+    readonly RELAY_8453: "relay_8453";
+    readonly RELAY_42161: "relay_42161";
+    readonly RELAY_8253038: "relay_8253038";
+    readonly RELAY_728126428: "relay_728126428";
+    readonly RELAY_792703809: "relay_792703809";
+    /** ZEC on Zcash through NEAR Intents (Zcash spec "Catalog, route and address"); checkout's ZCASH_RAIL. */
+    readonly NEAR_INTENTS_133701: "near_intents_133701";
+};
+export type CashoutCryptoRailType = typeof CashoutCryptoRail[keyof typeof CashoutCryptoRail];
+/** Every cashout rail, in rail order: fiat, then the crypto networks. */
+export declare const CashoutRail: {
+    readonly RELAY_1: "relay_1";
+    readonly RELAY_10: "relay_10";
+    readonly RELAY_56: "relay_56";
+    readonly RELAY_137: "relay_137";
+    readonly RELAY_480: "relay_480";
+    readonly RELAY_999: "relay_999";
+    readonly RELAY_5042: "relay_5042";
+    readonly RELAY_8453: "relay_8453";
+    readonly RELAY_42161: "relay_42161";
+    readonly RELAY_8253038: "relay_8253038";
+    readonly RELAY_728126428: "relay_728126428";
+    readonly RELAY_792703809: "relay_792703809";
+    /** ZEC on Zcash through NEAR Intents (Zcash spec "Catalog, route and address"); checkout's ZCASH_RAIL. */
+    readonly NEAR_INTENTS_133701: "near_intents_133701";
+    readonly VENMO: "venmo";
+    readonly CASHAPP: "cashapp";
+    readonly PAYPAL: "paypal";
+    readonly ZELLE: "zelle";
+    readonly REVOLUT: "revolut";
+    readonly CHIME: "chime";
+};
+export type CashoutRailType = CashoutFiatRailType | CashoutCryptoRailType;
+/** Fiat rails whose account the player connects so Peer can confirm buyer payments; derived from SAR_SUPPORTED_FIAT_RAILS. */
+export type CashoutSarRailType = Extract<CashoutFiatRailType, SarSupportedFiatRail>;
+/** Fiat rails with no connect step: the buyer proves the payment with the PeerAuth extension or the Peer app. */
+export type CashoutBuyerProofRailType = Exclude<CashoutFiatRailType, CashoutSarRailType>;
+export declare const CashoutPayoutProvider: {
+    readonly RELAY: "RELAY";
+    readonly NEAR_INTENTS: "NEAR_INTENTS";
+};
+export type CashoutPayoutProviderType = typeof CashoutPayoutProvider[keyof typeof CashoutPayoutProvider];
+export declare const CashoutPayoutBridgeStatus: {
+    readonly QUOTED: "QUOTED";
+    readonly NOT_SENT: "NOT_SENT";
+    readonly BRIDGING: "BRIDGING";
+    readonly DELIVERED: "DELIVERED";
+    readonly REFUNDED: "REFUNDED";
+};
+export type CashoutPayoutBridgeStatusType = typeof CashoutPayoutBridgeStatus[keyof typeof CashoutPayoutBridgeStatus];
+/** A crypto payout's coin, network and the player's address there. */
+export interface CashoutCryptoDestination {
+    chainId: number;
+    /** The shared catalog's address for the token on chainId. */
+    tokenAddress: string;
+    symbol: PayCryptoTokenSymbol;
+    decimals: number;
+    /** Canonical: EVM checksummed, bech32 lower-case, base58 as entered. */
+    address: string;
+}
+/** Body of the crypto payout-method, payout-quote and send-to-address requests. The rail names the network. */
+export interface CashoutPayoutDestinationRequest {
+    rail: CashoutCryptoRailType;
+    tokenAddress: string;
+    address: string;
+}
+/** A crypto payout method: the network's rail and where on it the player takes the payout. */
+export interface CashoutCryptoMethod {
+    rail: CashoutCryptoRailType;
+    destination: CashoutCryptoDestination;
+}
+/** POST /api/v1/cashout-checkout/:id/payout-quote. Not a promise. */
+export interface CashoutPayoutQuote {
+    destination: CashoutCryptoDestination;
+    /** Decimal USDC that would leave the player's wallet. */
+    usdcAmount: string;
+    /** Decimal destination token; equals usdcAmount for USDC on Base. */
+    estimatedAmount: string;
+    quotedAt: string;
+}
+/** The player's bridged payout, newest attempt first; never NOT_SENT. */
+export interface CashoutPayoutBridgeView {
+    provider: CashoutPayoutProviderType;
+    status: Exclude<CashoutPayoutBridgeStatusType, typeof CashoutPayoutBridgeStatus.NOT_SENT>;
+    destination: CashoutCryptoDestination;
+    usdcAmount: string;
+    /** The binding quote's output, decimal destination token. */
+    estimatedAmount: string;
+    deliveredAmount: string | null;
+    destinationTxHash: string | null;
+    /** Decimal USDC. */
+    refundedAmount: string | null;
+    refundTxHash: string | null;
+}
+export interface CashoutPartialFillView {
+    /** Decimal USDC this buyer paid. */
+    amount: string;
+    txHash: string;
+    paidAt: string;
+}
+/** Where a SETTLED cashout's USDC ended up; decimal USDC, "0.00" for a part that did not happen. */
+export interface CashoutSettlementBreakdown {
+    /** Paid by buyers through the escrow, across every listing. */
+    buyerPaidAmount: string;
+    /** USDC that left the player's wallet for a crypto payout (direct or bridged) or a send-to-address remainder. */
+    sentAmount: string;
+    /** The player's recipient: EVM lower-case, Solana, Tron and Bitcoin canonical; never a deposit address. */
+    sentTo: string | null;
+    /** Left in, or returned to, the player's Peer wallet. */
+    returnedAmount: string;
+    /** Swept by the escrow as dust when it closed the deposit. */
+    dustAmount: string;
+    /** Σ refundLossUnits: USDC Relay kept on refunds; "0.00" when none. */
+    refundFeeAmount: string;
+}
+/** Merchant-facing cashout. Never includes the Peer fee, the player's email, wallet or payee handle. */
+export interface CashoutView {
+    cashoutId: string;
+    merchantReference: string | null;
+    status: CashoutStatusType;
+    fundingStatus: CashoutFundingStatusType;
+    payout: {
+        amount: string;
+        chainId: number;
+        tokenAddress: string;
+        decimals: number;
+    };
+    merchantFee: {
+        bps: number;
+        amount: string;
+    };
+    funding: {
+        chainId: number;
+        tokenAddress: string;
+        decimals: number;
+        /** Quoted amount to send, decimal funding token. */
+        amount: string;
+        /** Sent before the deadline, decimal funding token. */
+        sentAmount: string;
+        /** amount − sentAmount, never below zero; decimal funding token. */
+        missingAmount: string;
+        /** Payout plus buffer: the USDC the quote delivers, decimal USDC. */
+        expectedAmount: string;
+        /** Reached the player's wallet on Base, decimal USDC. */
+        receivedAmount: string;
+        /** Null once the cashout can no longer be funded. */
+        depositAddress: string | null;
+        /** Funding deadline; each on-time arrival moves it to at least the funding TTL (24 hours by default) after that check. */
+        quoteExpiresAt: string;
+    };
+    depositAmount: string | null;
+    /** What buyers have paid across every listing, partial fills included. */
+    paidAmount: string;
+    partialFills: CashoutPartialFillView[];
+    /** Only when status is SETTLED. */
+    settlement: CashoutSettlementBreakdown | null;
+    attempt: {
+        kind: CashoutPayoutKindType;
+        rail: string | null;
+        status: CashoutAttemptStatusType;
+    } | null;
+    /** Only when settled with a sent amount, including a send-to-address remainder. */
+    payoutTransfer: {
+        /** Where the player received it. */
+        chainId: number;
+        tokenAddress: string;
+        decimals: number;
+        address: string;
+        /** Delivered, decimal destination token. */
+        amount: string;
+        /** The delivering transaction on chainId. */
+        txHash: string;
+        /** The USDC transfer on Base; settlement.sentAmount is its amount. */
+        usdcTxHash: string;
+        /** The bridge provider (RELAY or NEAR_INTENTS) when bridged; null for USDC on Base, where txHash = usdcTxHash. */
+        provider: CashoutPayoutProviderType | null;
+    } | null;
+    cancelSource: CashoutCancelSourceType | null;
+    returnUrl: string | null;
+    expiresAt: string;
+    fundedAt: string | null;
+    settledAt: string | null;
+    cancelledAt: string | null;
+    createdAt: string;
+}
+export interface CreateCashoutRequest {
+    merchantReference?: string;
+    customerEmail: string;
+    payout: {
+        amount: string;
+        chainId: number;
+        tokenAddress: string;
+    };
+    funding: {
+        chainId: number;
+        tokenAddress: string;
+        refundAddress?: string;
+    };
+    returnUrl?: string;
+    /** Limits the cashout to these rails; never widens the merchant's (any-coin spec "Cashout rails"). */
+    rails?: CashoutRailType[];
+}
+/** A replay with the same key and body returns the current checkout link, marked `idempotentReplay: true`. */
+export type CreateCashoutResponse = CashoutView & {
+    checkoutUrl: string;
+    idempotentReplay: boolean;
+};
+export interface ListCashoutsResponse {
+    items: CashoutView[];
+    page: number;
+    limit: number;
+    total: number;
+}
+/** A moment on a cashout's dashboard timeline. */
+export declare const CashoutTimelineEventType: {
+    readonly CREATED: "CREATED";
+    readonly PARTIALLY_FUNDED: "PARTIALLY_FUNDED";
+    readonly FUNDED: "FUNDED";
+    readonly FUNDING_EXPIRED: "FUNDING_EXPIRED";
+    readonly SIGNED_IN: "SIGNED_IN";
+    readonly METHOD_READY: "METHOD_READY";
+    readonly LISTED: "LISTED";
+    readonly TRANSFER_SENT: "TRANSFER_SENT";
+    readonly MATCHED: "MATCHED";
+    /** A buyer paid part of the listing; the rest is listed again or left for the player. */
+    readonly PARTIALLY_PAID: "PARTIALLY_PAID";
+    /** Pay set the deposit's intent range to what is left, so another buyer can take it. */
+    readonly RELISTED: "RELISTED";
+    readonly BUYER_DROPPED: "BUYER_DROPPED";
+    readonly RECONNECT_NEEDED: "RECONNECT_NEEDED";
+    readonly CANCEL_STARTED: "CANCEL_STARTED";
+    /** The listing came back to the player's wallet so they can pick another payout method. */
+    readonly LISTING_WITHDRAWN: "LISTING_WITHDRAWN";
+    readonly SETTLED: "SETTLED";
+    readonly CANCELLED: "CANCELLED";
+    readonly FUNDING_ISSUE: "FUNDING_ISSUE";
+    readonly PAYOUT_REFUNDED: "PAYOUT_REFUNDED";
+};
+export type CashoutTimelineEventTypeValue = typeof CashoutTimelineEventType[keyof typeof CashoutTimelineEventType];
+/** Largest merchant cashout payout step, in whole USDC. The smallest is the API's CASHOUT_MIN_USDC (10 in production). */
+export declare const CASHOUT_PAYOUT_STEP_MAX_USDC = 1000;
+/** Whole-USDC bounds for a merchant's cashout payout step in this environment. */
+export interface CashoutPayoutStepRange {
+    min: number;
+    max: number;
+}
+/** A merchant's cashout settings; the Peer fee is not the merchant's to see. */
+export interface CashoutSettings {
+    rails: CashoutRailType[];
+    /** Merchant fee in bps of the deposit, 0–1000. */
+    feeBps: number;
+    /** Whole USDC, within the environment's payout step range. */
+    payoutStepUsdc: number;
+    /** An https URL or a mailto: link; optional. Without it the player's checkout shows no contact line. */
+    supportUrl: string | null;
+}
+export declare const CashoutFundingIssueKind: {
+    readonly LATE_FUNDS: "LATE_FUNDS";
+    readonly OVERPAYMENT: "OVERPAYMENT";
+    readonly ROUTE_REFUND: "ROUTE_REFUND";
+};
+export type CashoutFundingIssueKindType = typeof CashoutFundingIssueKind[keyof typeof CashoutFundingIssueKind];
+export declare const CashoutFundingIssueResolution: {
+    readonly RETURNED: "RETURNED";
+    readonly CLAIMED: "CLAIMED";
+};
+export type CashoutFundingIssueResolutionType = typeof CashoutFundingIssueResolution[keyof typeof CashoutFundingIssueResolution];
+/** A funding token as offered to a merchant: `key` is "chainId:lowercaseAddress". */
+export interface CashoutFundingTokenOption {
+    key: string;
+    chainId: number;
+    address: string;
+    symbol: string;
+}
+/** GET /merchants/me/cashout-settings: the saved settings plus what Peer currently allows. */
+export interface CashoutSettingsView extends CashoutSettings {
+    availableRails: CashoutRailType[];
+    availableFundingTokens: CashoutFundingTokenOption[];
+    payoutStepRange: CashoutPayoutStepRange;
+}
+/** Merchant-facing; never includes the admin's note or name. */
+export interface MerchantCashoutFundingIssue {
+    kind: CashoutFundingIssueKindType;
+    /** Decimal USDC; null for a route refund, which is paid back in the origin token. */
+    amountUsdc: string | null;
+    txHash: string | null;
+    detectedAt: string;
+    resolution: CashoutFundingIssueResolutionType | null;
+    resolutionTxHash: string | null;
+    resolvedAt: string | null;
+}
+export type CashoutPayoutMethodView = {
+    rail: CashoutFiatRailType;
+    handle: string;
+} | CashoutCryptoMethod;
+/** The dashboard's cashout: the API view plus what only the merchant's staff may see. */
+export interface MerchantCashoutView extends CashoutView {
+    /** The player's email as given at create, stored lower-cased. */
+    customerEmail: string;
+    payoutMethod: CashoutPayoutMethodView | null;
+    /** Null once the cashout is final. */
+    checkoutUrl: string | null;
+}
+export interface CashoutTimelineEntry {
+    type: CashoutTimelineEventTypeValue;
+    text: string;
+    txHash: string | null;
+    /** The chain txHash is on; null when txHash isn't linked. */
+    txChainId: number | null;
+    occurredAt: string;
+}
+export interface CashoutWebhookDeliveryView {
+    eventType: string;
+    status: string;
+    attempts: number;
+    responseCode: number | null;
+    lastAttemptAt: string | null;
+    createdAt: string;
+}
+export interface MerchantCashoutDetail {
+    cashout: MerchantCashoutView;
+    timeline: CashoutTimelineEntry[];
+    /** Not stored: what happens next from the current status, or null when final. */
+    nextStep: string | null;
+    webhooks: CashoutWebhookDeliveryView[];
+    fundingIssues: MerchantCashoutFundingIssue[];
+}
+/** The dashboard's create form result; a replay returns the same cashout and its current link. */
+export type CreateMerchantCashoutResponse = MerchantCashoutView & {
+    idempotentReplay: boolean;
+};
+export interface ListMerchantCashoutsResponse {
+    items: MerchantCashoutView[];
+    page: number;
+    limit: number;
+    total: number;
+}
+export interface AdminCashoutSettings {
+    disabledRails: CashoutRailType[];
+    disabledFundingTokens: string[];
+    peerFeeRecipient: string;
+    supportedFundingTokens: CashoutFundingTokenOption[];
+    updatedAt: string;
+}
+export interface AdminCashoutMerchantConfig {
+    merchantId: string;
+    peerFeeBps: number;
+    payoutStepUsdc: number;
+    payoutStepRange: CashoutPayoutStepRange;
+    fundingTokens: string[];
+    /** Merchant cashout rails, edited by the merchant and Peer admins, in rail order. */
+    rails: CashoutRailType[];
+    /** Player support link; optional. */
+    supportUrl: string | null;
+    /** Merchant rails minus Peer's global disables and the fiat rails `DISABLED_RAILS` turns off, in rail order. */
+    effectiveRails: CashoutRailType[];
+    merchantFeeBps: number;
+    merchantFeeRecipient: string | null;
+}
+export interface AdminCashoutFundingIssue extends MerchantCashoutFundingIssue {
+    id: string;
+    cashoutId: string;
+    merchantId: string;
+    merchantName: string;
+    relayRequestId: string | null;
+    resolutionNote: string | null;
+    resolvedBy: string | null;
+}
+export interface AdminCashoutSupport {
+    fundingIssues: AdminCashoutFundingIssue[];
+}
+export interface AdminCashoutChange {
+    id: string;
+    merchantId: string | null;
+    cashoutFundingIssueId: string | null;
+    actor: string;
+    changes: Record<string, {
+        before: unknown;
+        after: unknown;
+    }>;
+    createdAt: string;
+}
+/** What the player can do next; drives every checkout button and every 409. */
+export declare const CashoutPlayerAction: {
+    readonly SET_METHOD: "SET_METHOD";
+    readonly CONNECT_RAIL: "CONNECT_RAIL";
+    readonly SKIP_CONNECT: "SKIP_CONNECT";
+    readonly CONFIRM: "CONFIRM";
+    readonly CANCEL: "CANCEL";
+    readonly FINISH_CANCEL: "FINISH_CANCEL";
+    readonly CHANGE_METHOD: "CHANGE_METHOD";
+    readonly SEND_TO_ADDRESS: "SEND_TO_ADDRESS";
+    readonly RELIST: "RELIST";
+};
+export type CashoutPlayerActionType = typeof CashoutPlayerAction[keyof typeof CashoutPlayerAction];
+/** What Pay is sending from the player's wallet. */
+export declare const CashoutSending: {
+    readonly LISTING: "LISTING";
+    readonly TRANSFER: "TRANSFER";
+    readonly WITHDRAW: "WITHDRAW";
+    readonly RELISTING: "RELISTING";
+};
+export type CashoutSendingType = typeof CashoutSending[keyof typeof CashoutSending];
+export declare const CashoutCredentialStatus: {
+    readonly ACTIVE: "active";
+    readonly INACTIVE: "inactive";
+    readonly MISSING: "missing";
+};
+export type CashoutCredentialStatusType = typeof CashoutCredentialStatus[keyof typeof CashoutCredentialStatus];
+export interface CashoutRailOption {
+    rail: CashoutRailType;
+    /** Smallest single buyer payment, USDC decimal; null for crypto rails. */
+    minAmount: string | null;
+    /** Largest single buyer payment, USDC decimal; null for crypto rails. */
+    maxAmount: string | null;
+}
+/** A SAR method supports seller-side confirmation; when connecting is skipped, each buyer proves payment. */
+export interface CashoutSarMethod {
+    rail: CashoutSarRailType;
+    payeeHandle: string;
+    credentialStatus: CashoutCredentialStatusType;
+    /** The player chose to list without connecting this method. */
+    connectSkipped: boolean;
+    payeeHash: string;
+    /** The email of the PayPal account; null on every other rail. Only the player's own checkout sees it. */
+    paypalEmail: string | null;
+}
+/** A buyer-proof method has no connect step or credential; each buyer proves their payment. */
+export interface CashoutBuyerProofMethod {
+    rail: CashoutBuyerProofRailType;
+    payeeHandle: string;
+    payeeHash: string;
+}
+/** GET /api/v1/cashout-checkout/:id (link token only). */
+export interface CashoutCheckoutSummary {
+    cashoutId: string;
+    merchant: {
+        name: string;
+        logoUrl: string | null;
+        supportUrl: string | null;
+        disableBranding: boolean;
+        checkoutTheme: MerchantCheckoutTheme | null;
+    };
+    email: string;
+    maskedEmail: string;
+    payoutAmount: string;
+    status: CashoutStatusType;
+    rails: CashoutRailOption[];
+    returnUrl: string | null;
+}
+/** GET /api/v1/cashout-checkout/:id/state (link token + Peer app login). */
+export interface CashoutCheckoutState {
+    cashoutId: string;
+    status: CashoutStatusType;
+    walletAddress: string;
+    depositAmount: string | null;
+    /** Live from the escrow deposit; null before listing and once the listing is closed. */
+    remainingAmount: string | null;
+    buyerPaymentActive: boolean;
+    method: CashoutSarMethod | CashoutBuyerProofMethod | CashoutCryptoMethod | null;
+    /** Prefill from this player's last cashout on an available rail; never a deposit address. */
+    lastPayoutTarget: CashoutPayoutMethodView | null;
+    attempt: {
+        attemptId: string;
+        status: CashoutAttemptStatusType;
+        depositId: string | null;
+    } | null;
+    signer: {
+        signerId: string;
+        policyId: string;
+        attached: boolean;
+    };
+    /** What Pay is sending from the player's wallet right now; null when nothing is in flight. */
+    sending: CashoutSendingType | null;
+    /**
+     * The newest send of the current attempt (or of the last closed attempt while the cashout is back in FUNDED/READY) failed; a failed relist counts only while the cashout is listed.
+     * Also true when a Venmo or PayPal listing's Peer Pay group send failed and its listing was withdrawn (the cashout is back in FUNDED/READY).
+     */
+    lastSendFailed: boolean;
+    /** Set when the Peer wallet no longer covers this cashout (newest first, like the wallet job): what it needs and what is left for it after the player's older cashouts, in decimal USDC. Only CANCEL is offered then. */
+    walletShortfall: {
+        requiredAmount: string;
+        availableAmount: string;
+    } | null;
+    /** PARTIALLY_FUNDED means the merchant still owes a top-up; receivedAmount is the USDC that reached the player's wallet. */
+    funding: {
+        status: CashoutFundingStatusType;
+        receivedAmount: string | null;
+    };
+    /** Who cancelled; PEER_APP when the player took the cashout back in the Peer app. */
+    cancelSource: CashoutCancelSourceType | null;
+    merchantReference: string | null;
+    /** Once settled: the delivering transaction and its chain. */
+    settleTx: {
+        chainId: number;
+        txHash: string;
+    } | null;
+    /** The newest attempt's newest bridge unless it is NOT_SENT. */
+    payoutBridge: CashoutPayoutBridgeView | null;
+    /** While a buyer pays, when that buyer was matched (ISO time). */
+    buyerMatchedAt: string | null;
+    /** Set once a buyer paid part of the cashout; decimal USDC. totalAmount is depositAmount. */
+    partialPayment: {
+        paidAmount: string;
+        unpaidAmount: string;
+        totalAmount: string;
+        /** What the live listing's deposit holds (cashoutDepositRemainingUnits); null when nothing is listed. Relist, withdraw and send amounts. */
+        listedAmount: string | null;
+        /**
+         * The listed deposit still takes new buyers (EscrowV2 `acceptingIntents`). False when nothing is listed, and when a
+         * withdraw landed while a buyer held the deposit (a send-to-address or change-method exit, or a Peer-app withdraw): the
+         * escrow then takes no new buyer, so the rest is never relisted and only an exit moves it.
+         */
+        acceptingBuyers: boolean;
+    } | null;
+    /** Only when status is SETTLED. */
+    settlement: CashoutSettlementBreakdown | null;
+    actions: CashoutPlayerActionType[];
+}
+export type SetCashoutPayoutMethodRequest = {
+    rail: typeof CashoutRail.VENMO | typeof CashoutRail.CASHAPP;
+    payeeHandle: string;
+}
+/** The App Clip checks the connected PayPal account against this email. */
+ | {
+    rail: typeof CashoutRail.PAYPAL;
+    payeeHandle: string;
+    paypalEmail: string;
+}
+/** Buyer-proof rails need only the payout account; there is no connect step. */
+ | {
+    rail: CashoutBuyerProofRailType;
+    payeeHandle: string;
+} | CashoutPayoutDestinationRequest;
+/** POST /api/v1/cashout-checkout/:id/send-to-address. The checkout requires the network tick box before sending. */
+export type SendCashoutToAddressRequest = CashoutPayoutDestinationRequest;
+export interface CashoutActivityItem {
+    cashoutId: string;
+    /** Only the player passing linkAuth and loginAuth may see this link to open their cashout. */
+    checkoutUrl: string;
+    payoutAmount: string;
+    /** The chosen payout app, or null before the player picks one. */
+    payoutRail: CashoutRailType | null;
+    status: CashoutStatusType;
+    createdAt: string;
+}
+export interface ListCashoutActivityResponse {
+    /** Only the player passing linkAuth and loginAuth may see the full recipient email identifying this list. */
+    email: string;
+    items: CashoutActivityItem[];
+    page: number;
+    limit: number;
+    total: number;
+}
 export {};

package/dist/types.js

@@ -231,12 +231,40 @@ export const WebhookEventType = {
     PAYMENT_CHARGEBACKED: 'PAYMENT_CHARGEBACKED',
     ORDER_PARTIALLY_CHARGEBACKED: 'ORDER_PARTIALLY_CHARGEBACKED',
     ORDER_CHARGEBACKED: 'ORDER_CHARGEBACKED',
-};
+    CASHOUT_ORDER_CREATED: 'CASHOUT_ORDER_CREATED',
+    CASHOUT_ORDER_CANCELLED: 'CASHOUT_ORDER_CANCELLED',
+    CASHOUT_ORDER_PARTIALLY_FUNDED: 'CASHOUT_ORDER_PARTIALLY_FUNDED',
+    CASHOUT_ORDER_FUNDED: 'CASHOUT_ORDER_FUNDED',
+    CASHOUT_ORDER_MATCHED: 'CASHOUT_ORDER_MATCHED',
+    CASHOUT_ORDER_PARTIALLY_PAID: 'CASHOUT_ORDER_PARTIALLY_PAID',
+    CASHOUT_ORDER_SETTLED: 'CASHOUT_ORDER_SETTLED',
+    CASHOUT_ORDER_EXPIRED: 'CASHOUT_ORDER_EXPIRED',
+};
+/** Cashout events carry a CashoutView, not the order envelope. */
+export const CASHOUT_WEBHOOK_EVENT_TYPES = [
+    WebhookEventType.CASHOUT_ORDER_CREATED,
+    WebhookEventType.CASHOUT_ORDER_CANCELLED,
+    WebhookEventType.CASHOUT_ORDER_PARTIALLY_FUNDED,
+    WebhookEventType.CASHOUT_ORDER_FUNDED,
+    WebhookEventType.CASHOUT_ORDER_MATCHED,
+    WebhookEventType.CASHOUT_ORDER_PARTIALLY_PAID,
+    WebhookEventType.CASHOUT_ORDER_SETTLED,
+    WebhookEventType.CASHOUT_ORDER_EXPIRED,
+];
+const CASHOUT_WEBHOOK_EVENT_TYPE_SET = new Set(CASHOUT_WEBHOOK_EVENT_TYPES);
+export function isCashoutWebhookEventType(type) {
+    return CASHOUT_WEBHOOK_EVENT_TYPE_SET.has(type);
+}
 export const WebhookDeliveryStatus = {
     PENDING: 'PENDING',
     DELIVERED: 'DELIVERED',
     FAILED: 'FAILED',
 };
+/** Bumped only on a breaking change to a cashout payload. */
+export const CASHOUT_WEBHOOK_VERSION = 1;
+export function isCashoutWebhook(payload) {
+    return isCashoutWebhookEventType(payload.type);
+}
 /**
  * Wallet-snapshot fence rejections (ownership-transfer era rule). PR 4-6 add keys to this object.
  * MERCHANT_OWNERSHIP_CHANGED is retryable: an order insert lost the era it read its wallet in.
@@ -318,3 +346,122 @@ export function maskOwnershipTransferEmail(email) {
         throw new Error('Cannot mask an address without a local part');
     return `${email.slice(0, 1)}•••${email.slice(at)}`;
 }
+// ============ Cashout Types (merchant → player payouts) ============
+export const CashoutStatus = {
+    AWAITING_FUNDING: 'AWAITING_FUNDING',
+    FUNDED: 'FUNDED',
+    READY: 'READY',
+    LISTING: 'LISTING',
+    PAYING: 'PAYING',
+    SETTLED: 'SETTLED',
+    CANCELLING: 'CANCELLING',
+    CANCELLED: 'CANCELLED',
+    EXPIRED: 'EXPIRED',
+};
+export const CashoutFundingStatus = {
+    AWAITING_FUNDING: 'AWAITING_FUNDING',
+    PARTIALLY_FUNDED: 'PARTIALLY_FUNDED',
+    FUNDED: 'FUNDED',
+    FUNDING_EXPIRED: 'FUNDING_EXPIRED',
+};
+export const CashoutCancelSource = {
+    CHECKOUT: 'CHECKOUT',
+    MERCHANT: 'MERCHANT',
+    PEER_APP: 'PEER_APP',
+};
+export const CashoutPayoutKind = { ESCROW: 'ESCROW', CRYPTO: 'CRYPTO' };
+export const CashoutAttemptStatus = {
+    ACTIVE: 'ACTIVE',
+    CLOSED: 'CLOSED',
+    SETTLED: 'SETTLED',
+    FAILED: 'FAILED',
+};
+/** Fiat payout methods, in the order players see them: SAR rails, then buyer-proof rails. */
+export const CashoutFiatRail = {
+    VENMO: 'venmo',
+    CASHAPP: 'cashapp',
+    PAYPAL: 'paypal',
+    ZELLE: 'zelle',
+    REVOLUT: 'revolut',
+    CHIME: 'chime',
+};
+/** One rail per crypto payout network, with checkout's rail ids (any-coin spec "Cashout rails"); the player sees them as one "Crypto" option. */
+export const CashoutCryptoRail = {
+    RELAY_1: 'relay_1',
+    RELAY_10: 'relay_10',
+    RELAY_56: 'relay_56',
+    RELAY_137: 'relay_137',
+    RELAY_480: 'relay_480',
+    RELAY_999: 'relay_999',
+    RELAY_5042: 'relay_5042',
+    RELAY_8453: 'relay_8453',
+    RELAY_42161: 'relay_42161',
+    RELAY_8253038: 'relay_8253038',
+    RELAY_728126428: 'relay_728126428',
+    RELAY_792703809: 'relay_792703809',
+    /** ZEC on Zcash through NEAR Intents (Zcash spec "Catalog, route and address"); checkout's ZCASH_RAIL. */
+    NEAR_INTENTS_133701: 'near_intents_133701',
+};
+/** Every cashout rail, in rail order: fiat, then the crypto networks. */
+export const CashoutRail = { ...CashoutFiatRail, ...CashoutCryptoRail };
+export const CashoutPayoutProvider = { RELAY: 'RELAY', NEAR_INTENTS: 'NEAR_INTENTS' };
+export const CashoutPayoutBridgeStatus = {
+    QUOTED: 'QUOTED', NOT_SENT: 'NOT_SENT', BRIDGING: 'BRIDGING', DELIVERED: 'DELIVERED', REFUNDED: 'REFUNDED',
+};
+// ============ Merchant Dashboard Cashout Types ============
+/** A moment on a cashout's dashboard timeline. */
+export const CashoutTimelineEventType = {
+    CREATED: 'CREATED',
+    PARTIALLY_FUNDED: 'PARTIALLY_FUNDED',
+    FUNDED: 'FUNDED',
+    FUNDING_EXPIRED: 'FUNDING_EXPIRED',
+    SIGNED_IN: 'SIGNED_IN',
+    METHOD_READY: 'METHOD_READY',
+    LISTED: 'LISTED',
+    TRANSFER_SENT: 'TRANSFER_SENT',
+    MATCHED: 'MATCHED',
+    /** A buyer paid part of the listing; the rest is listed again or left for the player. */
+    PARTIALLY_PAID: 'PARTIALLY_PAID',
+    /** Pay set the deposit's intent range to what is left, so another buyer can take it. */
+    RELISTED: 'RELISTED',
+    BUYER_DROPPED: 'BUYER_DROPPED',
+    RECONNECT_NEEDED: 'RECONNECT_NEEDED',
+    CANCEL_STARTED: 'CANCEL_STARTED',
+    /** The listing came back to the player's wallet so they can pick another payout method. */
+    LISTING_WITHDRAWN: 'LISTING_WITHDRAWN',
+    SETTLED: 'SETTLED',
+    CANCELLED: 'CANCELLED',
+    FUNDING_ISSUE: 'FUNDING_ISSUE',
+    PAYOUT_REFUNDED: 'PAYOUT_REFUNDED',
+};
+/** Largest merchant cashout payout step, in whole USDC. The smallest is the API's CASHOUT_MIN_USDC (10 in production). */
+export const CASHOUT_PAYOUT_STEP_MAX_USDC = 1000;
+export const CashoutFundingIssueKind = {
+    LATE_FUNDS: 'LATE_FUNDS',
+    OVERPAYMENT: 'OVERPAYMENT',
+    ROUTE_REFUND: 'ROUTE_REFUND',
+};
+export const CashoutFundingIssueResolution = {
+    RETURNED: 'RETURNED',
+    CLAIMED: 'CLAIMED',
+};
+// ============ Cashout Player Checkout Types ============
+/** What the player can do next; drives every checkout button and every 409. */
+export const CashoutPlayerAction = {
+    SET_METHOD: 'SET_METHOD',
+    CONNECT_RAIL: 'CONNECT_RAIL',
+    SKIP_CONNECT: 'SKIP_CONNECT',
+    CONFIRM: 'CONFIRM',
+    CANCEL: 'CANCEL',
+    FINISH_CANCEL: 'FINISH_CANCEL',
+    CHANGE_METHOD: 'CHANGE_METHOD',
+    SEND_TO_ADDRESS: 'SEND_TO_ADDRESS',
+    RELIST: 'RELIST',
+};
+/** What Pay is sending from the player's wallet. */
+export const CashoutSending = { LISTING: 'LISTING', TRANSFER: 'TRANSFER', WITHDRAW: 'WITHDRAW', RELISTING: 'RELISTING' };
+export const CashoutCredentialStatus = {
+    ACTIVE: 'active',
+    INACTIVE: 'inactive',
+    MISSING: 'missing',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/pay-shared",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Shared TypeScript types, enums, and chain utilities used by ZKP2P Pay API, SDK, and frontend apps.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "lint": "eslint . --ext .ts,.tsx",
-    "test": "vitest run",
+    "test": "vitest run && tsc -p tsconfig.test.json",
     "prepack": "npm run build",
     "prepublishOnly": "npm run lint"
   },