viem

name	viem
description	This skill should be used when the user asks about "viem", "viem client", "viem actions", "TypeScript Ethereum", "createPublicClient", "createWalletClient", "parseEther", "formatEther", "readContract", "writeContract", or mentions using viem for blockchain interactions.

Viem

Overview

Viem is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with the blockchain. It focuses on developer experience, stability, bundle size, and performance.

Key features:

• Automatic type safety and inference
• Tree-shakable lightweight modules
• Optimized encoding/parsing
• Composable APIs

Core Concepts

Concept	Description
Clients	PublicClient, WalletClient, TestClient - entry points
Transports	Connection layer (http, webSocket, custom)
Actions	Operations like getBlockNumber, sendTransaction
Chains	Chain configurations (mainnet, sepolia, arbitrum, etc.)

Constants

Viem exports useful constants for common values:

import { maxUint256, maxUint128, maxInt256, zeroAddress, zeroHash } from "viem";

// Max values for uint types
maxUint256; // 2n ** 256n - 1n
maxUint128; // 2n ** 128n - 1n

// Zero values
zeroAddress; // 0x0000000000000000000000000000000000000000
zeroHash; // 0x0000000000000000000000000000000000000000000000000000000000000000

Utilities

Unit Conversion

Convert between wei and human-readable values:

import { parseEther, formatEther, parseUnits, formatUnits } from "viem";

// ETH <-> Wei (18 decimals)
parseEther("1"); // 1000000000000000000n
formatEther(1000000000000000000n); // "1"

// Custom decimals (e.g., USDC with 6 decimals)
parseUnits("100", 6); // 100000000n
formatUnits(100000000n, 6); // "100"

ABI Utilities

Parse human-readable ABIs:

import { parseAbi, parseAbiItem } from "viem";

const abi = parseAbi([
  "function balanceOf(address owner) view returns (uint256)",
  "function transfer(address to, uint256 amount) returns (bool)",
  "event Transfer(address indexed from, address indexed to, uint256 amount)",
]);

const item = parseAbiItem("function name() view returns (string)");

Address Utilities

import { getAddress, isAddress, isAddressEqual } from "viem";

// Checksum address
getAddress("0xabc..."); // "0xAbc..." (checksummed)

// Validation
isAddress("0x..."); // true/false
isAddressEqual("0xAbc...", "0xabc..."); // true (case-insensitive)

Clients

Public Client (Read Operations)

For querying blockchain state:

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(), // or http("https://eth-mainnet.g.alchemy.com/v2/...")
});

// Read operations
const blockNumber = await publicClient.getBlockNumber();
const balance = await publicClient.getBalance({ address: "0x..." });
const block = await publicClient.getBlock();

Wallet Client (Write Operations)

For signing and sending transactions:

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";

const account = privateKeyToAccount("0x...");

const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http(),
});

// Send transaction
const hash = await walletClient.sendTransaction({
  to: "0x...",
  value: parseEther("0.1"),
});

Browser Wallet Client

For browser environments with injected wallets:

import "viem/window";
import { createWalletClient, custom } from "viem";
import { mainnet } from "viem/chains";

const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum!),
});

// Request accounts
const [address] = await walletClient.requestAddresses();

Extending Clients

Combine capabilities using .extend():

import { createWalletClient, http, publicActions } from "viem";
import { mainnet } from "viem/chains";

const client = createWalletClient({
  chain: mainnet,
  transport: http(),
}).extend(publicActions);

// Now supports both wallet and public actions
const balance = await client.getBalance({ address: "0x..." });
const hash = await client.sendTransaction({ to: "0x...", value: 1n });

Contract Interactions

Reading from Contracts

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(),
});

const abi = [
  {
    inputs: [{ name: "owner", type: "address" }],
    name: "balanceOf",
    outputs: [{ name: "", type: "uint256" }],
    stateMutability: "view",
    type: "function",
  },
] as const;

const balance = await publicClient.readContract({
  address: "0x...", // Contract address
  abi,
  functionName: "balanceOf",
  args: ["0x..."], // Owner address
});

Writing to Contracts

const hash = await walletClient.writeContract({
  address: "0x...",
  abi,
  functionName: "transfer",
  args: ["0x...", parseUnits("100", 18)],
});

Simulating Before Writing

Simulate a transaction before sending:

const { request } = await publicClient.simulateContract({
  address: "0x...",
  abi,
  functionName: "transfer",
  args: ["0x...", parseUnits("100", 18)],
  account: "0x...",
});

const hash = await walletClient.writeContract(request);

Account Types

Local Accounts

For server-side or controlled environments:

import { privateKeyToAccount, mnemonicToAccount } from "viem/accounts";

// From private key
const account = privateKeyToAccount("0x...");

// From mnemonic
const account = mnemonicToAccount("legal winner thank year wave sausage ...");

JSON-RPC Accounts

For browser wallets:

import "viem/window";

const [account] = await window.ethereum!.request({
  method: "eth_requestAccounts",
});

Chain Configuration

Built-in Chains

import { mainnet, sepolia, arbitrum, optimism, polygon, base } from "viem/chains";

const client = createPublicClient({
  chain: arbitrum,
  transport: http(),
});

Custom Chains

import { defineChain } from "viem";

const customChain = defineChain({
  id: 123456,
  name: "My Chain",
  nativeCurrency: { name: "ETH", symbol: "ETH", decimals: 18 },
  rpcUrls: {
    default: { http: ["https://rpc.mychain.com"] },
  },
  blockExplorers: {
    default: { name: "Explorer", url: "https://explorer.mychain.com" },
  },
});

Documentation

This skill provides a reference for common operations. For comprehensive documentation, fetch the full viem docs using context7 MCP:

Library ID: /wevm/viem

Use context7 to query specific topics:

• clients - Client types and configuration
• actions - Available actions (read, write, wallet)
• accounts - Local and JSON-RPC accounts
• contract - Contract interactions (readContract, writeContract)
• abi - ABI encoding/decoding utilities
• chains - Supported chains and custom chain configuration

Fetching Documentation

To fetch viem documentation for a specific topic:

1. Resolve the library ID with mcp__context7__resolve-library-id (or use /wevm/viem directly)
2. Call mcp__context7__get-library-docs with the topic parameter

Example topics: "getting started", "wallet client", "send transaction", "read contract".