@provex/utils 1.0.16 → 1.2.3

package/dist/src/endpoints.js

@@ -0,0 +1,70 @@
+/**
+ * Service endpoint URLs for the Provex platform.
+ *
+ * Each URL resolves at module load time using this priority:
+ * 1. Vite env (`import.meta.env.VITE_<NAME>`)
+ * 2. Node env (`process.env.<NAME>` or `process.env.VITE_<NAME>`)
+ * 3. Hardcoded production default
+ *
+ * Override any URL by setting the corresponding environment variable
+ * before the module is imported.
+ *
+ * @example
+ * // In .env or shell
+ * VITE_SPONSOR_SERVER_URL=http://localhost:3001
+ */
+/**
+ * Read an environment variable from either Vite or Node runtime.
+ *
+ * Checks `import.meta.env.VITE_<name>` first (browser / Vite dev server),
+ * then falls back to `process.env.<name>` and `process.env.VITE_<name>`
+ * (Node / scripts).
+ *
+ * @param name - The bare variable name without the `VITE_` prefix.
+ * @returns The value if found, otherwise `undefined`.
+ */
+function readEnv(name) {
+    const viteVal = typeof import.meta !== 'undefined'
+        ? import.meta.env?.[`VITE_${name}`]
+        : undefined;
+    const nodeVal = typeof process !== 'undefined'
+        ? (process.env?.[name] ?? process.env?.[`VITE_${name}`])
+        : undefined;
+    return viteVal ?? nodeVal ?? undefined;
+}
+/**
+ * Base URL for the gas-sponsorship relay server.
+ *
+ * The sponsor server wraps user operations in a sponsored transaction
+ * so end-users never need native gas tokens.
+ *
+ * @defaultValue `https://sponsor.provex.xyz`
+ */
+export const SPONSOR_SERVER_URL = readEnv('SPONSOR_SERVER_URL') ?? 'https://sponsor.provex.xyz';
+/**
+ * WebSocket URL for the Reclaim Protocol attestor node.
+ *
+ * Used during the ZK proof generation flow to obtain a TLS attestation
+ * of payment-provider API responses.
+ *
+ * @defaultValue `wss://attestor.reclaimprotocol.org/ws`
+ */
+export const ATTESTOR_WS_URL = readEnv('ATTESTOR_WS_URL') ?? 'wss://attestor.reclaimprotocol.org/ws';
+/**
+ * GraphQL endpoint for the Provex indexer.
+ *
+ * Serves deposit listings, intent history, and on-chain event data
+ * consumed by the UI and analytics dashboard.
+ *
+ * @defaultValue `https://indexer.provex.xyz/graphql`
+ */
+export const INDEXER_GRAPHQL_URL = readEnv('INDEXER_GRAPHQL_URL') ?? 'https://indexer.provex.xyz/graphql';
+/**
+ * Base URL for the attestation verification service.
+ *
+ * Validates TLS attestations produced by the attestor before they
+ * are submitted on-chain as proof of payment.
+ *
+ * @defaultValue `https://attestation.provex.xyz`
+ */
+export const ATTESTATION_SERVICE_URL = readEnv('ATTESTATION_SERVICE_URL') ?? 'https://attestation.provex.xyz';

package/dist/src/endpoints.test.d.ts

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

package/dist/src/endpoints.test.js

@@ -0,0 +1,54 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { SPONSOR_SERVER_URL, ATTESTOR_WS_URL, INDEXER_GRAPHQL_URL, ATTESTATION_SERVICE_URL, } from './endpoints.js';
+describe('endpoints', () => {
+    const endpoints = [
+        { name: 'SPONSOR_SERVER_URL', value: SPONSOR_SERVER_URL },
+        { name: 'ATTESTOR_WS_URL', value: ATTESTOR_WS_URL },
+        { name: 'INDEXER_GRAPHQL_URL', value: INDEXER_GRAPHQL_URL },
+        { name: 'ATTESTATION_SERVICE_URL', value: ATTESTATION_SERVICE_URL },
+    ];
+    for (const { name, value } of endpoints) {
+        describe(name, () => {
+            it('should be a non-empty string', () => {
+                assert.ok(typeof value === 'string', `${name} should be a string`);
+                assert.ok(value.length > 0, `${name} should not be empty`);
+            });
+            it('should start with https:// or wss://', () => {
+                assert.ok(value.startsWith('https://') || value.startsWith('wss://'), `${name} should start with https:// or wss://, got: ${value}`);
+            });
+            it('should not have a trailing slash', () => {
+                assert.ok(!value.endsWith('/'), `${name} should not end with a trailing slash, got: ${value}`);
+            });
+            it('should not contain whitespace', () => {
+                assert.equal(value, value.trim(), `${name} should not have leading/trailing whitespace`);
+                assert.ok(!/\s/.test(value), `${name} should not contain whitespace`);
+            });
+        });
+    }
+    describe('default values', () => {
+        it('SPONSOR_SERVER_URL defaults to production', () => {
+            assert.equal(SPONSOR_SERVER_URL, 'https://sponsor.provex.xyz');
+        });
+        it('ATTESTOR_WS_URL defaults to Reclaim attestor', () => {
+            assert.equal(ATTESTOR_WS_URL, 'wss://attestor.reclaimprotocol.org/ws');
+        });
+        it('INDEXER_GRAPHQL_URL defaults to production GraphQL', () => {
+            assert.equal(INDEXER_GRAPHQL_URL, 'https://indexer.provex.xyz/graphql');
+        });
+        it('ATTESTATION_SERVICE_URL defaults to production', () => {
+            assert.equal(ATTESTATION_SERVICE_URL, 'https://attestation.provex.xyz');
+        });
+    });
+    describe('protocol expectations', () => {
+        it('ATTESTOR_WS_URL uses wss:// protocol', () => {
+            assert.ok(ATTESTOR_WS_URL.startsWith('wss://'), 'WebSocket URL should use wss://');
+        });
+        it('HTTPS endpoints use https:// protocol', () => {
+            const httpsEndpoints = [SPONSOR_SERVER_URL, INDEXER_GRAPHQL_URL, ATTESTATION_SERVICE_URL];
+            for (const url of httpsEndpoints) {
+                assert.ok(url.startsWith('https://'), `Expected https://, got: ${url}`);
+            }
+        });
+    });
+});

package/dist/src/events.d.ts

@@ -1,3 +1,41 @@
-export declare const eventOrder: readonly ["deposit", "verifier_added", "currency_added", "rate_update", "intent", "exchange", "pruned", "withdrawal", "closed"];
+/**
+ * @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 declare const eventOrder: readonly ["deposit_received", "deposit_payment_method_added", "deposit_payment_method_active_updated", "deposit_currency_added", "deposit_delegate_set", "deposit_delegate_removed", "deposit_conversion_rate_updated", "deposit_accepting_intents_updated", "deposit_intent_amount_range_updated", "deposit_funds_added", "intent_signaled", "funds_locked", "payment_verified", "funds_unlocked_and_transferred", "intent_fulfilled", "intent_pruned", "funds_unlocked", "intent_expiry_extended", "funds_removed", "deposit_withdrawn", "deposit_closed", "dust_collected", "dust_recipient_updated", "dust_threshold_updated", "deposit_retain_on_empty_updated", "payment_method_currency_added", "payment_method_currency_removed", "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", "intent_expiration_period_updated", "max_intents_per_deposit_updated", "min_deposit_amount_set", "orchestrator_updated", "ownership_transferred", "payment_verifier_registry_updated", "provider_hash_added", "provider_hash_removed"];
+/**
+ * Union type of all valid event type names.
+ * Use this when filtering or handling specific event types.
+ */
 export type EventType = (typeof eventOrder)[number];
-export declare const eventOrderId: Map<"deposit" | "withdrawal" | "closed" | "exchange" | "verifier_added" | "currency_added" | "rate_update" | "intent" | "pruned", number>;
+/**
+ * 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 declare const eventOrderId: Map<"paused" | "deposit_received" | "deposit_payment_method_added" | "deposit_payment_method_active_updated" | "deposit_currency_added" | "deposit_delegate_set" | "deposit_delegate_removed" | "deposit_conversion_rate_updated" | "deposit_accepting_intents_updated" | "deposit_intent_amount_range_updated" | "deposit_funds_added" | "intent_signaled" | "funds_locked" | "payment_verified" | "funds_unlocked_and_transferred" | "intent_fulfilled" | "intent_pruned" | "funds_unlocked" | "intent_expiry_extended" | "funds_removed" | "deposit_withdrawn" | "deposit_closed" | "dust_collected" | "dust_recipient_updated" | "dust_threshold_updated" | "deposit_retain_on_empty_updated" | "payment_method_currency_added" | "payment_method_currency_removed" | "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" | "intent_expiration_period_updated" | "max_intents_per_deposit_updated" | "min_deposit_amount_set" | "orchestrator_updated" | "ownership_transferred" | "payment_verifier_registry_updated" | "provider_hash_added" | "provider_hash_removed", number>;

package/dist/src/events.js

@@ -1,16 +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',
-    'verifier_added',
-    'currency_added',
-    // configuration events
-    'rate_update',
+    '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',
-    'exchange',
-    'pruned',
+    'intent_signaled',
+    'funds_locked',
+    'payment_verified',
+    'funds_unlocked_and_transferred',
+    'intent_fulfilled',
+    'intent_pruned',
+    'funds_unlocked',
+    'intent_expiry_extended',
     // deposit close events
-    'withdrawal',
-    'closed',
+    '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/src/events.test.d.ts

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

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