Documentation

ABI Encoding

When sending values to or receiving values from a Contract, the data is generally encoded using the ABI standard.

The AbiCoder provides a utility to encode values to ABI data and decode values from ABI data.

Most of the time, developers should favour the Contract class, which further abstracts a lot of the finer details of ABI data.

class AbiCoder

The AbiCoder is a low-level class responsible for encoding JavaScript values into binary data and decoding binary data into JavaScript values.

CREATING INSTANCES

<src>AbiCoder.defaultAbiCoder()⇒ AbiCoder

Returns the shared singleton instance of a default AbiCoder.

On the first call, the instance is created internally.

METHODS

<src>abiCoder.decode(types: ReadonlyArray< string | ParamType >, data: BytesLike, loose?: boolean)⇒ Result

Decode the ABI data as the types into values.

If loose decoding is enabled, then strict padding is not enforced. Some older versions of Solidity incorrectly padded event data emitted from external functions.

<src>abiCoder.encode(types: ReadonlyArray< string | ParamType >, values: ReadonlyArray< any >)⇒ DataHexstring

Encode the values as the types into ABI data.

<src>abiCoder.getDefaultValue(types: ReadonlyArray< string | ParamType >)⇒ Result

Get the default values for the given types.

For example, a uint is by default 0 and bool is by default false.

STATIC METHODS

<src>AbiCoder.getBuiltinCallException(action: CallExceptionAction, tx: { data?: string , from?: null | string , to?: null | string }, data: null | BytesLike)⇒ CallExceptionError

Returns an ethers-compatible CallExceptionError Error for the given result data for the CallExceptionAction action against the Transaction tx.

Fragments

A fragment is a single item from an ABI, which may represent any of:

TYPES

<src>FormatType⇒ "sighash" | "minimal" | "full" | "json"

The format to serialize the output as.

"sighash" - the bare formatting, used to compute the selector or topic hash; this format cannot be reversed (as it discards indexed) so cannot by used to export an Interface.

"minimal" - Human-Readable ABI with minimal spacing and without names, so it is compact, but will result in Result objects that cannot be accessed by name.

"full" - Full Human-Readable ABI, with readable spacing and names intact; this is generally the recommended format.

"json" - The JSON ABI format.

The type of a Fragment.

<src>ParamTypeWalkAsyncFunc⇒ (type: string, value: any) => any | Promise< any >

When walking asynchronously a ParamType, this is called on each component.

<src>ParamTypeWalkFunc⇒ (type: string, value: any) => any

When walking a ParamType, this is called on each component.

class ConstructorFragment

inherits from Fragment

A Fragment which represents a constructor.

PROPERTIES

<src>constructorFragment.gas⇒ null | bigintread-only

The recommended gas limit for deployment or null.

<src>constructorFragment.payable⇒ booleanread-only

Whether the constructor can receive an endowment.

CREATING INSTANCES

<src>ConstructorFragment.from(obj: any)⇒ ConstructorFragment

Returns a new ConstructorFragment for obj.

METHODS

<src>constructorFragment.format(format?: FormatType)⇒ string

Returns a string representation of this constructor as format.

STATIC METHODS

<src>ConstructorFragment.isFragment(value: any)⇒ boolean

Returns true and provides a type guard if value is a ConstructorFragment.

class ErrorFragment

inherits from NamedFragment, Fragment

A Fragment which represents a Custom Error.

PROPERTIES

<src>errorFragment.selector⇒ stringread-only

The Custom Error selector.

CREATING INSTANCES

<src>ErrorFragment.from(obj: any)⇒ ErrorFragment

Returns a new ErrorFragment for obj.

METHODS

<src>errorFragment.format(format?: FormatType)⇒ string

Returns a string representation of this fragment as format.

STATIC METHODS

<src>ErrorFragment.isFragment(value: any)⇒ boolean

Returns true and provides a type guard if value is an ErrorFragment.

class EventFragment

inherits from NamedFragment, Fragment

A Fragment which represents an Event.

PROPERTIES

<src>eventFragment.anonymous⇒ booleanread-only

Whether this event is anonymous.

<src>eventFragment.topicHash⇒ stringread-only

The Event topic hash.

CREATING INSTANCES

<src>EventFragment.from(obj: any)⇒ EventFragment

Returns a new EventFragment for obj.

METHODS

<src>eventFragment.format(format?: FormatType)⇒ string

Returns a string representation of this event as format.

STATIC METHODS

<src>EventFragment.getTopicHash(name: string, params?: Array< any >)⇒ string

Return the topic hash for an event with name and params.

<src>EventFragment.isFragment(value: any)⇒ boolean

Returns true and provides a type guard if value is an EventFragment.

class FallbackFragment

inherits from Fragment

A Fragment which represents a method.

PROPERTIES

<src>fallbackFragment.payable⇒ booleanread-only

If the function can be sent value during invocation.

CREATING INSTANCES

<src>new FallbackFragment(guard: any, inputs: ReadonlyArray< ParamType >, payable: boolean)

<src>FallbackFragment.from(obj: any)⇒ FallbackFragment

Returns a new FallbackFragment for obj.

METHODS

<src>fallbackFragment.format(format?: FormatType)⇒ string

Returns a string representation of this fallback as format.

STATIC METHODS

<src>FallbackFragment.isFragment(value: any)⇒ boolean

Returns true and provides a type guard if value is a FallbackFragment.

abstract class Fragment

An abstract class to represent An individual fragment from a parse ABI.

PROPERTIES

<src>fragment.inputs⇒ ReadonlyArray< ParamType >read-only

The inputs for the fragment.

<src>fragment.type⇒ FragmentTyperead-only

The type of the fragment.

CREATING INSTANCES

<src>Fragment.from(obj: any)⇒ Fragment

Creates a new Fragment for obj, wich can be any supported ABI frgament type.

METHODS

<src>fragment.format(format?: FormatType)⇒ stringabstract

Returns a string representation of this fragment as format.

STATIC METHODS

<src>Fragment.isConstructor(value: any)⇒ boolean

Returns true if value is a ConstructorFragment.

<src>Fragment.isError(value: any)⇒ boolean

Returns true if value is an ErrorFragment.

<src>Fragment.isEvent(value: any)⇒ boolean

Returns true if value is an EventFragment.

<src>Fragment.isFunction(value: any)⇒ boolean

Returns true if value is a FunctionFragment.

<src>Fragment.isStruct(value: any)⇒ boolean

Returns true if value is a StructFragment.

class FunctionFragment

inherits from NamedFragment, Fragment

A Fragment which represents a method.

PROPERTIES

<src>functionFragment.constant⇒ booleanread-only

If the function is constant (e.g. pure or view functions).

<src>functionFragment.gas⇒ null | bigintread-only

The recommended gas limit to send when calling this function.

<src>functionFragment.outputs⇒ ReadonlyArray< ParamType >read-only

The returned types for the result of calling this function.

<src>functionFragment.payable⇒ booleanread-only

If the function can be sent value during invocation.

<src>functionFragment.selector⇒ stringread-only

The Function selector.

<src>functionFragment.stateMutability⇒ "payable" | "nonpayable" | "view" | "pure"read-only

The state mutability (e.g. payable, nonpayable, view or pure)

CREATING INSTANCES

<src>FunctionFragment.from(obj: any)⇒ FunctionFragment

Returns a new FunctionFragment for obj.

METHODS

<src>functionFragment.format(format?: FormatType)⇒ string

Returns a string representation of this function as format.

STATIC METHODS

<src>FunctionFragment.getSelector(name: string, params?: Array< any >)⇒ string

Return the selector for a function with name and params.

<src>FunctionFragment.isFragment(value: any)⇒ boolean

Returns true and provides a type guard if value is a FunctionFragment.

interface JsonFragment

A fragment for a method, event or error in a JSON ABI format.

PROPERTIES

<src>jsonFragment.anonymous⇒ booleanread-only

If the event is anonymous.

<src>jsonFragment.constant⇒ booleanread-only

If the function is constant.

<src>jsonFragment.gas⇒ stringread-only

The gas limit to use when sending a transaction for this function.

<src>jsonFragment.inputs⇒ ReadonlyArray< JsonFragmentType >read-only

The input parameters.

<src>jsonFragment.name⇒ stringread-only

The name of the error, event, function, etc.

<src>jsonFragment.outputs⇒ ReadonlyArray< JsonFragmentType >read-only

The output parameters.

<src>jsonFragment.payable⇒ booleanread-only

If the function is payable.

<src>jsonFragment.stateMutability⇒ stringread-only

The mutability state of the function.

<src>jsonFragment.type⇒ stringread-only

The type of the fragment (e.g. event, "function", etc.)

interface JsonFragmentType

A Type description in a JSON ABI format.

PROPERTIES

<src>jsonFragmentType.components⇒ ReadonlyArray< JsonFragmentType >read-only

The components for a tuple.

<src>jsonFragmentType.indexed⇒ booleanread-only

If the parameter is indexed.

<src>jsonFragmentType.internalType⇒ stringread-only

The internal Solidity type.

<src>jsonFragmentType.name⇒ stringread-only

The parameter name.

<src>jsonFragmentType.type⇒ stringread-only

The type of the parameter.

abstract class NamedFragment

inherits from Fragment

An abstract class to represent An individual fragment which has a name from a parse ABI.

PROPERTIES

<src>namedFragment.name⇒ stringread-only

The name of the fragment.

class ParamType

Each input and output of a Fragment is an Array of ParamType.

PROPERTIES

<src>paramType.arrayChildren⇒ null | ParamTyperead-only

The type of each child in the array.

For non-array types this is null.

<src>paramType.arrayLength⇒ null | numberread-only

The array length, or -1 for dynamic-lengthed arrays.

For non-array types this is null.

<src>paramType.baseType⇒ stringread-only

The base type (e.g. "address", "tuple", "array")

<src>paramType.components⇒ null | ReadonlyArray< ParamType >read-only

The components for the tuple.

For non-tuple types this is null.

<src>paramType.indexed⇒ null | booleanread-only

True if the parameters is indexed.

For non-indexable types this is null.

<src>paramType.name⇒ stringread-only

The local name of the parameter (or "" if unbound)

<src>paramType.type⇒ stringread-only

The fully qualified type (e.g. "address", "tuple(address)", "uint256[3][]")

CREATING INSTANCES

<src>ParamType.from(obj: any, allowIndexed?: boolean)⇒ ParamType

Creates a new ParamType for obj.

If allowIndexed then the indexed keyword is permitted, otherwise the indexed keyword will throw an error.

METHODS

<src>paramType.format(format?: FormatType)⇒ string

Return a string representation of this type.

For example,

sighash" => "(uint256,address)"

"minimal" => "tuple(uint256,address) indexed"

"full" => "tuple(uint256 foo, address bar) indexed baz"

<src>paramType.isArray()⇒ boolean

Returns true if this is an Array type.

This provides a type gaurd ensuring that arrayChildren and arrayLength are non-null.

<src>paramType.isIndexable()⇒ boolean

Returns true if this is an Indexable type.

This provides a type gaurd ensuring that indexed is non-null.

<src>paramType.isTuple()⇒ boolean

Returns true if this is a Tuple type.

This provides a type gaurd ensuring that components is non-null.

<src>paramType.walk(value: any, process: ParamTypeWalkFunc)⇒ any

Walks the ParamType with value, calling process on each type, destructing the value recursively.

<src>paramType.walkAsync(value: any, process: ParamTypeWalkAsyncFunc)⇒ Promise< any >

Walks the ParamType with value, asynchronously calling process on each type, destructing the value recursively.

This can be used to resolve ENS naes by walking and resolving each "address" type.

STATIC METHODS

<src>ParamType.isParamType(value: any)⇒ boolean

Returns true if value is a ParamType.

class StructFragment

inherits from NamedFragment, Fragment

A Fragment which represents a structure.

CREATING INSTANCES

<src>StructFragment.from(obj: any)⇒ StructFragment

Returns a new StructFragment for obj.

METHODS

<src>structFragment.format()⇒ string

Returns a string representation of this struct as format.

STATIC METHODS

<src>StructFragment.isFragment(value: any)⇒ boolean

Returns true and provides a type guard if value is a StructFragment.