abitype

ABIType provides strict TypeScript types for Ethereum ABIs and EIP-712 Typed Data. It allows you to add type inference and autocomplete to your code based on user-provided ABIs without needing a separate type-generation build step (like TypeChain).

import type {
  AbiParametersToPrimitiveTypes,
  ExtractAbiFunction,
  ExtractAbiFunctionNames,
} from 'abitype'
import { erc20Abi } from 'abitype/abis'

type FunctionNames = ExtractAbiFunctionNames<typeof erc20Abi, 'view'>
//   ^? type FunctionNames = "symbol" | "name" | "allowance" | "balanceOf" | "decimals" | "totalSupply"

type TransferInputTypes = AbiParametersToPrimitiveTypes<
  // ^? type TransferInputTypes = readonly [`0x${string}`, bigint]
  ExtractAbiFunction<typeof erc20Abi, 'transfer'>['inputs']
>

ABIType allows you to derive TypeScript types directly from your ABI objects. This enables blazing fast autocomplete and type checking for functions, variables, or custom types without needing third-party tools like TypeChain.

Common use cases include:

• Typechecking ABIs or EIP-712 Typed Data.
• Adding type inference to libraries based on user-provided ABIs (similar to how Viem or Wagmi work).
• Converting ABI parameter types (e.g., 'string') into TypeScript primitive types (e.g. string) using utilities like AbiParametersToPrimitiveTypes.

import { AbiParametersToPrimitiveTypes, ExtractAbiFunction } from 'abitype'
import { erc20Abi } from 'abitype/abis'

type TransferInputTypes = AbiParametersToPrimitiveTypes<
  // ^?

  ExtractAbiFunction<typeof erc20Abi, 'transfer'>['inputs']
>

Setting strictAbiType: true in the Register interface forces validation of an AbiParameter's type against the corresponding AbiType.

When to use: Only enable this if parsed types are returning as unknown and you need to debug why.

Warning: This option will significantly slow down type checking.

import 'abitype'

declare module 'abitype' {
  export interface Register {
    strictAbiType: true
  }
}

ABIType is suitable for projects that need to:

• Typecheck ABIs or EIP-712 Typed Data: Ensure your ABI structures conform to specifications.
• Add type inference and autocomplete: Build libraries (like Wagmi or Viem) that provide autocomplete based on user-provided ABIs.
• Convert ABI types to TypeScript types: Use utilities to transform ABI parameter types (e.g., 'string') into TypeScript types (e.g. string).
• Avoid type generation: Use existing ABIs directly in TypeScript without a build process to generate types.

Because ABIs often contain deeply nested arrays and objects, TypeScript's default type widening (e.g., converting a specific string like "transfer" to the general type string) will break type safety.

You must ensure your ABI is treated as a constant using one of two methods:

1. TypeScript Const Assertions: Use as const or the <const> syntax. This is the preferred method for pure TypeScript projects.
2. The narrow function: Use the narrow utility from abitype. This is useful when working with plain JavaScript where const assertions are not available.

// Method 1: Const assertions
const erc20Abi = [...] as const
const erc20Abi = <const>[...]

// Method 2: Using the narrow utility
import { narrow } from 'abitype'
const erc20Abi = narrow([...])

You can install abitype using your preferred package manager. ABIType provides strict TypeScript types for Ethereum ABIs and EIP-712 Typed Data without requiring a separate type-generation build step.

npm i abitype

ABIType's types are customizable via TypeScript declaration merging. You can extend the Register interface within the abitype module to override default types. This can be done directly in your source code or in a .d.ts file (e.g., abi.d.ts).

If you are using ABIType through a third-party package like viem, you must target that package's specific abitype module path (e.g., viem/node_modules/abitype) to ensure your customizations are applied correctly.

import 'abitype'

declare module 'abitype' {
  export interface Register {
    bigIntType: bigint & { foo: 'bar' }
  }
}

import { ResolvedRegister } from 'abitype'
type Result = ResolvedRegister['bigIntType']
//   ^? bigint & { foo: 'bar' }

The AbiStateMutability type defines the state mutability of a Solidity function. This is used in AbiFunction, AbiConstructor, AbiFallback, and AbiReceive definitions.

Allowed values are:

• pure: The function does not read or modify the state.
• view: The function reads the state but does not modify it.
• nonpayable: The function can modify the state but cannot receive Ether.
• payable: The function can modify the state and receive Ether.

You can extend the default ABI type resolution behavior by implementing the Register interface. This allows you to override how specific ABI types (like addresses, integers, or bytes) are mapped to TypeScript types, and to configure constraints for arrays and strictness levels.

To use this, define an interface that extends Register and pass it to the relevant abitype functions (where supported).

// Example of defining a custom registration
export interface MyCustomRegister extends Register {
  addressType: string;
  intType: number;
  strictAbiType: true;
}