@provex/utils 1.0.16 → 1.2.4

package/dist/input.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Input manipulation utilities for numeric string handling.
+ *
+ * Provides utilities for incrementing/decrementing decimal values while
+ * preserving the user's intended precision (trailing zeros).
+ */
+/**
+ * Adjust the lowest decimal place of a numeric string by +1 or -1.
+ * Preserves the original decimal precision (trailing zeros are maintained).
+ *
+ * Used for numeric input controls with up/down buttons that increment
+ * at the current decimal precision level.
+ *
+ * @param inputVal - The input value as a string (e.g., "1.50", "100", "0.001")
+ * @param direction - Direction to adjust: 1 (increment) or -1 (decrement)
+ * @returns The adjusted value with original precision preserved
+ *
+ * @example
+ * ```ts
+ * adjustLowestDecimal("1.50", 1)   // "1.51"
+ * adjustLowestDecimal("1.50", -1)  // "1.49"
+ * adjustLowestDecimal("100", 1)    // "101"
+ * adjustLowestDecimal("0.001", 1)  // "0.002"
+ * ```
+ */
+export declare const adjustLowestDecimal: (inputVal: string, direction: 1 | -1) => string;

package/dist/{src/input.js → input.js}

@@ -1,8 +1,27 @@
 /**
- * Adjust the lowest decimal place directly on the string, preserving all trailing zeros
- * @param inputVal - The input value
- * @param direction - The direction to adjust the decimal place
- * @returns The adjusted value
+ * @fileoverview Input manipulation utilities for numeric string handling.
+ *
+ * Provides utilities for incrementing/decrementing decimal values while
+ * preserving the user's intended precision (trailing zeros).
+ */
+/**
+ * Adjust the lowest decimal place of a numeric string by +1 or -1.
+ * Preserves the original decimal precision (trailing zeros are maintained).
+ *
+ * Used for numeric input controls with up/down buttons that increment
+ * at the current decimal precision level.
+ *
+ * @param inputVal - The input value as a string (e.g., "1.50", "100", "0.001")
+ * @param direction - Direction to adjust: 1 (increment) or -1 (decrement)
+ * @returns The adjusted value with original precision preserved
+ *
+ * @example
+ * ```ts
+ * adjustLowestDecimal("1.50", 1)   // "1.51"
+ * adjustLowestDecimal("1.50", -1)  // "1.49"
+ * adjustLowestDecimal("100", 1)    // "101"
+ * adjustLowestDecimal("0.001", 1)  // "0.002"
+ * ```
  */
 export const adjustLowestDecimal = (inputVal, direction) => {
     let [whole, decimal = ''] = inputVal.split('.');

package/dist/intent.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Intent data structures and validation utilities.
+ *
+ * An intent represents a buyer's commitment to purchase tokens from a deposit
+ * at a specific price. The intent lifecycle:
+ *
+ * 1. **Signal**: Buyer calls signalIntent() on Orchestrator, funds are soft-locked
+ * 2. **Lock**: For V3, explicit lock period with expiry time
+ * 3. **Verify**: Buyer proves off-chain payment via zkTLS attestation
+ * 4. **Fulfill**: Verifier releases escrowed funds to buyer
+ *
+ * @remarks
+ * V2 and V3 intents have different field structures:
+ * - V2: Uses paymentVerifier (address) to identify payment method
+ * - V3: Uses paymentMethod (bytes32 hash) and includes escrow address
+ *
+ * @see {@link peer-types} for attestation types
+ * @see {@link payment} for payment method definitions
+ */
+import type { Hex } from "viem";
+/**
+ * Structure representing an on-chain intent.
+ *
+ * V2 intents use `paymentVerifier` (address, 20 bytes).
+ * V3 intents use `paymentMethod` (bytes32, 32 bytes) and include `escrow`.
+ *
+ * When working with this interface:
+ * - Check `paymentMethod` first (V3), fall back to `paymentVerifier` (V2)
+ * - Use `escrow` only when available (V3)
+ */
+export interface IntentStruct {
+    owner: Hex;
+    to: Hex;
+    depositId: bigint;
+    amount: bigint;
+    timestamp: bigint;
+    fiatCurrency: Hex;
+    conversionRate: bigint;
+    /** V2 only: Payment verifier contract address (20 bytes) */
+    paymentVerifier?: Hex;
+    /** V3 only: Payment method ID hash (32 bytes) */
+    paymentMethod?: Hex;
+    /** V3 only: Escrow contract address */
+    escrow?: Hex;
+}
+/**
+ * Check if an intent is empty (not found on-chain).
+ * V3 Orchestrator returns zero-filled struct when intent doesn't exist.
+ */
+export declare function isEmptyIntent(intent: IntentStruct | null): boolean;

package/dist/intent.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Intent data structures and validation utilities.
+ *
+ * An intent represents a buyer's commitment to purchase tokens from a deposit
+ * at a specific price. The intent lifecycle:
+ *
+ * 1. **Signal**: Buyer calls signalIntent() on Orchestrator, funds are soft-locked
+ * 2. **Lock**: For V3, explicit lock period with expiry time
+ * 3. **Verify**: Buyer proves off-chain payment via zkTLS attestation
+ * 4. **Fulfill**: Verifier releases escrowed funds to buyer
+ *
+ * @remarks
+ * V2 and V3 intents have different field structures:
+ * - V2: Uses paymentVerifier (address) to identify payment method
+ * - V3: Uses paymentMethod (bytes32 hash) and includes escrow address
+ *
+ * @see {@link peer-types} for attestation types
+ * @see {@link payment} for payment method definitions
+ */
+/**
+ * Check if an intent is empty (not found on-chain).
+ * V3 Orchestrator returns zero-filled struct when intent doesn't exist.
+ */
+export function isEmptyIntent(intent) {
+    if (!intent)
+        return true;
+    return intent.amount === 0n && intent.timestamp === 0n && intent.depositId === 0n;
+}

package/dist/intent.test.d.ts

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

package/dist/intent.test.js

@@ -0,0 +1,119 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isEmptyIntent } from './intent.js';
+import { zeroAddress } from 'viem';
+/**
+ * Tests for IntentStruct and isEmptyIntent utility
+ *
+ * V2 intents use paymentVerifier (address, 20 bytes)
+ * V3 intents use paymentMethod (bytes32, 32 bytes) and include escrow
+ */
+// Sample V3 intent (all fields populated)
+const mockV3Intent = {
+    owner: '0x1234567890123456789012345678901234567890',
+    to: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+    escrow: '0x2f121CDDCA6d652f35e8B3E560f9760898888888',
+    depositId: 42n,
+    amount: 100000000n, // 100 USDC
+    timestamp: 1737123456n,
+    paymentMethod: '0x1234567890123456789012345678901234567890123456789012345678901234',
+    fiatCurrency: '0x0000000000000000000000000000000000000000000000000000000000555344', // USD
+    conversionRate: 1000000000000000000n, // 1.0
+};
+// Sample V2 intent (no escrow, uses paymentVerifier)
+const mockV2Intent = {
+    owner: '0x1234567890123456789012345678901234567890',
+    to: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+    depositId: 42n,
+    amount: 100000000n,
+    timestamp: 1737123456n,
+    paymentVerifier: '0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5', // venmo verifier
+    fiatCurrency: '0x0000000000000000000000000000000000000000000000000000000000555344',
+    conversionRate: 1000000000000000000n,
+};
+// Empty intent (what V3 Orchestrator returns when intent not found)
+const emptyIntent = {
+    owner: zeroAddress,
+    to: zeroAddress,
+    escrow: zeroAddress,
+    depositId: 0n,
+    amount: 0n,
+    timestamp: 0n,
+    paymentMethod: '0x0000000000000000000000000000000000000000000000000000000000000000',
+    fiatCurrency: '0x0000000000000000000000000000000000000000000000000000000000000000',
+    conversionRate: 0n,
+};
+describe('IntentStruct type', () => {
+    describe('V3 intent structure', () => {
+        it('has escrow field for V3', () => {
+            assert.ok(mockV3Intent.escrow !== undefined, 'escrow should be defined');
+            assert.equal(mockV3Intent.escrow, '0x2f121CDDCA6d652f35e8B3E560f9760898888888');
+        });
+        it('has paymentMethod field (bytes32) for V3', () => {
+            assert.ok(mockV3Intent.paymentMethod !== undefined, 'paymentMethod should be defined');
+            assert.equal(mockV3Intent.paymentMethod?.length, 66, '0x + 64 hex chars');
+        });
+        it('does not require paymentVerifier for V3', () => {
+            assert.equal(mockV3Intent.paymentVerifier, undefined);
+        });
+    });
+    describe('V2 intent structure', () => {
+        it('has paymentVerifier field (address) for V2', () => {
+            assert.ok(mockV2Intent.paymentVerifier !== undefined, 'paymentVerifier should be defined');
+            assert.equal(mockV2Intent.paymentVerifier?.length, 42, '0x + 40 hex chars');
+        });
+        it('does not require escrow for V2', () => {
+            assert.equal(mockV2Intent.escrow, undefined);
+        });
+        it('does not require paymentMethod for V2', () => {
+            assert.equal(mockV2Intent.paymentMethod, undefined);
+        });
+    });
+    describe('backwards compatibility', () => {
+        it('common fields are present in both V2 and V3', () => {
+            const commonFields = ['owner', 'to', 'depositId', 'amount', 'timestamp', 'fiatCurrency', 'conversionRate'];
+            for (const field of commonFields) {
+                assert.ok(field in mockV3Intent, `V3 intent should have ${field}`);
+                assert.ok(field in mockV2Intent, `V2 intent should have ${field}`);
+            }
+        });
+    });
+});
+describe('isEmptyIntent', () => {
+    it('returns true for null', () => {
+        assert.equal(isEmptyIntent(null), true);
+    });
+    it('returns true for empty intent (all zeros)', () => {
+        assert.equal(isEmptyIntent(emptyIntent), true);
+    });
+    it('returns false when only amount is 0 (other fields non-zero)', () => {
+        const intentWithZeroAmount = { ...mockV3Intent, amount: 0n };
+        assert.equal(isEmptyIntent(intentWithZeroAmount), false);
+    });
+    it('returns false when only timestamp is 0 (other fields non-zero)', () => {
+        const intentWithZeroTimestamp = { ...mockV3Intent, timestamp: 0n };
+        assert.equal(isEmptyIntent(intentWithZeroTimestamp), false);
+    });
+    it('returns false when only depositId is 0 (other fields non-zero)', () => {
+        const intentWithZeroDepositId = { ...mockV3Intent, depositId: 0n };
+        assert.equal(isEmptyIntent(intentWithZeroDepositId), false);
+    });
+    it('returns false for valid V3 intent', () => {
+        assert.equal(isEmptyIntent(mockV3Intent), false);
+    });
+    it('returns false for valid V2 intent', () => {
+        assert.equal(isEmptyIntent(mockV2Intent), false);
+    });
+});
+describe('payment identifier handling', () => {
+    it('can extract payment identifier from V3 intent', () => {
+        const paymentIdentifier = mockV3Intent.paymentMethod ?? mockV3Intent.paymentVerifier ?? '0x';
+        assert.equal(paymentIdentifier, mockV3Intent.paymentMethod);
+        assert.equal(paymentIdentifier.length, 66, 'bytes32');
+    });
+    it('can extract payment identifier from V2 intent', () => {
+        const paymentIdentifier = mockV2Intent.paymentMethod ?? mockV2Intent.paymentVerifier ?? '0x';
+        assert.equal(paymentIdentifier, mockV2Intent.paymentVerifier);
+        assert.equal(paymentIdentifier.length, 42, 'address');
+    });
+});

package/dist/json.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview JSON utilities for handling bigint serialization.
+ *
+ * Standard JSON.stringify cannot handle bigint values. This module provides
+ * a serializer that converts bigints to strings, and utilities for
+ * converting string fields back to bigints after parsing.
+ */
+/**
+ * JSON serializer with bigint support.
+ * Converts bigints to strings during stringify, allowing JSON.parse to read them later.
+ *
+ * @example
+ * ```ts
+ * const obj = { amount: 100_000000n, name: 'test' }
+ * const json = jsonSerializer.stringify(obj)
+ * // '{"amount":"100000000","name":"test"}'
+ *
+ * const parsed = jsonSerializer.parse(json)
+ * // { amount: "100000000", name: "test" } (amount is still a string!)
+ *
+ * // Use mapBigIntFields to convert back to bigint
+ * const restored = mapBigIntFields(parsed, ['amount'])
+ * // { amount: 100000000n, name: 'test' }
+ * ```
+ */
+export declare const jsonSerializer: {
+    /**
+     * Parse a JSON string
+     * @param str - The JSON string to parse
+     * @returns The parsed object
+     */
+    parse: (text: string, reviver?: (this: any, key: string, value: any) => any) => any;
+    /**
+     * Stringify an object
+     * @param obj - The object to stringify
+     * @returns The stringified object
+     */
+    stringify: (obj: unknown) => string;
+};
+/**
+ * Recursively convert specified string fields to BigInt in an object or array.
+ * Used after JSON.parse to restore bigint values that were serialized as strings.
+ *
+ * @param obj - The object or array to process
+ * @param fields - Array of field names that should be converted to BigInt
+ * @returns The object with specified fields converted to BigInt
+ *
+ * @example
+ * ```ts
+ * const data = { amount: "100", nested: { value: "50" }, name: "test" }
+ * const result = mapBigIntFields(data, ['amount', 'value'])
+ * // { amount: 100n, nested: { value: 50n }, name: "test" }
+ * ```
+ */
+export declare function mapBigIntFields<T>(obj: T, fields: string[]): T;

package/dist/json.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview JSON utilities for handling bigint serialization.
+ *
+ * Standard JSON.stringify cannot handle bigint values. This module provides
+ * a serializer that converts bigints to strings, and utilities for
+ * converting string fields back to bigints after parsing.
+ */
+/**
+ * JSON serializer with bigint support.
+ * Converts bigints to strings during stringify, allowing JSON.parse to read them later.
+ *
+ * @example
+ * ```ts
+ * const obj = { amount: 100_000000n, name: 'test' }
+ * const json = jsonSerializer.stringify(obj)
+ * // '{"amount":"100000000","name":"test"}'
+ *
+ * const parsed = jsonSerializer.parse(json)
+ * // { amount: "100000000", name: "test" } (amount is still a string!)
+ *
+ * // Use mapBigIntFields to convert back to bigint
+ * const restored = mapBigIntFields(parsed, ['amount'])
+ * // { amount: 100000000n, name: 'test' }
+ * ```
+ */
+export const jsonSerializer = {
+    /**
+     * Parse a JSON string
+     * @param str - The JSON string to parse
+     * @returns The parsed object
+     */
+    parse: JSON.parse,
+    /**
+     * Stringify an object
+     * @param obj - The object to stringify
+     * @returns The stringified object
+     */
+    stringify: (obj) => JSON.stringify(obj, (_key, value) => {
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        return value;
+    })
+};
+/**
+ * Recursively convert specified string fields to BigInt in an object or array.
+ * Used after JSON.parse to restore bigint values that were serialized as strings.
+ *
+ * @param obj - The object or array to process
+ * @param fields - Array of field names that should be converted to BigInt
+ * @returns The object with specified fields converted to BigInt
+ *
+ * @example
+ * ```ts
+ * const data = { amount: "100", nested: { value: "50" }, name: "test" }
+ * const result = mapBigIntFields(data, ['amount', 'value'])
+ * // { amount: 100n, nested: { value: 50n }, name: "test" }
+ * ```
+ */
+export function mapBigIntFields(obj, fields) {
+    if (Array.isArray(obj)) {
+        return obj.map(item => mapBigIntFields(item, fields));
+    }
+    if (obj && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (fields.includes(key) && typeof value === 'string' && value.match(/^-?\d+$/)) {
+                result[key] = BigInt(value);
+            }
+            else if (Array.isArray(value) || (value && typeof value === 'object')) {
+                result[key] = mapBigIntFields(value, fields);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    return obj;
+}

package/dist/participants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Participant identification utilities for the indexer.
+ *
+ * Participants (depositors and payers) are identified by a combination of
+ * their chain ID and address, hashed to create a unique cross-chain identifier.
+ */
+/**
+ * Generate a unique participant ID from chain ID and address.
+ * Uses keccak256(chainId || address) to create a deterministic identifier
+ * that is unique across all chains.
+ *
+ * @param chainId - The chain ID (number or bigint)
+ * @param address - The participant's wallet address
+ * @returns A 32-byte hex string representing the participant ID
+ *
+ * @example
+ * ```ts
+ * const id = generateParticipantId(8453, '0xabc123...')
+ * // '0x...' (keccak256 hash)
+ * ```
+ */
+export declare function generateParticipantId(chainId: number | bigint, address: string): string;

package/dist/participants.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Participant identification utilities for the indexer.
+ *
+ * Participants (depositors and payers) are identified by a combination of
+ * their chain ID and address, hashed to create a unique cross-chain identifier.
+ */
+import { concatHex, keccak256, numberToHex } from 'viem';
+/**
+ * Generate a unique participant ID from chain ID and address.
+ * Uses keccak256(chainId || address) to create a deterministic identifier
+ * that is unique across all chains.
+ *
+ * @param chainId - The chain ID (number or bigint)
+ * @param address - The participant's wallet address
+ * @returns A 32-byte hex string representing the participant ID
+ *
+ * @example
+ * ```ts
+ * const id = generateParticipantId(8453, '0xabc123...')
+ * // '0x...' (keccak256 hash)
+ * ```
+ */
+export function generateParticipantId(chainId, address) {
+    return keccak256(concatHex([
+        numberToHex(chainId, { size: 8 }),
+        address
+    ]));
+}