@provex/utils 1.2.3 → 1.2.4

package/dist/src/zkp2p-types.d.ts

@@ -1,317 +0,0 @@
-/**
- * @fileoverview ZKP2P 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 zkp2p 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 { type Hex } from "viem";
-import type { ProviderKey, SubProviderKey, ValidationDepositData } from "./payment.js";
-/**
- * Options for validating a depositor's payee details with the zkp2p gating service.
- */
-export type ValidationOptions = {
-    providerKey: ProviderKey;
-    telegramHandle: string;
-    providerId: string;
-};
-export type Zkp2pResponse<T> = {
-    success: boolean;
-    message: string;
-    statusCode: number;
-    responseObject: T;
-};
-export type CreateResponse = {
-    id: number;
-    processorName: string;
-    depositData: string;
-    hashedOnchainId: Hex;
-    createdAt: string;
-};
-export type PayeeDetails = {
-    id: number;
-    processorName: string;
-    createdAt: string;
-    hashedOnchainId: Hex;
-    depositData: ValidationDepositData;
-};
-export type IntentValidationOptions = {
-    processorName: ProviderKey;
-    depositId: string;
-    /** Token amount (was tokenAmount, renamed to amount for v2 API) */
-    amount: string;
-    payeeDetails: Hex;
-    toAddress: Hex;
-    /** Payment method bytes32 hash */
-    paymentMethod: Hex;
-    /** Fiat currency bytes32 hash */
-    fiatCurrency: Hex;
-    /** Conversion rate as string */
-    conversionRate: string;
-    chainId: string;
-    /** Orchestrator contract address */
-    orchestratorAddress: Hex;
-    /** Escrow contract address */
-    escrowAddress: Hex;
-    /** Optional sub-provider for providers like Zelle that have multiple banks (e.g., 'zelle-chase', 'zelle-bofa') */
-    subProvider?: SubProviderKey;
-};
-export type IntentValidation = {
-    signedIntent: Hex;
-    intentData: {
-        depositId: string;
-        tokenAmount: string;
-        recipientAddress: Hex;
-        verifierAddress: Hex;
-        currencyCodeHash: Hex;
-        gatingServiceSignature: Hex;
-    };
-    depositData: ValidationDepositData;
-};
-/**
- * Notarized proof from PeerAuth extension.
- * This is the zkTLS proof that proves a payment transaction occurred.
- * Mirrors the NotarizedProof type from @provex/extension-react.
- */
-export type NotarizedProofData = {
-    claim: {
-        context: string;
-        epoch: number;
-        identifier: Hex;
-        owner: Hex;
-        parameters: string;
-        provider: string;
-        timestampS: number;
-    };
-    signatures: {
-        attestorAddress: Hex;
-        claimSignature: Record<number, number>;
-        resultSignature: Record<number, number>;
-    };
-};
-/**
- * Intent data required by zkp2p attestation service.
- * This contains all the on-chain intent parameters needed to verify
- * that the off-chain payment matches the signaled intent.
- */
-export type V3IntentData = {
-    /** The intent hash from signalIntent */
-    intentHash: Hex;
-    /** Token amount in smallest unit (e.g., USDC with 6 decimals) */
-    amount: string;
-    /** Intent timestamp in milliseconds */
-    timestampMs: string;
-    /** Payment method bytes32 hash */
-    paymentMethod: Hex;
-    /** Fiat currency bytes32 hash */
-    fiatCurrency: Hex;
-    /** Conversion rate as string (scaled by 1e18) */
-    conversionRate: string;
-    /** Payee details hash */
-    payeeDetails: Hex;
-    /** Optional timestamp buffer in milliseconds (default: 3000) */
-    timestampBufferMs?: string;
-};
-/**
- * V3 attestation request sent to zkp2p attestation service.
- * The service validates Reclaim proofs and returns an EIP-712 signed attestation.
- *
- * Endpoint: POST /verify/{platform}/{action_type}
- * Example: POST /verify/chase/transfer_zelle
- */
-export type V3AttestationRequest = {
-    /** Type of proof being submitted */
-    proofType: 'reclaim';
-    /** JSON stringified array of Reclaim proofs */
-    proof: string;
-    /** Chain ID (e.g., 8453 for Base) */
-    chainId: number;
-    /** UnifiedPaymentVerifier contract address */
-    verifyingContract: Hex;
-    /** Intent data from on-chain signalIntent */
-    intent: V3IntentData;
-};
-/**
- * Options passed to the v3 getAttestation API.
- * These are transformed into V3AttestationRequest format.
- */
-export type V3AttestationOptions = {
-    /** Platform for the attestation service path (e.g., 'chase') */
-    platform: string;
-    /** Action type for the attestation service path (e.g., 'transfer_zelle') */
-    actionType: string;
-    /** Chain ID */
-    chainId: number;
-    /** UnifiedPaymentVerifier contract address */
-    verifyingContract: Hex;
-    /** Array of Reclaim proofs from PeerAuth */
-    proofs: NotarizedProofData[];
-    /** Intent data from on-chain intent */
-    intent: V3IntentData;
-};
-/**
- * EIP-712 typed data specification from attestation service.
- */
-export type V3TypedDataSpec = {
-    primaryType: string;
-    types: Record<string, Array<{
-        name: string;
-        type: string;
-    }>>;
-};
-/**
- * EIP-712 typed data values from attestation service.
- * These are the actual values that were signed.
- */
-export type V3TypedDataValue = {
-    intentHash: Hex;
-    releaseAmount: string;
-    dataHash: Hex;
-};
-/**
- * Response object from zkp2p attestation service.
- * Contains the EIP-712 signed attestation for on-chain verification.
- */
-export type V3AttestationResponseObject = {
-    /** EIP-712 signature to submit to fulfillIntent as paymentProof */
-    signature: Hex;
-    /** Address of the attestation signer */
-    signer: Hex;
-    /** EIP-712 domain separator */
-    domainSeparator: Hex;
-    /** EIP-712 type hash */
-    typeHash: Hex;
-    /** EIP-712 type specification */
-    typedDataSpec: V3TypedDataSpec;
-    /** The actual values that were signed */
-    typedDataValue: V3TypedDataValue;
-    /** ABI-encoded payment details for on-chain verification */
-    encodedPaymentDetails: Hex;
-    /** Additional metadata */
-    metadata: Hex;
-    /** Original proof input (for debugging) */
-    proofInput: string;
-    /** Platform used (e.g., 'chase') */
-    platform: string;
-    /** Action type (e.g., 'transfer_zelle') */
-    actionType: string;
-};
-/**
- * Full response from zkp2p attestation service.
- * Wrapped in standard Zkp2pResponse format.
- */
-export type V3AttestationResponse = Zkp2pResponse<V3AttestationResponseObject>;
-/**
- * @deprecated Use V3AttestationResponseObject for the inner response data
- */
-export type V3PaymentAttestation = {
-    depositor: Hex;
-    depositId: string;
-    amount: string;
-    paymentId: string;
-    timestamp: number;
-};
-export type V3IntentSignalOptions = {
-    depositId: string;
-    amount: string;
-    attestation: V3AttestationResponse;
-    chainId: number;
-};
-export type V3IntentFulfillOptions = {
-    intentId: string;
-    chainId: number;
-};
-/**
- * EIP-712 domain separator fields.
- * Used for typed structured data hashing and signing per EIP-712.
- * @see https://eips.ethereum.org/EIPS/eip-712
- */
-export type EIP712Domain = {
-    /** Human-readable name of the signing domain (e.g., "ZKP2P") */
-    name: string;
-    /** Version of the signing domain (e.g., "1") */
-    version: string;
-    /** Chain ID of the network where the contract is deployed */
-    chainId: number;
-    /** Address of the contract that will verify the signature */
-    verifyingContract: Hex;
-};
-/**
- * A payment attestation with its EIP-712 signature.
- * This is the complete attestation package sent to the contract for verification.
- */
-export type SignedAttestation = {
-    /** The payment attestation data */
-    attestation: V3PaymentAttestation;
-    /** EIP-712 typed signature of the attestation */
-    signature: Hex;
-};
-/**
- * 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 declare function encodeV3PaymentProof(attestation: V3AttestationResponseObject): Hex;
-/**
- * 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 declare function extractReclaimAttestorAddress(attestation: V3AttestationResponseObject): Hex | 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 declare function extractNullifier(attestation: V3AttestationResponseObject): Hex | null;
-/** @alias V3AttestationOptions */
-export type AttestationOptions = V3AttestationOptions;
-/** @alias V3AttestationRequest */
-export type AttestationRequest = V3AttestationRequest;
-/** @alias V3AttestationResponse */
-export type AttestationResponse = V3AttestationResponse;
-/** @alias V3AttestationResponseObject */
-export type AttestationResponseObject = V3AttestationResponseObject;
-/** @alias V3PaymentAttestation - @deprecated use V3AttestationResponseObject */
-export type PaymentAttestation = V3PaymentAttestation;
-/** @alias V3IntentData */
-export type IntentData = V3IntentData;

package/dist/src/zkp2p-types.js

@@ -1,169 +0,0 @@
-/**
- * @fileoverview ZKP2P 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 zkp2p 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 zkp2p's 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;
-    }
-}