@provex/utils 1.0.16 → 1.2.3

package/dist/src/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/src/fees.test.d.ts

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

package/dist/src/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);
+    });
+});

package/dist/src/ids.d.ts

@@ -1,40 +1,64 @@
+/**
+ * @fileoverview ID generation and parsing utilities for the indexer.
+ *
+ * The indexer uses composite IDs (orderIds) to uniquely identify and order
+ * events across multiple chains. Each ID type encodes different information:
+ *
+ * - **deposit**: [escrow (20)][localId (8)][chainId (4)] = 32 bytes
+ * - **block**: [timestamp (8)][chainId (4)] = 12 bytes
+ * - **transaction**: [timestamp (8)][txIndex (4)][chainId (4)] = 16 bytes
+ * - **log**: [timestamp (8)][txIndex (4)][logIndex (4)][chainId (4)] = 20 bytes
+ * - **order**: [timestamp (8)][txIndex (4)][eventType (1)][logIndex (4)][chainId (4)] = 21 bytes
+ * - **stat**: [timestamp (8)][hash (20)][chainId (4)] = 32 bytes
+ *
+ * @remarks
+ * The orderId structure ensures:
+ * - Global ordering across chains by timestamp
+ * - Deterministic ordering within same block
+ * - Parseability to extract original components
+ *
+ * @see {@link events} for event type definitions
+ * @see {@link depositKeys} for deposit compound keys
+ */
 import { type Hex } from "viem";
 import { type EventType } from "./events.js";
 import { type TimeResolutionKey } from "./time.js";
-import type { StatAction } from "./stats.js";
-export type DepositVerifierInputs = {
-    verifier: Hex;
-    depositId: Hex;
-};
-export type DepositCurrencyInputs = DepositVerifierInputs & {
-    currency: Hex;
-};
-export type ConversionRateUpdatedInputs = DepositCurrencyInputs & {
-    changeId: number;
-};
+import type { StatEvent } from "./stats.js";
+import { type ChainId } from "./chain.js";
+/** Input parameters for provider hash generation */
 export type ProviderHashInputs = {
     chainId: bigint | number;
     hash: Hex;
 };
+/** Input parameters for on-chain hash generation */
 export type OnChainHashInputs = {
     chainId: bigint | number;
     hash: Hex;
 };
+/** Input parameters for on-chain address hashing */
 export type OnChainAddressInputs = {
     chainId: bigint | number;
     address: Hex;
 };
+/**
+ * Generate a chain-specific hash by combining chainId and an existing hash.
+ * Creates a unique identifier that includes chain context.
+ */
 export declare const onChainHash: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
 export declare const onChainAddress: ({ chainId, address }: OnChainAddressInputs) => `0x${string}`;
+/**
+ * ID generator functions for various entity types.
+ * Each function creates a unique, deterministic identifier.
+ */
 export declare const ids: {
+    /** Block ID: keccak256(chainId || blockHash) */
     block: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
+    /** Transaction ID: keccak256(chainId || txHash) */
     transaction: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
-    participant: ({ chainId, address }: OnChainAddressInputs) => `0x${string}`;
+    /** Provider hash ID: keccak256(chainId || providerHash) */
     providerHash: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
+    /** Verifier ID: keccak256(chainId || verifierAddress) */
     verifier: ({ chainId, address }: OnChainAddressInputs) => `0x${string}`;
-    depositVerifierAdded: ({ depositId, verifier }: DepositVerifierInputs) => `0x${string}`;
-    depositCurrencyAdded: ({ depositId, currency, verifier }: DepositCurrencyInputs) => `0x${string}`;
-    depositConversionRateUpdated: ({ currency, verifier, depositId, changeId }: ConversionRateUpdatedInputs) => `0x${string}`;
 };
 export type OrderIdInputs = {
     timestamp: bigint;
@@ -51,22 +75,101 @@ export type OrderIdOrderInputs = OrderIdLogInputs & {
 };
 export type DepositIdInputs = {
     chainId: bigint | number;
+    escrow: Hex;
     depositId: bigint | number;
 };
 export type LogStatsIdInputs = {
     timestamp: bigint;
     type: TimeResolutionKey;
-    action: StatAction;
+    event: StatEvent;
     currency: Hex | null;
     token: Hex;
     verifier: Hex;
     chainId: bigint | number;
+    version: 'v2' | 'v3';
+};
+/**
+ * Chunk a hex string into parts of specified byte sizes
+ * @param input - The hex string to chunk (with 0x prefix)
+ * @param byteSizes - Array of byte sizes for each chunk
+ * @returns Array of hex strings, one for each chunk
+ */
+export declare function chunkHex<T extends readonly number[]>(input: Hex, byteSizes: T): {
+    [K in keyof T]: Hex;
 };
+/**
+ * OrderId serialization and parsing utilities.
+ *
+ * Each orderId type has a `serialize` method to create the ID from components,
+ * and a `parse` method to extract components from an existing ID.
+ *
+ * @example
+ * ```ts
+ * // Create a deposit orderId
+ * const id = orderId.deposit.serialize({ chainId: 8453n, escrow, depositId: 42n })
+ *
+ * // Parse it back
+ * const { chainId, escrow, depositId } = orderId.deposit.parse(id)
+ * ```
+ */
 export declare const orderId: {
-    deposit: ({ chainId, depositId }: DepositIdInputs) => `0x${string}`;
-    block: ({ timestamp, chainId }: OrderIdInputs) => `0x${string}`;
-    transaction: ({ timestamp, chainId, transactionIndex }: OrderIdTransactionInputs) => `0x${string}`;
-    log: ({ timestamp, chainId, transactionIndex, logIndex }: OrderIdLogInputs) => `0x${string}`;
-    order: ({ timestamp, chainId, transactionIndex, logIndex, name }: OrderIdOrderInputs) => `0x${string}`;
-    stat: ({ timestamp, type, action, currency, verifier, token, chainId }: LogStatsIdInputs) => `0x${string}`;
+    /**
+     * Deposit orderId: uniquely identifies a deposit across all chains and escrows.
+     * Format: [escrow (20)][localId (8)][chainId (4)] = 32 bytes
+     */
+    deposit: {
+        serialize: ({ chainId, escrow, depositId }: DepositIdInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            escrow: Hex;
+            depositId: bigint;
+            chainId: ChainId;
+        };
+    };
+    block: {
+        serialize: ({ timestamp, chainId }: OrderIdInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            chainId: ChainId;
+        };
+    };
+    transaction: {
+        serialize: ({ timestamp, chainId, transactionIndex }: OrderIdTransactionInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            transactionIndex: number;
+            chainId: ChainId;
+        };
+    };
+    log: {
+        serialize: ({ timestamp, chainId, transactionIndex, logIndex }: OrderIdLogInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            transactionIndex: number;
+            logIndex: number;
+            chainId: ChainId;
+        };
+    };
+    order: {
+        serialize: ({ timestamp, chainId, transactionIndex, logIndex, name }: OrderIdOrderInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            transactionIndex: number;
+            eventTypeId: number;
+            name?: EventType;
+            logIndex: number;
+            chainId: ChainId;
+        };
+    };
+    stat: {
+        serialize: ({ timestamp, type, event, currency, verifier, token, chainId, version }: LogStatsIdInputs) => `0x${string}`;
+        /**
+         * Parse a stat orderId to extract timestamp and chainId.
+         * Note: The hash component cannot be reversed to get type/event/currency/verifier/token.
+         * Format: [timestamp (8)][hash (20)][chainId (4)] = 32 bytes
+         */
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            chainId: ChainId;
+        };
+    };
 };