@zkp2p/pay-shared 2.0.0 → 3.1.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@2.0.0
+npm install @zkp2p/pay-shared@3.1.0
 ```
 
 ## Published artifacts

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

@@ -5,6 +5,9 @@ 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

@@ -5,6 +5,9 @@ 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;

package/dist/onboarding.js

@@ -0,0 +1,150 @@
+import { MerchantIntegrationPath, OnboardingStepStatus, OnboardingStepVerifiedBy, } from './types.js';
+export const OnboardingStepId = {
+    PROFILE: 'profile',
+    INDUSTRY: 'industry',
+    PATH: 'path',
+    RAILS: 'rails',
+    INTEGRATION: 'integration',
+    WEBHOOK: 'webhook',
+    GO_LIVE: 'goLive',
+    DOWNLOAD_PLUGIN: 'downloadPlugin',
+    PLUGIN_API_KEY: 'pluginApiKey',
+    TEST_ORDER: 'testOrder',
+    FIRST_QR: 'firstQr',
+    LINK_BOT: 'linkBot',
+    REQUEST_SETUP: 'requestSetup',
+};
+export const ONBOARDING_STEP_REGISTRY = [
+    { id: OnboardingStepId.PROFILE, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
+    { id: OnboardingStepId.INDUSTRY, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
+    {
+        id: OnboardingStepId.RAILS,
+        paths: 'ALL',
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: false,
+        // This step is unconditionally satisfied and carries no information, so allowing
+        // it to imply earlier steps would mark every merchant's onboarding complete.
+        impliesPrevious: false,
+    },
+    { id: OnboardingStepId.PATH, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
+    {
+        id: OnboardingStepId.INTEGRATION,
+        paths: [MerchantIntegrationPath.CUSTOM_API],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.WEBHOOK,
+        paths: [MerchantIntegrationPath.CUSTOM_API],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: false,
+    },
+    {
+        id: OnboardingStepId.LINK_BOT,
+        paths: [MerchantIntegrationPath.TELEGRAM],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.GO_LIVE,
+        paths: [MerchantIntegrationPath.CUSTOM_API, MerchantIntegrationPath.TELEGRAM],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.DOWNLOAD_PLUGIN,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.PLUGIN_API_KEY,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.TEST_ORDER,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.GO_LIVE,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.FIRST_QR,
+        paths: [MerchantIntegrationPath.IN_PERSON],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        // In-person merchants only need to show a Scan to Pay QR. Waiting for a real
+        // customer payment would leave unopened shops stuck in onboarding.
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.REQUEST_SETUP,
+        paths: [MerchantIntegrationPath.SHOPIFY],
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+];
+const autoStepPredicates = {
+    [OnboardingStepId.PROFILE]: (facts) => facts.hasName && facts.hasLogo,
+    [OnboardingStepId.INDUSTRY]: (facts) => facts.hasIndustry,
+    [OnboardingStepId.PATH]: (facts) => facts.hasIntegrationPath,
+    [OnboardingStepId.RAILS]: () => true,
+    [OnboardingStepId.INTEGRATION]: (facts) => facts.hasSandboxFulfilledOrder,
+    [OnboardingStepId.WEBHOOK]: (facts) => facts.hasWebhook,
+    [OnboardingStepId.TEST_ORDER]: (facts) => facts.hasSandboxFulfilledOrder,
+    [OnboardingStepId.LINK_BOT]: (facts) => facts.hasSandboxFulfilledOrder,
+    [OnboardingStepId.GO_LIVE]: (facts) => facts.hasLiveFulfilledOrder,
+    [OnboardingStepId.FIRST_QR]: (facts) => facts.hasSandboxOrder,
+};
+export function resolveOnboardingSteps(facts, path) {
+    const entries = ONBOARDING_STEP_REGISTRY.filter((entry) => entry.paths === 'ALL' || (path !== null && entry.paths.includes(path)));
+    // Load-bearing override: merchants already taking payments must remain free of
+    // the onboarding checklist, even when they have no selected integration path.
+    if (facts.hasLiveFulfilledOrder) {
+        return entries.map((entry) => ({
+            id: entry.id,
+            status: OnboardingStepStatus.DONE,
+            verifiedBy: entry.verifiedBy,
+        }));
+    }
+    const steps = entries.map((entry) => {
+        const isDone = entry.verifiedBy === OnboardingStepVerifiedBy.MANUAL
+            ? facts.manualSteps.includes(entry.id)
+            : autoStepPredicates[entry.id]?.(facts) ?? false;
+        return {
+            id: entry.id,
+            status: isDone ? OnboardingStepStatus.DONE : OnboardingStepStatus.TODO,
+            verifiedBy: entry.verifiedBy,
+        };
+    });
+    let laterStepIsDone = false;
+    for (let index = steps.length - 1; index >= 0; index -= 1) {
+        if (laterStepIsDone) {
+            steps[index] = { ...steps[index], status: OnboardingStepStatus.DONE };
+        }
+        else if (steps[index].status === OnboardingStepStatus.DONE
+            && entries[index].impliesPrevious) {
+            laterStepIsDone = true;
+        }
+    }
+    return steps;
+}
+export function isOnboardingComplete(steps) {
+    return steps.every((step) => step.status === OnboardingStepStatus.DONE);
+}

package/dist/payeeFeeCap.d.ts

@@ -0,0 +1,21 @@
+export type PayeeFeeEntry = {
+    readonly recipient: string;
+    readonly feeBps: number;
+};
+export type PayeeReferralFeeCapacityResult = {
+    readonly referralFees: PayeeFeeEntry[];
+    readonly configuredPlatformReferralFeeBps: number;
+    readonly adjustedPlatformReferralFeeBps: number;
+    readonly otherReferralFeeAmount: string;
+    readonly platformFeeCapacityAmount: string;
+    readonly insufficientCapacity: boolean;
+    readonly requiredNetCovered: boolean;
+};
+export declare function resolvePayeeReferralFeeCapacity(input: {
+    readonly grossSignalAmount: string;
+    readonly quotedTokenOutput: string;
+    readonly requiredNetAmount: string;
+    readonly platformRecipient: string;
+    readonly referralFees: readonly PayeeFeeEntry[];
+}): PayeeReferralFeeCapacityResult;
+export declare function computeNetAfterPreciseFees(grossAmount: string, feeRates18dec: readonly string[]): string;

package/dist/payeeFeeCap.js

@@ -0,0 +1,105 @@
+const BPS_DENOMINATOR = 10000n;
+const PRECISE_FEE_DENOMINATOR = 10n ** 18n;
+const UNSIGNED_INTEGER_PATTERN = /^\d+$/;
+export function resolvePayeeReferralFeeCapacity(input) {
+    const grossSignalAmount = parsePositiveUnits(input.grossSignalAmount, 'gross signal amount');
+    const quotedTokenOutput = parsePositiveUnits(input.quotedTokenOutput, 'quoted token output');
+    const requiredNetAmount = parsePositiveUnits(input.requiredNetAmount, 'required net amount');
+    if (quotedTokenOutput > grossSignalAmount) {
+        throw new RangeError('Quoted token output cannot exceed gross signal amount');
+    }
+    const platformRecipient = input.platformRecipient.trim().toLowerCase();
+    if (platformRecipient === '') {
+        throw new RangeError('Platform recipient is required');
+    }
+    const platformEntries = input.referralFees.filter((entry) => entry.recipient.trim().toLowerCase() === platformRecipient);
+    if (platformEntries.length > 1) {
+        throw new RangeError('Duplicate platform referral fee entries');
+    }
+    input.referralFees.forEach(validateFeeEntry);
+    const configuredPlatformReferralFeeBps = platformEntries[0]?.feeBps ?? 0;
+    const otherReferralFeeAmount = input.referralFees.reduce((total, entry) => {
+        if (entry.recipient.trim().toLowerCase() === platformRecipient) {
+            return total;
+        }
+        return total + computeBpsFee(grossSignalAmount, entry.feeBps);
+    }, 0n);
+    const platformFeeCapacityAmount = quotedTokenOutput - requiredNetAmount - otherReferralFeeAmount;
+    const insufficientCapacity = platformFeeCapacityAmount < 0n;
+    const adjustedPlatformReferralFeeBps = insufficientCapacity
+        ? 0
+        : findLargestFittingBps(grossSignalAmount, platformFeeCapacityAmount, configuredPlatformReferralFeeBps);
+    const adjustedPlatformFeeAmount = computeBpsFee(grossSignalAmount, adjustedPlatformReferralFeeBps);
+    const requiredNetCovered = quotedTokenOutput
+        - otherReferralFeeAmount
+        - adjustedPlatformFeeAmount >= requiredNetAmount;
+    return {
+        referralFees: input.referralFees.flatMap((entry) => {
+            if (entry.recipient.trim().toLowerCase() !== platformRecipient) {
+                return [{ ...entry }];
+            }
+            return adjustedPlatformReferralFeeBps === 0
+                ? []
+                : [{ ...entry, feeBps: adjustedPlatformReferralFeeBps }];
+        }),
+        configuredPlatformReferralFeeBps,
+        adjustedPlatformReferralFeeBps,
+        otherReferralFeeAmount: otherReferralFeeAmount.toString(),
+        platformFeeCapacityAmount: platformFeeCapacityAmount.toString(),
+        insufficientCapacity,
+        requiredNetCovered,
+    };
+}
+export function computeNetAfterPreciseFees(grossAmount, feeRates18dec) {
+    const gross = parsePositiveUnits(grossAmount, 'gross amount');
+    const totalFees = feeRates18dec.reduce((total, feeRate) => {
+        const rate = parseUnsignedUnits(feeRate, 'precise fee rate');
+        if (rate > PRECISE_FEE_DENOMINATOR) {
+            throw new RangeError('Precise fee rate cannot exceed 100%');
+        }
+        return total + (gross * rate / PRECISE_FEE_DENOMINATOR);
+    }, 0n);
+    if (totalFees > gross) {
+        throw new RangeError('Precise fees exceed gross amount');
+    }
+    return (gross - totalFees).toString();
+}
+function findLargestFittingBps(grossAmount, capacity, configuredBps) {
+    let low = 0;
+    let high = configuredBps;
+    while (low < high) {
+        const candidate = Math.ceil((low + high) / 2);
+        if (computeBpsFee(grossAmount, candidate) <= capacity) {
+            low = candidate;
+        }
+        else {
+            high = candidate - 1;
+        }
+    }
+    return low;
+}
+function computeBpsFee(grossAmount, feeBps) {
+    return grossAmount * BigInt(feeBps) / BPS_DENOMINATOR;
+}
+function validateFeeEntry(entry) {
+    if (entry.recipient.trim() === '') {
+        throw new RangeError('Referral fee recipient is required');
+    }
+    if (!Number.isInteger(entry.feeBps) || entry.feeBps < 0 || entry.feeBps > 10000) {
+        throw new RangeError(`Invalid referral fee bps: ${entry.feeBps}`);
+    }
+}
+function parsePositiveUnits(value, label) {
+    const parsed = parseUnsignedUnits(value, label);
+    if (parsed <= 0n) {
+        throw new RangeError(`${label} must be positive`);
+    }
+    return parsed;
+}
+function parseUnsignedUnits(value, label) {
+    const normalized = value.trim();
+    if (!UNSIGNED_INTEGER_PATTERN.test(normalized)) {
+        throw new RangeError(`${label} must be an unsigned integer`);
+    }
+    return BigInt(normalized);
+}

package/dist/types.d.ts

@@ -112,6 +112,7 @@ type CreateOrderRequestBase = {
     destinationChainId?: number;
     feePayer?: FeePayerType;
     enabledRails?: string[];
+    dynamicOrdersEnabled?: boolean;
     successUrl?: string | null;
     cancelUrl?: string | null;
     notes?: Record<string, unknown> | null;
@@ -140,6 +141,7 @@ export type MerchantCheckoutTheme = {
     buttonTextColor?: string | null;
     defaultMaxFeePercentage?: number;
     payWithCryptoEnabled?: boolean;
+    currencySelectorEnabled?: boolean;
     [key: string]: unknown;
 };
 export type CheckoutMerchant = {
@@ -174,6 +176,11 @@ export type CheckoutOrder = {
     cancelUrl: string | null;
     notes: unknown | null;
     metadata: unknown | null;
+    /** Merchant-requested fiat price; non-null only for pristine, un-resized fiat-input orders. */
+    requestedFiat?: {
+        amount: string;
+        currency: string;
+    } | null;
     bridgeInfo?: OrderBridgeInfo | null;
     referralSplitConfig: ReferralSplitConfig | null;
     cancelledAt: string | null;
@@ -189,6 +196,7 @@ export type CheckoutPaymentQuote = {
         amount: string;
         toAddress: string;
         escrowAddress?: string;
+        orchestratorAddress?: string;
         fiatCurrencyCode?: string;
         payeeDetails: string;
     };
@@ -208,10 +216,53 @@ export type CheckoutQuoteEntry = {
     spreadPercentage: number;
     sellerAutomatedReleaseAvailable?: boolean;
 };
+export type CheckoutNearbySuggestion = {
+    resizeAmountUsdc: string;
+    paymentAmount: string;
+    paymentCurrency: string;
+    tokenAmount: string;
+    percentDifference: string;
+    rail: string;
+};
+export type CheckoutNearbySuggestions = {
+    status: 'suggestions' | 'none' | 'ineligible' | 'unavailable';
+    below: CheckoutNearbySuggestion[];
+    above: CheckoutNearbySuggestion[];
+};
+export type QuoteAvailabilityRequest = {
+    amount: string;
+    quoteMode: CheckoutModeType;
+    fiatCurrency?: string;
+    destinationChainId: string | number;
+    destinationToken: string;
+    destinationAddress: string;
+    /** Max suggestions PER DIRECTION (1-10, API default 3). A response can carry up to 2x this. */
+    nearbyQuotesCount?: number;
+};
+export type QuoteAvailabilitySuggestion = {
+    suggestedAmount: string;
+    percentDifference: string;
+    rail: string;
+    paymentAmount: string;
+    paymentCurrency: string;
+    tokenAmount: string;
+    conversionRate: string;
+};
+export type QuoteAvailabilitySuggestions = {
+    below: QuoteAvailabilitySuggestion[];
+    above: QuoteAvailabilitySuggestion[];
+};
+/** `nearbySuggestions` is always null when `available` is true. */
+export type QuoteAvailability = {
+    available: boolean;
+    quoteCount: number;
+    nearbySuggestions: QuoteAvailabilitySuggestions | null;
+};
 export type CheckoutQuotes = {
     orderId: string;
     fiatCurrency: string;
     platforms: CheckoutQuoteEntry[];
+    nearbySuggestions?: CheckoutNearbySuggestions;
 };
 export type CheckoutPayment = {
     id: string;
@@ -256,8 +307,6 @@ export type CreateOrderResponse = {
     order: CheckoutOrder;
     orderToken: string;
 };
-export type CreateCheckoutResponse = CreateOrderResponse;
-export type CheckoutCreateResponse = CreateOrderResponse;
 export type CreatePaymentRequest = {
     rail: string;
     paymentMethodId?: string;
@@ -266,6 +315,7 @@ export type CreatePaymentRequest = {
     replacementPaymentId?: string;
     quoteLimit?: number;
     excludedPayToValues?: string[];
+    refundTo?: string;
 };
 export type CheckoutPaymentCreationResponse = CheckoutPayment & {
     relayerTransactionId?: string;
@@ -291,24 +341,14 @@ export type MerchantConfig = {
     sweepEnabled: boolean;
     recipientOverrideEnabled: boolean;
     disableBranding: boolean;
+    dynamicOrdersEnabled: boolean;
     merchantCheckoutTheme: MerchantCheckoutTheme;
     platformReferralFeeConfig: ReferralFeeConfig | null;
     referralSplitConfig: ReferralSplitConfig | null;
+    flatFeePricing: boolean;
     createdAt: string;
     updatedAt: string | null;
 };
-export declare const DashboardPrivyApp: {
-    readonly LEGACY: "LEGACY";
-    readonly V1: "V1";
-};
-export type DashboardPrivyAppType = typeof DashboardPrivyApp[keyof typeof DashboardPrivyApp];
-export declare const MerchantMigrationStatus: {
-    readonly PENDING: "PENDING";
-    readonly MIGRATING: "MIGRATING";
-    readonly COMPLETE: "COMPLETE";
-    readonly FAILED: "FAILED";
-};
-export type MerchantMigrationStatusType = typeof MerchantMigrationStatus[keyof typeof MerchantMigrationStatus];
 export type MerchantUser = {
     id: string;
     email: string | null;
@@ -325,11 +365,13 @@ export type MerchantProfile = {
     logoUrl: string | null;
     industryType: string | null;
     industryOtherText: string | null;
+    integrationPath: MerchantIntegrationPathValue | null;
+    onboardingCompletedAt: string | null;
+    onboardingSkippedAt: string | null;
     apiKey: string;
     environment: MerchantEnvironmentType;
     sandboxMerchantId: string | null;
     inPersonCheckoutEnabled: boolean;
-    migrationStatus: MerchantMigrationStatusType;
     evmWalletAddress: string | null;
     solanaWalletAddress: string | null;
     v1EvmWalletAddress: string | null;
@@ -547,6 +589,7 @@ type CreateSessionBaseRequest = {
     cancelUrl?: string;
     metadata?: Record<string, string>;
     enabledPaymentPlatforms?: PaymentPlatformType[];
+    dynamicOrdersEnabled?: boolean;
 };
 type CreateSessionExactTokenRequest = CreateSessionBaseRequest & {
     checkoutMode?: 'exact-token';
@@ -668,10 +711,41 @@ export interface OrderBridgeInfo {
     fallbackToOrigin?: boolean;
     failureMessage?: string | null;
 }
+export declare const MerchantIntegrationPath: {
+    readonly CUSTOM_API: "CUSTOM_API";
+    readonly WOOCOMMERCE: "WOOCOMMERCE";
+    readonly IN_PERSON: "IN_PERSON";
+    readonly TELEGRAM: "TELEGRAM";
+    readonly SHOPIFY: "SHOPIFY";
+};
+export type MerchantIntegrationPathValue = typeof MerchantIntegrationPath[keyof typeof MerchantIntegrationPath];
+export declare const OnboardingStepStatus: {
+    readonly DONE: "done";
+    readonly TODO: "todo";
+};
+export type OnboardingStepStatusValue = typeof OnboardingStepStatus[keyof typeof OnboardingStepStatus];
+export declare const OnboardingStepVerifiedBy: {
+    readonly AUTO: "auto";
+    readonly MANUAL: "manual";
+};
+export type OnboardingStepVerifiedByValue = typeof OnboardingStepVerifiedBy[keyof typeof OnboardingStepVerifiedBy];
+export type OnboardingStepState = {
+    id: string;
+    status: OnboardingStepStatusValue;
+    verifiedBy: OnboardingStepVerifiedByValue;
+};
+export type MerchantOnboardingResponse = {
+    path: MerchantIntegrationPathValue | null;
+    sandboxApiKey: string | null;
+    completedAt: string | null;
+    skippedAt: string | null;
+    steps: OnboardingStepState[];
+};
 export declare const WebhookEventType: {
     readonly ORDER_CREATED: "ORDER_CREATED";
     readonly ORDER_FULFILLED: "ORDER_FULFILLED";
     readonly ORDER_CANCELLED: "ORDER_CANCELLED";
+    readonly ORDER_RESIZED: "ORDER_RESIZED";
     readonly PAYMENT_CREATED: "PAYMENT_CREATED";
     readonly PAYMENT_SETTLED: "PAYMENT_SETTLED";
     readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
@@ -705,9 +779,6 @@ export type Webhook = {
     createdAt: string;
     updatedAt: string;
 };
-export type WebhookWithSecret = Webhook & {
-    secret: string;
-};
 export type WebhookDelivery = {
     id: string;
     webhookId: string;
@@ -729,6 +800,10 @@ export type WebhookPayload = {
         payment: CheckoutPayment | null;
         refund: Record<string, unknown> | null;
         paymentBridge: Record<string, unknown> | null;
+        resize?: {
+            previousAmountUsdc: string;
+            newAmountUsdc: string;
+        };
     };
 };
 export type CreateWebhookRequest = {
@@ -736,7 +811,10 @@ export type CreateWebhookRequest = {
     events?: WebhookEventTypeValue[];
     customHeaders?: WebhookHeader[];
 };
-export type CreateWebhookResponse = WebhookWithSecret;
+export type CreateWebhookResponse = {
+    webhook: Webhook;
+    secret: string;
+};
 export type UpdateWebhookRequest = {
     url?: string;
     events?: WebhookEventTypeValue[];

package/dist/types.js

@@ -90,16 +90,6 @@ export const CheckoutPaymentMemoPolicy = {
     REQUIRED: 'REQUIRED',
     EMPTY: 'EMPTY',
 };
-export const DashboardPrivyApp = {
-    LEGACY: 'LEGACY',
-    V1: 'V1',
-};
-export const MerchantMigrationStatus = {
-    PENDING: 'PENDING',
-    MIGRATING: 'MIGRATING',
-    COMPLETE: 'COMPLETE',
-    FAILED: 'FAILED',
-};
 // Structured error codes for Order failures
 export const OrderErrorCode = {
     // Proof verification errors
@@ -131,11 +121,28 @@ export const TrancheCurrency = {
     USD: 'USD',
     USDC: 'USDC',
 };
+// ============ Merchant Onboarding Types ============
+export const MerchantIntegrationPath = {
+    CUSTOM_API: 'CUSTOM_API',
+    WOOCOMMERCE: 'WOOCOMMERCE',
+    IN_PERSON: 'IN_PERSON',
+    TELEGRAM: 'TELEGRAM',
+    SHOPIFY: 'SHOPIFY',
+};
+export const OnboardingStepStatus = {
+    DONE: 'done',
+    TODO: 'todo',
+};
+export const OnboardingStepVerifiedBy = {
+    AUTO: 'auto',
+    MANUAL: 'manual',
+};
 // ============ Webhook Types ============
 export const WebhookEventType = {
     ORDER_CREATED: 'ORDER_CREATED',
     ORDER_FULFILLED: 'ORDER_FULFILLED',
     ORDER_CANCELLED: 'ORDER_CANCELLED',
+    ORDER_RESIZED: 'ORDER_RESIZED',
     PAYMENT_CREATED: 'PAYMENT_CREATED',
     PAYMENT_SETTLED: 'PAYMENT_SETTLED',
     PAYMENT_CANCELLED: 'PAYMENT_CANCELLED',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/pay-shared",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "Shared TypeScript types, enums, and chain utilities used by ZKP2P Pay API, SDK, and frontend apps.",
   "type": "module",
   "main": "dist/index.js",