256 lines
12 KiB
Plaintext
256 lines
12 KiB
Plaintext
_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
|
|
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](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.
|