or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account-chain-state.mdadvanced-features.mdblockchain-data-reading.mdconfiguration.mdconnection-management.mdcontract-interactions.mdens-operations.mdevent-watching.mdindex.mdsigning-verification.mdtanstack-query.mdtransaction-management.md
tile.json

tessl/npm-wagmi--core

VanillaJS library for Ethereum blockchain interactions with reactive primitives and utilities for building Ethereum applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@wagmi/core@2.20.x

To install, run

npx @tessl/cli install tessl/npm-wagmi--core@2.20.0

index.mddocs/

@wagmi/core

@wagmi/core is a VanillaJS library for Ethereum blockchain interactions that provides reactive primitives and utilities for building Ethereum applications. It serves as the core foundation for the Wagmi ecosystem, offering comprehensive wallet connection management, contract interactions, transaction handling, and blockchain data fetching with full TypeScript support and framework-agnostic design.

Package Information

  • Package Name: @wagmi/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @wagmi/core viem

Core Imports

import { createConfig, http } from '@wagmi/core'
import { mainnet, sepolia } from '@wagmi/core/chains'

Standard action imports:

import { connect, disconnect, getAccount, getBalance } from '@wagmi/core'

Selective imports for tree-shaking:

import { connect } from '@wagmi/core/actions'
import { getBalanceQueryOptions } from '@wagmi/core/query'

For CommonJS:

const { createConfig, connect, getAccount } = require('@wagmi/core')

Basic Usage

import { createConfig, http, connect, getAccount, getBalance } from '@wagmi/core'
import { mainnet, sepolia } from '@wagmi/core/chains'
import { injected } from '@wagmi/core/connectors'

// 1. Create and configure wagmi
const config = createConfig({
  chains: [mainnet, sepolia],
  connectors: [injected()],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

// 2. Connect to wallet
await connect(config, { connector: injected() })

// 3. Get account information
const account = getAccount(config)
console.log('Connected account:', account.address)

// 4. Get account balance
const balance = await getBalance(config, {
  address: account.address,
})
console.log('Balance:', balance.formatted, balance.symbol)

Architecture

@wagmi/core is built around several key architectural patterns:

  • Config-first Design: Central Config object manages chains, connectors, and transports
  • Action-based API: Pure functions that take config as first parameter for all operations
  • Reactive State Management: Built on Zustand with automatic state synchronization
  • Modular Exports: Multiple entry points (/actions, /query, /chains) for optimal tree-shaking
  • Transport Abstraction: Pluggable transport layer supporting HTTP, WebSocket, and custom transports
  • Connector System: Extensible wallet connection system with built-in and custom connector support
  • Type Safety: Full TypeScript integration with generic type preservation and inference

Capabilities

Configuration & Setup

Core configuration system for initializing wagmi with chains, connectors, and transports. Essential for all wagmi applications.

function createConfig<
  chains extends readonly [Chain, ...Chain[]],
  transports extends Record<chains[number]['id'], Transport>
>(parameters: CreateConfigParameters<chains, transports>): Config<chains, transports>;

interface CreateConfigParameters<chains, transports> {
  chains: chains;
  connectors?: CreateConnectorFn[];
  transports: transports;
  storage?: Storage;
  ssr?: boolean;
  syncConnectedChain?: boolean;
  multiInjectedProviderDiscovery?: boolean;
}

Configuration & Setup

Connection Management

Wallet connection, disconnection, and network switching functionality. Handles wallet lifecycle and chain management.

function connect<config extends Config>(
  config: config,
  parameters: ConnectParameters<config>
): Promise<ConnectReturnType<config>>;

function disconnect(config: Config, parameters?: DisconnectParameters): Promise<DisconnectReturnType>;

function switchChain<config extends Config>(
  config: config,
  parameters: SwitchChainParameters<config>
): Promise<SwitchChainReturnType<config>>;

Connection Management

Account & Chain State

Access to current account information, chain details, and connection status. Essential for understanding application state.

function getAccount<config extends Config>(config: config): GetAccountReturnType<config>;

function getChainId<config extends Config>(config: config): GetChainIdReturnType<config>;

function getConnections<config extends Config>(config: config): GetConnectionsReturnType<config>;

interface GetAccountReturnType<config extends Config> {
  address?: Address;
  addresses?: readonly Address[];
  chain?: Chain;
  chainId?: number;
  connector?: Connector;
  isConnected: boolean;
  isConnecting: boolean;
  isDisconnected: boolean;
  isReconnecting: boolean;
  status: 'connected' | 'connecting' | 'disconnected' | 'reconnecting';
}

Account & Chain State

Blockchain Data Reading

Comprehensive blockchain data fetching including balances, blocks, transactions, and contract state. Core read operations for dApps.

function getBalance<config extends Config>(
  config: config,
  parameters: GetBalanceParameters<config>
): Promise<GetBalanceReturnType>;

function getBlock<config extends Config>(
  config: config,
  parameters?: GetBlockParameters<config>
): Promise<GetBlockReturnType>;

function getTransaction<config extends Config>(
  config: config,
  parameters: GetTransactionParameters<config>
): Promise<GetTransactionReturnType>;

interface GetBalanceReturnType {
  decimals: number;
  formatted: string;
  symbol: string;
  value: bigint;
}

Blockchain Data Reading

Contract Interactions

Smart contract reading, writing, simulation, and deployment. Complete contract interaction suite with type safety.

function readContract<config extends Config>(
  config: config,
  parameters: ReadContractParameters<config>
): Promise<ReadContractReturnType>;

function writeContract<config extends Config>(
  config: config,
  parameters: WriteContractParameters<config>
): Promise<WriteContractReturnType>;

function simulateContract<config extends Config>(
  config: config,
  parameters: SimulateContractParameters<config>
): Promise<SimulateContractReturnType>;

function deployContract<config extends Config>(
  config: config,
  parameters: DeployContractParameters<config>
): Promise<DeployContractReturnType>;

Contract Interactions

Transaction Management

Transaction sending, estimation, waiting, and monitoring. Complete transaction lifecycle management.

function sendTransaction<config extends Config>(
  config: config,
  parameters: SendTransactionParameters<config>
): Promise<SendTransactionReturnType>;

function estimateGas<config extends Config>(
  config: config,
  parameters: EstimateGasParameters<config>
): Promise<EstimateGasReturnType>;

function waitForTransactionReceipt<config extends Config>(
  config: config,
  parameters: WaitForTransactionReceiptParameters<config>
): Promise<WaitForTransactionReceiptReturnType>;

function prepareTransactionRequest<config extends Config>(
  config: config,
  parameters: PrepareTransactionRequestParameters<config>
): Promise<PrepareTransactionRequestReturnType>;

Transaction Management

Signing & Verification

Message and typed data signing with EIP-712 support. Essential for authentication and authorization flows.

function signMessage<config extends Config>(
  config: config,
  parameters: SignMessageParameters<config>
): Promise<SignMessageReturnType>;

function signTypedData<config extends Config>(
  config: config,
  parameters: SignTypedDataParameters<config>
): Promise<SignTypedDataReturnType>;

function verifyMessage<config extends Config>(
  config: config,
  parameters: VerifyMessageParameters<config>
): Promise<VerifyMessageReturnType>;

interface SignTypedDataParameters<config extends Config> {
  types: Record<string, Array<{ name: string; type: string }>>;
  primaryType: string;
  domain?: TypedDataDomain;
  message: Record<string, any>;
}

Signing & Verification

ENS Operations

Ethereum Name Service resolution, reverse resolution, and metadata retrieval. Complete ENS integration.

function getEnsAddress<config extends Config>(
  config: config,
  parameters: GetEnsAddressParameters<config>
): Promise<GetEnsAddressReturnType>;

function getEnsName<config extends Config>(
  config: config,
  parameters: GetEnsNameParameters<config>
): Promise<GetEnsNameReturnType>;

function getEnsAvatar<config extends Config>(
  config: config,
  parameters: GetEnsAvatarParameters<config>
): Promise<GetEnsAvatarReturnType>;

function getEnsText<config extends Config>(
  config: config,
  parameters: GetEnsTextParameters<config>
): Promise<GetEnsTextReturnType>;

ENS Operations

Event Watching & Subscriptions

Real-time event watching for accounts, chains, blocks, and contract events. Reactive programming support.

function watchAccount<config extends Config>(
  config: config,
  parameters: WatchAccountParameters<config>
): WatchAccountReturnType;

function watchChainId<config extends Config>(
  config: config,
  parameters: WatchChainIdParameters<config>
): WatchChainIdReturnType;

function watchContractEvent<config extends Config>(
  config: config,
  parameters: WatchContractEventParameters<config>
): WatchContractEventReturnType;

function watchBlockNumber<config extends Config>(
  config: config,
  parameters: WatchBlockNumberParameters<config>
): WatchBlockNumberReturnType;

type WatchAccountReturnType = () => void; // Unsubscribe function

Event Watching & Subscriptions

TanStack Query Integration

First-class TanStack Query support with query options, mutation options, and caching strategies.

function getBalanceQueryOptions<config extends Config>(
  config: config,
  options: GetBalanceOptions<config>
): QueryOptions<GetBalanceData, GetBalanceErrorType>;

function connectMutationOptions<config extends Config>(
  config: config
): MutationOptions<ConnectData, ConnectErrorType, ConnectVariables>;

// Query key generation
function getBalanceQueryKey(parameters?: GetBalanceParameters): GetBalanceQueryKey;

// Utility functions
function hashFn(queryKey: QueryKey): string;
function structuralSharing<T>(oldData: T | undefined, newData: T): T;

TanStack Query Integration

Advanced Features

Advanced capabilities including EIP-5792 batch calls, wallet capabilities, code generation utilities, and experimental features.

function getCapabilities<config extends Config>(
  config: config,
  parameters?: GetCapabilitiesParameters<config>
): Promise<GetCapabilitiesReturnType>;

function sendCalls<config extends Config>(
  config: config,
  parameters: SendCallsParameters<config>
): Promise<SendCallsReturnType>;

function createReadContract<TAbi extends Abi>(
  parameters: CreateReadContractParameters<TAbi>
): CreateReadContractReturnType<TAbi>;

function createConnector<TProvider>(
  connectorFn: CreateConnectorFn<TProvider>
): CreateConnectorFn<TProvider>;

Advanced Features

Client Access

Access to Viem clients for advanced operations and direct blockchain interactions.

function getConnectorClient<config extends Config>(
  config: config,
  parameters?: GetConnectorClientParameters<config>
): Promise<GetConnectorClientReturnType<config>>;

function getWalletClient<config extends Config>(
  config: config,
  parameters?: GetWalletClientParameters<config>
): Promise<GetWalletClientReturnType<config>>;

interface GetConnectorClientParameters<config extends Config> {
  /** Chain ID */
  chainId?: config['chains'][number]['id'];
  /** Specific connector to use */
  connector?: Connector;
  /** Account to use (optional) */
  account?: Address | Account | null;
}

interface GetWalletClientParameters<config extends Config> {
  /** Chain ID */
  chainId?: config['chains'][number]['id'];
  /** Specific connector to use */
  connector?: Connector;
  /** Account to use (optional) */
  account?: Address | Account | null;
}

Error Handling

@wagmi/core provides structured error handling with specific error types:

class BaseError extends Error {
  name: string;
  message: string;
  cause?: unknown;
}

class ConnectorNotFoundError extends BaseError {}
class ChainNotConfiguredError extends BaseError {}
class ConnectorNotConnectedError extends BaseError {}

All async functions can throw typed errors that should be handled appropriately in your application.

Core Types

interface Config<
  chains extends readonly Chain[] = readonly Chain[],
  transports extends Record<chains[number]['id'], Transport> = Record<chains[number]['id'], Transport>
> {
  chains: chains;
  connectors: readonly Connector[];
  transports: transports;
  storage: Storage;
}

interface Chain {
  id: number;
  name: string;
  nativeCurrency: {
    name: string;
    symbol: string;
    decimals: number;
  };
  rpcUrls: {
    default: { http: readonly string[] };
    public?: { http: readonly string[] };
  };
  blockExplorers?: {
    default: { name: string; url: string };
  };
}

interface Connector {
  id: string;
  name: string;
  type: string;
  connect(parameters?: unknown): Promise<{
    accounts: readonly Address[];
    chainId: number;
  }>;
  disconnect(): Promise<void>;
  getAccounts(): Promise<readonly Address[]>;
  getChainId(): Promise<number>;
}

Utilities

@wagmi/core provides several utility functions for common operations:

Serialization & Deserialization

Safe JSON serialization/deserialization with support for BigInt and Map types, handling circular references.

function serialize(
  value: any,
  replacer?: (key: string, value: any) => any,
  indent?: number,
  circularReplacer?: (key: string, value: any, referenceKey: string) => any
): string;

function deserialize<T>(
  value: string, 
  reviver?: (key: string, value: any) => any
): T;

Deep Equality

Fast deep equality comparison for objects and arrays.

function deepEqual(a: any, b: any): boolean;

Version

Package version string for debugging and compatibility checks.

const version: string; // Current: "2.20.3"