ethers.js/docs.wrm/api/contract/contract.wrm

_section: Contract @<Contract> @SRC<contracts:class.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.

_subsection: Creating Instances @<Contract--creating>

_property: new ethers.Contract(address, abi, signerOrProvider) @src<contracts:class.Contract>

_property: contract.attach(addressOrName) => [[Contract]]  @<Contract-attach> @SRC<contracts:BaseContract.attach>
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.

_property: contract.connect(providerOrSigner) => [[Contract]]  @<Contract-connect> @SRC<contracts:BaseContract.connect>
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.


_subsection: Properties  @<Contract--properties>

_property: contract.address => string<[[address]]>
This is the address (or ENS name) the contract was constructed with.

_property: 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.

_property: contract.deployTransaction => [[providers-TransactionResponse]]
If the **Contract** object is the result of a ContractFactory deployment,
this is the transaction which was used to deploy the contract.

_property: contract.interface => [[Interface]]
This is the ABI as an [[Interface]].

_property: 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.

_property: contract.signer => [[Signer]]
If a signer was provided to the constructor, this is that signer.


_subsection: Methods @<Contract--methods>

_property: contract.deployed() => Promise<[[Contract]]>  @<Contract-deployed> @SRC<contracts>

_property: Contract.isIndexed(value) => boolean  @<Contract-isIndexed> @SRC<contracts>


_subsection: Events @<Contract--events>

_property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<Contract-queryFilter> @SRC<contracts>
Return Events that match the //event//.

_property: contract.listenerCount([ event ]) => number  @<Contract-listenerCount> @SRC<contracts:BaseContract.listenerCount>
Return the number of listeners that are subscribed to //event//. If
no event is provided, returns the total count of all events.

_property: contract.listeners(event) => Array<Listener>  @<Contract-listeners> @SRC<contracts:BaseContract.listeners>
Return a list of listeners that are subscribed to //event//.

_property: contract.off(event, listener) => this  @<Contract-off> @SRC<contracts>
Unsubscribe //listener// to //event//.

_property: contract.on(event, listener) => this  @<Contract-on> @SRC<contracts>
Subscribe to //event// calling //listener// when the event occurs.

_property: contract.once(event, listener) => this  @<Contract-once> @SRC<contracts>
Subscribe once to //event// calling //listener// when the event
occurs.

_property: contract.removeAllListeners([ event ]) => this  @<Contract-removeAllListeners> @SRC<contracts:BaseContract.removeAllListeners>
Unsubscribe all listeners for //event//. If no event is provided,
all events are unsubscribed.


_subsection: Meta-Class  @<Contract--metaclass>

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.


_heading: Read-Only Methods (constant)  @<Contract--readonly>

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..

_property: contract.METHOD_NAME(...args [, overrides ]) => Promise<any>  @<Contract-functionsCall>
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
straight forward; 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](errors--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

_property: 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.

_heading: Write Methods (non-constant) @<Contract--write>

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.

_property: contract.METHOD_NAME(...args [ , overrides ]) => Promise<[[providers-TransactionResponse]]>  @<contract-functionsSend>
Returns a [[providers-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 [[providers-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](providers-Block) this event occurred in
- ``receipt.getTransaction()`` - a method to return the
  [Transaction](providers-TransactionResponse) this event occurred in
- ``receipt.getTransactionReceipt()`` - a method to return the
  [Transaction Receipt](providers-TransactionReceipt) this event occurred in


_heading: Write Methods Analysis @<Contract--check>

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

_property: contract.estimateGas.METHOD_NAME(...args [ , overrides ]) => Promise<[[BigNumber]]>  @<contract-estimateGas>
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//.

_property: contract.populateTransaction.METHOD_NAME(...args [ , overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)>  @<contract-populateTransaction>
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//.

_property: contract.callStatic.METHOD_NAME(...args [ , overrides ]) => Promise<any>  @<contract-callStatic>
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](Contract--readonly).

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

_heading: Event Filters @<Contract--filters>
An event filter is made up of topics, which are values logged in a
[[link-wiki-bloomfilter]], allowing efficient searching for entries
which match a filter.

_property: 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.