@provex/utils 1.0.16 → 1.2.4

package/dist/events.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Event type definitions for the Provex indexer.
+ *
+ * This module defines all blockchain event types in their display order.
+ * The order determines how events are sorted in the UI when viewing
+ * deposit history - deposit creation events come first, followed by
+ * intent events, then close/withdrawal events.
+ *
+ * @remarks
+ * The eventOrderId map assigns each event a numeric ID used in orderId
+ * serialization for consistent cross-chain ordering.
+ *
+ * @see {@link ids} for orderId serialization
+ * @see {@link indexer} for event handlers
+ */
+/**
+ * Ordered list of all event types supported by the indexer.
+ * The order determines the display sort priority in the UI.
+ *
+ * Event categories:
+ * 1. Deposit open events (creation, configuration)
+ * 2. Intent lifecycle events (signal, lock, verify, fulfill)
+ * 3. Deposit close events (withdrawal, close)
+ * 4. Protocol configuration events (dust, fees, registries)
+ */
+export const eventOrder = [
+    // deposit open events
+    'deposit_received',
+    'deposit_payment_method_added',
+    'deposit_payment_method_active_updated',
+    'deposit_currency_added',
+    'deposit_delegate_set',
+    'deposit_delegate_removed',
+    // configuration events (these happen before funds_added in deposit creation)
+    'deposit_conversion_rate_updated',
+    'deposit_accepting_intents_updated',
+    'deposit_intent_amount_range_updated',
+    // funds added comes after configuration so it appears first in UI (newest-first)
+    'deposit_funds_added',
+    // intent events
+    'intent_signaled',
+    'funds_locked',
+    'payment_verified',
+    'funds_unlocked_and_transferred',
+    'intent_fulfilled',
+    'intent_pruned',
+    'funds_unlocked',
+    'intent_expiry_extended',
+    // deposit close events
+    'funds_removed', // synthetic UI event for partial withdrawal (remaining > 0)
+    'deposit_withdrawn', // full withdrawal that closes the deposit (remaining = 0)
+    'deposit_closed',
+    // dust events
+    'dust_collected',
+    'dust_recipient_updated',
+    'dust_threshold_updated',
+    // deposit config events
+    'deposit_retain_on_empty_updated',
+    'payment_method_currency_added',
+    'payment_method_currency_removed',
+    // registry events
+    'payment_method_added',
+    'payment_method_removed',
+    'allow_multiple_intents_updated',
+    'escrow_registry_updated',
+    'post_intent_hook_registry_updated',
+    'protocol_fee_recipient_updated',
+    'protocol_fee_updated',
+    'relayer_registry_updated',
+    'unpaused',
+    'paused',
+    // V3 global config events
+    'intent_expiration_period_updated',
+    'max_intents_per_deposit_updated',
+    'min_deposit_amount_set',
+    'orchestrator_updated',
+    'ownership_transferred',
+    'payment_verifier_registry_updated',
+    // V2 verifier events
+    'provider_hash_added',
+    'provider_hash_removed',
+];
+/**
+ * Map from event type name to its numeric order ID.
+ * Used in orderId serialization to maintain consistent ordering.
+ *
+ * @example
+ * ```ts
+ * const id = eventOrderId.get('intent_signaled') // 9
+ * ```
+ */
+export const eventOrderId = new Map(eventOrder.map((event, index) => [event, index]));

package/dist/events.test.d.ts

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

package/dist/events.test.js

@@ -0,0 +1,111 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { eventOrder, eventOrderId } from './events.js';
+describe('events', () => {
+    describe('eventOrder', () => {
+        it('is a non-empty array', () => {
+            assert.ok(Array.isArray(eventOrder));
+            assert.ok(eventOrder.length > 0);
+        });
+        it('contains deposit lifecycle events', () => {
+            assert.ok(eventOrder.includes('deposit_received'));
+            assert.ok(eventOrder.includes('deposit_withdrawn'));
+            assert.ok(eventOrder.includes('deposit_closed'));
+        });
+        it('contains intent lifecycle events', () => {
+            assert.ok(eventOrder.includes('intent_signaled'));
+            assert.ok(eventOrder.includes('intent_fulfilled'));
+            assert.ok(eventOrder.includes('intent_pruned'));
+        });
+        it('contains V3-specific events', () => {
+            assert.ok(eventOrder.includes('funds_locked'));
+            assert.ok(eventOrder.includes('funds_unlocked'));
+            assert.ok(eventOrder.includes('funds_unlocked_and_transferred'));
+            assert.ok(eventOrder.includes('payment_verified'));
+            assert.ok(eventOrder.includes('intent_expiry_extended'));
+            assert.ok(eventOrder.includes('deposit_payment_method_active_updated'));
+        });
+        it('contains V3 global config events', () => {
+            assert.ok(eventOrder.includes('intent_expiration_period_updated'));
+            assert.ok(eventOrder.includes('max_intents_per_deposit_updated'));
+            assert.ok(eventOrder.includes('min_deposit_amount_set'));
+            assert.ok(eventOrder.includes('orchestrator_updated'));
+            assert.ok(eventOrder.includes('payment_verifier_registry_updated'));
+        });
+        it('has no duplicate events', () => {
+            const uniqueEvents = new Set(eventOrder);
+            assert.strictEqual(uniqueEvents.size, eventOrder.length);
+        });
+        it('orders deposit events before intent events', () => {
+            const depositReceivedIdx = eventOrder.indexOf('deposit_received');
+            const intentSignaledIdx = eventOrder.indexOf('intent_signaled');
+            assert.ok(depositReceivedIdx < intentSignaledIdx);
+        });
+        it('orders intent_signaled before intent_fulfilled', () => {
+            const signaledIdx = eventOrder.indexOf('intent_signaled');
+            const fulfilledIdx = eventOrder.indexOf('intent_fulfilled');
+            assert.ok(signaledIdx < fulfilledIdx);
+        });
+        it('orders funds_locked before funds_unlocked', () => {
+            const lockedIdx = eventOrder.indexOf('funds_locked');
+            const unlockedIdx = eventOrder.indexOf('funds_unlocked');
+            assert.ok(lockedIdx < unlockedIdx);
+        });
+    });
+    describe('eventOrderId', () => {
+        it('is a Map', () => {
+            assert.ok(eventOrderId instanceof Map);
+        });
+        it('has same size as eventOrder', () => {
+            assert.strictEqual(eventOrderId.size, eventOrder.length);
+        });
+        it('maps each event to its index', () => {
+            for (let i = 0; i < eventOrder.length; i++) {
+                const event = eventOrder[i];
+                assert.strictEqual(eventOrderId.get(event), i);
+            }
+        });
+        it('returns correct index for deposit_received', () => {
+            const idx = eventOrderId.get('deposit_received');
+            assert.strictEqual(idx, 0);
+        });
+        it('returns correct index for intent_signaled', () => {
+            const idx = eventOrderId.get('intent_signaled');
+            assert.strictEqual(idx, eventOrder.indexOf('intent_signaled'));
+        });
+        it('returns undefined for invalid event', () => {
+            // @ts-expect-error - Testing runtime behavior with invalid event
+            const idx = eventOrderId.get('invalid_event');
+            assert.strictEqual(idx, undefined);
+        });
+    });
+    describe('EventType', () => {
+        it('type-checks valid events', () => {
+            // These should compile without error
+            const event1 = 'deposit_received';
+            const event2 = 'intent_signaled';
+            const event3 = 'funds_locked';
+            assert.ok(event1);
+            assert.ok(event2);
+            assert.ok(event3);
+        });
+    });
+    describe('event ordering consistency', () => {
+        it('maintains consistent ordering for UI display', () => {
+            // Events in same transaction should sort consistently
+            // Lower index = appears first in time-ordered list (oldest first)
+            // Higher index = appears later
+            // Deposit setup should come before funds added
+            const depositReceivedIdx = eventOrderId.get('deposit_received');
+            const fundsAddedIdx = eventOrderId.get('deposit_funds_added');
+            assert.ok(depositReceivedIdx < fundsAddedIdx);
+            // Intent signaled should come before payment verified
+            const intentSignaledIdx = eventOrderId.get('intent_signaled');
+            const paymentVerifiedIdx = eventOrderId.get('payment_verified');
+            assert.ok(intentSignaledIdx < paymentVerifiedIdx);
+            // Payment verified should come before intent fulfilled
+            const intentFulfilledIdx = eventOrderId.get('intent_fulfilled');
+            assert.ok(paymentVerifiedIdx < intentFulfilledIdx);
+        });
+    });
+});

package/dist/fees.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Fee calculation utilities for Provex protocol.
+ *
+ * Fee Precision Formats:
+ * - Basis points (bps): 10000 = 100%, 100 = 1%, 1 = 0.01%
+ * - 18 decimals: 1e18 = 100% (like Solidity's ether units)
+ *
+ * The protocol uses basis points for most fee calculations.
+ * Some contracts (Pulsechain V3) use 18-decimal precision which must
+ * be normalized to basis points before use.
+ *
+ * @example
+ * // Calculate 2% fee on 100 USDC
+ * const fee = calculateFeeAmount({ amount: 100_000000n, feeBps: 200n })
+ * // fee = 2_000000n (2 USDC)
+ */
+/**
+ * Maximum basis points value representing 100%.
+ * Used as the denominator in fee calculations.
+ */
+export declare const BPS_DENOMINATOR = 10000n;
+/**
+ * 18-decimal representation of 100%.
+ * Used to detect and normalize 18-decimal fee values.
+ */
+export declare const EIGHTEEN_DECIMAL_100_PERCENT: bigint;
+/**
+ * Precision format for fee values.
+ * - 'bps': Basis points (10000 = 100%)
+ * - '18decimals': 18-decimal precision (1e18 = 100%)
+ */
+export type FeePrecision = 'bps' | '18decimals';
+/**
+ * Result of fee precision detection.
+ */
+export interface FeeInfo {
+    /** Human-readable percentage string (e.g., "2%", "0.50%") */
+    percentage: string;
+    /** Detected precision format */
+    precision: FeePrecision;
+    /** Fee value normalized to basis points */
+    normalizedBps: bigint;
+}
+/**
+ * Calculate the fee amount for a given transaction.
+ *
+ * @param params.amount - Transaction amount in smallest unit (e.g., 6 decimals for USDC)
+ * @param params.feeBps - Fee in basis points (200 = 2%)
+ * @returns Fee amount in the same units as the input amount
+ *
+ * @example
+ * // 2% fee on 100 USDC (6 decimals)
+ * calculateFeeAmount({ amount: 100_000000n, feeBps: 200n })
+ * // Returns: 2_000000n (2 USDC)
+ *
+ * @example
+ * // 0.5% fee on 1000 USDC
+ * calculateFeeAmount({ amount: 1000_000000n, feeBps: 50n })
+ * // Returns: 5_000000n (5 USDC)
+ */
+export declare function calculateFeeAmount(params: {
+    amount: bigint;
+    feeBps: bigint;
+}): bigint;
+/**
+ * Calculate the net amount after deducting fees.
+ *
+ * @param params.grossAmount - Original amount before fees
+ * @param params.feeBps - Fee in basis points (200 = 2%)
+ * @returns Amount remaining after fee deduction
+ *
+ * @example
+ * // Net amount after 2% fee on 100 USDC
+ * calculateNetAmount({ grossAmount: 100_000000n, feeBps: 200n })
+ * // Returns: 98_000000n (98 USDC)
+ */
+export declare function calculateNetAmount(params: {
+    grossAmount: bigint;
+    feeBps: bigint;
+}): bigint;
+/**
+ * Format a basis points value as a human-readable percentage string.
+ *
+ * @param feeBps - Fee in basis points
+ * @returns Formatted percentage string (e.g., "2%", "0.50%")
+ *
+ * @example
+ * formatFeeBps(200n)   // "2%"
+ * formatFeeBps(50n)    // "0.50%"
+ * formatFeeBps(0n)     // "0%"
+ * formatFeeBps(10000n) // "100%"
+ * formatFeeBps(1n)     // "0.01%"
+ */
+export declare function formatFeeBps(feeBps: bigint): string;
+/**
+ * Detect the precision of a raw fee value and normalize to basis points.
+ *
+ * Contracts may use different precisions:
+ * - Basis points: 10000 = 100% (most common)
+ * - 18 decimals: 1e18 = 100% (like ether, used by some V3 contracts)
+ *
+ * Heuristic: If value > 1,000,000, assume 18-decimal precision.
+ *
+ * @param rawFee - Raw fee value from contract
+ * @returns Normalized fee information with bps value and detected precision
+ *
+ * @example
+ * // Basis points input
+ * normalizeFeePrecision(200n)
+ * // Returns: { percentage: "2%", precision: "bps", normalizedBps: 200n }
+ *
+ * @example
+ * // 18-decimal input (2%)
+ * normalizeFeePrecision(20000000000000000n)
+ * // Returns: { percentage: "2%", precision: "18decimals", normalizedBps: 200n }
+ */
+export declare function normalizeFeePrecision(rawFee: bigint): FeeInfo;
+/**
+ * Calculate total fees from multiple fee sources.
+ *
+ * @param fees - Array of fee amounts (all in same precision)
+ * @returns Total fee amount
+ *
+ * @example
+ * // Protocol fee + referrer fee
+ * calculateTotalFees([2_000000n, 500000n])
+ * // Returns: 2_500000n
+ */
+export declare function calculateTotalFees(fees: bigint[]): bigint;
+/**
+ * Check if a fee value represents a zero/no fee.
+ *
+ * @param feeBps - Fee in basis points
+ * @returns true if fee is zero
+ */
+export declare function isZeroFee(feeBps: bigint): boolean;

package/dist/fees.js

@@ -0,0 +1,178 @@
+/**
+ * Fee calculation utilities for Provex protocol.
+ *
+ * Fee Precision Formats:
+ * - Basis points (bps): 10000 = 100%, 100 = 1%, 1 = 0.01%
+ * - 18 decimals: 1e18 = 100% (like Solidity's ether units)
+ *
+ * The protocol uses basis points for most fee calculations.
+ * Some contracts (Pulsechain V3) use 18-decimal precision which must
+ * be normalized to basis points before use.
+ *
+ * @example
+ * // Calculate 2% fee on 100 USDC
+ * const fee = calculateFeeAmount({ amount: 100_000000n, feeBps: 200n })
+ * // fee = 2_000000n (2 USDC)
+ */
+/**
+ * Maximum basis points value representing 100%.
+ * Used as the denominator in fee calculations.
+ */
+export const BPS_DENOMINATOR = 10000n;
+/**
+ * 18-decimal representation of 100%.
+ * Used to detect and normalize 18-decimal fee values.
+ */
+export const EIGHTEEN_DECIMAL_100_PERCENT = 10n ** 18n;
+/**
+ * Threshold to distinguish basis points from 18-decimal values.
+ * If a raw fee value exceeds this, it's likely using 18-decimal precision.
+ */
+const PRECISION_DETECTION_THRESHOLD = 1000000n;
+/**
+ * Calculate the fee amount for a given transaction.
+ *
+ * @param params.amount - Transaction amount in smallest unit (e.g., 6 decimals for USDC)
+ * @param params.feeBps - Fee in basis points (200 = 2%)
+ * @returns Fee amount in the same units as the input amount
+ *
+ * @example
+ * // 2% fee on 100 USDC (6 decimals)
+ * calculateFeeAmount({ amount: 100_000000n, feeBps: 200n })
+ * // Returns: 2_000000n (2 USDC)
+ *
+ * @example
+ * // 0.5% fee on 1000 USDC
+ * calculateFeeAmount({ amount: 1000_000000n, feeBps: 50n })
+ * // Returns: 5_000000n (5 USDC)
+ */
+export function calculateFeeAmount(params) {
+    const { amount, feeBps } = params;
+    return (amount * feeBps) / BPS_DENOMINATOR;
+}
+/**
+ * Calculate the net amount after deducting fees.
+ *
+ * @param params.grossAmount - Original amount before fees
+ * @param params.feeBps - Fee in basis points (200 = 2%)
+ * @returns Amount remaining after fee deduction
+ *
+ * @example
+ * // Net amount after 2% fee on 100 USDC
+ * calculateNetAmount({ grossAmount: 100_000000n, feeBps: 200n })
+ * // Returns: 98_000000n (98 USDC)
+ */
+export function calculateNetAmount(params) {
+    const { grossAmount, feeBps } = params;
+    const feeAmount = calculateFeeAmount({ amount: grossAmount, feeBps });
+    return grossAmount - feeAmount;
+}
+/**
+ * Format a basis points value as a human-readable percentage string.
+ *
+ * @param feeBps - Fee in basis points
+ * @returns Formatted percentage string (e.g., "2%", "0.50%")
+ *
+ * @example
+ * formatFeeBps(200n)   // "2%"
+ * formatFeeBps(50n)    // "0.50%"
+ * formatFeeBps(0n)     // "0%"
+ * formatFeeBps(10000n) // "100%"
+ * formatFeeBps(1n)     // "0.01%"
+ */
+export function formatFeeBps(feeBps) {
+    // Convert bps to percentage: bps / 100
+    // We use number for display since percentages won't exceed Number.MAX_SAFE_INTEGER
+    const percentage = Number(feeBps) / 100;
+    // Format with appropriate decimal places
+    if (percentage === 0) {
+        return '0%';
+    }
+    // If it's a whole number, show without decimals
+    if (Number.isInteger(percentage)) {
+        return `${percentage}%`;
+    }
+    // Otherwise show 2 decimal places, removing trailing zeros
+    const formatted = percentage.toFixed(2).replace(/\.?0+$/, '');
+    return `${formatted}%`;
+}
+/**
+ * Detect the precision of a raw fee value and normalize to basis points.
+ *
+ * Contracts may use different precisions:
+ * - Basis points: 10000 = 100% (most common)
+ * - 18 decimals: 1e18 = 100% (like ether, used by some V3 contracts)
+ *
+ * Heuristic: If value > 1,000,000, assume 18-decimal precision.
+ *
+ * @param rawFee - Raw fee value from contract
+ * @returns Normalized fee information with bps value and detected precision
+ *
+ * @example
+ * // Basis points input
+ * normalizeFeePrecision(200n)
+ * // Returns: { percentage: "2%", precision: "bps", normalizedBps: 200n }
+ *
+ * @example
+ * // 18-decimal input (2%)
+ * normalizeFeePrecision(20000000000000000n)
+ * // Returns: { percentage: "2%", precision: "18decimals", normalizedBps: 200n }
+ */
+export function normalizeFeePrecision(rawFee) {
+    // Detect 18-decimal precision by checking if value is very large
+    if (rawFee > PRECISION_DETECTION_THRESHOLD) {
+        // 18-decimal precision: 1e18 = 100%
+        // Convert to percentage for display
+        const percentage = Number(rawFee) / Number(EIGHTEEN_DECIMAL_100_PERCENT) * 100;
+        // Normalize to basis points: (rawFee * 10000) / 1e18
+        const normalizedBps = (rawFee * BPS_DENOMINATOR) / EIGHTEEN_DECIMAL_100_PERCENT;
+        return {
+            percentage: formatFromNumber(percentage),
+            precision: '18decimals',
+            normalizedBps,
+        };
+    }
+    // Already in basis points
+    return {
+        percentage: formatFeeBps(rawFee),
+        precision: 'bps',
+        normalizedBps: rawFee,
+    };
+}
+/**
+ * Helper to format a number as a percentage string.
+ * @internal
+ */
+function formatFromNumber(percentage) {
+    if (percentage === 0) {
+        return '0%';
+    }
+    if (Number.isInteger(percentage)) {
+        return `${percentage}%`;
+    }
+    const formatted = percentage.toFixed(2).replace(/\.?0+$/, '');
+    return `${formatted}%`;
+}
+/**
+ * Calculate total fees from multiple fee sources.
+ *
+ * @param fees - Array of fee amounts (all in same precision)
+ * @returns Total fee amount
+ *
+ * @example
+ * // Protocol fee + referrer fee
+ * calculateTotalFees([2_000000n, 500000n])
+ * // Returns: 2_500000n
+ */
+export function calculateTotalFees(fees) {
+    return fees.reduce((total, fee) => total + fee, 0n);
+}
+/**
+ * Check if a fee value represents a zero/no fee.
+ *
+ * @param feeBps - Fee in basis points
+ * @returns true if fee is zero
+ */
+export function isZeroFee(feeBps) {
+    return feeBps === 0n;
+}

package/dist/fees.test.d.ts

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

package/dist/fees.test.js

@@ -0,0 +1,165 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { BPS_DENOMINATOR, EIGHTEEN_DECIMAL_100_PERCENT, calculateFeeAmount, calculateNetAmount, formatFeeBps, normalizeFeePrecision, calculateTotalFees, isZeroFee, } from './fees.js';
+describe('BPS_DENOMINATOR', () => {
+    it('should equal 10000', () => {
+        assert.equal(BPS_DENOMINATOR, 10000n);
+    });
+});
+describe('EIGHTEEN_DECIMAL_100_PERCENT', () => {
+    it('should equal 10^18', () => {
+        assert.equal(EIGHTEEN_DECIMAL_100_PERCENT, 10n ** 18n);
+    });
+});
+describe('calculateFeeAmount', () => {
+    it('should calculate 2% fee correctly', () => {
+        // 2% = 200 bps, 100 USDC (6 decimals) = 100_000000
+        const result = calculateFeeAmount({ amount: 100000000n, feeBps: 200n });
+        assert.equal(result, 2000000n); // 2 USDC
+    });
+    it('should calculate 0.5% fee correctly', () => {
+        // 0.5% = 50 bps
+        const result = calculateFeeAmount({ amount: 1000000000n, feeBps: 50n });
+        assert.equal(result, 5000000n); // 5 USDC
+    });
+    it('should return 0 for 0% fee', () => {
+        const result = calculateFeeAmount({ amount: 100000000n, feeBps: 0n });
+        assert.equal(result, 0n);
+    });
+    it('should handle 100% fee', () => {
+        const result = calculateFeeAmount({ amount: 100000000n, feeBps: 10000n });
+        assert.equal(result, 100000000n);
+    });
+    it('should handle 0 amount', () => {
+        const result = calculateFeeAmount({ amount: 0n, feeBps: 200n });
+        assert.equal(result, 0n);
+    });
+    it('should handle small amounts with integer division', () => {
+        // 1 USDC with 2% fee = 0.02 USDC, but integer division truncates
+        const result = calculateFeeAmount({ amount: 1000000n, feeBps: 200n });
+        assert.equal(result, 20000n); // 0.02 USDC
+    });
+    it('should handle very small amounts that round to zero', () => {
+        // 0.0001 USDC with 0.01% fee
+        const result = calculateFeeAmount({ amount: 100n, feeBps: 1n });
+        assert.equal(result, 0n); // Rounds down to 0
+    });
+});
+describe('calculateNetAmount', () => {
+    it('should calculate net amount after 2% fee', () => {
+        const result = calculateNetAmount({ grossAmount: 100000000n, feeBps: 200n });
+        assert.equal(result, 98000000n); // 98 USDC
+    });
+    it('should return full amount for 0% fee', () => {
+        const result = calculateNetAmount({ grossAmount: 100000000n, feeBps: 0n });
+        assert.equal(result, 100000000n);
+    });
+    it('should return 0 for 100% fee', () => {
+        const result = calculateNetAmount({ grossAmount: 100000000n, feeBps: 10000n });
+        assert.equal(result, 0n);
+    });
+    it('should handle 0.5% fee', () => {
+        const result = calculateNetAmount({ grossAmount: 1000000000n, feeBps: 50n });
+        assert.equal(result, 995000000n); // 995 USDC
+    });
+});
+describe('formatFeeBps', () => {
+    it('should format 0% correctly', () => {
+        assert.equal(formatFeeBps(0n), '0%');
+    });
+    it('should format whole percentages without decimals', () => {
+        assert.equal(formatFeeBps(100n), '1%');
+        assert.equal(formatFeeBps(200n), '2%');
+        assert.equal(formatFeeBps(500n), '5%');
+        assert.equal(formatFeeBps(1000n), '10%');
+        assert.equal(formatFeeBps(10000n), '100%');
+    });
+    it('should format fractional percentages with decimals', () => {
+        assert.equal(formatFeeBps(50n), '0.5%');
+        assert.equal(formatFeeBps(1n), '0.01%');
+        assert.equal(formatFeeBps(25n), '0.25%');
+        assert.equal(formatFeeBps(150n), '1.5%');
+    });
+    it('should remove trailing zeros', () => {
+        assert.equal(formatFeeBps(250n), '2.5%');
+        assert.equal(formatFeeBps(300n), '3%');
+    });
+});
+describe('normalizeFeePrecision', () => {
+    describe('basis points input', () => {
+        it('should detect and normalize 0 bps', () => {
+            const result = normalizeFeePrecision(0n);
+            assert.equal(result.precision, 'bps');
+            assert.equal(result.normalizedBps, 0n);
+            assert.equal(result.percentage, '0%');
+        });
+        it('should detect and normalize 200 bps (2%)', () => {
+            const result = normalizeFeePrecision(200n);
+            assert.equal(result.precision, 'bps');
+            assert.equal(result.normalizedBps, 200n);
+            assert.equal(result.percentage, '2%');
+        });
+        it('should detect and normalize small bps values', () => {
+            const result = normalizeFeePrecision(50n);
+            assert.equal(result.precision, 'bps');
+            assert.equal(result.normalizedBps, 50n);
+            assert.equal(result.percentage, '0.5%');
+        });
+        it('should detect and normalize 10000 bps (100%)', () => {
+            const result = normalizeFeePrecision(10000n);
+            assert.equal(result.precision, 'bps');
+            assert.equal(result.normalizedBps, 10000n);
+            assert.equal(result.percentage, '100%');
+        });
+    });
+    describe('18-decimal input', () => {
+        it('should detect and normalize 18-decimal 2%', () => {
+            // 2% in 18 decimals = 0.02 * 1e18 = 2e16
+            const rawFee = 20000000000000000n;
+            const result = normalizeFeePrecision(rawFee);
+            assert.equal(result.precision, '18decimals');
+            assert.equal(result.normalizedBps, 200n);
+            assert.equal(result.percentage, '2%');
+        });
+        it('should detect and normalize 18-decimal 0.5%', () => {
+            // 0.5% in 18 decimals = 0.005 * 1e18 = 5e15
+            const rawFee = 5000000000000000n;
+            const result = normalizeFeePrecision(rawFee);
+            assert.equal(result.precision, '18decimals');
+            assert.equal(result.normalizedBps, 50n);
+            assert.equal(result.percentage, '0.5%');
+        });
+        it('should detect and normalize 18-decimal 100%', () => {
+            // 100% in 18 decimals = 1e18
+            const rawFee = 1000000000000000000n;
+            const result = normalizeFeePrecision(rawFee);
+            assert.equal(result.precision, '18decimals');
+            assert.equal(result.normalizedBps, 10000n);
+            assert.equal(result.percentage, '100%');
+        });
+    });
+});
+describe('calculateTotalFees', () => {
+    it('should sum multiple fees', () => {
+        const result = calculateTotalFees([2000000n, 500000n, 100000n]);
+        assert.equal(result, 2600000n);
+    });
+    it('should return 0 for empty array', () => {
+        const result = calculateTotalFees([]);
+        assert.equal(result, 0n);
+    });
+    it('should return single fee for array with one element', () => {
+        const result = calculateTotalFees([5000000n]);
+        assert.equal(result, 5000000n);
+    });
+});
+describe('isZeroFee', () => {
+    it('should return true for 0 bps', () => {
+        assert.equal(isZeroFee(0n), true);
+    });
+    it('should return false for non-zero bps', () => {
+        assert.equal(isZeroFee(1n), false);
+        assert.equal(isZeroFee(100n), false);
+        assert.equal(isZeroFee(200n), false);
+    });
+});