Documentation

Documentation (single page)

Documentation

The ethers.js library aims to be a complete and compact library for interacting with the Ethereum Blockchain and its ecosystem.

It is often used to create decentralized applications (dapps), wallets (such as MetaMask and Tally) and other tools and simple scripts that require reading and writing to the blockchain.

About this documentation?

These docs are still under construction, and are being expanded every day.

Developers new to Ethers should be sure to read through the Getting Started section.

And the Application Programming Interface is available for drilling down into more details about the entire Application Programming Interface.

Older Documentation

Getting Started

This is a very short introduction to Ethers, but covers many of the most common operations that developers require and provides a starting point for those newer to Ethereum.

Getting Ethers

If using NPM, you must first install Ethers.

installing via NPM

# Install ethers
/home/ricmoo/test-ethers> npm install ethers@beta-exports

Everything in Ethers is exported from its root as well as on the ethers object. There are also exports in the package.json to facilitate more fine-grained importing.

Generally this documentation will presume all exports from ethers have been imported in the code examples, but you may import the necessary objects any way you wish.

importing in Node.js

// Import everything
import { ethers } from "ethers";

// Import just a few select items
import { BrowserProvider, parseUnits } from "ethers";

// Import from a specific export
import { HDNodeWallet } from "ethers/wallet";

importing ESM in a browser

<script type="module">
  import { ethers } from "https://cdnjs.cloudflare.com/ajax/libs/ethers/5.7.2/ethers.min.js";
  // Your code here...
</script>

Some Common Terminology

To begin, it is useful to have a basic understanding of the types of objects available and what they are responsible for, at a high level.

Provider

A Provider is a read-only connection to the blockchain, which allows querying the blockchain state, such as account, block or transaction details, querying event logs or evaluating read-only code using call.

If you are coming from Web3.js, you are used to a Provider offering both read and write access. In Ethers, all write operations are further abstracted into another Object, the Signer.

Signer

A Signer wraps all operations that interact with an account. An account generally has a private key located somewhere, which can be used to sign a variety of types of payloads.

The private key may be located in memory (using a Wallet) or protected via some IPC layer, such as MetaMask which proxies interaction from a website to a browser plug-in, which keeps the private key out of the reach of the website and only permits interaction after requesting permission from the user and receiving authorization.

Transaction

To make any state changes to the blockchain, a transaction is required, which requires a fee be paid, where the fee covers the associated costs with executing the transaction (such as reading the disk and performing maths) and storing the updated information.

If a transaction reverts, a fee must still be paid, since the validator still had to expend resources to try running the transaction to determine that it reverted and the details of its failure are still be recorded.

Transactions include sending ether from one user to another, deploying a Contract or executing a state-changing operation against a Contract.

Contract

A Contract is a program that has been deployed to the blockchain, which includes some code and has allocated storage which it can read from and write to.

It may be read from when it is connected to a Provider or state-changing operations can be called when connected to a Signer.

Receipt

Once a Transaction has been submitted to the blockchain, it is placed in the memory pool (mempool) until a validator decides to include it.

A transaction's changes are only made once it has been included in the blockchain, at which time a receipt is available, which includes details about the transaction, such as which block it was included in, the actual fee paid, gas used, all the events that it emitted and whether it was successful or reverted.

Connecting to Ethereum

This very first thing needed to begin interacting with the blockchain is connecting to it using a Provider.

MetaMask (and other injected providers)

The quickest and easiest way to experiment and begin developing on Ethereum is to use MetaMask, which is a browser extension that injects objects into the window, providing:

read-only access to the Ethereum network (a Provider)
authenticated write access backed by a private key (a Signer)

When requesting access to the authenticated methods, such as sending a transaction or even requesting the private key address, MetaMask will show a pop-up to the user asking for permission.

let signer = null;

let provider;
if (window.ethereum == null) {

    // If MetaMask is not installed, we use the default provider,
    // which is backed by a variety of third-party services (such
    // as INFURA). They do not have private keys installed so are
    // only have read-only access
    console.log("MetaMask not installed; using read-only defaults")
    provider = ethers.getDefaultProvider()

} else {

    // Connect to the MetaMask EIP-1193 object. This is a standard
    // protocol that allows Ethers access to make all read-only
    // requests through MetaMask.
    provider = new ethers.BrowserProvider(window.ethereum)

    // It also provides an opportunity to request access to write
    // operations, which will be performed by the private key
    // that MetaMask manages for the user.
    signer = await provider.getSigner();
}

Custom RPC Backend

If you are running your own Ethereum node (e.g. Geth) or using a custom third-party service (e.g. INFURA), you can use the JsonRpcProvider directly, which communicates using the link-jsonrpc protocol.

When using your own Ethereum node or a developer-base blockchain, such as Hardhat or Ganache, you can get access the accounts with JsonRpcProvider-getSigner.

connecting to a JSON-RPC URL

// If no %%url%% is provided, it connects to the default
// http://localhost:8545, which most nodes use.
provider = new ethers.JsonRpcProvider(url)

// Get write access as an account by getting the signer
signer = await provider.getSigner()

User Interaction

All units in Ethereum tend to be integer values, since dealing with decimals and floating points can lead to imprecise and non-obvious results when performing mathematic operations.

As a result, the internal units used (e.g. wei) which are suited for machine-readable purposes and maths are often very large and not terribly human-readable.

For example, imagine dealing with dollars and cents; you would show values like "$2.56". In the blockchain world we would keep all values as cents, so that would be 256 cents, internally.

So, when accepting data that a user types, it must be converted from its decimal string representation (e.g. "2.56") to its lowest-unit integer representation (e.g. 256). And when displaying a value to a user the opposite operation is necessary.

In Ethereum, one ether is equal to 10 ** 18 wei and one gwei is equal to 10 ** 9 wei, so the values get very large very quickly, so some convenience functions are provided to help convert between representations.

// Convert user-provided strings in ether to wei for a value
eth = parseEther("1.0")
// 1000000000000000000n

// Convert user-provided strings in gwei to wei for max base fee
feePerGas = parseUnits("4.5", "gwei")
// 4500000000n

// Convert a value in wei to a string in ether to display in a UI
formatEther(eth)
// '1.0'

// Convert a value in wei to a string in gwei to display in a UI
formatUnits(feePerGas, "gwei")
// '4.5'

Interacting with the Blockchain

Querying State

Once you have a Provider, you have a read-only connection to the data on the blockchain. This can be used to query the current account state, fetch historic logs, look up contract code and so on.

// Look up the current block number (i.e. height)
await provider.getBlockNumber()
// 16895094

// Get the current balance of an account (by address or ENS name)
balance = await provider.getBalance("ethers.eth")
// 182334002436162568n

// Since the balance is in wei, you may wish to display it
// in ether instead.
formatEther(balance)
// '0.182334002436162568'

// Get the next nonce required to send a transaction
await provider.getTransactionCount("ethers.eth")
// 3

Sending Transactions

To write to the blockchain you require access to a private key which controls some account. In most cases, those private keys are not accessible directly to your code, and instead you make requests via a Signer, which dispatches the request to a service (such as MetaMask) which provides strictly gated access and requires feedback to the user to approve or reject operations.

// When sending a transaction, the value is in wei, so parseEther
// converts ether to wei.
tx = await signer.sendTransaction({
  to: "ethers.eth",
  value: parseEther("1.0")
});

// Often you may wish to wait until the transaction is mined
receipt = await tx.wait();

Contracts

A Contract is a meta-class, which means that its definition its derived at run-time, based on the ABI it is passed, which then determined what methods and properties are available on it.

Application Binary Interface (ABI)

Since all operations that occur on the blockchain must be encoded as binary data, we need a concise way to define how to convert between common objects (like strings and numbers) and its binary representation, as well as encode the ways to call and interpret the Contract.

For any method, event or error you wish to use, you must include a Fragment to inform Ethers how it should encode the request and decode the result.

Any methods or events that are not needed can be safely excluded.

There are several common formats available to describe an ABI. The Solidity compiler usually dumps a JSON representation but when typing an ABI by hand it is often easier (and more readable) to use the human-readable ABI, which is just the Solidity signature.

simplified ERC-20 ABI

abi = [
  "function decimals() returns (string)",
  "function symbol() returns (string)",
  "function balanceOf(address addr) returns (uint)"
]

// Create a contract
contract = new Contract("dai.tokens.ethers.eth", abi, provider)

Read-only methods (i.e. view and pure)

A read-only method is one which cannot change the state of the blockchain, but often provide a simple interface to get important data about a Contract.

reading the DAI ERC-20 contract

// The contract ABI (fragments we care about)
abi = [
  "function decimals() view returns (uint8)",
  "function symbol() view returns (string)",
  "function balanceOf(address a) view returns (uint)"
]

// Create a contract; connected to a Provider, so it may
// only access read-only methods (like view and pure)
contract = new Contract("dai.tokens.ethers.eth", abi, provider)

// The symbol name for the token
sym = await contract.symbol()
// 'DAI'

// The number of decimals the token uses
decimals = await contract.decimals()
// 18n

// Read the token balance for an account
balance = await contract.balanceOf("ethers.eth")
// 189668770000000000000000n

// Format the balance for humans, such as in a UI
formatUnits(balance, decimals)
// '189668.77'

State-changing Methods

change state on an ERC-20 contract

abi = [
  "function transfer(address to, uint amount)"
]

// Connected to a Signer; can make state changing transactions,
// which will cost the account ether
contract = new Contract("dai.tokens.ethers.eth", abi, signer)

// Send 1 DAI
amount = parseUnits("1.0", 18);

// Send the transaction
tx = await contract.transfer("ethers.eth", amount)

// Currently the transaction has been sent to the mempool,
// but has not yet been included. So, we...

// ...wait for the transaction to be included.
await tx.wait()

forcing a call (simulation) of a state-changing method

abi = [
  "function transfer(address to, uint amount) returns (bool)"
]

// Connected to a Provider since we only require read access
contract = new Contract("dai.tokens.ethers.eth", abi, provider)

amount = parseUnits("1.0", 18)

// There are many limitations to using a static call, but can
// often be useful to preflight a transaction.
await contract.transfer.staticCall("ethers.eth", amount)
// true

// We can also simulate the transaction as another account
other = new VoidSigner("0x643aA0A61eADCC9Cc202D1915D942d35D005400C")
contractAsOther = contract.connect(other.connect(provider))
await contractAsOther.transfer.staticCall("ethers.eth", amount)
// true

Listening to Events

When adding event listeners for a named event, the event parameters are destructed for the listener.

There is always one additional parameter passed to a listener, which is an EventPayload, which includes more information about the event including the filter and a method to remove that listener.

listen for ERC-20 events

abi = [
  "event Transfer(address indexed from, address indexed to, uint amount)"
]

// Create a contract; connected to a Provider, so it may
// only access read-only methods (like view and pure)
contract = new Contract("dai.tokens.ethers.eth", abi, provider)

// Begin listening for any Transfer event
contract.on("Transfer", (from, to, _amount, event) => {
  const amount = formatEther(_amount, 18)
  console.log(`${ from } => ${ to }: ${ amount }`);

  // The `event.log` has the entire EventLog

  // Optionally, convenience method to stop listening
  event.removeListener();
});

// Same as above
contract.on(contract.filters.Transfer, (from, to, amount, event) => {
  // See above
})

// Listen for any Transfer to "ethers.eth"
filter = contract.filters.Transfer("ethers.eth")
contract.on(filter, (from, to, amount, event) => {
  // `to` will always be equal to the address of "ethers.eth"
});

// Listen for any event, whether it is present in the ABI
// or not. Since unknown events can be picked up, the
// parameters are not destructed.
contract.on("*", (event) => {
  // The `event.log` has the entire EventLog
});

Query Historic Events

When querying within a large range of blocks, some backends may be prohibitively slow, may return an error or may truncate the results without any indication. This is at the discretion of each backend.

query historic ERC-20 events

abi = [
  "event Transfer(address indexed from, address indexed to, uint amount)"
]

// Create a contract; connected to a Provider, so it may
// only access read-only methods (like view and pure)
contract = new Contract("dai.tokens.ethers.eth", abi, provider)

// Query the last 100 blocks for any transfer
filter = contract.filters.Transfer
events = await contract.queryFilter(filter, -100)

// The events are a normal Array
events.length
// 81

// The first matching event
events[0]
// EventLog {
//   address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
//   args: Result(3) [
//     '0x16a0D44A028c065550D0d836aECfbc3741672746',
//     '0x95AD589D75561b715475C6c7C8EcD1B80f2F8470',
//     1000000000000000000000n
//   ],
//   blockHash: '0x9e9dbf9165ec333006242d8a462fd95f5a69f5799d9922e816ee8332daec5748',
//   blockNumber: 16894994,
//   data: '0x00000000000000000000000000000000000000000000003635c9adc5dea00000',
//   fragment: EventFragment { ... },
//   index: 230,
//   interface: Interface { ... },
//   provider: InfuraProvider { ... },
//   removed: false,
//   topics: [
//     '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
//     '0x00000000000000000000000016a0d44a028c065550d0d836aecfbc3741672746',
//     '0x00000000000000000000000095ad589d75561b715475c6c7c8ecd1b80f2f8470'
//   ],
//   transactionHash: '0x493af518539d62081e479e697b4fddff565e003a1f62f7cfb037a8aa1bb380f9',
//   transactionIndex: 183
// }

// Query all time for any transfer to ethers.eth
filter = contract.filters.Transfer("ethers.eth")
events = await contract.queryFilter(filter)

// The first matching event
events[0]
// EventLog {
//   address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
//   args: Result(3) [
//     '0x643aA0A61eADCC9Cc202D1915D942d35D005400C',
//     '0x8ba1f109551bD432803012645Ac136ddd64DBA72',
//     1230000000000000000n
//   ],
//   blockHash: '0x3ce00ad556efbeb520775e82ef3afc9d425d65040f7c87de02e3d4a5c2a64a15',
//   blockNumber: 15986046,
//   data: '0x0000000000000000000000000000000000000000000000001111d67bb1bb0000',
//   fragment: EventFragment { ... },
//   index: 236,
//   interface: Interface { ... },
//   provider: InfuraProvider { ... },
//   removed: false,
//   topics: [
//     '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
//     '0x000000000000000000000000643aa0a61eadcc9cc202d1915d942d35d005400c',
//     '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72'
//   ],
//   transactionHash: '0xe9376d6c4f80e441ca3882a38a576ae511bf863266efdc4c3e8b27672772994f',
//   transactionIndex: 128
// }

Signing Messages

A private key can do a lot more than just sign a transaction to authorize it. It can also be used to sign other forms of data, which are then able to be validated for other purposes.

For example, signing a message can be used to prove ownership of an account which a website could use to authenticate a user and log them in.

// Our signer; Signing messages does not require a Provider
signer = new Wallet(id("test"))
// Wallet {
//   address: '0xC08B5542D177ac6686946920409741463a15dDdB',
//   provider: null
// }

message = "sign into ethers.org?"

// Signing the message
sig = await signer.signMessage(message);
// '0xefc6e1d2f21bb22b1013d05ecf1f06fd73cdcb34388111e4deec58605f3667061783be1297d8e3bee955d5b583bac7b26789b4a4c12042d59799ca75d98d23a51c'

// Validating a message; notice the address matches the signer
verifyMessage(message, sig)
// '0xC08B5542D177ac6686946920409741463a15dDdB'

Many other more advanced protocols built on top of signed messages are used to allow a private key to authorize other users to transfer their tokens, allowing the transaction fees of the transfer to be paid by someone else.

Ethereum Basics

Prelude here...

About stuff?

Some info

ABI

Explain about ABI here, what it does and does not do

encodes arbitrary (but defined) data structures to raw bytes

Call

About encoding

selector or signature hash (sighash)

Results

Events

Deployment

About initcode

Another paragraph BIP-39.

Foo?

Bar?

Application Programming Interface

The Application Programming Interface (API) is the collection of functions, classes and types offered by the Ethers library.

CONSTANTS

<src>version⇒ string

The current version of Ethers.

Application Binary Interface

Explain about ABI here...

FUNCTIONS

<src>decodeBytes32String(bytes: BytesLike)⇒ string

Encodes the Bytes32-encoded bytes into a string.

<src>encodeBytes32String(text: string)⇒ string

Encodes text as a Bytes32 string.

Interfaces

About Interface

TYPES

<src>InterfaceAbi⇒ string | ReadonlyArray< Fragment | JsonFragment | string >

class ErrorDescription

PROPERTIES

<src>errorDescription.args⇒ Resultread-only

<src>errorDescription.fragment⇒ ErrorFragmentread-only

<src>errorDescription.name⇒ stringread-only

<src>errorDescription.selector⇒ stringread-only

<src>errorDescription.signature⇒ stringread-only

CREATING INSTANCES

<src>new ErrorDescription(fragment: ErrorFragment, selector: string, args: Result)

class Indexed

PROPERTIES

<src>indexed._isIndexed⇒ booleanread-only

<src>indexed.hash⇒ null | stringread-only

CREATING INSTANCES

<src>new Indexed(hash: null | string)

STATIC METHODS

<src>Indexed.isIndexed(value: any)⇒ boolean

class Interface

An Interface abstracts many of the low-level details for encoding and decoding the data on the blockchain.

An ABI provides information on how to encode data to send to a Contract, how to decode the results and events and how to interpret revert errors.

The ABI can be specified by any supported format.

PROPERTIES

<src>interface.deploy⇒ ConstructorFragmentread-only

The Contract constructor.

<src>interface.fallback⇒ null | FallbackFragmentread-only

The Fallback method, if any.

<src>interface.fragments⇒ ReadonlyArray< Fragment >read-only

All the Contract ABI members (i.e. methods, events, errors, etc).

<src>interface.receive⇒ booleanread-only

If receiving ether is supported.

CREATING INSTANCES

<src>new Interface(fragments: InterfaceAbi)

Create a new Interface for the fragments.

<src>Interface.from(value: InterfaceAbi | Interface)⇒ Interface

Creates a new Interface from the ABI value.

The value may be provided as an existing Interface object, a JSON-encoded ABI or any Human-Readable ABI format.

METHODS

<src>interface._decodeParams(params: ReadonlyArray< ParamType >, data: BytesLike)⇒ Result

<src>interface._encodeParams(params: ReadonlyArray< ParamType >, values: ReadonlyArray< any >)⇒ string

<src>interface.decodeErrorResult(fragment: ErrorFragment | string, data: BytesLike)⇒ Result

Decodes the result data (e.g. from an eth_call) for the specified error (see getError for valid values for key).

Most developers should prefer the parseCallResult method instead, which will automatically detect a CALL_EXCEPTION and throw the corresponding error.

<src>interface.decodeEventLog(fragment: EventFragment | string, data: BytesLike, topics?: ReadonlyArray< string >)⇒ Result

<src>interface.decodeFunctionData(fragment: FunctionFragment | string, data: BytesLike)⇒ Result

Decodes the data from a transaction tx.data for the function specified (see getFunction for valid values for fragment).

Most developers should prefer the parseTransaction method instead, which will automatically detect the fragment.

<src>interface.decodeFunctionResult(fragment: FunctionFragment | string, data: BytesLike)⇒ Result

Decodes the result data (e.g. from an eth_call) for the specified function (see getFunction for valid values for key).

Most developers should prefer the parseCallResult method instead, which will automatically detect a CALL_EXCEPTION and throw the corresponding error.

<src>interface.encodeDeploy(values?: ReadonlyArray< any >)⇒ string

Encodes a tx.data object for deploying the Contract with the values as the constructor arguments.

<src>interface.encodeErrorResult(fragment: ErrorFragment | string, values?: ReadonlyArray< any >)⇒ string

Encodes the transaction revert data for a call result that reverted from the the Contract with the sepcified error (see getError for valid values for fragment) with the values.

This is generally not used by most developers, unless trying to mock a result from a Contract.

<src>interface.encodeEventLog(fragment: EventFragment | string, values: ReadonlyArray< any >)⇒ { data: string , topics: Array< string > }

<src>interface.encodeFilterTopics(fragment: EventFragment | string, values: ReadonlyArray< any >)⇒ Array< null | string | Array< string > >

<src>interface.encodeFunctionData(fragment: FunctionFragment | string, values?: ReadonlyArray< any >)⇒ string

Encodes the tx.data for a transaction that calls the function specified (see getFunction for valid values for fragment) with the values.

<src>interface.encodeFunctionResult(fragment: FunctionFragment | string, values?: ReadonlyArray< any >)⇒ string

Encodes the result data (e.g. from an eth_call) for the specified function (see getFunction for valid values for fragment) with values.

This is generally not used by most developers, unless trying to mock a result from a Contract.

<src>interface.forEachError(callback: (func: ErrorFragment, index: number) => void)⇒ void

Iterate over all errors, calling callback, sorted by their name.

<src>interface.forEachEvent(callback: (func: EventFragment, index: number) => void)⇒ void

Iterate over all events, calling callback, sorted by their name.

<src>interface.forEachFunction(callback: (func: FunctionFragment, index: number) => void)⇒ void

Iterate over all functions, calling callback, sorted by their name.

<src>interface.format(minimal?: boolean)⇒ Array< string >

Returns the entire Human-Readable ABI, as an array of signatures, optionally as minimal strings, which removes parameter names and unneceesary spaces.

<src>interface.formatJson()⇒ string

Return the JSON-encoded ABI. This is the format Solidiy returns.

<src>interface.getAbiCoder()⇒ AbiCoder

The ABI coder that will be used to encode and decode binary data.

<src>interface.getError(key: string, values?: Array< any | Typed >)⇒ null | ErrorFragment

Get the ErrorFragment for key, which may be an error selector, error name or error signature that belongs to the ABI.

If values is provided, it will use the Typed API to handle ambiguous cases where multiple errors match by name.

If the key and values do not refine to a single error in the ABI, this will throw.

<src>interface.getEvent(key: string, values?: Array< any | Typed >)⇒ null | EventFragment

Get the EventFragment for key, which may be a topic hash, event name or event signature that belongs to the ABI.

If values is provided, it will use the Typed API to handle ambiguous cases where multiple events match by name.

If the key and values do not refine to a single event in the ABI, this will throw.

<src>interface.getEventName(key: string)⇒ string

Get the event name for key, which may be a topic hash, event name or event signature that belongs to the ABI.

<src>interface.getFunction(key: string, values?: Array< any | Typed >)⇒ null | FunctionFragment

Get the FunctionFragment for key, which may be a function selector, function name or function signature that belongs to the ABI.

If values is provided, it will use the Typed API to handle ambiguous cases where multiple functions match by name.

If the key and values do not refine to a single function in the ABI, this will throw.

<src>interface.getFunctionName(key: string)⇒ string

Get the function name for key, which may be a function selector, function name or function signature that belongs to the ABI.

<src>interface.makeError(data: BytesLike, tx: CallExceptionTransaction)⇒ CallExceptionError

<src>interface.parseCallResult(data: BytesLike)⇒ Result

<src>interface.parseError(data: BytesLike)⇒ null | ErrorDescription

Parses a revert data, finding the matching error and extracts the parameter values along with other useful error details.

If the matching event cannot be found, returns null.

<src>interface.parseLog(log: { data: string , topics: Array< string > })⇒ null | LogDescription

Parses a receipt log, finding the matching event and extracts the parameter values along with other useful event details.

If the matching event cannot be found, returns null.

<src>interface.parseTransaction(tx: { data: string , value?: BigNumberish })⇒ null | TransactionDescription

Parses a transaction, finding the matching function and extracts the parameter values along with other useful function details.

If the matching function cannot be found, return null.

class LogDescription

PROPERTIES

<src>logDescription.args⇒ Resultread-only

<src>logDescription.fragment⇒ EventFragmentread-only

<src>logDescription.name⇒ stringread-only

<src>logDescription.signature⇒ stringread-only

<src>logDescription.topic⇒ stringread-only

CREATING INSTANCES

<src>new LogDescription(fragment: EventFragment, topic: string, args: Result)

class TransactionDescription

PROPERTIES

<src>transactionDescription.args⇒ Resultread-only

<src>transactionDescription.fragment⇒ FunctionFragmentread-only

<src>transactionDescription.name⇒ stringread-only

<src>transactionDescription.selector⇒ stringread-only

<src>transactionDescription.signature⇒ stringread-only

<src>transactionDescription.value⇒ bigintread-only

CREATING INSTANCES

<src>new TransactionDescription(fragment: FunctionFragment, selector: string, args: Result, value: bigint)

Typed Values

About typed...

class Typed

PROPERTIES

<src>typed._typedSymbol⇒ Symbolread-only

<src>typed.arrayLength⇒ null | numberread-only

<src>typed.tupleName⇒ null | stringread-only

<src>typed.type⇒ stringread-only

<src>typed.value⇒ anyread-only

CREATING INSTANCES

<src>new Typed(gaurd: any, type: string, value: any, options?: any)

<src>Typed.address(v: string | Addressable)⇒ Typed

<src>Typed.array(v: Array< any | Typed >, dynamic?: null | boolean)⇒ Typed

<src>Typed.bool(v: any)⇒ Typed

<src>Typed.bytes(v: BytesLike)⇒ Typed

<src>Typed.bytes1(v: BytesLike)⇒ Typed

<src>Typed.bytes10(v: BytesLike)⇒ Typed

<src>Typed.bytes11(v: BytesLike)⇒ Typed

<src>Typed.bytes12(v: BytesLike)⇒ Typed

<src>Typed.bytes13(v: BytesLike)⇒ Typed

<src>Typed.bytes14(v: BytesLike)⇒ Typed

<src>Typed.bytes15(v: BytesLike)⇒ Typed

<src>Typed.bytes16(v: BytesLike)⇒ Typed

<src>Typed.bytes17(v: BytesLike)⇒ Typed

<src>Typed.bytes18(v: BytesLike)⇒ Typed

<src>Typed.bytes19(v: BytesLike)⇒ Typed

<src>Typed.bytes2(v: BytesLike)⇒ Typed

<src>Typed.bytes20(v: BytesLike)⇒ Typed

<src>Typed.bytes21(v: BytesLike)⇒ Typed

<src>Typed.bytes22(v: BytesLike)⇒ Typed

<src>Typed.bytes23(v: BytesLike)⇒ Typed

<src>Typed.bytes24(v: BytesLike)⇒ Typed

<src>Typed.bytes25(v: BytesLike)⇒ Typed

<src>Typed.bytes26(v: BytesLike)⇒ Typed

<src>Typed.bytes27(v: BytesLike)⇒ Typed

<src>Typed.bytes28(v: BytesLike)⇒ Typed

<src>Typed.bytes29(v: BytesLike)⇒ Typed

<src>Typed.bytes3(v: BytesLike)⇒ Typed

<src>Typed.bytes30(v: BytesLike)⇒ Typed

<src>Typed.bytes31(v: BytesLike)⇒ Typed

<src>Typed.bytes32(v: BytesLike)⇒ Typed

<src>Typed.bytes4(v: BytesLike)⇒ Typed

<src>Typed.bytes5(v: BytesLike)⇒ Typed

<src>Typed.bytes6(v: BytesLike)⇒ Typed

<src>Typed.bytes7(v: BytesLike)⇒ Typed

<src>Typed.bytes8(v: BytesLike)⇒ Typed

<src>Typed.bytes9(v: BytesLike)⇒ Typed

<src>Typed.from(type: string, value: any)⇒ Typed

<src>Typed.int(v: BigNumberish)⇒ Typed

<src>Typed.int104(v: BigNumberish)⇒ Typed

<src>Typed.int112(v: BigNumberish)⇒ Typed

<src>Typed.int120(v: BigNumberish)⇒ Typed

<src>Typed.int128(v: BigNumberish)⇒ Typed

<src>Typed.int136(v: BigNumberish)⇒ Typed

<src>Typed.int144(v: BigNumberish)⇒ Typed

<src>Typed.int152(v: BigNumberish)⇒ Typed

<src>Typed.int16(v: BigNumberish)⇒ Typed

<src>Typed.int160(v: BigNumberish)⇒ Typed

<src>Typed.int168(v: BigNumberish)⇒ Typed

<src>Typed.int176(v: BigNumberish)⇒ Typed

<src>Typed.int184(v: BigNumberish)⇒ Typed

<src>Typed.int192(v: BigNumberish)⇒ Typed

<src>Typed.int200(v: BigNumberish)⇒ Typed

<src>Typed.int208(v: BigNumberish)⇒ Typed

<src>Typed.int216(v: BigNumberish)⇒ Typed

<src>Typed.int224(v: BigNumberish)⇒ Typed

<src>Typed.int232(v: BigNumberish)⇒ Typed

<src>Typed.int24(v: BigNumberish)⇒ Typed

<src>Typed.int240(v: BigNumberish)⇒ Typed

<src>Typed.int248(v: BigNumberish)⇒ Typed

<src>Typed.int256(v: BigNumberish)⇒ Typed

<src>Typed.int32(v: BigNumberish)⇒ Typed

<src>Typed.int40(v: BigNumberish)⇒ Typed

<src>Typed.int48(v: BigNumberish)⇒ Typed

<src>Typed.int56(v: BigNumberish)⇒ Typed

<src>Typed.int64(v: BigNumberish)⇒ Typed

<src>Typed.int72(v: BigNumberish)⇒ Typed

<src>Typed.int8(v: BigNumberish)⇒ Typed

<src>Typed.int80(v: BigNumberish)⇒ Typed

<src>Typed.int88(v: BigNumberish)⇒ Typed

<src>Typed.int96(v: BigNumberish)⇒ Typed

<src>Typed.overrides(v: Record< string, any >)⇒ Typed

<src>Typed.string(v: string)⇒ Typed

<src>Typed.tuple(v: Array< any | Typed > | Record< string, any | Typed >, name?: string)⇒ Typed

<src>Typed.uint(v: BigNumberish)⇒ Typed

<src>Typed.uint104(v: BigNumberish)⇒ Typed

<src>Typed.uint112(v: BigNumberish)⇒ Typed

<src>Typed.uint120(v: BigNumberish)⇒ Typed

<src>Typed.uint128(v: BigNumberish)⇒ Typed

<src>Typed.uint136(v: BigNumberish)⇒ Typed

<src>Typed.uint144(v: BigNumberish)⇒ Typed

<src>Typed.uint152(v: BigNumberish)⇒ Typed

<src>Typed.uint16(v: BigNumberish)⇒ Typed

<src>Typed.uint160(v: BigNumberish)⇒ Typed

<src>Typed.uint168(v: BigNumberish)⇒ Typed

<src>Typed.uint176(v: BigNumberish)⇒ Typed

<src>Typed.uint184(v: BigNumberish)⇒ Typed

<src>Typed.uint192(v: BigNumberish)⇒ Typed

<src>Typed.uint200(v: BigNumberish)⇒ Typed

<src>Typed.uint208(v: BigNumberish)⇒ Typed

<src>Typed.uint216(v: BigNumberish)⇒ Typed

<src>Typed.uint224(v: BigNumberish)⇒ Typed

<src>Typed.uint232(v: BigNumberish)⇒ Typed

<src>Typed.uint24(v: BigNumberish)⇒ Typed

<src>Typed.uint240(v: BigNumberish)⇒ Typed

<src>Typed.uint248(v: BigNumberish)⇒ Typed

<src>Typed.uint256(v: BigNumberish)⇒ Typed

<src>Typed.uint32(v: BigNumberish)⇒ Typed

<src>Typed.uint40(v: BigNumberish)⇒ Typed

<src>Typed.uint48(v: BigNumberish)⇒ Typed

<src>Typed.uint56(v: BigNumberish)⇒ Typed

<src>Typed.uint64(v: BigNumberish)⇒ Typed

<src>Typed.uint72(v: BigNumberish)⇒ Typed

<src>Typed.uint8(v: BigNumberish)⇒ Typed

<src>Typed.uint80(v: BigNumberish)⇒ Typed

<src>Typed.uint88(v: BigNumberish)⇒ Typed

<src>Typed.uint96(v: BigNumberish)⇒ Typed

METHODS

<src>typed.defaultValue()⇒ string | number | bigint | Result

<src>typed.format()⇒ string

<src>typed.isBigInt()⇒ boolean

<src>typed.isData()⇒ boolean

<src>typed.isString()⇒ boolean

<src>typed.maxValue()⇒ string | number | bigint

<src>typed.minValue()⇒ string | number | bigint

STATIC METHODS

<src>Typed.dereference(value: Typed | T, type: string)⇒ T

If the value is a Typed instance, validates the underlying value and returns it, otherwise returns value directly.

This is useful for functions that with to accept either a Typed object or values.

<src>Typed.isTyped(value: any)⇒ boolean

Returns true only if value is a Typed instance.

interface TypedBigInt

inherits from Typed

PROPERTIES

<src>typedBigInt.value⇒ bigint

METHODS

<src>typedBigInt.defaultValue()⇒ bigint

<src>typedBigInt.maxValue()⇒ bigint

<src>typedBigInt.minValue()⇒ bigint

interface TypedData

inherits from Typed

PROPERTIES

<src>typedData.value⇒ string

METHODS

<src>typedData.defaultValue()⇒ string

interface TypedNumber

inherits from Typed

PROPERTIES

<src>typedNumber.value⇒ number

METHODS

<src>typedNumber.defaultValue()⇒ number

<src>typedNumber.maxValue()⇒ number

<src>typedNumber.minValue()⇒ number

interface TypedString

inherits from Typed

PROPERTIES

<src>typedString.value⇒ string

METHODS

<src>typedString.defaultValue()⇒ string

ABI Encoding

When sending values to or receiving values from a Contract, the data is generally encoded using the ABI standard.

The AbiCoder provides a utility to encode values to ABI data and decode values from ABI data.

Most of the time, developers should favour the Contract class, which further abstracts a lot of the finer details of ABI data.

class AbiCoder

About AbiCoder

CREATING INSTANCES

<src>AbiCoder.defaultAbiCoder()⇒ AbiCoder

Returns the shared singleton instance of a default AbiCoder.

On the first call, the instance is created internally.

METHODS

<src>abiCoder.decode(types: ReadonlyArray< string | ParamType >, data: BytesLike, loose?: boolean)⇒ Result

Decode the ABI data as the types into values.

If loose decoding is enabled, then strict padding is not enforced. Some older versions of Solidity incorrectly padded event data emitted from external functions.

<src>abiCoder.encode(types: ReadonlyArray< string | ParamType >, values: ReadonlyArray< any >)⇒ DataHexstring

Encode the values as the types into ABI data.

<src>abiCoder.getDefaultValue(types: ReadonlyArray< string | ParamType >)⇒ Result

Get the default values for the given types.

For example, a uint is by default 0 and bool is by default false.

STATIC METHODS

<src>AbiCoder.getBuiltinCallException(action: CallExceptionAction, tx: { data?: string , from?: null | string , to?: null | string }, data: null | BytesLike)⇒ CallExceptionError

Returns an ethers-compatible CallExceptionError Error for the given result data for the CallExceptionAction action against the Transaction tx.

Fragments

About frgaments...

TYPES

<src>FormatType⇒ "sighash" | "minimal" | "full" | "json"

The format to serialize the output as.

The type of a Fragment.

<src>ParamTypeWalkAsyncFunc⇒ (type: string, value: any) => any | Promise< any >

When walking asynchronously a ParamType, this is called on each component.

<src>ParamTypeWalkFunc⇒ (type: string, value: any) => any

When walking a ParamType, this is called on each component.

class ConstructorFragment

inherits from Fragment

A Fragment which represents a constructor.

PROPERTIES

<src>constructorFragment.gas⇒ null | bigintread-only

<src>constructorFragment.payable⇒ booleanread-only

CREATING INSTANCES

<src>ConstructorFragment.from(obj: any)⇒ ConstructorFragment

METHODS

<src>constructorFragment.format(format?: FormatType)⇒ string

STATIC METHODS

<src>ConstructorFragment.isFragment(value: any)⇒ boolean

class ErrorFragment

inherits from NamedFragment, Fragment

A Fragment which represents a Custom Error.

PROPERTIES

<src>errorFragment.selector⇒ stringread-only

The Custom Error selector.

CREATING INSTANCES

<src>ErrorFragment.from(obj: any)⇒ ErrorFragment

METHODS

<src>errorFragment.format(format?: FormatType)⇒ string

STATIC METHODS

<src>ErrorFragment.isFragment(value: any)⇒ boolean

class EventFragment

inherits from NamedFragment, Fragment

A Fragment which represents an Event.

PROPERTIES

<src>eventFragment.anonymous⇒ booleanread-only

<src>eventFragment.topicHash⇒ stringread-only

The Event topic hash.

CREATING INSTANCES

<src>EventFragment.from(obj: any)⇒ EventFragment

METHODS

<src>eventFragment.format(format?: FormatType)⇒ string

STATIC METHODS

<src>EventFragment.getTopicHash(name: string, params?: Array< any >)⇒ string

<src>EventFragment.isFragment(value: any)⇒ boolean

class FallbackFragment

inherits from Fragment

A Fragment which represents a method.

PROPERTIES

<src>fallbackFragment.payable⇒ booleanread-only

If the function can be sent value during invocation.

CREATING INSTANCES

<src>new FallbackFragment(guard: any, inputs: ReadonlyArray< ParamType >, payable: boolean)

<src>FallbackFragment.from(obj: any)⇒ FallbackFragment

METHODS

<src>fallbackFragment.format(format?: FormatType)⇒ string

STATIC METHODS

<src>FallbackFragment.isFragment(value: any)⇒ boolean

abstract class Fragment

An abstract class to represent An individual fragment from a parse ABI.

PROPERTIES

<src>fragment.inputs⇒ ReadonlyArray< ParamType >read-only

The inputs for the fragment.

<src>fragment.type⇒ FragmentTyperead-only

The type of the fragment.

CREATING INSTANCES

<src>Fragment.from(obj: any)⇒ Fragment

Creates a new Fragment for obj, wich can be any supported ABI frgament type.

METHODS

<src>fragment.format(format?: FormatType)⇒ stringabstract

Returns a string representation of this fragment.

STATIC METHODS

<src>Fragment.isConstructor(value: any)⇒ boolean

Returns true if value is a ConstructorFragment.

<src>Fragment.isError(value: any)⇒ boolean

Returns true if value is an ErrorFragment.

<src>Fragment.isEvent(value: any)⇒ boolean

Returns true if value is an EventFragment.

<src>Fragment.isFunction(value: any)⇒ boolean

Returns true if value is a FunctionFragment.

<src>Fragment.isStruct(value: any)⇒ boolean

Returns true if value is a StructFragment.

class FunctionFragment

inherits from NamedFragment, Fragment

A Fragment which represents a method.

PROPERTIES

<src>functionFragment.constant⇒ booleanread-only

If the function is constant (e.g. pure or view functions).

<src>functionFragment.gas⇒ null | bigintread-only

The amount of gas to send when calling this function

<src>functionFragment.outputs⇒ ReadonlyArray< ParamType >read-only

The returned types for the result of calling this function.

<src>functionFragment.payable⇒ booleanread-only

If the function can be sent value during invocation.

<src>functionFragment.selector⇒ stringread-only

The Function selector.

<src>functionFragment.stateMutability⇒ "payable" | "nonpayable" | "view" | "pure"read-only

The state mutability (e.g. payable, nonpayable, view or pure)

CREATING INSTANCES

<src>FunctionFragment.from(obj: any)⇒ FunctionFragment

METHODS

<src>functionFragment.format(format?: FormatType)⇒ string

STATIC METHODS

<src>FunctionFragment.getSelector(name: string, params?: Array< any >)⇒ string

<src>FunctionFragment.isFragment(value: any)⇒ boolean

interface JsonFragment

A fragment for a method, event or error in a JSON API.

PROPERTIES

<src>jsonFragment.anonymous⇒ booleanread-only

If the event is anonymous.

<src>jsonFragment.constant⇒ booleanread-only

If the function is constant.

<src>jsonFragment.gas⇒ stringread-only

The gas limit to use when sending a transaction for this function.

<src>jsonFragment.inputs⇒ ReadonlyArray< JsonFragmentType >read-only

The input parameters.

<src>jsonFragment.name⇒ stringread-only

The name of the error, event, function, etc.

<src>jsonFragment.outputs⇒ ReadonlyArray< JsonFragmentType >read-only

The output parameters.

<src>jsonFragment.payable⇒ booleanread-only

If the function is payable.

<src>jsonFragment.stateMutability⇒ stringread-only

The mutability state of the function.

<src>jsonFragment.type⇒ stringread-only

The type of the fragment (e.g. event, "function", etc.)

interface JsonFragmentType

A type description in a JSON API.

PROPERTIES

<src>jsonFragmentType.components⇒ ReadonlyArray< JsonFragmentType >read-only

The components for a tuple.

<src>jsonFragmentType.indexed⇒ booleanread-only

If the parameter is indexed.

<src>jsonFragmentType.internalType⇒ stringread-only

The internal Solidity type.

<src>jsonFragmentType.name⇒ stringread-only

The parameter name.

<src>jsonFragmentType.type⇒ stringread-only

The type of the parameter.

abstract class NamedFragment

inherits from Fragment

An abstract class to represent An individual fragment which has a name from a parse ABI.

PROPERTIES

<src>namedFragment.name⇒ stringread-only

The name of the fragment.

class ParamType

Each input and output of a Fragment is an Array of PAramType.

PROPERTIES

<src>paramType.arrayChildren⇒ null | ParamTyperead-only

The type of each child in the array.

For non-array types this is null.

<src>paramType.arrayLength⇒ null | numberread-only

The array length, or -1 for dynamic-lengthed arrays.

For non-array types this is null.

<src>paramType.baseType⇒ stringread-only

The base type (e.g. "address", "tuple", "array")

<src>paramType.components⇒ null | ReadonlyArray< ParamType >read-only

The components for the tuple.

For non-tuple types this is null.

<src>paramType.indexed⇒ null | booleanread-only

True if the parameters is indexed.

For non-indexable types this is null.

<src>paramType.name⇒ stringread-only

The local name of the parameter (or "" if unbound)

<src>paramType.type⇒ stringread-only

The fully qualified type (e.g. "address", "tuple(address)", "uint256[3][]")

CREATING INSTANCES

<src>ParamType.from(obj: any, allowIndexed?: boolean)⇒ ParamType

Creates a new ParamType for obj.

If allowIndexed then the indexed keyword is permitted, otherwise the indexed keyword will throw an error.

METHODS

<src>paramType.format(format?: FormatType)⇒ string

Return a string representation of this type.

For example,

sighash" => "(uint256,address)"

"minimal" => "tuple(uint256,address) indexed"

"full" => "tuple(uint256 foo, address bar) indexed baz"

<src>paramType.isArray()⇒ boolean

Returns true if this is an Array type.

This provides a type gaurd ensuring that arrayChildren and arrayLength are non-null.

<src>paramType.isIndexable()⇒ boolean

Returns true if this is an Indexable type.

This provides a type gaurd ensuring that indexed is non-null.

<src>paramType.isTuple()⇒ boolean

Returns true if this is a Tuple type.

This provides a type gaurd ensuring that components is non-null.

<src>paramType.walk(value: any, process: ParamTypeWalkFunc)⇒ any

Walks the ParamType with value, calling process on each type, destructing the value recursively.

<src>paramType.walkAsync(value: any, process: ParamTypeWalkAsyncFunc)⇒ Promise< any >

Walks the ParamType with value, asynchronously calling process on each type, destructing the value recursively.

This can be used to resolve ENS naes by walking and resolving each "address" type.

STATIC METHODS

<src>ParamType.isParamType(value: any)⇒ boolean

Returns true if value is a ParamType.

class StructFragment

inherits from NamedFragment, Fragment

A Fragment which represents a structure.

CREATING INSTANCES

<src>StructFragment.from(obj: any)⇒ StructFragment

METHODS

<src>structFragment.format()⇒ string

STATIC METHODS

<src>StructFragment.isFragment(value: any)⇒ boolean

Addresses

Addresses are a fundamental part of interacting with Ethereum. They represent the gloabal identity of Externally Owned Accounts (accounts backed by a private key) and contracts.

The Ethereum Naming Service (ENS) provides an interconnected ecosystem of contracts, standards and libraries which enable looking up an address for an ENS name.

These functions help convert between various formats, validate addresses and safely resolve ENS names.

TYPES

<src>AddressLike⇒ string | Promise< string > | Addressable

Anything that can be used to return or resolve an address.

FUNCTIONS

<src>getAddress(address: string)⇒ string

Returns a normalized and checksumed address for address. This accepts non-checksum addresses, checksum addresses and getIcapAddress formats.

The checksum in Ethereum uses the capitalization (upper-case vs lower-case) of the characters within an address to encode its checksum, which offers, on average, a checksum of 15-bits.

If address contains both upper-case and lower-case, it is assumed to already be a checksum address and its checksum is validated, and if the address fails its expected checksum an error is thrown.

If you wish the checksum of address to be ignore, it should be converted to lower-case (i.e. .toLowercase()) before being passed in. This should be a very rare situation though, that you wish to bypass the safegaurds in place to protect against an address that has been incorrectly copied from another source.

// Adds the checksum (via upper-casing specific letters)
getAddress("0x8ba1f109551bd432803012645ac136ddd64dba72")
// '0x8ba1f109551bD432803012645Ac136ddd64DBA72'

// Converts ICAP address and adds checksum
getAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
// '0x8ba1f109551bD432803012645Ac136ddd64DBA72'

// Throws an error if an address contains mixed case,
// but the checksum fails
getAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBA72")
// Error("bad address checksum", {
//   code: "INVALID_ARGUMENT"
//   argument: "address"
//   value: "0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
// })

<src>getCreate2Address(from: string, salt: BytesLike, initCodeHash: BytesLike)⇒ string

Returns the address that would result from a CREATE2 operation with the given from, salt and initCodeHash.

To compute the initCodeHash from a contract's init code, use the keccak256 function.

For a quick overview and example of CREATE2, see Wisps: The Magical World of Create2.

// The address of the contract
from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"

// The salt
salt = id("HelloWorld")

// The hash of the initCode
initCode = "0x6394198df16000526103ff60206004601c335afa6040516060f3";
initCodeHash = keccak256(initCode)

getCreate2Address(from, salt, initCodeHash)
// '0x533ae9d683B10C02EbDb05471642F85230071FC3'

<src>getCreateAddress(tx: { from: string , nonce: BigNumberish })⇒ string

Returns the address that would result from a CREATE for tx.

This can be used to compute the address a contract will be deployed to by an EOA when sending a deployment transaction (i.e. when the to address is null).

This can also be used to compute the address a contract will be deployed to by a contract, by using the contract's address as the to and the contract's nonce.

from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
nonce = 5;

getCreateAddress({ from, nonce });
// '0x082B6aC9e47d7D83ea3FaBbD1eC7DAba9D687b36'

<src>getIcapAddress(address: string)⇒ string

The ICAP Address format format is an early checksum format which attempts to be compatible with the banking industry IBAN format for bank accounts.

It is no longer common or a recommended format.

getIcapAddress("0x8ba1f109551bd432803012645ac136ddd64dba72");
// 'XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36'

getIcapAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
// 'XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36'

// Throws an error if the ICAP checksum is wrong
getIcapAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK37");
// Error("bad icap checksum", {
//   code: "INVALID_ARGUMENT"
//   argument: "address"
//   value: "XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK37"
// })

<src>isAddress(value: any)⇒ boolean

Returns true if value is a valid address.

// Valid address
isAddress("0x8ba1f109551bD432803012645Ac136ddd64DBA72")
// true

// Valid ICAP address
isAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36")
// true

// Invalid checksum
isAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBa72")
// false

// Invalid ICAP checksum
isAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBA72")
// false

// Not an address (an ENS name requires a provided and an
// asynchronous API to access)
isAddress("ricmoo.eth")
// false

<src>isAddressable(value: any)⇒ boolean

Returns true if value is an object which implements the Addressable interface.

// Wallets and AbstractSigner sub-classes
isAddressable(Wallet.createRandom())
// true

// Contracts
contract = new Contract("dai.tokens.ethers.eth", [ ], provider)
isAddressable(contract)
// true

<src>resolveAddress(target: AddressLike, resolver?: null | NameResolver)⇒ string | Promise< string >

Resolves to an address for the target, which may be any supported address type, an Addressable or a Promise which resolves to an address.

If an ENS name is provided, but that name has not been correctly configured a UnconfiguredNameError is thrown.

addr = "0x6B175474E89094C44Da98b954EedeAC495271d0F"

// Addresses are return synchronously
resolveAddress(addr, provider)
// '0x6B175474E89094C44Da98b954EedeAC495271d0F'

// Address promises are resolved asynchronously
resolveAddress(Promise.resolve(addr))
// Promise<'0x6B175474E89094C44Da98b954EedeAC495271d0F'>

// ENS names are resolved asynchronously
resolveAddress("dai.tokens.ethers.eth", provider)
// Promise<'0x6B175474E89094C44Da98b954EedeAC495271d0F'>

// Addressable objects are resolved asynchronously
contract = new Contract(addr, [ ])
resolveAddress(contract, provider)
// Promise<'0x6B175474E89094C44Da98b954EedeAC495271d0F'>

// Unconfigured ENS names reject
resolveAddress("nothing-here.ricmoo.eth", provider)
// Promise<Error("unconfigured name", {
//   code: "UNCONFIGURED_NAME"
//   value: "nothing-here.ricmoo.eth"
// })>

// ENS names require a NameResolver object passed in
// (notice the provider was omitted)
resolveAddress("nothing-here.ricmoo.eth")
// Error("ENS resolution requires a provider", {
//   code: "UNSUPPORTED_OPERATION"
//   operation: "resolveName"
// })

interface Addressable

An interface for objects which have an address, and can resolve it asyncronously.

This allows objects such as Signer or Contract to be used most places an address can be, for example getting the balance.

METHODS

<src>addressable.getAddress()⇒ Promise< string >

Get the object address.

interface NameResolver

An interface for any object which can resolve an ENS name.

METHODS

<src>nameResolver.resolveName(name: string)⇒ Promise< null | string >

Resolve to the address for the ENS name.

Resolves to null if the name is unconfigued. Use resolveAddress (passing this object as resolver) to throw for names that are unconfigured.

Constants

Some common constants useful for Ethereum.

CONSTANTS

<src>EtherSymbol⇒ string

A constant for the ether symbol (normalized using NFKC).

(i.e. "\u039e")

<src>MaxInt256⇒ bigint

A constant for the maximum value for an int256.

(i.e. 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn)

<src>MaxUint256⇒ bigint

A constant for the maximum value for a uint256.

(i.e. 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn)

<src>MessagePrefix⇒ string

A constant for the EIP-191 personal message prefix.

(i.e. "\x19Ethereum Signed Message:\n")

<src>MinInt256⇒ bigint

A constant for the minimum value for an int256.

(i.e. -8000000000000000000000000000000000000000000000000000000000000000n)

<src>N⇒ bigint

A constant for the order N for the secp256k1 curve.

(i.e. 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n)

<src>WeiPerEther⇒ bigint

A constant for the number of wei in a single ether.

(i.e. 1000000000000000000n)

<src>ZeroAddress⇒ string

A constant for the zero address.

(i.e. "0x0000000000000000000000000000000000000000")

<src>ZeroHash⇒ string

A constant for the zero hash.

(i.e. "0x0000000000000000000000000000000000000000000000000000000000000000")

Contracts

About contracts...

TYPES

<src>ContractEventArgs⇒ TODO(A4BRecord<@TODO-005: @TODO-006>)

<src>ContractEventName⇒ string | ContractEvent | TopicFilter | DeferredTopicFilter

<src>ContractMethodArgs⇒ PostfixOverrides < TODO(A4BRecord<@TODO-005: @TODO-006>) >

<src>PostfixOverrides⇒ A | tuple< TODO(A5BFOOBAR ...[object Object]), Overrides >

class BaseContract

inherits from Addressable

PROPERTIES

<src>baseContract.fallback⇒ null | WrappedFallbackread-only

<src>baseContract.filters⇒ Record< string, ContractEvent >read-only

<src>baseContract.interface⇒ Interfaceread-only

<src>baseContract.internal⇒ anyread-only

<src>baseContract.runner⇒ null | ContractRunnerread-only

<src>baseContract.target⇒ string | Addressableread-only

CREATING INSTANCES

<src>new BaseContract(target: string | Addressable, abi: Interface | InterfaceAbi, runner?: null | ContractRunner, deployTx?: null | TransactionResponse)

METHODS

<src>baseContract.addListener(event: ContractEventName, listener: Listener)⇒ Promise< this >

<src>baseContract.connect(runner: null | ContractRunner)⇒ BaseContract

<src>baseContract.deploymentTransaction()⇒ null | ContractTransactionResponse

<src>baseContract.emit(event: ContractEventName, args: Array< any >)⇒ Promise< boolean >

<src>baseContract.getAddress()⇒ Promise< string >

<src>baseContract.getDeployedCode()⇒ Promise< null | string >

<src>baseContract.getEvent(key: string | EventFragment)⇒ ContractEvent

<src>baseContract.getFunction(key: string | FunctionFragment)⇒ T

<src>baseContract.listenerCount(event?: ContractEventName)⇒ Promise< number >

<src>baseContract.listeners(event?: ContractEventName)⇒ Promise< Array< Listener > >

<src>baseContract.off(event: ContractEventName, listener?: Listener)⇒ Promise< this >

<src>baseContract.on(event: ContractEventName, listener: Listener)⇒ Promise< this >

<src>baseContract.once(event: ContractEventName, listener: Listener)⇒ Promise< this >

<src>baseContract.queryFilter(event: ContractEventName, fromBlock?: BlockTag, toBlock?: BlockTag)⇒ Promise< Array< EventLog | Log > >

<src>baseContract.queryTransaction(hash: string)⇒ Promise< Array< EventLog > >

<src>baseContract.removeAllListeners(event?: ContractEventName)⇒ Promise< this >

<src>baseContract.removeListener(event: ContractEventName, listener: Listener)⇒ Promise< this >

<src>baseContract.waitForDeployment()⇒ Promise< this >

STATIC METHODS

<src>BaseContract.buildClass(abi: InterfaceAbi)⇒ TODO(A2Bconstructor(@TODO-001))

<src>BaseContract.from(target: string, abi: InterfaceAbi, runner?: null | ContractRunner)⇒ BaseContract & Omit< T, keyof<BaseContract> >

interface BaseContractMethod

PROPERTIES

<src>baseContractMethod.fragment⇒ FunctionFragment

<src>baseContractMethod.name⇒ string

METHODS

<src>baseContractMethod.estimateGas(args: ContractMethodArgs < A >)⇒ Promise< bigint >

<src>baseContractMethod.getFragment(args: ContractMethodArgs < A >)⇒ FunctionFragment

<src>baseContractMethod.populateTransaction(args: ContractMethodArgs < A >)⇒ Promise< ContractTransaction >

<src>baseContractMethod.send(args: ContractMethodArgs < A >)⇒ Promise< ContractTransactionResponse >

<src>baseContractMethod.staticCall(args: ContractMethodArgs < A >)⇒ Promise< R >

<src>baseContractMethod.staticCallResult(args: ContractMethodArgs < A >)⇒ Promise< Result >

interface ConstantContractMethod

inherits from ContractMethod, BaseContractMethod

class Contract

interface ContractDeployTransaction

interface ContractEvent

PROPERTIES

<src>contractEvent.fragment⇒ EventFragment

<src>contractEvent.name⇒ string

METHODS

<src>contractEvent.getFragment(args: ContractEventArgs < A >)⇒ EventFragment

class ContractEventPayload

inherits from ContractUnknownEventPayload, EventPayload

PROPERTIES

<src>contractEventPayload.args⇒ Resultread-only

<src>contractEventPayload.eventName⇒ stringread-only

<src>contractEventPayload.eventSignature⇒ stringread-only

<src>contractEventPayload.fragment⇒ EventFragmentread-only

<src>contractEventPayload.log⇒ EventLogread-only

CREATING INSTANCES

<src>new ContractEventPayload(contract: BaseContract, listener: null | Listener, filter: ContractEventName, fragment: EventFragment, log: Log)

class ContractFactory

PROPERTIES

<src>contractFactory.bytecode⇒ stringread-only

<src>contractFactory.interface⇒ Interfaceread-only

<src>contractFactory.runner⇒ null | ContractRunnerread-only

CREATING INSTANCES

<src>new ContractFactory(abi: Interface | InterfaceAbi, bytecode: BytesLike | { object: string }, runner?: null | ContractRunner)

METHODS

<src>contractFactory.connect(runner: null | ContractRunner)⇒ ContractFactory < A, I >

<src>contractFactory.deploy(args: ContractMethodArgs < A >)⇒ Promise< BaseContract & { deploymentTransaction: ContractTransactionResponse } & Omit< I, keyof<BaseContract> > >

<src>contractFactory.getDeployTransaction(args: ContractMethodArgs < A >)⇒ Promise< ContractDeployTransaction >

STATIC METHODS

<src>ContractFactory.fromSolidity(output: any, runner?: ContractRunner)⇒ ContractFactory < A, I >

interface ContractInterface

interface ContractMethod

inherits from BaseContractMethod

interface ContractTransaction

inherits from PreparedTransactionRequest

PROPERTIES

<src>contractTransaction.data⇒ string

<src>contractTransaction.from⇒ string

<src>contractTransaction.to⇒ string

class ContractTransactionReceipt

inherits from TransactionReceipt, TransactionReceiptParams

PROPERTIES

<src>contractTransactionReceipt.logs⇒ Array< EventLog | Log >read-only

CREATING INSTANCES

<src>new ContractTransactionReceipt(iface: Interface, provider: Provider, tx: TransactionReceipt)

class ContractTransactionResponse

inherits from TransactionResponse, TransactionResponseParams

CREATING INSTANCES

<src>new ContractTransactionResponse(iface: Interface, provider: Provider, tx: TransactionResponse)

METHODS

<src>contractTransactionResponse.wait(confirms?: number)⇒ Promise< null | ContractTransactionReceipt >

class ContractUnknownEventPayload

inherits from EventPayload

PROPERTIES

<src>contractUnknownEventPayload.log⇒ Logread-only

CREATING INSTANCES

<src>new ContractUnknownEventPayload(contract: BaseContract, listener: null | Listener, filter: ContractEventName, log: Log)

METHODS

<src>contractUnknownEventPayload.getBlock()⇒ Promise< Block >

<src>contractUnknownEventPayload.getTransaction()⇒ Promise< TransactionResponse >

<src>contractUnknownEventPayload.getTransactionReceipt()⇒ Promise< TransactionReceipt >

interface DeferredTopicFilter

PROPERTIES

<src>deferredTopicFilter.fragment⇒ EventFragment

METHODS

<src>deferredTopicFilter.getTopicFilter()⇒ Promise< TopicFilter >

class EventLog

inherits from Log, LogParams

PROPERTIES

<src>eventLog.args⇒ Resultread-only

<src>eventLog.eventName⇒ stringread-only

<src>eventLog.eventSignature⇒ stringread-only

<src>eventLog.fragment⇒ EventFragmentread-only

<src>eventLog.interface⇒ Interfaceread-only

CREATING INSTANCES

<src>new EventLog(log: Log, iface: Interface, fragment: EventFragment)

interface Overrides

interface WrappedFallback

METHODS

<src>wrappedFallback.estimateGas(overrides?: Omit< TransactionRequest, "to" >)⇒ Promise< bigint >

<src>wrappedFallback.populateTransaction(overrides?: Omit< TransactionRequest, "to" >)⇒ Promise< ContractTransaction >

<src>wrappedFallback.send(overrides?: Omit< TransactionRequest, "to" >)⇒ Promise< ContractTransactionResponse >

<src>wrappedFallback.staticCall(overrides?: Omit< TransactionRequest, "to" >)⇒ Promise< string >

Cryptographic Functions

A fundamental building block of Ethereum is the underlying cryptographic primitives.

FUNCTIONS

<src>lock()⇒ void

Hash Functions

Cryptographic hashing functions

FUNCTIONS

<src>keccak256(data: BytesLike)⇒ DataHexstring

Compute the cryptographic KECCAK256 hash of data.

The data must be a data representation, to compute the hash of UTF-8 data use the id function.

keccak256("0x")
// '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470'

keccak256("0x1337")
// '0x2636a8beb2c41b8ccafa9a55a5a5e333892a83b491df3a67d2768946a9f9c6dc'

keccak256(new Uint8Array([ 0x13, 0x37 ]))
// '0x2636a8beb2c41b8ccafa9a55a5a5e333892a83b491df3a67d2768946a9f9c6dc'

// Strings are assumed to be DataHexString, otherwise it will
// throw. To hash UTF-8 data, see the note above.
keccak256("Hello World")
// Error("invalid BytesLike value", {
//   code: "INVALID_ARGUMENT"
//   argument: "data"
//   value: "Hello World"
// })

<src>ripemd160(data: BytesLike)⇒ DataHexstring

Compute the cryptographic RIPEMD-160 hash of data.

ripemd160("0x")
// '0x9c1185a5c5e9fc54612808977ee8f548b2258d31'

ripemd160("0x1337")
// '0x224d2bd5251d8f9faa114eb0826e371d1236fda1'

ripemd160(new Uint8Array([ 0x13, 0x37 ]))
// '0x224d2bd5251d8f9faa114eb0826e371d1236fda1'

<src>sha256(data: BytesLike)⇒ DataHexstring

Compute the cryptographic SHA2-256 hash of data.

sha256("0x")
// '0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'

sha256("0x1337")
// '0x158760c856e5ea1ba97e2e2a456736c4bf30d964559afa6d748cf05694a636ff'

sha256(new Uint8Array([ 0x13, 0x37 ]))
// '0x158760c856e5ea1ba97e2e2a456736c4bf30d964559afa6d748cf05694a636ff'

<src>sha512(data: BytesLike)⇒ DataHexstring

Compute the cryptographic SHA2-512 hash of data.

sha512("0x")
// '0xcf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e'

sha512("0x1337")
// '0x55ccb35e52b39adac42b68304bf33ff7ecb854f09b2e761e234061482e98e45b4e68de2756bcc7b7099d7dd178f04dafa229d403b90bf8884eedea3806d4642b'

sha512(new Uint8Array([ 0x13, 0x37 ]))
// '0x55ccb35e52b39adac42b68304bf33ff7ecb854f09b2e761e234061482e98e45b4e68de2756bcc7b7099d7dd178f04dafa229d403b90bf8884eedea3806d4642b'

HMAC

An HMAC enables verification that a given key was used to authenticate a payload.

See: link-wiki-hmac

FUNCTIONS

<src>computeHmac(algorithm: "sha256" | "sha512", key: BytesLike, data: BytesLike)⇒ string

Return the HMAC for data using the key key with the underlying algo used for compression.

key = id("some-secret")

// Compute the HMAC
computeHmac("sha256", key, "0x1337")
// '0xbc985612171f71b89c7561c593f2cea20038d3f38f710b2516e405085d7c0c79'

// To compute the HMAC of UTF-8 data, the data must be
// converted to UTF-8 bytes
computeHmac("sha256", key, toUtf8Bytes("Hello World"))
// '0xd0404ef8fae0d7f18a54a0ddfad8b81afa9e4cdab872a1dc36628c4397fd8201'

Passwords

A Password-Based Key-Derivation Function is designed to create a sequence of bytes suitible as a key from a human-rememberable password.

TYPES

<src>ProgressCallback⇒ (percent: number) => void

A callback during long-running operations to update any UI or provide programatic access to the progress.

The percent is a value between 0 and 1.

FUNCTIONS

<src>pbkdf2(password: BytesLike, salt: BytesLike, iterations: number, keylen: number, algo: "sha256" | "sha512")⇒ string

Return the PBKDF2 for keylen bytes for password using the salt and using iterations of algo.

This PBKDF is outdated and should not be used in new projects, but is required to decrypt older files.

// The password must be converted to bytes, and it is generally
// best practices to ensure the string has been normalized. Many
// formats explicitly indicate the normalization form to use.
password = "hello"
passwordBytes = toUtf8Bytes(password, "NFKC")

salt = id("some-salt")

// Compute the PBKDF2
pbkdf2(passwordBytes, salt, 1024, 16, "sha256")
// '0x226addf5b6d87544337e9733b99ceb9d'

<src>scrypt(passwd: BytesLike, salt: BytesLike, N: number, r: number, p: number, dkLen: number, progress?: ProgressCallback)⇒ Promise< string >

The scrypt PBKDF uses a memory and cpu hard method of derivation to increase the resource cost to brute-force a password for a given key.

This means this algorithm is intentionally slow, and can be tuned to become slower. As computation and memory speed improve over time, increasing the difficulty maintains the cost of an attacker.

For example, if a target time of 5 seconds is used, a legitimate user which knows their password requires only 5 seconds to unlock their account. A 6 character password has 68 billion possibilities, which would require an attacker to invest over 10,000 years of CPU time. This is of course a crude example (as password generally aren't random), but demonstrates to value of imposing large costs to decryption.

For this reason, if building a UI which involved decrypting or encrypting datsa using scrypt, it is recommended to use a ProgressCallback (as event short periods can seem lik an eternity if the UI freezes). Including the phrase "decrypting" in the UI can also help, assuring the user their waiting is for a good reason.

// The password must be converted to bytes, and it is generally
// best practices to ensure the string has been normalized. Many
// formats explicitly indicate the normalization form to use.
password = "hello"
passwordBytes = toUtf8Bytes(password, "NFKC")

salt = id("some-salt")

// Compute the scrypt
scrypt(passwordBytes, salt, 1024, 8, 1, 16)
// Promise<'0x3982633256a26ab2e62efa0621d1a5c0'>

<src>scryptSync(passwd: BytesLike, salt: BytesLike, N: number, r: number, p: number, dkLen: number)⇒ string

Provides a synchronous variant of scrypt.

This will completely lock up and freeze the UI in a browser and will prevent any event loop from progressing. For this reason, it is preferred to use the async variant.

// The password must be converted to bytes, and it is generally
// best practices to ensure the string has been normalized. Many
// formats explicitly indicate the normalization form to use.
password = "hello"
passwordBytes = toUtf8Bytes(password, "NFKC")

salt = id("some-salt")

// Compute the scrypt
scryptSync(passwordBytes, salt, 1024, 8, 1, 16)
// '0x3982633256a26ab2e62efa0621d1a5c0'

Random Values

A Cryptographically Secure Random Value is one that has been generated with additional care take to prevent side-channels from allowing others to detect it and prevent others from through coincidence generate the same values.

FUNCTIONS

<src>randomBytes(length: number)⇒ Uint8Array

Return length bytes of cryptographically secure random data.

randomBytes(8)
// Uint8Array(8) [
//    21,  22, 245, 168,
//   176, 196, 241, 121
// ]

Signing

Add details about signing here.

TYPES

<src>SignatureLike⇒ Signature | string | { r: string , s: string , v: BigNumberish , yParity?: 0 | 1 , yParityAndS?: string } | { r: string , s?: string , v?: number , yParity?: 0 | 1 , yParityAndS: string } | { r: string , s: string , v?: BigNumberish , yParity: 0 | 1 , yParityAndS?: string }

A SignatureLike

class Signature

A Signature @TODO

PROPERTIES

<src>signature.compactSerialized⇒ stringread-only

The EIP-2098 compact representation.

<src>signature.legacyChainId⇒ null | bigintread-only

The chain ID for EIP-155 legacy transactions. For non-legacy transactions, this value is null.

<src>signature.networkV⇒ null | bigintread-only

The EIP-155 v for legacy transactions. For non-legacy transactions, this value is null.

<src>signature.r⇒ string

The r value for a signautre.

This represents the x coordinate of a "reference" or challenge point, from which the y can be computed.

<src>signature.s⇒ string

The s value for a signature.

<src>signature.serialized⇒ stringread-only

The serialized representation.

<src>signature.v⇒ 27 | 28

The v value for a signature.

Since a given x value for r has two possible values for its correspondin y, the v indicates which of the two y values to use.

It is normalized to the values 27 or 28 for legacy purposes.

<src>signature.yParity⇒ 0 | 1read-only

The yParity for the signature.

See v for more details on how this value is used.

<src>signature.yParityAndS⇒ stringread-only

The EIP-2098 compact representation of the yParity and s compacted into a single bytes32.

CREATING INSTANCES

<src>Signature.from(sig?: SignatureLike)⇒ Signature

Creates a new Signature.

If no sig is provided, a new Signature is created with default values.

If sig is a string, it is parsed.

METHODS

<src>signature.clone()⇒ Signature

Returns a new identical Signature.

<src>signature.toJSON()⇒ any

Returns a representation that is compatible with JSON.stringify.

STATIC METHODS

<src>Signature.getChainId(v: BigNumberish)⇒ bigint

Compute the chain ID from the v in a legacy EIP-155 transactions.

Signature.getChainId(45)
// 5n

Signature.getChainId(46)
// 5n

<src>Signature.getChainIdV(chainId: BigNumberish, v: 27 | 28)⇒ bigint

Compute the v for a chain ID for a legacy EIP-155 transactions.

Legacy transactions which use EIP-155 hijack the v property to include the chain ID.

Signature.getChainIdV(5, 27)
// 45n

Signature.getChainIdV(5, 28)
// 46n

<src>Signature.getNormalizedV(v: BigNumberish)⇒ 27 | 28

Compute the normalized legacy transaction v from a yParirty, a legacy transaction v or a legacy EIP-155 transaction.

// The values 0 and 1 imply v is actually yParity
Signature.getNormalizedV(0)
// 27

// Legacy non-EIP-1559 transaction (i.e. 27 or 28)
Signature.getNormalizedV(27)
// 27

// Legacy EIP-155 transaction (i.e. >= 35)
Signature.getNormalizedV(46)
// 28

// Invalid values throw
Signature.getNormalizedV(5)
// Error("invalid v", {
//   code: "INVALID_ARGUMENT"
//   argument: "v"
//   value: 5
// })

class SigningKey

A SigningKey provides high-level access to the elliptic curve cryptography (ECC) operations and key management.

PROPERTIES

<src>signingKey.compressedPublicKey⇒ stringread-only

The compressed public key.

This will always begin with either the prefix 0x02 or 0x03 and be 68 characters long (the 0x prefix and 33 hexadecimal nibbles)

<src>signingKey.privateKey⇒ stringread-only

The private key.

<src>signingKey.publicKey⇒ stringread-only

The uncompressed public key.

This will always begin with the prefix 0x04 and be 132 characters long (the 0x prefix and 130 hexadecimal nibbles).

CREATING INSTANCES

<src>new SigningKey(privateKey: BytesLike)

Creates a new SigningKey for privateKey.

METHODS

<src>signingKey.computeSharedSecret(other: BytesLike)⇒ string

Returns the ECDH shared secret between this private key and the other key.

The other key may be any type of key, a raw public key, a compressed/uncompressed pubic key or aprivate key.

Best practice is usually to use a cryptographic hash on the returned value before using it as a symetric secret.

sign1 = new SigningKey(id("some-secret-1"))
sign2 = new SigningKey(id("some-secret-2"))

// Notice that privA.computeSharedSecret(pubB)...
sign1.computeSharedSecret(sign2.publicKey)
// '0x04b5bc2a5428042331a4c70da8f090d5552bdb35bc08a00ea8ed0a9b6d8737b8b7ea016b268d7cb9f02e11736b82b129ea3f37a8fdc6a7b0e9f5cdde4105ceb0de'

// ...is equal to privB.computeSharedSecret(pubA).
sign2.computeSharedSecret(sign1.publicKey)
// '0x04b5bc2a5428042331a4c70da8f090d5552bdb35bc08a00ea8ed0a9b6d8737b8b7ea016b268d7cb9f02e11736b82b129ea3f37a8fdc6a7b0e9f5cdde4105ceb0de'

<src>signingKey.sign(digest: BytesLike)⇒ Signature

Return the signature of the signed digest.

STATIC METHODS

<src>SigningKey.addPoints(p0: BytesLike, p1: BytesLike, compressed?: boolean)⇒ string

Returns the point resulting from adding the ellipic curve points p0 and p1.

This is not a common function most developers should require, but can be useful for certain privacy-specific techniques.

For example, it is used by HDNodeWallet to compute child addresses from parent public keys and chain codes.

<src>SigningKey.computePublicKey(key: BytesLike, compressed?: boolean)⇒ string

Compute the public key for key, optionally compressed.

The key may be any type of key, a raw public key, a compressed/uncompressed public key or private key.

sign = new SigningKey(id("some-secret"));

// Compute the uncompressed public key for a private key
SigningKey.computePublicKey(sign.privateKey)
// '0x04925bec9818e11ac806bf8b142a7965ac9231aaa9d23f256795d63b1d8d7f203f7481609b6a6964a0f5b459585e9d18a9ec9070d0baf24689138868811c974c96'

// Compute the compressed public key for a private key
SigningKey.computePublicKey(sign.privateKey, true)
// '0x02925bec9818e11ac806bf8b142a7965ac9231aaa9d23f256795d63b1d8d7f203f'

// Compute the uncompressed public key
SigningKey.computePublicKey(sign.publicKey, false);
// '0x04925bec9818e11ac806bf8b142a7965ac9231aaa9d23f256795d63b1d8d7f203f7481609b6a6964a0f5b459585e9d18a9ec9070d0baf24689138868811c974c96'

// Compute the Compressed a public key
SigningKey.computePublicKey(sign.publicKey, true);
// '0x02925bec9818e11ac806bf8b142a7965ac9231aaa9d23f256795d63b1d8d7f203f'

<src>SigningKey.recoverPublicKey(digest: BytesLike, signature: SignatureLike)⇒ string

Returns the public key for the private key which produced the signature for the given digest.

key = new SigningKey(id("some-secret"))
digest = id("hello world")
sig = key.sign(digest)

// Notice the signer public key...
key.publicKey
// '0x04925bec9818e11ac806bf8b142a7965ac9231aaa9d23f256795d63b1d8d7f203f7481609b6a6964a0f5b459585e9d18a9ec9070d0baf24689138868811c974c96'

// ...is equal to the recovered public key
SigningKey.recoverPublicKey(digest, sig)
// '0x04925bec9818e11ac806bf8b142a7965ac9231aaa9d23f256795d63b1d8d7f203f7481609b6a6964a0f5b459585e9d18a9ec9070d0baf24689138868811c974c96'

Hashing Utilities

About hashing here...

FUNCTIONS

<src>dnsEncode(name: string)⇒ string

Returns the DNS encoded name.

This is used for various parts of ENS name resolution, such as the wildcard resolution.

<src>ensNormalize(name: string)⇒ string

Returns the ENS name normalized.

<src>hashMessage(message: Uint8Array | string)⇒ string

Computes the EIP-191 personal-sign message digest to sign.

This prefixes the message with MessagePrefix and the decimal length of message and computes the keccak256 digest.

If message is a string, it is converted to its UTF-8 bytes first. To compute the digest of a DataHexString, it must be converted to bytes.

hashMessage("Hello World")
// '0xa1de988600a42c4b4ab089b619297c17d53cffae5d5120d82d8a92d0bb3b78f2'

// Hashes the SIX (6) string characters, i.e.
// [ "0", "x", "4", "2", "4", "3" ]
hashMessage("0x4243")
// '0x6d91b221f765224b256762dcba32d62209cf78e9bebb0a1b758ca26c76db3af4'

// Hashes the TWO (2) bytes [ 0x42, 0x43 ]...
hashMessage(getBytes("0x4243"))
// '0x0d3abc18ec299cf9b42ba439ac6f7e3e6ec9f5c048943704e30fc2d9c7981438'

// ...which is equal to using data
hashMessage(new Uint8Array([ 0x42, 0x43 ]))
// '0x0d3abc18ec299cf9b42ba439ac6f7e3e6ec9f5c048943704e30fc2d9c7981438'

<src>id(value: string)⇒ string

A simple hashing function which operates on UTF-8 strings to compute an 32-byte irentifier.

This simply computes the UTF-8 bytes and computes the keccak256.

id("hello world")
// '0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad'

<src>isValidName(name: string)⇒ boolean

Returns true if name is a valid ENS name.

<src>namehash(name: string)⇒ string

Returns the namehash for name.

<src>solidityPacked(types: ReadonlyArray< string >, values: ReadonlyArray< any >)⇒ string

Computes the Non-Standard Packed Mode representation of values respectively to their types.

addr = "0x8ba1f109551bd432803012645ac136ddd64dba72"
solidityPacked([ "address", "uint" ], [ addr, 45 ]);
// '0x8ba1f109551bd432803012645ac136ddd64dba72000000000000000000000000000000000000000000000000000000000000002d'

<src>solidityPackedKeccak256(types: ReadonlyArray< string >, values: ReadonlyArray< any >)⇒ string

Computes the Non-Standard Packed Mode keccak256 hash of values respectively to their types.

addr = "0x8ba1f109551bd432803012645ac136ddd64dba72"
solidityPackedKeccak256([ "address", "uint" ], [ addr, 45 ]);
// '0x9465ddbc845149cfc7046bee85c30fd1b52b4f87d9c03ca8a0bd046868763030'

<src>solidityPackedSha256(types: ReadonlyArray< string >, values: ReadonlyArray< any >)⇒ string

Computes the Non-Standard Packed Mode sha256 hash of values respectively to their types.

addr = "0x8ba1f109551bd432803012645ac136ddd64dba72"
solidityPackedSha256([ "address", "uint" ], [ addr, 45 ]);
// '0xb9d5d16842f6832018ea7bd1aa6aef22049eb966a5fb915470e22dfc3e2f828f'

<src>verifyMessage(message: Uint8Array | string, sig: SignatureLike)⇒ string

<src>verifyTypedData(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >, signature: SignatureLike)⇒ string

Compute the address used to sign the typed data for the signature.

interface TypedDataDomain

PROPERTIES

<src>typedDataDomain.chainId⇒ null | BigNumberish

<src>typedDataDomain.name⇒ null | string

<src>typedDataDomain.salt⇒ null | BytesLike

<src>typedDataDomain.verifyingContract⇒ null | string

<src>typedDataDomain.version⇒ null | string

class TypedDataEncoder

PROPERTIES

<src>typedDataEncoder.primaryType⇒ stringread-only

<src>typedDataEncoder.types⇒ Record< string, Array< TypedDataField > >read-only

CREATING INSTANCES

<src>new TypedDataEncoder(types: Record< string, Array< TypedDataField > >)

<src>TypedDataEncoder.from(types: Record< string, Array< TypedDataField > >)⇒ TypedDataEncoder

METHODS

<src>typedDataEncoder._visit(type: string, value: any, callback: (type: string, data: any) => any)⇒ any

<src>typedDataEncoder.encode(value: Record< string, any >)⇒ string

<src>typedDataEncoder.encodeData(type: string, value: any)⇒ string

<src>typedDataEncoder.encodeType(name: string)⇒ string

<src>typedDataEncoder.getEncoder(type: string)⇒ (value: any) => string

<src>typedDataEncoder.hash(value: Record< string, any >)⇒ string

<src>typedDataEncoder.hashStruct(name: string, value: Record< string, any >)⇒ string

<src>typedDataEncoder.visit(value: Record< string, any >, callback: (type: string, data: any) => any)⇒ any

STATIC METHODS

<src>TypedDataEncoder.encode(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ string

<src>TypedDataEncoder.getPayload(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ any

<src>TypedDataEncoder.getPrimaryType(types: Record< string, Array< TypedDataField > >)⇒ string

<src>TypedDataEncoder.hash(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ string

<src>TypedDataEncoder.hashDomain(domain: TypedDataDomain)⇒ string

<src>TypedDataEncoder.hashStruct(name: string, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ string

<src>TypedDataEncoder.resolveNames(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >, resolveName: (name: string) => Promise< string >)⇒ Promise< { domain: TypedDataDomain , value: any } >

interface TypedDataField

PROPERTIES

<src>typedDataField.name⇒ string

<src>typedDataField.type⇒ string

Providers

About providers.

TYPES

<src>BlockTag⇒ BigNumberish | string

<src>DebugEventBrowserProvider⇒ { action: "sendEip1193Payload" , payload: { method: string , params: Array< any > } } | { action: "receiveEip1193Result" , result: any } | { action: "receiveEip1193Error" , error: Error }

<src>GasCostParameters⇒ { txAccessListAddress?: number , txAccessListStorageKey?: number , txBase?: number , txCreate?: number , txDataNonzero?: number , txDataZero?: number }

<src>OrphanFilter⇒ { hash: string , number: number , orphan: "drop-block" } | { orphan: "drop-transaction" , other?: { blockHash: string , blockNumber: number , hash: string } , tx: { blockHash: string , blockNumber: number , hash: string } } | { orphan: "reorder-transaction" , other?: { blockHash: string , blockNumber: number , hash: string } , tx: { blockHash: string , blockNumber: number , hash: string } } | { log: { address: string , blockHash: string , blockNumber: number , data: string , index: number , topics: ReadonlyArray< string > , transactionHash: string } , orphan: "drop-log" }

An Orphan Filter allows detecting when an orphan block has resulted in dropping a block or transaction or has resulted in transactions changing order.

Not currently fully supported.

<src>ProviderEvent⇒ string | Array< string | Array< string > > | EventFilter | OrphanFilter

<src>TopicFilter⇒ Array< null | string | Array< string > >

A TopicFilter provides a struture to define bloom-filter queries.

Each field that is null matches any value, a field that is a string must match exactly that value and and array is effectively an OR-ed set, where any one of those values must match.

<src>WebSocketCreator⇒ () => WebSocketLike

FUNCTIONS

<src>copyRequest(req: TransactionRequest)⇒ PreparedTransactionRequest

<src>getDefaultProvider(network: string | Networkish | WebSocketLike, options?: any)⇒ AbstractProvider

class Block

inherits from BlockParams

A Block represents the data associated with a full block on Ethereum.

PROPERTIES

<src>block.baseFeePerGas⇒ null | bigintread-only

The base fee per gas that all transactions in this block were charged.

This adjusts after each block, depending on how congested the network is.

<src>block.date⇒ null | Dateread-only

The Date this block was included at.

<src>block.difficulty⇒ bigintread-only

The difficulty target.

On legacy networks, this is the proof-of-work target required for a block to meet the protocol rules to be included.

On modern networks, this is a random number arrived at using randao. @TODO: Find links?

<src>block.extraData⇒ stringread-only

Any extra data the validator wished to include.

<src>block.gasLimit⇒ bigintread-only

The total gas limit for this block.

<src>block.gasUsed⇒ bigintread-only

The total gas used in this block.

<src>block.hash⇒ null | stringread-only

The block hash.

<src>block.length⇒ numberread-only

The number of transactions in this block.

<src>block.miner⇒ stringread-only

The miner coinbase address, wihch receives any subsidies for including this block.

<src>block.nonce⇒ stringread-only

The nonce.

On legacy networks, this is the random number inserted which permitted the difficulty target to be reached.

<src>block.number⇒ numberread-only

The block number, sometimes called the block height. This is a sequential number that is one higher than the parent block.

<src>block.parentHash⇒ stringread-only

The block hash of the parent block.

<src>block.prefetchedTransactions⇒ Array< TransactionResponse >read-only

Returns the complete transactions for blocks which prefetched them, by passing true to prefetchTxs into provider_getBlock.

<src>block.provider⇒ Providerread-only

The provider connected to the block used to fetch additional details if necessary.

<src>block.timestamp⇒ numberread-only

The timestamp for this block, which is the number of seconds since epoch that this block was included.

<src>block.transactions⇒ ReadonlyArray< string >read-only

Returns the list of transaction hashes.

CREATING INSTANCES

<src>new Block(block: BlockParams, provider: Provider)

Create a new Block object.

This should generally not be necessary as the unless implementing a low-level library.

METHODS

<src>block.getPrefetchedTransaction(indexOrHash: number | string)⇒ TransactionResponse

<src>block.getTransaction(indexOrHash: number | string)⇒ Promise< TransactionResponse >

Get the transaction at indexe within this block.

<src>block.isLondon()⇒ boolean

<src>block.isMined()⇒ boolean

Has this block been mined.

If true, the block has been typed-gaurded that all mined properties are non-null.

<src>block.orphanedEvent()⇒ OrphanFilter

<src>block.toJSON()⇒ any

Returns a JSON-friendly value.

class BrowserProvider

inherits from JsonRpcApiPollingProvider, JsonRpcApiProvider

CREATING INSTANCES

<src>new BrowserProvider(ethereum: Eip1193Provider, network?: Networkish)

METHODS

<src>browserProvider._send(payload: JsonRpcPayload | Array< JsonRpcPayload >)⇒ Promise< Array< JsonRpcResult | JsonRpcError > >

<src>browserProvider.getRpcError(payload: JsonRpcPayload, error: JsonRpcError)⇒ Error

<src>browserProvider.getSigner(address?: number | string)⇒ Promise< JsonRpcSigner >

<src>browserProvider.hasSigner(address: number | string)⇒ Promise< boolean >

<src>browserProvider.send(method: string, params: Array< any > | Record< string, any >)⇒ Promise< any >

interface ContractRunner

PROPERTIES

<src>contractRunner.call⇒ (tx: TransactionRequest) => Promise< string >

<src>contractRunner.estimateGas⇒ (tx: TransactionRequest) => Promise< bigint >

<src>contractRunner.provider⇒ null | Provider

<src>contractRunner.resolveName⇒ (name: string) => Promise< null | string >

<src>contractRunner.sendTransaction⇒ (tx: TransactionRequest) => Promise< TransactionResponse >

interface Eip1193Provider

METHODS

<src>eip1193Provider.request(request: { method: string , params?: Array< any > | Record< string, any > })⇒ Promise< any >

class EnsPlugin

inherits from NetworkPlugin

PROPERTIES

<src>ensPlugin.address⇒ stringread-only

<src>ensPlugin.targetNetwork⇒ numberread-only

CREATING INSTANCES

<src>new EnsPlugin(address?: null | string, targetNetwork?: null | number)

METHODS

<src>ensPlugin.clone()⇒ EnsPlugin

interface EventFilter

PROPERTIES

<src>eventFilter.address⇒ AddressLike | Array< AddressLike >

<src>eventFilter.topics⇒ TopicFilter

class FeeData

A FeeData wraps all the fee-related values associated with the network.

PROPERTIES

<src>feeData.gasPrice⇒ null | bigintread-only

The gas price for legacy networks.

<src>feeData.maxFeePerGas⇒ null | bigintread-only

The maximum fee to pay per gas.

The base fee per gas is defined by the network and based on congestion, increasing the cost during times of heavy load and lowering when less busy.

The actual fee per gas will be the base fee for the block and the priority fee, up to the max fee per gas.

This will be null on legacy networks (i.e. pre-EIP-1559)

<src>feeData.maxPriorityFeePerGas⇒ null | bigintread-only

The additional amout to pay per gas to encourage a validator to include the transaction.

The purpose of this is to compensate the validator for the adjusted risk for including a given transaction.

This will be null on legacy networks (i.e. pre-EIP-1559)

CREATING INSTANCES

<src>new FeeData(gasPrice?: null | bigint, maxFeePerGas?: null | bigint, maxPriorityFeePerGas?: null | bigint)

Creates a new FeeData for gasPrice, maxFeePerGas and maxPriorityFeePerGas.

METHODS

<src>feeData.toJSON()⇒ any

Returns a JSON-friendly value.

class FeeDataNetworkPlugin

inherits from NetworkPlugin

PROPERTIES

<src>feeDataNetworkPlugin.feeDataFunc⇒ (provider: Provider) => Promise< FeeData >read-only

CREATING INSTANCES

<src>new FeeDataNetworkPlugin(feeDataFunc: (provider: Provider) => Promise< FeeData >)

METHODS

<src>feeDataNetworkPlugin.clone()⇒ FeeDataNetworkPlugin

<src>feeDataNetworkPlugin.getFeeData(provider: Provider)⇒ Promise< FeeData >

interface Filter

inherits from EventFilter

PROPERTIES

<src>filter.fromBlock⇒ BlockTag

<src>filter.toBlock⇒ BlockTag

interface FilterByBlockHash

inherits from EventFilter

PROPERTIES

<src>filterByBlockHash.blockHash⇒ string

class GasCostPlugin

inherits from NetworkPlugin

PROPERTIES

<src>gasCostPlugin.effectiveBlock⇒ numberread-only

<src>gasCostPlugin.txAccessListAddress⇒ numberread-only

<src>gasCostPlugin.txAccessListStorageKey⇒ numberread-only

<src>gasCostPlugin.txBase⇒ numberread-only

<src>gasCostPlugin.txCreate⇒ numberread-only

<src>gasCostPlugin.txDataNonzero⇒ numberread-only

<src>gasCostPlugin.txDataZero⇒ numberread-only

CREATING INSTANCES

<src>new GasCostPlugin(effectiveBlock?: number, costs?: GasCostParameters)

METHODS

<src>gasCostPlugin.clone()⇒ GasCostPlugin

class IpcSocketProvider

inherits from SocketProvider, JsonRpcApiProvider

PROPERTIES

<src>ipcSocketProvider.socket⇒ Socketread-only

CREATING INSTANCES

<src>new IpcSocketProvider(path: string, network?: Networkish)

METHODS

<src>ipcSocketProvider._write(message: string)⇒ Promise< void >

<src>ipcSocketProvider.destroy()⇒ void

class Log

inherits from LogParams

PROPERTIES

<src>log.address⇒ stringread-only

<src>log.blockHash⇒ stringread-only

<src>log.blockNumber⇒ numberread-only

<src>log.data⇒ stringread-only

<src>log.index⇒ numberread-only

<src>log.provider⇒ Providerread-only

<src>log.removed⇒ booleanread-only

<src>log.topics⇒ ReadonlyArray< string >read-only

<src>log.transactionHash⇒ stringread-only

<src>log.transactionIndex⇒ numberread-only

CREATING INSTANCES

<src>new Log(log: LogParams, provider: Provider)

METHODS

<src>log.getBlock()⇒ Promise< Block >

<src>log.getTransaction()⇒ Promise< TransactionResponse >

<src>log.getTransactionReceipt()⇒ Promise< TransactionReceipt >

<src>log.removedEvent()⇒ OrphanFilter

<src>log.toJSON()⇒ any

interface MinedBlock

inherits from Block, BlockParams

An Interface to indicate a Block has been included in the blockchain. This asserts a Type Guard that necessary properties are non-null.

Before a block is included, it is a pending block.

PROPERTIES

<src>minedBlock.date⇒ Dateread-only

<src>minedBlock.hash⇒ stringread-only

<src>minedBlock.miner⇒ stringread-only

<src>minedBlock.number⇒ numberread-only

<src>minedBlock.timestamp⇒ numberread-only

interface MinedTransactionResponse

inherits from TransactionResponse, TransactionResponseParams

PROPERTIES

<src>minedTransactionResponse.blockHash⇒ string

<src>minedTransactionResponse.blockNumber⇒ number

<src>minedTransactionResponse.date⇒ Date

class NetworkPlugin

PROPERTIES

<src>networkPlugin.name⇒ stringread-only

CREATING INSTANCES

<src>new NetworkPlugin(name: string)

METHODS

<src>networkPlugin.clone()⇒ NetworkPlugin

class NonceManager

inherits from AbstractSigner, Signer

PROPERTIES

<src>nonceManager.signer⇒ Signer

CREATING INSTANCES

<src>new NonceManager(signer: Signer)

METHODS

<src>nonceManager.connect(provider: null | Provider)⇒ NonceManager

<src>nonceManager.getAddress()⇒ Promise< string >

<src>nonceManager.getNonce(blockTag?: BlockTag)⇒ Promise< number >

<src>nonceManager.increment()⇒ void

<src>nonceManager.reset()⇒ void

<src>nonceManager.sendTransaction(tx: TransactionRequest)⇒ Promise< TransactionResponse >

<src>nonceManager.signMessage(message: string | Uint8Array)⇒ Promise< string >

<src>nonceManager.signTransaction(tx: TransactionRequest)⇒ Promise< string >

<src>nonceManager.signTypedData(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ Promise< string >

interface PreparedTransactionRequest

PROPERTIES

<src>preparedTransactionRequest.accessList⇒ AccessList

<src>preparedTransactionRequest.blockTag⇒ BlockTag

<src>preparedTransactionRequest.chainId⇒ bigint

<src>preparedTransactionRequest.customData⇒ any

<src>preparedTransactionRequest.data⇒ string

<src>preparedTransactionRequest.enableCcipRead⇒ boolean

<src>preparedTransactionRequest.from⇒ AddressLike

<src>preparedTransactionRequest.gasLimit⇒ bigint

<src>preparedTransactionRequest.gasPrice⇒ bigint

<src>preparedTransactionRequest.maxFeePerGas⇒ bigint

<src>preparedTransactionRequest.maxPriorityFeePerGas⇒ bigint

<src>preparedTransactionRequest.nonce⇒ number

<src>preparedTransactionRequest.to⇒ AddressLike

<src>preparedTransactionRequest.type⇒ number

<src>preparedTransactionRequest.value⇒ bigint

interface Provider

inherits from ContractRunner, EventEmitterable, NameResolver

A Provider is the primary method to interact with the read-only content on Ethereum.

It allows access to details about accounts, blocks and transactions and the ability to query event logs and simulate contract execution.

Account data includes the balance, transaction count, code and state trie storage.

Simulating execution can be used to call, estimate gas and get transaction results.

The broadcastTransaction is the only method which allows updating the blockchain, but it is usually accessed by a Signer, since a private key must be used to sign the transaction before it can be broadcast.

PROPERTIES

<src>provider.provider⇒ this

The provider iteself.

This is part of the necessary API for executing a contract, as it provides a common property on any ContractRunner that can be used to access the read-only portion of the runner.

METHODS

<src>provider.broadcastTransaction(signedTx: string)⇒ Promise< TransactionResponse >

Broadcasts the signedTx to the network, adding it to the memory pool of any node for which the transaction meets the rebroadcast requirements.

<src>provider.call(tx: TransactionRequest)⇒ Promise< string >

Simulate the execution of tx. If the call reverts, it will throw a CallExceptionError which includes the revert data.

<src>provider.destroy()⇒ void

Shutdown any resources this provider is using. No additional calls should be made to this provider after calling this.

<src>provider.estimateGas(tx: TransactionRequest)⇒ Promise< bigint >

Estimates the amount of gas required to executre tx.

<src>provider.getBalance(address: AddressLike, blockTag?: BlockTag)⇒ Promise< bigint >

Get the account balance (in wei) of address. If blockTag is specified and the node supports archive access for that blockTag, the balance is as of that BlockTag.

<src>provider.getBlock(blockHashOrBlockTag: BlockTag | string, prefetchTxs?: boolean)⇒ Promise< null | Block >

Resolves to the block for blockHashOrBlockTag.

If prefetchTxs, and the backend supports including transactions with block requests, all transactions will be included and the Block object will not need to make remote calls for getting transactions.

<src>provider.getBlockNumber()⇒ Promise< number >

Get the current block number.

<src>provider.getCode(address: AddressLike, blockTag?: BlockTag)⇒ Promise< string >

Get the bytecode for address.

<src>provider.getFeeData()⇒ Promise< FeeData >

Get the best guess at the recommended FeeData.

<src>provider.getLogs(filter: Filter | FilterByBlockHash)⇒ Promise< Array< Log > >

Resolves to the list of Logs that match filter

<src>provider.getNetwork()⇒ Promise< Network >

Get the connected Network.

<src>provider.getStorage(address: AddressLike, position: BigNumberish, blockTag?: BlockTag)⇒ Promise< string >

Get the storage slot value for address at slot position.

<src>provider.getTransaction(hash: string)⇒ Promise< null | TransactionResponse >

Resolves to the transaction for hash.

If the transaction is unknown or on pruning nodes which discard old transactions this resolves to null.

<src>provider.getTransactionCount(address: AddressLike, blockTag?: BlockTag)⇒ Promise< number >

Get the number of transactions ever sent for address, which is used as the nonce when sending a transaction. If blockTag is specified and the node supports archive access for that blockTag, the transaction count is as of that BlockTag.

<src>provider.getTransactionReceipt(hash: string)⇒ Promise< null | TransactionReceipt >

Resolves to the transaction receipt for hash, if mined.

If the transaction has not been mined, is unknown or on pruning nodes which discard old transactions this resolves to null.

<src>provider.getTransactionResult(hash: string)⇒ Promise< null | string >

Resolves to the result returned by the executions of hash.

This is only supported on nodes with archive access and with the necessary debug APIs enabled.

<src>provider.lookupAddress(address: string)⇒ Promise< null | string >

Resolves to the ENS name associated for the address or null if the primary name is not configured.

Users must perform additional steps to configure a primary name, which is not currently common.

<src>provider.resolveName(ensName: string)⇒ Promise< null | string >

Resolves to the address configured for the ensName or null if unconfigured.

<src>provider.waitForBlock(blockTag?: BlockTag)⇒ Promise< Block >

Resolves to the block at blockTag once it has been mined.

This can be useful for waiting some number of blocks by using the currentBlockNumber + N.

<src>provider.waitForTransaction(hash: string, confirms?: number, timeout?: number)⇒ Promise< null | TransactionReceipt >

Waits until the transaction hash is mined and has confirms confirmations.

interface Signer

inherits from Addressable, ContractRunner, NameResolver

A Signer represents an account on the Ethereum Blockchain, and is most often backed by a private key represented by a mnemonic or residing on a Hardware Wallet.

The API remains abstract though, so that it can deal with more advanced exotic Signing entities, such as Smart Contract Wallets or Virtual Wallets (where the private key may not be known).

PROPERTIES

<src>signer.provider⇒ null | Provider

The Provider attached to this Signer (if any).

METHODS

<src>signer.call(tx: TransactionRequest)⇒ Promise< string >

Evaluates the tx by running it against the current Blockchain state. This cannot change state and has no cost in ether, as it is effectively simulating execution.

This can be used to have the Blockchain perform computations based on its state (e.g. running a Contract's getters) or to simulate the effect of a transaction before actually performing an operation.

<src>signer.connect(provider: null | Provider)⇒ Signer

Returns a new instance of this Signer connected to provider or detached from any Provider if null.

<src>signer.estimateGas(tx: TransactionRequest)⇒ Promise< bigint >

Estimates the required gas required to execute tx on the Blockchain. This will be the expected amount a transaction will require as its gasLimit to successfully run all the necessary computations and store the needed state that the transaction intends.

Keep in mind that this is best efforts, since the state of the Blockchain is in flux, which could affect transaction gas requirements.

<src>signer.getAddress()⇒ Promise< string >

Get the address of the Signer.

<src>signer.getNonce(blockTag?: BlockTag)⇒ Promise< number >

Gets the next nonce required for this Signer to send a transaction.

<src>signer.populateCall(tx: TransactionRequest)⇒ Promise< TransactionLike < string > >

Prepares a {@link TransactionRequest} for calling:

resolves to and from addresses
if from is specified , check that it matches this Signer

<src>signer.populateTransaction(tx: TransactionRequest)⇒ Promise< TransactionLike < string > >

Prepares a {@link TransactionRequest} for sending to the network by populating any missing properties:

resolves to and from addresses
if from is specified , check that it matches this Signer
populates nonce via signer.getNonce("pending")
populates gasLimit via signer.estimateGas(tx)
populates chainId via signer.provider.getNetwork()
populates type and relevant fee data for that type (gasPrice for legacy transactions, maxFeePerGas for EIP-1559, etc)

<src>signer.resolveName(name: string)⇒ Promise< null | string >

Resolves an ENS Name to an address.

<src>signer.sendTransaction(tx: TransactionRequest)⇒ Promise< TransactionResponse >

Sends tx to the Network. The signer.populateTransaction(tx) is called first to ensure all necessary properties for the transaction to be valid have been popualted first.

<src>signer.signMessage(message: string | Uint8Array)⇒ Promise< string >

Signers an EIP-191 prefixed personal message.

If the message is a string, it is signed as UTF-8 encoded bytes. It is not interpretted as a BytesLike; so the string "0x1234" is signed as six characters, not two bytes.

To sign that example as two bytes, the Uint8Array should be used (i.e. new Uint8Array([ 0x12, 0x34 ])).

<src>signer.signTransaction(tx: TransactionRequest)⇒ Promise< string >

Signs tx, returning the fully signed transaction. This does not populate any additional properties within the transaction.

<src>signer.signTypedData(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ Promise< string >

Signs the EIP-712 typed data.

class TransactionReceipt

inherits from TransactionReceiptParams

PROPERTIES

<src>transactionReceipt.blockHash⇒ stringread-only

<src>transactionReceipt.blockNumber⇒ numberread-only

<src>transactionReceipt.contractAddress⇒ null | stringread-only

<src>transactionReceipt.cumulativeGasUsed⇒ bigintread-only

<src>transactionReceipt.fee⇒ bigintread-only

<src>transactionReceipt.from⇒ stringread-only

<src>transactionReceipt.gasPrice⇒ bigintread-only

<src>transactionReceipt.gasUsed⇒ bigintread-only

<src>transactionReceipt.hash⇒ stringread-only

<src>transactionReceipt.index⇒ numberread-only

<src>transactionReceipt.length⇒ numberread-only

<src>transactionReceipt.logs⇒ ReadonlyArray< Log >read-only

<src>transactionReceipt.logsBloom⇒ stringread-only

<src>transactionReceipt.provider⇒ Providerread-only

<src>transactionReceipt.root⇒ null | stringread-only

<src>transactionReceipt.status⇒ null | numberread-only

<src>transactionReceipt.to⇒ null | stringread-only

<src>transactionReceipt.type⇒ numberread-only

CREATING INSTANCES

<src>new TransactionReceipt(tx: TransactionReceiptParams, provider: Provider)

METHODS

<src>transactionReceipt.confirmations()⇒ Promise< number >

<src>transactionReceipt.getBlock()⇒ Promise< Block >

<src>transactionReceipt.getResult()⇒ Promise< string >

<src>transactionReceipt.getTransaction()⇒ Promise< TransactionResponse >

<src>transactionReceipt.removedEvent()⇒ OrphanFilter

<src>transactionReceipt.reorderedEvent(other?: TransactionResponse)⇒ OrphanFilter

<src>transactionReceipt.toJSON()⇒ any

interface TransactionRequest

PROPERTIES

<src>transactionRequest.accessList⇒ null | AccessListish

<src>transactionRequest.blockTag⇒ BlockTag

<src>transactionRequest.chainId⇒ null | BigNumberish

<src>transactionRequest.customData⇒ any

<src>transactionRequest.data⇒ null | string

<src>transactionRequest.enableCcipRead⇒ boolean

<src>transactionRequest.from⇒ null | AddressLike

<src>transactionRequest.gasLimit⇒ null | BigNumberish

<src>transactionRequest.gasPrice⇒ null | BigNumberish

<src>transactionRequest.maxFeePerGas⇒ null | BigNumberish

<src>transactionRequest.maxPriorityFeePerGas⇒ null | BigNumberish

<src>transactionRequest.nonce⇒ null | number

<src>transactionRequest.to⇒ null | AddressLike

<src>transactionRequest.type⇒ null | number

<src>transactionRequest.value⇒ null | BigNumberish

class TransactionResponse

inherits from TransactionResponseParams

PROPERTIES

<src>transactionResponse.accessList⇒ null | AccessListread-only

The EIP-2930 access list for transaction types that support it, otherwise null.

<src>transactionResponse.blockHash⇒ null | stringread-only

The blockHash of the block that this transaction was included in.

This is null for pending transactions.

<src>transactionResponse.blockNumber⇒ null | numberread-only

The block number of the block that this transaction was included in.

This is null for pending transactions.

<src>transactionResponse.chainId⇒ bigintread-only

The chain ID.

<src>transactionResponse.data⇒ stringread-only

The data.

<src>transactionResponse.from⇒ stringread-only

The sender of this transaction. It is implicitly computed from the transaction pre-image hash (as the digest) and the signature using ecrecover.

<src>transactionResponse.gasLimit⇒ bigintread-only

The maximum units of gas this transaction can consume. If execution exceeds this, the entries transaction is reverted and the sender is charged for the full amount, despite not state changes being made.

<src>transactionResponse.gasPrice⇒ bigintread-only

The gas price can have various values, depending on the network.

In modern networks, for transactions that are included this is the effective gas price (the fee per gas that was actually charged), while for transactions that have not been included yet is the maxFeePerGas.

For legacy transactions, or transactions on legacy networks, this is the fee that will be charged per unit of gas the transaction consumes.

<src>transactionResponse.hash⇒ stringread-only

The transaction hash.

<src>transactionResponse.index⇒ numberread-only

The index within the block that this transaction resides at.

<src>transactionResponse.maxFeePerGas⇒ null | bigintread-only

The maximum fee (per unit of gas) to allow this transaction to charge the sender.

<src>transactionResponse.maxPriorityFeePerGas⇒ null | bigintread-only

The maximum priority fee (per unit of gas) to allow a validator to charge the sender. This is inclusive of the maxFeeFeePerGas.

<src>transactionResponse.nonce⇒ numberread-only

The nonce, which is used to prevent replay attacks and offer a method to ensure transactions from a given sender are explicitly ordered.

When sending a transaction, this must be equal to the number of transactions ever sent by from.

<src>transactionResponse.provider⇒ Providerread-only

The provider this is connected to, which will influence how its methods will resolve its async inspection methods.

<src>transactionResponse.signature⇒ Signatureread-only

The signature.

<src>transactionResponse.to⇒ null | stringread-only

The receiver of this transaction.

If null, then the transaction is an initcode transaction. This means the result of executing the data will be deployed as a new contract on chain (assuming it does not revert) and the address may be computed using getCreateAddress.

<src>transactionResponse.type⇒ numberread-only

The EIP-2718 transaction envelope type. This is 0 for legacy transactions types.

<src>transactionResponse.value⇒ bigintread-only

The value, in wei. Use formatEther to format this value as ether.

CREATING INSTANCES

<src>new TransactionResponse(tx: TransactionResponseParams, provider: Provider)

Create a new TransactionResponse with tx parameters connected to provider.

METHODS

<src>transactionResponse.getBlock()⇒ Promise< null | Block >

Resolves to the Block that this transaction was included in.

This will return null if the transaction has not been included yet.

<src>transactionResponse.getTransaction()⇒ Promise< null | TransactionResponse >

Resolves to this transaction being re-requested from the provider. This can be used if you have an unmined transaction and wish to get an up-to-date populated instance.

<src>transactionResponse.isBerlin()⇒ boolean

Returns true if the transaction is a Berlin (i.e. type == 1) transaction. See EIP-2930.

This provides a Type Guard that this transaction will have the null-ness for hardfork-specific properties set correctly.

<src>transactionResponse.isLegacy()⇒ boolean

Returns true if the transaction is a legacy (i.e. type == 0) transaction.

This provides a Type Guard that this transaction will have the null-ness for hardfork-specific properties set correctly.

<src>transactionResponse.isLondon()⇒ boolean

Returns true if the transaction is a London (i.e. type == 2) transaction. See EIP-1559.

This provides a Type Guard that this transaction will have the null-ness for hardfork-specific properties set correctly.

<src>transactionResponse.isMined()⇒ boolean

Returns true if this transaction has been included.

This is effective only as of the time the TransactionResponse was instantiated. To get up-to-date information, use getTransaction.

This provides a Type Guard that this transaction will have non-null property values for properties that are null for unmined transactions.

<src>transactionResponse.removedEvent()⇒ OrphanFilter

Returns a filter which can be used to listen for orphan events that evict this transaction.

<src>transactionResponse.reorderedEvent(other?: TransactionResponse)⇒ OrphanFilter

Returns a filter which can be used to listen for orphan events that re-order this event against other.

<src>transactionResponse.replaceableTransaction(startBlock: number)⇒ TransactionResponse

Returns a new TransactionResponse instance which has the ability to detect (and throw an error) if the transaction is replaced, which will begin scanning at startBlock.

This should generally not be used by developers and is intended primarily for internal use. Setting an incorrect startBlock can have devastating performance consequences if used incorrectly.

<src>transactionResponse.toJSON()⇒ any

Returns a JSON representation of this transaction.

<src>transactionResponse.wait(confirms?: number, timeout?: number)⇒ Promise< null | TransactionReceipt >

Resolves once this transaction has been mined and has confirms blocks including it (default: 1) with an optional timeout.

This can resolve to null only if confirms is 0 and the transaction has not been mined, otherwise this will wait until enough confirmations have completed.

interface WebSocketLike

PROPERTIES

<src>webSocketLike.onerror⇒ null | PAREN<(args: Array< any >) => any>

<src>webSocketLike.onmessage⇒ null | PAREN<(args: Array< any >) => any>

<src>webSocketLike.onopen⇒ null | PAREN<(args: Array< any >) => any>

<src>webSocketLike.readyState⇒ number

METHODS

<src>webSocketLike.close(code?: number, reason?: string)⇒ void

<src>webSocketLike.send(payload: any)⇒ void

class WebSocketProvider

inherits from SocketProvider, JsonRpcApiProvider

PROPERTIES

<src>webSocketProvider.websocket⇒ WebSocketLikeread-only

CREATING INSTANCES

<src>new WebSocketProvider(url: string | WebSocketLike | WebSocketCreator, network?: Networkish)

METHODS

<src>webSocketProvider._write(message: string)⇒ Promise< void >

<src>webSocketProvider.destroy()⇒ Promise< void >

Networks

About networks

TYPES

<src>Networkish⇒ Network | number | bigint | string | { chainId?: number , ensAddress?: string , ensNetwork?: number , name?: string }

A Networkish can be used to allude to a Network, by specifing:

a Network object
a well-known (or registered) network name
a well-known (or registered) chain ID
an object with sufficient details to describe a network

class Network

PROPERTIES

<src>network.chainId⇒ bigint

<src>network.name⇒ string

<src>network.plugins⇒ Array< NetworkPlugin >read-only

CREATING INSTANCES

<src>new Network(name: string, chainId: BigNumberish)

<src>Network.from(network?: Networkish)⇒ Network

Returns a new Network for the network name or chainId.

METHODS

<src>network.attachPlugin(plugin: NetworkPlugin)⇒ this

<src>network.clone()⇒ Network

<src>network.computeIntrinsicGas(tx: TransactionLike)⇒ number

<src>network.getPlugin(name: string)⇒ null | T

<src>network.getPlugins(basename: string)⇒ Array< T >

<src>network.toJSON()⇒ any

STATIC METHODS

<src>Network.register(nameOrChainId: string | number | bigint, networkFunc: () => Network)⇒ void

Subclassing Provider

About Subclassing the Provider...

TYPES

<src>DebugEventAbstractProvider⇒ { action: "sendCcipReadFetchRequest" , index: number , request: FetchRequest , urls: Array< string > } | { action: "receiveCcipReadFetchResult" , request: FetchRequest , result: any } | { action: "receiveCcipReadFetchError" , request: FetchRequest , result: any } | { action: "sendCcipReadCall" , transaction: { data: string , to: string } } | { action: "receiveCcipReadCallResult" , result: string , transaction: { data: string , to: string } } | { action: "receiveCcipReadCallError" , error: Error , transaction: { data: string , to: string } }

<src>PerformActionFilter⇒ { address?: string | Array< string > , fromBlock?: BlockTag , toBlock?: BlockTag , topics?: Array< null | string | Array< string > > } | { address?: string | Array< string > , blockHash?: string , topics?: Array< null | string | Array< string > > }

<src>PerformActionRequest⇒ { method: "broadcastTransaction" , signedTransaction: string } | { blockTag: BlockTag , method: "call" , transaction: PerformActionTransaction } | { method: "chainId" } | { method: "estimateGas" , transaction: PerformActionTransaction } | { address: string , blockTag: BlockTag , method: "getBalance" } | { blockTag: BlockTag , includeTransactions: boolean , method: "getBlock" } | { blockHash: string , includeTransactions: boolean , method: "getBlock" } | { method: "getBlockNumber" } | { address: string , blockTag: BlockTag , method: "getCode" } | { method: "getGasPrice" } | { filter: PerformActionFilter , method: "getLogs" } | { address: string , blockTag: BlockTag , method: "getStorage" , position: bigint } | { hash: string , method: "getTransaction" } | { address: string , blockTag: BlockTag , method: "getTransactionCount" } | { hash: string , method: "getTransactionReceipt" } | { hash: string , method: "getTransactionResult" }

<src>Subscription⇒ { tag: string , type: "block" | "close" | "debug" | "network" | "pending" } | { hash: string , tag: string , type: "transaction" } | { filter: EventFilter , tag: string , type: "event" } | { filter: OrphanFilter , tag: string , type: "orphan" }

FUNCTIONS

<src>getPollingSubscriber(provider: AbstractProvider, event: ProviderEvent)⇒ Subscriber

class AbstractProvider

inherits from Provider, ContractRunner, EventEmitterable, NameResolver

PROPERTIES

<src>abstractProvider.disableCcipRead⇒ boolean

<src>abstractProvider.paused⇒ boolean

<src>abstractProvider.plugins⇒ Array< AbstractProviderPlugin >read-only

<src>abstractProvider.provider⇒ thisread-only

CREATING INSTANCES

<src>new AbstractProvider(network?: "any" | Networkish)

METHODS

<src>abstractProvider._clearTimeout(timerId: number)⇒ void

<src>abstractProvider._detectNetwork()⇒ Promise< Network >

<src>abstractProvider._forEachSubscriber(func: (s: Subscriber) => void)⇒ void

<src>abstractProvider._getAddress(address: AddressLike)⇒ string | Promise< string >

<src>abstractProvider._getBlockTag(blockTag?: BlockTag)⇒ string | Promise< string >

<src>abstractProvider._getFilter(filter: Filter | FilterByBlockHash)⇒ PerformActionFilter | Promise< PerformActionFilter >

<src>abstractProvider._getProvider(chainId: number)⇒ AbstractProvider

<src>abstractProvider._getSubscriber(sub: Subscription)⇒ Subscriber

<src>abstractProvider._getTransactionRequest(request: TransactionRequest)⇒ PerformActionTransaction | Promise< PerformActionTransaction >

<src>abstractProvider._perform(req: PerformActionRequest)⇒ Promise< T >

<src>abstractProvider._recoverSubscriber(oldSub: Subscriber, newSub: Subscriber)⇒ void

<src>abstractProvider._setTimeout(func: () => void, timeout?: number)⇒ number

<src>abstractProvider._wrapBlock(value: BlockParams, network: Network)⇒ Block

<src>abstractProvider._wrapLog(value: LogParams, network: Network)⇒ Log

<src>abstractProvider._wrapTransactionReceipt(value: TransactionReceiptParams, network: Network)⇒ TransactionReceipt

<src>abstractProvider._wrapTransactionResponse(tx: TransactionResponseParams, network: Network)⇒ TransactionResponse

<src>abstractProvider.addListener(event: ProviderEvent, listener: Listener)⇒ Promise< this >

<src>abstractProvider.attachPlugin(plugin: AbstractProviderPlugin)⇒ this

<src>abstractProvider.broadcastTransaction(signedTx: string)⇒ Promise< TransactionResponse >

<src>abstractProvider.call(tx: TransactionRequest)⇒ Promise< string >

<src>abstractProvider.ccipReadFetch(tx: PerformActionTransaction, calldata: string, urls: Array< string >)⇒ Promise< null | string >

<src>abstractProvider.destroy()⇒ void

<src>abstractProvider.emit(event: ProviderEvent, args: Array< any >)⇒ Promise< boolean >

<src>abstractProvider.estimateGas(tx: TransactionRequest)⇒ Promise< bigint >

<src>abstractProvider.getAvatar(name: string)⇒ Promise< null | string >

<src>abstractProvider.getBalance(address: AddressLike, blockTag?: BlockTag)⇒ Promise< bigint >

<src>abstractProvider.getBlock(block: BlockTag | string, prefetchTxs?: boolean)⇒ Promise< null | Block >

<src>abstractProvider.getBlockNumber()⇒ Promise< number >

<src>abstractProvider.getCode(address: AddressLike, blockTag?: BlockTag)⇒ Promise< string >

<src>abstractProvider.getFeeData()⇒ Promise< FeeData >

<src>abstractProvider.getLogs(filter: Filter | FilterByBlockHash)⇒ Promise< Array< Log > >

<src>abstractProvider.getNetwork()⇒ Promise< Network >

<src>abstractProvider.getPlugin(name: string)⇒ null | T

<src>abstractProvider.getResolver(name: string)⇒ Promise< null | EnsResolver >

<src>abstractProvider.getStorage(address: AddressLike, position: BigNumberish, blockTag?: BlockTag)⇒ Promise< string >

<src>abstractProvider.getTransaction(hash: string)⇒ Promise< null | TransactionResponse >

<src>abstractProvider.getTransactionCount(address: AddressLike, blockTag?: BlockTag)⇒ Promise< number >

<src>abstractProvider.getTransactionReceipt(hash: string)⇒ Promise< null | TransactionReceipt >

<src>abstractProvider.getTransactionResult(hash: string)⇒ Promise< null | string >

<src>abstractProvider.listenerCount(event?: ProviderEvent)⇒ Promise< number >

<src>abstractProvider.listeners(event?: ProviderEvent)⇒ Promise< Array< Listener > >

<src>abstractProvider.lookupAddress(address: string)⇒ Promise< null | string >

<src>abstractProvider.off(event: ProviderEvent, listener?: Listener)⇒ Promise< this >

<src>abstractProvider.on(event: ProviderEvent, listener: Listener)⇒ Promise< this >

<src>abstractProvider.once(event: ProviderEvent, listener: Listener)⇒ Promise< this >

<src>abstractProvider.pause(dropWhilePaused?: boolean)⇒ void

<src>abstractProvider.removeAllListeners(event?: ProviderEvent)⇒ Promise< this >

<src>abstractProvider.removeListener(event: ProviderEvent, listener: Listener)⇒ Promise< this >

<src>abstractProvider.resolveName(name: string)⇒ Promise< null | string >

<src>abstractProvider.resume()⇒ void

<src>abstractProvider.waitForBlock(blockTag?: BlockTag)⇒ Promise< Block >

<src>abstractProvider.waitForTransaction(hash: string, confirms?: null | number, timeout?: null | number)⇒ Promise< null | TransactionReceipt >

interface AbstractProviderPlugin

PROPERTIES

<src>abstractProviderPlugin.name⇒ stringread-only

METHODS

<src>abstractProviderPlugin.connect(provider: AbstractProvider)⇒ AbstractProviderPlugin

class FilterIdEventSubscriber

inherits from FilterIdSubscriber, Subscriber

A FilterIdSubscriber for receiving contract events.

CREATING INSTANCES

<src>new FilterIdEventSubscriber(provider: JsonRpcApiProvider, filter: EventFilter)

METHODS

<src>filterIdEventSubscriber._emitResults(provider: JsonRpcApiProvider, results: Array< any >)⇒ Promise< void >

<src>filterIdEventSubscriber._recover(provider: AbstractProvider)⇒ Subscriber

<src>filterIdEventSubscriber._subscribe(provider: JsonRpcApiProvider)⇒ Promise< string >

class FilterIdPendingSubscriber

inherits from FilterIdSubscriber, Subscriber

A FilterIdSubscriber for receiving pending transactions events.

METHODS

<src>filterIdPendingSubscriber._emitResults(provider: JsonRpcApiProvider, results: Array< any >)⇒ Promise< void >

<src>filterIdPendingSubscriber._subscribe(provider: JsonRpcApiProvider)⇒ Promise< string >

class FilterIdSubscriber

inherits from Subscriber

Some backends support subscribing to events using a Filter ID.

When subscribing with this technique, the node issues a unique Filter ID. At this point the node dedicates resources to the filter, so that periodic calls to follow up on the Filter ID will receive any events since the last call.

CREATING INSTANCES

<src>new FilterIdSubscriber(provider: JsonRpcApiProvider)

METHODS

<src>filterIdSubscriber._emitResults(provider: AbstractProvider, result: Array< any >)⇒ Promise< void >

<src>filterIdSubscriber._recover(provider: AbstractProvider)⇒ Subscriber

<src>filterIdSubscriber._subscribe(provider: JsonRpcApiProvider)⇒ Promise< string >

<src>filterIdSubscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>filterIdSubscriber.resume()⇒ void

<src>filterIdSubscriber.start()⇒ void

<src>filterIdSubscriber.stop()⇒ void

class OnBlockSubscriber

inherits from Subscriber

CREATING INSTANCES

<src>new OnBlockSubscriber(provider: AbstractProvider)

METHODS

<src>onBlockSubscriber._poll(blockNumber: number, provider: AbstractProvider)⇒ Promise< void >

<src>onBlockSubscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>onBlockSubscriber.resume()⇒ void

<src>onBlockSubscriber.start()⇒ void

<src>onBlockSubscriber.stop()⇒ void

interface PerformActionTransaction

inherits from PreparedTransactionRequest

PROPERTIES

<src>performActionTransaction.from⇒ string

<src>performActionTransaction.to⇒ string

class PollingBlockSubscriber

inherits from Subscriber

PROPERTIES

<src>pollingBlockSubscriber.pollingInterval⇒ number

CREATING INSTANCES

<src>new PollingBlockSubscriber(provider: AbstractProvider)

METHODS

<src>pollingBlockSubscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>pollingBlockSubscriber.resume()⇒ void

<src>pollingBlockSubscriber.start()⇒ void

<src>pollingBlockSubscriber.stop()⇒ void

class PollingEventSubscriber

inherits from Subscriber

CREATING INSTANCES

<src>new PollingEventSubscriber(provider: AbstractProvider, filter: EventFilter)

METHODS

<src>pollingEventSubscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>pollingEventSubscriber.resume()⇒ void

<src>pollingEventSubscriber.start()⇒ void

<src>pollingEventSubscriber.stop()⇒ void

class PollingOrphanSubscriber

inherits from OnBlockSubscriber, Subscriber

CREATING INSTANCES

<src>new PollingOrphanSubscriber(provider: AbstractProvider, filter: OrphanFilter)

METHODS

<src>pollingOrphanSubscriber._poll(blockNumber: number, provider: AbstractProvider)⇒ Promise< void >

class PollingTransactionSubscriber

inherits from OnBlockSubscriber, Subscriber

CREATING INSTANCES

<src>new PollingTransactionSubscriber(provider: AbstractProvider, hash: string)

METHODS

<src>pollingTransactionSubscriber._poll(blockNumber: number, provider: AbstractProvider)⇒ Promise< void >

interface Subscriber

PROPERTIES

<src>subscriber.pollingInterval⇒ number

METHODS

<src>subscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>subscriber.resume()⇒ void

<src>subscriber.start()⇒ void

<src>subscriber.stop()⇒ void

class UnmanagedSubscriber

inherits from Subscriber

PROPERTIES

<src>unmanagedSubscriber.name⇒ string

CREATING INSTANCES

<src>new UnmanagedSubscriber(name: string)

METHODS

<src>unmanagedSubscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>unmanagedSubscriber.resume()⇒ void

<src>unmanagedSubscriber.start()⇒ void

<src>unmanagedSubscriber.stop()⇒ void

Generic long-lived socket provider.

Sub-classing notes

a sub-class MUST call the `_start()` method once connected
a sub-class MUST override the `_write(string)` method
a sub-class MUST call `_processMessage(string)` for each message

class SocketBlockSubscriber

inherits from SocketSubscriber, Subscriber

CREATING INSTANCES

<src>new SocketBlockSubscriber(provider: SocketProvider)

METHODS

<src>socketBlockSubscriber._emit(provider: SocketProvider, message: any)⇒ Promise< void >

class SocketEventSubscriber

inherits from SocketSubscriber, Subscriber

PROPERTIES

<src>socketEventSubscriber.logFilter⇒ EventFilterread-only

CREATING INSTANCES

<src>new SocketEventSubscriber(provider: SocketProvider, filter: EventFilter)

METHODS

<src>socketEventSubscriber._emit(provider: SocketProvider, message: any)⇒ Promise< void >

class SocketPendingSubscriber

inherits from SocketSubscriber, Subscriber

CREATING INSTANCES

<src>new SocketPendingSubscriber(provider: SocketProvider)

METHODS

<src>socketPendingSubscriber._emit(provider: SocketProvider, message: any)⇒ Promise< void >

class SocketProvider

inherits from JsonRpcApiProvider, AbstractProvider

SocketProvider...

CREATING INSTANCES

<src>new SocketProvider(network?: Networkish)

METHODS

<src>socketProvider._getSubscriber(sub: Subscription)⇒ Subscriber

<src>socketProvider._processMessage(message: string)⇒ Promise< void >

<src>socketProvider._register(filterId: number | string, subscriber: SocketSubscriber)⇒ void

<src>socketProvider._send(payload: JsonRpcPayload | Array< JsonRpcPayload >)⇒ Promise< Array< JsonRpcResult | JsonRpcError > >

<src>socketProvider._write(message: string)⇒ Promise< void >

class SocketSubscriber

inherits from Subscriber

PROPERTIES

<src>socketSubscriber.filter⇒ Array< any >read-only

CREATING INSTANCES

<src>new SocketSubscriber(provider: SocketProvider, filter: Array< any >)

METHODS

<src>socketSubscriber._emit(provider: SocketProvider, message: any)⇒ Promise< void >

<src>socketSubscriber._handleMessage(message: any)⇒ void

<src>socketSubscriber.pause(dropWhilePaused?: boolean)⇒ void

<src>socketSubscriber.resume()⇒ void

<src>socketSubscriber.start()⇒ void

<src>socketSubscriber.stop()⇒ void

Subclassing Signer

About Abstract Signer and subclassing

abstract class AbstractSigner

inherits from Signer, Addressable, ContractRunner, NameResolver

PROPERTIES

<src>abstractSigner.provider⇒ Pread-only

CREATING INSTANCES

<src>new AbstractSigner(provider?: P)

METHODS

<src>abstractSigner.call(tx: TransactionRequest)⇒ Promise< string >

<src>abstractSigner.connect(provider: null | Provider)⇒ Signerabstract

<src>abstractSigner.estimateGas(tx: TransactionRequest)⇒ Promise< bigint >

<src>abstractSigner.getAddress()⇒ Promise< string >abstract

<src>abstractSigner.getNonce(blockTag?: BlockTag)⇒ Promise< number >

<src>abstractSigner.populateCall(tx: TransactionRequest)⇒ Promise< TransactionLike < string > >

<src>abstractSigner.populateTransaction(tx: TransactionRequest)⇒ Promise< TransactionLike < string > >

<src>abstractSigner.resolveName(name: string)⇒ Promise< null | string >

<src>abstractSigner.sendTransaction(tx: TransactionRequest)⇒ Promise< TransactionResponse >

<src>abstractSigner.signMessage(message: string | Uint8Array)⇒ Promise< string >abstract

<src>abstractSigner.signTransaction(tx: TransactionRequest)⇒ Promise< string >abstract

<src>abstractSigner.signTypedData(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ Promise< string >abstract

class VoidSigner

inherits from AbstractSigner, Signer

PROPERTIES

<src>voidSigner.address⇒ stringread-only

CREATING INSTANCES

<src>new VoidSigner(address: string, provider?: null | Provider)

METHODS

<src>voidSigner.connect(provider: null | Provider)⇒ VoidSigner

<src>voidSigner.getAddress()⇒ Promise< string >

<src>voidSigner.signMessage(message: string | Uint8Array)⇒ Promise< string >

<src>voidSigner.signTransaction(tx: TransactionRequest)⇒ Promise< string >

<src>voidSigner.signTypedData(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ Promise< string >

ENS Resolver

About ENS Resolver

TYPES

The type of data found during a steip during avatar resolution.

interface AvatarLinkage

An individual record for each step during avatar resolution.

PROPERTIES

<src>avatarLinkage.type⇒ AvatarLinkageType

<src>avatarLinkage.value⇒ string

interface AvatarResult

When resolving an avatar for an ENS name, there are many steps involved, fetching metadata, validating results, et cetera.

Some applications may wish to analyse this data, or use this data to diagnose promblems, so an AvatarResult provides details of each completed step during avatar resolution.

PROPERTIES

<src>avatarResult.linkage⇒ Array< AvatarLinkage >

<src>avatarResult.url⇒ null | string

class BasicMulticoinProviderPlugin

inherits from MulticoinProviderPlugin, AbstractProviderPlugin

A basic multicoin provider plugin.

CREATING INSTANCES

<src>new BasicMulticoinProviderPlugin()

class EnsResolver

A connected object to a resolved ENS name resolver, which can be used to query additional details.

PROPERTIES

<src>ensResolver.address⇒ string

The address of the resolver.

<src>ensResolver.name⇒ string

The name this resolver was resolved against.

<src>ensResolver.provider⇒ AbstractProvider

The connected provider.

CREATING INSTANCES

<src>new EnsResolver(provider: AbstractProvider, address: string, name: string)

METHODS

<src>ensResolver._getAvatar()⇒ Promise< AvatarResult >

When resolving an avatar, there are many steps involved, such fetching metadata and possibly validating ownership of an NFT.

This method can be used to examine each step and the value it was working from.

<src>ensResolver.getAddress(coinType?: number)⇒ Promise< null | string >

Resolves to the address for coinType or null if the provided coinType has not been configured.

<src>ensResolver.getAvatar()⇒ Promise< null | string >

Resolves to the avatar url or null if the avatar is either unconfigured or incorrectly configured (e.g. references an NFT not owned by the address).

If diagnosing issues with configurations, the _getAvatar method may be useful.

<src>ensResolver.getContentHash()⇒ Promise< null | string >

Rsolves to the content-hash or null if unconfigured.

<src>ensResolver.getText(key: string)⇒ Promise< null | string >

Resolves to the EIP-643 text record for key, or null if unconfigured.

<src>ensResolver.supportsWildcard()⇒ Promise< boolean >

Resolves to true if the resolver supports wildcard resolution.

STATIC METHODS

<src>EnsResolver.fromName(provider: AbstractProvider, name: string)⇒ Promise< null | EnsResolver >

Resolve to the ENS resolver for name using provider or null if unconfigured.

<src>EnsResolver.getEnsAddress(provider: Provider)⇒ Promise< string >

abstract class MulticoinProviderPlugin

inherits from AbstractProviderPlugin

A provider plugin super-class for processing multicoin address types.

PROPERTIES

<src>multicoinProviderPlugin.name⇒ stringread-only

CREATING INSTANCES

<src>new MulticoinProviderPlugin(name: string)

METHODS

<src>multicoinProviderPlugin.connect(proivder: Provider)⇒ MulticoinProviderPlugin

<src>multicoinProviderPlugin.decodeAddress(coinType: number, data: BytesLike)⇒ Promise< string >

<src>multicoinProviderPlugin.encodeAddress(coinType: number, address: string)⇒ Promise< string >

<src>multicoinProviderPlugin.supportsCoinType(coinType: number)⇒ boolean

Fallback Provider

Explain all the nitty-gritty about the FallbackProvider.

TYPES

<src>FallbackProviderOptions⇒ { eventQuorum: number , eventWorkers: number , quorum: number }

Additional options to configure a FallbackProvider.

class FallbackProvider

inherits from AbstractProvider, Provider

A Fallback Provider.

PROPERTIES

<src>fallbackProvider.eventQuorum⇒ numberread-only

<src>fallbackProvider.eventWorkers⇒ numberread-only

<src>fallbackProvider.providerConfigs⇒ Array< FallbackProviderState >read-only

<src>fallbackProvider.quorum⇒ numberread-only

CREATING INSTANCES

<src>new FallbackProvider(providers: Array< AbstractProvider | FallbackProviderConfig >, network?: Networkish)

METHODS

<src>fallbackProvider._detectNetwork()⇒ Promise< Network >

<src>fallbackProvider._perform(req: PerformActionRequest)⇒ Promise< T >

<src>fallbackProvider._translatePerform(provider: AbstractProvider, req: PerformActionRequest)⇒ Promise< any >

<src>fallbackProvider.destroy()⇒ Promise< void >

interface FallbackProviderConfig

A configuration entry for how to use a Provider.

PROPERTIES

<src>fallbackProviderConfig.priority⇒ number

<src>fallbackProviderConfig.provider⇒ AbstractProvider

<src>fallbackProviderConfig.stallTimeout⇒ number

<src>fallbackProviderConfig.weight⇒ number