@provex/utils 1.10.0 → 1.11.0-rc.20261018212258.bdc024c

package/dist/contracts.d.ts

@@ -84,6 +84,28 @@ export declare const v3BaseContracts: V3Contracts;
  * rather than a single `orchestrator()` address.
  */
 export declare const v4BaseContracts: V4Contracts;
+/**
+ * Base contracts zkp2p moved to after {@link v4BaseContracts}, INDEXED ONLY.
+ *
+ * From 2026-08-05 zkp2p routes every new Base intent through OrchestratorV3,
+ * and from 2026-08-11 every payment proof through UnifiedPaymentVerifierV3. The
+ * OrchestratorRegistry removed OrchestratorV2 on 2026-08-27. Their events match
+ * OrchestratorV2 / UnifiedPaymentVerifierV2 by signature, so the indexer adds
+ * them to the same streams. Without them, Base intents and fills stopped in our
+ * data on 2026-08-27 while on-chain activity kept growing.
+ *
+ * Kept OUT of `v4BaseContracts.orchestrator` on purpose: the app signals to
+ * the last configured orchestrator (`getConfiguredOrchestratorForEscrow` uses
+ * `.at(-1)`), and OrchestratorV3 adds a lifecycle hook (dispute protection and
+ * stake) that has not been checked against our orders. Switching the Base order
+ * flow is a separate decision.
+ *
+ * Deploy blocks: OrchestratorV3 49494316, UnifiedPaymentVerifierV3 49352536.
+ */
+export declare const baseIndexOnlyContracts: {
+    readonly orchestrator: [`0x${string}`];
+    readonly unifiedPaymentVerifier: [`0x${string}`];
+};
 /**
  * V4 contracts on PulseChain (Chain ID 369) — LIVE as of 2026-07-24.
  *

package/dist/contracts.js

@@ -97,6 +97,28 @@ export const v4BaseContracts = {
     orchestrator: [getAddress('0x888888359E981B5225CA48fbCdCeff702FC3b888')],
     orchestratorRegistry: getAddress('0xBe9fED15ED7A4B915C03EFcEcb9662739C3382A9'),
 };
+/**
+ * Base contracts zkp2p moved to after {@link v4BaseContracts}, INDEXED ONLY.
+ *
+ * From 2026-08-05 zkp2p routes every new Base intent through OrchestratorV3,
+ * and from 2026-08-11 every payment proof through UnifiedPaymentVerifierV3. The
+ * OrchestratorRegistry removed OrchestratorV2 on 2026-08-27. Their events match
+ * OrchestratorV2 / UnifiedPaymentVerifierV2 by signature, so the indexer adds
+ * them to the same streams. Without them, Base intents and fills stopped in our
+ * data on 2026-08-27 while on-chain activity kept growing.
+ *
+ * Kept OUT of `v4BaseContracts.orchestrator` on purpose: the app signals to
+ * the last configured orchestrator (`getConfiguredOrchestratorForEscrow` uses
+ * `.at(-1)`), and OrchestratorV3 adds a lifecycle hook (dispute protection and
+ * stake) that has not been checked against our orders. Switching the Base order
+ * flow is a separate decision.
+ *
+ * Deploy blocks: OrchestratorV3 49494316, UnifiedPaymentVerifierV3 49352536.
+ */
+export const baseIndexOnlyContracts = {
+    orchestrator: [getAddress('0x014025fDE093f8701d86e9f38e2C3a9b779cb5c7')],
+    unifiedPaymentVerifier: [getAddress('0xC6F4a193576C60892a47e111Bb5706c30162502B')],
+};
 /**
  * V4 contracts on PulseChain (Chain ID 369) — LIVE as of 2026-07-24.
  *

package/dist/conversionRates.d.ts

@@ -192,7 +192,8 @@ export declare const convertTokenInputToCurrency: ({ token, amountOutInt, rate }
  * @param params.currency - Currency info with decimals
  * @param params.currencyAmountInt - Fiat amount as bigint
  * @param params.rate - Conversion rate with 18 decimals (1e18 = 1:1)
- * @returns Token amount as bigint, floored to smallest token unit
+ * @returns Token amount in base units, floored so the buyer is never credited more than paid
+ * @throws RangeError when `rate` is zero or negative
  *
  * @example
  * ```ts
@@ -216,9 +217,9 @@ export declare const convertCurrencyToTokenOutput: ({ token, currency, currencyA
  * Smallest currency amount that {@link convertCurrencyToTokenOutput} turns into
  * at least `tokenAmount` tokens at `rate`.
  *
- * `convertCurrencyToTokenOutput` floors its result to a whole multiple of
- * `10^(token.decimals - currency.decimals)`. The inverse therefore rounds the
- * token amount UP to that same multiple before dividing, and rounds the
+ * `convertCurrencyToTokenOutput` floors its result onto the grid of
+ * {@link tokenOutputGrid}. The inverse therefore rounds the
+ * token amount UP to that same grid before dividing, and rounds the
  * currency amount UP. The result is exact: it fills `tokenAmount`, and one
  * currency unit less does not.
  *

package/dist/conversionRates.js

@@ -251,6 +251,37 @@ export const convertTokenInputToCurrency = ({ token, amountOutInt, rate }) => {
     const finalAmountInInt = amountInInt + (negativeSpace === oneCent ? 0n : negativeSpace);
     return finalAmountInInt;
 };
+const ONE_ETHER = 10n ** 18n;
+/**
+ * Throw a clear error when a conversion rate cannot be divided by.
+ *
+ * @param rate - Conversion rate with 18 decimals
+ * @throws RangeError when the rate is zero or negative
+ */
+const assertPositiveRate = (rate) => {
+    if (rate > 0n)
+        return;
+    throw new RangeError(`Conversion rate must be positive, received ${rate}`);
+};
+/**
+ * Granularity, in token base units, that {@link convertCurrencyToTokenOutput}
+ * floors onto.
+ *
+ * A currency with cents floors to a whole cent of the token (10^4 base units
+ * for a 6-decimal token and 2 currency decimals). A currency without cents
+ * (JPY, KRW, VND, UGX) has no such grid, so it keeps every base unit. Using
+ * the cent grid there floored 20,000 won at 1,400 won per USDC to 14 USDC
+ * instead of 14.285714 USDC.
+ *
+ * @param params.token - Token info with decimals
+ * @param params.currency - Currency info with decimals
+ * @returns Grid size in token base units (1n means no grid)
+ */
+const tokenOutputGrid = ({ token, currency }) => {
+    if (currency.decimals === 0)
+        return 1n;
+    return 10n ** BigInt(token.decimals - currency.decimals);
+};
 /**
  * Convert a fiat currency amount back to token amount (inverse of convertTokenInputToCurrency).
  * Accounts for the cent-rounding that was applied during the forward conversion.
@@ -260,7 +291,8 @@ export const convertTokenInputToCurrency = ({ token, amountOutInt, rate }) => {
  * @param params.currency - Currency info with decimals
  * @param params.currencyAmountInt - Fiat amount as bigint
  * @param params.rate - Conversion rate with 18 decimals (1e18 = 1:1)
- * @returns Token amount as bigint, floored to smallest token unit
+ * @returns Token amount in base units, floored so the buyer is never credited more than paid
+ * @throws RangeError when `rate` is zero or negative
  *
  * @example
  * ```ts
@@ -275,25 +307,21 @@ export const convertTokenInputToCurrency = ({ token, amountOutInt, rate }) => {
  * ```
  */
 export const convertCurrencyToTokenOutput = ({ token, currency, currencyAmountInt, rate, }) => {
-    const smallestUnit = 10n ** BigInt(token.decimals - currency.decimals);
-    const oneEther = 10n ** 18n;
-    // First, we need to find the original amount before cent-rounding was applied
-    // The original function rounds up to the nearest cent, so we need to find
-    // the maximum token amount that would result in this currency amount after rounding
-    // Start with the direct inverse calculation
-    // console.log('currencyAmountInt', currencyAmountInt, smallestUnit, converter, rate)
-    let tokenAmountOut = (currencyAmountInt * smallestUnit * oneEther) / rate;
-    const remainder = tokenAmountOut % smallestUnit;
-    const finalTokenAmountOut = (tokenAmountOut - remainder);
-    return finalTokenAmountOut;
+    assertPositiveRate(rate);
+    const unit = 10n ** BigInt(token.decimals - currency.decimals);
+    const grid = tokenOutputGrid({ token, currency });
+    // Exact token amount in base units, then floor onto the grid so the buyer is
+    // never credited more than they paid.
+    const exactTokenAmount = (currencyAmountInt * unit * ONE_ETHER) / rate;
+    return exactTokenAmount - (exactTokenAmount % grid);
 };
 /**
  * Smallest currency amount that {@link convertCurrencyToTokenOutput} turns into
  * at least `tokenAmount` tokens at `rate`.
  *
- * `convertCurrencyToTokenOutput` floors its result to a whole multiple of
- * `10^(token.decimals - currency.decimals)`. The inverse therefore rounds the
- * token amount UP to that same multiple before dividing, and rounds the
+ * `convertCurrencyToTokenOutput` floors its result onto the grid of
+ * {@link tokenOutputGrid}. The inverse therefore rounds the
+ * token amount UP to that same grid before dividing, and rounds the
  * currency amount UP. The result is exact: it fills `tokenAmount`, and one
  * currency unit less does not.
  *
@@ -307,12 +335,12 @@ export const convertCurrencyToTokenOutput = ({ token, currency, currencyAmountIn
 export const minimumCurrencyAmountForTokenAmount = ({ token, currency, tokenAmount, rate, }) => {
     if (rate <= 0n)
         return null;
-    const smallestUnit = 10n ** BigInt(token.decimals - currency.decimals);
-    const oneEther = 10n ** 18n;
-    const wholeUnits = (tokenAmount + smallestUnit - 1n) / smallestUnit;
-    const tokenAmountOnUnitGrid = wholeUnits * smallestUnit;
-    const denominator = smallestUnit * oneEther;
-    return (tokenAmountOnUnitGrid * rate + denominator - 1n) / denominator;
+    const unit = 10n ** BigInt(token.decimals - currency.decimals);
+    const grid = tokenOutputGrid({ token, currency });
+    const gridSteps = (tokenAmount + grid - 1n) / grid;
+    const tokenAmountOnGrid = gridSteps * grid;
+    const denominator = unit * ONE_ETHER;
+    return (tokenAmountOnGrid * rate + denominator - 1n) / denominator;
 };
 /**
  * Largest currency amount that {@link convertCurrencyToTokenOutput} turns into
@@ -331,13 +359,12 @@ export const minimumCurrencyAmountForTokenAmount = ({ token, currency, tokenAmou
 export const maximumCurrencyAmountForTokenAmount = ({ token, currency, tokenAmount, rate, }) => {
     if (rate <= 0n)
         return null;
-    const smallestUnit = 10n ** BigInt(token.decimals - currency.decimals);
-    const oneEther = 10n ** 18n;
-    const floorUnits = tokenAmount / smallestUnit;
-    const nextUnitBoundary = (floorUnits + 1n) * smallestUnit;
-    const denominator = smallestUnit * oneEther;
-    // Largest c with c * smallestUnit * 1e18 / rate < nextUnitBoundary.
-    return (nextUnitBoundary * rate + denominator - 1n) / denominator - 1n;
+    const unit = 10n ** BigInt(token.decimals - currency.decimals);
+    const grid = tokenOutputGrid({ token, currency });
+    const nextGridBoundary = (tokenAmount / grid + 1n) * grid;
+    const denominator = unit * ONE_ETHER;
+    // Largest c with c * unit * 1e18 / rate < nextGridBoundary.
+    return (nextGridBoundary * rate + denominator - 1n) / denominator - 1n;
 };
 /**
  * The token amount an order is created with: what the buyer's currency amount

package/dist/conversionRates.test.js

@@ -469,6 +469,65 @@ describe('conversionRates', () => {
             // Floored to smallest unit (10^4 for 6-2 decimal difference)
             assert.equal(result, 100010000n);
         });
+        describe('zero-decimal currencies keep the full token precision', () => {
+            const ONE_ETHER = 10n ** 18n;
+            const convert = (currency, currencyAmountInt, rate) => convertCurrencyToTokenOutput({ token: MOCK_TOKEN, currency, currencyAmountInt, rate });
+            it('20,000 won at 1,400 won per USDC is 14.285714 USDC, not 14', () => {
+                // 20000 / 1400 = 14.285714285..., rounded DOWN at the sixth decimal.
+                assert.equal(convert(SUPPORTED_CURRENCIES.KRW, 20000n, 1400n * ONE_ETHER), 14285714n);
+            });
+            it('an amount below one token still buys a fraction of a token', () => {
+                // 500 / 1400 = 0.357142857...
+                assert.equal(convert(SUPPORTED_CURRENCIES.KRW, 500n, 1400n * ONE_ETHER), 357142n);
+                // 1 / 151 = 0.006622516...
+                assert.equal(convert(SUPPORTED_CURRENCIES.JPY, 1n, 151n * ONE_ETHER), 6622n);
+            });
+            it('covers every zero-decimal currency (JPY, KRW, VND, UGX)', () => {
+                assert.equal(convert(SUPPORTED_CURRENCIES.JPY, 15000n, 150n * ONE_ETHER), 100000000n);
+                assert.equal(convert(SUPPORTED_CURRENCIES.VND, 1000000n, 25000n * ONE_ETHER), 40000000n);
+                // 10000 / 3700 = 2.702702702...
+                assert.equal(convert(SUPPORTED_CURRENCIES.UGX, 10000n, 3700n * ONE_ETHER), 2702702n);
+            });
+            it('never credits more than the buyer paid, and is within one base unit of it', () => {
+                const rate = 1402n * ONE_ETHER + 123456789n;
+                for (const won of [1n, 7n, 999n, 20000n, 1234567n, 987654321n]) {
+                    const tokens = convert(SUPPORTED_CURRENCIES.KRW, won, rate);
+                    // tokens / 1e6 USDC * rate / 1e18 won per USDC must not exceed the won paid.
+                    const paidScaled = won * 1000000n * ONE_ETHER;
+                    assert.ok(tokens * rate <= paidScaled, `${won} won over-credited`);
+                    assert.ok((tokens + 1n) * rate > paidScaled, `${won} won under-credited by more than one base unit`);
+                }
+            });
+        });
+        describe('two-decimal currencies are unchanged', () => {
+            const ONE_ETHER = 10n ** 18n;
+            const convert = (currency, currencyAmountInt, rate) => convertCurrencyToTokenOutput({ token: MOCK_TOKEN, currency, currencyAmountInt, rate });
+            it('USD still floors to a whole cent of the token', () => {
+                // 100.00 / 1.05 = 95.238095...; the cent grid keeps 95.23.
+                assert.equal(convert(SUPPORTED_CURRENCIES.USD, 10000n, 1050000000000000000n), 95230000n);
+            });
+            it('EUR and GBP still floor to a whole cent of the token', () => {
+                // 100.00 / 0.92 = 108.695652...; the cent grid keeps 108.69.
+                assert.equal(convert(SUPPORTED_CURRENCIES.EUR, 10000n, 920000000000000000n), 108690000n);
+                // 50.00 / 0.8 = 62.50 exactly.
+                assert.equal(convert(SUPPORTED_CURRENCIES.GBP, 5000n, 800000000000000000n), 62500000n);
+            });
+            it('USD one cent buys one cent of the token at par', () => {
+                assert.equal(convert(SUPPORTED_CURRENCIES.USD, 1n, ONE_ETHER), 10000n);
+            });
+        });
+        describe('a rate that is not positive', () => {
+            for (const rate of [0n, -1n, -1400n * 10n ** 18n]) {
+                it(`throws a clear error for rate ${rate}`, () => {
+                    assert.throws(() => convertCurrencyToTokenOutput({
+                        token: MOCK_TOKEN,
+                        currency: SUPPORTED_CURRENCIES.KRW,
+                        currencyAmountInt: 20000n,
+                        rate,
+                    }), /rate must be positive/i);
+                });
+            }
+        });
     });
     describe('currency bounds for a token amount (inverse of convertCurrencyToTokenOutput)', () => {
         const ONE_ETHER = 10n ** 18n;

package/dist/currencies.d.ts

@@ -219,6 +219,62 @@ export declare function getCurrencyByContractId(contractId: string): Currency |
  * @returns The formatted currency amount
  */
 export declare function formatCurrencyAmount(amount: string | number, currencyCode: string): string;
+/** From this many whole currency units up, {@link formatCurrencyTotal} switches to compact notation. */
+export declare const COMPACT_TOTAL_THRESHOLD_MAJOR_UNITS = 100000n;
+/**
+ * Format a total of money for a small space, such as the "escrowed" line of a
+ * payment method row.
+ *
+ * - Below 100,000 whole units: grouped digits and no decimals ("$12,345").
+ * - At or above 100,000 whole units: compact notation and no decimals ("$2M").
+ * - Below one whole unit but above zero: the currency's own decimals, so a
+ *   real amount never reads as zero ("$0.40").
+ *
+ * The text is cut down, never rounded up, so it never claims more than the
+ * bigint holds. The currency symbol and the digit conventions come from
+ * `Intl.NumberFormat` for `locale`. A ticker that `Intl` does not know falls
+ * back to the currency's own symbol in front of the digits.
+ *
+ * @param params.amount - Amount in the currency's base units (cents for USD, whole units for KRW)
+ * @param params.currency - Currency the amount is in
+ * @param params.locale - BCP 47 tag that sets digit grouping and symbol placement. Default "en-US".
+ * @returns The formatted text
+ *
+ * @example
+ * ```ts
+ * formatCurrencyTotal({ amount: 1_234_500n, currency: SUPPORTED_CURRENCIES.USD }) // "$12,345"
+ * formatCurrencyTotal({ amount: 250_000_000n, currency: SUPPORTED_CURRENCIES.USD }) // "$2M"
+ * ```
+ */
+export declare function formatCurrencyTotal({ amount, currency, locale, }: {
+    amount: bigint;
+    currency: Currency;
+    locale?: string;
+}): string;
+/**
+ * Format a total of tokens for a small space, such as the "escrowed" line of a
+ * payment method row, with the same rules as {@link formatCurrencyTotal}:
+ * grouped whole units, compact from 100,000 up, two decimals below one token,
+ * and always cut down, never rounded up. The symbol follows the number.
+ *
+ * @param params.amount - Amount in the token's base units
+ * @param params.decimals - The token's decimals
+ * @param params.symbol - The token's symbol, e.g. "USDC"
+ * @param params.locale - BCP 47 tag for digit grouping. Default "en-US".
+ * @returns The formatted text
+ *
+ * @example
+ * ```ts
+ * formatTokenTotal({ amount: 1_177_250_000n, decimals: 6, symbol: 'USDC' }) // "1,177 USDC"
+ * formatTokenTotal({ amount: 2_950_000_000_000n, decimals: 6, symbol: 'USDC' }) // "2.9M USDC"
+ * ```
+ */
+export declare function formatTokenTotal({ amount, decimals, symbol, locale, }: {
+    amount: bigint;
+    decimals: number;
+    symbol: string;
+    locale?: string;
+}): string;
 /**
  * Get all supported currencies
  * @returns All supported currencies

package/dist/currencies.js

@@ -278,6 +278,141 @@ export function formatCurrencyAmount(amount, currencyCode) {
     const formattedWithSeparators = addThousandsSeparator(formatted);
     return `${currencyInfo.symbol}${formattedWithSeparators}`;
 }
+/** From this many whole currency units up, {@link formatCurrencyTotal} switches to compact notation. */
+export const COMPACT_TOTAL_THRESHOLD_MAJOR_UNITS = 100000n;
+/**
+ * Formatters already built, by locale, currency, notation and fraction digits.
+ * Building an `Intl.NumberFormat` is slow and a list of rows asks for the same
+ * few shapes again and again, so each shape is built once. A shape the runtime
+ * rejects is cached as its symbol fallback, so the failed attempt is not repeated.
+ */
+const totalFormatterCache = new Map();
+/**
+ * The formatter for one shape of total, built once.
+ *
+ * @param params.fractionDigits - Digits for a standard figure. Ignored in compact notation, which always uses 0 to 1.
+ */
+function getTotalFormatter({ locale, currency, isCompact, fractionDigits, }) {
+    const cacheKey = [locale, currency.ticker, currency.symbol, isCompact ? 'compact' : 'standard', isCompact ? 'compact' : fractionDigits].join('|');
+    const cached = totalFormatterCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const numberOptions = totalNumberOptions({ isCompact, fractionDigits });
+    const formatter = buildTotalFormatter({ locale, currency, numberOptions });
+    totalFormatterCache.set(cacheKey, formatter);
+    return formatter;
+}
+/**
+ * Number options shared by every total: compact or standard notation, and
+ * always cut down (`floor`), never rounded up.
+ */
+function totalNumberOptions({ isCompact, fractionDigits, }) {
+    // Compact notation applies the digits to the shortened figure, so one digit
+    // shows 2,900,000 as "$2.9M" instead of understating it as "$2M".
+    return {
+        notation: isCompact ? 'compact' : 'standard',
+        minimumFractionDigits: isCompact ? 0 : fractionDigits,
+        maximumFractionDigits: isCompact ? 1 : fractionDigits,
+        roundingMode: 'floor',
+    };
+}
+/**
+ * Shape a total of `amount` base units for display.
+ *
+ * @param params.decimals - Base-unit decimals of the amount
+ * @param params.decimalsBelowOneUnit - Digits shown when the total is below one whole unit
+ */
+function totalShape({ amount, decimals, decimalsBelowOneUnit, }) {
+    const unit = 10n ** BigInt(decimals);
+    const wholeUnits = amount / unit;
+    const isBelowOneUnit = wholeUnits === 0n && amount > 0n;
+    return {
+        value: isBelowOneUnit ? Number(amount) / Number(unit) : wholeUnits,
+        isCompact: wholeUnits >= COMPACT_TOTAL_THRESHOLD_MAJOR_UNITS,
+        fractionDigits: isBelowOneUnit ? decimalsBelowOneUnit : 0,
+    };
+}
+/** Build the currency-style formatter, or the symbol-prefix fallback when the ticker is not a valid `Intl` currency. */
+function buildTotalFormatter({ locale, currency, numberOptions, }) {
+    try {
+        const currencyFormat = new Intl.NumberFormat(locale, { ...numberOptions, style: 'currency', currency: currency.ticker });
+        return (value) => currencyFormat.format(value);
+    }
+    catch (error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        const plainFormat = new Intl.NumberFormat(locale, numberOptions);
+        return (value) => `${currency.symbol}${plainFormat.format(value)}`;
+    }
+}
+/**
+ * Format a total of money for a small space, such as the "escrowed" line of a
+ * payment method row.
+ *
+ * - Below 100,000 whole units: grouped digits and no decimals ("$12,345").
+ * - At or above 100,000 whole units: compact notation and no decimals ("$2M").
+ * - Below one whole unit but above zero: the currency's own decimals, so a
+ *   real amount never reads as zero ("$0.40").
+ *
+ * The text is cut down, never rounded up, so it never claims more than the
+ * bigint holds. The currency symbol and the digit conventions come from
+ * `Intl.NumberFormat` for `locale`. A ticker that `Intl` does not know falls
+ * back to the currency's own symbol in front of the digits.
+ *
+ * @param params.amount - Amount in the currency's base units (cents for USD, whole units for KRW)
+ * @param params.currency - Currency the amount is in
+ * @param params.locale - BCP 47 tag that sets digit grouping and symbol placement. Default "en-US".
+ * @returns The formatted text
+ *
+ * @example
+ * ```ts
+ * formatCurrencyTotal({ amount: 1_234_500n, currency: SUPPORTED_CURRENCIES.USD }) // "$12,345"
+ * formatCurrencyTotal({ amount: 250_000_000n, currency: SUPPORTED_CURRENCIES.USD }) // "$2M"
+ * ```
+ */
+export function formatCurrencyTotal({ amount, currency, locale = 'en-US', }) {
+    const { value, isCompact, fractionDigits } = totalShape({
+        amount,
+        decimals: currency.decimals,
+        decimalsBelowOneUnit: currency.decimals,
+    });
+    return getTotalFormatter({ locale, currency, isCompact, fractionDigits })(value);
+}
+/** Digits a token total shows below one whole token: cents, not the token's full precision. */
+const TOKEN_TOTAL_DECIMALS_BELOW_ONE_UNIT = 2;
+/** Plain-number formatters for token totals, by locale and shape. */
+const tokenTotalFormatterCache = new Map();
+/**
+ * Format a total of tokens for a small space, such as the "escrowed" line of a
+ * payment method row, with the same rules as {@link formatCurrencyTotal}:
+ * grouped whole units, compact from 100,000 up, two decimals below one token,
+ * and always cut down, never rounded up. The symbol follows the number.
+ *
+ * @param params.amount - Amount in the token's base units
+ * @param params.decimals - The token's decimals
+ * @param params.symbol - The token's symbol, e.g. "USDC"
+ * @param params.locale - BCP 47 tag for digit grouping. Default "en-US".
+ * @returns The formatted text
+ *
+ * @example
+ * ```ts
+ * formatTokenTotal({ amount: 1_177_250_000n, decimals: 6, symbol: 'USDC' }) // "1,177 USDC"
+ * formatTokenTotal({ amount: 2_950_000_000_000n, decimals: 6, symbol: 'USDC' }) // "2.9M USDC"
+ * ```
+ */
+export function formatTokenTotal({ amount, decimals, symbol, locale = 'en-US', }) {
+    const shape = totalShape({
+        amount,
+        decimals,
+        decimalsBelowOneUnit: Math.min(decimals, TOKEN_TOTAL_DECIMALS_BELOW_ONE_UNIT),
+    });
+    const cacheKey = [locale, shape.isCompact ? 'compact' : shape.fractionDigits].join('|');
+    const cached = tokenTotalFormatterCache.get(cacheKey);
+    const formatter = cached ?? new Intl.NumberFormat(locale, totalNumberOptions(shape));
+    if (!cached)
+        tokenTotalFormatterCache.set(cacheKey, formatter);
+    return `${formatter.format(shape.value)} ${symbol}`;
+}
 /**
  * Get all supported currencies
  * @returns All supported currencies

package/dist/currencies.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { SUPPORTED_CURRENCIES, getCurrencyInfo, getCurrencyByContractId, getCurrencyNameByContractId, getAllSupportedCurrencies, isSupportedCurrency, formatCurrencyAmount, tickerToContractId, generateCurrencyId, formatDefaultRate, Currency, } from './currencies.js';
+import { SUPPORTED_CURRENCIES, getCurrencyInfo, getCurrencyByContractId, getCurrencyNameByContractId, getAllSupportedCurrencies, isSupportedCurrency, formatCurrencyAmount, tickerToContractId, generateCurrencyId, formatDefaultRate, formatCurrencyTotal, formatTokenTotal, Currency, } from './currencies.js';
 describe('currencies', () => {
     describe('SUPPORTED_CURRENCIES', () => {
         it('should have exactly 36 supported currencies', () => {
@@ -340,4 +340,122 @@ describe('currencies', () => {
             assert.equal(result, '1.000');
         });
     });
+    describe('formatTokenTotal', () => {
+        // The escrowed line shows USDC, not currency: one deposit with an odd
+        // rate (about $1,101 per USDC on Revolut) inflated a currency total.
+        const usdc = { decimals: 6, symbol: 'USDC' };
+        it('shows whole tokens with grouping and the symbol after', () => {
+            assert.equal(formatTokenTotal({ amount: 1177250000n, ...usdc }), '1,177 USDC');
+        });
+        it('cuts down instead of rounding up, so it never claims more than escrowed', () => {
+            assert.equal(formatTokenTotal({ amount: 1999999999n, ...usdc }), '1,999 USDC');
+        });
+        it('switches to compact notation from 100,000 tokens, still cut down', () => {
+            assert.equal(formatTokenTotal({ amount: 2990000000000n, ...usdc }), '2.9M USDC');
+        });
+        it('shows cents below one token so a real amount never reads as zero', () => {
+            assert.equal(formatTokenTotal({ amount: 400000n, ...usdc }), '0.40 USDC');
+        });
+    });
+    describe('formatCurrencyTotal', () => {
+        const { USD, KRW, JPY, EUR } = SUPPORTED_CURRENCIES;
+        it('shows full grouped digits below 100,000 whole units, with no decimals', () => {
+            assert.equal(formatCurrencyTotal({ amount: 1234567n, currency: USD }), '$12,345');
+            assert.equal(formatCurrencyTotal({ amount: 9999999n, currency: USD }), '$99,999');
+        });
+        it('switches to compact notation at exactly 100,000 whole units', () => {
+            assert.equal(formatCurrencyTotal({ amount: 10000000n, currency: USD }), '$100K');
+            assert.equal(formatCurrencyTotal({ amount: 300000000n, currency: USD }), '$3M');
+        });
+        it('keeps one compact decimal so a total is not understated by a whole unit', () => {
+            assert.equal(formatCurrencyTotal({ amount: 290000000n, currency: USD }), '$2.9M');
+            assert.equal(formatCurrencyTotal({ amount: 28400000n, currency: KRW }), '₩28.4M');
+        });
+        it('rounds compact values down: it never claims more than the amount holds', () => {
+            assert.equal(formatCurrencyTotal({ amount: 299999999n, currency: USD }), '$2.9M');
+            assert.equal(formatCurrencyTotal({ amount: 14999900n, currency: USD }), '$149.9K');
+        });
+        it('reads zero-decimal KRW as whole won, grouped and compact', () => {
+            assert.equal(formatCurrencyTotal({ amount: 99999n, currency: KRW }), '₩99,999');
+            assert.equal(formatCurrencyTotal({ amount: 140000000n, currency: KRW }), '₩140M');
+        });
+        it('uses the symbol and the digit conventions of the locale for JPY and EUR', () => {
+            assert.equal(formatCurrencyTotal({ amount: 54321n, currency: JPY }), '¥54,321');
+            assert.equal(formatCurrencyTotal({ amount: 15000000n, currency: EUR, locale: 'en-US' }), '€150K');
+            assert.equal(formatCurrencyTotal({ amount: 1234500n, currency: EUR, locale: 'de-DE' }), '12.345\u00a0€');
+        });
+        it('keeps the currency decimals below one unit so a real amount never reads as zero', () => {
+            assert.equal(formatCurrencyTotal({ amount: 40n, currency: USD }), '$0.40');
+        });
+        it('formats zero as a plain zero', () => {
+            assert.equal(formatCurrencyTotal({ amount: 0n, currency: USD }), '$0');
+        });
+        it('formats every supported currency without throwing', () => {
+            for (const currency of Object.values(SUPPORTED_CURRENCIES)) {
+                const text = formatCurrencyTotal({ amount: 123456789n, currency });
+                assert.ok(text.length > 0, currency.ticker);
+            }
+        });
+    });
+    describe('formatCurrencyTotal formatter cache', () => {
+        const { USD, KRW } = SUPPORTED_CURRENCIES;
+        /** Run `action` while counting every `Intl.NumberFormat` construction. */
+        const countConstructions = (action) => {
+            const Original = Intl.NumberFormat;
+            let constructions = 0;
+            Intl.NumberFormat = function (...args) {
+                constructions += 1;
+                return new Original(...args);
+            };
+            try {
+                action();
+            }
+            finally {
+                Intl.NumberFormat = Original;
+            }
+            return constructions;
+        };
+        it('builds one formatter per key and returns the same text on every call', () => {
+            // A locale no other test uses, so the module cache starts empty for it.
+            const locale = 'fr-CA';
+            const results = [];
+            const constructions = countConstructions(() => {
+                for (let call = 0; call < 50; call++) {
+                    results.push(formatCurrencyTotal({ amount: 1234567n + BigInt(call * 100), currency: USD, locale }));
+                }
+            });
+            assert.equal(constructions, 1);
+            // Same key, so same layout: the digits change with the amount, the format does not.
+            assert.ok(results.every((text) => text.includes('$')));
+            assert.equal(results[0], formatCurrencyTotal({ amount: 1234567n, currency: USD, locale }));
+        });
+        it('keeps compact, standard, sub-unit and other-currency formatters apart', () => {
+            const locale = 'es-MX';
+            const constructions = countConstructions(() => {
+                for (let call = 0; call < 3; call++) {
+                    formatCurrencyTotal({ amount: 1234567n, currency: USD, locale }); // standard, 0 digits
+                    formatCurrencyTotal({ amount: 300000000n, currency: USD, locale }); // compact
+                    formatCurrencyTotal({ amount: 40n, currency: USD, locale }); // sub-unit, 2 digits
+                    formatCurrencyTotal({ amount: 28400000n, currency: KRW, locale }); // another currency, compact
+                }
+            });
+            assert.equal(constructions, 4);
+            assert.equal(formatCurrencyTotal({ amount: 40n, currency: USD, locale: 'en-US' }), '$0.40');
+            assert.equal(formatCurrencyTotal({ amount: 300000000n, currency: USD, locale: 'en-US' }), '$3M');
+        });
+        it('caches the symbol fallback for a ticker Intl rejects, so repeat calls construct nothing', () => {
+            const unknownTicker = { ...USD, ticker: 'NOT-A-CODE' };
+            const locale = 'en-GB';
+            let first = '';
+            const firstConstructions = countConstructions(() => {
+                first = formatCurrencyTotal({ amount: 1234567n, currency: unknownTicker, locale });
+            });
+            assert.equal(first, '$12,345');
+            assert.ok(firstConstructions <= 2);
+            const repeatConstructions = countConstructions(() => {
+                assert.equal(formatCurrencyTotal({ amount: 7654321n, currency: unknownTicker, locale }), '$76,543');
+            });
+            assert.equal(repeatConstructions, 0);
+        });
+    });
 });

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from './sort.js';
 export * from './time.js';
 export * from './tokens.js';
 export * from './stats.js';
+export * from './selfTrade.js';
 export * from './stateKey.js';
 export * from './deposit.js';
 export * from './depositKeys.js';

package/dist/index.js

@@ -35,6 +35,7 @@ export * from './sort.js';
 export * from './time.js';
 export * from './tokens.js';
 export * from './stats.js';
+export * from './selfTrade.js';
 export * from './stateKey.js';
 export * from './deposit.js';
 export * from './depositKeys.js';

package/dist/peer-types.test.d.ts

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

package/dist/peer-types.test.js

@@ -0,0 +1,178 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { decodeAbiParameters, encodeAbiParameters, keccak256, parseAbiParameters } from 'viem';
+import { encodeV3PaymentProof, extractNullifier, extractReclaimAttestorAddress, } from './peer-types.js';
+/**
+ * Where the expected values come from, so these tests can fail:
+ * - REAL_ATTESTATION is a live Chase/Zelle response captured from the zkp2p
+ *   attestation service (same capture as packages/ui/tests/unit/nullifier-check.test.ts
+ *   and packages/gate/test/build-attestation.parity.test.ts).
+ * - GOLDEN_PAYMENT_PROOF was produced by Foundry, not by this repository:
+ *   cast abi-encode "f(((bytes32,uint256,bytes32),bytes[],bytes,bytes,address[]))" ...
+ * - GOLDEN_NULLIFIER was produced by `cast keccak <paymentMethod><paymentId>`.
+ * The struct shape is the one UnifiedPaymentVerifier decodes from
+ * VerifyPaymentData.paymentProof: an outer tuple holding the PaymentAttestation
+ * tuple, signatures, encodedPaymentDetails, metadata and attestorAddresses.
+ */
+const REAL_ENCODED_PAYMENT_DETAILS = '0x6aa1d1401e79ad0549dced8b1b96fb72c41cd02b32a7d9ea1fed54ba9e17152ea12c51a3a379c061570fadc1f978de44ff552f57114ce261c4da11f6b335fc950000000000000000000000000000000000000000000000000000000000000068c4ae21aac0c6549d71dd96035b7e0bdb6c79ebdba8891b666115bc976d16a29e0000000000000000000000000000000000000000000000000000019be3003018b41e43e69d7b4063442552ee0e7cd9cc702b7c05fb80553cfc54a59e0803b2db1897217eb5e39abdb0e1e2f07523f20d84e0c57d6f28b6f3e7623932e90fa00600000000000000000000000000000000000000000000000000000000000f42406aa1d1401e79ad0549dced8b1b96fb72c41cd02b32a7d9ea1fed54ba9e17152ec4ae21aac0c6549d71dd96035b7e0bdb6c79ebdba8891b666115bc976d16a29ea12c51a3a379c061570fadc1f978de44ff552f57114ce261c4da11f6b335fc950000000000000000000000000000000000000000000000000e6ed27d66680000000000000000000000000000000000000000000000000000000000006970152b0000000000000000000000000000000000000000000000000000000000000003';
+const REAL_ATTESTATION = {
+    signature: '0x5ba11f82b78ad3964f6b91b63bb99056ee8674c1988f6fed0971e9a449f809b51cd51a2ec748c36cb4694b4877e8a6dfddc45aea1f947b1b779b6da9e8f3c1761b',
+    signer: '0x5106a86819ed6bb82c77ccbfc151250e1d369dba',
+    domainSeparator: '0xb1833b9f638dab05c557a6f834d3c67891b9a14ed769ae7d604277aa6e22ed30',
+    typeHash: '0x3fbf9df18b1c2ca7c48d809a8d8c6bbf8d7ac33f3741ab78dac072aba0f77103',
+    typedDataSpec: {
+        primaryType: 'PaymentAttestation',
+        types: {
+            PaymentAttestation: [
+                { name: 'intentHash', type: 'bytes32' },
+                { name: 'releaseAmount', type: 'uint256' },
+                { name: 'dataHash', type: 'bytes32' },
+            ],
+        },
+    },
+    typedDataValue: {
+        intentHash: '0x1897217eb5e39abdb0e1e2f07523f20d84e0c57d6f28b6f3e7623932e90fa006',
+        releaseAmount: '1000000',
+        dataHash: '0xf92e1669366c9e55f073eb170eed40ae2601684b091105f22b692d766b6418b0',
+    },
+    encodedPaymentDetails: REAL_ENCODED_PAYMENT_DETAILS,
+    metadata: '0x',
+    // The live proofInput is a multi-kilobyte Reclaim proof. Only the attestor
+    // address matters to the extractor, and it is copied from the live value.
+    proofInput: JSON.stringify({
+        proofType: 'reclaim',
+        proof: JSON.stringify([{ signatures: { attestorAddress: '0x0636c417755e3ae25c6c166d181c0607f4c572a3' } }]),
+    }),
+    platform: 'chase',
+    actionType: 'transfer_zelle',
+};
+const GOLDEN_PAYMENT_PROOF = '0x00000000000000000000000000000000000000000000000000000000000000201897217eb5e39abdb0e1e2f07523f20d84e0c57d6f28b6f3e7623932e90fa00600000000000000000000000000000000000000000000000000000000000f4240f92e1669366c9e55f073eb170eed40ae2601684b091105f22b692d766b6418b000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000003a00000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000415ba11f82b78ad3964f6b91b63bb99056ee8674c1988f6fed0971e9a449f809b51cd51a2ec748c36cb4694b4877e8a6dfddc45aea1f947b1b779b6da9e8f3c1761b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001c06aa1d1401e79ad0549dced8b1b96fb72c41cd02b32a7d9ea1fed54ba9e17152ea12c51a3a379c061570fadc1f978de44ff552f57114ce261c4da11f6b335fc950000000000000000000000000000000000000000000000000000000000000068c4ae21aac0c6549d71dd96035b7e0bdb6c79ebdba8891b666115bc976d16a29e0000000000000000000000000000000000000000000000000000019be3003018b41e43e69d7b4063442552ee0e7cd9cc702b7c05fb80553cfc54a59e0803b2db1897217eb5e39abdb0e1e2f07523f20d84e0c57d6f28b6f3e7623932e90fa00600000000000000000000000000000000000000000000000000000000000f42406aa1d1401e79ad0549dced8b1b96fb72c41cd02b32a7d9ea1fed54ba9e17152ec4ae21aac0c6549d71dd96035b7e0bdb6c79ebdba8891b666115bc976d16a29ea12c51a3a379c061570fadc1f978de44ff552f57114ce261c4da11f6b335fc950000000000000000000000000000000000000000000000000e6ed27d66680000000000000000000000000000000000000000000000000000000000006970152b0000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000005106a86819ed6bb82c77ccbfc151250e1d369dba';
+/** keccak256(paymentMethod ++ paymentId) for the live payment, from `cast keccak`. */
+const GOLDEN_NULLIFIER = '0xe2795a9349479ff11623b1a7080d2db11ed0d3d9e7cbfacb9cb03d40d724468f';
+const PROOF_PARAMETERS = parseAbiParameters('((bytes32 intentHash, uint256 releaseAmount, bytes32 dataHash) attestation, bytes[] signatures, bytes encodedPaymentDetails, bytes metadata, address[] attestorAddresses) proof');
+const word = (hex, index) => '0x' + hex.slice(2 + index * 64, 2 + (index + 1) * 64);
+describe('encodeV3PaymentProof', () => {
+    it('reproduces the Foundry-encoded bytes for the live attestation', () => {
+        assert.equal(encodeV3PaymentProof(REAL_ATTESTATION), GOLDEN_PAYMENT_PROOF);
+    });
+    it('matches a hand-built encoding from the contract struct types', () => {
+        const expected = encodeAbiParameters(PROOF_PARAMETERS, [
+            {
+                attestation: {
+                    intentHash: '0x1897217eb5e39abdb0e1e2f07523f20d84e0c57d6f28b6f3e7623932e90fa006',
+                    releaseAmount: 1000000n,
+                    dataHash: '0xf92e1669366c9e55f073eb170eed40ae2601684b091105f22b692d766b6418b0',
+                },
+                signatures: [REAL_ATTESTATION.signature],
+                encodedPaymentDetails: REAL_ENCODED_PAYMENT_DETAILS,
+                metadata: '0x',
+                attestorAddresses: ['0x5106a86819ed6bb82c77ccbfc151250e1d369dba'],
+            },
+        ]);
+        assert.equal(encodeV3PaymentProof(REAL_ATTESTATION), expected);
+    });
+    it('wraps the struct in an outer tuple: first word is the 0x20 offset, then the attestation words', () => {
+        const proof = encodeV3PaymentProof(REAL_ATTESTATION);
+        assert.equal(word(proof, 0), '0x' + '0'.repeat(62) + '20');
+        assert.equal(word(proof, 1), REAL_ATTESTATION.typedDataValue.intentHash);
+        assert.equal(word(proof, 2), '0x' + (1_000_000).toString(16).padStart(64, '0'));
+        assert.equal(word(proof, 3), REAL_ATTESTATION.typedDataValue.dataHash);
+    });
+    it('decodes back to every field it was given', () => {
+        const attestation = {
+            ...REAL_ATTESTATION,
+            signature: ('0x' + 'ab'.repeat(65)),
+            signer: '0x00000000000000000000000000000000000000a1',
+            typedDataValue: {
+                intentHash: ('0x' + '11'.repeat(32)),
+                releaseAmount: (2n ** 128n + 7n).toString(),
+                dataHash: ('0x' + '22'.repeat(32)),
+            },
+            encodedPaymentDetails: '0xdeadbeef',
+            metadata: '0xcafe',
+        };
+        const [decoded] = decodeAbiParameters(PROOF_PARAMETERS, encodeV3PaymentProof(attestation));
+        assert.equal(decoded.attestation.intentHash, '0x' + '11'.repeat(32));
+        assert.equal(decoded.attestation.releaseAmount, 2n ** 128n + 7n);
+        assert.equal(decoded.attestation.dataHash, '0x' + '22'.repeat(32));
+        assert.deepEqual(decoded.signatures, ['0x' + 'ab'.repeat(65)]);
+        assert.equal(decoded.encodedPaymentDetails, '0xdeadbeef');
+        assert.equal(decoded.metadata, '0xcafe');
+        assert.deepEqual(decoded.attestorAddresses.map((address) => address.toLowerCase()), ['0x00000000000000000000000000000000000000a1']);
+    });
+    it('keeps the largest uint256 release amount intact', () => {
+        const max = 2n ** 256n - 1n;
+        const proof = encodeV3PaymentProof({
+            ...REAL_ATTESTATION,
+            typedDataValue: { ...REAL_ATTESTATION.typedDataValue, releaseAmount: max.toString() },
+        });
+        const [decoded] = decodeAbiParameters(PROOF_PARAMETERS, proof);
+        assert.equal(decoded.attestation.releaseAmount, max);
+    });
+    it('rejects a release amount that is not an integer', () => {
+        assert.throws(() => encodeV3PaymentProof({
+            ...REAL_ATTESTATION,
+            typedDataValue: { ...REAL_ATTESTATION.typedDataValue, releaseAmount: '1.5' },
+        }));
+    });
+});
+describe('extractNullifier', () => {
+    it('derives the known nullifier for the live payment', () => {
+        assert.equal(extractNullifier(REAL_ATTESTATION), GOLDEN_NULLIFIER);
+    });
+    it('is keccak256 of paymentMethod then paymentId, in that order', () => {
+        const paymentMethod = '0x6aa1d1401e79ad0549dced8b1b96fb72c41cd02b32a7d9ea1fed54ba9e17152e';
+        const paymentId = '0xb41e43e69d7b4063442552ee0e7cd9cc702b7c05fb80553cfc54a59e0803b2db';
+        assert.equal(keccak256(`${paymentMethod}${paymentId.slice(2)}`), GOLDEN_NULLIFIER);
+        assert.notEqual(keccak256(`${paymentId}${paymentMethod.slice(2)}`), GOLDEN_NULLIFIER);
+    });
+    it('changes when only the payment identifier changes', () => {
+        const changed = REAL_ENCODED_PAYMENT_DETAILS.replace('b41e43e69d7b4063442552ee0e7cd9cc702b7c05fb80553cfc54a59e0803b2db', 'b41e43e69d7b4063442552ee0e7cd9cc702b7c05fb80553cfc54a59e0803b2dc');
+        assert.notEqual(extractNullifier({ ...REAL_ATTESTATION, encodedPaymentDetails: changed }), GOLDEN_NULLIFIER);
+    });
+    it('does not depend on the amount or timestamp fields', () => {
+        const bytes32 = (digit) => ('0x' + digit.repeat(64));
+        const encode = (amount, timestamp) => encodeAbiParameters(parseAbiParameters('(bytes32 paymentMethod, bytes32 payeeId, uint256 amount, bytes32 currency, uint256 timestamp, bytes32 paymentId) details, (bytes32 intentHash, uint256 amount, bytes32 paymentMethod, bytes32 currency, bytes32 payeeId, uint256 conversionRate, uint256 timestamp, uint256 timestampBuffer) snapshot'), [
+            { paymentMethod: bytes32('1'), payeeId: bytes32('2'), amount, currency: bytes32('3'), timestamp, paymentId: bytes32('4') },
+            { intentHash: bytes32('5'), amount: 1n, paymentMethod: bytes32('1'), currency: bytes32('3'), payeeId: bytes32('2'), conversionRate: 1n, timestamp: 1n, timestampBuffer: 3n },
+        ]);
+        const first = extractNullifier({ ...REAL_ATTESTATION, encodedPaymentDetails: encode(100n, 5n) });
+        const second = extractNullifier({ ...REAL_ATTESTATION, encodedPaymentDetails: encode(999n, 77n) });
+        assert.equal(first, keccak256(('0x' + '1'.repeat(64) + '4'.repeat(64))));
+        assert.equal(first, second);
+    });
+    it('returns null for bytes that are not an encoded payment details tuple', () => {
+        assert.equal(extractNullifier({ ...REAL_ATTESTATION, encodedPaymentDetails: '0x1234' }), null);
+        assert.equal(extractNullifier({ ...REAL_ATTESTATION, encodedPaymentDetails: '0x' }), null);
+    });
+});
+describe('extractReclaimAttestorAddress', () => {
+    const withProofs = (proofs) => ({
+        ...REAL_ATTESTATION,
+        proofInput: JSON.stringify({ proofType: 'reclaim', proof: JSON.stringify(proofs) }),
+    });
+    it('reads the attestor address of the live proof', () => {
+        assert.equal(extractReclaimAttestorAddress(REAL_ATTESTATION), '0x0636c417755e3ae25c6c166d181c0607f4c572a3');
+    });
+    it('reads the first proof only', () => {
+        const attestation = withProofs([
+            { signatures: { attestorAddress: '0x00000000000000000000000000000000000000f1' } },
+            { signatures: { attestorAddress: '0x00000000000000000000000000000000000000f2' } },
+        ]);
+        assert.equal(extractReclaimAttestorAddress(attestation), '0x00000000000000000000000000000000000000f1');
+    });
+    it('returns null when there are no proofs', () => {
+        assert.equal(extractReclaimAttestorAddress(withProofs([])), null);
+        assert.equal(extractReclaimAttestorAddress(withProofs({ not: 'an array' })), null);
+    });
+    it('returns null when the signatures or the address are missing or not a string', () => {
+        assert.equal(extractReclaimAttestorAddress(withProofs([{}])), null);
+        assert.equal(extractReclaimAttestorAddress(withProofs([{ signatures: {} }])), null);
+        assert.equal(extractReclaimAttestorAddress(withProofs([{ signatures: { attestorAddress: 5 } }])), null);
+        assert.equal(extractReclaimAttestorAddress(withProofs([{ signatures: { attestorAddress: '' } }])), null);
+    });
+    it('returns null for malformed JSON at either level', () => {
+        assert.equal(extractReclaimAttestorAddress({ ...REAL_ATTESTATION, proofInput: 'not json' }), null);
+        assert.equal(extractReclaimAttestorAddress({ ...REAL_ATTESTATION, proofInput: JSON.stringify({ proof: 'not json' }) }), null);
+    });
+});

package/dist/reputation.test.js

@@ -241,3 +241,51 @@ describe('isOverOrderCap', () => {
         assert.equal(isOverOrderCap({ orderTokenAmount: null, cap: usdc(100n) }), false);
     });
 });
+describe('getTierFromVolume: one base unit either side of every threshold', () => {
+    // The tier ladder is volume-driven. The cap and cooldown a taker gets depend
+    // on landing in the right step, so a one-base-unit slip at a boundary is a
+    // real money limit applied to the wrong person. Boundaries are written as
+    // literal USDC base units (not read from TAKER_TIERS) so a changed threshold fails.
+    const steps = [
+        { threshold: 500000000n, below: 'peasant', at: 'neutral' },
+        { threshold: 2000000000n, below: 'neutral', at: 'plus' },
+        { threshold: 10000000000n, below: 'plus', at: 'pro' },
+        { threshold: 25000000000n, below: 'pro', at: 'platinum' },
+    ];
+    for (const { threshold, below, at } of steps) {
+        it(`${threshold} base units: n-1 is ${below}, n is ${at}, n+1 is ${at}`, () => {
+            assert.equal(getTierFromVolume(threshold - 1n), below);
+            assert.equal(getTierFromVolume(threshold), at);
+            assert.equal(getTierFromVolume(threshold + 1n), at);
+        });
+    }
+    it('0 base units is the entry tier and 1 base unit stays there', () => {
+        assert.equal(getTierFromVolume(0n), 'peasant');
+        assert.equal(getTierFromVolume(1n), 'peasant');
+    });
+});
+describe('isOverOrderCap: base unit boundaries', () => {
+    const cap = 100000000n; // 100 USDC
+    it('is not over one base unit below the cap or at the cap, but over one base unit above', () => {
+        assert.equal(isOverOrderCap({ orderTokenAmount: cap - 1n, cap }), false);
+        assert.equal(isOverOrderCap({ orderTokenAmount: cap, cap }), false);
+        assert.equal(isOverOrderCap({ orderTokenAmount: cap + 1n, cap }), true);
+    });
+    it('treats a null cap as no limit even for an enormous order', () => {
+        assert.equal(isOverOrderCap({ orderTokenAmount: UNLIMITED_CAP_BASE_UNITS, cap: null }), false);
+    });
+    it('a zero cap is not "no limit": any positive order is over it', () => {
+        assert.equal(isOverOrderCap({ orderTokenAmount: 0n, cap: 0n }), false);
+        assert.equal(isOverOrderCap({ orderTokenAmount: 1n, cap: 0n }), true);
+    });
+    it('agrees with the real entry-tier cap at its exact edge', () => {
+        const entryCap = getEffectiveCap({ tier: 'peasant', providerKey: 'revolut', decimals: USDC });
+        assert.notEqual(entryCap, null);
+        assert.equal(isOverOrderCap({ orderTokenAmount: entryCap, cap: entryCap }), false);
+        assert.equal(isOverOrderCap({ orderTokenAmount: entryCap + 1n, cap: entryCap }), true);
+    });
+    it('compares against the unlimited sentinel as an ordinary bigint', () => {
+        assert.equal(isOverOrderCap({ orderTokenAmount: UNLIMITED_CAP_BASE_UNITS, cap: UNLIMITED_CAP_BASE_UNITS }), false);
+        assert.equal(isOverOrderCap({ orderTokenAmount: UNLIMITED_CAP_BASE_UNITS + 1n, cap: UNLIMITED_CAP_BASE_UNITS }), true);
+    });
+});

package/dist/selfTrade.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Self-trade detection.
+ *
+ * A self-trade is an intent in which the deposit's own seller (or the seller's
+ * delegate) is also the buyer or the recipient of the funds. Such a trade moves
+ * no value between two parties, so it must count for nothing: no volume
+ * statistics and no reputation, on the taker side or the maker side.
+ *
+ * The check lives in this one function. The indexer calls it once, when the
+ * intent is signaled, and stores the answer in the `isSelfTrade` column. Every
+ * later aggregate reads that column, so the flag and the aggregates cannot
+ * disagree.
+ */
+/** The addresses that identify who sits on each side of one intent. */
+export type SelfTradeParties = {
+    /** The intent owner (the buyer): `intentSignaled.ownerAddress`. */
+    ownerAddress: string;
+    /** The intent recipient: `intentSignaled.toAddress`. Omit when unknown. */
+    toAddress?: string | null;
+    /** The deposit's seller: `deposit.participantAddress`. */
+    depositorAddress: string;
+    /** The deposit's delegate: `deposit.delegate`. The zero address means none. */
+    delegateAddress?: string | null;
+};
+/**
+ * Returns true when the buyer or the recipient is the deposit's own seller or
+ * delegate. Comparison ignores letter case. A zero delegate is not a party, so
+ * it never matches a zero-address owner or recipient by accident.
+ *
+ * @param parties - The addresses on each side of the intent.
+ * @returns Whether the intent is a self-trade.
+ */
+export declare function isSelfTrade(parties: SelfTradeParties): boolean;

package/dist/selfTrade.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Self-trade detection.
+ *
+ * A self-trade is an intent in which the deposit's own seller (or the seller's
+ * delegate) is also the buyer or the recipient of the funds. Such a trade moves
+ * no value between two parties, so it must count for nothing: no volume
+ * statistics and no reputation, on the taker side or the maker side.
+ *
+ * The check lives in this one function. The indexer calls it once, when the
+ * intent is signaled, and stores the answer in the `isSelfTrade` column. Every
+ * later aggregate reads that column, so the flag and the aggregates cannot
+ * disagree.
+ */
+import { zeroAddress } from 'viem';
+/**
+ * Returns true when the buyer or the recipient is the deposit's own seller or
+ * delegate. Comparison ignores letter case. A zero delegate is not a party, so
+ * it never matches a zero-address owner or recipient by accident.
+ *
+ * @param parties - The addresses on each side of the intent.
+ * @returns Whether the intent is a self-trade.
+ */
+export function isSelfTrade(parties) {
+    const sellerSide = new Set([parties.depositorAddress.toLowerCase()]);
+    const delegate = parties.delegateAddress?.toLowerCase();
+    if (delegate && delegate !== zeroAddress)
+        sellerSide.add(delegate);
+    const buyerSide = [parties.ownerAddress, parties.toAddress];
+    return buyerSide.some((address) => !!address && sellerSide.has(address.toLowerCase()));
+}

package/dist/selfTrade.test.d.ts

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

package/dist/selfTrade.test.js

@@ -0,0 +1,39 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isSelfTrade } from './selfTrade.js';
+const seller = '0xAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+const buyer = '0xBbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';
+const stranger = '0xcccccccccccccccccccccccccccccccccccccccc';
+const zero = '0x0000000000000000000000000000000000000000';
+describe('isSelfTrade', () => {
+    it('is false for a normal trade between two different parties', () => {
+        assert.equal(isSelfTrade({ ownerAddress: buyer, toAddress: stranger, depositorAddress: seller, delegateAddress: zero }), false);
+    });
+    it('is true when the buyer is the seller', () => {
+        assert.equal(isSelfTrade({ ownerAddress: seller, toAddress: buyer, depositorAddress: seller }), true);
+    });
+    it('is true when only the recipient is the seller', () => {
+        assert.equal(isSelfTrade({ ownerAddress: buyer, toAddress: seller, depositorAddress: seller }), true);
+    });
+    it('is true when the buyer is the deposit delegate', () => {
+        assert.equal(isSelfTrade({ ownerAddress: stranger, toAddress: buyer, depositorAddress: seller, delegateAddress: stranger }), true);
+    });
+    it('is true when the recipient is the deposit delegate', () => {
+        assert.equal(isSelfTrade({ ownerAddress: buyer, toAddress: stranger, depositorAddress: seller, delegateAddress: stranger }), true);
+    });
+    it('ignores letter case on every side', () => {
+        assert.equal(isSelfTrade({ ownerAddress: seller.toLowerCase(), depositorAddress: seller.toUpperCase().replace('0X', '0x') }), true);
+        assert.equal(isSelfTrade({
+            ownerAddress: buyer,
+            toAddress: stranger.toUpperCase().replace('0X', '0x'),
+            depositorAddress: seller,
+            delegateAddress: stranger.toLowerCase(),
+        }), true);
+    });
+    it('does not treat a zero delegate as a party', () => {
+        assert.equal(isSelfTrade({ ownerAddress: zero, toAddress: zero, depositorAddress: seller, delegateAddress: zero }), false);
+    });
+    it('treats a missing recipient and a missing delegate as no match', () => {
+        assert.equal(isSelfTrade({ ownerAddress: buyer, toAddress: null, depositorAddress: seller, delegateAddress: null }), false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.10.0",
+  "version": "1.11.0-rc.20261018212258.bdc024c",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",