@provex/utils 1.0.16 → 1.2.3

package/dist/src/peer-types.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Peer protocol types for attestation and proof verification.
+ *
+ * This module defines the type system for the V3 attestation flow, including:
+ * - Notarized proofs from the PeerAuth browser extension
+ * - Attestation requests/responses from the peer attestation service
+ * - EIP-712 typed data structures for on-chain verification
+ * - Payment proof encoding for the UnifiedPaymentVerifier contract
+ *
+ * @remarks
+ * **V3 Attestation Flow:**
+ * 1. Buyer generates zkTLS proof via PeerAuth extension (NotarizedProofData)
+ * 2. Proof + intent data sent to attestation service (V3AttestationRequest)
+ * 3. Service validates and returns EIP-712 signed attestation (V3AttestationResponse)
+ * 4. Attestation encoded as paymentProof bytes (encodeV3PaymentProof)
+ * 5. Buyer calls fulfillIntent() with encoded proof
+ *
+ * **Type Aliases:**
+ * For cleaner imports, V3-prefixed types have unprefixed aliases:
+ * - AttestationOptions = V3AttestationOptions
+ * - AttestationResponse = V3AttestationResponse
+ * - IntentData = V3IntentData
+ *
+ * @see {@link intent} for intent data structures
+ * @see {@link payment} for provider definitions
+ */
+import { encodeAbiParameters, decodeAbiParameters, keccak256, encodePacked } from "viem";
+// ============================================================================
+// V3 Payment Proof Encoding
+// ============================================================================
+/**
+ * ABI parameter definition for the V3 payment proof struct.
+ *
+ * IMPORTANT: The struct must be wrapped in an outer tuple to match the peer encoding.
+ * This causes ABI encoding to add an offset prefix (0x20) at the start.
+ *
+ * Structure:
+ * - Outer tuple wrapper (adds 0x20 offset prefix)
+ *   - PaymentAttestation tuple (intentHash, releaseAmount, dataHash)
+ *   - signatures[] array of EIP-712 signatures
+ *   - encodedPaymentDetails bytes
+ *   - metadata bytes
+ *   - attestorAddresses[] array of signer addresses
+ */
+const V3_PAYMENT_PROOF_ABI = [
+    {
+        type: 'tuple',
+        components: [
+            {
+                type: 'tuple',
+                name: 'attestation',
+                components: [
+                    { name: 'intentHash', type: 'bytes32' },
+                    { name: 'releaseAmount', type: 'uint256' },
+                    { name: 'dataHash', type: 'bytes32' }
+                ]
+            },
+            { type: 'bytes[]', name: 'signatures' },
+            { type: 'bytes', name: 'encodedPaymentDetails' },
+            { type: 'bytes', name: 'metadata' },
+            { type: 'address[]', name: 'attestorAddresses' }
+        ]
+    }
+];
+/**
+ * Encodes a V3 attestation response into the paymentProof bytes format
+ * expected by the UnifiedPaymentVerifier contract's fulfillIntent function.
+ *
+ * The encoded struct contains (wrapped in outer tuple for offset prefix):
+ * - PaymentAttestation: { intentHash, releaseAmount, dataHash }
+ * - signatures: [signature] (array with the EIP-712 signature)
+ * - encodedPaymentDetails: payment details for on-chain verification
+ * - metadata: additional metadata bytes
+ * - attestorAddresses: [signer] (array with the attestor address)
+ *
+ * @param attestation - The V3AttestationResponseObject from the attestation service
+ * @returns ABI-encoded bytes to pass as paymentProof in fulfillIntent
+ */
+export function encodeV3PaymentProof(attestation) {
+    return encodeAbiParameters(V3_PAYMENT_PROOF_ABI, [
+        {
+            attestation: {
+                intentHash: attestation.typedDataValue.intentHash,
+                releaseAmount: BigInt(attestation.typedDataValue.releaseAmount),
+                dataHash: attestation.typedDataValue.dataHash
+            },
+            signatures: [attestation.signature],
+            encodedPaymentDetails: attestation.encodedPaymentDetails,
+            metadata: attestation.metadata,
+            attestorAddresses: [attestation.signer]
+        }
+    ]);
+}
+/**
+ * Extracts the Reclaim attestor address from the attestation proofInput.
+ * This is needed for the verificationData field in fulfillIntent.
+ *
+ * @param attestation - The V3AttestationResponseObject from the attestation service
+ * @returns The Reclaim attestor address as Hex, or null if not found
+ */
+export function extractReclaimAttestorAddress(attestation) {
+    try {
+        const proofInput = JSON.parse(attestation.proofInput);
+        const proofs = JSON.parse(proofInput.proof);
+        if (Array.isArray(proofs) && proofs.length > 0) {
+            const attestorAddress = proofs[0]?.signatures?.attestorAddress;
+            if (attestorAddress && typeof attestorAddress === 'string') {
+                return attestorAddress;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extracts the nullifier from a V3 attestation response.
+ *
+ * The nullifier is NOT directly stored in `encodedPaymentDetails`. Instead, it's derived
+ * from `paymentMethod` and `paymentId` using:
+ * `keccak256(abi.encodePacked(paymentMethod, paymentId))`
+ *
+ * The `encodedPaymentDetails` contains a tuple of `(PaymentDetails, IntentSnapshot)`.
+ * This function decodes the PaymentDetails struct to extract paymentMethod and paymentId,
+ * then derives the nullifier.
+ *
+ * @param attestation - The V3AttestationResponseObject from the attestation service
+ * @returns The derived nullifier as Hex, or null if extraction fails
+ */
+export function extractNullifier(attestation) {
+    try {
+        // Decode encodedPaymentDetails as (PaymentDetails, IntentSnapshot) tuple
+        // PaymentDetails struct: { paymentMethod, payeeId, amount, currency, timestamp, paymentId }
+        // IntentSnapshot struct: { paymentMethod, currency, payeeId, conversionRate, timestamp, unknown }
+        const decoded = decodeAbiParameters([
+            {
+                type: 'tuple',
+                components: [
+                    { type: 'bytes32', name: 'paymentMethod' },
+                    { type: 'bytes32', name: 'payeeId' },
+                    { type: 'uint256', name: 'amount' },
+                    { type: 'bytes32', name: 'currency' },
+                    { type: 'uint256', name: 'timestamp' },
+                    { type: 'bytes32', name: 'paymentId' },
+                ],
+            },
+            {
+                type: 'tuple',
+                components: [
+                    { type: 'bytes32', name: 'paymentMethod' },
+                    { type: 'bytes32', name: 'currency' },
+                    { type: 'bytes32', name: 'payeeId' },
+                    { type: 'uint256', name: 'conversionRate' },
+                    { type: 'uint256', name: 'timestamp' },
+                    { type: 'uint256', name: 'unknown' },
+                ],
+            },
+        ], attestation.encodedPaymentDetails);
+        const paymentDetails = decoded[0];
+        // Derive nullifier: keccak256(abi.encodePacked(paymentMethod, paymentId))
+        const nullifier = keccak256(encodePacked(['bytes32', 'bytes32'], [paymentDetails.paymentMethod, paymentDetails.paymentId]));
+        return nullifier;
+    }
+    catch (error) {
+        console.error('Failed to extract nullifier:', error);
+        return null;
+    }
+}

package/dist/src/profit.d.ts

@@ -1,20 +1,41 @@
+/**
+ * @fileoverview Profit calculation utilities for market maker analytics.
+ *
+ * Calculates the profit/loss on fulfilled intents by comparing the token
+ * amount received against the expected amount at a 1:1 fiat:token rate.
+ *
+ * @remarks
+ * This is most meaningful for USD where $1 ≈ 1 USDC. For other currencies,
+ * the calculation shows the mathematical difference assuming 1:1 parity,
+ * which may not reflect actual profit in local currency terms.
+ */
 import type { ChainId } from "./chain.js";
-/** BigIntish type */
+/**
+ * Flexible bigint input type that accepts string, bigint, or number.
+ */
 export type BigIntish = string | bigint | number;
-/** Profit calculation input */
+/**
+ * Input parameters for profit calculation on a single intent.
+ */
 export interface ProfitCalculationInput {
+    /** Token amount received in base units (e.g., 6 decimals for USDC) */
     amount: BigIntish;
+    /** Chain ID for token decimal lookup */
     chainId: ChainId;
+    /** Conversion rate at which the exchange occurred */
     conversionRate: {
+        /** Rate value with 18 decimals (1e18 = 1.0) */
         value: BigIntish;
+        /** Currency contract ID (keccak256 hash) */
         currency: string;
     };
 }
 /**
  * Calculate the profit of an intent fulfilled event
- * @param param0.amount - The amount
- * @param param0.conversionRate - The conversion rate
- * @returns The profit
+ * @param param0.amount - The fiat amount in currency base units (e.g., cents for USD)
+ * @param param0.conversionRate - The conversion rate (tokens per fiat unit, scaled by 10^18)
+ * @param param0.chainId - The chain ID to get the default token
+ * @returns The profit in token base units, or null if not calculable
  */
 export declare const calculateProfit: ({ amount: amountInput, conversionRate, chainId, }: ProfitCalculationInput) => bigint | null;
 /**

package/dist/src/profit.js

@@ -1,22 +1,45 @@
+/**
+ * @fileoverview Profit calculation utilities for market maker analytics.
+ *
+ * Calculates the profit/loss on fulfilled intents by comparing the token
+ * amount received against the expected amount at a 1:1 fiat:token rate.
+ *
+ * @remarks
+ * This is most meaningful for USD where $1 ≈ 1 USDC. For other currencies,
+ * the calculation shows the mathematical difference assuming 1:1 parity,
+ * which may not reflect actual profit in local currency terms.
+ */
 import { getCurrencyByContractId } from "./currencies.js";
 import { getDefaultToken } from "./tokens.js";
 /**
  * Calculate the profit of an intent fulfilled event
- * @param param0.amount - The amount
- * @param param0.conversionRate - The conversion rate
- * @returns The profit
+ * @param param0.amount - The fiat amount in currency base units (e.g., cents for USD)
+ * @param param0.conversionRate - The conversion rate (tokens per fiat unit, scaled by 10^18)
+ * @param param0.chainId - The chain ID to get the default token
+ * @returns The profit in token base units, or null if not calculable
  */
 export const calculateProfit = ({ amount: amountInput, conversionRate, chainId, }) => {
     const rate = BigInt(conversionRate.value);
     const amount = BigInt(amountInput);
-    const valueReceived = amount * rate / 10n ** 18n;
     const currency = getCurrencyByContractId(conversionRate.currency);
     const inputTokenInfo = getDefaultToken(chainId);
-    const isOneForOne = currency.ticker === 'USD';
-    if (inputTokenInfo && isOneForOne) {
-        return valueReceived - amount;
+    if (!inputTokenInfo || !currency) {
+        return null;
     }
-    return null;
+    // Calculate expected token amount based on fiat amount and conversion rate
+    // valueReceived = (fiat_amount * rate) / 10^18, gives us token amount in token base units
+    const valueReceived = amount * rate / 10n ** 18n;
+    // Scale the fiat amount to match token decimals for comparison
+    // e.g., $100 USD (10000 in 2 decimals) -> 100000000 in 6 decimals for USDC
+    // e.g., €100 EUR (10000 in 2 decimals) -> 100000000 in 6 decimals for USDC
+    const decimalDiff = inputTokenInfo.decimals - currency.decimals;
+    const amountScaled = decimalDiff >= 0
+        ? amount * 10n ** BigInt(decimalDiff)
+        : amount / 10n ** BigInt(-decimalDiff);
+    // Profit = what we received - what we expected for 1:1 fiat:token exchange
+    // Note: This is most meaningful for USD where $1 ≈ 1 USDC
+    // For other currencies, this shows the mathematical difference assuming 1:1
+    return valueReceived - amountScaled;
 };
 /**
  * Calculate the profits for a list of inputs

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

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

package/dist/src/profit.test.js

@@ -0,0 +1,315 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { base, pulsechain } from 'viem/chains';
+import { calculateProfit, calculateProfits } from './profit.js';
+import { SUPPORTED_CURRENCIES } from './currencies.js';
+describe('profit', () => {
+    // Constants for testing
+    const USD_CONTRACT_ID = SUPPORTED_CURRENCIES.USD.contractId;
+    const EUR_CONTRACT_ID = SUPPORTED_CURRENCIES.EUR.contractId;
+    const JPY_CONTRACT_ID = SUPPORTED_CURRENCIES.JPY.contractId;
+    /**
+     * Rate calculation for USD/USDC:
+     * - USD has 2 decimals (amount in cents)
+     * - USDC has 6 decimals
+     * - Rate is scaled by 10^18
+     *
+     * For a 1:1 USD/USDC rate:
+     * - $100 USD = 10000 cents
+     * - Expected: 100 USDC = 100000000 (in 6 decimals)
+     * - valueReceived = amount * rate / 10^18
+     * - 100000000 = 10000 * rate / 10^18
+     * - rate = 100000000 * 10^18 / 10000 = 10^22
+     *
+     * This accounts for decimal difference (6-2=4 extra zeros)
+     */
+    // 1.0 rate that produces 1:1 fiat:token (accounts for 4 decimal difference USD->USDC)
+    const RATE_1_0 = 10n ** 22n;
+    // 1.05 rate (5% premium)
+    const RATE_1_05 = (10n ** 22n * 105n) / 100n;
+    // 0.95 rate (5% discount)
+    const RATE_0_95 = (10n ** 22n * 95n) / 100n;
+    describe('calculateProfit', () => {
+        it('should return 0 profit for 1:1 rate with USD', () => {
+            // $100 USD (10000 in 2 decimals) at 1.0 rate
+            const input = {
+                amount: 10000n, // $100 in cents
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_0,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            // At 1:1 rate, profit should be 0
+            assert.equal(profit, 0n);
+        });
+        it('should return positive profit for rate above 1.0', () => {
+            // $100 USD at 1.05 rate means receiving 105 USDC
+            const input = {
+                amount: 10000n, // $100 in cents
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_05,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            assert.ok(profit > 0n, 'Profit should be positive for rate > 1.0');
+            // Expected: received (100 * 1.05 = 105 USDC) - expected (100 USDC) = 5 USDC = 5000000 in 6 decimals
+            assert.equal(profit, 5000000n);
+        });
+        it('should return negative profit (loss) for rate below 1.0', () => {
+            // $100 USD at 0.95 rate means receiving 95 USDC
+            const input = {
+                amount: 10000n, // $100 in cents
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_0_95,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            assert.ok(profit < 0n, 'Profit should be negative for rate < 1.0');
+            // Expected: received (100 * 0.95 = 95 USDC) - expected (100 USDC) = -5 USDC = -5000000 in 6 decimals
+            assert.equal(profit, -5000000n);
+        });
+        it('should work with Pulsechain', () => {
+            const input = {
+                amount: 10000n,
+                chainId: pulsechain.id,
+                conversionRate: {
+                    value: RATE_1_0,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            assert.equal(profit, 0n);
+        });
+        it('should handle EUR currency', () => {
+            // EUR also has 2 decimals like USD
+            const input = {
+                amount: 10000n, // €100 in cents
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_0, // Same rate logic for EUR
+                    currency: EUR_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            // At 1:1 rate, profit should be 0
+            assert.equal(profit, 0n);
+        });
+        it('should handle JPY (0 decimal currency)', () => {
+            // JPY has 0 decimals, USDC has 6
+            // For 1:1 rate: ¥15000 -> 15000 USDC
+            // Rate = 15000 * 10^6 * 10^18 / 15000 = 10^24 (accounts for 6 decimal difference)
+            const JPY_RATE_1_0 = 10n ** 24n;
+            const input = {
+                amount: 15000n, // ¥15000
+                chainId: base.id,
+                conversionRate: {
+                    value: JPY_RATE_1_0,
+                    currency: JPY_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            assert.equal(profit, 0n);
+        });
+        it('should accept string amount', () => {
+            const input = {
+                amount: '10000',
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_0,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+        });
+        it('should accept number amount', () => {
+            const input = {
+                amount: 10000,
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_0,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+        });
+        it('should accept string rate', () => {
+            const input = {
+                amount: 10000n,
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_0.toString(),
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+        });
+        it('should return null for invalid currency', () => {
+            const input = {
+                amount: 10000n,
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_0,
+                    currency: '0x' + '0'.repeat(64), // Invalid currency contract ID
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.equal(profit, null);
+        });
+        it('should return null for invalid chainId', () => {
+            const input = {
+                amount: 10000n,
+                chainId: 99999, // Invalid chain
+                conversionRate: {
+                    value: RATE_1_0,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.equal(profit, null);
+        });
+        it('should handle large amounts', () => {
+            // $1,000,000 USD
+            const input = {
+                amount: 100000000n, // $1M in cents
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_05,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            // 5% profit on $1M = $50,000 = 50000000000 in 6 decimals
+            assert.equal(profit, 50000000000n);
+        });
+        it('should handle small amounts', () => {
+            // $0.01 USD (1 cent)
+            const input = {
+                amount: 1n,
+                chainId: base.id,
+                conversionRate: {
+                    value: RATE_1_05,
+                    currency: USD_CONTRACT_ID,
+                },
+            };
+            const profit = calculateProfit(input);
+            assert.ok(profit !== null, 'Profit should not be null');
+            // Small amount should still calculate correctly
+            assert.ok(typeof profit === 'bigint');
+        });
+    });
+    describe('calculateProfits', () => {
+        it('should calculate total profit for multiple inputs', () => {
+            const inputs = [
+                {
+                    amount: 10000n, // $100
+                    chainId: base.id,
+                    conversionRate: { value: RATE_1_05, currency: USD_CONTRACT_ID },
+                },
+                {
+                    amount: 20000n, // $200
+                    chainId: base.id,
+                    conversionRate: { value: RATE_1_05, currency: USD_CONTRACT_ID },
+                },
+            ];
+            const result = calculateProfits(inputs);
+            assert.equal(result.nullAmounts, 0);
+            // $100 * 5% + $200 * 5% = $5 + $10 = $15 = 15000000 in 6 decimals
+            assert.equal(result.profit, 15000000n);
+        });
+        it('should handle mix of positive and negative profits', () => {
+            const inputs = [
+                {
+                    amount: 10000n,
+                    chainId: base.id,
+                    conversionRate: { value: RATE_1_05, currency: USD_CONTRACT_ID }, // +$5
+                },
+                {
+                    amount: 10000n,
+                    chainId: base.id,
+                    conversionRate: { value: RATE_0_95, currency: USD_CONTRACT_ID }, // -$5
+                },
+            ];
+            const result = calculateProfits(inputs);
+            assert.equal(result.nullAmounts, 0);
+            // +5 + -5 = 0
+            assert.equal(result.profit, 0n);
+        });
+        it('should count null amounts', () => {
+            const inputs = [
+                {
+                    amount: 10000n,
+                    chainId: base.id,
+                    conversionRate: { value: RATE_1_0, currency: USD_CONTRACT_ID },
+                },
+                {
+                    amount: 10000n,
+                    chainId: 99999, // Invalid - will return null
+                    conversionRate: { value: RATE_1_0, currency: USD_CONTRACT_ID },
+                },
+                {
+                    amount: 10000n,
+                    chainId: base.id,
+                    conversionRate: { value: RATE_1_0, currency: '0x' + '0'.repeat(64) }, // Invalid currency
+                },
+            ];
+            const result = calculateProfits(inputs);
+            assert.equal(result.nullAmounts, 2);
+        });
+        it('should return 0 profit and 0 nullAmounts for empty array', () => {
+            const result = calculateProfits([]);
+            assert.equal(result.profit, 0n);
+            assert.equal(result.nullAmounts, 0);
+        });
+        it('should handle all null results', () => {
+            const inputs = [
+                {
+                    amount: 10000n,
+                    chainId: 99999,
+                    conversionRate: { value: RATE_1_0, currency: USD_CONTRACT_ID },
+                },
+                {
+                    amount: 10000n,
+                    chainId: 99998,
+                    conversionRate: { value: RATE_1_0, currency: USD_CONTRACT_ID },
+                },
+            ];
+            const result = calculateProfits(inputs);
+            assert.equal(result.nullAmounts, 2);
+            assert.equal(result.profit, 0n);
+        });
+        it('should work with mixed chains', () => {
+            const inputs = [
+                {
+                    amount: 10000n,
+                    chainId: base.id,
+                    conversionRate: { value: RATE_1_05, currency: USD_CONTRACT_ID },
+                },
+                {
+                    amount: 10000n,
+                    chainId: pulsechain.id,
+                    conversionRate: { value: RATE_1_05, currency: USD_CONTRACT_ID },
+                },
+            ];
+            const result = calculateProfits(inputs);
+            assert.equal(result.nullAmounts, 0);
+            // Both should have 5% profit = $5 each = $10 total
+            assert.equal(result.profit, 10000000n);
+        });
+    });
+});