@provex/utils 1.0.16 → 1.2.3

package/dist/src/contracts.d.ts

@@ -1,30 +1,206 @@
+/**
+ * @fileoverview Contract addresses and configuration for the Peer protocol.
+ *
+ * This module is the single source of truth for all deployed contract addresses
+ * across supported chains (Base, Pulsechain) and protocol versions (V2, V3).
+ *
+ * @remarks
+ * **Version Strategy:**
+ * - V3 is the active version for all new transactions on both Base and Pulsechain
+ * - V2 contracts remain available for historical data access only
+ *
+ * **Contract Architecture (V3):**
+ * - Escrow: Holds depositor funds, manages deposit lifecycle
+ * - Orchestrator: Coordinates intents across escrows (read via escrow.orchestrator())
+ * - UnifiedPaymentVerifier: Verifies zkTLS proofs for all payment methods
+ * - PaymentVerifierRegistry: Maps payment method IDs to verifier contracts
+ *
+ * **Contract Architecture (V2 - Deprecated):**
+ * - Escrow: Simpler escrow without orchestrator
+ * - Per-provider verifiers: Separate contracts for Venmo, Zelle, etc.
+ *
+ * @see {@link chain} for chain configuration
+ * @see {@link abis} for contract ABIs
+ */
 import { type Hex } from 'viem';
 import type { ChainId } from './chain.js';
 /**
- * Contracts for the app
+ * Contract type definitions for the app.
  */
-export type Contracts = {
+type NonEmptyArray<T> = [T, ...T[]];
+export type V2Contracts = {
     gatingService: Hex;
     usdc: Hex;
-    escrow: Hex[];
-    venmoReclaimVerifier: Hex[];
-    revolutReclaimVerifier: Hex[];
-    cashappReclaimVerifier: Hex[];
-    wiseReclaimVerifier: Hex[];
-    mercadopagoReclaimVerifier: Hex[];
-    zelleBaseVerifier: Hex[];
-    zelleBoAReclaimVerifier: Hex[];
-    zelleChaseReclaimVerifier: Hex[];
-    zelleCitiReclaimVerifier: Hex[];
-    paypalReclaimVerifier: Hex[];
-    monzoReclaimVerifier: Hex[];
+    escrow: NonEmptyArray<Hex>;
+    venmoReclaimVerifier: NonEmptyArray<Hex>;
+    revolutReclaimVerifier: NonEmptyArray<Hex>;
+    cashappReclaimVerifier: NonEmptyArray<Hex>;
+    wiseReclaimVerifier: NonEmptyArray<Hex>;
+    mercadopagoReclaimVerifier: NonEmptyArray<Hex>;
+    zelleBaseVerifier: NonEmptyArray<Hex>;
+    zelleBoAReclaimVerifier: NonEmptyArray<Hex>;
+    zelleChaseReclaimVerifier: NonEmptyArray<Hex>;
+    zelleCitiReclaimVerifier: NonEmptyArray<Hex>;
+    paypalReclaimVerifier: NonEmptyArray<Hex>;
+    monzoReclaimVerifier: NonEmptyArray<Hex>;
+};
+export type V3Contracts = {
+    usdc: Hex;
+    gatingService: Hex;
+    escrow: NonEmptyArray<Hex>;
+    unifiedPaymentVerifier: NonEmptyArray<Hex>;
 };
+export type ContractKey = keyof V2Contracts | keyof V3Contracts;
 export declare const reclaimSigners: {
-    readonly zkp2pWitnessSigner: "0x0636c417755E3ae25C6c166D181c0607F4C572A3";
+    readonly peerWitnessSigner: "0x0636c417755E3ae25C6c166D181c0607F4C572A3";
     readonly reclaimWitnessSigner: "0x244897572368eadf65bfbc5aec98d8e5443a9072";
 };
-export declare const baseContracts: Contracts;
-export declare const pulsechainContracts: Contracts;
-export declare const contractsByChainId: Map<number, Contracts>;
-export declare const getContracts: (chainId: ChainId) => Contracts | null;
-export declare const getLatestContract: (chainId: ChainId, key: keyof Contracts) => `0x${string}` | null;
+export declare const v2BaseContracts: V2Contracts;
+export declare const v2PulsechainContracts: V2Contracts;
+export declare const v3BaseContracts: V3Contracts;
+/**
+ * V3 contracts deployed to Pulsechain (Chain ID 369)
+ * Deployed: 2026-01-12
+ * Deployer: 0xC3c7e05D1BA19563693D891e5c38f0FC988A5d11
+ * MultiSig: 0x948eB6D3A08BEb29Dc1D08d09753862573A94122
+ */
+export declare const v3PulsechainContracts: V3Contracts;
+/**
+ * V3 Pulsechain protocol contract addresses - FOR REFERENCE ONLY
+ *
+ * DO NOT use these directly in code. The orchestrator and paymentVerifierRegistry
+ * addresses should be read dynamically from the escrow contract at runtime.
+ * See ponder.config.ts `callEach()` for the correct pattern.
+ */
+export declare const V3_PULSECHAIN_DEPLOYMENT_REFERENCE: {
+    readonly orchestrator: "0x742d48639F44701Bff5A0A441600AD6DA4A3b080";
+    readonly paymentVerifierRegistry: "0x6a4fF1950Be05995dEe75920cf27CD8FEbB6597A";
+    readonly protocolViewer: "0x31dD72E1a385F98F4e6A94330c8121d2Ed62Ab72";
+    readonly escrowRegistry: "0x7238d0B6a28a3a6e3DfCd281D7Cb9b3250B30EA6";
+    readonly postIntentHookRegistry: "0x94F510fa245843Ff5eDa2d18479FE63ac51F8fE6";
+    readonly relayerRegistry: "0x689F82b4078aA07F443af9ae308534bD2Ff545D3";
+    readonly nullifierRegistry: "0x4AeA2288ec542963256b66D70EfddF4cB8754f82";
+    readonly simpleAttestationVerifier: "0x49DAd1f29a3FE2E4D90a59e6687d9f7A2836B4a8";
+};
+export declare const versions: {
+    readonly V2: "v2";
+    readonly V3: "v3";
+};
+export declare const versionKeys: ("v2" | "v3")[];
+export type Version = (typeof versionKeys)[number];
+/**
+ * Contract addresses organized by version and chain.
+ *
+ * @important v3 on Base is the active version for the buy/sell UI.
+ * v2 contracts are deprecated but remain for historical data access.
+ */
+export declare const contracts: {
+    v2: {
+        8453: V2Contracts;
+        369: V2Contracts;
+    };
+    v3: {
+        8453: V3Contracts;
+        369: V3Contracts;
+    };
+};
+/**
+ * Get contracts for a specific version and chain.
+ * @param version - The contract version (v2 or v3)
+ * @param chainId - The chain ID
+ * @returns The contracts for that version and chain, or null if not found
+ */
+export declare const getContracts: (version: Version, chainId: ChainId) => V2Contracts | V3Contracts;
+/**
+ * Get the latest deployed contract address for a given key.
+ *
+ * @important This function defaults to Base v3 contracts for the buy/sell UI.
+ * v2 contracts are deprecated for new transactions.
+ *
+ * When contracts are upgraded, the latest version is at the end of the array.
+ *
+ * @param chainId - The chain ID
+ * @param key - The contract key (e.g., 'escrow', 'usdc', 'unifiedPaymentVerifier')
+ * @param version - Optional version override for accessing historical v2 data
+ * @returns The contract address, or null if not found
+ *
+ * @example
+ * // Get Base v3 escrow (default for buy/sell UI)
+ * const escrow = getLatestContract(base.id, 'escrow')
+ *
+ * @example
+ * // Explicitly get v2 contract for historical data
+ * const v2Escrow = getLatestContract(pulsechain.id, 'escrow', 'v2')
+ */
+export declare const getLatestContract: (chainId: ChainId, key: ContractKey, version?: Version) => Hex | null;
+/**
+ * Represents a unique escrow location identified by version, chain, and address
+ */
+export type EscrowLocation = {
+    version: Version;
+    chainId: ChainId;
+    escrow: Hex;
+};
+/**
+ * Get all escrow contracts across all versions and chains.
+ * Returns a flat list of all escrow locations for querying deposits.
+ *
+ * @returns Array of escrow locations with version, chainId, and escrow address
+ *
+ * @example
+ * // Get all escrows to search for a deposit
+ * const escrows = getAllEscrowContracts()
+ * // [
+ * //   { version: 'v2', chainId: 8453, escrow: '0xCA38...' },
+ * //   { version: 'v2', chainId: 369, escrow: '0x2932...' },
+ * //   { version: 'v3', chainId: 8453, escrow: '0x2f12...' },
+ * // ]
+ */
+export declare function getAllEscrowContracts(): EscrowLocation[];
+/**
+ * Get all V3 escrow contracts across all chains.
+ * Used for cross-chain nullifier checking to prevent double-spending.
+ *
+ * @returns Array of V3 escrow locations with chainId and escrow address
+ *
+ * @example
+ * const v3Escrows = getAllV3EscrowContracts()
+ * // [
+ * //   { version: 'v3', chainId: 8453, escrow: '0x2f12...' },
+ * //   { version: 'v3', chainId: 369, escrow: '0x0B42...' },
+ * // ]
+ */
+export declare function getAllV3EscrowContracts(): EscrowLocation[];
+/**
+ * Get a short display label for an escrow address (first 6 + last 4 chars)
+ * @param escrow - The escrow address
+ * @returns Shortened address string
+ */
+export declare function shortenEscrowAddress(escrow: Hex): string;
+/**
+ * Get the version of an escrow contract by looking up its address.
+ *
+ * @param escrowAddress - The escrow contract address to look up
+ * @param chainId - Optional chain ID to narrow down the search
+ * @returns The escrow version ('v2' or 'v3'), or null if not found
+ *
+ * @example
+ * // Determine if escrow supports V3 features
+ * const version = getEscrowVersion(deposit.escrow, deposit.chainId)
+ * const isV3 = version === 'v3'
+ */
+export declare function getEscrowVersion(escrowAddress: Hex, chainId?: ChainId): Version | null;
+/**
+ * Check if an escrow address is a V3 contract.
+ * Convenience function for feature gating V3-only functionality.
+ *
+ * @param escrowAddress - The escrow contract address
+ * @param chainId - The chain ID
+ * @returns true if the escrow is V3, false otherwise
+ *
+ * @example
+ * // Gate V3-only features in UI
+ * const showRetainToggle = isV3Escrow(deposit.escrow, deposit.chainId) && isOwner
+ */
+export declare function isV3Escrow(escrowAddress: Hex, chainId: ChainId): boolean;
+export {};

package/dist/src/contracts.js

@@ -1,10 +1,34 @@
+/**
+ * @fileoverview Contract addresses and configuration for the Peer protocol.
+ *
+ * This module is the single source of truth for all deployed contract addresses
+ * across supported chains (Base, Pulsechain) and protocol versions (V2, V3).
+ *
+ * @remarks
+ * **Version Strategy:**
+ * - V3 is the active version for all new transactions on both Base and Pulsechain
+ * - V2 contracts remain available for historical data access only
+ *
+ * **Contract Architecture (V3):**
+ * - Escrow: Holds depositor funds, manages deposit lifecycle
+ * - Orchestrator: Coordinates intents across escrows (read via escrow.orchestrator())
+ * - UnifiedPaymentVerifier: Verifies zkTLS proofs for all payment methods
+ * - PaymentVerifierRegistry: Maps payment method IDs to verifier contracts
+ *
+ * **Contract Architecture (V2 - Deprecated):**
+ * - Escrow: Simpler escrow without orchestrator
+ * - Per-provider verifiers: Separate contracts for Venmo, Zelle, etc.
+ *
+ * @see {@link chain} for chain configuration
+ * @see {@link abis} for contract ABIs
+ */
 import { getAddress } from 'viem';
 import { base, pulsechain } from 'viem/chains';
 export const reclaimSigners = {
-    zkp2pWitnessSigner: '0x0636c417755E3ae25C6c166D181c0607F4C572A3',
+    peerWitnessSigner: '0x0636c417755E3ae25C6c166D181c0607F4C572A3',
     reclaimWitnessSigner: '0x244897572368eadf65bfbc5aec98d8e5443a9072',
 };
-export const baseContracts = {
+export const v2BaseContracts = {
     gatingService: getAddress('0x396D31055Db28C0C6f36e8b36f18FE7227248a97'),
     usdc: getAddress('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'),
     escrow: [getAddress('0xCA38607D85E8F6294Dc10728669605E6664C2D70')],
@@ -26,7 +50,7 @@ export const baseContracts = {
     paypalReclaimVerifier: [getAddress('0x03d17E9371C858072E171276979f6B44571C5DeA')],
     monzoReclaimVerifier: [getAddress('0x0dE46433bD251027f73eD8f28E01eF05DA36a2E0')],
 };
-export const pulsechainContracts = {
+export const v2PulsechainContracts = {
     gatingService: getAddress('0x4Bd6364FCC4D8A537aBfee33B16E959794fDf9Cf'),
     usdc: getAddress('0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07'),
     escrow: [getAddress('0x2932E08BFD212Ef0732257bDd6463BF55E9b97d7')],
@@ -43,22 +67,226 @@ export const pulsechainContracts = {
     zelleChaseReclaimVerifier: [getAddress('0xB0aA0a58959465bBCf0eCbD62A84B743A5435c99')],
     zelleCitiReclaimVerifier: [getAddress('0x5624E479924eBFb25B51F36e3FDaE605dADb448b')],
 };
-export const contractsByChainId = new Map([
-    [base.id, baseContracts],
-    [pulsechain.id, pulsechainContracts],
-]);
-export const getContracts = (chainId) => {
-    return contractsByChainId.get(chainId) ?? null;
+export const v3BaseContracts = {
+    usdc: getAddress('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'),
+    gatingService: getAddress('0x5106a86819ed6bb82c77ccbfc151250e1d369dba'),
+    escrow: [
+        getAddress('0x2f121CDDCA6d652f35e8B3E560f9760898888888'),
+        getAddress('0x777777779d229cdf3110e9de47943791c26300ef'),
+    ],
+    unifiedPaymentVerifier: [
+        getAddress('0x16b3e4a3CA36D3A4bCA281767f15C7ADeF4ab163'),
+        getAddress('0x46A58Dc65587D4D7B8198C6A25eEdf5b2535Da94'),
+    ],
+};
+/**
+ * V3 contracts deployed to Pulsechain (Chain ID 369)
+ * Deployed: 2026-01-12
+ * Deployer: 0xC3c7e05D1BA19563693D891e5c38f0FC988A5d11
+ * MultiSig: 0x948eB6D3A08BEb29Dc1D08d09753862573A94122
+ */
+export const v3PulsechainContracts = {
+    usdc: getAddress('0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07'),
+    gatingService: getAddress('0x4Bd6364FCC4D8A537aBfee33B16E959794fDf9Cf'),
+    escrow: [getAddress('0x0B42393d4DBA08892d339b32Cd3064248003f11a')],
+    unifiedPaymentVerifier: [getAddress('0x0e73181a60C6a58Eb9298bCf28781E1d46cd81Db')],
+};
+/**
+ * V3 Pulsechain protocol contract addresses - FOR REFERENCE ONLY
+ *
+ * DO NOT use these directly in code. The orchestrator and paymentVerifierRegistry
+ * addresses should be read dynamically from the escrow contract at runtime.
+ * See ponder.config.ts `callEach()` for the correct pattern.
+ */
+export const V3_PULSECHAIN_DEPLOYMENT_REFERENCE = {
+    orchestrator: '0x742d48639F44701Bff5A0A441600AD6DA4A3b080', // read via escrow.orchestrator()
+    paymentVerifierRegistry: '0x6a4fF1950Be05995dEe75920cf27CD8FEbB6597A', // read via escrow.paymentVerifierRegistry()
+    protocolViewer: '0x31dD72E1a385F98F4e6A94330c8121d2Ed62Ab72', // static registry
+    escrowRegistry: '0x7238d0B6a28a3a6e3DfCd281D7Cb9b3250B30EA6',
+    postIntentHookRegistry: '0x94F510fa245843Ff5eDa2d18479FE63ac51F8fE6',
+    relayerRegistry: '0x689F82b4078aA07F443af9ae308534bD2Ff545D3',
+    nullifierRegistry: '0x4AeA2288ec542963256b66D70EfddF4cB8754f82',
+    simpleAttestationVerifier: '0x49DAd1f29a3FE2E4D90a59e6687d9f7A2836B4a8',
+};
+export const versions = {
+    V2: 'v2', // Deprecated: Historical data only
+    V3: 'v3', // Active: Primary version for Base buy/sell UI
 };
-export const getLatestContract = (chainId, key) => {
-    const contracts = getContracts(chainId);
-    if (!contracts)
+export const versionKeys = Object.values(versions);
+/**
+ * Contract addresses organized by version and chain.
+ *
+ * @important v3 on Base is the active version for the buy/sell UI.
+ * v2 contracts are deprecated but remain for historical data access.
+ */
+export const contracts = {
+    v2: {
+        // Deprecated: Historical data only
+        [base.id]: v2BaseContracts,
+        [pulsechain.id]: v2PulsechainContracts,
+    },
+    v3: {
+        // Active: Primary version for buy/sell UI
+        [base.id]: v3BaseContracts,
+        [pulsechain.id]: v3PulsechainContracts,
+    },
+};
+/**
+ * Get the default version for a given chain.
+ *
+ * @important Both Base and Pulsechain now use v3 as the primary version.
+ * v2 contracts are deprecated for new transactions but remain available for historical data.
+ *
+ * @param chainId - The chain ID
+ * @returns The default contract version for the chain
+ *
+ * Defaults:
+ * - Base: v3 (active, used for all new transactions)
+ * - PulseChain: v3 (active, deployed 2026-01-12)
+ * - All others: v3
+ */
+const getDefaultVersion = (_chainId) => {
+    // Both Base and Pulsechain use v3 for all new transactions
+    return 'v3';
+};
+/**
+ * Get contracts for a specific version and chain.
+ * @param version - The contract version (v2 or v3)
+ * @param chainId - The chain ID
+ * @returns The contracts for that version and chain, or null if not found
+ */
+export const getContracts = (version, chainId) => {
+    return version === 'v2' ? contracts.v2[chainId] : contracts.v3[chainId];
+};
+/**
+ * Get the latest deployed contract address for a given key.
+ *
+ * @important This function defaults to Base v3 contracts for the buy/sell UI.
+ * v2 contracts are deprecated for new transactions.
+ *
+ * When contracts are upgraded, the latest version is at the end of the array.
+ *
+ * @param chainId - The chain ID
+ * @param key - The contract key (e.g., 'escrow', 'usdc', 'unifiedPaymentVerifier')
+ * @param version - Optional version override for accessing historical v2 data
+ * @returns The contract address, or null if not found
+ *
+ * @example
+ * // Get Base v3 escrow (default for buy/sell UI)
+ * const escrow = getLatestContract(base.id, 'escrow')
+ *
+ * @example
+ * // Explicitly get v2 contract for historical data
+ * const v2Escrow = getLatestContract(pulsechain.id, 'escrow', 'v2')
+ */
+export const getLatestContract = (chainId, key, version) => {
+    const v = version ?? getDefaultVersion(chainId);
+    const chainContracts = getContracts(v, chainId);
+    if (!chainContracts) {
+        console.log('No contracts found for chainId', v, chainId);
         return null;
-    const target = contracts[key];
+    }
+    const target = chainContracts[key];
     if (!target)
         return null;
-    if (Array.isArray(target)) {
-        return target[target.length - 1] ?? null;
-    }
-    return target;
+    return Array.isArray(target) ? target.at(-1) : target;
 };
+/**
+ * Get all escrow contracts across all versions and chains.
+ * Returns a flat list of all escrow locations for querying deposits.
+ *
+ * @returns Array of escrow locations with version, chainId, and escrow address
+ *
+ * @example
+ * // Get all escrows to search for a deposit
+ * const escrows = getAllEscrowContracts()
+ * // [
+ * //   { version: 'v2', chainId: 8453, escrow: '0xCA38...' },
+ * //   { version: 'v2', chainId: 369, escrow: '0x2932...' },
+ * //   { version: 'v3', chainId: 8453, escrow: '0x2f12...' },
+ * // ]
+ */
+export function getAllEscrowContracts() {
+    const escrows = [];
+    for (const [version, chainContracts] of Object.entries(contracts)) {
+        for (const [chainIdStr, c] of Object.entries(chainContracts)) {
+            const chainId = Number(chainIdStr);
+            const contractsForChain = c;
+            if (contractsForChain.escrow) {
+                for (const escrow of contractsForChain.escrow) {
+                    escrows.push({
+                        version: version,
+                        chainId,
+                        escrow,
+                    });
+                }
+            }
+        }
+    }
+    return escrows;
+}
+/**
+ * Get all V3 escrow contracts across all chains.
+ * Used for cross-chain nullifier checking to prevent double-spending.
+ *
+ * @returns Array of V3 escrow locations with chainId and escrow address
+ *
+ * @example
+ * const v3Escrows = getAllV3EscrowContracts()
+ * // [
+ * //   { version: 'v3', chainId: 8453, escrow: '0x2f12...' },
+ * //   { version: 'v3', chainId: 369, escrow: '0x0B42...' },
+ * // ]
+ */
+export function getAllV3EscrowContracts() {
+    return getAllEscrowContracts().filter((loc) => loc.version === 'v3');
+}
+/**
+ * Get a short display label for an escrow address (first 6 + last 4 chars)
+ * @param escrow - The escrow address
+ * @returns Shortened address string
+ */
+export function shortenEscrowAddress(escrow) {
+    return `${escrow.slice(0, 6)}...${escrow.slice(-4)}`;
+}
+/**
+ * Get the version of an escrow contract by looking up its address.
+ *
+ * @param escrowAddress - The escrow contract address to look up
+ * @param chainId - Optional chain ID to narrow down the search
+ * @returns The escrow version ('v2' or 'v3'), or null if not found
+ *
+ * @example
+ * // Determine if escrow supports V3 features
+ * const version = getEscrowVersion(deposit.escrow, deposit.chainId)
+ * const isV3 = version === 'v3'
+ */
+export function getEscrowVersion(escrowAddress, chainId) {
+    const normalizedAddress = escrowAddress.toLowerCase();
+    const allEscrows = getAllEscrowContracts();
+    for (const location of allEscrows) {
+        // If chainId is provided, skip non-matching chains
+        if (chainId !== undefined && location.chainId !== chainId) {
+            continue;
+        }
+        if (location.escrow.toLowerCase() === normalizedAddress) {
+            return location.version;
+        }
+    }
+    return null;
+}
+/**
+ * Check if an escrow address is a V3 contract.
+ * Convenience function for feature gating V3-only functionality.
+ *
+ * @param escrowAddress - The escrow contract address
+ * @param chainId - The chain ID
+ * @returns true if the escrow is V3, false otherwise
+ *
+ * @example
+ * // Gate V3-only features in UI
+ * const showRetainToggle = isV3Escrow(deposit.escrow, deposit.chainId) && isOwner
+ */
+export function isV3Escrow(escrowAddress, chainId) {
+    return getEscrowVersion(escrowAddress, chainId) === 'v3';
+}

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

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