Interface

The Interface Class abstracts the encoding and decoding required to interact with contracts on the Ethereum network.

Many of the standards organically evolved along side the Solidity language, which other languages have adopted to remain compatible with existing deployed contracts.

The EVM itself does not understand what the ABI is. It is simply an agreed upon set of formats to encode various types of data which each contract can expect so they can interoperate with each other.

Creating Instances

new ethers.utils.Interface( abi )

Create a new Interface from a JSON string or object representing abi.

The abi may be a JSON string or the parsed Object (using JSON.parse) which is emitted by the Solidity compiler (or compatible languages).

The abi may also be a Human-Readable Abi, which is a format the Ethers created to simplify manually typing the ABI into the source and so that a Contract ABI can also be referenced easily within the same source file.

Properties

interface.fragments Array< Fragment >

All the Fragments in the interface.

interface.events Array< EventFragment >

All the Event Fragments in the interface.

interface.functions Array< FunctionFragment >

All the Function Fragments in the interface.

interface.deploy ConstructorFragment

The Constructor Fragments for the interface.

Formatting

interface.format( [ format ] ) string | Array< string >

Return the formatted Interface. If the format type is json a single string is returned, otherwise an Array of the human-readable strings is returned.

Fragment Access

interface.getFunction( fragment ) FunctionFragment

Returns the FunctionFragment for fragment (see Specifying Fragments).

interface.getEvent( fragment ) EventFragment

Returns the EventFragment for fragment (see Specifying Fragments).

Signature and Topic Hashes

interface.getSighash( fragment ) string< DataHexString< 4 > >

Return the sighash (or Function Selector) for fragment (see Specifying Fragments).

interface.getEventTopic( fragment ) string< DataHexString< 32 > >

Return the topic hash for fragment (see Specifying Fragments).

Encoding Data

interface.encodeDeploy( [ values ] ) string< DataHexString >

Return the encoded deployment data, which can be concatenated to the deployment bytecode of a contract to pass values into the contract constructor.

interface.encodeFilterTopics( fragment [ , values ] ) Array< topic | Array< topic > >

Returns the encoded topic filter, which can be passed to getLogs for fragment (see Specifying Fragments) for the given values.

Each topic is a 32 byte (64 nibble) DataHexString.

interface.encodeFunctionData( fragment [ , values ] ) string< DataHexString >

Returns the encoded data, which can be used as the data for a transaction for fragment (see Specifying Fragments) for the given values.

interface.encodeFunctionResult( fragment [ , values ] ) string< DataHexString >

Returns the encoded result, which would normally be the response from a call for fragment (see Specifying Fragments) for the given values.

Most developers will not need this method, but may be useful for authors of a mock blockchain.

Decoding Data

interface.decodeEventLog( fragment , data [ , topics ] ) Result

Returns the decoded event values from an event log for fragment (see Specifying Fragments) for the given data with the optional topics.

If topics is not specified, placeholders will be inserted into the result.

interface.decodeFunctionData( fragment , data ) Result

Returns the decoded values from transaction data for fragment (see Specifying Fragments) for the given data.

Most developers will not need this method, but may be useful for debugging or inspecting transactions.

interface.decodeFunctionResult( fragment , data ) Result

Returns the decoded values from the result of a call for fragment (see Specifying Fragments) for the given data.

Parsing

The functions are generally the most useful for most developers. They will automatically search the ABI for a matching Event or Function and decode the components as a fully specified description.

interface.parseLog( log ) LogDescription

Search the event that matches the log topic hash and parse the values the log represents.

interface.parseTransaction( transaction ) TransactionDescription

Search for the function that matches the transaction data sighash and parse the transaction properties.

Types

Result inherits Array<any>

A Result is an array, so each value can be accessed as a positional argument.

Additionally, if values are named, the identical object as its positional value can be accessed by its name.

The name length is however reserved as it is part of the Array, so any named value for this key is renamed to _length. If there is a name collision, only the first is available by its key.

LogDescription

logDescription.args Result

The values of the input parameters of the event.

logDescription.eventFragment EventFragment

The EventFragment which matches the topic in the Log.

logDescription.name string

The event name. (e.g. Transfer)

logDescription.signature string

The event signature. (e.g. Transfer(address,address,uint256))

logDescription.topic string

The topic hash.

TransactionDescription

transactionDescription.args Result

The decoded values from the transaction data which were passed as the input parameters.

transactionDescription.functionFragment FunctionFragment

The FunctionFragment which matches the sighash in the transaction data.

transactionDescription.name string

The name of the function. (e.g. transfer)

transactionDescription.sighash string

The sighash (or function selector) that matched the transaction data.

transactionDescription.signature string

The signature of the function. (e.g. transfer(address,uint256))

transactionDescription.value BigNumber

The value from the transaction.

Specifying Fragments

When specifying a fragment to any of the functions in an Interface, any of the following may be used: