Contract
Last updated
Last updated
A Contract is an abstraction of code that has been deployed.
A Contract may be sent transactions, which will trigger its code to be run with the input of the transaction data.
new hethers.Contract( address , abi , signerOrProvider )contract.attach( address ) ⇒ 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 ) ⇒ Returns a new instance of the Contract, but connected to providerOrSigner.
By passing in a , this will return a downgraded Contract which only has read-only access (i.e. constant calls).
By passing in a . this will return a Contract which will act on behalf of that signer.
contract.address ⇒ string< >This is the address the contract was constructed with.
contract.deployTransaction ⇒ If the Contract object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract.
If a signer was provided to the constructor, this is that signer.
Contract.isIndexed( value ) ⇒ booleanReturn Events that match the event.
contract.listenerCount( [ event ] ) ⇒ numberReturn 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 ) ⇒ thisUnsubscribe listener to event.
contract.on( event , listener ) ⇒ thisSubscribe to event calling listener when the event occurs.
contract.once( event , listener ) ⇒ thisSubscribe once to event calling listener when the event occurs.
contract.removeAllListeners( [ event ] ) ⇒ thisUnsubscribe all listeners for event. If no event is provided, all events are unsubscribed.
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.
A constant method (denoted by pure or view in Solidity) is read-only and evaluates a small amount of EVM code against the current state and can be computed by asking a single node, which can return a result. It requires the execution of ContractLocalCall transactions which require a signer to be connected. They cannot make changes to the 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, an < 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 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 - msg.value (or CALLVALUE) to use during the execution of the code
- overrides.gasLimit - the amount of gas (theoretically) to allow a node to use during the execution of the code
- overrides.nodeId - pass a specific node that will be called
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.
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.
A non-constant method requires a transaction to be signed and requires payment in the form of a fee to be paid to a node.
It cannot return a result. If a result is required, it should be logged using a Solidity event (or EVM log).
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 must:
- overrides.gasLimit - the limit on the amount of gas to allow the transaction to consume; any unused gas is returned
Other values that may be provided are:
- overrides.value - the amount of hbar (in tinybar) to forward with the call
If the wait() method on the returned TransactionResponse is called, there will be additional properties on the receipt:
- timestamp
- contractAddress
- gasUsed
- logsBloom
- transactionHash
- logs
- cumulativeGasUsed
- type
- byzantium
- status
- accountAddress
- events
There are several options to analyze the properties and results of a write method without actually executing it.
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 not 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.
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 ) ⇒ FilterReturn 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.
This is the ABI as an .
If a provider was provided to the constructor, this is that provider. If a signer was provided that had a , this is that provider.
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 is returned.
This simplifies frameworks that wish to use the object since they do not need to inspect the return types to unwrap simplified functions.