viem

Viem is a low-level TypeScript library that provides a set of modular abstractions for building applications on Ethereum and EVM-compatible chains. Unlike monolithic SDKs, it offers granular, tree-shakable modules for specific tasks like reading chain data (public actions), executing transactions (wallet actions), or interacting with smart contracts. This architecture allows developers to import only the functionality they need, resulting in significantly smaller bundle sizes and improved application performance.

The library is built with type safety and developer experience as core principles. It leverages TypeScript to its fullest, providing autocomplete, compile-time error checking, and precise type inference for contract ABIs, RPC methods, and transaction parameters. Viem abstracts away the complexity of direct RPC calls, handling tasks like ABI encoding/decoding, gas estimation, and EIP-1559 transaction formatting internally, which reduces boilerplate code and potential errors.

A key architectural feature is its separation of clients and actions. Developers instantiate a client (e.g., createPublicClient, createWalletClient) configured for a specific chain and transport (HTTP, WebSocket, IPC). They then use imported action functions (e.g., readContract, sendTransaction) that operate on that client. This clear separation of concerns makes code more testable and composable. Viem also includes first-class support for WalletConnect, ENS, and advanced patterns like account abstraction and multicall.

In practice, viem is often compared to and used alongside Ethers.js, but it is architecturally distinct. While Ethers.js is a more opinionated, all-in-one toolkit, viem adopts a minimalist, functional approach. It is the recommended library for frameworks like Wagmi, which uses viem under the hood for its core blockchain interactions. Its efficiency and precision make it particularly well-suited for both browser-based dApps and backend Node.js services requiring high-performance blockchain connectivity.

The term viem (pronounced vye-em) is a coined word, not an acronym, created by the project's founder, Matteo Gaggia. It was selected for its brevity, ease of recall, and the absence of prior associations in the blockchain space, allowing the project to establish its own identity. The name's clean, technical sound aligns with the library's core philosophy of providing a lean, modular, and type-safe interface for Ethereum interaction.

The project originated in 2022 as a direct evolution from and successor to the widely-used ethers.js library. While viem shares a similar high-level goal—enabling developers to interact with the Ethereum blockchain—it was built from the ground up with a fundamentally different architectural philosophy. Its creation was driven by the need for improved TypeScript support, better modularity, and a more focused, composable API that could keep pace with Ethereum's rapidly evolving ecosystem, including Layer 2 rollups.

The development of viem is intrinsically linked to the rise of the Wagmi project, a collection of React Hooks for Ethereum. Wagmi's original core was built on ethers.js, but its creators sought a more type-safe and performant underlying primitive. Viem was developed to be that primitive, leading to a symbiotic relationship where Wagmi provides the frontend framework and viem provides the robust, low-level blockchain communication layer. This origin underscores viem's design as a library for builders of higher-level tools.

Etymologically, viem breaks from the tradition of naming crypto libraries after units of currency (e.g., web3.js, ethers) or playful puns. Its abstract, almost synthetic quality reflects a maturation in developer tooling, prioritizing technical precision and developer experience over thematic naming. This choice signals its role as essential, infrastructural software—the viem through which applications connect to Ethereum, much like a conduit or medium.

Viem is a modular, type-safe, and low-level TypeScript library for interacting with the Ethereum blockchain and its ecosystem. Its architecture is built around a clear separation of concerns, organized into distinct clients, transports, and actions. The foundational Client object, configured with a specific Transport (like HTTP or WebSocket), serves as the primary interface. This client then exposes public actions—modular functions for specific operations like reading chain data or sending transactions—which internally call the transport to communicate with a node. This design enables powerful type inference, excellent tree-shaking, and flexible composition for developers.

The data flow in viem begins with a developer importing and creating a client. For example, createPublicClient is used for read operations, requiring a transport such as http() to connect to a JSON-RPC provider. When an action like getBlockNumber is called on this client, the request is serialized, passed through the configured transport layer to the node, and the response is deserialized and strongly typed before being returned. For writing to the chain, a Wallet Client (createWalletClient) is used, which manages private keys or connectors (e.g., for browser wallets) to sign transactions before they are broadcast via the public client's transport.

Key architectural concepts include its modular actions, which are imported on-demand to keep bundle sizes minimal, and its extensive support for Account Abstraction via the viem/accounts submodule, which provides utilities for managing different private key types and signing methods. The library also features a comprehensive ABI-driven type system; when you provide a contract's ABI to a readContract or writeContract action, viem infers the exact function names, argument types, and return types, providing full autocompletion and compile-time safety. This makes interacting with smart contracts far less error-prone.

Beyond core Ethereum, viem's architecture extends to L2s and other chains through its chains module. Developers can import chain definitions (e.g., arbitrum, polygon) and pass them during client creation. The client automatically uses the correct RPC URLs, chain IDs, and native currency information. Furthermore, viem includes specialized utilities for ens, multicall batching, and error handling with custom error classes, making it a comprehensive toolkit that abstracts away the complexities of direct RPC communication while remaining flexible and performant.

This example demonstrates the fundamental pattern for querying a smart contract's state using viem's readContract function, which executes a view or pure function without sending a transaction or paying gas. The core steps involve: - Importing the necessary clients and functions from viem. - Configuring a public client for the desired blockchain network (e.g., mainnet). - Defining the target contract's address, Application Binary Interface (ABI), and the specific function to call. - Executing the read call and handling the returned data. This pattern is essential for fetching on-chain data like token balances, governance proposals, or protocol parameters.

A typical implementation begins by setting up a public client using createPublicClient and a transport like http(). The contract's ABI is a critical component, as it provides the type definitions that viem uses to encode the function call and decode the response. For example, to read the totalSupply of an ERC-20 token, you would import or define the ERC-20 ABI snippet containing the totalSupply function. The readContract function is then called with an object containing the client, the contract's address, the abi, the functionName, and any required args (arguments) for the function.

Error handling and type safety are paramount. Viem, being a TypeScript-first library, leverages the provided ABI to infer the return type of the function call, ensuring the result is correctly typed. Network-specific considerations, such as multicall batching for efficiency or handling RPC rate limits, can be addressed using viem's extended client capabilities. This code pattern forms the basis for more advanced interactions, such as simulating transactions with simulateContract or writing to contracts with writeContract, establishing viem as a comprehensive toolkit for Ethereum development.