@zkp2p/pay-shared 1.0.0 → 3.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@1.0.0
+npm install @zkp2p/pay-shared@3.0.0
 ```
 
 ## Published artifacts
@@ -66,7 +66,7 @@ import {
 
 const chainId = parseSupportedChainSelection('polygon'); // 137
 const usdc = resolveDestinationTokenAddress('USDC', 137); // Chain-specific USDC address
-const supportedAliases = getSupportedDestinationTokenAliasesForChain(BASE_CHAIN_ID); // ["USDC"]
+const supportedAliases = getSupportedDestinationTokenAliasesForChain(BASE_CHAIN_ID); // ["USDC", "USDT"]
 
 console.log(getSupportedChainIds(), chainId, usdc, supportedAliases);
 ```

package/dist/addressEncoding.d.ts

@@ -0,0 +1,5 @@
+export declare function sha256(value: Uint8Array): Uint8Array;
+export declare function doubleSha256(value: Uint8Array): Uint8Array;
+export declare function decodeBase58(value: string): Uint8Array | null;
+export declare function encodeBase58(value: Uint8Array): string;
+export declare function hasBase58CheckChecksum(value: string, version: number): boolean;

package/dist/addressEncoding.js

@@ -0,0 +1,126 @@
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const SHA256_CONSTANTS = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+    0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+    0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+    0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+    0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+    0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotateRight(value, shift) {
+    return (value >>> shift) | (value << (32 - shift));
+}
+export function sha256(value) {
+    const paddedLength = Math.ceil((value.length + 9) / 64) * 64;
+    const message = new Uint8Array(paddedLength);
+    message.set(value);
+    message[value.length] = 0x80;
+    const bitLength = BigInt(value.length) * 8n;
+    const view = new DataView(message.buffer);
+    view.setUint32(paddedLength - 8, Number(bitLength >> 32n), false);
+    view.setUint32(paddedLength - 4, Number(bitLength & 0xffffffffn), false);
+    const hash = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+        0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const words = new Uint32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let index = 0; index < 16; index += 1) {
+            words[index] = view.getUint32(offset + (index * 4), false);
+        }
+        for (let index = 16; index < 64; index += 1) {
+            const previous15 = words[index - 15];
+            const previous2 = words[index - 2];
+            const sigma0 = rotateRight(previous15, 7) ^ rotateRight(previous15, 18) ^ (previous15 >>> 3);
+            const sigma1 = rotateRight(previous2, 17) ^ rotateRight(previous2, 19) ^ (previous2 >>> 10);
+            words[index] = (words[index - 16] + sigma0 + words[index - 7] + sigma1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = hash;
+        for (let index = 0; index < 64; index += 1) {
+            const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choice = (e & f) ^ (~e & g);
+            const temporary1 = (h + sum1 + choice + SHA256_CONSTANTS[index] + words[index]) >>> 0;
+            const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const temporary2 = (sum0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temporary1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temporary1 + temporary2) >>> 0;
+        }
+        hash[0] = (hash[0] + a) >>> 0;
+        hash[1] = (hash[1] + b) >>> 0;
+        hash[2] = (hash[2] + c) >>> 0;
+        hash[3] = (hash[3] + d) >>> 0;
+        hash[4] = (hash[4] + e) >>> 0;
+        hash[5] = (hash[5] + f) >>> 0;
+        hash[6] = (hash[6] + g) >>> 0;
+        hash[7] = (hash[7] + h) >>> 0;
+    }
+    const digest = new Uint8Array(32);
+    const digestView = new DataView(digest.buffer);
+    hash.forEach((word, index) => digestView.setUint32(index * 4, word, false));
+    return digest;
+}
+export function doubleSha256(value) {
+    return sha256(sha256(value));
+}
+export function decodeBase58(value) {
+    let decodedValue = 0n;
+    for (const character of value) {
+        const digit = BASE58_ALPHABET.indexOf(character);
+        if (digit === -1) {
+            return null;
+        }
+        decodedValue = (decodedValue * 58n) + BigInt(digit);
+    }
+    const bytes = [];
+    while (decodedValue > 0n) {
+        bytes.push(Number(decodedValue & 0xffn));
+        decodedValue >>= 8n;
+    }
+    bytes.reverse();
+    const leadingZeroes = value.match(/^1*/)?.[0].length ?? 0;
+    const decoded = new Uint8Array(leadingZeroes + bytes.length);
+    decoded.set(bytes, leadingZeroes);
+    return decoded;
+}
+export function encodeBase58(value) {
+    let encodedValue = 0n;
+    for (const byte of value) {
+        encodedValue = (encodedValue << 8n) + BigInt(byte);
+    }
+    let encoded = '';
+    while (encodedValue > 0n) {
+        encoded = BASE58_ALPHABET[Number(encodedValue % 58n)] + encoded;
+        encodedValue /= 58n;
+    }
+    let leadingZeroes = 0;
+    while (leadingZeroes < value.length && value[leadingZeroes] === 0) {
+        leadingZeroes += 1;
+    }
+    return '1'.repeat(leadingZeroes) + encoded;
+}
+export function hasBase58CheckChecksum(value, version) {
+    const decoded = decodeBase58(value);
+    if (decoded === null || decoded.length !== 25 || decoded[0] !== version) {
+        return false;
+    }
+    const payload = decoded.subarray(0, 21);
+    const expectedChecksum = doubleSha256(payload).subarray(0, 4);
+    return decoded.subarray(21).every((byte, index) => byte === expectedChecksum[index]);
+}

package/dist/addressValidators.d.ts

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

package/dist/addressValidators.js

@@ -0,0 +1,14 @@
+import { decodeBase58, encodeBase58, hasBase58CheckChecksum, } from './addressEncoding.js';
+export function isValidSolanaAddress(value) {
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value)) {
+        return false;
+    }
+    const decoded = decodeBase58(value);
+    return decoded !== null
+        && decoded.length === 32
+        && encodeBase58(decoded) === value;
+}
+export function isValidTronAddress(value) {
+    return /^T[1-9A-HJ-NP-Za-km-z]{33}$/.test(value)
+        && hasBase58CheckChecksum(value, 0x41);
+}

package/dist/bitcoin.js

@@ -1,13 +1,79 @@
-const BITCOIN_BASE58_ADDRESS_REGEX = /^[13][1-9A-HJ-NP-Za-km-z]{25,34}$/;
-const BITCOIN_BECH32_ADDRESS_REGEX = /^(bc1)[ac-hj-np-z02-9]{11,71}$/i;
+import { hasBase58CheckChecksum } from './addressEncoding.js';
+const BECH32_ALPHABET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const BECH32_CHECKSUM = 1;
+const BECH32M_CHECKSUM = 0x2bc830a3;
+function calculatePolymod(values) {
+    const generators = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+    let checksum = 1;
+    for (const value of values) {
+        const highBits = checksum >>> 25;
+        checksum = (((checksum & 0x1ffffff) << 5) ^ value) >>> 0;
+        for (let index = 0; index < generators.length; index += 1) {
+            if (((highBits >>> index) & 1) !== 0) {
+                checksum = (checksum ^ generators[index]) >>> 0;
+            }
+        }
+    }
+    return checksum;
+}
+function convertWitnessProgram(values) {
+    const decoded = [];
+    let accumulator = 0;
+    let bits = 0;
+    for (const value of values) {
+        accumulator = (accumulator << 5) | value;
+        bits += 5;
+        while (bits >= 8) {
+            bits -= 8;
+            decoded.push((accumulator >>> bits) & 0xff);
+        }
+    }
+    if (bits >= 5 || ((accumulator << (8 - bits)) & 0xff) !== 0) {
+        return null;
+    }
+    return Uint8Array.from(decoded);
+}
+function isValidBech32Address(value) {
+    if (value.length > 90 || (value !== value.toLowerCase() && value !== value.toUpperCase())) {
+        return false;
+    }
+    const normalized = value.toLowerCase();
+    const separatorIndex = normalized.lastIndexOf('1');
+    if (separatorIndex !== 2 || normalized.slice(0, separatorIndex) !== 'bc') {
+        return false;
+    }
+    const data = [...normalized.slice(separatorIndex + 1)]
+        .map((character) => BECH32_ALPHABET.indexOf(character));
+    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]);
+    if (witnessVersion > 16
+        || (witnessVersion === 0 && polymod !== BECH32_CHECKSUM)
+        || (witnessVersion > 0 && polymod !== BECH32M_CHECKSUM)) {
+        return false;
+    }
+    const witnessProgram = convertWitnessProgram(data.slice(1, -6));
+    if (witnessProgram === null || witnessProgram.length < 2 || witnessProgram.length > 40) {
+        return false;
+    }
+    return witnessVersion !== 0 || witnessProgram.length === 20 || witnessProgram.length === 32;
+}
 export function isValidBitcoinAddress(value) {
     const trimmed = value.trim();
     if (!trimmed) {
         return false;
     }
     if (trimmed.toLowerCase().startsWith('bc1')) {
-        const isUniformCase = trimmed === trimmed.toLowerCase() || trimmed === trimmed.toUpperCase();
-        return isUniformCase && BITCOIN_BECH32_ADDRESS_REGEX.test(trimmed);
+        return isValidBech32Address(trimmed);
     }
-    return BITCOIN_BASE58_ADDRESS_REGEX.test(trimmed);
+    return /^[13][1-9A-HJ-NP-Za-km-z]{25,34}$/.test(trimmed)
+        && (hasBase58CheckChecksum(trimmed, 0x00)
+            || hasBase58CheckChecksum(trimmed, 0x05));
 }

package/dist/buyerTee.d.ts

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

package/dist/buyerTee.js

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

package/dist/chains.d.ts

@@ -5,6 +5,7 @@
  * Import this module instead of duplicating chain configs in each app.
  */
 export declare const BASE_CHAIN_ID = 8453;
+export declare const ETHEREUM_CHAIN_ID = 1;
 export declare const HYPEREVM_CHAIN_ID = 999;
 export declare const SOLANA_CHAIN_ID = 792703809;
 export declare const SUPPORTED_DESTINATION_TOKEN_ALIASES: readonly ["USDC", "USDT"];

package/dist/chains.js

@@ -6,6 +6,7 @@
  */
 // Chain IDs
 export const BASE_CHAIN_ID = 8453;
+export const ETHEREUM_CHAIN_ID = 1;
 export const HYPEREVM_CHAIN_ID = 999;
 export const SOLANA_CHAIN_ID = 792703809;
 export const SUPPORTED_DESTINATION_TOKEN_ALIASES = ['USDC', 'USDT'];
@@ -135,6 +136,10 @@ for (const chainId of SUPPORTED_CHAIN_IDS) {
     }
 }
 const DESTINATION_TOKEN_ADDRESSES = {
+    // Base
+    8453: {
+        usdt: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
+    },
     // Ethereum
     1: {
         usdt: '0xdAC17F958D2ee523a2206206994597C13D831ec7',

package/dist/crypto.d.ts

@@ -4,6 +4,12 @@ export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT",
 export type PayCryptoTokenSymbol = (typeof PAY_CRYPTO_TOKEN_SYMBOLS)[number];
 export declare const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS: PayCryptoTokenSymbol[];
 export declare const DEFAULT_ENABLED_DESTINATION_TOKENS: PayCryptoTokenSymbol[];
+/**
+ * Display-order priority for the "Pay with crypto" chain dropdown.
+ * Chains not in this list fall back to the existing numeric chain-ID
+ * iteration order of PAY_CRYPTO_CHAIN_CONFIGS as a stable tiebreaker.
+ */
+export declare const PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY: readonly number[];
 export declare const STABLECOIN_SYMBOLS: Set<"USDC" | "USDT" | "ETH" | "BNB" | "SOL" | "BTC" | "PYUSD" | "HYPE" | "WBTC" | "USDH">;
 export interface SupportedCryptoTokenConfig {
     chainId: number;
@@ -18,6 +24,31 @@ export declare function normalizePayCryptoTokenSymbol(value: string | null | und
 export declare function isStablecoinSymbol(symbol: string | null | undefined): boolean;
 export declare function getSupportedPayCryptoTokenConfigsForChain(chainId: number, enabledSymbols?: readonly string[] | null): SupportedCryptoTokenConfig[];
 export declare function getSupportedPayCryptoChainIds(enabledSymbols?: readonly string[] | null): number[];
+/**
+ * Returns the union of tokens supported by any of `enabledChainIds`,
+ * sorted by the canonical pay-crypto display order
+ * (DEFAULT_ENABLED_PAY_CRYPTO_TOKENS order).
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export declare function getAvailablePayCryptoTokens(enabledChainIds?: readonly number[]): PayCryptoTokenSymbol[];
+/**
+ * Returns the chain IDs that support `symbol`, optionally filtered
+ * to `enabledChainIds`, sorted by PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY
+ * with ascending numeric chain-ID order as the stable tiebreaker.
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export declare function getSupportedPayCryptoChainIdsForToken(symbol: PayCryptoTokenSymbol, enabledChainIds?: readonly number[]): number[];
+/**
+ * Returns the display name for a chain used by the "Pay with crypto"
+ * flow. Resolves through PAY_CRYPTO_CHAIN_CONFIGS first so Bitcoin
+ * and Tron (which are not in MAINNET_CHAINS) get the correct label.
+ * Falls back to getChainName for chains not registered here.
+ */
+export declare function getPayCryptoChainName(chainId: number): string;
 export declare function resolvePayCryptoTokenConfig(chainId: number, symbol: string | null | undefined): SupportedCryptoTokenConfig | null;
 /**
  * Reverse lookup of a token config by contract address on a specific chain.

package/dist/crypto.js

@@ -1,4 +1,4 @@
-import { MAINNET_CHAINS, } from './chains.js';
+import { MAINNET_CHAINS, BASE_CHAIN_ID, ETHEREUM_CHAIN_ID, SOLANA_CHAIN_ID, getChainName, } from './chains.js';
 export const BITCOIN_CHAIN_ID = 8253038;
 export const TRON_CHAIN_ID = 728126428;
 export const PAY_CRYPTO_TOKEN_SYMBOLS = [
@@ -15,9 +15,9 @@ export const PAY_CRYPTO_TOKEN_SYMBOLS = [
 ];
 export const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS = [
     'BTC',
-    'USDC',
-    'USDT',
     'ETH',
+    'USDT',
+    'USDC',
     'PYUSD',
     'SOL',
     'BNB',
@@ -29,6 +29,17 @@ export const DEFAULT_ENABLED_DESTINATION_TOKENS = [
     'USDC',
     'USDT',
 ];
+/**
+ * Display-order priority for the "Pay with crypto" chain dropdown.
+ * Chains not in this list fall back to the existing numeric chain-ID
+ * iteration order of PAY_CRYPTO_CHAIN_CONFIGS as a stable tiebreaker.
+ */
+export const PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY = [
+    BITCOIN_CHAIN_ID,
+    ETHEREUM_CHAIN_ID,
+    SOLANA_CHAIN_ID,
+    BASE_CHAIN_ID,
+];
 export const STABLECOIN_SYMBOLS = new Set([
     'USDC',
     'USDT',
@@ -160,6 +171,60 @@ export function getSupportedPayCryptoChainIds(enabledSymbols) {
         .map(Number)
         .filter((chainId) => getSupportedPayCryptoTokenConfigsForChain(chainId, enabledSymbols).length > 0);
 }
+/**
+ * Returns the union of tokens supported by any of `enabledChainIds`,
+ * sorted by the canonical pay-crypto display order
+ * (DEFAULT_ENABLED_PAY_CRYPTO_TOKENS order).
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export function getAvailablePayCryptoTokens(enabledChainIds) {
+    const chainIds = enabledChainIds === undefined
+        ? Object.keys(CHAIN_TOKEN_CONFIGS).map(Number)
+        : enabledChainIds;
+    const available = new Set();
+    for (const chainId of chainIds) {
+        const chainTokens = CHAIN_TOKEN_CONFIGS[chainId];
+        if (chainTokens === undefined)
+            continue;
+        for (const symbol of Object.keys(chainTokens)) {
+            available.add(symbol);
+        }
+    }
+    return DEFAULT_ENABLED_PAY_CRYPTO_TOKENS.filter((symbol) => available.has(symbol));
+}
+/**
+ * Returns the chain IDs that support `symbol`, optionally filtered
+ * to `enabledChainIds`, sorted by PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY
+ * with ascending numeric chain-ID order as the stable tiebreaker.
+ *
+ * When `enabledChainIds` is undefined, uses every supported chain.
+ * When `enabledChainIds` is an empty array, returns [].
+ */
+export function getSupportedPayCryptoChainIdsForToken(symbol, enabledChainIds) {
+    const candidateChainIds = enabledChainIds === undefined
+        ? Object.keys(CHAIN_TOKEN_CONFIGS).map(Number)
+        : Array.from(new Set(enabledChainIds));
+    const supporting = candidateChainIds.filter((chainId) => (CHAIN_TOKEN_CONFIGS[chainId]?.[symbol] !== undefined));
+    const supportingSet = new Set(supporting);
+    const priorityPortion = PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY
+        .filter((chainId) => supportingSet.has(chainId));
+    const prioritySet = new Set(PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY);
+    const restPortion = supporting
+        .filter((chainId) => !prioritySet.has(chainId))
+        .sort((a, b) => a - b);
+    return [...priorityPortion, ...restPortion];
+}
+/**
+ * Returns the display name for a chain used by the "Pay with crypto"
+ * flow. Resolves through PAY_CRYPTO_CHAIN_CONFIGS first so Bitcoin
+ * and Tron (which are not in MAINNET_CHAINS) get the correct label.
+ * Falls back to getChainName for chains not registered here.
+ */
+export function getPayCryptoChainName(chainId) {
+    return PAY_CRYPTO_CHAIN_CONFIGS[chainId]?.name ?? getChainName(chainId);
+}
 export function resolvePayCryptoTokenConfig(chainId, symbol) {
     const normalizedSymbol = normalizePayCryptoTokenSymbol(symbol);
     if (!normalizedSymbol) {

package/dist/fiatAmount.d.ts

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

package/dist/fiatAmount.js

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

package/dist/index.d.ts

@@ -3,4 +3,11 @@ export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
 export * from './rails.js';
+export * from './buyerTee.js';
 export * from './bitcoin.js';
+export * from './addressValidators.js';
+export * from './fiatAmount.js';
+export * from './paypalSarPhase.js';
+export * from './paypalSarVerify.js';
+export * from './payeeFeeCap.js';
+export * from './onboarding.js';

package/dist/index.js

@@ -3,4 +3,11 @@ export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
 export * from './rails.js';
+export * from './buyerTee.js';
 export * from './bitcoin.js';
+export * from './addressValidators.js';
+export * from './fiatAmount.js';
+export * from './paypalSarPhase.js';
+export * from './paypalSarVerify.js';
+export * from './payeeFeeCap.js';
+export * from './onboarding.js';

package/dist/onboarding.d.ts

@@ -0,0 +1,39 @@
+import type { MerchantIntegrationPathValue, OnboardingStepState, OnboardingStepVerifiedByValue } from './types.js';
+export type OnboardingFacts = {
+    hasName: boolean;
+    hasLogo: boolean;
+    hasIndustry: boolean;
+    hasIntegrationPath: boolean;
+    hasWebhook: boolean;
+    hasSandboxOrder: boolean;
+    hasSandboxFulfilledOrder: boolean;
+    hasLiveOrder: boolean;
+    hasLiveFulfilledOrder: boolean;
+    manualSteps: readonly string[];
+};
+export declare const OnboardingStepId: {
+    readonly PROFILE: "profile";
+    readonly INDUSTRY: "industry";
+    readonly PATH: "path";
+    readonly RAILS: "rails";
+    readonly INTEGRATION: "integration";
+    readonly WEBHOOK: "webhook";
+    readonly GO_LIVE: "goLive";
+    readonly DOWNLOAD_PLUGIN: "downloadPlugin";
+    readonly PLUGIN_API_KEY: "pluginApiKey";
+    readonly TEST_ORDER: "testOrder";
+    readonly FIRST_QR: "firstQr";
+    readonly LINK_BOT: "linkBot";
+    readonly REQUEST_SETUP: "requestSetup";
+};
+export type OnboardingStepIdValue = typeof OnboardingStepId[keyof typeof OnboardingStepId];
+export type OnboardingStepRegistryEntry = {
+    readonly id: OnboardingStepIdValue;
+    readonly paths: readonly MerchantIntegrationPathValue[] | 'ALL';
+    readonly verifiedBy: OnboardingStepVerifiedByValue;
+    readonly inChecklist: boolean;
+    readonly impliesPrevious: boolean;
+};
+export declare const ONBOARDING_STEP_REGISTRY: readonly OnboardingStepRegistryEntry[];
+export declare function resolveOnboardingSteps(facts: OnboardingFacts, path: MerchantIntegrationPathValue | null): OnboardingStepState[];
+export declare function isOnboardingComplete(steps: readonly OnboardingStepState[]): boolean;