Human-Readable ABI

Type-level and runtime utilities for parsing human-readable ABIs

Human-Readable ABIs compress JSON ABIs into signatures that are nicer to read and less verbose to write. For example:

const abi = [
  'constructor()',
  'function balanceOf(address owner) view returns (uint256)',
  'event Transfer(address indexed from, address indexed to, uint256 amount)',
  'error ApprovalCallerNotOwnerNorApproved()',
] as const

ABIType contains parallel type-level and runtime utilities for parsing and formatting human-readable ABIs, ABI items, and ABI parameters.

Signature Types

For the most part, human-readable signatures match their Solidity counterparts and support function, event, error, struct, constructor, fallback, and receive types.

Functions

Function signatures match the following format:

function name(inputs) scope mutability returns (outputs)

name function name.
inputs function input parameters (optional).
scope function scope (optional). Only supports 'public' | 'external'.
mutability function state mutability (optional). Supports AbiStateMutability.
outputs function outputs (optional).

Examples

'function mint()' // name
'function withdraw(uint wad)' // name, inputs
'function activate() public' // name, scope
'function deposit() payable' // name, mutability
'function name() returns (string)' // name, outputs
'function tokenURI(uint256 tokenId) pure returns (string)' // name, inputs, mutability, outputs

Events

Event signatures match the following format:

event name(inputs)

name event name.
inputs event input parameters (optional). Parameters support the indexed modifier.

Examples

'event Mint()' // name
'event Transfer(bytes32 indexed node, address owner)' // name, inputs

Errors

Error signatures match the following format:

error name(inputs)

name error name.
inputs error input parameters (optional).

Examples

'event CriteriaNotEnabledForItem()' // name
'event InvalidRestrictedOrder(bytes32 orderHash)' // name, inputs

Structs

Struct signatures match the following format:

struct Name { properties }

Name struct name.
properties struct properties (colon-separated).

Examples

'struct AdditionalRecipient { uint256; address; }' // unnamed properties
'struct AdditionalRecipient { uint256 amount; address recipient; }' // named properties

Constructor

Constructor signatures match the following format:

constructor(parameters) mutability

parameters constructor parameters (optional).
mutability constructor state mutability (optional). Supports 'payable'.

Examples

'constructor()' // empty parameters
'constructor(address conduitController)' // name, parameters
'constructor(address conduitController) payable' // name, parameters, mutability

Fallback

Fallback signatures match the following format:

fallback() scope mutability

Examples

'fallback() external' // scope
'fallback() external payable' // scope, mutability

scope fallback scope. Supports 'external'.
mutability fallback state mutability (optional). Supports 'payable'.

Receive

Receive signatures match the following format:

receive() external payable

Examples

'receive() external payable'

Syntax Rules

Some additional rules that apply to human-readable ABIs:

Whitespace matters. This allows us to infer TypeScript types at the type-level and make sure signatures are valid. For example, 'function name() returns (string)' is valid, but 'function name()returns(string)' is not.
No semi-colons. This is a stylistic choice to make signatures more readable.
No recursive structs. Structs can reference other structs, but not themselves or other structs in a circular way. For example, ['struct A { B; }', 'struct B { string; }'] is valid, but 'struct A { A; }' and ['struct A { B; }', 'struct B { A; }'] are not valid.
Modifier keywords. Modifier keywords like 'calldata', 'memory', and 'storage' are ignored when parsing signatures. For example, 'function name(string calldata)' is valid and 'calldata' will be ignored when parsing the signature.
Inline tuples. Inline tuples are supported for function inputs and outputs, error, event, and constructor inputs, and struct properties. For example, '(uint256, string)' is valid and corresponds to the following JSON ABI parameter: { type: 'tuple', components: [{ type: 'uint256' }, { type: 'string' }] }. You can also nest inline tuples inside inline tuples.
Named and unnamed parameters. Named and unnamed parameters/properties are both supported. For example, 'string foo' is named and 'string' is unnamed.

Types

Types for parsing and formatting human-readable ABIs.

`ParseAbi`

Parses human-readable ABI into JSON Abi.

Name	Description	Type
`TSignatures`	Human-Readable ABI.	`string[]`
returns	Parsed `Abi`	`TAbi` (inferred)

Example

import { ParseAbi } from 'abitype'
 
type Result = ParseAbi<[
  'function balanceOf(address owner) view returns (uint256)',
  'event Transfer(address indexed from, address indexed to, uint256 amount)',
]>
let result: Result
//  ^?

`ParseAbiItem`

Parses human-readable ABI item (e.g. error, event, function) into ABI item.

Name	Description	Type
`TSignature`	Human-Readable ABI item.	`string[]`
returns	Parsed ABI item	`TAbiItem` (inferred)

Example

import { ParseAbiItem } from 'abitype'
 
type Result = ParseAbiItem<
  'function balanceOf(address owner) view returns (uint256)'
>
let result: Result
//  ^? 
 
 
 
 
 
 
 
 
 
 
 
 
 
type ResultStruct = ParseAbiItem<[
  'function foo(Baz bar) view returns (string)',
  'struct Baz { string name; }',
]>
let resultStruct: ResultStruct
//  ^?

`ParseAbiParameter`

Parses human-readable ABI parameter into AbiParameter.

Name	Description	Type
`TParam`	Human-Readable ABI parameter.	`string \| string[]`
returns	Parsed `AbiParameter`	`TAbiParameter` (inferred)

Example

import { ParseAbiParameter } from 'abitype'
 
type Result = ParseAbiParameter<'address from'>
//   ^? 
 
 
 
 
 
 
type ResultStruct = ParseAbiParameter<[
  // ^? 
 
 
 
 
 
 
 
 
 
  'Baz bar',
  'struct Baz { string name; }',
]>## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 34 - Cannot find module 'abitype' or its corresponding type declarations.

`ParseAbiParameters`

Parses human-readable ABI parameters into AbiParameters.

Name	Description	Type
`TParams`	Human-Readable ABI parameters.	`string \| string[]`
returns	Parsed `AbiParameter`s	`TAbiParameter[]` (inferred)

Example

import { ParseAbiParameters } from 'abitype'
 
type Result = ParseAbiParameters<'address from, uint256 amount'>
//   ^? 
 
 
 
 
 
 
 
 
 
 
type ResultStruct = ParseAbiParameters<[
  // ^? 
 
 
 
 
 
 
 
 
 
  'Baz bar',
  'struct Baz { string name; }',
]>## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 35 - Cannot find module 'abitype' or its corresponding type declarations.

`FormatAbi`

Formats Abi into human-readable ABI.

Name	Description	Type
`TAbi`	ABI	`Abi`
returns	Human-Readable ABI.	`string[]` (inferred)

Example

import { FormatAbi } from 'abitype'
 
type Result = FormatAbi<[
//   ^? 
 
 
 
  {
    name: 'balanceOf'
    type: 'function'
    stateMutability: 'view'
    inputs: [{ type: 'address'; name: 'owner' }]
    outputs: [{ type: 'uint256' }]
  },
  {
    name: 'Transfer'
    type: 'event'
    inputs: [
      { type: 'address'; name: 'from'; indexed: true },
      { type: 'address'; name: 'to'; indexed: true },
      { type: 'uint256'; name: 'amount' },
    ]
  },
]>## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 26 - Cannot find module 'abitype' or its corresponding type declarations.

`FormatAbiItem`

Formats Abi item (e.g. error, event, function) into human-readable ABI parameter.

Name	Description	Type
`TAbiItem`	ABI item	`Abi[number]`
returns	Human-Readable ABI item.	`string` (inferred)

Example

import { FormatAbiItem } from 'abitype'
 
type Result = FormatAbiItem<{
//   ^? 
 
 
 
  name: 'balanceOf'
  type: 'function'
  stateMutability: 'view'
  inputs: [{ type: 'address'; name: 'owner' }]
  outputs: [{ type: 'uint256' }]
}>## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 30 - Cannot find module 'abitype' or its corresponding type declarations.

`FormatAbiParameter`

Formats AbiParameter into human-readable ABI parameter.

Name	Description	Type
`TAbiParameter`	ABI parameter	`AbiParameter`
returns	Human-Readable ABI parameters.	`string[]` (inferred)

Example

import { FormatAbiParameter } from 'abitype'
 
type Result = FormatAbiParameter<{ type: 'address'; name: 'from' }>
//   ^? ## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 35 - Cannot find module 'abitype' or its corresponding type declarations.

`FormatAbiParameters`

Formats AbiParameters into human-readable ABI parameters.

Name	Description	Type
`TAbiParameters`	ABI parameters	`AbiParameter[]`
returns	Human-Readable ABI parameter.	`string` (inferred)

Example

import { FormatAbiParameters } from 'abitype'
 
type Result = FormatAbiParameters<[
//   ^? 
 
 
  { type: 'address'; name: 'from' },
  { type: 'uint256'; name: 'tokenId' },
]>## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 36 - Cannot find module 'abitype' or its corresponding type declarations.

Utilities

Runtime functions for parsing and formatting human-readable ABIs.

`parseAbi`

Parses human-readable ABI into JSON Abi.

Name	Description	Type
`signatures`	Human-Readable ABI.	`string[]`
returns	Parsed `Abi`	`TAbi` (inferred)

Example

import { parseAbi } from 'abitype'
 
const abi = parseAbi([
  'function balanceOf(address owner) view returns (uint256)',
  'event Transfer(address indexed from, address indexed to, uint256 amount)',
])
abi
//^?

`parseAbiItem`

Parses human-readable ABI item (e.g. error, event, function) into ABI item.

Name	Description	Type
`signature`	Human-Readable ABI item.	`string \| string[]`
returns	Parsed ABI item	`TAbiItem` (inferred)

Example

import { parseAbiItem } from 'abitype'
 
const abiItem = parseAbiItem(
  'function balanceOf(address owner) view returns (uint256)',
)
abiItem
// ^? 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
const abiItemStruct = parseAbiItem([
  'function foo(Baz bar) view returns (string)',
  'struct Baz { string name; }',
])
abiItemStruct
// ^?

`parseAbiParameter`

Parses human-readable ABI parameter into AbiParameter.

Name	Description	Type
`param`	Human-Readable ABI parameter.	`string \| string[]`
returns	Parsed `AbiParameter`	`TAbiParameter` (inferred)

Example

import { parseAbiParameter } from 'abitype'
 
const abiParameter = parseAbiParameter('address from')
//    ^? 
 
 
 
 
 
const abiParameterStruct = parseAbiParameter([
  'Baz bar',
  'struct Baz { string name; }',
])
abiParameterStruct
//  ^?

`parseAbiParameters`

Parses human-readable ABI parameters into AbiParameters.

Name	Description	Type
`params`	Human-Readable ABI parameters.	`string \| string[]`
returns	Parsed `AbiParameter`s	`TAbiParameter[]` (inferred)

Example

import { parseAbiParameters } from 'abitype'
 
const abiParameters = parseAbiParameters(
  'address from, address to, uint256 amount',
)
abiParameters
//  ^?
 
 
 
 
 
 
 
 
 
 
 
const abiParametersStruct = parseAbiParameters([
  'Baz bar',
  'struct Baz { string name; }',
])
abiParametersStruct
// ^?

`formatAbi`

Formats Abi into human-readable ABI.

Name	Description	Type
`abi`	ABI	`Abi`
returns	Human-Readable ABI.	`string[]` (inferred)

Example

import { formatAbi } from 'abitype'
 
const result = formatAbi([
//    ^? 
 
 
 
  {
    name: 'balanceOf',
    type: 'function',
    stateMutability: 'view',
    inputs: [{ type: 'address', name: 'owner' }],
    outputs: [{ type: 'uint256' }],
  },
  {
    name: 'Transfer',
    type: 'event',
    inputs: [
      { type: 'address', name: 'from', indexed: true },
      { type: 'address', name: 'to', indexed: true },
      { type: 'uint256', name: 'amount' },
    ],
  },
])## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 26 - Cannot find module 'abitype' or its corresponding type declarations.

`formatAbiItem`

Formats Abi item (e.g. error, event, function) into human-readable ABI parameter.

Name	Description	Type
`abiItem`	ABI item	`Abi[number]`
returns	Human-Readable ABI item.	`string` (inferred)

Example

import { formatAbiItem } from 'abitype'
 
const result = formatAbiItem({
//    ^? 
 
 
 
  name: 'balanceOf',
  type: 'function',
  stateMutability: 'view',
  inputs: [{ type: 'address', name: 'owner' }],
  outputs: [{ type: 'uint256' }],
})## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 30 - Cannot find module 'abitype' or its corresponding type declarations.

`formatAbiParameter`

Formats AbiParameter into human-readable ABI parameter.

Name	Description	Type
`abiParameter`	ABI parameter	`AbiParameter`
returns	Human-Readable ABI parameter.	`string` (inferred)

Example

import { formatAbiParameter } from 'abitype'
 
const result = formatAbiParameter({ type: 'address', name: 'from' })
//    ^? ## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 35 - Cannot find module 'abitype' or its corresponding type declarations.

`formatAbiParameters`

Formats AbiParameters into human-readable ABI parameters.

Name	Description	Type
`abiParameters`	ABI parameters	`AbiParameter[]`
returns	Human-Readable ABI parameter.	`string` (inferred)

Example

import { formatAbiParameters } from 'abitype'
 
const result = formatAbiParameters([
//    ^? 
 
 
  { type: 'address', name: 'from' },
  { type: 'uint256', name: 'tokenId' },
])## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 36 - Cannot find module 'abitype' or its corresponding type declarations.

Errors

import {
  CircularReferenceError,
  InvalidParenthesisError,
  UnknownSignatureError,
  InvalidSignatureError,
  InvalidStructSignatureError,
  InvalidAbiParameterError,
  InvalidAbiParametersError,
  InvalidParameterError,
  SolidityProtectedKeywordError,
  InvalidModifierError,
  InvalidFunctionModifierError,
  InvalidAbiTypeParameterError,
  InvalidAbiItemError,
  UnknownTypeError,
} from 'abitype'## Errors were thrown in the sample, but not included in an errors tag

These errors were not marked as being expected: 2307. 
Expected: // @errors: 2307

Compiler Errors:

index.ts
  [2307] 396 - Cannot find module 'abitype' or its corresponding type declarations.