@provex/utils 1.11.0 → 2.0.0

package/dist/buy/settlementReconciliation.test.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Tests for the partial-settlement figures on the success panel.
+ *
+ * The expected strings were captured from the inline code in `CompletePanel`
+ * before it moved here, so each row pins what buyers already saw. A buyer reads
+ * these numbers to learn what they received and what went back to the maker,
+ * so a rounding change here changes a figure that touches money.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { SUPPORTED_CURRENCIES } from '../currencies.js';
+import { reconcileSettlement } from './settlementReconciliation.js';
+const PULSECHAIN = 369;
+/** Not a chain the protocol runs on, so it has no settlement token. */
+const UNSUPPORTED_CHAIN = 1;
+const USD = SUPPORTED_CURRENCIES.USD.contractId;
+const EUR = SUPPORTED_CURRENCIES.EUR.contractId;
+/** Only `releaseAmount` is read, so the rest of the attestation is left out. */
+const attestationReleasing = (releaseAmount) => ({ typedDataValue: { releaseAmount: releaseAmount.toString() } });
+const intentFor = ({ amount, conversionRate, fiatCurrency, }) => ({ amount, conversionRate, fiatCurrency });
+const hundredUsdc = intentFor({ amount: 100000000n, conversionRate: 1020000000000000000n, fiatCurrency: USD });
+describe('reconcileSettlement: partial settlements', () => {
+    const rows = [
+        {
+            name: 'no fee known: the buyer keeps the whole release',
+            release: 60000000n,
+            intent: hundredUsdc,
+            feeBps: null,
+            expected: {
+                currencySymbol: '$',
+                contractedFiat: '102.00',
+                attestedFiat: '61.20',
+                netToBuyer: '60.00',
+                protocolFee: null,
+                returnedToMaker: '40.00',
+            },
+        },
+        {
+            name: 'zero fee: same as no fee, and no fee row',
+            release: 60000000n,
+            intent: hundredUsdc,
+            feeBps: 0n,
+            expected: {
+                currencySymbol: '$',
+                contractedFiat: '102.00',
+                attestedFiat: '61.20',
+                netToBuyer: '60.00',
+                protocolFee: null,
+                returnedToMaker: '40.00',
+            },
+        },
+        {
+            name: 'two percent fee comes off the released amount, not the locked amount',
+            release: 60000000n,
+            intent: hundredUsdc,
+            feeBps: 200n,
+            expected: {
+                currencySymbol: '$',
+                contractedFiat: '102.00',
+                attestedFiat: '61.20',
+                netToBuyer: '58.80',
+                protocolFee: '1.20',
+                returnedToMaker: '40.00',
+            },
+        },
+        {
+            name: 'euro order with odd base units and a 0.5 percent fee',
+            release: 33333333n,
+            intent: intentFor({ amount: 77777777n, conversionRate: 920000000000000000n, fiatCurrency: EUR }),
+            feeBps: 50n,
+            expected: {
+                currencySymbol: '€',
+                contractedFiat: '71.56',
+                attestedFiat: '30.67',
+                netToBuyer: '33.16',
+                protocolFee: '0.16',
+                returnedToMaker: '44.44',
+            },
+        },
+        {
+            name: 'a fee below one display cent still shows a fee row of 0.00',
+            release: 1000000n,
+            intent: intentFor({ amount: 2000000n, conversionRate: 1000000000000000000n, fiatCurrency: USD }),
+            feeBps: 1n,
+            expected: {
+                currencySymbol: '$',
+                contractedFiat: '2.00',
+                attestedFiat: '1.00',
+                netToBuyer: '0.99',
+                protocolFee: '0.00',
+                returnedToMaker: '1.00',
+            },
+        },
+    ];
+    for (const row of rows) {
+        it(row.name, () => {
+            const result = reconcileSettlement({
+                attestation: attestationReleasing(row.release),
+                intent: row.intent,
+                chainId: PULSECHAIN,
+                feeBps: row.feeBps,
+            });
+            assert.deepEqual(result, row.expected);
+        });
+    }
+});
+describe('reconcileSettlement: nothing to reconcile', () => {
+    const partialRelease = attestationReleasing(60000000n);
+    it('returns null for a full settlement, so no partial story is told', () => {
+        const result = reconcileSettlement({
+            attestation: attestationReleasing(100000000n),
+            intent: hundredUsdc,
+            chainId: PULSECHAIN,
+            feeBps: 200n,
+        });
+        assert.equal(result, null);
+    });
+    it('returns null when the release exceeds the lock', () => {
+        const result = reconcileSettlement({
+            attestation: attestationReleasing(120000000n),
+            intent: hundredUsdc,
+            chainId: PULSECHAIN,
+            feeBps: 200n,
+        });
+        assert.equal(result, null);
+    });
+    const missingInputs = [
+        ['no attestation', { attestation: undefined, intent: hundredUsdc, chainId: PULSECHAIN, feeBps: 200n }],
+        ['no intent', { attestation: partialRelease, intent: undefined, chainId: PULSECHAIN, feeBps: 200n }],
+        [
+            'an intent of zero amount',
+            {
+                attestation: partialRelease,
+                intent: intentFor({ amount: 0n, conversionRate: 1n, fiatCurrency: USD }),
+                chainId: PULSECHAIN,
+                feeBps: 200n,
+            },
+        ],
+        [
+            'an intent of zero rate',
+            {
+                attestation: partialRelease,
+                intent: intentFor({ amount: 5n, conversionRate: 0n, fiatCurrency: USD }),
+                chainId: PULSECHAIN,
+                feeBps: 200n,
+            },
+        ],
+        [
+            'a currency this build does not know',
+            {
+                attestation: partialRelease,
+                intent: intentFor({ amount: 100000000n, conversionRate: 10n ** 18n, fiatCurrency: `0x${'12'.repeat(32)}` }),
+                chainId: PULSECHAIN,
+                feeBps: 200n,
+            },
+        ],
+        ['a chain with no settlement token', { attestation: partialRelease, intent: hundredUsdc, chainId: UNSUPPORTED_CHAIN, feeBps: 200n }],
+    ];
+    for (const [name, input] of missingInputs) {
+        it(`returns null for ${name}`, () => {
+            assert.equal(reconcileSettlement(input), null);
+        });
+    }
+});

package/dist/buy/submitStepDerivations.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Pure derivations extracted from SubmitStep.tsx.
+ *
+ * SubmitStep is 1016 lines of state machine + UI. Most of the JSX is
+ * conditional on the lifecycle status — surfacing that branching as a
+ * named, tested predicate keeps the JSX side readable and lets us pin
+ * the status → label / disabled / display mappings without mounting
+ * the whole step (which needs wagmi + tx-flight + indexer + toast
+ * contexts wired up).
+ *
+ * Bigint throughout — see the `money-values-stay-bigint-until-display`
+ * rule. The only string conversions happen at the formatter boundary
+ * (formatUnits / formatTokenDisplay), which is the display layer.
+ */
+import type { V3AttestationResponseObject } from '../peer-types.js';
+/** Where the attestation request and the on-chain submission stand. */
+export type AttestationState = 'idle' | 'requesting' | 'verifying' | 'verified' | 'submitting' | 'confirming' | 'syncing' | 'complete' | 'error';
+/**
+ * Discriminated union for attestation + submission lifecycle. Mirrors
+ * the local type in SubmitStep so the derivations don't depend on a
+ * re-export from the consumer file (avoids a cycle if SubmitStep ever
+ * starts importing helpers from here).
+ */
+export type AttestationResult = {
+    status: 'idle';
+} | {
+    status: 'requesting';
+} | {
+    status: 'verifying';
+    data: V3AttestationResponseObject;
+} | {
+    status: 'verified';
+    data: V3AttestationResponseObject;
+} | {
+    status: 'submitting';
+    data: V3AttestationResponseObject;
+} | {
+    status: 'confirming';
+    data: V3AttestationResponseObject;
+} | {
+    status: 'syncing';
+    data: V3AttestationResponseObject;
+} | {
+    status: 'complete';
+    data: V3AttestationResponseObject;
+} | {
+    status: 'error';
+    error: string;
+    isSubmissionError: boolean;
+    data?: V3AttestationResponseObject;
+};
+/** Map the lifecycle result to the simpler AttestationState enum the
+ *  UI components consume. The mapping is 1:1 but pinning it here lets
+ *  a future refactor that splits the result type from the UI state
+ *  type catch the divergence in a test rather than at render time. */
+export declare function attestationStateFromResult(result: AttestationResult): AttestationState;
+/** Pull the attestation payload out of any lifecycle status that has
+ *  it (including `error` when the failure was post-verification). */
+export declare function attestationFromResult(result: AttestationResult): V3AttestationResponseObject | null;
+/** Returns the error string only when the result is in the error state. */
+export declare function attestationErrorFromResult(result: AttestationResult): string | null;
+/** Returns true when the error originated post-verification (i.e.
+ *  during the on-chain submission), as opposed to during the
+ *  attestation request itself. Drives different retry-button copy. */
+export declare function isSubmissionErrorFromResult(result: AttestationResult): boolean;
+/** True when the attestation has been verified and the user is in
+ *  one of the downstream submission states. Used to gate the
+ *  receive-first card's "verified" recap row vs the in-progress
+ *  spinner row. */
+export declare function isVerifiedOrLater(state: AttestationState): boolean;
+/** Inputs that decide whether the Complete Order button is waiting. */
+export interface CompleteButtonProgressInput {
+    state: AttestationState;
+    /** True once the protocol fee has loaded, so "You'll receive" is final. */
+    isFeeReady: boolean;
+}
+/** Loading label for the Complete Order button, or undefined when the
+ *  button is not waiting on anything and shows its default label.
+ *
+ *  Covers the wait BEFORE the order is actionable (proof requested,
+ *  payment being verified, fee still loading) as well as the
+ *  submission phases. Without the first group the button sat muted
+ *  with no spinner while data loaded, and the only cue that it was
+ *  ready was its outline changing color. */
+export declare function buttonLoadingTextFromState({ state, isFeeReady, }: CompleteButtonProgressInput): string | undefined;
+/** True while the button is waiting: wagmi reports `isPending`, or
+ *  the state has a loading label. Deriving it from the label keeps
+ *  the spinner and its text from ever disagreeing. */
+export declare function isCompleteButtonLoading({ isPending, ...progress }: CompleteButtonProgressInput & {
+    isPending: boolean;
+}): boolean;
+/** True when the Complete Onramp button should be disabled.
+ *  Enabled only in the `verified` state (when there's an attestation
+ *  ready to submit) and never when already loading. */
+export declare function isCompleteButtonDisabled({ state, isLoading, }: {
+    state: AttestationState;
+    isLoading: boolean;
+}): boolean;
+/** Build the protocol-fee display string for the receive-first card.
+ *  Returns null when there's no fee for this provider (normalizedBps
+ *  is 0n) or when any required input is missing.
+ *
+ *  The two-step trim/pad keeps a fee like `0.0050` from rendering
+ *  with trailing zeros while still preserving the minimum 2-decimal
+ *  padding (`0.005` stays `0.005`, `0.50` stays `0.50`).
+ */
+export declare function formatFeeTokenAmount({ intentAmount, tokenDecimals, feeBps, }: {
+    intentAmount: bigint | null | undefined;
+    tokenDecimals: number | null | undefined;
+    feeBps: bigint | null | undefined;
+}): string | null;
+/** Net token amount after fee deduction, formatted to 2 decimals.
+ *  Falls back to the un-deducted `defaultDisplay` when there's no fee
+ *  or when any required input is missing — the caller passes the
+ *  display value already computed by useOrderDisplayValues so the
+ *  fallback has no extra formatting cost. */
+export declare function formatNetTokenAmount({ intentAmount, tokenDecimals, feeBps, defaultDisplay, }: {
+    intentAmount: bigint | null | undefined;
+    tokenDecimals: number | null | undefined;
+    feeBps: bigint | null | undefined;
+    defaultDisplay: string;
+}): string;

package/dist/buy/submitStepDerivations.js

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Pure derivations extracted from SubmitStep.tsx.
+ *
+ * SubmitStep is 1016 lines of state machine + UI. Most of the JSX is
+ * conditional on the lifecycle status — surfacing that branching as a
+ * named, tested predicate keeps the JSX side readable and lets us pin
+ * the status → label / disabled / display mappings without mounting
+ * the whole step (which needs wagmi + tx-flight + indexer + toast
+ * contexts wired up).
+ *
+ * Bigint throughout — see the `money-values-stay-bigint-until-display`
+ * rule. The only string conversions happen at the formatter boundary
+ * (formatUnits / formatTokenDisplay), which is the display layer.
+ */
+import { formatUnits } from '../units.js';
+import { calculateFeeAmount, calculateNetAmount } from '../fees.js';
+/** Map the lifecycle result to the simpler AttestationState enum the
+ *  UI components consume. The mapping is 1:1 but pinning it here lets
+ *  a future refactor that splits the result type from the UI state
+ *  type catch the divergence in a test rather than at render time. */
+export function attestationStateFromResult(result) {
+    return result.status;
+}
+/** Pull the attestation payload out of any lifecycle status that has
+ *  it (including `error` when the failure was post-verification). */
+export function attestationFromResult(result) {
+    switch (result.status) {
+        case 'verifying':
+        case 'verified':
+        case 'submitting':
+        case 'confirming':
+        case 'syncing':
+        case 'complete':
+            return result.data;
+        case 'error':
+            return result.data ?? null;
+        default:
+            return null;
+    }
+}
+/** Returns the error string only when the result is in the error state. */
+export function attestationErrorFromResult(result) {
+    return result.status === 'error' ? result.error : null;
+}
+/** Returns true when the error originated post-verification (i.e.
+ *  during the on-chain submission), as opposed to during the
+ *  attestation request itself. Drives different retry-button copy. */
+export function isSubmissionErrorFromResult(result) {
+    return result.status === 'error' && result.isSubmissionError;
+}
+/** True when the attestation has been verified and the user is in
+ *  one of the downstream submission states. Used to gate the
+ *  receive-first card's "verified" recap row vs the in-progress
+ *  spinner row. */
+export function isVerifiedOrLater(state) {
+    return (state === 'verified' ||
+        state === 'submitting' ||
+        state === 'confirming' ||
+        state === 'syncing' ||
+        state === 'complete');
+}
+/** Loading label for the Complete Order button, or undefined when the
+ *  button is not waiting on anything and shows its default label.
+ *
+ *  Covers the wait BEFORE the order is actionable (proof requested,
+ *  payment being verified, fee still loading) as well as the
+ *  submission phases. Without the first group the button sat muted
+ *  with no spinner while data loaded, and the only cue that it was
+ *  ready was its outline changing color. */
+export function buttonLoadingTextFromState({ state, isFeeReady, }) {
+    switch (state) {
+        case 'idle':
+        case 'requesting':
+            return 'Loading proof...';
+        case 'verifying':
+            return 'Verifying payment...';
+        case 'verified':
+            return isFeeReady ? undefined : 'Loading fees...';
+        case 'submitting':
+            return 'Submitting...';
+        case 'confirming':
+            return 'Confirming...';
+        case 'syncing':
+            return 'Syncing...';
+        default:
+            return undefined;
+    }
+}
+/** True while the button is waiting: wagmi reports `isPending`, or
+ *  the state has a loading label. Deriving it from the label keeps
+ *  the spinner and its text from ever disagreeing. */
+export function isCompleteButtonLoading({ isPending, ...progress }) {
+    return isPending || buttonLoadingTextFromState(progress) !== undefined;
+}
+/** True when the Complete Onramp button should be disabled.
+ *  Enabled only in the `verified` state (when there's an attestation
+ *  ready to submit) and never when already loading. */
+export function isCompleteButtonDisabled({ state, isLoading, }) {
+    return state !== 'verified' && !isLoading;
+}
+// ---------------------------------------------------------------------------
+// Fee + net display
+// ---------------------------------------------------------------------------
+/** Build the protocol-fee display string for the receive-first card.
+ *  Returns null when there's no fee for this provider (normalizedBps
+ *  is 0n) or when any required input is missing.
+ *
+ *  The two-step trim/pad keeps a fee like `0.0050` from rendering
+ *  with trailing zeros while still preserving the minimum 2-decimal
+ *  padding (`0.005` stays `0.005`, `0.50` stays `0.50`).
+ */
+export function formatFeeTokenAmount({ intentAmount, tokenDecimals, feeBps, }) {
+    if (!intentAmount || tokenDecimals === null || tokenDecimals === undefined)
+        return null;
+    if (!feeBps || feeBps === 0n)
+        return null;
+    const fee = calculateFeeAmount({ amount: intentAmount, feeBps });
+    const raw = formatUnits(fee, { decimals: tokenDecimals, truncateDecimals: tokenDecimals });
+    const [int, frac = ''] = raw.split('.');
+    const trimmed = frac.length > 2 ? frac.replace(/0+$/, '') : frac;
+    return `${int}.${trimmed.padEnd(2, '0')}`;
+}
+/** Net token amount after fee deduction, formatted to 2 decimals.
+ *  Falls back to the un-deducted `defaultDisplay` when there's no fee
+ *  or when any required input is missing — the caller passes the
+ *  display value already computed by useOrderDisplayValues so the
+ *  fallback has no extra formatting cost. */
+export function formatNetTokenAmount({ intentAmount, tokenDecimals, feeBps, defaultDisplay, }) {
+    if (!intentAmount || tokenDecimals === null || tokenDecimals === undefined) {
+        return defaultDisplay;
+    }
+    if (!feeBps || feeBps === 0n)
+        return defaultDisplay;
+    const net = calculateNetAmount({ grossAmount: intentAmount, feeBps });
+    return formatUnits(net, {
+        decimals: tokenDecimals,
+        truncateDecimals: 2,
+        padDecimals: 2,
+    });
+}

package/dist/buy/submitStepDerivations.test.d.ts

@@ -0,0 +1 @@
+export {};