@openzeppelin/ui-utils 1.0.0

package/dist/index-qy1AQMhr.d.ts

@@ -0,0 +1,1205 @@
+import { ClassValue } from "clsx";
+import { AccessSnapshot, AppRuntimeConfig, ContractAdapter, FieldType, FieldValidation, FieldValue, FormValues, IndexerEndpointConfig, RoleAssignment, RoleIdentifier, RpcEndpointConfig, ServiceParameterConfig, UiKitName, UserExplorerConfig, UserRpcProviderConfig } from "@openzeppelin/ui-types";
+
+//#region src/contractInputs.d.ts
+/**
+ * Returns names of adapter-declared required inputs that are missing/empty in values.
+ */
+declare function getMissingRequiredContractInputs(adapter: ContractAdapter, values: FormValues): string[];
+/**
+ * True if any adapter-declared required inputs are missing/empty.
+ */
+declare function hasMissingRequiredContractInputs(adapter: ContractAdapter | null | undefined, values: FormValues): boolean;
+//# sourceMappingURL=contractInputs.d.ts.map
+//#endregion
+//#region src/requiredInputs.d.ts
+type RequiredInputSnapshot = Record<string, unknown>;
+/**
+ * Builds a snapshot of required form input values.
+ * @param adapter - Contract adapter to get field definitions from
+ * @param formValues - Current form values
+ * @returns Snapshot of required field values, or null if no required fields
+ */
+declare function buildRequiredInputSnapshot(adapter: ContractAdapter | null, formValues: FormValues | null | undefined): RequiredInputSnapshot | null;
+/**
+ * Compares two required input snapshots for equality.
+ * @param a - First snapshot to compare
+ * @param b - Second snapshot to compare
+ * @returns True if snapshots are equal, false otherwise
+ */
+declare function requiredSnapshotsEqual(a: RequiredInputSnapshot | null, b: RequiredInputSnapshot | null): boolean;
+//#endregion
+//#region src/addressNormalization.d.ts
+/**
+ * Normalizes a contract address by trimming whitespace and converting to lowercase.
+ * This is useful for case-insensitive and whitespace-insensitive address comparison.
+ *
+ * @param address - The address to normalize (string, null, or undefined)
+ * @returns The normalized address string, or empty string if input is falsy
+ *
+ * @example
+ * ```ts
+ * normalizeAddress('  0xABC123  ') // Returns '0xabc123'
+ * normalizeAddress('0xDEF456') // Returns '0xdef456'
+ * normalizeAddress(null) // Returns ''
+ * normalizeAddress(undefined) // Returns ''
+ * ```
+ */
+declare function normalizeAddress(address: string | null | undefined): string;
+/**
+ * Compares two addresses after normalization.
+ * Returns true if both addresses normalize to the same value.
+ *
+ * @param address1 - First address to compare
+ * @param address2 - Second address to compare
+ * @returns True if addresses are equal after normalization
+ *
+ * @example
+ * ```ts
+ * addressesEqual('  0xABC  ', '0xabc') // Returns true
+ * addressesEqual('0xDEF', '0xABC') // Returns false
+ * addressesEqual(null, '') // Returns true
+ * ```
+ */
+declare function addressesEqual(address1: string | null | undefined, address2: string | null | undefined): boolean;
+//# sourceMappingURL=addressNormalization.d.ts.map
+//#endregion
+//#region src/logger.d.ts
+/**
+ * Logger utility for consistent logging across the application.
+ * Supports different log levels and can be disabled for testing.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LoggerOptions {
+  enabled: boolean;
+  level: LogLevel;
+}
+declare class Logger {
+  private static instance;
+  private options;
+  private constructor();
+  static getInstance(): Logger;
+  configure(options: Partial<LoggerOptions>): void;
+  private shouldLog;
+  private formatMessage;
+  debug(system: string, message: string, ...args: unknown[]): void;
+  info(system: string, message: string, ...args: unknown[]): void;
+  warn(system: string, message: string, ...args: unknown[]): void;
+  error(system: string, message: string, ...args: unknown[]): void;
+}
+declare const logger: Logger;
+//#endregion
+//#region src/AppConfigService.d.ts
+/**
+ * Type for the strategy array in initialize method.
+ */
+type ConfigLoadStrategy = {
+  type: 'viteEnv';
+  env: ViteEnv | undefined;
+} | {
+  type: 'json';
+  path?: string;
+} | {
+  type: 'localStorage';
+  key?: string;
+};
+interface ViteEnv {
+  [key: string]: string | boolean | undefined;
+}
+/**
+ * AppConfigService
+ *
+ * Responsible for loading, merging, and providing access to the application's
+ * runtime configuration (`AppRuntimeConfig`).
+ */
+declare class AppConfigService {
+  private config;
+  private isInitialized;
+  /**
+   * Creates a new AppConfigService with default configuration.
+   */
+  constructor();
+  private loadFromViteEnvironment;
+  private loadFromJson;
+  /**
+   * Initializes the service by loading configuration from the specified strategies.
+   * @param strategies - Array of configuration loading strategies to apply
+   */
+  initialize(strategies: ConfigLoadStrategy[]): Promise<void>;
+  /**
+   * Gets the API key for a specific explorer service.
+   * @param serviceIdentifier - The service identifier
+   * @returns The API key if configured, undefined otherwise
+   */
+  getExplorerApiKey(serviceIdentifier: string): string | undefined;
+  /**
+   * Gets the configuration for a global service.
+   * @param serviceName - The name of the service
+   * @returns The service configuration if found, undefined otherwise
+   */
+  getGlobalServiceConfig(serviceName: string): ServiceParameterConfig | undefined;
+  /**
+   * Checks if a feature flag is enabled.
+   * @param flagName - The name of the feature flag
+   * @returns True if the feature is enabled, false otherwise
+   */
+  isFeatureEnabled(flagName: string): boolean;
+  /**
+   * Gets a global service parameter value.
+   * @param serviceName The name of the service
+   * @param paramName The name of the parameter
+   * @returns The parameter value (can be any type including objects, arrays) or undefined if not found
+   */
+  getGlobalServiceParam(serviceName: string, paramName: string): string | number | boolean | object | Array<unknown> | undefined;
+  /**
+   * Gets the RPC endpoint override for a specific network.
+   * @param networkId - The network identifier
+   * @returns The RPC endpoint configuration if found, undefined otherwise
+   */
+  getRpcEndpointOverride(networkId: string): string | RpcEndpointConfig | UserRpcProviderConfig | undefined;
+  /**
+   * Get the indexer endpoint override for a specific network.
+   * Indexer endpoints are used for querying historical blockchain data.
+   * @param networkId The network identifier (e.g., 'stellar-testnet')
+   * @returns The indexer endpoint configuration, or undefined if not configured
+   */
+  getIndexerEndpointOverride(networkId: string): string | IndexerEndpointConfig | undefined;
+  /**
+   * Returns the entire configuration object.
+   * Primarily for debugging or for parts of the app that need a broader view.
+   * Use specific getters like `getExplorerApiKey` or `isFeatureEnabled` where possible.
+   */
+  getConfig(): Readonly<AppRuntimeConfig>;
+  /**
+   * Gets a nested configuration object with type safety.
+   *
+   * This is a helper method to safely access complex nested configuration objects
+   * with proper TypeScript type checking.
+   *
+   * @param serviceName The name of the service (e.g., 'walletui')
+   * @param paramName The parameter name that contains the nested object (e.g., 'config')
+   *                  Pass an empty string to get the entire service configuration.
+   * @returns The typed nested configuration object or undefined if not found
+   *
+   * @example
+   * // Get a typed UI kit configuration:
+   * const uiConfig = appConfigService.getTypedNestedConfig<UiKitConfiguration>('walletui', 'config');
+   * if (uiConfig) {
+   *   console.log(uiConfig.kitName); // Properly typed
+   * }
+   *
+   * // Get entire service configuration:
+   * const allAnalytics = appConfigService.getTypedNestedConfig<AnalyticsConfig>('analytics', '');
+   */
+  getTypedNestedConfig<T extends object>(serviceName: string, paramName: string): T | undefined;
+  /**
+   * Checks if a nested configuration exists and has a specific property.
+   *
+   * @param serviceName The name of the service
+   * @param paramName The parameter name containing the nested object
+   * @param propName The property name to check for
+   * @returns True if the property exists in the nested configuration
+   *
+   * @example
+   * if (appConfigService.hasNestedConfigProperty('walletui', 'config', 'showInjectedConnector')) {
+   *   // Do something when the property exists
+   * }
+   */
+  hasNestedConfigProperty(serviceName: string, paramName: string, propName: string): boolean;
+  /**
+   * Gets wallet UI configuration for a specific ecosystem.
+   * Uses ecosystem-namespaced format with optional default fallback.
+   *
+   * @param ecosystemId The ecosystem ID (e.g., 'stellar', 'evm', 'solana')
+   * @returns The wallet UI configuration for the ecosystem, or undefined
+   *
+   * @example
+   * Configuration format:
+   * {
+   *   "globalServiceConfigs": {
+   *     "walletui": {
+   *       "stellar": { "kitName": "stellar-wallets-kit", "kitConfig": {} },
+   *       "evm": { "kitName": "rainbowkit", "kitConfig": {} },
+   *       "default": { "kitName": "custom", "kitConfig": {} }
+   *     }
+   *   }
+   * }
+   * const stellarConfig = appConfigService.getWalletUIConfig('stellar');
+   */
+  getWalletUIConfig<T extends object = {
+    kitName: UiKitName;
+    kitConfig?: Record<string, unknown>;
+  }>(ecosystemId?: string): T | undefined;
+}
+declare const appConfigService: AppConfigService;
+//#endregion
+//#region src/UserRpcConfigService.d.ts
+type RpcConfigEventType = 'rpc-config-changed' | 'rpc-config-cleared';
+interface RpcConfigEvent {
+  type: RpcConfigEventType;
+  networkId: string;
+  config?: UserRpcProviderConfig;
+}
+/**
+ * Service for managing user-configured RPC endpoints.
+ * Stores RPC configurations in localStorage for persistence across sessions.
+ */
+declare class UserRpcConfigService {
+  private static readonly STORAGE_PREFIX;
+  private static readonly eventListeners;
+  /**
+   * Emits an RPC configuration event to all registered listeners
+   */
+  private static emitEvent;
+  /**
+   * Subscribes to RPC configuration changes for a specific network or all networks
+   * @param networkId The network identifier or '*' for all networks
+   * @param listener The callback to invoke when RPC config changes
+   * @returns Unsubscribe function
+   */
+  static subscribe(networkId: string, listener: (event: RpcConfigEvent) => void): () => void;
+  /**
+   * Saves a user RPC configuration for a specific network.
+   * @param networkId The network identifier
+   * @param config The RPC configuration to save
+   */
+  static saveUserRpcConfig(networkId: string, config: UserRpcProviderConfig): void;
+  /**
+   * Retrieves a user RPC configuration for a specific network.
+   * @param networkId The network identifier
+   * @returns The stored configuration or null if not found
+   */
+  static getUserRpcConfig(networkId: string): UserRpcProviderConfig | null;
+  /**
+   * Clears a user RPC configuration for a specific network.
+   * @param networkId The network identifier
+   */
+  static clearUserRpcConfig(networkId: string): void;
+  /**
+   * Clears all user RPC configurations.
+   */
+  static clearAllUserRpcConfigs(): void;
+}
+declare const userRpcConfigService: typeof UserRpcConfigService;
+//#endregion
+//#region src/UserExplorerConfigService.d.ts
+type ExplorerConfigEventType = 'explorer-config-changed' | 'explorer-config-cleared';
+interface ExplorerConfigEvent {
+  type: ExplorerConfigEventType;
+  networkId: string;
+  config?: UserExplorerConfig;
+}
+/**
+ * Service for managing user-configured block explorer endpoints and API keys.
+ * Stores explorer configurations in localStorage for persistence across sessions.
+ */
+declare class UserExplorerConfigService {
+  private static readonly STORAGE_PREFIX;
+  private static readonly eventListeners;
+  /**
+   * Emits an explorer configuration event to all registered listeners
+   */
+  private static emitEvent;
+  /**
+   * Subscribes to explorer configuration changes for a specific network or all networks
+   * @param networkId The network identifier or '*' for all networks
+   * @param listener The callback to invoke when explorer config changes
+   * @returns Unsubscribe function
+   */
+  static subscribe(networkId: string, listener: (event: ExplorerConfigEvent) => void): () => void;
+  /**
+   * Saves a user explorer configuration for a specific network.
+   * @param networkId The network identifier
+   * @param config The explorer configuration to save
+   */
+  static saveUserExplorerConfig(networkId: string, config: UserExplorerConfig): void;
+  /**
+   * Retrieves a user explorer configuration for a specific network.
+   * First checks for global settings, then falls back to network-specific settings.
+   * @param networkId The network identifier
+   * @returns The stored configuration or null if not found
+   */
+  static getUserExplorerConfig(networkId: string): UserExplorerConfig | null;
+  /**
+   * Clears a user explorer configuration for a specific network.
+   * @param networkId The network identifier
+   */
+  static clearUserExplorerConfig(networkId: string): void;
+  /**
+   * Clears all user explorer configurations.
+   */
+  static clearAllUserExplorerConfigs(): void;
+  /**
+   * Gets all network IDs that have explorer configurations.
+   * @returns Array of network IDs
+   */
+  static getConfiguredNetworkIds(): string[];
+}
+declare const userExplorerConfigService: typeof UserExplorerConfigService;
+//#endregion
+//#region src/UserNetworkServiceConfigService.d.ts
+/**
+ * Event types emitted by UserNetworkServiceConfigService
+ */
+type ServiceConfigEventType = 'service-config-changed' | 'service-config-cleared';
+/**
+ * Event emitted when a service configuration changes or is cleared.
+ * Used for subscribing to configuration updates across the application.
+ *
+ * @interface ServiceConfigEvent
+ */
+interface ServiceConfigEvent {
+  /** Type of event: config changed or cleared */
+  type: ServiceConfigEventType;
+  /** Network ID for which the configuration changed */
+  networkId: string;
+  /** Service ID (e.g., 'rpc', 'explorer', 'contract-definitions') */
+  serviceId: string;
+  /** The new configuration data (only present for 'service-config-changed' events) */
+  config?: Record<string, unknown>;
+}
+/**
+ * Service for managing user-defined network service configurations.
+ *
+ * This service provides a generic, chain-agnostic way to store and retrieve
+ * per-network, per-service user configurations.
+ *
+ * Configurations are stored in localStorage with the key format:
+ * `tfb_service_config_{serviceId}__{networkId}`
+ *
+ * @example
+ * ```typescript
+ * // Save RPC configuration for Sepolia
+ * userNetworkServiceConfigService.save('ethereum-sepolia', 'rpc', {
+ *   rpcUrl: 'https://sepolia.infura.io/v3/your-key'
+ * });
+ *
+ * // Retrieve configuration
+ * const config = userNetworkServiceConfigService.get('ethereum-sepolia', 'rpc');
+ *
+ * // Subscribe to changes
+ * const unsubscribe = userNetworkServiceConfigService.subscribe(
+ *   'ethereum-sepolia',
+ *   'rpc',
+ *   (event) => {
+ *     console.log('Config changed:', event.config);
+ *   }
+ * );
+ * ```
+ *
+ * @class UserNetworkServiceConfigService
+ */
+declare class UserNetworkServiceConfigService {
+  private static readonly STORAGE_PREFIX;
+  private static readonly listeners;
+  /**
+   * Generates a localStorage key for a network-service combination.
+   *
+   * @private
+   * @param networkId - The network ID
+   * @param serviceId - The service ID
+   * @returns The storage key string
+   */
+  private static key;
+  /**
+   * Subscribes to configuration change events for a specific network and/or service.
+   *
+   * Use '*' as a wildcard to listen to all networks or all services.
+   * The listener will be called whenever a matching configuration changes or is cleared.
+   *
+   * @param networkId - Network ID to listen to, or '*' for all networks
+   * @param serviceId - Service ID to listen to, or '*' for all services
+   * @param listener - Callback function to invoke when matching events occur
+   * @returns Unsubscribe function to remove the listener
+   *
+   * @example
+   * ```typescript
+   * // Listen to all RPC config changes across all networks
+   * const unsubscribe = userNetworkServiceConfigService.subscribe('*', 'rpc', (event) => {
+   *   console.log(`${event.networkId} RPC config changed`);
+   * });
+   *
+   * // Later, unsubscribe
+   * unsubscribe();
+   * ```
+   */
+  static subscribe(networkId: string | '*', serviceId: string | '*', listener: (event: ServiceConfigEvent) => void): () => void;
+  /**
+   * Emits an event to all matching subscribers.
+   * Subscribers are matched based on exact network/service IDs or wildcards.
+   *
+   * @private
+   * @param event - The event to emit
+   */
+  private static emit;
+  /**
+   * Saves a service configuration for a specific network.
+   *
+   * The configuration is stored in localStorage and all matching subscribers
+   * are notified via a 'service-config-changed' event.
+   *
+   * @param networkId - The network ID (e.g., 'ethereum-sepolia')
+   * @param serviceId - The service ID (e.g., 'rpc', 'explorer', 'contract-definitions')
+   * @param config - The configuration object to save
+   *
+   * @example
+   * ```typescript
+   * userNetworkServiceConfigService.save('ethereum-sepolia', 'rpc', {
+   *   rpcUrl: 'https://sepolia.infura.io/v3/your-key'
+   * });
+   * ```
+   */
+  static save(networkId: string, serviceId: string, config: Record<string, unknown>): void;
+  /**
+   * Retrieves a saved service configuration for a specific network.
+   *
+   * @param networkId - The network ID (e.g., 'ethereum-sepolia')
+   * @param serviceId - The service ID (e.g., 'rpc', 'explorer', 'contract-definitions')
+   * @returns The configuration object, or null if not found or if retrieval fails
+   *
+   * @example
+   * ```typescript
+   * const config = userNetworkServiceConfigService.get('ethereum-sepolia', 'rpc');
+   * if (config) {
+   *   console.log('RPC URL:', config.rpcUrl);
+   * }
+   * ```
+   */
+  static get(networkId: string, serviceId: string): Record<string, unknown> | null;
+  /**
+   * Clears a saved service configuration for a specific network.
+   *
+   * Removes the configuration from localStorage and notifies all matching subscribers
+   * via a 'service-config-cleared' event.
+   *
+   * @param networkId - The network ID (e.g., 'ethereum-sepolia')
+   * @param serviceId - The service ID (e.g., 'rpc', 'explorer', 'contract-definitions')
+   *
+   * @example
+   * ```typescript
+   * userNetworkServiceConfigService.clear('ethereum-sepolia', 'rpc');
+   * ```
+   */
+  static clear(networkId: string, serviceId: string): void;
+}
+/**
+ * Singleton instance of UserNetworkServiceConfigService.
+ * This is the preferred way to access the service.
+ *
+ * @example
+ * ```typescript
+ * import { userNetworkServiceConfigService } from '@openzeppelin/ui-utils';
+ *
+ * userNetworkServiceConfigService.save('ethereum-sepolia', 'rpc', { rpcUrl: '...' });
+ * ```
+ */
+declare const userNetworkServiceConfigService: typeof UserNetworkServiceConfigService;
+//#endregion
+//#region src/fieldDefaults.d.ts
+/**
+ * Get a default value for a field type.
+ * This is a chain-agnostic utility that provides appropriate default values
+ * based on the UI field type.
+ *
+ * @param fieldType - The UI field type
+ * @returns The appropriate default value for that field type
+ */
+declare function getDefaultValueForType<T extends FieldType>(fieldType: T): FieldValue<T>;
+//# sourceMappingURL=fieldDefaults.d.ts.map
+//#endregion
+//#region src/fieldValidation.d.ts
+/**
+ * Numeric type bounds configuration.
+ * Each adapter provides its own bounds map based on chain-specific type names.
+ */
+type NumericBoundsMap = Record<string, {
+  min?: number;
+  max?: number;
+}>;
+/**
+ * Enhances field validation with numeric bounds based on parameter type.
+ * Only applies bounds if they are not already set in the validation object.
+ *
+ * @param validation - Existing validation rules (may be undefined)
+ * @param parameterType - The blockchain parameter type (e.g., 'uint32', 'U32', 'Uint<0..255>')
+ * @param boundsMap - Chain-specific map of type names to min/max bounds
+ * @returns Enhanced validation object with numeric bounds applied
+ *
+ * @example
+ * ```typescript
+ * const stellarBounds = { U32: { min: 0, max: 4_294_967_295 } };
+ * const validation = enhanceNumericValidation(undefined, 'U32', stellarBounds);
+ * // Returns: { min: 0, max: 4_294_967_295 }
+ * ```
+ */
+declare function enhanceNumericValidation(validation: FieldValidation | undefined, parameterType: string, boundsMap: NumericBoundsMap): FieldValidation;
+//# sourceMappingURL=fieldValidation.d.ts.map
+//#endregion
+//#region src/typeguards.d.ts
+/**
+ * Type guard to check if a value is a non-null object (Record<string, unknown>).
+ * Useful for safely accessing properties on an 'unknown' type after this check.
+ * @param value - The value to check.
+ * @returns True if the value is a non-null object, false otherwise.
+ */
+declare function isRecordWithProperties(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a plain object (not an array, not null).
+ * This is useful for distinguishing between objects and arrays, since arrays are technically objects in JavaScript.
+ * @param value - The value to check.
+ * @returns True if the value is a plain object (not array, not null), false otherwise.
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=typeguards.d.ts.map
+//#endregion
+//#region src/cn.d.ts
+/**
+ * Combines class names using clsx and tailwind-merge.
+ * @param inputs - Class values to combine
+ * @returns Merged class name string
+ */
+declare function cn(...inputs: ClassValue[]): string;
+//# sourceMappingURL=cn.d.ts.map
+
+//#endregion
+//#region src/formatting.d.ts
+/**
+ * String and date formatting utility functions
+ * These utilities help with common formatting operations
+ */
+/**
+ * Truncates a string (like an Ethereum address) in the middle
+ * @param str The string to truncate
+ * @param startChars Number of characters to show at the beginning
+ * @param endChars Number of characters to show at the end
+ * @returns The truncated string with ellipsis in the middle
+ */
+declare function truncateMiddle(str: string, startChars?: number, endChars?: number): string;
+/**
+ * Formats a timestamp as a relative time string (e.g., "2h ago", "just now")
+ * @param date The date to format
+ * @returns A human-readable relative time string
+ */
+declare function formatTimestamp(date: Date): string;
+/**
+ * Detects whether a string contains hex-encoded or base64-encoded binary data.
+ * Useful for auto-detecting the encoding format of user inputs across blockchain adapters.
+ *
+ * @param value - The string to analyze
+ * @returns 'hex' if the string appears to be hexadecimal, 'base64' if it appears to be base64
+ *
+ * @example
+ * ```typescript
+ * detectBytesEncoding("48656c6c6f") // → 'hex'
+ * detectBytesEncoding("SGVsbG8=") // → 'base64'
+ * detectBytesEncoding("0x48656c6c6f") // → 'hex' (after stripping 0x prefix)
+ * ```
+ */
+declare function detectBytesEncoding(value: string): 'base64' | 'hex';
+//# sourceMappingURL=formatting.d.ts.map
+//#endregion
+//#region src/generateId.d.ts
+/**
+ * General utility functions, which are not specific to any blockchain
+ * It's important to keep these functions as simple as possible and avoid any
+ * dependencies from other packages.
+ */
+/**
+ * Generates a unique ID for form fields, components, etc.
+ * Uses crypto.getRandomValues() for browser-compatible random ID generation.
+ *
+ * @param prefix Optional prefix to add before the UUID
+ * @returns A string ID that is guaranteed to be unique
+ */
+declare function generateId(prefix?: string): string;
+//# sourceMappingURL=generateId.d.ts.map
+//#endregion
+//#region src/validators.d.ts
+/**
+ * URL validation utilities
+ */
+/**
+ * Validates if a string is a valid URL (supports http, https, and ftp protocols).
+ * Relies solely on the URL constructor for validation.
+ *
+ * @param urlString - The string to validate
+ * @returns True if the URL is valid, false otherwise
+ */
+declare function isValidUrl(urlString: string): boolean;
+/**
+ * Gets a user-friendly error message for invalid URLs.
+ *
+ * @returns Standard error message for invalid URLs
+ */
+declare function getInvalidUrlMessage(): string;
+//# sourceMappingURL=validators.d.ts.map
+//#endregion
+//#region src/async.d.ts
+/**
+ * Utility to add delay between operations
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the specified delay
+ */
+declare const delay: (ms: number) => Promise<void>;
+/**
+ * Executes operations in batches with rate limiting to prevent API overload
+ * @param operations - Array of functions that return promises
+ * @param batchSize - Number of operations to execute in parallel per batch (default: 2)
+ * @param delayMs - Delay in milliseconds between batches (default: 100)
+ * @returns Promise that resolves to an array of results from all operations
+ */
+declare function rateLimitedBatch<T>(operations: (() => Promise<T>)[], batchSize?: number, delayMs?: number): Promise<T[]>;
+/**
+ * Wraps a promise with a timeout. Rejects with a descriptive Error after timeoutMs.
+ *
+ * @param promise The promise to wrap
+ * @param timeoutMs Timeout in milliseconds
+ * @param label Optional label to include in the timeout error message
+ */
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label?: string): Promise<T>;
+/**
+ * Default concurrency limit for parallel operations.
+ * Set to a reasonable value that balances performance and service limits.
+ */
+declare const DEFAULT_CONCURRENCY_LIMIT = 10;
+/**
+ * Execute an array of promise-returning functions with a concurrency limit.
+ *
+ * Uses a worker pool approach that maintains up to `limit` concurrent operations.
+ * As soon as one operation completes, the next one starts immediately, maximizing
+ * throughput while respecting the concurrency limit.
+ *
+ * Results are returned in the same order as the input tasks, regardless of
+ * completion order.
+ *
+ * @param tasks Array of functions that return promises
+ * @param limit Maximum number of concurrent executions (default: 10)
+ * @returns Promise resolving to array of results in same order as input tasks
+ *
+ * @example
+ * ```typescript
+ * // Fetch 100 role members with max 10 concurrent RPC requests
+ * const tasks = memberIndices.map((index) => () => getRoleMember(contract, role, index));
+ * const members = await promiseAllWithLimit(tasks, 10);
+ * ```
+ */
+declare function promiseAllWithLimit<T>(tasks: (() => Promise<T>)[], limit?: number): Promise<T[]>;
+/**
+ * Execute an array of promise-returning functions with a concurrency limit,
+ * settling all promises (similar to Promise.allSettled but with concurrency control).
+ *
+ * Unlike promiseAllWithLimit, this function does not fail fast on errors.
+ * All tasks will be executed regardless of individual failures.
+ *
+ * @param tasks Array of functions that return promises
+ * @param limit Maximum number of concurrent executions (default: 10)
+ * @returns Promise resolving to array of settled results in same order as input tasks
+ *
+ * @example
+ * ```typescript
+ * const tasks = items.map((item) => () => fetchItem(item.id));
+ * const results = await promiseAllSettledWithLimit(tasks, 10);
+ *
+ * for (const result of results) {
+ *   if (result.status === 'fulfilled') {
+ *     console.log('Success:', result.value);
+ *   } else {
+ *     console.log('Failed:', result.reason);
+ *   }
+ * }
+ * ```
+ */
+declare function promiseAllSettledWithLimit<T>(tasks: (() => Promise<T>)[], limit?: number): Promise<PromiseSettledResult<T>[]>;
+//# sourceMappingURL=async.d.ts.map
+//#endregion
+//#region src/hash.d.ts
+/**
+ * Simple browser-compatible hash utilities
+ * These functions provide deterministic hashing for content comparison
+ * and are not intended for cryptographic purposes.
+ */
+/**
+ * Creates a simple hash from a string using a non-cryptographic algorithm
+ * Suitable for content comparison, caching keys, and quick fingerprinting
+ *
+ * @param str - The string to hash
+ * @returns A hexadecimal hash string (always positive)
+ *
+ * @example
+ * ```typescript
+ * const hash1 = simpleHash('{"name": "test"}');
+ * const hash2 = simpleHash('{"name": "test"}');
+ * console.log(hash1 === hash2); // true - deterministic
+ * ```
+ */
+declare function simpleHash(str: string): string;
+//# sourceMappingURL=hash.d.ts.map
+//#endregion
+//#region src/bytesValidation.d.ts
+/**
+ * Options for bytes validation
+ */
+interface BytesValidationOptions {
+  /**
+   * Whether to accept hex, base64, or both formats
+   */
+  acceptedFormats?: 'hex' | 'base64' | 'both';
+  /**
+   * Maximum length in bytes (not characters)
+   */
+  maxBytes?: number;
+  /**
+   * Whether to allow 0x prefix for hex values
+   */
+  allowHexPrefix?: boolean;
+}
+/**
+ * Result of bytes validation
+ */
+interface BytesValidationResult {
+  /**
+   * Whether the input is valid
+   */
+  isValid: boolean;
+  /**
+   * Error message if validation failed
+   */
+  error?: string;
+  /**
+   * Detected format of the input
+   */
+  detectedFormat?: 'hex' | 'base64';
+  /**
+   * Cleaned value (whitespace removed, prefix handled)
+   */
+  cleanedValue?: string;
+  /**
+   * Size in bytes
+   */
+  byteSize?: number;
+}
+/**
+ * Validates bytes input using the established validator.js library.
+ *
+ * This function provides comprehensive validation for blockchain bytes data including:
+ * - Hex encoding validation (with optional 0x prefix)
+ * - Base64 encoding validation
+ * - Byte length validation
+ * - Format detection
+ *
+ * @param value - The input string to validate
+ * @param options - Validation options
+ * @returns Validation result with details
+ *
+ * @example
+ * ```typescript
+ * validateBytes('48656c6c6f') // → { isValid: true, detectedFormat: 'hex', byteSize: 5 }
+ * validateBytes('SGVsbG8=') // → { isValid: true, detectedFormat: 'base64', byteSize: 5 }
+ * validateBytes('invalid') // → { isValid: false, error: '...' }
+ * ```
+ */
+declare function validateBytes(value: string, options?: BytesValidationOptions): BytesValidationResult;
+/**
+ * Simple validation function that returns boolean or error string
+ * (for compatibility with existing React Hook Form validation)
+ *
+ * @param value - The input string to validate
+ * @param options - Validation options
+ * @returns true if valid, error string if invalid
+ */
+declare function validateBytesSimple(value: string, options?: BytesValidationOptions): boolean | string;
+/**
+ * Extracts the size from a Bytes<N> type string, or returns undefined for dynamic Uint8Array
+ *
+ * @param type - Type string (e.g., "Bytes<32>", "Uint8Array", "bytes")
+ * @returns Size in bytes if fixed-size, undefined if dynamic
+ *
+ * @example
+ * ```typescript
+ * getBytesSize('Bytes<32>') // → 32
+ * getBytesSize('Bytes<64>') // → 64
+ * getBytesSize('Uint8Array') // → undefined
+ * getBytesSize('bytes') // → undefined
+ * ```
+ */
+declare function getBytesSize(type: string): number | undefined;
+//# sourceMappingURL=bytesValidation.d.ts.map
+//#endregion
+//#region src/bytesConversion.d.ts
+/**
+ * Cross-platform bytes conversion utilities that work in both browser and Node.js
+ * without requiring Buffer polyfills.
+ */
+/**
+ * Convert a hex string to Uint8Array using native browser APIs
+ * @param hex - Hex string (with or without 0x prefix)
+ * @returns Uint8Array representation
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert a base64 string to Uint8Array using native browser APIs
+ * Handles data URLs by stripping the prefix
+ * @param base64 - Base64 encoded string (with optional data URL prefix)
+ * @returns Uint8Array representation
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Convert Uint8Array to hex string
+ * @param bytes - Uint8Array to convert
+ * @param withPrefix - Whether to include '0x' prefix
+ * @returns Hex string representation
+ */
+declare function bytesToHex(bytes: Uint8Array, withPrefix?: boolean): string;
+/**
+ * Convert string to bytes based on detected encoding (hex or base64)
+ * @param value - The string value to convert
+ * @param encoding - The detected encoding type
+ * @returns Uint8Array representation
+ */
+declare function stringToBytes(value: string, encoding: 'hex' | 'base64'): Uint8Array;
+//# sourceMappingURL=bytesConversion.d.ts.map
+//#endregion
+//#region src/environment.d.ts
+/**
+ * Utility functions for environment detection
+ */
+/**
+ * Check if the application is running in development or test environment
+ * @returns True if NODE_ENV is 'development' or 'test'
+ */
+declare function isDevelopmentOrTestEnvironment(): boolean;
+/**
+ * Check if the application is running in production environment
+ * @returns True if NODE_ENV is 'production'
+ */
+declare function isProductionEnvironment(): boolean;
+//# sourceMappingURL=environment.d.ts.map
+//#endregion
+//#region src/RouterService.d.ts
+/**
+ * RouterService
+ *
+ * Minimal wrapper to abstract routing. This avoids coupling the app to a
+ * specific router implementation and allows future swaps.
+ */
+interface RouterService {
+  /** Returns the current location href (string form). */
+  currentLocation(): string;
+  /** Returns the value of a query parameter or null if not present. */
+  getParam(name: string): string | null;
+  /** Navigates to a path (client-side when router is present; falls back to location). */
+  navigate(path: string): void;
+}
+/**
+ * Singleton instance for global consumption.
+ */
+declare const routerService: RouterService;
+//# sourceMappingURL=RouterService.d.ts.map
+
+//#endregion
+//#region src/AnalyticsService.d.ts
+/**
+ * Google Analytics service for tracking user interactions.
+ * Manages Google Analytics initialization and event tracking.
+ * Only active when the analytics_enabled feature flag is true.
+ *
+ * This is a generic service that provides core analytics functionality.
+ * App-specific tracking methods should be implemented in app-level hooks
+ * that use the generic `trackEvent` method.
+ *
+ * @example
+ * ```typescript
+ * // Initialize analytics (typically done once at app startup)
+ * AnalyticsService.initialize('G-XXXXXXXXXX');
+ *
+ * // Track a custom event
+ * AnalyticsService.trackEvent('button_clicked', { button_name: 'submit' });
+ *
+ * // Track page view
+ * AnalyticsService.trackPageView('Dashboard', '/dashboard');
+ * ```
+ */
+declare class AnalyticsService {
+  private static initialized;
+  /**
+   * Initialize Google Analytics
+   * @param tagId - Google Analytics tag ID (e.g., G-N3DZK5FCT1)
+   */
+  static initialize(tagId: string): void;
+  /**
+   * Check if analytics is enabled via feature flag
+   */
+  static isEnabled(): boolean;
+  /**
+   * Reset the analytics service state (primarily for testing)
+   */
+  static reset(): void;
+  /**
+   * Generic event tracking method.
+   * Use this to track any custom event with arbitrary parameters.
+   *
+   * @param eventName - Name of the event (e.g., 'button_clicked', 'form_submitted')
+   * @param parameters - Key-value pairs of event parameters
+   *
+   * @example
+   * ```typescript
+   * AnalyticsService.trackEvent('ecosystem_selected', { ecosystem: 'evm' });
+   * AnalyticsService.trackEvent('wizard_step', { step_number: 2, step_name: 'configure' });
+   * ```
+   */
+  static trackEvent(eventName: string, parameters: Record<string, string | number>): void;
+  /**
+   * Track page view event.
+   * Common event shared across all apps.
+   *
+   * @param pageName - Human-readable name of the page
+   * @param pagePath - URL path of the page
+   *
+   * @example
+   * ```typescript
+   * AnalyticsService.trackPageView('Dashboard', '/dashboard');
+   * ```
+   */
+  static trackPageView(pageName: string, pagePath: string): void;
+  /**
+   * Track network selection event.
+   * Common event shared across all apps that involve network selection.
+   *
+   * @param networkId - Selected network ID
+   * @param ecosystem - Ecosystem the network belongs to (e.g., 'evm', 'stellar')
+   *
+   * @example
+   * ```typescript
+   * AnalyticsService.trackNetworkSelection('ethereum-mainnet', 'evm');
+   * ```
+   */
+  static trackNetworkSelection(networkId: string, ecosystem: string): void;
+  /**
+   * Load the Google Analytics gtag script
+   * @private
+   */
+  private static loadGtagScript;
+  /**
+   * Initialize gtag with configuration
+   * @private
+   */
+  private static initializeGtag;
+}
+/**
+ * Type declarations for Google Analytics gtag
+ */
+
+sideEffect();
+
+//#endregion
+//#region src/deepLink.d.ts
+/**
+ * Deep-link utilities (chain-agnostic)
+ *
+ * NOTE: Stub implementation for TDD. Tests will drive full behavior in Phase 3.3.
+ */
+type DeepLinkParams = Record<string, string>;
+/**
+ * Parses URL query parameters into a key-value object.
+ * @returns Object containing all URL query parameters
+ */
+declare function parseDeepLink(): DeepLinkParams;
+/**
+ * Gets the forced service from deep link parameters.
+ * @param params - Deep link parameters object
+ * @returns Service name if specified, null otherwise
+ */
+declare function getForcedService(params: DeepLinkParams): string | null;
+/**
+ * Computes the effective provider preference based on priority order.
+ * @param input - Configuration object with provider options
+ * @returns The effective provider and its source
+ */
+declare function computeEffectiveProviderPreference(input: {
+  forcedService?: string | null;
+  uiSelection?: string | null;
+  appDefault?: string | null;
+  adapterDefaultOrder: readonly string[];
+}): {
+  effectiveProvider: string;
+  source: 'urlForced' | 'ui' | 'appConfig' | 'adapterDefault';
+};
+//# sourceMappingURL=deepLink.d.ts.map
+//#endregion
+//#region src/sanitize.d.ts
+/**
+ * Minimal HTML sanitizer for client-side rendering of adapter-provided notes.
+ *
+ * - Strips <script>/<style> blocks and closing tags
+ * - Removes inline event handlers (on*)
+ * - Neutralizes javascript: URLs in href/src
+ * - Whitelists a small set of tags: a,b,strong,i,em,code,br,ul,ol,li,p
+ *
+ * This utility is intentionally small and dependency-free. If we decide to
+ * allow richer HTML, we can swap this implementation with a vetted library
+ * (e.g., DOMPurify) behind the same function signature.
+ */
+declare function sanitizeHtml(html: string): string;
+//# sourceMappingURL=sanitize.d.ts.map
+//#endregion
+//#region src/access/snapshot.d.ts
+/**
+ * Validates an access snapshot structure
+ * @param snapshot The snapshot to validate
+ * @returns True if valid, false otherwise
+ */
+declare function validateSnapshot(snapshot: AccessSnapshot): boolean;
+/**
+ * Serializes an access snapshot to JSON string
+ * @param snapshot The snapshot to serialize
+ * @returns JSON string representation
+ * @throws Error if snapshot is invalid
+ */
+declare function serializeSnapshot(snapshot: AccessSnapshot): string;
+/**
+ * Deserializes a JSON string to an access snapshot
+ * @param json The JSON string to deserialize
+ * @returns Access snapshot object
+ * @throws Error if JSON is invalid or snapshot structure is invalid
+ */
+declare function deserializeSnapshot(json: string): AccessSnapshot;
+/**
+ * Creates an empty snapshot
+ * @returns Empty snapshot with no roles and no ownership
+ */
+declare function createEmptySnapshot(): AccessSnapshot;
+/**
+ * Finds a role assignment by role ID
+ * @param snapshot The snapshot to search
+ * @param roleId The role ID to find
+ * @returns The role assignment if found, undefined otherwise
+ */
+declare function findRoleAssignment(snapshot: AccessSnapshot, roleId: string): RoleAssignment | undefined;
+/**
+ * Checks if a snapshot has any roles
+ * @param snapshot The snapshot to check
+ * @returns True if snapshot has at least one role assignment
+ */
+declare function hasRoles(snapshot: AccessSnapshot): boolean;
+/**
+ * Checks if a snapshot has ownership information
+ * @param snapshot The snapshot to check
+ * @returns True if snapshot has ownership information
+ */
+declare function hasOwnership(snapshot: AccessSnapshot): boolean;
+/**
+ * Gets the total number of role members across all roles
+ * @param snapshot The snapshot to count
+ * @returns Total number of unique members across all roles
+ */
+declare function getTotalMemberCount(snapshot: AccessSnapshot): number;
+/**
+ * Gets all unique members across all roles
+ * @param snapshot The snapshot to extract members from
+ * @returns Array of unique member addresses
+ */
+declare function getAllMembers(snapshot: AccessSnapshot): string[];
+/**
+ * Compares two snapshots and returns differences
+ * @param snapshot1 First snapshot
+ * @param snapshot2 Second snapshot
+ * @returns Object describing differences
+ */
+declare function compareSnapshots(snapshot1: AccessSnapshot, snapshot2: AccessSnapshot): {
+  rolesAdded: RoleAssignment[];
+  rolesRemoved: RoleAssignment[];
+  rolesModified: Array<{
+    role: RoleIdentifier;
+    membersAdded: string[];
+    membersRemoved: string[];
+  }>;
+  ownershipChanged: boolean;
+};
+//# sourceMappingURL=snapshot.d.ts.map
+//#endregion
+//#region src/access/errors.d.ts
+/**
+ * Access Control Error Utilities
+ *
+ * Chain-agnostic helper functions for working with access control errors.
+ * These utilities can be used across any adapter that implements access control.
+ *
+ * Note: These utilities work with the AccessControlError types from @openzeppelin/ui-types
+ * but don't import them directly to avoid circular dependencies.
+ */
+/**
+ * Base interface for access control errors (matches the class in types package)
+ */
+interface AccessControlErrorLike extends Error {
+  readonly contractAddress?: string;
+}
+/**
+ * Type guard to check if an error is an AccessControlError
+ *
+ * @param error The error to check
+ * @returns True if the error has the AccessControlError structure
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await service.grantRole(...);
+ * } catch (error) {
+ *   if (isAccessControlError(error)) {
+ *     console.log('Access control error:', error.contractAddress);
+ *   }
+ * }
+ * ```
+ */
+declare function isAccessControlError(error: unknown): error is AccessControlErrorLike;
+/**
+ * Helper to safely extract error message from unknown error type
+ *
+ * @param error The error to extract message from
+ * @returns The error message string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   const message = getErrorMessage(error);
+ *   logger.error('Operation failed:', message);
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * Helper to create a user-friendly error message with full context
+ *
+ * This function formats an AccessControlError into a readable multi-line message
+ * that includes all relevant context (contract address, roles, operations, etc.).
+ *
+ * @param error The AccessControlError to format
+ * @returns Formatted error message string with all context
+ *
+ * @example
+ * ```typescript
+ * import { PermissionDenied } from '@openzeppelin/ui-types';
+ * import { formatAccessControlError } from '@openzeppelin/ui-utils';
+ *
+ * try {
+ *   await service.grantRole(...);
+ * } catch (error) {
+ *   if (error instanceof PermissionDenied) {
+ *     const formatted = formatAccessControlError(error);
+ *     showErrorToUser(formatted);
+ *   }
+ * }
+ * ```
+ *
+ * Output format:
+ * ```
+ * [ErrorName] Error message
+ * Contract: 0x123...
+ * [Additional context based on error type]
+ * ```
+ */
+declare function formatAccessControlError(error: AccessControlErrorLike): string;
+//#endregion
+export { AnalyticsService, AppConfigService, BytesValidationOptions, BytesValidationResult, ConfigLoadStrategy, DEFAULT_CONCURRENCY_LIMIT, DeepLinkParams, ExplorerConfigEvent, NumericBoundsMap, RouterService, RpcConfigEvent, ServiceConfigEvent, UserExplorerConfigService, UserNetworkServiceConfigService, UserRpcConfigService, addressesEqual, appConfigService, base64ToBytes, buildRequiredInputSnapshot, bytesToHex, cn, compareSnapshots, computeEffectiveProviderPreference, createEmptySnapshot, delay, deserializeSnapshot, detectBytesEncoding, enhanceNumericValidation, findRoleAssignment, formatAccessControlError, formatTimestamp, generateId, getAllMembers, getBytesSize, getDefaultValueForType, getErrorMessage, getForcedService, getInvalidUrlMessage, getMissingRequiredContractInputs, getTotalMemberCount, hasMissingRequiredContractInputs, hasOwnership, hasRoles, hexToBytes, isAccessControlError, isDevelopmentOrTestEnvironment, isPlainObject, isProductionEnvironment, isRecordWithProperties, isValidUrl, logger, normalizeAddress, parseDeepLink, promiseAllSettledWithLimit, promiseAllWithLimit, rateLimitedBatch, requiredSnapshotsEqual, routerService, sanitizeHtml, serializeSnapshot, simpleHash, stringToBytes, truncateMiddle, userExplorerConfigService, userNetworkServiceConfigService, userRpcConfigService, validateBytes, validateBytesSimple, validateSnapshot, withTimeout };
+//# sourceMappingURL=index-qy1AQMhr.d.ts.map