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

_section: Contract @<Contract> @SRC<contracts:class.Contract>

Explain contract here...

_subsection: Creating Instances @<Contract--creating>

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

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

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

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

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


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

There are secveral 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//.

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

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

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