@provex/react 1.2.3

package/dist/index.d.ts

@@ -0,0 +1,1857 @@
+import * as viem from 'viem';
+import { Hex, Chain, TransactionReceipt, PublicClient } from 'viem';
+import { ChainId } from '@provex/utils/chain';
+import * as _provex_utils_payment from '@provex/utils/payment';
+import { ProviderKey, SubProviderKey, TakerTier } from '@provex/utils/payment';
+import { UserReputation } from '@provex/utils/reputation';
+import { Currency } from '@provex/utils/currencies';
+import { TokenInfo } from '@provex/utils/tokens';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import React__default from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { FeeInfo } from '@provex/utils/fees';
+import { Version } from '@provex/utils/contracts';
+import * as _tanstack_query_core from '@tanstack/query-core';
+
+/**
+ * @fileoverview Hook for fetching deposits that match a buyer's criteria.
+ *
+ * Queries the IndexerAdapter for active V3 deposits that:
+ * - Support the specified payment method
+ * - Support the specified fiat currency
+ * - Have sufficient liquidity for the requested amount
+ * - Are accepting intents
+ *
+ * @see {@link @provex/utils/payment} for provider configuration
+ */
+
+/**
+ * Lightweight deposit info returned by the hook.
+ * Maps from IndexedDeposit — same shape the UI already consumes.
+ */
+interface DepositInfo {
+    escrow: Hex;
+    localId: bigint;
+    chainId: number;
+    participantAddress: Hex;
+    token: Hex;
+    remaining: bigint;
+    deposited: bigint;
+    minAmount: bigint;
+    maxAmount: bigint;
+    status: string;
+    acceptingIntents: boolean;
+    availableFunds: bigint;
+    conversionRates: Map<string, Map<string, bigint>>;
+    verifierPaymentMethodIds: Set<string>;
+}
+/** Options for the useDeposits hook. */
+interface UseDepositsOptions {
+    token: TokenInfo;
+    paymentMethod: ProviderKey;
+    currency?: Currency;
+    refetchIntervalMs?: number;
+}
+/**
+ * Get the best (lowest) conversion rate for a deposit across the main provider
+ * and all sub-providers.
+ *
+ * Returns 0n when the deposit has no rate for the given payment method / currency.
+ */
+declare function getRate({ deposit, paymentMethod, currency, }: {
+    deposit: DepositInfo | null | undefined;
+    paymentMethod: ProviderKey | SubProviderKey;
+    currency: Currency;
+}): bigint;
+/**
+ * Hook to fetch matchable deposits from the indexer.
+ *
+ * @example
+ * ```ts
+ * const { deposits, isLoading, getMatchableDeposits } = useDeposits({
+ *   token: usdcToken,
+ *   paymentMethod: 'venmo',
+ * })
+ *
+ * const matches = getMatchableDeposits(parseUnits('100', { decimals: 2 }))
+ * ```
+ */
+declare function useDeposits(options: UseDepositsOptions): {
+    deposits: DepositInfo[];
+    isLoading: boolean;
+    isUpdating: boolean;
+    error: Error | null;
+    refetch: () => void;
+    filterDepositsByAmount: (amountInInt: bigint) => DepositInfo[];
+    getMatchableDeposits: (amountInInt: bigint | null | string) => DepositInfo[];
+};
+
+/**
+ * @fileoverview IndexerAdapter — data source abstraction for @provex/react.
+ *
+ * Decouples the react hooks from any specific indexer implementation.
+ * Consumers provide their own adapter:
+ * - `@provex/indexer-client` exports `createPonderAdapter()` for Ponder SQL
+ * - Third parties can implement against The Graph, REST APIs, or direct RPC
+ *
+ * All methods that return lists support optional pagination via `limit`/`cursor`.
+ * When omitted, the implementation returns all results.
+ */
+
+/** Cursor-based pagination options. */
+interface PaginationOptions {
+    /** Maximum number of results to return. */
+    limit?: number;
+    /** Opaque cursor from a previous response. Pass to fetch the next page. */
+    cursor?: string;
+}
+/** Paginated response wrapper. */
+interface PaginatedResult<T> {
+    items: T[];
+    /** Cursor for the next page. Null when there are no more results. */
+    nextCursor: string | null;
+}
+/** A deposit with computed availability, rates, and payment method info. */
+interface IndexedDeposit {
+    escrow: Hex;
+    localId: bigint;
+    chainId: ChainId;
+    participantAddress: Hex;
+    token: Hex;
+    remaining: bigint;
+    deposited: bigint;
+    minAmount: bigint;
+    maxAmount: bigint;
+    status: string;
+    acceptingIntents: boolean;
+    /** remaining + reclaimable - activeLocked */
+    availableFunds: bigint;
+    /** Map<paymentMethodId, Map<currencyId, rateValue>> */
+    conversionRates: Map<string, Map<string, bigint>>;
+    /** Set of payment method IDs this deposit accepts */
+    paymentMethodIds: Set<string>;
+    /** Verifier records for payee detail lookups */
+    verifiers: IndexedVerifier[];
+}
+/** A deposit verifier record. */
+interface IndexedVerifier {
+    paymentMethodId: Hex;
+    payeeDetailsHash: Hex;
+    intentGatingService: Hex;
+    active: boolean;
+}
+/** An indexed intent with lifecycle status and expiry. */
+interface IndexedIntent {
+    intentHash: Hex;
+    ownerAddress: Hex;
+    toAddress: Hex;
+    escrow: Hex;
+    depositLocalId: bigint;
+    amount: bigint;
+    timestamp: bigint;
+    paymentMethodId: Hex;
+    fiatCurrency: Hex;
+    conversionRate: bigint;
+    /** Expiry timestamp from fundsLocked (unix seconds), null if not locked */
+    expiryTime: bigint | null;
+    /** Lifecycle status */
+    status: 'pending' | 'signalled' | 'fulfilled' | 'pruned';
+    /** When the intent was pruned (unix seconds), null if not pruned */
+    prunedAt: bigint | null;
+}
+/** Pre-computed reputation data for tier calculation. */
+interface ReputationData {
+    /** Total fulfilled volume in USDC (human-readable, e.g. 1500.50) */
+    fulfilledVolumeUsdc: number;
+    /** Number of fulfilled intents */
+    fulfilledCount: number;
+    /** Number of late cancellations (>15 min after signal) */
+    lateCancellations: number;
+    /** Unix timestamp (seconds) of most recent signaled intent per chain. Null if never signaled. */
+    lastSignaledAt: Partial<Record<ChainId, bigint>>;
+}
+/**
+ * Data source abstraction for @provex/react.
+ *
+ * Every method that returns a list accepts optional `PaginationOptions`.
+ * For batch queries, callers can specify multiple filter keys.
+ *
+ * Implementations:
+ * - `createPonderAdapter(ponderClient)` from `@provex/indexer-client`
+ * - Custom REST/Graph/RPC implementations
+ *
+ * @example
+ * ```ts
+ * // Using the Ponder adapter
+ * import { createPonderAdapter } from '@provex/indexer-client'
+ * const indexer = createPonderAdapter(ponderClient)
+ *
+ * // Using a custom REST API
+ * const indexer: IndexerAdapter = {
+ *   getMatchableDeposits: ({ chainId, token, currencyId }) =>
+ *     fetch(`/api/deposits?chain=${chainId}&token=${token}&currency=${currencyId}`)
+ *       .then(r => r.json()),
+ *   // ...
+ * }
+ * ```
+ */
+interface IndexerAdapter {
+    /**
+     * Fetch active V3 deposits that match buyer criteria.
+     *
+     * Returns deposits with computed availability (remaining + reclaimable - locked),
+     * active conversion rates, and payment method IDs.
+     *
+     * The implementation should:
+     * - Filter to active, v3, acceptingIntents deposits on the given chain/token
+     * - Filter to deposits supporting the given currency
+     * - Include conversion rates and verifier data
+     * - Compute availableFunds from locked/unlocked/transferred events
+     *
+     * @param params.chainId - Chain to query
+     * @param params.token - Token address to filter by
+     * @param params.currencyId - Fiat currency contract ID to filter by
+     * @param params.pagination - Optional limit/cursor
+     */
+    getMatchableDeposits(params: {
+        chainId: ChainId;
+        token: Hex;
+        currencyId: Hex;
+        pagination?: PaginationOptions;
+    }): Promise<PaginatedResult<IndexedDeposit>>;
+    /**
+     * Fetch a single deposit with its verifiers.
+     *
+     * Used by usePayeeDetails to look up deposit info after an intent is signaled.
+     */
+    getDepositWithVerifiers(params: {
+        escrow: Hex;
+        localId: bigint;
+        chainId: ChainId;
+    }): Promise<IndexedDeposit | null>;
+    /**
+     * Fetch intent details including expiry time and lifecycle status.
+     *
+     * Combines intent signal data, lock data, and status (fulfilled/pruned/signalled)
+     * into a single response.
+     */
+    getIntent(params: {
+        intentHash: Hex;
+        chainId: ChainId;
+    }): Promise<IndexedIntent | null>;
+    /**
+     * Get the payee details hash for a deposit's payment method.
+     *
+     * Used before signaling an intent — the gating service needs this hash.
+     *
+     * @returns The payeeDetailsHash, or null if no verifier is found
+     */
+    getPayeeDetailsHash(params: {
+        escrow: Hex;
+        localId: bigint;
+        chainId: ChainId;
+        paymentMethodId: Hex;
+    }): Promise<Hex | null>;
+    /**
+     * Get user's reputation data for tier calculation.
+     *
+     * Returns pre-computed stats that the reputation hook uses to derive
+     * the tier, lock score, and cooldown.
+     *
+     * @param params.address - User's wallet address
+     * @param params.chainId - Optional chain filter. When set, only counts
+     *                         activity on that chain. When omitted, counts all chains.
+     */
+    getUserReputation(params: {
+        address: Hex;
+        chainId?: ChainId;
+    }): Promise<ReputationData>;
+    /**
+     * Check if a transaction has been indexed.
+     * Returns a truthy value when indexed, null when not yet.
+     */
+    getTransactionByHash(hash: Hex): Promise<unknown | null>;
+    /**
+     * Check a deposit's current indexed status.
+     * Returns null if the deposit isn't indexed yet.
+     */
+    getDepositById(depositId: Hex): Promise<{
+        status: string;
+    } | null>;
+}
+
+/**
+ * @fileoverview Types for the ProveXClient — framework-agnostic protocol client.
+ */
+
+interface ProveXClientConfig {
+    /**
+     * The viem Chain object to operate on. Provides chain ID, RPC URLs,
+     * block explorers, and native currency config.
+     *
+     * Import from `viem/chains` or define your own for custom RPCs / testnets.
+     *
+     * @example
+     * ```ts
+     * import { base, pulsechain } from 'viem/chains'
+     *
+     * // Standard chain
+     * createProveXClient({ chain: base })
+     *
+     * // Custom RPC
+     * createProveXClient({
+     *   chain: { ...base, rpcUrls: { default: { http: ['https://my-rpc.com'] } } }
+     * })
+     *
+     * // Testnet
+     * createProveXClient({ chain: pulsechainV4, escrowAddress: '0x...' })
+     * ```
+     */
+    chain: Chain;
+    /**
+     * Backend API URL. Defaults to `https://app.provex.com`.
+     * Override for self-hosted or staging deployments.
+     */
+    apiUrl?: string;
+    /**
+     * Wallet adapter for signing transactions.
+     * Omit for prepare-only mode (`.prepare()` works without a wallet).
+     */
+    wallet?: WalletAdapter;
+    /**
+     * Data source adapter for indexer queries.
+     * Omit if you only need on-chain reads and `.prepare()`.
+     */
+    indexer?: IndexerAdapter;
+    /** Override the default V3 escrow address for this chain. */
+    escrowAddress?: Hex;
+    /** Called with the tx hash immediately after wallet submission. */
+    onTransactionHash?: (hash: Hex) => void;
+    /** Called when indexer sync takes longer than expected. */
+    onSlowSync?: () => void;
+}
+/** Framework-agnostic wallet interface. Works with wagmi, ethers, or custom. */
+interface WalletAdapter {
+    /** Connected address, or undefined if disconnected. */
+    address?: Hex;
+    /** Sign and send a transaction. Returns the tx hash. */
+    sendTransaction(tx: {
+        to: Hex;
+        data: Hex;
+        value?: bigint;
+        chainId: number;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    }): Promise<Hex>;
+    /** Read from a contract (optional — falls back to public RPC). */
+    readContract?(params: {
+        address: Hex;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+        chainId?: number;
+    }): Promise<unknown>;
+}
+/**
+ * Unsigned transaction data. Pass to any wallet, multisig, relayer, or batch builder.
+ *
+ * @example
+ * ```ts
+ * const prepared = await client.addFunds.prepare({ depositId: 1n, amount: 100n })
+ * // Hand to Safe SDK, Privy, gasless relay, etc.
+ * await safeSDK.createTransaction({ transactions: [prepared] })
+ * ```
+ */
+interface PreparedTransaction {
+    to: Hex;
+    data: Hex;
+    value: bigint;
+    chainId: number;
+}
+/** Result of a fully executed transaction. */
+interface TransactionResult {
+    hash: Hex;
+    receipt: TransactionReceipt;
+}
+/**
+ * A protocol write operation. Callable to execute the full lifecycle,
+ * or use `.prepare()` to get unsigned transaction data.
+ *
+ * @example
+ * ```ts
+ * // Full execute: gas → wallet → receipt → indexer sync
+ * const { hash } = await client.addFunds({ depositId: 1n, amount: 100n })
+ *
+ * // Prepare only: returns { to, data, value, chainId }
+ * const prepared = await client.addFunds.prepare({ depositId: 1n, amount: 100n })
+ * ```
+ */
+interface WritableMethod<TParams> {
+    /** Execute the full transaction lifecycle. Requires a wallet. */
+    (params: TParams): Promise<TransactionResult>;
+    /** Return unsigned transaction data only. No wallet needed. */
+    prepare(params: TParams): Promise<PreparedTransaction>;
+}
+type ProveXErrorCode = 'WALLET_REJECTED' | 'WALLET_NOT_CONNECTED' | 'TX_REVERTED' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_LIQUIDITY' | 'INDEXER_TIMEOUT' | 'INDEXER_NOT_CONFIGURED' | 'CONTRACT_ERROR' | 'API_ERROR' | 'VALIDATION_ERROR' | 'UNKNOWN';
+/**
+ * Typed error for ProveX protocol operations.
+ * Non-React consumers catch these directly; React hooks map them to UI state.
+ */
+declare class ProveXError extends Error {
+    readonly code: ProveXErrorCode;
+    readonly cause?: Error;
+    constructor(code: ProveXErrorCode, message: string, cause?: Error);
+    /** Check if this error was caused by the user rejecting in their wallet. */
+    get isRejection(): boolean;
+}
+/** Options for registering or validating a maker's payment identity. */
+interface MakerRegistrationParams {
+    /** Payment provider key (e.g. 'venmo', 'zelle', 'revolut') */
+    providerKey: string;
+    /** Provider-specific user ID (e.g. Venmo username, Zelle phone) */
+    providerId: string;
+    /** Optional Telegram handle for contact */
+    telegramHandle?: string;
+}
+/** Payee details returned by the API. */
+interface PayeeDetails {
+    payeeId?: string;
+    name?: string;
+    platformName?: string;
+    [key: string]: unknown;
+}
+/** Attestation request for zkTLS proof submission. */
+interface AttestationParams {
+    /** Payment platform (e.g. 'chase', 'venmo') */
+    platform: string;
+    /** Action type (e.g. 'transfer_zelle', 'transfer_venmo') */
+    actionType: string;
+    /** Reclaim proofs */
+    proofs: unknown[];
+    /** Chain ID for the attestation */
+    chainId: number;
+    /** Verifying contract address */
+    verifyingContract: Hex;
+    /** Intent data for the attestation */
+    intent: unknown;
+}
+/** Attestation response with signed payment proof. */
+interface AttestationResponse {
+    success: boolean;
+    message?: string;
+    statusCode?: number;
+    responseObject: {
+        paymentProof?: unknown;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Human-readable params for signaling an intent (buyer side).
+ *
+ * The SDK handles:
+ * 1. Looking up payee details from the indexer
+ * 2. Requesting a gating service signature from the API
+ * 3. Building and simulating the on-chain transaction
+ * 4. Extracting the intent hash from the IntentSignaled event
+ *
+ * @example
+ * ```ts
+ * const { hash, intentHash } = await client.signalIntent({
+ *   deposit: { escrow: '0x...', localId: 1n },
+ *   paymentMethod: '0x...',     // bytes32 payment method hash
+ *   tokenAmount: 100_000000n,
+ *   toAddress: '0x...',
+ *   fiatCurrencyCode: '0x...',  // bytes32 currency code hash
+ *   conversionRate: 1_000000000000000000n,
+ * })
+ * ```
+ */
+interface SignalIntentParams {
+    deposit: {
+        escrow: Hex;
+        localId: bigint;
+    };
+    paymentMethod: Hex;
+    tokenAmount: bigint;
+    toAddress: Hex;
+    fiatCurrencyCode: Hex;
+    conversionRate: bigint;
+    subProvider?: string;
+}
+/** Result of a signalIntent call. Extends TransactionResult with the intent hash. */
+interface SignalIntentResult extends TransactionResult {
+    /** The on-chain intent hash, extracted from the IntentSignaled event. */
+    intentHash: Hex;
+}
+/** Raw on-chain params matching the Orchestrator's signalIntent signature. */
+interface SignalIntentRawParams {
+    escrow: Hex;
+    depositId: bigint;
+    amount: bigint;
+    to: Hex;
+    paymentMethod: Hex;
+    fiatCurrency: Hex;
+    conversionRate: bigint;
+    referrer: Hex;
+    referrerFee: bigint;
+    gatingServiceSignature: Hex;
+    signatureExpiration: bigint;
+    postIntentHook: Hex;
+    data: Hex;
+}
+/** Raw contract-level params matching the V3 Escrow's createDeposit signature. */
+interface CreateDepositRawParams {
+    token: Hex;
+    amount: bigint;
+    intentAmountRange: {
+        min: bigint;
+        max: bigint;
+    };
+    paymentMethods: Hex[];
+    paymentMethodData: Array<{
+        intentGatingService: Hex;
+        payeeDetails: Hex;
+        data: Hex;
+    }>;
+    currencies: Array<Array<{
+        code: Hex;
+        minConversionRate: bigint;
+    }>>;
+    delegate: Hex;
+    intentGuardian: Hex;
+    retainOnEmpty: boolean;
+}
+/** A payment method to include in a new deposit. */
+interface DepositPaymentMethod {
+    /** Provider key (e.g., 'venmo', 'zelle', 'revolut', 'wise'). */
+    provider: string;
+    /** Plaintext payee identifier — SDK hashes and registers it automatically. */
+    payeeId: string;
+    /**
+     * Currencies this payment method accepts, with minimum conversion rates.
+     *
+     * @example
+     * ```ts
+     * currencies: [
+     *   { code: 'USD', minRate: 0n },   // accept any rate
+     *   { code: 'EUR', minRate: 980000000000000000n },  // min 0.98 EUR/USDC
+     * ]
+     * ```
+     */
+    currencies: Array<{
+        code: string;
+        minRate: bigint;
+    }>;
+    /**
+     * Custom intent gating service address. Defaults to the protocol's
+     * standard Reclaim gating service for this chain.
+     */
+    intentGatingService?: Hex;
+    /**
+     * Custom data field for the payment method (encoded ABI params).
+     * Defaults to the standard Reclaim witness signer encoding.
+     */
+    data?: Hex;
+}
+/**
+ * Human-readable params for creating a deposit.
+ * The SDK handles hashing, sub-provider expansion, maker registration, and
+ * all the encoding needed to build the on-chain transaction.
+ *
+ * @example
+ * ```ts
+ * await client.createDeposit({
+ *   token: USDC_ADDRESS,
+ *   amount: 1000_000000n,
+ *   intentRange: { min: 10_000000n, max: 500_000000n },
+ *   paymentMethods: [
+ *     { provider: 'venmo', payeeId: '@myvenmo', currencies: [{ code: 'USD', minRate: 0n }] },
+ *   ],
+ * })
+ * ```
+ */
+interface CreateDepositParams$1 {
+    /** ERC-20 token address (e.g., USDC). */
+    token: Hex;
+    /** Deposit amount in the token's smallest unit (e.g., 6 decimals for USDC). */
+    amount: bigint;
+    /**
+     * Min/max intent amount range buyers can signal.
+     * `min` defaults to 1_000000n (1 USDC). `max` defaults to `amount`.
+     */
+    intentRange?: {
+        min?: bigint;
+        max?: bigint;
+    };
+    /** Payment methods the depositor accepts. */
+    paymentMethods: DepositPaymentMethod[];
+    /** Optional Telegram handle for buyer-seller contact. */
+    telegramHandle?: string;
+    /** Delegate address that can manage this deposit. Defaults to zero (no delegate). */
+    delegate?: Hex;
+    /** Guardian address for intent gating. Defaults to zero (no guardian). */
+    intentGuardian?: Hex;
+    /** Keep deposit active even when fully claimed. Defaults to false. */
+    retainOnEmpty?: boolean;
+}
+
+/**
+ * @fileoverview React hook for the V3 intent signaling flow.
+ *
+ * Thin state wrapper around ProveXClient.signalIntent() —
+ * manages status, error messages, and loading state for the UI.
+ */
+
+/** Status of the signal intent flow. */
+type SignalIntentStatus = 'input' | 'loading_payee' | 'loading_intent' | 'prompt_wallet_confirm' | 'writing_intent' | 'success' | 'error';
+/**
+ * Hook for signaling intent to buy tokens via the V3 Orchestrator.
+ *
+ * Delegates to ProveXClient.signalIntent() for the full multi-step flow:
+ * 1. Fetch payee details from indexer
+ * 2. Request gating signature from API
+ * 3. Simulate, submit, and parse IntentSignaled event
+ *
+ * @example
+ * ```ts
+ * const { startOrder, status, message, isLoading } = useSignalIntent({
+ *   wallet,
+ *   chainId: 369,
+ *   deposit: selectedDeposit,
+ *   onSuccess: (intentHash) => navigate(`/verify/${intentHash}`),
+ * })
+ * ```
+ */
+declare function useSignalIntent({ wallet, onSuccess, onFailure, deposit, refetchDeposits, }: {
+    /** Wallet adapter for signing transactions. */
+    wallet: WalletAdapter;
+    /** @deprecated Chain is resolved from ProvexProvider. Kept for API compat. */
+    chainId?: ChainId;
+    /** Called when the intent is signaled successfully. */
+    onSuccess: (intentHash: Hex) => void;
+    /** Called when the flow fails. */
+    onFailure?: () => void;
+    /** The deposit to signal intent against. */
+    deposit: DepositInfo | null;
+    /** Called on failure to refresh deposit data. */
+    refetchDeposits?: () => void;
+}): {
+    startOrder: ({ paymentMethod, depositId, tokenAmount, toAddress, fiatCurrencyCode, conversionRate, subProvider, }: {
+        paymentMethod: Hex;
+        depositId: bigint;
+        tokenAmount: bigint;
+        toAddress: Hex;
+        fiatCurrencyCode: Hex;
+        conversionRate: bigint;
+        subProvider?: SubProviderKey;
+    }) => Promise<void>;
+    status: SignalIntentStatus;
+    message: string | null;
+    isLoading: boolean;
+};
+
+/**
+ * @fileoverview Hook for calculating reputation-based trading limits.
+ *
+ * Applies tier-based restrictions on transaction caps and cooldowns.
+ * Pure computation -- no Ponder, no contract reads.
+ *
+ * @see {@link useReputation} for fetching the user's tier
+ * @see {@link @provex/utils/reputation} for tier definitions
+ */
+
+/** Input parameters for calculating reputation limits. */
+interface ReputationLimitsParams {
+    /** Current chain ID */
+    chainId: ChainId;
+    /** Currently selected payment method */
+    selectedPaymentMethod: ProviderKey;
+    /** User's reputation tier */
+    tier: TakerTier;
+    /** Amount in fiat currency (for cap exceeded check) - in token base units (e.g., 6 decimals for USDC) */
+    amountInInt?: bigint | null;
+    /** When the user's cooldown ends (from useReputation) */
+    cooldownEndsAt?: Date | null;
+}
+/** Result of the useReputationLimits hook. */
+interface ReputationLimits {
+    /** Whether reputation limits apply */
+    hasLimits: boolean;
+    /** Alternative providers with no cooldown */
+    noCooldownProviders: ProviderKey[];
+    /** Cooldown hours for the selected payment method (category, not remaining) */
+    selectedProviderCooldownHours: number;
+    /** Remaining cooldown time in formatted string (e.g., "5h 30m") - null if not on cooldown */
+    cooldownRemaining: string | null;
+    /** Whether user is currently on cooldown for the selected payment method */
+    isOnCooldown: boolean;
+    /** Effective cap in USD for the selected payment method (null if no cap) */
+    effectiveCap: number | null;
+    /** Whether the current amount exceeds the cap */
+    amountExceedsCap: boolean;
+    /** Error message when cap is exceeded */
+    capExceededMessage: string | null;
+}
+/**
+ * Hook to calculate reputation-based limits for payment methods.
+ *
+ * @example
+ * ```ts
+ * const {
+ *   noCooldownProviders,
+ *   selectedProviderCooldownHours,
+ *   effectiveCap,
+ *   amountExceedsCap,
+ *   capExceededMessage,
+ * } = useReputationLimits({
+ *   chainId,
+ *   selectedPaymentMethod,
+ *   tier: reputation.tier,
+ *   amountInInt,
+ * })
+ * ```
+ */
+declare function useReputationLimits({ chainId, selectedPaymentMethod, tier, amountInInt, cooldownEndsAt, }: ReputationLimitsParams): ReputationLimits;
+
+/**
+ * @fileoverview Hook for reading protocol fee configuration.
+ *
+ * Fetches the current protocol fee percentage and recipient address
+ * from the Orchestrator contract via wagmi.
+ *
+ * @remarks
+ * Fees may be stored as basis points (bps) or 18-decimal precision
+ * depending on the chain. This hook normalizes both to a consistent format.
+ *
+ * @see {@link @provex/utils/fees} for fee calculation utilities
+ */
+
+/** Result of the useProtocolFees hook. */
+interface ProtocolFeesResult {
+    /** Raw protocol fee value from contract (may be bps or 18-decimal) */
+    protocolFeeRaw: bigint | undefined;
+    /** Normalized fee info with percentage string and bps value */
+    feeInfo: FeeInfo | undefined;
+    /** Address that receives protocol fees */
+    protocolFeeRecipient: Hex | undefined;
+    /** Orchestrator contract address (read from escrow) */
+    orchestratorAddress: Hex | undefined;
+    /** True while loading fee data */
+    isLoading: boolean;
+    /** True if an error occurred */
+    isError: boolean;
+    /** Error object if an error occurred */
+    error: Error | null;
+    /** Refetch fee data */
+    refetch: () => void;
+}
+/** Hook parameters for useProtocolFees. */
+interface UseProtocolFeesParams {
+    /** The chain ID to read fees from */
+    chainId: ChainId;
+    /** V3 Escrow contract address (orchestrator is read from this) */
+    escrowAddress: Hex;
+    /** Whether to enable the query (defaults to true) */
+    enabled?: boolean;
+}
+/**
+ * Hook to read protocol fees from the V3 Orchestrator contract.
+ *
+ * The V3 Orchestrator charges a protocol fee on intent fulfillment.
+ * This hook reads:
+ * 1. Orchestrator address from the Escrow contract
+ * 2. Protocol fee (as bps or 18-decimal precision)
+ * 3. Protocol fee recipient address
+ *
+ * Fee precision is automatically detected and normalized to basis points.
+ *
+ * Requires a wagmi `WagmiProvider` ancestor in the component tree.
+ *
+ * @param params - Hook parameters
+ * @returns Protocol fee data and loading state
+ *
+ * @example
+ * ```tsx
+ * const { feeInfo, isLoading } = useProtocolFees({
+ *   chainId: 8453,
+ *   escrowAddress: '0x2f121CDDCA6d652f35e8B3E560f9760898888888',
+ * })
+ *
+ * if (!isLoading && feeInfo) {
+ *   console.log(`Protocol fee: ${feeInfo.percentage}`) // "0%" or "2%"
+ * }
+ * ```
+ */
+declare function useProtocolFees({ chainId, escrowAddress, enabled, }: UseProtocolFeesParams): ProtocolFeesResult;
+/**
+ * Simplified hook to get just the protocol fee percentage for a chain.
+ *
+ * @param params - Hook parameters
+ * @returns The fee percentage string (e.g., "0%", "2%") or undefined if loading
+ */
+declare function useProtocolFeePercentage(params: UseProtocolFeesParams): string | undefined;
+
+/**
+ * @fileoverview Hook for fetching user reputation (taker tier).
+ *
+ * Calculates the user's reputation tier based on:
+ * - Fulfilled volume (in USDC, 1:1 with USD)
+ * - Lock score (penalty for cancellations)
+ * - Cooldown status
+ *
+ * Uses the IndexerAdapter for data — no direct Ponder queries.
+ *
+ * @see {@link @provex/utils/reputation} for tier definitions
+ * @see {@link useReputationLimits} for applying limits to specific payments
+ */
+
+/**
+ * Hook to fetch and calculate user reputation tier.
+ *
+ * @param address - User's wallet address
+ * @param chainId - Current chain ID
+ * @returns User reputation data and loading state
+ */
+declare function useReputation({ address, chainId, }: {
+    address: Hex | undefined;
+    chainId: ChainId;
+}): {
+    reputation: UserReputation;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+};
+/**
+ * Get display info for a tier.
+ */
+declare function getTierDisplayInfo(tier: TakerTier): {
+    name: string;
+    baseCap: number;
+    cooldownHours: number;
+    color: string;
+    volumeRangeDisplay: string;
+};
+
+/**
+ * @fileoverview Hook for checking nullifier usage (double-spend prevention).
+ *
+ * The NullifierRegistry tracks which payment proofs have been used to
+ * prevent the same off-chain payment from being used multiple times.
+ *
+ * @remarks
+ * Chain of contract calls to reach NullifierRegistry:
+ * 1. V3Escrow → orchestrator()
+ * 2. Orchestrator → paymentVerifierRegistry()
+ * 3. PaymentVerifierRegistry → getVerifier(paymentMethodId)
+ * 4. UnifiedPaymentVerifier → nullifierRegistry()
+ */
+
+/**
+ * Hook to interact with the NullifierRegistry for checking if a nullifier has been used.
+ *
+ * The nullifier is derived from paymentMethod and paymentId to prevent double-spending.
+ *
+ * Requires a wagmi `WagmiProvider` ancestor in the component tree.
+ *
+ * @param escrowAddress - The V3 escrow contract address
+ * @param paymentMethodId - The payment method ID (bytes32 hash)
+ * @param chainId - The chain ID
+ */
+declare function useNullifierRegistry({ escrowAddress, paymentMethodId, chainId, }: {
+    escrowAddress: Hex | undefined;
+    paymentMethodId: Hex | undefined;
+    chainId: number;
+}): {
+    orchestratorAddress: Hex | undefined;
+    paymentVerifierRegistryAddress: Hex | undefined;
+    verifierAddress: Hex | undefined;
+    nullifierRegistryAddress: Hex | undefined;
+    isLoading: boolean;
+    checkNullifierUsed: (nullifier: Hex) => Promise<boolean | null>;
+};
+
+/**
+ * @fileoverview Hook for ERC20 token allowance checking and approval.
+ *
+ * Handles the common pattern of checking if a spender (escrow contract)
+ * has sufficient allowance to transfer tokens, and prompting for approval
+ * if needed.
+ *
+ * @remarks
+ * Approval is required before createDeposit or addFunds can transfer
+ * tokens to the escrow contract.
+ */
+
+declare const useAllowance: ({ token, spender, account, balance, defaultAllowance, onSuccess, onError, onSettled, }: {
+    token: TokenInfo;
+    spender: Hex;
+    /** The account address to check/write allowance for. If undefined, hook returns null allowance and writeApproval is a no-op. */
+    account: Hex | undefined;
+    balance?: bigint;
+    defaultAllowance?: "max" | "balance";
+    onSuccess?: (...args: unknown[]) => void;
+    onError?: (...args: unknown[]) => void;
+    onSettled?: (...args: unknown[]) => void;
+}) => {
+    allowance: bigint | null;
+    isLoading: boolean;
+    isWritingApproval: boolean;
+    /** Loading text for the approval button */
+    approvalLoadingText: string;
+    error: Error | null;
+    writeApproval: () => Promise<void>;
+};
+
+/**
+ * @fileoverview Hook for canceling an active intent.
+ *
+ * V3: Delegates to ProveXClient.cancelIntent (Orchestrator).
+ * V2: Falls back to direct wagmi writeContract (legacy Escrow).
+ */
+
+/** Status values for the cancel intent operation. */
+type CancelIntentStatus = 'idle' | 'prompt_wallet_confirm' | 'writing_tx' | 'success' | 'error';
+/**
+ * Hook to cancel an intent with automatic v2/v3 version detection.
+ *
+ * V3 delegates to ProveXClient. V2 uses wagmi directly (legacy).
+ */
+declare const useCancelIntent: ({ onSuccess, onMutate, onError, onSettled, chainId, escrowAddress: providedEscrowAddress, version: explicitVersion, }: {
+    onSuccess?: () => void;
+    onMutate?: () => void;
+    onError?: (error: Error) => void;
+    onSettled?: () => void;
+    chainId?: ChainId | null | undefined;
+    escrowAddress?: Hex | null | undefined;
+    version?: Version;
+}) => {
+    cancelIntent: (intentHash: Hex) => Promise<void>;
+    status: CancelIntentStatus;
+    isLoading: boolean;
+    version: "v2" | "v3";
+    errorMessage: string | null;
+};
+
+/**
+ * @fileoverview Hook for releasing funds back to payer.
+ *
+ * V3: Delegates to ProveXClient.releaseFundsToPayer (Orchestrator).
+ * V2: Falls back to direct wagmi writeContract (legacy Escrow).
+ */
+
+/** Status values for the release funds operation. */
+type ReleaseFundsStatus = 'idle' | 'prompt_wallet_confirm' | 'writing_tx' | 'success' | 'error';
+/**
+ * Hook to release funds back to payer with automatic v2/v3 version detection.
+ *
+ * V3 delegates to ProveXClient. V2 uses wagmi directly (legacy).
+ */
+declare const useReleaseFundsToPayer: ({ onSuccess, onSettled, chainId, escrowAddress: providedEscrowAddress, version: explicitVersion, }: {
+    onSuccess?: () => void;
+    onSettled?: () => void;
+    chainId?: ChainId | null | undefined;
+    escrowAddress?: Hex | null | undefined;
+    version?: Version;
+}) => {
+    releaseFundsToPayer: (intentHash: Hex) => Promise<void>;
+    status: ReleaseFundsStatus;
+    isLoading: boolean;
+    errorMessage: string | null;
+    version: "v2" | "v3";
+};
+
+/**
+ * Status values for escrow write operations.
+ */
+type V3EscrowStatus = 'idle' | 'prompt_wallet_confirm' | 'writing_tx' | 'confirming' | 'syncing' | 'success' | 'error';
+/** @deprecated Use `CreateDepositRawParams` from `@provex/react/client/types`. */
+type CreateDepositParams = CreateDepositRawParams;
+/**
+ * Hook for interacting with v3 Escrow contract.
+ *
+ * All write methods delegate to ProveXClient. Reads use wagmi for
+ * automatic cache management.
+ */
+declare const useV3Escrow: ({ chainId, escrowAddress, onSlowSync, onTransactionConfirmed, onError, }: {
+    chainId?: ChainId | null;
+    escrowAddress?: Hex | null;
+    /** Called when indexer sync is taking longer than expected. */
+    onSlowSync?: () => void;
+    /** Called after the transaction is confirmed on-chain. */
+    onTransactionConfirmed?: (params: {
+        hash: Hex;
+        chainId: ChainId;
+        action: string;
+    }) => void;
+    /** Called when a write method fails (contract revert, gas issues, etc). Not called on user rejection. */
+    onError?: (error: Error) => void;
+}) => {
+    status: V3EscrowStatus;
+    error: string | null;
+    isLoading: boolean;
+    escrow: `0x${string}` | null;
+    orchestratorAddress: `0x${string}` | undefined;
+    depositCounter: bigint | undefined;
+    txHash: `0x${string}` | null;
+    createDeposit: (params: CreateDepositRawParams) => Promise<`0x${string}` | null>;
+    addFunds: (depositId: bigint, amount: bigint) => Promise<`0x${string}` | null>;
+    removeFunds: (depositId: bigint, amount: bigint) => Promise<`0x${string}` | null>;
+    withdrawDeposit: (depositId: bigint) => Promise<`0x${string}` | null>;
+    pruneExpiredIntents: (depositId: bigint) => Promise<`0x${string}` | null>;
+    setAcceptingIntents: (depositId: bigint, accepting: boolean) => Promise<`0x${string}` | null>;
+    setRetainOnEmpty: (depositId: bigint, retain: boolean) => Promise<`0x${string}` | null>;
+    setIntentRange: (depositId: bigint, intentAmountRange: {
+        min: bigint;
+        max: bigint;
+    }) => Promise<`0x${string}` | null>;
+    setPaymentMethodActive: (depositId: bigint, paymentMethod: Hex, active: boolean) => Promise<`0x${string}` | null>;
+    setCurrencyMinRate: (params: {
+        depositId: bigint;
+        paymentMethod: Hex;
+        currency: Hex;
+        newMinConversionRate: bigint;
+    }) => Promise<`0x${string}` | null>;
+    addCurrencies: (params: {
+        depositId: bigint;
+        paymentMethod: Hex;
+        currencies: Array<{
+            code: Hex;
+            minConversionRate: bigint;
+        }>;
+    }) => Promise<`0x${string}` | null>;
+    deactivateCurrency: (params: {
+        depositId: bigint;
+        paymentMethod: Hex;
+        currencyCode: Hex;
+    }) => Promise<`0x${string}` | null>;
+    addPaymentMethods: (params: {
+        depositId: bigint;
+        paymentMethods: Hex[];
+        paymentMethodData: Array<{
+            intentGatingService: Hex;
+            payeeDetails: Hex;
+            data: Hex;
+        }>;
+        currencies: Array<Array<{
+            code: Hex;
+            minConversionRate: bigint;
+        }>>;
+    }) => Promise<`0x${string}` | null>;
+    getDeposit: (depositId: bigint) => Promise<unknown>;
+    getAccountDeposits: (account: Hex) => Promise<unknown>;
+    reset: () => void;
+    refetchOrchestrator: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<`0x${string}`, viem.ReadContractErrorType>>;
+    refetchDepositCounter: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<bigint, viem.ReadContractErrorType>>;
+};
+
+/**
+ * Phase of the transaction lifecycle.
+ */
+type TransactionPhase = 'idle' | 'submitting' | 'confirming' | 'syncing' | 'complete' | 'error';
+interface UseTransactionWithIndexerOptions {
+    /** Called when transaction is fully indexed */
+    onSuccess?: () => void;
+    /** Called on any error */
+    onError?: (error: Error) => void;
+    /** Called when indexer sync is taking longer than expected. */
+    onSlowSync?: () => void;
+    /** Called after the transaction is confirmed on-chain. */
+    onTransactionConfirmed?: (params: {
+        hash: Hex;
+        chainId: ChainId;
+        action: string;
+    }) => void;
+    /** Called when a transaction-level error message is available. */
+    onTransactionError?: (message: string) => void;
+    /** Indexer adapter. Falls back to ProvexProvider context, then skips sync. */
+    indexer?: IndexerAdapter;
+}
+interface TransactionSyncOptions {
+    /** The transaction hash to track */
+    hash: Hex;
+    /** Chain ID for the transaction */
+    chainId: ChainId;
+    /** Action description (e.g., "Deposit created") */
+    action: string;
+}
+interface MutationSyncOptions {
+    /** The transaction hash */
+    hash: Hex;
+    /** Deposit local ID for mutation tracking */
+    depositId: bigint;
+    /** Chain ID for the deposit */
+    chainId: ChainId;
+    /** Target status to wait for */
+    status: string;
+    /** Action description */
+    action: string;
+}
+/**
+ * Hook for handling the three-phase transaction flow:
+ * 1. Transaction submission (handled by caller)
+ * 2. Transaction confirmation (waiting for mining)
+ * 3. Indexer sync (waiting for indexer to process)
+ */
+declare const useTransactionWithIndexer: (options?: UseTransactionWithIndexerOptions) => {
+    phase: TransactionPhase;
+    isLoading: boolean;
+    loadingText: string | undefined;
+    waitForTransaction: ({ hash, chainId, action, }: TransactionSyncOptions) => Promise<void>;
+    waitForMutation: ({ hash, depositId, chainId, status, action, }: MutationSyncOptions) => Promise<void>;
+    reset: () => void;
+    setPhase: React$1.Dispatch<React$1.SetStateAction<TransactionPhase>>;
+};
+
+/**
+ * @fileoverview ProveXClient — framework-agnostic protocol client.
+ *
+ * Works in any JavaScript runtime: Node.js, React, Vue, Svelte, serverless.
+ * Every write method supports `.prepare()` for smart accounts and relayers.
+ *
+ * @example
+ * ```ts
+ * import { createProveXClient } from '@provex/react'
+ * import { createPonderAdapter } from '@provex/indexer-client'
+ *
+ * // Full client (reads + writes)
+ * const client = createProveXClient({
+ *   chainId: 8453,
+ *   apiUrl: 'https://app.provex.com',
+ *   wallet: myWalletAdapter,
+ *   indexer: createPonderAdapter(),
+ * })
+ *
+ * // Prepare-only mode (no wallet, no indexer)
+ * const client = createProveXClient({ chainId: 8453, apiUrl: 'https://app.provex.com' })
+ * const prepared = await client.addFunds.prepare({ depositId: 1n, amount: 100_000000n })
+ * ```
+ */
+
+/**
+ * ProveXClient — the framework-agnostic core of the ProveX SDK.
+ *
+ * Encapsulates all protocol interactions: indexer reads, on-chain reads,
+ * and contract writes. React hooks are thin wrappers around this class.
+ */
+declare class ProveXClient {
+    /** The viem Chain object — carries RPC URLs, chain ID, and metadata. */
+    readonly chain: Chain;
+    /** Numeric chain ID (derived from chain.id). */
+    readonly chainId: ChainId;
+    private readonly wallet?;
+    private readonly indexer?;
+    private readonly escrowOverride?;
+    private readonly onTransactionHash?;
+    readonly apiUrl: string;
+    private readonly onSlowSync?;
+    /** Lazily-created public client for RPC calls. */
+    private _publicClient;
+    /** Cached orchestrator address (lazy-loaded). */
+    private cachedOrchestratorAddress;
+    constructor(config: ProveXClientConfig);
+    /** Get the V3 escrow address for this client's chain. */
+    getEscrowAddress(): Hex;
+    /** Get the orchestrator address (cached after first read). */
+    getOrchestratorAddress(): Promise<Hex>;
+    private requireIndexer;
+    getMatchableDeposits(params: {
+        token: Hex;
+        currencyId: Hex;
+        pagination?: PaginationOptions;
+    }): Promise<PaginatedResult<IndexedDeposit>>;
+    getDepositWithVerifiers(params: {
+        escrow: Hex;
+        localId: bigint;
+    }): Promise<IndexedDeposit | null>;
+    getIntent(intentHash: Hex): Promise<IndexedIntent | null>;
+    getPayeeDetailsHash(params: {
+        escrow: Hex;
+        localId: bigint;
+        paymentMethodId: Hex;
+    }): Promise<Hex | null>;
+    getUserReputation(address: Hex): Promise<ReputationData>;
+    getProtocolFees(): Promise<{
+        feeRaw: bigint;
+        feeInfo: FeeInfo;
+        feeRecipient: Hex;
+    }>;
+    getDeposit(depositId: bigint): Promise<unknown>;
+    getAccountDeposits(account: Hex): Promise<unknown>;
+    getDepositCounter(): Promise<bigint>;
+    getAllowance(params: {
+        token: Hex;
+        owner: Hex;
+        spender: Hex;
+    }): Promise<bigint>;
+    checkNullifierUsed(params: {
+        paymentMethodId: Hex;
+        nullifier: Hex;
+    }): Promise<boolean | null>;
+    /** Low-level deposit creation — pass pre-hashed contract params directly. */
+    readonly createDepositRaw: WritableMethod<CreateDepositRawParams>;
+    readonly addFunds: WritableMethod<{
+        depositId: bigint;
+        amount: bigint;
+    }>;
+    readonly removeFunds: WritableMethod<{
+        depositId: bigint;
+        amount: bigint;
+    }>;
+    readonly withdrawDeposit: WritableMethod<{
+        depositId: bigint;
+    }>;
+    readonly pruneExpiredIntents: WritableMethod<{
+        depositId: bigint;
+    }>;
+    readonly setAcceptingIntents: WritableMethod<{
+        depositId: bigint;
+        accepting: boolean;
+    }>;
+    readonly setRetainOnEmpty: WritableMethod<{
+        depositId: bigint;
+        retain: boolean;
+    }>;
+    readonly setIntentRange: WritableMethod<{
+        depositId: bigint;
+        min: bigint;
+        max: bigint;
+    }>;
+    readonly setPaymentMethodActive: WritableMethod<{
+        depositId: bigint;
+        paymentMethod: Hex;
+        active: boolean;
+    }>;
+    readonly setCurrencyMinRate: WritableMethod<{
+        depositId: bigint;
+        paymentMethod: Hex;
+        currency: Hex;
+        rate: bigint;
+    }>;
+    readonly addCurrencies: WritableMethod<{
+        depositId: bigint;
+        paymentMethod: Hex;
+        currencies: Array<{
+            code: Hex;
+            minConversionRate: bigint;
+        }>;
+    }>;
+    readonly deactivateCurrency: WritableMethod<{
+        depositId: bigint;
+        paymentMethod: Hex;
+        currencyCode: Hex;
+    }>;
+    readonly addPaymentMethods: WritableMethod<{
+        depositId: bigint;
+        paymentMethods: Hex[];
+        paymentMethodData: Array<{
+            intentGatingService: Hex;
+            payeeDetails: Hex;
+            data: Hex;
+        }>;
+        currencies: Array<Array<{
+            code: Hex;
+            minConversionRate: bigint;
+        }>>;
+    }>;
+    /**
+     * Create a deposit with human-readable params.
+     *
+     * Handles all encoding internally:
+     * 1. Registers payee details with the API (so buyers can discover them)
+     * 2. Hashes provider keys and currency codes to bytes32
+     * 3. Expands sub-providers (e.g., 'zelle' → zelle-chase, zelle-bofa, zelle-citi)
+     * 4. Encodes gating service witness signers
+     * 5. Submits the on-chain transaction
+     *
+     * @example
+     * ```ts
+     * await client.createDeposit({
+     *   token: USDC_ADDRESS,
+     *   amount: 1000_000000n,
+     *   intentRange: { min: 10_000000n, max: 500_000000n },
+     *   paymentMethods: [
+     *     { provider: 'venmo', payeeId: '@myvenmo', currencies: [{ code: 'USD', minRate: 0n }] },
+     *   ],
+     *   retainOnEmpty: true,
+     * })
+     * ```
+     */
+    createDeposit(params: CreateDepositParams$1): Promise<TransactionResult>;
+    /**
+     * Prepare an unsigned createDeposit transaction (no API call, no wallet).
+     *
+     * Use this for smart accounts, multisig, gasless relayers, or offline signing.
+     * Maker registration is NOT performed — call `registerMaker()` separately
+     * if you need buyers to discover the payee.
+     */
+    prepareCreateDeposit(params: CreateDepositParams$1): Promise<PreparedTransaction>;
+    /**
+     * Convert human-readable deposit params to raw contract params.
+     * Handles provider expansion, hashing, gating service encoding, and defaults.
+     */
+    private buildCreateDepositRawParams;
+    readonly cancelIntent: WritableMethod<{
+        intentHash: Hex;
+    }>;
+    readonly releaseFundsToPayer: WritableMethod<{
+        intentHash: Hex;
+    }>;
+    /**
+     * Signal an intent to buy tokens from a deposit (buyer side).
+     *
+     * Handles the full multi-step flow:
+     * 1. Fetches payee details hash from the indexer
+     * 2. Requests a gating service signature from the API
+     * 3. Simulates the transaction
+     * 4. Submits to Orchestrator.signalIntent()
+     * 5. Parses the IntentSignaled event to extract the intent hash
+     *
+     * @returns Transaction result with the on-chain intent hash.
+     * @throws {ProveXError} VALIDATION_ERROR if payee details or gating signature missing.
+     * @throws {ProveXError} API_ERROR if gating service rejects the intent.
+     * @throws {ProveXError} WALLET_REJECTED if user cancels in wallet.
+     *
+     * @example
+     * ```ts
+     * const { hash, intentHash } = await client.signalIntent({
+     *   deposit: { escrow: '0x...', localId: 1n },
+     *   paymentMethod: providerKeyToContractId('venmo'),
+     *   tokenAmount: 100_000000n,
+     *   toAddress: wallet.address,
+     *   fiatCurrencyCode: tickerToContractId('USD'),
+     *   conversionRate: 1_000000000000000000n,
+     * })
+     * ```
+     */
+    signalIntent(params: SignalIntentParams): Promise<SignalIntentResult>;
+    /**
+     * Request a gating service signature for intent signaling.
+     * The gating service validates the intent and returns a signature
+     * the Orchestrator contract verifies on-chain.
+     */
+    private requestGatingSignature;
+    readonly approve: WritableMethod<{
+        token: Hex;
+        spender: Hex;
+        amount?: bigint;
+    }>;
+    /** Get payee details for a provider and user ID. */
+    getPayeeInfo(params: {
+        provider: string;
+        userId: string;
+    }): Promise<PayeeDetails | null>;
+    /** Validate a maker's payment identity before registration. */
+    validateMaker(params: MakerRegistrationParams): Promise<boolean>;
+    /** Register a maker's payment identity (e.g., Venmo username). Required before creating deposits. */
+    registerMaker(params: MakerRegistrationParams): Promise<{
+        id: string;
+    } | null>;
+    /**
+     * Submit zkTLS proofs and get a signed attestation for fulfillIntent.
+     * This is the proof verification step — after the buyer makes payment and
+     * generates proofs via the browser extension.
+     */
+    getAttestation(params: AttestationParams): Promise<AttestationResponse>;
+    /** Make a POST request to the API. */
+    private apiPost;
+    waitForTransactionIndexed(hash: Hex): Promise<void>;
+    /** Get or create a viem PublicClient for this chain. Cached after first use. */
+    getPublicClient(): PublicClient;
+    /** Read from a contract using wallet adapter or public RPC. */
+    private readContract;
+    /** Require a connected wallet, or throw. */
+    private requireWallet;
+    /**
+     * Build a WritableMethod from an ABI definition.
+     * The returned function supports both execute (full lifecycle) and .prepare() (unsigned tx).
+     */
+    private buildWritableMethod;
+}
+/**
+ * Create a ProveXClient instance.
+ *
+ * @example
+ * ```ts
+ * // Full client
+ * const client = createProveXClient({
+ *   chainId: 8453,
+ *   apiUrl: 'https://app.provex.com',
+ *   wallet: myWalletAdapter,
+ *   indexer: createPonderAdapter(),
+ * })
+ *
+ * // Prepare-only mode
+ * const client = createProveXClient({ chainId: 8453, apiUrl: 'https://app.provex.com' })
+ * const tx = await client.addFunds.prepare({ depositId: 1n, amount: 100_000000n })
+ * ```
+ */
+declare function createProveXClient(config: ProveXClientConfig): ProveXClient;
+
+/**
+ * @fileoverview React hook that bridges ProvexProvider context to ProveXClient.
+ *
+ * Creates (and memoizes) a ProveXClient instance from the provider's
+ * indexer adapter, config, and an optional wallet adapter.
+ */
+
+/**
+ * Get a memoized ProveXClient from the ProvexProvider context.
+ *
+ * @param wallet - Optional wallet adapter for write operations.
+ *                 Omit for read-only usage or prepare-only mode.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const client = useProveXClient(myWallet)
+ *   const prepared = await client.addFunds.prepare({ depositId: 1n, amount: 100n })
+ * }
+ * ```
+ */
+declare function useProveXClient(wallet?: WalletAdapter): ProveXClient;
+
+/**
+ * @fileoverview Bridge wagmi's wallet to the WalletAdapter interface.
+ *
+ * Creates a memoized WalletAdapter from wagmi's `useWalletClient` and
+ * `useAccount` hooks. Pass the result to `useProveXClient(wallet)` or
+ * directly to any hook that accepts a WalletAdapter.
+ */
+
+/**
+ * Create a WalletAdapter from the connected wagmi wallet.
+ *
+ * Returns `null` when no wallet is connected.
+ *
+ * @example
+ * ```tsx
+ * const wallet = useWagmiWallet()
+ * const client = useProveXClient(wallet ?? undefined)
+ * ```
+ */
+declare function useWagmiWallet(): WalletAdapter | null;
+
+/** Intent status values representing the lifecycle state. */
+declare const intentStatuses: {
+    readonly pending: "pending";
+    readonly signalled: "signalled";
+    readonly fulfilled: "fulfilled";
+    readonly pruned: "pruned";
+};
+type IntentStatus = (typeof intentStatuses)[keyof typeof intentStatuses];
+/** Payee details from the API. */
+interface PayeeInfo {
+    payeeId?: string;
+    name?: string;
+    platformName?: string;
+    [key: string]: unknown;
+}
+/**
+ * Hook to fetch intent details and payee information.
+ *
+ * @param intentHash - The intent hash to look up
+ * @param chainId - The chain ID to query
+ * @returns Intent details, payee info, and loading state
+ */
+declare function usePayeeDetails({ intentHash, chainId, }: {
+    intentHash: Hex | null;
+    chainId: ChainId;
+}): {
+    intentStatus: IntentStatus | null;
+    isFetching: boolean;
+    isValid: boolean;
+    intent: {
+        owner: `0x${string}`;
+        to: `0x${string}`;
+        escrow: `0x${string}`;
+        depositId: bigint;
+        amount: bigint;
+        timestamp: bigint;
+        paymentMethod: `0x${string}`;
+        fiatCurrency: `0x${string}`;
+        conversionRate: bigint;
+    } | null;
+    providerKey: _provex_utils_payment.ProviderKey | null;
+    userId: `0x${string}` | null;
+    payeeDetails: PayeeInfo | null;
+    deposit: IndexedDeposit | null;
+    expiryTime: bigint | null;
+    isV2Intent: boolean;
+    isPruned: boolean;
+    prunedAt: bigint | null;
+    isFulfilled: boolean;
+    refetch: () => void;
+    refetchAll: () => Promise<IntentStatus | null>;
+};
+
+/** Configuration for ProvexProvider. */
+interface ProvexConfig {
+    /** Backend API URL (e.g. "https://app.provex.com") */
+    apiUrl: string;
+    /** The viem Chain object. Import from `viem/chains`. */
+    chain: Chain;
+    /** @deprecated Use `chain.id` — kept for backward compat during migration. */
+    chainId?: ChainId;
+}
+/** Buy flow phases. */
+type BuyPhase = 'browse' | 'committed' | 'proving' | 'complete';
+/** Theme overrides applied as CSS custom properties on the root element. */
+interface ProvexTheme {
+    accent?: string;
+    background?: string;
+    backgroundCard?: string;
+    text?: string;
+    textMuted?: string;
+    border?: string;
+    error?: string;
+    radius?: string;
+    font?: string;
+}
+/** Options for the useProvexBuy hook. */
+interface UseProvexBuyOptions {
+    /** Wallet adapter — host app's wallet connection. */
+    wallet: WalletAdapter;
+    /** Called when the user signals intent (USDC reserved). */
+    onIntentSignaled?: (intentHash: string, chainId: number) => void;
+    /** Called when the full flow completes (USDC released). */
+    onComplete?: (intentHash: string, chainId: number) => void;
+    /** Restrict to specific payment methods. */
+    paymentMethods?: ProviderKey[];
+}
+/** Return value of the useProvexBuy hook — the full buy-flow state machine. */
+interface UseProvexBuyReturn {
+    /** Current phase of the buy flow. */
+    phase: BuyPhase;
+    /** Fiat amount entered by the user (string for input binding). */
+    amount: string;
+    /** Set the fiat amount. */
+    setAmount: (value: string) => void;
+    /** Currently selected payment method, or empty string if none. */
+    selectedPaymentMethod: ProviderKey | '';
+    /** Set the selected payment method. */
+    setSelectedPaymentMethod: (method: ProviderKey) => void;
+    /** Payment methods available for the current chain. */
+    availablePaymentMethods: ProviderKey[];
+    /** All deposits matching the current criteria. */
+    deposits: DepositInfo[];
+    /** The best deposit selected for the current amount. */
+    selectedDeposit: DepositInfo | null;
+    /** Manually select a deposit (advanced use). */
+    selectDeposit: (deposit: DepositInfo) => void;
+    /** True while deposits are loading for the first time. */
+    isLoadingDeposits: boolean;
+    /** Best rate for the current amount/payment method (raw 18-decimal). */
+    rate: bigint | null;
+    /** Human-readable rate string (e.g. "1 USDC = $1.01"). */
+    rateDisplay: string | null;
+    /** Token amount the user will receive (base units). */
+    tokenAmount: bigint | null;
+    /** Human-readable token amount (e.g. "99.50"). */
+    tokenAmountDisplay: string | null;
+    /** Token info for the current chain. */
+    token: TokenInfo | null;
+    /** Currency info (e.g. USD). */
+    currency: Currency | null;
+    /** User reputation data. */
+    reputation: UserReputation;
+    /** Reputation-based limits for the selected payment method. */
+    limits: ReputationLimits;
+    /** Protocol fee percentage string (e.g. "0%"), or null if loading. */
+    feePercentage: string | null;
+    /** Seller's payment details (name, handle, platform). */
+    payeeDetails: PayeeInfo | null;
+    /** Seller's display name. */
+    payeeName: string | null;
+    /** Seller's payment handle (e.g. Venmo username, Zelle email). */
+    payeeId: string | null;
+    /** True while payee details are loading. */
+    isPayeeLoading: boolean;
+    /** Intent expiry time. */
+    intentExpiryTime: Date | null;
+    /** Whether the intent has expired (pruned). */
+    isIntentExpired: boolean;
+    /** Indexed intent lifecycle status (signalled, fulfilled, pruned). */
+    indexedIntentStatus: IntentStatus | null;
+    /** Whether the order form can be submitted. */
+    canSubmit: boolean;
+    /** User-facing validation message, or null when valid. */
+    validationMessage: string | null;
+    /** Submit the order (signal intent on-chain). */
+    submitOrder: () => Promise<void>;
+    /** Confirm payment was sent (transitions to proving/complete). */
+    confirmPayment: () => void;
+    /** Reset the flow back to browse. */
+    reset: () => void;
+    /** Intent hash after successful order submission. */
+    intentHash: Hex | null;
+    /** Current status of the signal intent flow. */
+    intentStatus: SignalIntentStatus;
+    /** Error message from the intent flow. */
+    intentError: string | null;
+    /** True while the intent is being submitted. */
+    isSubmitting: boolean;
+    /** Chain ID for the current configuration. */
+    chainId: ChainId;
+}
+/** Props for the ProvexBuy widget component (Layer 3). */
+interface BuyProps {
+    /** Wallet adapter — host app's wallet connection. */
+    wallet: WalletAdapter;
+    /** Called when the user signals intent (USDC reserved). */
+    onIntentSignaled?: (intentHash: string, chainId: number) => void;
+    /** Called when the full flow completes (USDC released). */
+    onComplete?: (intentHash: string, chainId: number) => void;
+    /** Restrict to specific payment methods. */
+    paymentMethods?: ProviderKey[];
+    /** CSS class name for the root container. */
+    className?: string;
+    /** Inline styles for the root container. */
+    style?: React.CSSProperties;
+    /** Theme overrides applied as CSS custom properties. */
+    theme?: ProvexTheme;
+}
+/** Common props accepted by all phase components. */
+interface PhaseComponentProps {
+    /** CSS class name. */
+    className?: string;
+    /** Inline styles. */
+    style?: React.CSSProperties;
+}
+/** Props for a phase component with a custom render prop. */
+interface PhaseRenderProps<TState> extends PhaseComponentProps {
+    /** Custom render function — receives the phase state, returns JSX. */
+    render?: (state: TState) => React.ReactNode;
+}
+
+/**
+ * @fileoverview Thin API client for @provex/react.
+ *
+ * Provides typed get/post methods for the Provex backend API.
+ * No external dependencies — uses the Fetch API directly.
+ */
+/** API client for making typed requests to the Provex backend. */
+interface ApiClient {
+    /** Send a GET request and parse the JSON response. */
+    get: <T>(path: string, options?: RequestInit) => Promise<T>;
+    /** Send a POST request with a JSON body and parse the response. */
+    post: <T>(path: string, body: unknown, options?: RequestInit) => Promise<T>;
+}
+/** Create an API client that targets the given base URL. */
+declare function createApiClient(apiUrl: string): ApiClient;
+
+/** Shape of the context value provided by ProvexProvider. */
+interface ProvexContextValue {
+    /** User-supplied configuration (apiUrl, chainId). */
+    config: ProvexConfig;
+    /** Data source adapter for indexer queries. */
+    indexer: IndexerAdapter;
+    /** Thin fetch wrapper for the Provex backend API. */
+    apiClient: ApiClient;
+}
+/** Props for the ProvexProvider component. */
+interface ProvexProviderProps {
+    /** Protocol configuration. */
+    config: ProvexConfig;
+    /**
+     * Data source adapter. Implement IndexerAdapter against any backend:
+     * - `createPonderAdapter()` from `@provex/indexer-client` (default for Provex apps)
+     * - Custom REST, Graph, or RPC implementation
+     */
+    indexer: IndexerAdapter;
+    /** Optional external QueryClient — if omitted, a default one is created. */
+    queryClient?: QueryClient;
+    /** Child components that consume the context. */
+    children: React__default.ReactNode;
+}
+/**
+ * ProvexProvider — wrap your app (or a subtree) with this to enable
+ * Provex hooks and components.
+ *
+ * @example
+ * ```tsx
+ * import { createPonderAdapter } from '@provex/indexer-client'
+ *
+ * const indexer = createPonderAdapter()
+ *
+ * <ProvexProvider
+ *   indexer={indexer}
+ *   config={{ apiUrl: 'https://app.provex.com', chainId: 369 }}
+ * >
+ *   <App />
+ * </ProvexProvider>
+ * ```
+ */
+declare function ProvexProvider({ config, indexer, queryClient, children, }: ProvexProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * useProvex — access the Provex context (config, indexer, apiClient).
+ *
+ * Must be called within a ProvexProvider. Throws if used outside the provider.
+ */
+declare function useProvex(): ProvexContextValue;
+
+/**
+ * @fileoverview useProvexBuy — headless state machine for the buy flow.
+ *
+ * Layer 1 of the 3-layer architecture. Returns all state + actions
+ * with zero rendering. The integrator builds their entire UI.
+ *
+ * @example
+ * ```tsx
+ * function MyBuyPage() {
+ *   const buy = useProvexBuy({ wallet })
+ *
+ *   return (
+ *     <div>
+ *       <input value={buy.amount} onChange={e => buy.setAmount(e.target.value)} />
+ *       <button disabled={!buy.canSubmit} onClick={buy.submitOrder}>
+ *         Buy
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+
+/**
+ * useProvexBuy — headless buy-flow state machine.
+ *
+ * Encapsulates all state, derived data, validation, and actions for the
+ * 4-phase buy flow. Returns a flat object that phase components (Layer 2)
+ * or custom UIs (Layer 1) can consume.
+ *
+ * Must be called within a `<ProvexProvider>`.
+ */
+declare function useProvexBuy({ wallet, onIntentSignaled, onComplete, paymentMethods: allowedPaymentMethods, }: UseProvexBuyOptions): UseProvexBuyReturn;
+
+/**
+ * useProvexBuyContext — access the buy-flow state machine from within
+ * a `<ProvexBuyProvider>`.
+ *
+ * Throws if called outside the provider.
+ */
+declare function useProvexBuyContext(): UseProvexBuyReturn;
+/** Props for the ProvexBuyProvider component. */
+interface ProvexBuyProviderProps extends UseProvexBuyOptions {
+    /** Child components that consume the buy-flow context. */
+    children: React__default.ReactNode;
+}
+/**
+ * ProvexBuyProvider — context provider that runs the buy-flow state machine
+ * and makes it available to child phase components via `useProvexBuyContext()`.
+ */
+declare function ProvexBuyProvider({ children, ...options }: ProvexBuyProviderProps): react_jsx_runtime.JSX.Element;
+
+/** State slice exposed to the BrowsePhase render prop. */
+interface BrowsePhaseState {
+    amount: UseProvexBuyReturn['amount'];
+    setAmount: UseProvexBuyReturn['setAmount'];
+    selectedPaymentMethod: UseProvexBuyReturn['selectedPaymentMethod'];
+    setSelectedPaymentMethod: UseProvexBuyReturn['setSelectedPaymentMethod'];
+    availablePaymentMethods: UseProvexBuyReturn['availablePaymentMethods'];
+    chainId: UseProvexBuyReturn['chainId'];
+    rateDisplay: UseProvexBuyReturn['rateDisplay'];
+    tokenAmountDisplay: UseProvexBuyReturn['tokenAmountDisplay'];
+    token: UseProvexBuyReturn['token'];
+    currency: UseProvexBuyReturn['currency'];
+    canSubmit: UseProvexBuyReturn['canSubmit'];
+    isSubmitting: UseProvexBuyReturn['isSubmitting'];
+    validationMessage: UseProvexBuyReturn['validationMessage'];
+    intentError: UseProvexBuyReturn['intentError'];
+    intentStatus: UseProvexBuyReturn['intentStatus'];
+    isLoadingDeposits: UseProvexBuyReturn['isLoadingDeposits'];
+    deposits: UseProvexBuyReturn['deposits'];
+    submitOrder: UseProvexBuyReturn['submitOrder'];
+}
+/**
+ * BrowsePhase — renders the browse/input phase of the buy flow.
+ *
+ * Reads state from ProvexBuyContext. Only renders when phase === 'browse'.
+ */
+declare function BrowsePhase({ className, style, render, }: PhaseRenderProps<BrowsePhaseState>): react_jsx_runtime.JSX.Element | null;
+
+/** State slice exposed to the CommittedPhase render prop. */
+interface CommittedPhaseState {
+    intentHash: UseProvexBuyReturn['intentHash'];
+    amount: UseProvexBuyReturn['amount'];
+    currency: UseProvexBuyReturn['currency'];
+    selectedPaymentMethod: UseProvexBuyReturn['selectedPaymentMethod'];
+    chainId: UseProvexBuyReturn['chainId'];
+    tokenAmountDisplay: UseProvexBuyReturn['tokenAmountDisplay'];
+    token: UseProvexBuyReturn['token'];
+    confirmPayment: UseProvexBuyReturn['confirmPayment'];
+    payeeDetails: UseProvexBuyReturn['payeeDetails'];
+    payeeName: UseProvexBuyReturn['payeeName'];
+    payeeId: UseProvexBuyReturn['payeeId'];
+    isPayeeLoading: UseProvexBuyReturn['isPayeeLoading'];
+    intentExpiryTime: UseProvexBuyReturn['intentExpiryTime'];
+}
+/**
+ * CommittedPhase — renders the committed phase of the buy flow.
+ *
+ * Shows the order summary and payment instructions after the user has
+ * successfully signaled intent on-chain.
+ */
+declare function CommittedPhase({ className, style, render, }: PhaseRenderProps<CommittedPhaseState>): react_jsx_runtime.JSX.Element | null;
+
+/** State slice exposed to the ProvingPhase render prop. */
+interface ProvingPhaseState {
+    intentHash: UseProvexBuyReturn['intentHash'];
+    intentExpiryTime: UseProvexBuyReturn['intentExpiryTime'];
+    isIntentExpired: UseProvexBuyReturn['isIntentExpired'];
+    indexedIntentStatus: UseProvexBuyReturn['indexedIntentStatus'];
+}
+/**
+ * ProvingPhase — renders the proving phase of the buy flow.
+ *
+ * Shows the ZKP proof generation progress after the user confirms payment.
+ */
+declare function ProvingPhase({ className, style, render, }: PhaseRenderProps<ProvingPhaseState>): react_jsx_runtime.JSX.Element | null;
+
+/** State slice exposed to the CompletePhase render prop. */
+interface CompletePhaseState {
+    intentHash: UseProvexBuyReturn['intentHash'];
+    chainId: UseProvexBuyReturn['chainId'];
+    reset: UseProvexBuyReturn['reset'];
+}
+/**
+ * CompletePhase — renders the completion phase of the buy flow.
+ *
+ * Shows a success message and a button to start a new purchase.
+ */
+declare function CompletePhase({ className, style, render, }: PhaseRenderProps<CompletePhaseState>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * ProvexBuy — Layer 3 buy-flow widget.
+ *
+ * Renders a complete 4-phase buy flow (browse -> committed -> proving -> complete)
+ * using plain HTML elements with `data-provex-*` attributes for CSS targeting.
+ *
+ * No UI framework dependencies. All styling via CSS custom properties and data attributes.
+ */
+declare function ProvexBuy({ wallet, onIntentSignaled, onComplete, paymentMethods, className, style, theme, }: BuyProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the ProvexBuyWagmi component. Same as BuyProps minus `wallet`. */
+interface ProvexBuyWagmiProps {
+    /** Called when the user signals intent (USDC reserved). */
+    onIntentSignaled?: (intentHash: string, chainId: number) => void;
+    /** Called when the full flow completes (USDC released). */
+    onComplete?: (intentHash: string, chainId: number) => void;
+    /** Restrict to specific payment methods. */
+    paymentMethods?: ProviderKey[];
+    /** CSS class name for the root container. */
+    className?: string;
+    /** Inline styles for the root container. */
+    style?: React__default.CSSProperties;
+    /** Theme overrides applied as CSS custom properties. */
+    theme?: ProvexTheme;
+}
+/**
+ * ProvexBuyWagmi — drop-in buy widget for wagmi apps.
+ *
+ * Reads the connected wallet from wagmi context automatically.
+ * No need to create a WalletAdapter manually.
+ */
+declare function ProvexBuyWagmi({ onIntentSignaled, onComplete, paymentMethods, className, style, theme, }: ProvexBuyWagmiProps): react_jsx_runtime.JSX.Element;
+
+export { type ApiClient, type AttestationParams, type AttestationResponse, BrowsePhase, type BrowsePhaseState, type BuyPhase, type BuyProps, type CancelIntentStatus, CommittedPhase, type CommittedPhaseState, CompletePhase, type CompletePhaseState, type CreateDepositParams$1 as CreateDepositParams, type CreateDepositRawParams, type DepositInfo, type DepositPaymentMethod, type IndexedDeposit, type IndexedIntent, type IndexedVerifier, type IndexerAdapter, type IntentStatus, type MakerRegistrationParams, type MutationSyncOptions, type PaginatedResult, type PaginationOptions, type PayeeDetails, type PayeeInfo, type PhaseComponentProps, type PhaseRenderProps, type PreparedTransaction, type ProtocolFeesResult, ProveXClient, type ProveXClientConfig, ProveXError, type ProveXErrorCode, ProvexBuy, ProvexBuyProvider, type ProvexBuyProviderProps, ProvexBuyWagmi, type ProvexBuyWagmiProps, type ProvexConfig, type ProvexContextValue, ProvexProvider, type ProvexProviderProps, type ProvexTheme, ProvingPhase, type ProvingPhaseState, type ReleaseFundsStatus, type ReputationData, type ReputationLimits, type ReputationLimitsParams, type SignalIntentParams, type SignalIntentRawParams, type SignalIntentResult, type SignalIntentStatus, type TransactionPhase, type TransactionResult, type TransactionSyncOptions, type UseProtocolFeesParams, type UseProvexBuyOptions, type UseProvexBuyReturn, type UseTransactionWithIndexerOptions, type CreateDepositParams as V3EscrowCreateDepositParams, type V3EscrowStatus, type WalletAdapter, type WritableMethod, createApiClient, createProveXClient, getRate, getTierDisplayInfo, intentStatuses, useAllowance, useCancelIntent, useDeposits, useNullifierRegistry, usePayeeDetails, useProtocolFeePercentage, useProtocolFees, useProveXClient, useProvex, useProvexBuy, useProvexBuyContext, useReleaseFundsToPayer, useReputation, useReputationLimits, useSignalIntent, useTransactionWithIndexer, useV3Escrow, useWagmiWallet };