Contract

A Contract is an abstraction of code that has been deployed to the blockchain.

A Contract may be sent transactions, which will trigger its code to be run with the input of the transaction data.

Creating Instances

new ethers.Contract( address , abi , signerOrProvider )
contract.attach( addressOrName ) Contract

Returns a new instance of the Contract attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them.

contract.connect( providerOrSigner ) Contract

Returns a new instance of the Contract, but connected to providerOrSigner.

By passing in a Provider, this will return a downgraded Contract which only has read-only access (i.e. constant calls).

By passing in a Signer. this will return a Contract which will act on behalf of that signer.

Properties

contract.address string< Address >

This is the address (or ENS name) the contract was constructed with.

contract.resolvedAddress string< Address >

This is a promise that will resolve to the address the Contract object is attached to. If an Address was provided to the constructor, it will be equal to this; if an ENS name was provided, this will be the resolved address.

contract.deployTransaction TransactionResponse

If the Contract object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract.

contract.interface Interface

This is the ABI as an Interface.

contract.provider Provider

If a provider was provided to the constructor, this is that provider. If a signer was provided that had a Provider, this is that provider.

contract.signer Signer

If a signer was provided to the constructor, this is that signer.

Methods

contract.deployed( ) Promise< Contract >
Contract.isIndexed( value ) boolean

Events

contract.queryFilter( event [ , fromBlockOrBlockHash [ , toBlock ] ) Promise< Array< Event > >

Return Events that match the event.

contract.listenerCount( [ event ] ) number

Return the number of listeners that are subscribed to event. If no event is provided, returns the total count of all events.

contract.listeners( event ) Array< Listener >

Return a list of listeners that are subscribed to event.

contract.off( event , listener ) this

Unsubscribe listener to event.

contract.on( event , listener ) this

Subscribe to event calling listener when the event occurs.

contract.once( event , listener ) this

Subscribe once to event calling listener when the event occurs.

contract.removeAllListeners( [ event ] ) this

Unsubscribe all listeners for event. If no event is provided, all events are unsubscribed.

Meta-Class

A Meta-Class is a Class which has any of its properties determined at run-time. The Contract object uses a Contract's ABI to determine what methods are available, so the following sections describe the generic ways to interact with the properties added at run-time during the Contract constructor.

Read-Only Methods (constant)

A constant method (denoted by pure or view in Solidity) is read-only and evaluates a small amount of EVM code against the current blockchain state and can be computed by asking a single node, which can return a result. It is therefore free and does not require any ether, but cannot make changes to the blockchain state..

contract.METHOD_NAME( ...args [ , overrides ] ) Promise< any >

The type of the result depends on the ABI. If the method returns a single value, it will be returned directly, otherwise a Result object will be returned with each parameter available positionally and if the parameter is named, it will also be available by its name.

For values that have a simple meaning in JavaScript, the types are fairly straightforward; strings and booleans are returned as JavaScript strings and booleans.

For numbers, if the type is in the JavaScript safe range (i.e. less than 53 bits, such as an int24 or uint48) a normal JavaScript number is used. Otherwise a BigNumber is returned.

For bytes (both fixed length and dynamic), a DataHexString is returned.

If the call reverts (or runs out of gas), a CALL_EXCEPTION will be thrown which will include:

  • error.address - the contract address
  • error.args - the arguments passed into the method
  • error.transaction - the transaction

The overrides object for a read-only method may include any of:

  • overrides.from - the msg.sender (or CALLER) to use during the execution of the code
  • overrides.value - the msg.value (or CALLVALUE) to use during the execution of the code
  • overrides.gasPrice - the price to pay per gas (theoretically); since there is no transaction, there is not going to be any fee charged, but the EVM still requires a value to report to tx.gasprice (or GASPRICE); most developers will not require this
  • overrides.gasLimit - the amount of gas (theoretically) to allow a node to use during the execution of the code; since there is no transaction, there is not going to be any fee charged, but the EVM still processes gas metering so calls like gasleft (or GAS) report meaningful values
  • overrides.blockTag - a block tag to simulate the execution at, which can be used for hypothetical historic analysis; note that many backends do not support this, or may require paid plans to access as the node database storage and processing requirements are much higher

contract.functions.METHOD_NAME( ...args [ , overrides ] ) Promise< Result >

The result will always be a Result, even if there is only a single return value type.

This simplifies frameworks which wish to use the Contract object, since they do not need to inspect the return types to unwrap simplified functions.

Another use for this method is for error recovery. For example, if a function result is an invalid UTF-8 string, the normal call using the above meta-class function will throw an exception. This allows using the Result access error to access the low-level bytes and reason for the error allowing an alternate UTF-8 error strategy to be used.

Most developers should not require this.

The overrides are identical to the read-only operations above.

Write Methods (non-constant)

A non-constant method requires a transaction to be signed and requires payment in the form of a fee to be paid to a miner. This transaction will be verified by every node on the entire network as well by the miner who will compute the new state of the blockchain after executing it against the current state.

It cannot return a result. If a result is required, it should be logged using a Solidity event (or EVM log), which can then be queried from the transaction receipt.

contract.METHOD_NAME( ...args [ , overrides ] ) Promise< TransactionResponse >

Returns a TransactionResponse for the transaction after it is sent to the network. This requires the Contract has a signer.

The overrides object for write methods may include any of:

  • overrides.gasPrice - the price to pay per gas
  • overrides.gasLimit - the limit on the amount of gas to allow the transaction to consume; any unused gas is returned at the gasPrice
  • overrides.value - the amount of ether (in wei) to forward with the call
  • overrides.nonce - the nonce to use for the Signer

If the wait() method on the returned TransactionResponse is called, there will be additional properties on the receipt:

  • receipt.events - an array of the logs, with additional properties (if the ABI included a description for the events)
  • receipt.events[n].args - the parsed arguments
  • receipt.events[n].decode - a method that can be used to parse the log topics and data (this was used to compute args)
  • receipt.events[n].event - the name of the event
  • receipt.events[n].eventSignature - the full signature of the event
  • receipt.removeListener() - a method to remove the listener that trigger this event
  • receipt.getBlock() - a method to return the Block this event occurred in
  • receipt.getTransaction() - a method to return the Transaction this event occurred in
  • receipt.getTransactionReceipt() - a method to return the Transaction Receipt this event occurred in

Write Methods Analysis

There are several options to analyze properties and results of a write method without actually executing it.

contract.estimateGas.METHOD_NAME( ...args [ , overrides ] ) Promise< BigNumber >

Returns the estimate units of gas that would be required to execute the METHOD_NAME with args and overrides.

The overrides are identical to the overrides above for read-only or write methods, depending on the type of call of METHOD_NAME.

contract.populateTransaction.METHOD_NAME( ...args [ , overrides ] ) Promise< UnsignedTx >

Returns an UnsignedTransaction which represents the transaction that would need to be signed and submitted to the network to execute METHOD_NAME with args and overrides.

The overrides are identical to the overrides above for read-only or write methods, depending on the type of call of METHOD_NAME.

contract.callStatic.METHOD_NAME( ...args [ , overrides ] ) Promise< any >

Rather than executing the state-change of a transaction, it is possible to ask a node to pretend that a call is not state-changing and return the result.

This does not actually change any state, but is free. This in some cases can be used to determine if a transaction will fail or succeed.

This otherwise functions the same as a Read-Only Method.

The overrides are identical to the read-only operations above.

Event Filters

An event filter is made up of topics, which are values logged in a Bloom Filter, allowing efficient searching for entries which match a filter.

contract.filters.EVENT_NAME( ...args ) Filter

Return a filter for EVENT_NAME, optionally filtering by additional constraints.

Only indexed event parameters may be filtered. If a parameter is null (or not provided) then any value in that field matches.