302 lines
7.4 KiB
Plaintext
302 lines
7.4 KiB
Plaintext
_section: Migration: From Ethers v4 @<migration-v4>
|
|
|
|
This document only covers the features present in v4 which have changed
|
|
in some important way in v5.
|
|
|
|
It does not cover all the new additional features that have been added and
|
|
mainly aims to help those updating their older scripts and applications to
|
|
retain functional parity.
|
|
|
|
If you encounter any missing changes, please let me know and I'll update this
|
|
guide.
|
|
|
|
|
|
_subsection: BigNumber
|
|
|
|
_heading: Namespace
|
|
Since [[BigNumber]] is used quite frequently, it has been moved to
|
|
the top level of the umbrella package.
|
|
|
|
_code: @lang<script>
|
|
|
|
// v4
|
|
ethers.utils.BigNumber
|
|
ethers.utils.BigNumberish
|
|
|
|
// v5
|
|
ethers.BigNumber
|
|
ethers.BigNumberish
|
|
|
|
|
|
_heading: Creating Instances
|
|
|
|
The ``bigNumberify`` method was always preferred over the constructor
|
|
since it could short-circuit an object instantiation for [[BigNumber]
|
|
objects (since they are immutable). This has been moved to a static
|
|
``from`` class method.
|
|
|
|
_code: @lang<script>
|
|
|
|
// v4
|
|
new ethers.utils.BigNumber(someValue)
|
|
ethers.utils.bigNumberify(someValue);
|
|
|
|
// v5
|
|
// - Constructor is private
|
|
// - Removed `bigNumberify`
|
|
ethers.BigNumber.from(someValue)
|
|
|
|
|
|
_subsection: Contracts
|
|
|
|
_heading: ENS Name Resolution
|
|
|
|
The name of the resolved address has changed. If the address passed into the
|
|
constructor was an ENS name, the address will be resolved before any calls
|
|
are made to the contract.
|
|
|
|
The name of the property where the resolved address has changed from ``addressPromise``
|
|
to ``resolvedAddress``.
|
|
|
|
_code: Resolved ENS Names @lang<script>
|
|
|
|
// v4
|
|
contract.addressPromise
|
|
|
|
// v5
|
|
contract.resolvedAddress
|
|
|
|
|
|
_heading: Gas Estimation
|
|
|
|
The only difference in gas estimation is that the bucket has changed
|
|
its name from ``estimate`` to ``estimateGas``.
|
|
|
|
_code: Gas Estimation @lang<script>
|
|
|
|
// v4
|
|
contract.estimate.transfer(toAddress, amount)
|
|
|
|
// v5
|
|
contract.estimateGas.transfer(toAddress, amount)
|
|
|
|
_heading: Functions
|
|
|
|
In a contract in ethers, there is a ``functions`` bucket, which exposes
|
|
all the methods of a contract.
|
|
|
|
All these functions are available on the root contract itself as well
|
|
and historically there was no difference between ``contact.foo`` and
|
|
``contract.functions.foo``. The original reason for the ``functions`` bucket
|
|
was to help when there were method names that collided with other buckets,
|
|
which is rare.
|
|
|
|
In v5, the ``functions`` bucket is now intended to help with frameworks and
|
|
for the new error recovery API, so most users should use the methods on the
|
|
root contract.
|
|
|
|
The main difference will occur when a contract method only returns a single
|
|
item. The root method will dereference this automatically while the ``functions``
|
|
bucket will preserve it as an [[Result]].
|
|
|
|
If a method returns multiple items, there is no difference.
|
|
|
|
This helps when creating a framework, since the result will always be known to
|
|
have the same number of components as the [[Fragment]] outputs, without having
|
|
to handle the special case of a single return value.
|
|
|
|
_code: Functions Bucket @lang<script>
|
|
|
|
const abi = [
|
|
|
|
// Returns a single value
|
|
"function single() view returns (uint8)",
|
|
|
|
// Returns two values
|
|
"function double() view returns (uint8, uint8)",
|
|
];
|
|
|
|
// v4
|
|
await contract.single()
|
|
// 123
|
|
await contract.functions.single()
|
|
// 123
|
|
|
|
|
|
// v5 (notice the change in the .function variant)
|
|
await contract.single()
|
|
// 123
|
|
await contract.functions.single()
|
|
// [ 123 ]
|
|
|
|
|
|
// v4
|
|
await contract.double()
|
|
// [ 123, 5 ]
|
|
await contract.functions.double()
|
|
// [ 123, 5 ]
|
|
|
|
|
|
// v5 (no difference from v4)
|
|
await contract.double()
|
|
// [ 123, 5 ]
|
|
await contract.functions.double()
|
|
// [ 123, 5 ]
|
|
|
|
|
|
_subsection: Errors
|
|
|
|
_heading: Namespace
|
|
All errors now belong to the [[Logger]] class and the related functions
|
|
have been moved to [[Logger]] instances, which can include a per-package
|
|
version string.
|
|
|
|
Global error functions have been moved to [[Logger]] class methods.
|
|
|
|
_code: @lang<script>
|
|
|
|
// v4
|
|
ethers.errors.UNKNOWN_ERROR
|
|
ethers.errors.*
|
|
|
|
errors.setCensorship(censorship, permanent)
|
|
errors.setLogLevel(logLevel)
|
|
|
|
errors.checkArgumentCount(count, expectedCount, suffix)
|
|
errors.checkNew(self, kind)
|
|
errors.checkNormalize()
|
|
errors.throwError(message, code, params)
|
|
errors.warn(...)
|
|
errors.info(...)
|
|
|
|
// v5
|
|
ethers.utils.Logger.errors.UNKNOWN_ERROR
|
|
ethers.utils.Logger.errors.*
|
|
|
|
Logger.setCensorship(censorship, permanent)
|
|
Logger.setLogLevel(logLevel)
|
|
|
|
const logger = new ethers.utils.Logger(version);
|
|
logger.checkArgumentCount(count, expectedCount, suffix)
|
|
logger.checkNew(self, kind)
|
|
logger.checkNormalize()
|
|
logger.throwError(message, code, params)
|
|
logger.warn(...)
|
|
logger.info(...)
|
|
|
|
|
|
_subsection: Interface
|
|
|
|
The [[Interface]] object has undergone the most dramatic changes.
|
|
|
|
It is no longer a meta-class and now has methods that simplify handling
|
|
contract interface operations without the need for object inspection and
|
|
special edge cases.
|
|
|
|
_heading: Functions
|
|
|
|
_code: @lang<script>
|
|
|
|
// v4 (example: "transfer(address to, uint amount)")
|
|
interface.functions.transfer.encode(to, amount)
|
|
interface.functions.transfer.decode(callData)
|
|
|
|
// v5
|
|
interface.encodeFunctionData("transfer", [ to, amount ])
|
|
interface.decodeFunctionResult("transfer", data)
|
|
|
|
// Or you can use any compatible signature or Fragment objects.
|
|
// Notice that signature normalization is performed for you,
|
|
// e.g. "uint" and "uint256" will be automatically converted
|
|
interface.encodeFunctionData("transfer(address,uint)", [ to, amount ])
|
|
interface.decodeFunctionResult("transfer(address to, uint256 amount)", data)
|
|
|
|
|
|
_heading: Events
|
|
|
|
_code: @lang<script>
|
|
|
|
// v4 (example: Transfer(address indexed, address indexed, uint256)
|
|
interface.events.Transfer.encodeTopics(values)
|
|
interface.events.Transfer.decode(data, topics)
|
|
|
|
// v5
|
|
interface.encodeFilterTopics("Transfer", values)
|
|
interface.decodeEventLog("Transfer", data, topics)
|
|
|
|
|
|
_heading: Inspection
|
|
Interrogating properties about a function or event can now (mostly) be
|
|
done directly on the [[Fragment]] object.
|
|
|
|
_code:
|
|
|
|
// v4
|
|
interface.functions.transfer.name
|
|
interface.functions.transfer.inputs
|
|
interface.functions.transfer.outputs
|
|
interface.functions.transfer.payable
|
|
interface.functions.transfer.gas
|
|
|
|
// v5
|
|
const functionFragment = interface.getFunction("transfer")
|
|
functionFragment.name
|
|
functionFragment.inputs
|
|
functionFragment.outputs
|
|
functionFragment.payable
|
|
functionFragment.gas
|
|
|
|
|
|
// v4; type is "call" or "transaction"
|
|
interface.functions.transfer.type
|
|
|
|
// v5; constant is true (i.e. "call") or false (i.e. "transaction")
|
|
functionFragment.constant
|
|
|
|
|
|
// v4
|
|
interface.events.Transfer.anonymous
|
|
interface.events.Transfer.inputs
|
|
interface.events.Transfer.name
|
|
|
|
// v5
|
|
const eventFragment = interface.getEvent("Transfer");
|
|
eventFragment.anonymous
|
|
eventFragment.inputs
|
|
eventFragment.name
|
|
|
|
|
|
// v4
|
|
const functionSig = interface.functions.transfer.signature
|
|
const sighash = interface.functions.transfer.sighash
|
|
|
|
const eventSig = interface.events.Transfer.signature
|
|
const topic = interface.events.Transfer.topic
|
|
|
|
// v5
|
|
const functionSig = functionFragment.format()
|
|
const sighash = interface.getSighash(functionFragment)
|
|
|
|
const eventSig = eventFragment.format()
|
|
const topic = interface.getTopic(eventFragment)
|
|
|
|
|
|
_subsection: Wallet
|
|
|
|
_heading: Mnemonic Phrases
|
|
The **mnemonic** phrase and related properties have been merged into
|
|
a single ``mnemonic`` object, which also now includes the ``locale``.
|
|
|
|
_code: @lang<script>
|
|
|
|
// v4
|
|
wallet.mnemonic
|
|
wallet.path
|
|
|
|
// v5
|
|
// - Mnemonic phrase and path are a Mnemonic object
|
|
// - Note: wallet.mnemonic is null if there is no mnemonic
|
|
wallet.mnemonic.phrase
|
|
wallet.mnemonic.path
|
|
|