Configuration & Setup

/**
 * Creates wagmi configuration with chains, connectors, and transports
 * @param parameters - Configuration parameters
 * @returns Configured wagmi instance
 */
function createConfig<
  const chains extends readonly [Chain, ...Chain[]],
  transports extends Record<chains[number]['id'], Transport>,
  const connectorFns extends readonly CreateConnectorFn[]
>(
  parameters: CreateConfigParameters<chains, transports, connectorFns>
): Config<chains, transports, connectorFns>;

interface CreateConfigParameters<chains, transports, connectorFns> {
  /** Array of blockchain networks to support */
  chains: chains;
  /** Array of wallet connector functions */
  connectors?: connectorFns;
  /** Transport configuration for each chain */
  transports: transports;
  /** Storage for persisting wagmi state */
  storage?: Storage;
  /** Enable server-side rendering support */
  ssr?: boolean;
  /** Sync connected chain with connector's active chain */
  syncConnectedChain?: boolean;
  /** Enable multi-injected provider discovery (EIP-6963) */
  multiInjectedProviderDiscovery?: boolean;
}

interface Config<chains, transports, connectorFns> {
  chains: chains;
  connectors: readonly Connector[];
  transports: transports;
  storage: Storage;
  state: State;
  subscribe: (listener: () => void) => () => void;
  getClient: (parameters?: { chainId?: number }) => Client;
}

import { createConfig, http } from '@wagmi/core'
import { mainnet, sepolia, polygon } from '@wagmi/core/chains'
import { injected, metaMask, walletConnect } from '@wagmi/core/connectors'

const config = createConfig({
  chains: [mainnet, sepolia, polygon],
  connectors: [
    injected(),
    metaMask(),
    walletConnect({ projectId: 'your-project-id' }),
  ],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http('https://sepolia.infura.io/v3/your-key'),
    [polygon.id]: http('https://polygon-rpc.com'),
  },
  ssr: true,
})

/**
 * Creates storage for persisting wagmi state
 * @param parameters - Storage configuration
 * @returns Storage instance
 */
function createStorage(parameters?: CreateStorageParameters): Storage;

interface CreateStorageParameters {
  /** Storage backend (defaults to localStorage) */
  storage?: {
    getItem(key: string): string | null;
    setItem(key: string, value: string): void;
    removeItem(key: string): void;
  };
  /** Storage key prefix */
  key?: string;
  /** Serialization functions */
  serialize?: (value: any) => string;
  deserialize?: (value: string) => any;
}

interface Storage {
  getItem<T>(key: string, defaultValue?: T): T | null;
  setItem<T>(key: string, value: T): void;
  removeItem(key: string): void;
}

/** No-op storage implementation */
const noopStorage: Storage;

import { createStorage } from '@wagmi/core'

// Custom storage
const customStorage = createStorage({
  storage: window.sessionStorage, // Use sessionStorage instead of localStorage
  key: 'my-app-wagmi',
})

// Use in config
const config = createConfig({
  // ... other config
  storage: customStorage,
})

/**
 * Hydrates config with initial state for SSR
 * @param config - Wagmi configuration
 * @param initialState - Initial state to hydrate with
 */
function hydrate<config extends Config>(
  config: config,
  initialState: PartializedState
): void;

interface PartializedState {
  chainId?: number;
  connections?: Map<string, Connection>;
  current?: string;
  status?: 'connected' | 'connecting' | 'disconnected' | 'reconnecting';
}

import { createConfig, hydrate } from '@wagmi/core'

const config = createConfig({
  // ... config
  ssr: true,
})

// On client, hydrate with server state
if (typeof window !== 'undefined') {
  hydrate(config, window.__WAGMI_STATE__)
}

/**
 * Injected wallet connector (MetaMask, browser wallets)
 * @param parameters - Injected connector options
 * @returns Connector function
 */
function injected(parameters?: InjectedParameters): CreateConnectorFn;

interface InjectedParameters {
  /** Target specific injected wallets */
  target?: 
    | 'metaMask'
    | 'coinbaseWallet' 
    | 'trust'
    | (() => { id: string; name: string; provider?: any });
  /** Shimmed disconnect behavior */
  shimDisconnect?: boolean;
}

/**
 * Mock connector for testing
 * @param parameters - Mock connector options
 * @returns Connector function for testing
 */
function mock(parameters: MockParameters): CreateConnectorFn;

interface MockParameters {
  /** Mock accounts */
  accounts: readonly Address[];
  /** Mock chain ID */
  chainId?: number;
  /** Mock features */
  features?: {
    connectError?: boolean;
    reconnect?: boolean;
    signMessageError?: boolean;
    switchChainError?: boolean;
  };
}

/**
 * Creates a custom connector
 * @param connectorFn - Connector implementation function
 * @returns Custom connector function
 */
function createConnector<TProvider, TOptions = any>(
  connectorFn: (config: CreateConnectorFn<TProvider, TOptions>) => Connector<TProvider>
): CreateConnectorFn<TProvider, TOptions>;

interface CreateConnectorFn<TProvider = any, TOptions = any> {
  (options?: TOptions): (config: Config) => Connector<TProvider>;
}

interface Connector<TProvider = any> {
  id: string;
  name: string;
  type: string;
  icon?: string;
  rdns?: string | readonly string[];
  
  setup?(): Promise<void>;
  connect(parameters?: { chainId?: number; isReconnecting?: boolean }): Promise<{
    accounts: readonly Address[];
    chainId: number;
  }>;
  disconnect(): Promise<void>;
  getAccounts(): Promise<readonly Address[]>;
  getChainId(): Promise<number>;
  getProvider(): Promise<TProvider>;
  isAuthorized(): Promise<boolean>;
  switchChain?(parameters: { chainId: number }): Promise<Chain>;
  
  onAccountsChanged?(accounts: string[]): void;
  onChainChanged?(chainId: string | number): void;
  onConnect?(connectInfo: { chainId: string | number }): void;
  onDisconnect?(error?: { code: number; message: string }): void;
  onMessage?(message: { type: string; data?: any }): void;
}

interface ConnectorEventMap {
  change: {
    accounts?: readonly Address[];
    chainId?: number;
  };
  connect: {
    accounts: readonly Address[];
    chainId: number;
  };
  disconnect: void;
  error: { error: Error };
  message: { message: any };
}

import { createConnector } from '@wagmi/core'

// Custom WalletConnect-style connector example
const customWalletConnector = createConnector((config) => ({
  id: 'custom-wallet',
  name: 'Custom Wallet',
  type: 'injected',
  
  async connect() {
    // Custom connection logic
    const provider = await this.getProvider()
    const accounts = await provider.request({ method: 'eth_requestAccounts' })
    const chainId = await provider.request({ method: 'eth_chainId' })
    
    return {
      accounts: accounts,
      chainId: parseInt(chainId, 16),
    }
  },
  
  async getProvider() {
    // Return custom provider
    return window.customWallet
  },
  
  // ... other required methods
}))

const config = createConfig({
  connectors: [customWalletConnector()],
  // ... rest of config
})

/**
 * Fallback transport that tries multiple transports in order
 * @param transports - Array of transports to try
 * @param config - Fallback configuration
 * @returns Fallback transport
 */
function fallback<TTransport extends Transport>(
  transports: TTransport[],
  config?: FallbackConfig
): FallbackTransport<TTransport>;

interface FallbackConfig {
  /** Number of times to retry */
  retryCount?: number;
  /** Delay between retries in ms */
  retryDelay?: number;
  /** Rank transports by priority */
  rank?: boolean;
}

/**
 * Unstable connector transport (experimental)
 * @param config - Connector transport configuration
 * @returns Connector transport
 */
function unstable_connector(config: ConnectorTransportConfig): ConnectorTransport;

interface ConnectorTransportConfig {
  /** Connector to use for transport */
  connector: Connector;
}

// Re-exported from viem
function http(url?: string, config?: HttpTransportConfig): HttpTransport;
function webSocket(url: string, config?: WebSocketTransportConfig): WebSocketTransport;
function custom<TProvider>(provider: TProvider): CustomTransport;

/**
 * Cookie-based storage for SSR applications
 */
const cookieStorage: Storage;

/**
 * Converts cookie to initial state for hydration
 * @param cookie - Cookie string
 * @returns Initial state
 */
function cookieToInitialState(cookie?: string): PartializedState | undefined;

/**
 * Parses cookie string into key-value pairs
 * @param cookie - Cookie string to parse
 * @returns Parsed cookie object
 */
function parseCookie(cookie: string): Record<string, string>;

/**
 * Extracts RPC URLs from transport configuration
 * @param transports - Transport configuration
 * @returns Map of chain IDs to RPC URLs
 */
function extractRpcUrls(transports: Record<number, Transport>): Record<number, string[]>;

/**
 * Normalizes chain ID to number format
 * @param chainId - Chain ID in various formats
 * @returns Normalized chain ID as number
 */
function normalizeChainId(chainId: string | number | bigint): number;