@provex/react 1.2.5 → 1.3.0

package/dist/ProvexProvider-DWxHsaR8.d.cts

@@ -0,0 +1,1013 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+import { QueryClient } from '@tanstack/react-query';
+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';
+
+/**
+ * @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 {
+    /** 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;
+
+/** 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, chain). */
+    config: ProvexConfig;
+    /** Data source adapter for indexer queries. */
+    indexer: IndexerAdapter;
+    /** Thin fetch wrapper for the Provex backend API. */
+    apiClient: ApiClient;
+    /** Public clients keyed by chain ID. Always contains at least `config.chain.id`. */
+    publicClients: Record<number, PublicClient>;
+    /** Optional wallet adapter for write operations. */
+    wallet?: WalletAdapter;
+}
+/** 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;
+    /**
+     * Viem public client for the primary chain (`config.chain.id`).
+     * Shorthand for `publicClients={{ [config.chain.id]: client }}`.
+     */
+    publicClient?: PublicClient;
+    /**
+     * Viem public clients keyed by chain ID. Use when your app reads from
+     * multiple chains (e.g., cross-chain deposits).
+     */
+    publicClients?: Record<number, PublicClient>;
+    /**
+     * Wallet adapter for write operations (signalIntent, createDeposit, etc).
+     * Omit for read-only apps.
+     */
+    wallet?: WalletAdapter;
+    /** 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'
+ * import { createPublicClient, http } from 'viem'
+ * import { base } from 'viem/chains'
+ *
+ * const publicClient = createPublicClient({ chain: base, transport: http() })
+ *
+ * <ProvexProvider
+ *   config={{ apiUrl: 'https://app.provex.com', chain: base }}
+ *   indexer={createPonderAdapter()}
+ *   publicClient={publicClient}
+ *   wallet={myWalletAdapter}
+ * >
+ *   <App />
+ * </ProvexProvider>
+ * ```
+ */
+declare function ProvexProvider({ config, indexer, queryClient, publicClient, publicClients, wallet, children, }: ProvexProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * useProvex — access the Provex context (config, indexer, apiClient,
+ * publicClients, wallet).
+ *
+ * Must be called within a ProvexProvider. Throws if used outside the provider.
+ */
+declare function useProvex(): ProvexContextValue;
+/**
+ * Get the public client for a specific chain, or the primary chain if omitted.
+ * Returns `undefined` if no client is registered for that chain.
+ */
+declare function useProvexPublicClient(chainId?: number): PublicClient | undefined;
+/**
+ * Get the optional public client without requiring ProvexProvider.
+ * Returns `undefined` outside the provider or when no client is registered.
+ */
+declare function useOptionalProvexPublicClient(chainId?: number): PublicClient | undefined;
+/**
+ * Get the configured wallet adapter, if any. Returns `undefined` for
+ * read-only apps that did not pass a wallet to ProvexProvider.
+ */
+declare function useProvexWallet(): WalletAdapter | undefined;
+/**
+ * Get the optional wallet adapter without requiring ProvexProvider.
+ */
+declare function useOptionalProvexWallet(): WalletAdapter | undefined;
+
+export { type IndexedVerifier as $, type AttestationParams as A, type BuyProps as B, type CreateDepositRawParams as C, type DepositPaymentMethod as D, useDeposits as E, getRate as F, usePayeeDetails as G, intentStatuses as H, type IndexerAdapter as I, useSignalIntent as J, useProvexPublicClient as K, useOptionalProvexPublicClient as L, type MakerRegistrationParams as M, useProvexWallet as N, useOptionalProvexWallet as O, type ProveXClientConfig as P, type ReputationLimitsParams as Q, type ReputationData as R, type SignalIntentParams as S, type TransactionResult as T, type UseProvexBuyOptions as U, type ReputationLimits as V, type WritableMethod as W, type DepositInfo as X, type IntentStatus as Y, type PayeeInfo as Z, type SignalIntentStatus as _, type PaginationOptions as a, type PaginatedResult as b, type IndexedDeposit as c, type IndexedIntent as d, type CreateDepositParams as e, type PreparedTransaction as f, type SignalIntentResult as g, type PayeeDetails as h, type AttestationResponse as i, type WalletAdapter as j, type UseProvexBuyReturn as k, type PhaseRenderProps as l, type ProvexConfig as m, type BuyPhase as n, type ProvexTheme as o, type PhaseComponentProps as p, ProvexProvider as q, type ProvexContextValue as r, type ProvexProviderProps as s, ProveXError as t, useProvex as u, type ProveXErrorCode as v, type SignalIntentRawParams as w, createApiClient as x, type ApiClient as y, useReputationLimits as z };