@dcentralab/d402-client 0.2.7 → 0.3.2

package/dist/index.d.ts

@@ -4,35 +4,6 @@ import { PublicClient, WalletClient, Hash, Address } from 'viem';
 /**
  * Type definitions for D402 payment protocol
  */
-
-/**
- * Supported blockchain networks (where IATP contracts are deployed)
- */
-type SupportedNetwork = 'sepolia';
-/**
- * D402 Client configuration
- */
-interface D402Config {
-    /** Viem account for signing payments */
-    account: Account;
-    /** Blockchain network */
-    network: SupportedNetwork;
-    /** Maximum payment amount in wei (smallest token unit) */
-    maxPaymentAmount: bigint;
-    /** Token contract address (defaults to USDC if not provided) */
-    tokenAddress?: `0x${string}`;
-    /** Payment validity window in seconds (default: 300) */
-    validityWindowSeconds?: number;
-}
-/**
- * EIP-712 domain for signature verification
- */
-interface EIP712Domain {
-    name: string;
-    version: string;
-    chainId: number;
-    verifyingContract: `0x${string}`;
-}
 /**
  * Payment requirement from 402 response.
  *
@@ -105,6 +76,24 @@ interface SignedPayment {
         authorization: PaymentAuthorization;
     };
 }
+/**
+ * Raw 402 response structure
+ */
+interface D402Response {
+    d402Version: number;
+    accepts?: PaymentRequirement[];
+    scheme?: string;
+    network?: string;
+    maxAmountRequired?: string;
+    payTo?: `0x${string}`;
+    asset?: `0x${string}`;
+    resource?: string;
+    extra?: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+}
 
 /**
  * Payment requirements selection logic
@@ -126,9 +115,11 @@ interface PaymentSelectorOptions {
     preferredToken?: string;
 }
 /**
- * Select payment requirement from a list based on filters and preferences
+ * Select payment requirement from a list based on filters and preferences.
  *
- * This function implements the same logic as
+ * Applies filters (network, scheme, maxAmount) and preferences to choose
+ * the most appropriate payment option from the list. Prefers matching
+ * preferred network/token if specified, otherwise uses filters.
  *
  * @param requirements - List of accepted payment requirements from 402 response
  * @param options - Selection options and filters
@@ -138,11 +129,13 @@ interface PaymentSelectorOptions {
  * @throws {PaymentAmountExceededError} If payment exceeds max amount
  *
  * @example
+ * ```ts
  * const selected = selectPaymentRequirement(requirements, {
  *   scheme: 'exact',
  *   network: 'base-mainnet',
  *   maxAmount: 1000000n
  * })
+ * ```
  */
 declare function selectPaymentRequirement(requirements: PaymentRequirement[], options?: PaymentSelectorOptions): PaymentRequirement;
 /**
@@ -173,6 +166,26 @@ declare function createPaymentSelector(defaultOptions: PaymentSelectorOptions):
  * @returns Sorted list (preferred first)
  */
 declare function sortPaymentRequirements(requirements: PaymentRequirement[], preferredNetwork?: string): PaymentRequirement[];
+/**
+ * Find matching payment requirement from a list.
+ *
+ * Simple helper to find a requirement matching scheme and network.
+ * For more complex selection logic, use selectPaymentRequirement() instead.
+ *
+ * @param requirements - List of payment requirements
+ * @param scheme - Desired payment scheme (default: "exact")
+ * @param network - Desired network (optional)
+ * @returns Matching payment requirement or undefined
+ *
+ * @example
+ * ```ts
+ * const match = findMatchingPaymentRequirement(requirements, 'exact', 'sepolia')
+ * if (match) {
+ *   console.log('Found exact payment on Sepolia')
+ * }
+ * ```
+ */
+declare function findMatchingPaymentRequirement(requirements: PaymentRequirement[], scheme?: string, network?: string): PaymentRequirement | undefined;
 
 /**
  * D402 Client - Main client class for handling HTTP 402 payments
@@ -444,6 +457,25 @@ declare function signD402Payment(params: {
  * ```
  */
 declare function parsePaymentRequirement(response: Response): Promise<PaymentRequirement>;
+/**
+ * Parse all payment requirements from 402 response.
+ *
+ * Similar to parsePaymentRequirement but returns all options instead of just first.
+ * Useful when client needs to choose from multiple payment options.
+ *
+ * @param response - HTTP Response object with status 402
+ * @returns Array of all payment requirements
+ * @throws {Invalid402ResponseError} If response is invalid
+ *
+ * @example
+ * ```ts
+ * const response = await fetch('http://api.example.com')
+ * const allOptions = await parseAllPaymentRequirements(response)
+ * // Choose based on network, token, etc.
+ * const preferred = allOptions.find(r => r.network === 'sepolia')
+ * ```
+ */
+declare function parseAllPaymentRequirements(response: Response): Promise<PaymentRequirement[]>;
 
 /**
  * Base64 encoding/decoding for payment payloads
@@ -483,123 +515,26 @@ declare function encodePayment(payment: SignedPayment): string;
  * ```
  */
 declare function decodePayment(encodedPayment: string): SignedPayment;
-
-/**
- * Utility functions for D402 payment processing
- */
-
-/**
- * Parse a money string or number into atomic units (wei)
- *
- * @param amount - Amount as string (e.g., "$1.00", "1.5") or number
- * @param decimals - Token decimals (e.g., 6 for USDC, 18 for ETH)
- * @returns Amount in atomic units (wei)
- *
- * @example
- * parseMoney("$1.00", 6) // Returns 1000000n (1 USDC in wei)
- * parseMoney("0.5", 18)  // Returns 500000000000000000n (0.5 ETH in wei)
- */
-declare function parseMoney(amount: string | number | bigint, decimals: number): bigint;
-/**
- * Format atomic units back to human-readable format
- *
- * @param amount - Amount in atomic units (wei)
- * @param decimals - Token decimals
- * @returns Formatted string
- *
- * @example
- * formatMoney(1000000n, 6) // Returns "1.000000"
- */
-declare function formatMoney(amount: bigint, decimals: number): string;
-/**
- * Get USDC token address for a given network
- *
- * @param network - Network name
- * @returns USDC token address
- *
- * @throws {UnsupportedNetworkError} If network is not supported
- */
-declare function getUsdcAddress(network: SupportedNetwork): `0x${string}`;
 /**
- * Get chain ID for a given network.
- *
- * This function maps network names to chain IDs for parsing 402 payment requirements
- * from external APIs. It supports many networks that may appear in 402 responses,
- * even if IATP contracts are not deployed on those networks.
- *
- * Note: IATP contracts are currently only deployed on Sepolia. This function exists
- * to handle 402 responses from any API that might support other networks.
+ * Decode X-PAYMENT-RESPONSE header from server.
  *
- * @param network - Network name or chain ID as string
- * @returns Chain ID as number
+ * After a successful payment, servers may return payment confirmation
+ * in the X-PAYMENT-RESPONSE header. This function decodes it.
  *
- * @throws {UnsupportedNetworkError} If network is not supported
+ * @param header - Base64 encoded payment response header
+ * @returns Decoded payment response object
  *
  * @example
  * ```ts
- * getChainId('sepolia')    // Returns 11155111
- * getChainId('11155111')   // Returns 11155111 (passthrough)
- * getChainId('base')       // Returns 8453 (for parsing 402 responses)
- * ```
- */
-declare function getChainId(network: string): number;
-/**
- * Find matching payment requirement from a list
- *
- * @param requirements - List of payment requirements
- * @param scheme - Desired payment scheme (default: "exact")
- * @param network - Desired network (optional)
- * @returns Matching payment requirement or undefined
- */
-declare function findMatchingPaymentRequirement(requirements: PaymentRequirement[], scheme?: string, network?: string): PaymentRequirement | undefined;
-/**
- * Convert USD amount to USDC atomic units
- *
- * @param usdAmount - Amount in USD (e.g., "1.00" or 1.5)
- * @param decimals - USDC decimals (default: 6)
- * @returns Amount in USDC atomic units
- *
- * @example
- * usdToUsdc("1.00") // Returns 1000000n
- * usdToUsdc(1.5)    // Returns 1500000n
- */
-declare function usdToUsdc(usdAmount: string | number, decimals?: number): bigint;
-/**
- * Generate a random nonce for payment authorization
- *
- * @returns Random 32-byte nonce as hex string
- */
-declare function generateNonce(): `0x${string}`;
-/**
- * Get current timestamp in seconds
- *
- * @returns Unix timestamp in seconds
- */
-declare function getCurrentTimestamp(): number;
-/**
- * Validate Ethereum address format
- *
- * @param address - Address to validate
- * @returns True if valid Ethereum address
- */
-declare function isValidAddress(address: string): boolean;
-/**
- * Normalize Ethereum address to checksummed format
- * Note: This is a simple lowercase normalization. For full checksum validation, use viem's getAddress()
- *
- * @param address - Address to normalize
- * @returns Normalized address
- */
-declare function normalizeAddress(address: string): `0x${string}`;
-/**
- * Decode X-PAYMENT-RESPONSE header from server
- *
- * @param header - Base64 encoded payment response
- * @returns Decoded payment response
+ * const response = await fetch(url, { headers: { 'X-Payment': payment } })
+ * const responseHeader = response.headers.get('X-Payment-Response')
  *
- * @example
- * const response = decodePaymentResponse(responseHeader)
- * console.log(response.success, response.transaction)
+ * if (responseHeader) {
+ *   const paymentResponse = decodePaymentResponse(responseHeader)
+ *   console.log('Success:', paymentResponse.success)
+ *   console.log('Transaction:', paymentResponse.transaction)
+ * }
+ * ```
  */
 declare function decodePaymentResponse(header: string): {
     success: boolean;
@@ -610,118 +545,7 @@ declare function decodePaymentResponse(header: string): {
 };
 
 /**
- * Error classes for D402 payment protocol
- */
-/**
- * Base error class for all payment-related errors
- */
-declare class PaymentError extends Error {
-    constructor(message: string);
-}
-/**
- * Thrown when payment amount exceeds the configured maximum allowed value
- */
-declare class PaymentAmountExceededError extends PaymentError {
-    amount: bigint;
-    maxAmount: bigint;
-    tokenAddress?: string | undefined;
-    constructor(amount: bigint, maxAmount: bigint, tokenAddress?: string | undefined);
-}
-/**
- * Thrown when request configuration is missing required fields
- */
-declare class MissingRequestConfigError extends PaymentError {
-    constructor(message: string);
-}
-/**
- * Thrown when payment has already been attempted for a request
- */
-declare class PaymentAlreadyAttemptedError extends PaymentError {
-    constructor(message?: string);
-}
-/**
- * Thrown when no supported payment scheme is found in payment requirements
- */
-declare class UnsupportedSchemeError extends PaymentError {
-    availableSchemes: string[];
-    constructor(availableSchemes: string[], message?: string);
-}
-/**
- * Thrown when payment verification fails
- */
-declare class PaymentVerificationError extends PaymentError {
-    constructor(message: string);
-}
-/**
- * Thrown when HTTP 402 response is malformed
- */
-declare class Invalid402ResponseError extends PaymentError {
-    constructor(message: string);
-}
-/**
- * Thrown when network is not supported
- */
-declare class UnsupportedNetworkError extends PaymentError {
-    network: string;
-    constructor(network: string);
-}
-
-/**
- * Network and token constants
- */
-
-/**
- * Chain IDs for supported networks
- */
-declare const CHAIN_IDS: Record<SupportedNetwork, number>;
-/**
- * Network configuration
- */
-declare const NETWORKS: Record<SupportedNetwork, {
-    chainId: number;
-    name: string;
-    nativeCurrency: {
-        name: string;
-        symbol: string;
-        decimals: number;
-    };
-}>;
-/**
- * Default USDC token addresses per network
- */
-declare const TOKEN_ADDRESSES: Record<SupportedNetwork, `0x${string}`>;
-/**
- * Default payment validity window (5 minutes)
- */
-declare const DEFAULT_VALIDITY_WINDOW_SECONDS = 300;
-/**
- * EIP-712 type definitions for PullFundsForSettlement
- */
-declare const EIP712_TYPES: {
-    readonly PullFundsForSettlement: readonly [{
-        readonly name: "wallet";
-        readonly type: "address";
-    }, {
-        readonly name: "provider";
-        readonly type: "address";
-    }, {
-        readonly name: "token";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint256";
-    }, {
-        readonly name: "requestPath";
-        readonly type: "string";
-    }];
-};
-
-/**
- * IATPWallet creation and management
- *
+ * Type definitions for wallet module
  */
 
 /**
@@ -741,6 +565,11 @@ interface WalletCreationResult {
     /** Chain ID */
     chainId: number;
 }
+
+/**
+ * IATPWallet creation functions
+ */
+
 /**
  * Create a new IATPWallet using IATPWalletFactory.
  *
@@ -758,7 +587,6 @@ interface WalletCreationResult {
  * @param params.ownerAccount - Owner's account (will own the wallet)
  * @param params.network - Network to deploy on (default: "sepolia")
  * @param params.rpcUrl - Custom RPC URL (optional)
- * @param params.operatorPrivateKey - Use specific operator key instead of generating (optional)
  * @returns Wallet creation result with addresses and keys
  *
  * @example
@@ -774,7 +602,6 @@ interface WalletCreationResult {
  * })
  *
  * console.log('Wallet created:', result.walletAddress)
- * console.log('Operator key:', result.operatorPrivateKey) // Store securely!
  * ```
  */
 declare function createIATPWallet(params: {
@@ -782,23 +609,63 @@ declare function createIATPWallet(params: {
     network?: 'sepolia';
     rpcUrl?: string;
 }): Promise<WalletCreationResult>;
+
 /**
- * Get all IATPWallet addresses owned by a user.
- *
- * Queries the IATPWalletFactory contract to retrieve all wallets
- * where the specified address is the owner.
+ * IATPWallet query functions
+ */
+
+/**
+ * Get available balance for a specific token in an IATPWallet.
  *
- * Use this to check if a user already has a wallet before calling createIATPWallet().
+ * Queries the IATPWallet contract's getAvailableBalance function to retrieve
+ * the available balance for a given token.
  *
  * @param params - Query parameters
- * @param params.ownerAddress - User's wallet address (from MetaMask)
+ * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
+ * @param params.walletAddress - IATPWallet contract address
+ * @param params.tokenAddress - Token contract address (e.g., USDC)
  * @param params.network - Network to query (default: "sepolia")
- * @param params.rpcUrl - Custom RPC URL (optional)
- * @returns Array of IATPWallet contract addresses (empty if user has no wallets)
+ * @returns Available balance in token's base units (wei)
  *
  * @example
  * ```ts
- * import { getWalletsByOwner } from '@dcentralab/d402-client'
+ * import { getAvailableBalance } from '@dcentralab/d402-client'
+ * import { usePublicClient } from 'wagmi'
+ *
+ * const publicClient = usePublicClient()
+ *
+ * const balance = await getAvailableBalance({
+ *   publicClient,
+ *   walletAddress: '0xUserIATPWallet...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC on Sepolia
+ * })
+ *
+ * console.log('Available balance:', balance) // 1000000n (1 USDC)
+ * ```
+ */
+declare function getAvailableBalance(params: {
+    publicClient: PublicClient;
+    walletAddress: Address;
+    tokenAddress: Address;
+    network?: 'sepolia';
+}): Promise<bigint>;
+/**
+ * Get all IATPWallet addresses owned by a user.
+ *
+ * Queries the IATPWalletFactory contract to retrieve all wallets
+ * where the specified address is the owner.
+ *
+ * Use this to check if a user already has a wallet before calling createIATPWallet().
+ *
+ * @param params - Query parameters
+ * @param params.ownerAddress - User's wallet address (from MetaMask)
+ * @param params.network - Network to query (default: "sepolia")
+ * @param params.rpcUrl - Custom RPC URL (optional)
+ * @returns Array of IATPWallet contract addresses (empty if user has no wallets)
+ *
+ * @example
+ * ```ts
+ * import { getWalletsByOwner } from '@dcentralab/d402-client'
  * import { useAccount } from 'wagmi'
  *
  * const { address } = useAccount()
@@ -821,47 +688,125 @@ declare function getWalletsByOwner(params: {
     network?: 'sepolia';
     rpcUrl?: string;
 }): Promise<Address[]>;
+
 /**
- * Get available balance for a specific token in an IATPWallet.
+ * IATPWallet withdrawal functions
+ */
+
+/**
+ * Get withdrawal request for a token in an IATPWallet.
  *
- * Queries the IATPWallet contract's getAvailableBalance function to retrieve
- * the available balance for a given token.
+ * Queries the IATPWallet contract to get the current withdrawal request
+ * (amount and unlock timestamp) for a specific token.
  *
  * @param params - Query parameters
- * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
+ * @param params.publicClient - Viem PublicClient
  * @param params.walletAddress - IATPWallet contract address
- * @param params.tokenAddress - Token contract address (e.g., USDC)
+ * @param params.tokenAddress - Token contract address
  * @param params.network - Network to query (default: "sepolia")
- * @returns Available balance in token's base units (wei)
+ * @returns Withdrawal request: [amount, unlockTimestamp] or null if no request exists
  *
  * @example
  * ```ts
- * import { getAvailableBalance } from '@dcentralab/d402-client'
- * import { usePublicClient } from 'wagmi'
+ * import { getWithdrawalRequest } from '@dcentralab/d402-client'
  *
- * const publicClient = usePublicClient()
+ * const request = await getWithdrawalRequest({
+ *   publicClient,
+ *   walletAddress: '0xUserIATPWallet...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+ * })
  *
- * const balance = await getAvailableBalance({
+ * if (request) {
+ *   const [amount, unlockTimestamp] = request
+ *   const isUnlocked = Date.now() >= Number(unlockTimestamp) * 1000
+ * }
+ * ```
+ */
+declare function getWithdrawalRequest(params: {
+    publicClient: PublicClient;
+    walletAddress: Address;
+    tokenAddress: Address;
+    network?: 'sepolia';
+}): Promise<[bigint, bigint] | null>;
+/**
+ * Request a withdrawal from an IATPWallet.
+ *
+ * Initiates a withdrawal request for a token. The withdrawal will be locked
+ * for a period (typically 5 minutes) before it can be executed.
+ *
+ * @param params - Transaction parameters
+ * @param params.walletClient - Viem WalletClient (from wagmi useWalletClient)
+ * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
+ * @param params.walletAddress - IATPWallet contract address
+ * @param params.tokenAddress - Token contract address
+ * @param params.amount - Amount in token's base units (wei)
+ * @param params.account - Account to sign transaction (operator)
+ * @param params.network - Network (default: "sepolia")
+ * @returns Transaction hash
+ *
+ * @example
+ * ```ts
+ * import { requestWithdrawal } from '@dcentralab/d402-client'
+ * import { parseUnits } from 'viem'
+ *
+ * const hash = await requestWithdrawal({
+ *   walletClient,
  *   publicClient,
  *   walletAddress: '0xUserIATPWallet...',
- *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC on Sepolia
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+ *   amount: parseUnits('100', 6), // 100 USDC (6 decimals)
+ *   account: walletClient.account,
  * })
+ * ```
+ */
+declare function requestWithdrawal(params: {
+    walletClient: WalletClient;
+    publicClient: PublicClient;
+    walletAddress: Address;
+    tokenAddress: Address;
+    amount: bigint;
+    account: Account;
+    network?: 'sepolia';
+}): Promise<Hash>;
+/**
+ * Execute a withdrawal from an IATPWallet (after unlock period).
  *
- * console.log('Available balance:', balance) // 1000000n (1 USDC)
+ * Completes a withdrawal that has passed its unlock period. This transfers
+ * the tokens from the IATPWallet back to the user's wallet.
+ *
+ * @param params - Transaction parameters
+ * @param params.walletClient - Viem WalletClient
+ * @param params.publicClient - Viem PublicClient
+ * @param params.walletAddress - IATPWallet contract address
+ * @param params.tokenAddress - Token contract address
+ * @param params.account - Account to sign transaction (operator)
+ * @param params.network - Network (default: "sepolia")
+ * @returns Transaction hash
+ *
+ * @example
+ * ```ts
+ * import { executeWithdrawal } from '@dcentralab/d402-client'
+ *
+ * const hash = await executeWithdrawal({
+ *   walletClient,
+ *   publicClient,
+ *   walletAddress: '0xUserIATPWallet...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+ *   account: walletClient.account,
+ * })
  * ```
  */
-declare function getAvailableBalance(params: {
+declare function executeWithdrawal(params: {
+    walletClient: WalletClient;
     publicClient: PublicClient;
     walletAddress: Address;
     tokenAddress: Address;
+    account: Account;
     network?: 'sepolia';
-}): Promise<bigint>;
+}): Promise<Hash>;
 
 /**
- * IATPSettlementLayer contract operations
- *
- * Functions for providers (utility agents) to query settlement balances,
- * epochs, and manage withdrawals from the settlement layer.
+ * IATPSettlementLayer query functions
  */
 
 /**
@@ -930,6 +875,13 @@ declare function getUnlockedBalanceForProvider(params: {
     tokenAddress: Address;
     network?: 'sepolia';
 }): Promise<bigint>;
+
+/**
+ * IATPSettlementLayer operations
+ *
+ * Functions for managing withdrawals from the settlement layer.
+ */
+
 /**
  * Withdraw all available epochs for a provider (utility agent).
  *
@@ -965,4 +917,243 @@ declare function withdrawAllAvailableEpochs(params: {
     network?: 'sepolia';
 }): Promise<Hash>;
 
-export { CHAIN_IDS, D402Client, type D402ClientConfig, type D402Config, DEFAULT_VALIDITY_WINDOW_SECONDS, type EIP712Domain, EIP712_TYPES, Invalid402ResponseError, MissingRequestConfigError, NETWORKS, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedNetwork, TOKEN_ADDRESSES, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, findMatchingPaymentRequirement, formatMoney, generateNonce, getAvailableBalance, getChainId, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, isValidAddress, normalizeAddress, parseMoney, parsePaymentRequirement, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc, withdrawAllAvailableEpochs };
+/**
+ * Core type definitions shared across the package
+ */
+/**
+ * Supported blockchain networks (where IATP contracts are deployed)
+ */
+type SupportedNetwork = 'sepolia';
+/**
+ * EIP-712 domain for signature verification
+ */
+interface EIP712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+}
+
+/**
+ * Contract configuration and utilities.
+ *
+ * Provides access to IATPWallet contract ABIs and deployed addresses.
+ * Contract data is bundled directly in the package for reliability.
+ */
+
+/**
+ * Supported contract names.
+ */
+declare enum ContractName {
+    IATP_WALLET = "IATPWallet",
+    IATP_WALLET_FACTORY = "IATPWalletFactory",
+    IATP_SETTLEMENT_LAYER = "IATPSettlementLayer",
+    ROLE_MANAGER = "RoleManager"
+}
+/**
+ * Get contract address for a given network.
+ *
+ * @param contractName - Name of the contract (use ContractName enum)
+ * @param network - Network name (default: "sepolia")
+ * @param useProxy - Use proxy address if true, implementation if false (default: true)
+ * @returns Contract address as hex string, or null if not found
+ *
+ * @example
+ * ```ts
+ * const factoryAddr = getContractAddress(ContractName.IATP_WALLET_FACTORY, 'sepolia')
+ * console.log(factoryAddr) // "0x15D83638E339a0f29283f6B93dC1bb90b8339078"
+ * ```
+ */
+declare function getContractAddress(contractName: string | ContractName, network?: SupportedNetwork, useProxy?: boolean): string | null;
+/**
+ * Get contract ABI for a given network.
+ *
+ * @param contractName - Name of the contract (use ContractName enum)
+ * @param network - Network name (default: "sepolia")
+ * @returns Contract ABI as array of objects, or null if not found
+ *
+ * @example
+ * ```ts
+ * const factoryAbi = getContractAbi(ContractName.IATP_WALLET_FACTORY, 'sepolia')
+ * console.log(factoryAbi.length) // Number of ABI entries
+ * ```
+ */
+declare function getContractAbi(contractName: string | ContractName, network?: SupportedNetwork): any[] | null;
+/**
+ * Get contract configuration (address and ABI) for a network.
+ *
+ * @param contractName - Name of the contract
+ * @param network - Network name (default: "sepolia")
+ * @returns Object with address and abi, or null if not found
+ *
+ * @example
+ * ```ts
+ * const config = getContractConfig(ContractName.IATP_WALLET_FACTORY, 'sepolia')
+ * if (config) {
+ *   console.log(config.address)
+ *   console.log(config.abi.length)
+ * }
+ * ```
+ */
+declare function getContractConfig(contractName: string | ContractName, network?: SupportedNetwork): {
+    address: string;
+    abi: any[];
+} | null;
+
+/**
+ * Utility functions for D402 payment processing
+ */
+
+/**
+ * Parse a money string or number into atomic units (wei)
+ *
+ * @param amount - Amount as string (e.g., "$1.00", "1.5") or number
+ * @param decimals - Token decimals (e.g., 6 for USDC, 18 for ETH)
+ * @returns Amount in atomic units (wei)
+ *
+ * @example
+ * parseMoney("$1.00", 6) // Returns 1000000n (1 USDC in wei)
+ * parseMoney("0.5", 18)  // Returns 500000000000000000n (0.5 ETH in wei)
+ */
+declare function parseMoney(amount: string | number | bigint, decimals: number): bigint;
+/**
+ * Format atomic units back to human-readable format
+ *
+ * @param amount - Amount in atomic units (wei)
+ * @param decimals - Token decimals
+ * @returns Formatted string
+ *
+ * @example
+ * formatMoney(1000000n, 6) // Returns "1.000000"
+ */
+declare function formatMoney(amount: bigint, decimals: number): string;
+/**
+ * Get USDC token address for a given network
+ *
+ * @param network - Network name
+ * @returns USDC token address
+ *
+ * @throws {UnsupportedNetworkError} If network is not supported
+ */
+declare function getUsdcAddress(network: SupportedNetwork): `0x${string}`;
+/**
+ * Get chain ID for a given network.
+ *
+ * This function maps network names to chain IDs for parsing 402 payment requirements
+ * from external APIs. It supports many networks that may appear in 402 responses,
+ * even if IATP contracts are not deployed on those networks.
+ *
+ * Note: IATP contracts are currently only deployed on Sepolia. This function exists
+ * to handle 402 responses from any API that might support other networks.
+ *
+ * @param network - Network name or chain ID as string
+ * @returns Chain ID as number
+ *
+ * @throws {UnsupportedNetworkError} If network is not supported
+ *
+ * @example
+ * ```ts
+ * getChainId('sepolia')    // Returns 11155111
+ * getChainId('11155111')   // Returns 11155111 (passthrough)
+ * getChainId('base')       // Returns 8453 (for parsing 402 responses)
+ * ```
+ */
+declare function getChainId(network: string): number;
+/**
+ * Convert USD amount to USDC atomic units
+ *
+ * @param usdAmount - Amount in USD (e.g., "1.00" or 1.5)
+ * @param decimals - USDC decimals (default: 6)
+ * @returns Amount in USDC atomic units
+ *
+ * @example
+ * usdToUsdc("1.00") // Returns 1000000n
+ * usdToUsdc(1.5)    // Returns 1500000n
+ */
+declare function usdToUsdc(usdAmount: string | number, decimals?: number): bigint;
+/**
+ * Generate a random nonce for payment authorization
+ *
+ * @returns Random 32-byte nonce as hex string
+ */
+declare function generateNonce(): `0x${string}`;
+/**
+ * Get current timestamp in seconds
+ *
+ * @returns Unix timestamp in seconds
+ */
+declare function getCurrentTimestamp(): number;
+/**
+ * Validate Ethereum address format
+ *
+ * @param address - Address to validate
+ * @returns True if valid Ethereum address
+ */
+declare function isValidAddress(address: string): boolean;
+/**
+ * Normalize Ethereum address to checksummed format
+ * Note: This is a simple lowercase normalization. For full checksum validation, use viem's getAddress()
+ *
+ * @param address - Address to normalize
+ * @returns Normalized address
+ */
+declare function normalizeAddress(address: string): `0x${string}`;
+
+/**
+ * Error classes for D402 payment protocol
+ */
+/**
+ * Base error class for all payment-related errors
+ */
+declare class PaymentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when payment amount exceeds the configured maximum allowed value
+ */
+declare class PaymentAmountExceededError extends PaymentError {
+    amount: bigint;
+    maxAmount: bigint;
+    tokenAddress?: string | undefined;
+    constructor(amount: bigint, maxAmount: bigint, tokenAddress?: string | undefined);
+}
+/**
+ * Thrown when request configuration is missing required fields
+ */
+declare class MissingRequestConfigError extends PaymentError {
+    constructor(message: string);
+}
+/**
+ * Thrown when payment has already been attempted for a request
+ */
+declare class PaymentAlreadyAttemptedError extends PaymentError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when no supported payment scheme is found in payment requirements
+ */
+declare class UnsupportedSchemeError extends PaymentError {
+    availableSchemes: string[];
+    constructor(availableSchemes: string[], message?: string);
+}
+/**
+ * Thrown when payment verification fails
+ */
+declare class PaymentVerificationError extends PaymentError {
+    constructor(message: string);
+}
+/**
+ * Thrown when HTTP 402 response is malformed
+ */
+declare class Invalid402ResponseError extends PaymentError {
+    constructor(message: string);
+}
+/**
+ * Thrown when network is not supported
+ */
+declare class UnsupportedNetworkError extends PaymentError {
+    network: string;
+    constructor(network: string);
+}
+
+export { ContractName, D402Client, type D402ClientConfig, type D402Response, type EIP712Domain, Invalid402ResponseError, MissingRequestConfigError, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedNetwork, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, executeWithdrawal, findMatchingPaymentRequirement, formatMoney, generateNonce, getAvailableBalance, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, getWithdrawalRequest, isValidAddress, normalizeAddress, parseAllPaymentRequirements, parseMoney, parsePaymentRequirement, requestWithdrawal, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc, withdrawAllAvailableEpochs };