@provex/utils 1.0.16 → 1.2.3

package/dist/src/input.d.ts

@@ -1,7 +1,26 @@
 /**
- * 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 declare const adjustLowestDecimal: (inputVal: string, direction: 1 | -1) => string;

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

@@ -1,6 +1,32 @@
+/**
+ * @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 for an intent
+ * 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;
@@ -8,7 +34,17 @@ export interface IntentStruct {
     depositId: bigint;
     amount: bigint;
     timestamp: bigint;
-    paymentVerifier: Hex;
     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/src/intent.js

@@ -1 +1,28 @@
-export {};
+/**
+ * @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/src/intent.test.d.ts

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

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

@@ -1,5 +1,27 @@
 /**
- * JSON serializer
+ * @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: {
     /**
@@ -15,4 +37,19 @@ export declare const jsonSerializer: {
      */
     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/src/json.js

@@ -1,5 +1,27 @@
 /**
- * JSON serializer
+ * @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 = {
     /**
@@ -20,7 +42,21 @@ export const jsonSerializer = {
         return value;
     })
 };
-// Recursively convert specified fields to BigInt in an object or array
+/**
+ * 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));

package/dist/src/normalization.d.ts

@@ -0,0 +1,224 @@
+import type { Hex } from 'viem';
+import type { Version } from './contracts.js';
+/**
+ * V2 Deposit structure as stored in the database.
+ * This represents the raw v2 deposit data from the indexer.
+ */
+export type V2DepositData = {
+    escrow: Hex;
+    localId: bigint;
+    chainId: bigint;
+    orderId: Hex;
+    logId: Hex;
+    transactionId: Hex;
+    token: Hex;
+    participantId: Hex;
+    deposited: bigint;
+    remaining: bigint;
+    minAmount: bigint;
+    maxAmount: bigint;
+    depositConversionRateCurrencies: Hex[];
+    depositConversionRateVerifiers: Hex[];
+    version: 'v2';
+    acceptingIntents: boolean;
+    delegate: Hex;
+    intentGuardian: Hex;
+    status: 'active' | 'underfunded' | 'withdrawn' | 'closed';
+};
+/**
+ * V3 Deposit structure - the normalized format.
+ * V3 deposits have the same core fields but may include additional v3-specific metadata.
+ */
+export type V3DepositData = Omit<V2DepositData, 'version'> & {
+    version: 'v3';
+    /**
+     * Tracks the original version if this deposit was normalized from v2.
+     * Undefined for native v3 deposits.
+     */
+    _originalVersion?: Version;
+};
+/**
+ * Normalizes a V2 deposit to V3 format for unified UI consumption.
+ *
+ * Since deposits are already stored in a unified schema, this function
+ * primarily marks the deposit as "appearing" as v3 while preserving
+ * the original version information.
+ *
+ * @param v2Deposit - The v2 deposit data from the indexer
+ * @returns The deposit in v3-normalized format
+ *
+ * @example
+ * ```typescript
+ * const v2Deposit = await getDeposit(escrow, depositId, chainId)
+ * if (v2Deposit.version === 'v2') {
+ *   const normalized = normalizeV2Deposit(v2Deposit)
+ *   // normalized.version === 'v3'
+ *   // normalized._originalVersion === 'v2'
+ * }
+ * ```
+ */
+export declare function normalizeV2Deposit(v2Deposit: V2DepositData): V3DepositData;
+/**
+ * V2 Intent structure as stored in the database.
+ * V2 intents use v2Currency and v2ConversionRateChangeId for rate lookups.
+ */
+export type V2IntentData = {
+    intentHash: Hex;
+    orderId: Hex;
+    logId: Hex;
+    transactionId: Hex;
+    depositEscrow: Hex;
+    depositLocalId: bigint;
+    depositChainId: bigint;
+    escrow: Hex;
+    paymentMethodId: Hex;
+    ownerParticipantId: Hex;
+    toParticipantId: Hex;
+    amount: bigint;
+    fiatCurrency: Hex;
+    conversionRate: bigint;
+    timestamp: bigint;
+    /** V2-specific: Currency hash used for conversion rate lookup */
+    v2Currency: Hex;
+    /** V2-specific: Conversion rate change ID at intent time */
+    v2ConversionRateChangeId: number;
+};
+/**
+ * V3 Intent structure - the normalized format.
+ * V3 intents rely on paymentMethodId for all rate/currency information.
+ */
+export type V3IntentData = {
+    intentHash: Hex;
+    orderId: Hex;
+    logId: Hex;
+    transactionId: Hex;
+    depositEscrow: Hex;
+    depositLocalId: bigint;
+    depositChainId: bigint;
+    escrow: Hex;
+    paymentMethodId: Hex;
+    ownerParticipantId: Hex;
+    toParticipantId: Hex;
+    amount: bigint;
+    fiatCurrency: Hex;
+    conversionRate: bigint;
+    timestamp: bigint;
+    /** V2-specific fields are null in v3 native intents */
+    v2Currency: null;
+    v2ConversionRateChangeId: null;
+    /**
+     * Tracks the original version if this intent was normalized from v2.
+     * Undefined for native v3 intents.
+     */
+    _originalVersion?: Version;
+};
+/**
+ * Normalizes a V2 intent to V3 format for unified UI consumption.
+ *
+ * V2 intents store currency and rate change ID explicitly, while V3 intents
+ * derive this information from the paymentMethodId relationship.
+ * This function converts v2 intent data to the v3 format.
+ *
+ * @param v2Intent - The v2 intent data from the indexer
+ * @returns The intent in v3-normalized format
+ *
+ * @example
+ * ```typescript
+ * const intent = await getIntent(intentHash)
+ * if (intent.v2Currency !== null) {
+ *   const normalized = normalizeV2Intent(intent)
+ *   // normalized.v2Currency === null
+ *   // normalized._originalVersion === 'v2'
+ * }
+ * ```
+ */
+export declare function normalizeV2Intent(v2Intent: V2IntentData): V3IntentData;
+/**
+ * V2 Payment Verification data.
+ * V2 uses ZK proofs verified on-chain via payment verifier contracts.
+ */
+export type V2VerificationData = {
+    intentHash: Hex;
+    verifierAddress: Hex;
+    proofTimestamp: bigint;
+    transactionId: Hex;
+    depositorAddress: Hex;
+    depositId: bigint;
+    amount: bigint;
+};
+/**
+ * V3-style attestation format.
+ * V3 uses EIP-712 signed attestations from trusted attesters.
+ */
+export type V3AttestationData = {
+    intentHash: Hex;
+    attestation: {
+        depositor: Hex;
+        depositId: bigint;
+        amount: bigint;
+        /** Payment identifier (synthesized from v2 proof data) */
+        paymentId: string;
+        timestamp: bigint;
+    };
+    /** Signature placeholder - v2 doesn't have signatures */
+    signature: null;
+    /**
+     * Tracks the original version if this attestation was normalized from v2.
+     */
+    _originalVersion: 'v2';
+    /** Original v2 verification data preserved for reference */
+    _v2Verification: V2VerificationData;
+};
+/**
+ * Normalizes a V2 payment verification to V3 attestation format.
+ *
+ * V2 uses ZK proofs verified by on-chain verifier contracts, while V3 uses
+ * EIP-712 signed attestations. This function synthesizes an attestation-like
+ * structure from v2 verification data.
+ *
+ * Note: The signature field is null since v2 verifications don't use signatures.
+ * The original v2 verification data is preserved in `_v2Verification`.
+ *
+ * @param v2Verification - The v2 verification data
+ * @returns A v3-style attestation structure
+ *
+ * @example
+ * ```typescript
+ * const verification = getV2Verification(intentHash)
+ * const attestation = normalizeV2Verification(verification)
+ * // attestation.attestation.depositor === verification.depositorAddress
+ * // attestation.signature === null (v2 doesn't have signatures)
+ * // attestation._originalVersion === 'v2'
+ * ```
+ */
+export declare function normalizeV2Verification(v2Verification: V2VerificationData): V3AttestationData;
+/**
+ * Type guard to check if a deposit is a v2 deposit.
+ * @param deposit - The deposit data to check
+ * @returns True if the deposit is from v2 escrow
+ */
+export declare function isV2Deposit(deposit: {
+    version: Version;
+}): deposit is {
+    version: 'v2';
+} & typeof deposit;
+/**
+ * Type guard to check if an intent is a v2 intent.
+ * @param intent - The intent data to check
+ * @returns True if the intent has v2-specific fields populated
+ */
+export declare function isV2Intent(intent: {
+    v2Currency: Hex | null;
+}): intent is {
+    v2Currency: Hex;
+} & typeof intent;
+/**
+ * Type guard to check if data was normalized from v2.
+ * @param data - The data to check
+ * @returns True if the data has _originalVersion === 'v2'
+ */
+export declare function isNormalizedFromV2(data: {
+    _originalVersion?: Version;
+}): data is {
+    _originalVersion: 'v2';
+} & typeof data;