ABI Formats

There are several formats available to specify an ABI for a Smart Contract, which specifies to the under-lying library what methods, events and errors exist so that encoding and decoding the data from and to the network can be handled by the library.

The supports ABI types are:

• Human-Readable ABI
• Solidity JSON ABI
• Solidity Object ABI

Human-Readable ABI

The Human-Readable ABI was introduced early by ethers, which allows for a Solidity signatures to be used to describe each method, event and error.

It is important to note that a Solidity signature fully describes all the properties the ABI requires:

• name
• type (constructor, event, function)
• inputs (types, nested structures and optionally names)
• outputs (types nested structures and optionally names)
• state mutability (for constructors and methods)
• payability (for constructors and methods)
• whether inputs are indexed (for events)

This allows for a simple format which is both machine-readable (since the parser is a machine) and human-readable (at least developer-readable), as well as simple for humans to type and inline into code, which improves code readability. The Human-Readable ABI is also considerably smaller, which helps reduce code size.

A Human-Readable ABI is simple an array of strings, where each string is the Solidity signature.

Signatures may be minimally specified (i.e. names of inputs and outputs may be omitted) or fully specified (i.e. with all property names) and whitespace is ignored.

Several modifiers available in Solidity are dropped internally, as they are not required for the ABI and used old by Solidity's semantic checking system, such as input parameter data location like "calldata" and "memory". As such, they can be safely dropped in the ABI as well.

Solidity JSON ABI

The Solidity JSON ABI is a standard format that many tools export, including the Solidity compiler. For the full specification, see the Solidity compiler documentation.

Various versions include slightly different keys and values. For example, early compilers included only a boolean "constant" to indicate mutability, while newer versions include a string "mutabilityState", which encompasses several older properties.

When creating an instance of a Fragment using a JSON ABI, it will automatically infer all legacy properties for new-age ABIs and for legacy ABIs will infer the new-age properties. All properties will be populated, so it will match the equivalent created using a Human-Readable ABI fragment.

Solidity Object ABI

The output from parsing (using JSON.parse) a Solidity JSON ABI is also fully compatible with the Interface class and each method, event and error from that object are compatible with the Fragment class.

Some developers may prefer this as it allows access to the ABI properties as normal JavaScript objects, and closely matches the JSON ABI that those familiar with the Solidity ABI will recognize.

Converting Between Formats

The Fragment object makes it simple to reformat a single method, event or error, however most developers will be interested in converting an entire ABI.

For production code it is recommended to inline the Human-Readable ABI as it makes it easy to see at a glance which methods, events and errors are available. It is also highly recommend to strip out unused parts of the ABI (such as admin methods) to further reduce code size.