viem 2.53.1 → 2.54.0

package/clients/decorators/public.ts

@@ -265,6 +265,12 @@ import {
   type VerifySiweMessageReturnType,
   verifySiweMessage,
 } from '../../actions/siwe/verifySiweMessage.js'
+import {
+  getAllowance,
+  getMetadata,
+  getBalance as getTokenBalance,
+  getTotalSupply,
+} from '../../actions/token/index.js'
 import {
   type PrepareTransactionRequestParameters,
   type PrepareTransactionRequestRequest,
@@ -281,6 +287,7 @@ import {
   type SendRawTransactionSyncReturnType,
   sendRawTransactionSync,
 } from '../../actions/wallet/sendRawTransactionSync.js'
+import type { Tokens } from '../../tokens/defineToken.js'
 import type { Account } from '../../types/account.js'
 import type { BlockNumber, BlockTag } from '../../types/block.js'
 import type { Chain } from '../../types/chain.js'
@@ -293,13 +300,17 @@ import type {
 } from '../../types/contract.js'
 import type { FeeValuesType } from '../../types/fee.js'
 import type { FilterType } from '../../types/filter.js'
-import type { Client } from '../createClient.js'
+import { bindActionDecorators, type Client } from '../createClient.js'
 import type { Transport } from '../transports/createTransport.js'
 
+/** @internal */
+export type { TokenName } from '../../actions/token/internal.js'
+
 export type PublicActions<
   transport extends Transport = Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = {
   /**
    * Executes a new message call immediately without submitting a transaction to the network.
@@ -2091,15 +2102,150 @@ export type PublicActions<
   watchPendingTransactions: (
     args: WatchPendingTransactionsParameters<transport>,
   ) => WatchPendingTransactionsReturnType
+  /**
+   * Read-only ERC-20 Actions, exposed under the `token` namespace.
+   *
+   * Every action selects its token by `token`, which is either a token symbol
+   * (resolved from the Client's `tokens` array) or a contract `address`.
+   *
+   * - Docs: https://viem.sh/docs/token
+   */
+  token: {
+    /**
+     * Gets the amount of tokens a `spender` is allowed to spend on behalf of an
+     * `account`.
+     *
+     * - Docs: https://viem.sh/docs/token/getAllowance
+     *
+     * @param parameters - {@link getAllowance.Parameters}
+     * @returns The remaining allowance, in base units and human-readable form. {@link getAllowance.ReturnValue}
+     *
+     * @example
+     * import { createPublicClient, http } from 'viem'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createPublicClient({ chain: mainnet, transport: http() })
+     *
+     * const allowance = await client.token.getAllowance({
+     *   account: '0x…',
+     *   spender: '0x…',
+     *   token: 'usdc',
+     * })
+     */
+    getAllowance: ((
+      parameters: getAllowance.Parameters<chain, tokens>,
+    ) => Promise<getAllowance.ReturnValue>) & {
+      /**
+       * Defines an `allowance` contract call, ready to pass to `multicall`,
+       * `simulateContract`, or any other action that accepts a contract call.
+       *
+       * - Docs: https://viem.sh/docs/token/getAllowance#composing-calls
+       *
+       * @param args - {@link getAllowance.Args}
+       * @returns The contract call.
+       */
+      call: (
+        args: getAllowance.Args<chain, tokens>,
+      ) => ReturnType<typeof getAllowance.call>
+    }
+    /**
+     * Gets the token balance of an `account`.
+     *
+     * - Docs: https://viem.sh/docs/token/getBalance
+     *
+     * @param parameters - {@link getTokenBalance.Parameters}
+     * @returns The token balance, in base units and human-readable form. {@link getTokenBalance.ReturnValue}
+     *
+     * @example
+     * import { createPublicClient, http } from 'viem'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createPublicClient({ chain: mainnet, transport: http() })
+     *
+     * const balance = await client.token.getBalance({
+     *   account: '0x…',
+     *   token: 'usdc',
+     * })
+     */
+    getBalance: ((
+      parameters: getTokenBalance.Parameters<chain, account, tokens>,
+    ) => Promise<getTokenBalance.ReturnValue>) & {
+      /**
+       * Defines a `balanceOf` contract call, ready to pass to `multicall`,
+       * `simulateContract`, or any other action that accepts a contract call.
+       *
+       * - Docs: https://viem.sh/docs/token/getBalance#composing-calls
+       *
+       * @param args - {@link getTokenBalance.Args}
+       * @returns The contract call.
+       */
+      call: (
+        args: getTokenBalance.Args<chain, account, tokens>,
+      ) => ReturnType<typeof getTokenBalance.call>
+    }
+    /**
+     * Gets the metadata (`decimals`, `name`, `symbol`) of the token. Fields
+     * declared on the Client's `tokens` array are used as-is; any missing field
+     * is fetched from the token contract.
+     *
+     * - Docs: https://viem.sh/docs/token/getMetadata
+     *
+     * @param parameters - {@link getMetadata.Parameters}
+     * @returns The token metadata (`decimals`, `name`, `symbol`). {@link getMetadata.ReturnValue}
+     *
+     * @example
+     * import { createPublicClient, http } from 'viem'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createPublicClient({ chain: mainnet, transport: http() })
+     *
+     * const metadata = await client.token.getMetadata({ token: 'usdc' })
+     */
+    getMetadata: (
+      parameters: getMetadata.Parameters<chain, tokens>,
+    ) => Promise<getMetadata.ReturnValue>
+    /**
+     * Gets the total supply of the token.
+     *
+     * - Docs: https://viem.sh/docs/token/getTotalSupply
+     *
+     * @param parameters - {@link getTotalSupply.Parameters}
+     * @returns The token total supply, in base units and human-readable form. {@link getTotalSupply.ReturnValue}
+     *
+     * @example
+     * import { createPublicClient, http } from 'viem'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createPublicClient({ chain: mainnet, transport: http() })
+     *
+     * const totalSupply = await client.token.getTotalSupply({ token: 'usdc' })
+     */
+    getTotalSupply: ((
+      parameters: getTotalSupply.Parameters<chain, tokens>,
+    ) => Promise<getTotalSupply.ReturnValue>) & {
+      /**
+       * Defines a `totalSupply` contract call, ready to pass to `multicall`,
+       * `simulateContract`, or any other action that accepts a contract call.
+       *
+       * - Docs: https://viem.sh/docs/token/getTotalSupply#composing-calls
+       *
+       * @param args - {@link getTotalSupply.Args}
+       * @returns The contract call.
+       */
+      call: (
+        args: getTotalSupply.Args<chain, tokens>,
+      ) => ReturnType<typeof getTotalSupply.call>
+    }
+  }
 }
-
 export function publicActions<
   transport extends Transport = Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 >(
-  client: Client<transport, chain, account>,
-): PublicActions<transport, chain, account> {
+  client: Client<transport, chain, account, undefined, undefined, tokens>,
+): PublicActions<transport, chain, account, tokens> {
   return {
     call: (args) => call(client, args),
     createAccessList: (args) => createAccessList(client, args),
@@ -2166,5 +2312,21 @@ export function publicActions<
     watchContractEvent: (args) => watchContractEvent(client, args),
     watchEvent: (args) => watchEvent(client, args),
     watchPendingTransactions: (args) => watchPendingTransactions(client, args),
+    token: bindPublicToken(client) as never,
+  }
+}
+
+/**
+ * Binds the read-only ERC-20 actions (and their `.call` helpers) to `client`.
+ * Merged with the write actions from {@link walletActions} (when present) by the
+ * Client's `extend`, which shallow-merges conflicting plain-object namespaces.
+ * @internal
+ */
+function bindPublicToken(client: Client<Transport, Chain | undefined, any>) {
+  return {
+    getAllowance: bindActionDecorators(client, getAllowance),
+    getBalance: bindActionDecorators(client, getTokenBalance),
+    getMetadata: bindActionDecorators(client, getMetadata),
+    getTotalSupply: bindActionDecorators(client, getTotalSupply),
   }
 }

package/clients/decorators/wallet.ts

@@ -10,6 +10,12 @@ import {
   type GetChainIdReturnType,
   getChainId,
 } from '../../actions/public/getChainId.js'
+import {
+  approve,
+  approveSync,
+  transfer,
+  transferSync,
+} from '../../actions/token/index.js'
 import {
   type AddChainParameters,
   addChain,
@@ -139,17 +145,19 @@ import {
   type WriteContractSyncReturnType,
   writeContractSync,
 } from '../../actions/wallet/writeContractSync.js'
+import type { Tokens } from '../../tokens/defineToken.js'
 import type { Chain } from '../../types/chain.js'
 import type {
   ContractFunctionArgs,
   ContractFunctionName,
 } from '../../types/contract.js'
-import type { Client } from '../createClient.js'
+import { bindActionDecorators, type Client } from '../createClient.js'
 import type { Transport } from '../transports/createTransport.js'
 
 export type WalletActions<
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = {
   /**
    * Adds an EVM chain to the wallet.
@@ -1175,13 +1183,238 @@ export type WalletActions<
       chainOverride
     >,
   ) => Promise<WriteContractSyncReturnType>
+  /**
+   * Write ERC-20 Actions, exposed under the `token` namespace.
+   *
+   * Every action selects its token by `token`, which is either a token symbol
+   * (resolved from the Client's `tokens` array) or a contract `address`. `amount`
+   * inputs are base-unit `bigint` values, or
+   * `{ decimals?: number, formatted: string }` to parse a human-readable decimal
+   * string.
+   *
+   * - Docs: https://viem.sh/docs/token
+   */
+  token: {
+    /**
+     * Approves a `spender` to transfer up to `amount` tokens on behalf of the
+     * caller, and waits for the transaction to be confirmed.
+     *
+     * - Docs: https://viem.sh/docs/token/approve
+     *
+     * @param parameters - {@link approveSync.Parameters}
+     * @returns The decoded `Approval` event and the transaction receipt. {@link approveSync.ReturnValue}
+     *
+     * @example
+     * import { createWalletClient, http } from 'viem'
+     * import { privateKeyToAccount } from 'viem/accounts'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createWalletClient({
+     *   account: privateKeyToAccount('0x…'),
+     *   chain: mainnet,
+     *   transport: http(),
+     * })
+     *
+     * const { receipt, value } = await client.token.approveSync({
+     *   amount: { decimals: 6, formatted: '10.5' },
+     *   spender: '0x…',
+     *   token: 'usdc',
+     * })
+     */
+    approveSync: (
+      parameters: approveSync.Parameters<chain, account, tokens>,
+    ) => Promise<approveSync.ReturnValue>
+    /**
+     * Approves a `spender` to transfer up to `amount` tokens on behalf of the
+     * caller, and returns the transaction hash.
+     *
+     * - Docs: https://viem.sh/docs/token/approve#asynchronous-usage
+     *
+     * @param parameters - {@link approve.Parameters}
+     * @returns The transaction hash. {@link approve.ReturnValue}
+     *
+     * @example
+     * import { createWalletClient, http } from 'viem'
+     * import { privateKeyToAccount } from 'viem/accounts'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createWalletClient({
+     *   account: privateKeyToAccount('0x…'),
+     *   chain: mainnet,
+     *   transport: http(),
+     * })
+     *
+     * const hash = await client.token.approve({
+     *   amount: { decimals: 6, formatted: '10.5' },
+     *   spender: '0x…',
+     *   token: 'usdc',
+     * })
+     */
+    approve: ((
+      parameters: approve.Parameters<chain, account, tokens>,
+    ) => Promise<approve.ReturnValue>) & {
+      /**
+       * Defines an `approve` contract call, ready to pass to `sendCalls`,
+       * `sendTransaction` (`calls`), or `multicall`.
+       *
+       * - Docs: https://viem.sh/docs/token/approve#composing-calls
+       *
+       * @param args - {@link approve.Args}
+       * @returns The contract call.
+       */
+      call: (
+        args: approve.Args<chain, tokens>,
+      ) => ReturnType<typeof approve.call>
+      /**
+       * Estimates the gas required to approve a `spender` to transfer up to
+       * `amount` tokens on behalf of the caller.
+       *
+       * - Docs: https://viem.sh/docs/token/approve#estimate-gas--simulate
+       *
+       * @param parameters - {@link approve.Parameters}
+       * @returns The gas estimate.
+       */
+      estimateGas: (
+        parameters: approve.Parameters<chain, account, tokens>,
+      ) => Promise<bigint>
+      /**
+       * Extracts the `Approval` event from transaction logs.
+       *
+       * - Docs: https://viem.sh/docs/token/approve
+       *
+       * @param logs - The logs.
+       * @returns The decoded `Approval` event.
+       */
+      extractEvent: typeof approve.extractEvent
+      /**
+       * Simulates approving a `spender` to transfer up to `amount` tokens on
+       * behalf of the caller, returning the result and write request.
+       *
+       * - Docs: https://viem.sh/docs/token/approve#estimate-gas--simulate
+       *
+       * @param parameters - {@link approve.Parameters}
+       * @returns The simulation result and write request.
+       */
+      simulate: (
+        parameters: approve.Parameters<chain, account, tokens>,
+      ) => ReturnType<typeof approve.simulate>
+    }
+    /**
+     * Transfers `amount` tokens to a recipient, and waits for the transaction to
+     * be confirmed. Pass `from` to transfer on behalf of another address using an
+     * allowance (calls `transferFrom`).
+     *
+     * - Docs: https://viem.sh/docs/token/transfer
+     *
+     * @param parameters - {@link transferSync.Parameters}
+     * @returns The decoded `Transfer` event and the transaction receipt. {@link transferSync.ReturnValue}
+     *
+     * @example
+     * import { createWalletClient, http } from 'viem'
+     * import { privateKeyToAccount } from 'viem/accounts'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createWalletClient({
+     *   account: privateKeyToAccount('0x…'),
+     *   chain: mainnet,
+     *   transport: http(),
+     * })
+     *
+     * const { receipt, value } = await client.token.transferSync({
+     *   amount: { decimals: 6, formatted: '10.5' },
+     *   to: '0x…',
+     *   token: 'usdc',
+     * })
+     */
+    transferSync: (
+      parameters: transferSync.Parameters<chain, account, tokens>,
+    ) => Promise<transferSync.ReturnValue>
+    /**
+     * Transfers `amount` tokens to a recipient, and returns the transaction hash.
+     * Pass `from` to transfer on behalf of another address using an allowance
+     * (calls `transferFrom`).
+     *
+     * - Docs: https://viem.sh/docs/token/transfer#asynchronous-usage
+     *
+     * @param parameters - {@link transfer.Parameters}
+     * @returns The transaction hash. {@link transfer.ReturnValue}
+     *
+     * @example
+     * import { createWalletClient, http } from 'viem'
+     * import { privateKeyToAccount } from 'viem/accounts'
+     * import { mainnet } from 'viem/chains'
+     *
+     * const client = createWalletClient({
+     *   account: privateKeyToAccount('0x…'),
+     *   chain: mainnet,
+     *   transport: http(),
+     * })
+     *
+     * const hash = await client.token.transfer({
+     *   amount: { decimals: 6, formatted: '10.5' },
+     *   to: '0x…',
+     *   token: 'usdc',
+     * })
+     */
+    transfer: ((
+      parameters: transfer.Parameters<chain, account, tokens>,
+    ) => Promise<transfer.ReturnValue>) & {
+      /**
+       * Defines a `transfer` (or `transferFrom`, when `from` is given) contract
+       * call, ready to pass to `sendCalls`, `sendTransaction` (`calls`), or
+       * `multicall`.
+       *
+       * - Docs: https://viem.sh/docs/token/transfer#composing-calls
+       *
+       * @param args - {@link transfer.Args}
+       * @returns The contract call.
+       */
+      call: (
+        args: transfer.Args<chain, tokens>,
+      ) => ReturnType<typeof transfer.call>
+      /**
+       * Estimates the gas required to transfer `amount` tokens to a recipient.
+       *
+       * - Docs: https://viem.sh/docs/token/transfer#estimate-gas--simulate
+       *
+       * @param parameters - {@link transfer.Parameters}
+       * @returns The gas estimate.
+       */
+      estimateGas: (
+        parameters: transfer.Parameters<chain, account, tokens>,
+      ) => Promise<bigint>
+      /**
+       * Extracts the `Transfer` event from transaction logs.
+       *
+       * - Docs: https://viem.sh/docs/token/transfer
+       *
+       * @param logs - The logs.
+       * @returns The decoded `Transfer` event.
+       */
+      extractEvent: typeof transfer.extractEvent
+      /**
+       * Simulates a transfer of `amount` tokens to a recipient, returning the
+       * result and write request.
+       *
+       * - Docs: https://viem.sh/docs/token/transfer#estimate-gas--simulate
+       *
+       * @param parameters - {@link transfer.Parameters}
+       * @returns The simulation result and write request.
+       */
+      simulate: (
+        parameters: transfer.Parameters<chain, account, tokens>,
+      ) => ReturnType<typeof transfer.simulate>
+    }
+  }
 }
-
 export function walletActions<
   transport extends Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
->(client: Client<transport, chain, account>): WalletActions<chain, account> {
+  tokens extends Tokens | undefined = Tokens | undefined,
+>(
+  client: Client<transport, chain, account, undefined, undefined, tokens>,
+): WalletActions<chain, account, tokens> {
   return {
     addChain: (args) => addChain(client, args),
     deployContract: (args) => deployContract(client, args),
@@ -1212,5 +1445,11 @@ export function walletActions<
     watchAsset: (args) => watchAsset(client, args),
     writeContract: (args) => writeContract(client, args as any),
     writeContractSync: (args) => writeContractSync(client, args as any),
+    token: {
+      approve: bindActionDecorators(client, approve),
+      approveSync: bindActionDecorators(client, approveSync),
+      transfer: bindActionDecorators(client, transfer),
+      transferSync: bindActionDecorators(client, transferSync),
+    } as never,
   }
 }

package/clients/transports/http.ts

@@ -42,6 +42,8 @@ export type HttpTransportConfig<
    * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
    */
   fetchOptions?: HttpRpcClientOptions['fetchOptions'] | undefined
+  /** Maximum response body size in bytes. Set to `false` to disable. @default 10_485_760 */
+  maxResponseBodySize?: HttpRpcClientOptions['maxResponseBodySize'] | undefined
   /** A callback to handle the response from `fetch`. */
   onFetchRequest?: HttpRpcClientOptions['onRequest'] | undefined
   /** A callback to handle the response from `fetch`. */
@@ -108,6 +110,7 @@ export function http<
     fetchFn,
     fetchOptions,
     key = 'http',
+    maxResponseBodySize,
     methods,
     name = 'HTTP JSON-RPC',
     onFetchRequest,
@@ -126,6 +129,7 @@ export function http<
     const rpcClient = getHttpRpcClient(url_, {
       fetchFn,
       fetchOptions,
+      maxResponseBodySize,
       onRequest: onFetchRequest,
       onResponse: onFetchResponse,
       timeout,

package/errors/encoding.ts

@@ -66,6 +66,17 @@ export class InvalidHexValueError extends BaseError {
   }
 }
 
+export type RlpDepthLimitExceededErrorType = RlpDepthLimitExceededError & {
+  name: 'RlpDepthLimitExceededError'
+}
+export class RlpDepthLimitExceededError extends BaseError {
+  constructor({ limit }: { limit: number }) {
+    super(`RLP depth limit of \`${limit}\` exceeded.`, {
+      name: 'RlpDepthLimitExceededError',
+    })
+  }
+}
+
 export type SizeOverflowErrorType = SizeOverflowError & {
   name: 'SizeOverflowError'
 }

package/errors/request.ts

@@ -44,6 +44,23 @@ export class HttpRequestError extends BaseError {
   }
 }
 
+export type ResponseBodyTooLargeErrorType = ResponseBodyTooLargeError & {
+  name: 'ResponseBodyTooLargeError'
+}
+export class ResponseBodyTooLargeError extends BaseError {
+  maxSize: number
+  size: number
+
+  constructor({ maxSize, size }: { maxSize: number; size: number }) {
+    super('HTTP response body exceeded the size limit.', {
+      metaMessages: [`Max: ${maxSize} bytes`, `Received: ${size} bytes`],
+      name: 'ResponseBodyTooLargeError',
+    })
+    this.maxSize = maxSize
+    this.size = size
+  }
+}
+
 export type WebSocketRequestErrorType = WebSocketRequestError & {
   name: 'WebSocketRequestError'
 }

package/errors/transaction.ts

@@ -53,6 +53,17 @@ export class InvalidLegacyVError extends BaseError {
   }
 }
 
+export type InvalidYParityErrorType = InvalidYParityError & {
+  name: 'InvalidYParityError'
+}
+export class InvalidYParityError extends BaseError {
+  constructor({ yParity }: { yParity: bigint }) {
+    super(`Invalid \`yParity\` value "${yParity}". Expected 0 or 1.`, {
+      name: 'InvalidYParityError',
+    })
+  }
+}
+
 export type InvalidSerializableTransactionErrorType =
   InvalidSerializableTransactionError & {
     name: 'InvalidSerializableTransactionError'

package/errors/version.ts

@@ -1 +1 @@
-export const version = '2.53.1'
+export const version = '2.54.0'

package/index.ts

@@ -878,6 +878,8 @@ export {
   type InvalidHexBooleanErrorType,
   InvalidHexValueError,
   type InvalidHexValueErrorType,
+  RlpDepthLimitExceededError,
+  type RlpDepthLimitExceededErrorType,
   SizeOverflowError,
   type SizeOverflowErrorType,
 } from './errors/encoding.js'
@@ -938,6 +940,8 @@ export {
 export {
   HttpRequestError,
   type HttpRequestErrorType,
+  ResponseBodyTooLargeError,
+  type ResponseBodyTooLargeErrorType,
   RpcRequestError,
   type RpcRequestErrorType,
   SocketClosedError,
@@ -1025,6 +1029,8 @@ export {
   type InvalidSerializedTransactionTypeErrorType,
   InvalidStorageKeySizeError,
   type InvalidStorageKeySizeErrorType,
+  InvalidYParityError,
+  type InvalidYParityErrorType,
   TransactionExecutionError,
   type TransactionExecutionErrorType,
   TransactionNotFoundError,
@@ -1050,6 +1056,7 @@ export {
   InvalidDecimalNumberError,
   type InvalidDecimalNumberErrorType,
 } from './errors/unit.js'
+export type { ResolvedToken, Tokens } from './tokens/defineToken.js'
 export type {
   DeriveAccount,
   HDKey,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viem",
   "description": "TypeScript Interface for Ethereum",
-  "version": "2.53.1",
+  "version": "2.54.0",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -133,6 +133,11 @@
       "import": "./_esm/tempo/zones/index.js",
       "default": "./_cjs/tempo/zones/index.js"
     },
+    "./tokens": {
+      "types": "./_types/tokens/index.d.ts",
+      "import": "./_esm/tokens/index.js",
+      "default": "./_cjs/tokens/index.js"
+    },
     "./utils": {
       "types": "./_types/utils/index.d.ts",
       "import": "./_esm/utils/index.js",

package/tempo/Client.ts

@@ -88,8 +88,10 @@ export type Client<
     chain,
     account,
     rpcSchema,
-    PublicActions<transport, chain, account> &
-      WalletActions<chain, account> &
+    Omit<
+      PublicActions<transport, chain, account> & WalletActions<chain, account>,
+      'token'
+    > &
       Decorator<chain, account>
   >
 >