@provex/utils 1.0.16 → 1.2.3

package/dist/src/normalization.js

@@ -0,0 +1,119 @@
+/**
+ * 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 function normalizeV2Deposit(v2Deposit) {
+    const { version: _v2Version, ...rest } = v2Deposit;
+    return {
+        ...rest,
+        version: 'v3',
+        _originalVersion: 'v2',
+    };
+}
+/**
+ * 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 function normalizeV2Intent(v2Intent) {
+    const { v2Currency: _currency, v2ConversionRateChangeId: _changeId, ...rest } = v2Intent;
+    return {
+        ...rest,
+        v2Currency: null,
+        v2ConversionRateChangeId: null,
+        _originalVersion: 'v2',
+    };
+}
+/**
+ * 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 function normalizeV2Verification(v2Verification) {
+    return {
+        intentHash: v2Verification.intentHash,
+        attestation: {
+            depositor: v2Verification.depositorAddress,
+            depositId: v2Verification.depositId,
+            amount: v2Verification.amount,
+            // Synthesize a payment ID from intent hash (v2 doesn't have explicit payment IDs)
+            paymentId: `v2-${v2Verification.intentHash.slice(0, 18)}`,
+            timestamp: v2Verification.proofTimestamp,
+        },
+        signature: null,
+        _originalVersion: 'v2',
+        _v2Verification: v2Verification,
+    };
+}
+/**
+ * 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 function isV2Deposit(deposit) {
+    return deposit.version === 'v2';
+}
+/**
+ * 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 function isV2Intent(intent) {
+    return intent.v2Currency !== null;
+}
+/**
+ * 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 function isNormalizedFromV2(data) {
+    return data._originalVersion === 'v2';
+}

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

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

package/dist/src/normalization.test.js

@@ -0,0 +1,284 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeV2Deposit, normalizeV2Intent, normalizeV2Verification, isV2Deposit, isV2Intent, isNormalizedFromV2, } from './normalization.js';
+describe('normalization', () => {
+    // Test data fixtures
+    const TEST_ESCROW = '0x1234567890123456789012345678901234567890';
+    const TEST_TOKEN = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+    const TEST_PARTICIPANT = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd';
+    const TEST_DELEGATE = '0x1111111111111111111111111111111111111111';
+    const TEST_GUARDIAN = '0x2222222222222222222222222222222222222222';
+    const TEST_ORDER_ID = '0x3333333333333333333333333333333333333333333333333333333333333333';
+    const TEST_LOG_ID = '0x4444444444444444444444444444444444444444444444444444444444444444';
+    const TEST_TX_ID = '0x5555555555555555555555555555555555555555555555555555555555555555';
+    const TEST_INTENT_HASH = '0x6666666666666666666666666666666666666666666666666666666666666666';
+    const TEST_CURRENCY = '0x7777777777777777777777777777777777777777777777777777777777777777';
+    const TEST_PAYMENT_METHOD = '0x8888888888888888888888888888888888888888888888888888888888888888';
+    const TEST_VERIFIER = '0x9999999999999999999999999999999999999999';
+    const createV2Deposit = () => ({
+        escrow: TEST_ESCROW,
+        localId: 1n,
+        chainId: 8453n,
+        orderId: TEST_ORDER_ID,
+        logId: TEST_LOG_ID,
+        transactionId: TEST_TX_ID,
+        token: TEST_TOKEN,
+        participantId: TEST_PARTICIPANT,
+        deposited: 1000000000n,
+        remaining: 500000000n,
+        minAmount: 100000000n,
+        maxAmount: 1000000000n,
+        depositConversionRateCurrencies: [TEST_CURRENCY],
+        depositConversionRateVerifiers: [TEST_VERIFIER],
+        version: 'v2',
+        acceptingIntents: true,
+        delegate: TEST_DELEGATE,
+        intentGuardian: TEST_GUARDIAN,
+        status: 'active',
+    });
+    const createV2Intent = () => ({
+        intentHash: TEST_INTENT_HASH,
+        orderId: TEST_ORDER_ID,
+        logId: TEST_LOG_ID,
+        transactionId: TEST_TX_ID,
+        depositEscrow: TEST_ESCROW,
+        depositLocalId: 1n,
+        depositChainId: 8453n,
+        escrow: TEST_ESCROW,
+        paymentMethodId: TEST_PAYMENT_METHOD,
+        ownerParticipantId: TEST_PARTICIPANT,
+        toParticipantId: TEST_DELEGATE,
+        amount: 500000000n,
+        fiatCurrency: TEST_CURRENCY,
+        conversionRate: 1000000n,
+        timestamp: 1704067200n,
+        v2Currency: TEST_CURRENCY,
+        v2ConversionRateChangeId: 42,
+    });
+    const createV2Verification = () => ({
+        intentHash: TEST_INTENT_HASH,
+        verifierAddress: TEST_VERIFIER,
+        proofTimestamp: 1704067200n,
+        transactionId: TEST_TX_ID,
+        depositorAddress: TEST_PARTICIPANT,
+        depositId: 1n,
+        amount: 500000000n,
+    });
+    describe('normalizeV2Deposit', () => {
+        it('should convert v2 deposit to v3 format', () => {
+            const v2Deposit = createV2Deposit();
+            const normalized = normalizeV2Deposit(v2Deposit);
+            assert.equal(normalized.version, 'v3');
+            assert.equal(normalized._originalVersion, 'v2');
+        });
+        it('should preserve all original fields', () => {
+            const v2Deposit = createV2Deposit();
+            const normalized = normalizeV2Deposit(v2Deposit);
+            assert.equal(normalized.escrow, v2Deposit.escrow);
+            assert.equal(normalized.localId, v2Deposit.localId);
+            assert.equal(normalized.chainId, v2Deposit.chainId);
+            assert.equal(normalized.orderId, v2Deposit.orderId);
+            assert.equal(normalized.logId, v2Deposit.logId);
+            assert.equal(normalized.transactionId, v2Deposit.transactionId);
+            assert.equal(normalized.token, v2Deposit.token);
+            assert.equal(normalized.participantId, v2Deposit.participantId);
+            assert.equal(normalized.deposited, v2Deposit.deposited);
+            assert.equal(normalized.remaining, v2Deposit.remaining);
+            assert.equal(normalized.minAmount, v2Deposit.minAmount);
+            assert.equal(normalized.maxAmount, v2Deposit.maxAmount);
+            assert.deepEqual(normalized.depositConversionRateCurrencies, v2Deposit.depositConversionRateCurrencies);
+            assert.deepEqual(normalized.depositConversionRateVerifiers, v2Deposit.depositConversionRateVerifiers);
+            assert.equal(normalized.acceptingIntents, v2Deposit.acceptingIntents);
+            assert.equal(normalized.delegate, v2Deposit.delegate);
+            assert.equal(normalized.intentGuardian, v2Deposit.intentGuardian);
+            assert.equal(normalized.status, v2Deposit.status);
+        });
+        it('should not mutate original deposit', () => {
+            const v2Deposit = createV2Deposit();
+            const originalVersion = v2Deposit.version;
+            normalizeV2Deposit(v2Deposit);
+            assert.equal(v2Deposit.version, originalVersion);
+        });
+        it('should handle deposits with different statuses', () => {
+            const statuses = [
+                'active',
+                'underfunded',
+                'withdrawn',
+                'closed',
+            ];
+            for (const status of statuses) {
+                const v2Deposit = { ...createV2Deposit(), status };
+                const normalized = normalizeV2Deposit(v2Deposit);
+                assert.equal(normalized.status, status);
+                assert.equal(normalized.version, 'v3');
+            }
+        });
+        it('should handle deposits with empty arrays', () => {
+            const v2Deposit = {
+                ...createV2Deposit(),
+                depositConversionRateCurrencies: [],
+                depositConversionRateVerifiers: [],
+            };
+            const normalized = normalizeV2Deposit(v2Deposit);
+            assert.deepEqual(normalized.depositConversionRateCurrencies, []);
+            assert.deepEqual(normalized.depositConversionRateVerifiers, []);
+        });
+    });
+    describe('normalizeV2Intent', () => {
+        it('should convert v2 intent to v3 format', () => {
+            const v2Intent = createV2Intent();
+            const normalized = normalizeV2Intent(v2Intent);
+            assert.equal(normalized.v2Currency, null);
+            assert.equal(normalized.v2ConversionRateChangeId, null);
+            assert.equal(normalized._originalVersion, 'v2');
+        });
+        it('should preserve all non-v2-specific fields', () => {
+            const v2Intent = createV2Intent();
+            const normalized = normalizeV2Intent(v2Intent);
+            assert.equal(normalized.intentHash, v2Intent.intentHash);
+            assert.equal(normalized.orderId, v2Intent.orderId);
+            assert.equal(normalized.logId, v2Intent.logId);
+            assert.equal(normalized.transactionId, v2Intent.transactionId);
+            assert.equal(normalized.depositEscrow, v2Intent.depositEscrow);
+            assert.equal(normalized.depositLocalId, v2Intent.depositLocalId);
+            assert.equal(normalized.depositChainId, v2Intent.depositChainId);
+            assert.equal(normalized.escrow, v2Intent.escrow);
+            assert.equal(normalized.paymentMethodId, v2Intent.paymentMethodId);
+            assert.equal(normalized.ownerParticipantId, v2Intent.ownerParticipantId);
+            assert.equal(normalized.toParticipantId, v2Intent.toParticipantId);
+            assert.equal(normalized.amount, v2Intent.amount);
+            assert.equal(normalized.fiatCurrency, v2Intent.fiatCurrency);
+            assert.equal(normalized.conversionRate, v2Intent.conversionRate);
+            assert.equal(normalized.timestamp, v2Intent.timestamp);
+        });
+        it('should not mutate original intent', () => {
+            const v2Intent = createV2Intent();
+            const originalCurrency = v2Intent.v2Currency;
+            const originalChangeId = v2Intent.v2ConversionRateChangeId;
+            normalizeV2Intent(v2Intent);
+            assert.equal(v2Intent.v2Currency, originalCurrency);
+            assert.equal(v2Intent.v2ConversionRateChangeId, originalChangeId);
+        });
+        it('should clear v2-specific rate lookup fields', () => {
+            const v2Intent = createV2Intent();
+            const normalized = normalizeV2Intent(v2Intent);
+            // V3 intents derive rate info from paymentMethodId, not these fields
+            assert.strictEqual(normalized.v2Currency, null);
+            assert.strictEqual(normalized.v2ConversionRateChangeId, null);
+        });
+    });
+    describe('normalizeV2Verification', () => {
+        it('should convert v2 verification to v3 attestation format', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.equal(normalized.intentHash, v2Verification.intentHash);
+            assert.equal(normalized._originalVersion, 'v2');
+            assert.equal(normalized.signature, null);
+        });
+        it('should create attestation structure from verification data', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.equal(normalized.attestation.depositor, v2Verification.depositorAddress);
+            assert.equal(normalized.attestation.depositId, v2Verification.depositId);
+            assert.equal(normalized.attestation.amount, v2Verification.amount);
+            assert.equal(normalized.attestation.timestamp, v2Verification.proofTimestamp);
+        });
+        it('should synthesize paymentId from intent hash', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.ok(normalized.attestation.paymentId.startsWith('v2-'));
+            assert.ok(normalized.attestation.paymentId.includes(v2Verification.intentHash.slice(2, 18)));
+        });
+        it('should preserve original v2 verification data', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.deepEqual(normalized._v2Verification, v2Verification);
+        });
+        it('should not mutate original verification', () => {
+            const v2Verification = createV2Verification();
+            const originalHash = v2Verification.intentHash;
+            normalizeV2Verification(v2Verification);
+            assert.equal(v2Verification.intentHash, originalHash);
+        });
+        it('should have null signature since v2 does not use signatures', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.strictEqual(normalized.signature, null);
+        });
+    });
+    describe('isV2Deposit', () => {
+        it('should return true for v2 deposits', () => {
+            const v2Deposit = createV2Deposit();
+            assert.equal(isV2Deposit(v2Deposit), true);
+        });
+        it('should return false for v3 deposits', () => {
+            const v3Deposit = { version: 'v3' };
+            assert.equal(isV2Deposit(v3Deposit), false);
+        });
+        it('should work with normalized deposits', () => {
+            const v2Deposit = createV2Deposit();
+            const normalized = normalizeV2Deposit(v2Deposit);
+            assert.equal(isV2Deposit(normalized), false); // Normalized is now v3
+        });
+    });
+    describe('isV2Intent', () => {
+        it('should return true for v2 intents with non-null v2Currency', () => {
+            const v2Intent = createV2Intent();
+            assert.equal(isV2Intent(v2Intent), true);
+        });
+        it('should return false for v3 intents with null v2Currency', () => {
+            const v3Intent = { v2Currency: null };
+            assert.equal(isV2Intent(v3Intent), false);
+        });
+        it('should work with normalized intents', () => {
+            const v2Intent = createV2Intent();
+            const normalized = normalizeV2Intent(v2Intent);
+            assert.equal(isV2Intent(normalized), false); // Normalized has null v2Currency
+        });
+    });
+    describe('isNormalizedFromV2', () => {
+        it('should return true for normalized v2 deposits', () => {
+            const v2Deposit = createV2Deposit();
+            const normalized = normalizeV2Deposit(v2Deposit);
+            assert.equal(isNormalizedFromV2(normalized), true);
+        });
+        it('should return true for normalized v2 intents', () => {
+            const v2Intent = createV2Intent();
+            const normalized = normalizeV2Intent(v2Intent);
+            assert.equal(isNormalizedFromV2(normalized), true);
+        });
+        it('should return true for normalized v2 verifications', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.equal(isNormalizedFromV2(normalized), true);
+        });
+        it('should return false for native v3 data without _originalVersion', () => {
+            const nativeV3 = { _originalVersion: undefined };
+            assert.equal(isNormalizedFromV2(nativeV3), false);
+        });
+        it('should return false for data without _originalVersion property', () => {
+            const noOriginalVersion = {};
+            assert.equal(isNormalizedFromV2(noOriginalVersion), false);
+        });
+    });
+    describe('type safety', () => {
+        it('normalizeV2Deposit should return V3DepositData type', () => {
+            const v2Deposit = createV2Deposit();
+            const normalized = normalizeV2Deposit(v2Deposit);
+            assert.ok(normalized);
+            assert.equal(normalized.version, 'v3');
+        });
+        it('normalizeV2Intent should return V3IntentData type', () => {
+            const v2Intent = createV2Intent();
+            const normalized = normalizeV2Intent(v2Intent);
+            assert.ok(normalized);
+            assert.strictEqual(normalized.v2Currency, null);
+        });
+        it('normalizeV2Verification should return V3AttestationData type', () => {
+            const v2Verification = createV2Verification();
+            const normalized = normalizeV2Verification(v2Verification);
+            assert.ok(normalized);
+            assert.equal(normalized._originalVersion, 'v2');
+        });
+    });
+});

package/dist/src/participants.d.ts

@@ -1,7 +1,22 @@
 /**
- * Generate a participantId from chainId and address using the same logic as the indexer
- * @param chainId - The chain ID
- * @param address - The address
- * @returns The participant ID
+ * @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/src/participants.js

@@ -1,9 +1,24 @@
+/**
+ * @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 participantId from chainId and address using the same logic as the indexer
- * @param chainId - The chain ID
- * @param address - The address
- * @returns The participant ID
+ * 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([