Ethers v5

https://docs.ethers.org/v5
Admin
Ethers.js v5 is a complete and compact library for interacting with the Ethereum blockchain,...
Tokens:297,326
Snippets:2,010
Trust Score:8
Update:6 days ago
Show doc for...
Tokens:
Raw
### AlchemyProvider connection examples

Source: https://docs.ethers.org/v5/api/providers/api-providers

Shows how to create AlchemyProvider instances for mainnet, goerli, and with an API key, plus how to get a WebSocket provider. Note that if no API key is provided, a shared key is used which may be throttled.

```javascript
// Connect to mainnet (homestead)
provider = new AlchemyProvider();

// Connect to the goerli testnet
// (see EtherscanProvider above for other network examples)
provider = new AlchemyProvider("goerli");

// Connect to mainnet with an API key (these are equivalent)
provider = new AlchemyProvider(null, apiKey);
provider = new AlchemyProvider("homestead", apiKey);

// Connect to the Alchemy WebSocket endpoints with a WebSocketProvider
provider = AlchemyProvider.getWebSocketProvider()
```

--------------------------------

### Clone and install ethers.js

Source: https://docs.ethers.org/v5/contributing

Clone the ethers.js repository and install all dependencies. The npm install command runs preinstall, install, postinstall scripts to hoist dependencies, build rat-nests, create a dependency graph, and link rat-nests into each project.

```bash
git clone https://github.com/ethers-io/ethers.js.git
cd ethers.js
npm install
```

--------------------------------

### SimpleStore.bin - Bytecode example

Source: https://docs.ethers.org/v5/cli/asm

Example bytecode file for the SimpleStore contract. It is split into multiple blocks, each optionally prefixed with 0x, and all blocks must have even length. Whitespace is ignored.

```bin
0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
0x5514602457806355241077146030575b60006000fd5b60005460005260206000
0xf35b6024361415601e5760043560005560006000f3
```

--------------------------------

### PocketProvider usage examples

Source: https://docs.ethers.org/v5/api/providers/api-providers

Examples for creating PocketProvider instances: connecting to mainnet, goerli testnet, and mainnet with an application ID or with application ID, secret, and load balancer option.

```javascript
// Connect to mainnet (homestead)
provider = new PocketProvider();

// Connect to the goerli testnet
// (see EtherscanProvider above for other network examples)
provider = new PocketProvider("goerli");

// Connect to mainnet with an Application ID (these are equivalent)
provider = new PocketProvider(null, applicationId);
provider = new PocketProvider("homestead", applicationId);

// Connect to mainnet with an application ID, application secret
// and specify whether to use the load balances
provider = new PocketProvider("homestead", {
    applicationId: applicationId,
    applicationSecretKey: applicationSecretKey,
    loadBalancer: loadBalancer // true or false
});
```

--------------------------------

### InfuraProvider connection examples

Source: https://docs.ethers.org/v5/api/providers/api-providers

Examples of creating an InfuraProvider for mainnet, goerli, with a project ID, with a project secret, and using the WebSocket endpoint.

```javascript
// Connect to mainnet (homestead)
provider = new InfuraProvider();

// Connect to the goerli testnet
// (see EtherscanProvider above for other network examples)
provider = new InfuraProvider("goerli");

// Connect to mainnet with a Project ID (these are equivalent)
provider = new InfuraProvider(null, projectId);
provider = new InfuraProvider("homestead", projectId);

// Connect to mainnet with a Project ID and Project Secret
provider = new InfuraProvider("homestead", {
  projectId: projectId,
  projectSecret: projectSecret
});

// Connect to the INFURA WebSocket endpoints with a WebSocketProvider
provider = InfuraProvider.getWebSocketProvider()
```

--------------------------------

### Wallet creation and usage example

Source: https://docs.ethers.org/v5/api/signer

This example shows how to create a Wallet from a mnemonic or private key, access addresses and keys, sign messages and transactions, connect to a provider, and send ether. It includes comments explaining the behavior of mnemonic availability and the connect method.

```javascript
// Create a wallet instance from a mnemonic...
mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
walletMnemonic = Wallet.fromMnemonic(mnemonic)

// ...or from a private key
walletPrivateKey = new Wallet(walletMnemonic.privateKey)

walletMnemonic.address === walletPrivateKey.address
// true

// The address as a Promise per the Signer API
await walletMnemonic.getAddress()
// '0x71CB05EE1b1F506fF321Da3dac38f25c0c9ce6E1'

// A Wallet address is also available synchronously
walletMnemonic.address
// '0x71CB05EE1b1F506fF321Da3dac38f25c0c9ce6E1'

// The internal cryptographic components
walletMnemonic.privateKey
// '0x1da6847600b0ee25e9ad9a52abbd786dd2502fa4005dd5af9310b7cc7a3b25db'
walletMnemonic.publicKey
// '0x04b9e72dfd423bcf95b3801ac93f4392be5ff22143f9980eb78b3a860c4843bfd04829ae61cdba4b3b1978ac5fc64f5cc2f4350e35a108a9c9a92a81200a60cd64'

// The wallet mnemonic
walletMnemonic.mnemonic
// {
//   locale: 'en',
//   path: "m/44'/60'/0'/0/0",
//   phrase: 'announce room limb pattern dry unit scale effort smooth jazz weasel alcohol'
// }

// Note: A wallet created with a private key does not
// have a mnemonic (the derivation prevents it)
walletPrivateKey.mnemonic
// null

// Signing a message
await walletMnemonic.signMessage("Hello World")
// '0x14280e5885a19f60e536de50097e96e3738c7acae4e9e62d67272d794b8127d31c03d9cd59781d4ee31fb4e1b893bd9b020ec67dfa65cfb51e2bdadbb1de26d91c'

tx = {
  to: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  value: utils.parseEther("1.0")
}

// Signing a transaction
await walletMnemonic.signTransaction(tx)
// '0xf865808080948ba1f109551bd432803012645ac136ddd64dba72880de0b6b3a7640000801ca0918e294306d177ab7bd664f5e141436563854ebe0a3e523b9690b4922bbb52b8a01181612cec9c431c4257a79b8c9f0c980a2c49bb5a0e6ac52949163eeb565dfc'

// The connect method returns a new instance of the
// Wallet connected to a provider
wallet = walletMnemonic.connect(provider)

// Querying the network
await wallet.getBalance();
// { BigNumber: "6846" }
await wallet.getTransactionCount();
// 3

// Sending ether
await wallet.sendTransaction(tx)
// {
//   accessList: [],
//   chainId: 123456,
//   confirmations: 0,
//   data: '0x',
//   from: '0x46E0726Ef145d92DEA66D38797CF51901701926e',
//   gasLimit: { BigNumber: "21000" },
//   gasPrice: null,
//   hash: '0x1c4913f6e06a8b48443dbe3169acb6701b558ed6d3b478723eb6b137d2418792',
//   maxFeePerGas: { BigNumber: "1500000014" },
//   maxPriorityFeePerGas: { BigNumber: "1500000000" },
//   nonce: 5,
//   r: '0xb58e9234bf734f5bab14634ca21e35c3fa163562930d782424e78120cfcc9b8f',
//   s: '0x690c4b1c3d2b6e519340b2f0f3fc80ccea47e3c2a077f9771aaa2e1d7552aa24',
//   to: '0x8ba1f109551bD432803012645Ac136ddd64DBA72',
//   type: 2,
//   v: 0,
//   value: { BigNumber: "1000000000000000000" },
//   wait: [Function (anonymous)]
// }
```

--------------------------------

### SimpleStore.asm example

Source: https://docs.ethers.org/v5/single-page

Example assembler input file defining a SimpleStore contract with getValue and setValue functions. Uses assembler defines for sighash and checksum, and includes error handling for non-payable calls and invalid signatures.

```asm
; SimpleStore (uint)
; Set the initial value of 42
sstore(0, 42)
; Init code to deploy myContract
codecopy(0, $myContract, #myContract)
return(0, #myContract)
@myContract {
    ; Non-payable
    jumpi($error, callvalue)
    ; Get the Sighash
    shr({{= 256 - 32 }}, calldataload(0))
    ; getValue()
    dup1 {{= sighash("getValue()") }}
    jumpi($getValue, eq)
    ; setValue(uint)
    dup1 {{= sighash("setValue(uint)") }}
    jumpi($setValue, eq)
    ; No matching signature
    @error: revert(0, 0)
    @getValue:
        mstore(0, sload(0))
        return (0, 32)
    @setValue:
        ; Make sure we have exactly a uint
        jumpi($error, iszero(eq(calldatasize, 36)))
        ; Store the value
        sstore(0, calldataload(4))
        return (0, 0)
    ; There is no *need* for the PUSH32, it just makes
    ; decompiled code look nicer
    @checksum[ {{= (defines.checksum ? concat([ Opcode.from("PUSH32"), id(myContract.source) ]): "0x") }} ]
}
```

--------------------------------

### SimpleStore.asm - Ethers ASM dialect example

Source: https://docs.ethers.org/v5/cli/asm

Example assembly source file for a simple storage contract. It sets an initial value, deploys the contract code, and includes functions getValue() and setValue(uint). Uses assembler defines and sighash macros.

```asm
; SimpleStore (uint)
; Set the initial value of 42
sstore(0, 42)
; Init code to deploy myContract
codecopy(0, $myContract, #myContract)
return(0, #myContract)
@myContract {
    ; Non-payable
    jumpi($error, callvalue)
    ; Get the Sighash
    shr({{= 256 - 32 }}, calldataload(0))
    ; getValue()
    dup1
    {{= sighash("getValue()") }}
    jumpi($getValue, eq)
    ; setValue(uint)
    dup1
    {{= sighash("setValue(uint)") }}
    jumpi($setValue, eq)
    ; No matching signature
    @error:
    revert(0, 0)
    @getValue:
    mstore(0, sload(0))
    return (0, 32)
    @setValue:
    ; Make sure we have exactly a uint
    jumpi($error, iszero(eq(calldatasize, 36)))
    ; Store the value
    sstore(0, calldataload(4))
    return (0, 0)
    ; There is no *need* for the PUSH32, it just makes
    ; decompiled code look nicer
    @checksum[ {{= (defines.checksum ? concat([ Opcode.from("PUSH32"), id(myContract.source) ]): "0x") }} ]
}
```

--------------------------------

### EtherscanProvider connection examples

Source: https://docs.ethers.org/v5/api/providers/api-providers

Shows how to create an EtherscanProvider for mainnet, goerli testnet (using name or chain ID), and with an API key. The goerli examples are equivalent, and the network object can be obtained via ethers.providers.getNetwork.

```javascript
// Connect to mainnet (homestead)
provider = new EtherscanProvider();

// Connect to goerli testnet (these are equivalent)
provider = new EtherscanProvider("goerli");
provider = new EtherscanProvider(5);

network = ethers.providers.getNetwork("goerli");
// {
//   chainId: 5,
//   ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
//   name: 'goerli'
// }

provider = new EtherscanProvider(network);

// Connect to mainnet (homestead) with an API key
provider = new EtherscanProvider(null, apiKey);
provider = new EtherscanProvider("homestead", apiKey);
```

--------------------------------

### InfuraProvider connection examples

Source: https://docs.ethers.org/v5/single-page

Examples for connecting to different networks, using a Project ID, Project Secret, and WebSocket provider. Note that if no apiKey is provided, a shared API key is used which may result in reduced performance and throttled requests.

```javascript
// Connect to mainnet (homestead)
provider = new InfuraProvider();

// Connect to the goerli testnet
// (see EtherscanProvider above for other network examples)
provider = new InfuraProvider("goerli");

// Connect to mainnet with a Project ID (these are equivalent)
provider = new InfuraProvider(null, projectId);
provider = new InfuraProvider("homestead", projectId);

// Connect to mainnet with a Project ID and Project Secret
provider = new InfuraProvider("homestead", { projectId: projectId, projectSecret: projectSecret });

// Connect to the INFURA WebSocket endpoints with a WebSocketProvider
provider = InfuraProvider.getWebSocketProvider()
```

--------------------------------

### Install ethers via npm

Source: https://docs.ethers.org/v5/getting-started

Installs the ethers umbrella package, which provides all classes and functions. Use this for most projects.

```bash
npm install --save ethers
```

--------------------------------

### AnkrProvider usage examples

Source: https://docs.ethers.org/v5/api/providers/api-providers

Examples for creating AnkrProvider instances: connecting to mainnet, Polygon (matic), and mainnet with an API key.

```javascript
// Connect to mainnet (homestead)
provider = new AnkrProvider();

// Connect to polygont
// (see EtherscanProvider above for other network examples)
provider = new AnkrProvider("matic");

// Connect to mainnet with an API Key (these are equivalent)
provider = new AnkrProvider(null, apiKey);
provider = new AnkrProvider("homestead", apiKey);
```

--------------------------------

### VoidSigner Pre-flight Example

Source: https://docs.ethers.org/v5/api/signer

This example shows how to create a VoidSigner and use it with a contract to pre-flight a transfer call, checking for reverts without a private key. The first call succeeds, while the second fails due to insufficient balance.

```javascript
address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
signer = new ethers.VoidSigner(address, provider)

// The DAI token contract
abi = [
  "function balanceOf(address) view returns (uint)",
  "function transfer(address, uint) returns (bool)"
]
contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)

// Get the number of tokens for this account
tokens = await contract.balanceOf(signer.getAddress())
// { BigNumber: "19862540059122458201631" }


// Pre-flight (check for revert) on DAI from the signer
//
// Note: We do not have the private key at this point, this
// simply allows us to check what would happen if we
// did. This can be useful to check before prompting
// a request in the UI
//

// This will pass since the token balance is available
await contract.callStatic.transfer("donations.ethers.eth", tokens)
// true

// This will fail since it is greater than the token balance
await contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
// [Error: call revert exception; VM Exception while processing transaction: reverted with reason string "Dai/insufficient-balance"
// [ See: https://links.ethers.org/v5-errors-CALL_EXCEPTION ]] {
//   address: 'dai.tokens.ethers.eth',
//   args: [
//     'donations.ethers.eth',
//     { BigNumber: "19862540059122458201632" }
//   ],
//   code: 'CALL_EXCEPTION',
//   data: '0x08c379a0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000184461692f696e73756666696369656e742d62616c616e63650000000000000000',
//   errorArgs: [
//     'Dai/insufficient-balance'
//   ],
//   errorName: 'Error',
//   errorSignature: 'Error(string)',
//   method: 'transfer(address,uint256)',
//   reason: 'Dai/insufficient-balance',
//   transaction: {
//     data: '0xa9059cbb000000000000000000000000643aa0a61eadcc9cc202d1915d942d35d005400c000000000000000000000000000000000000000000000434c01dc386406c8e20',
//     from: '0x8ba1f109551bD432803012645Ac136ddd64DBA72',
//     to: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
//   }
// }
```

--------------------------------

### getCreate2Address example

Source: https://docs.ethers.org/v5/api/utils/address

Computes the contract address from a CREATE2 call using the given from, salt, and initCodeHash. The example uses from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72", salt = "0x7c5ea36004851c764c44143b1dcb59679b11c9a68e5f41497f6cf3d480715331", and initCode = "0x6394198df16000526103ff60206004601c335afa6040516060f3", with initCodeHash = keccak256(initCode), producing '0x533ae9d683B10C02EbDb05471642F85230071FC3'.

```javascript
const from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
const salt = "0x7c5ea36004851c764c44143b1dcb59679b11c9a68e5f41497f6cf3d480715331";
const initCode = "0x6394198df16000526103ff60206004601c335afa6040516060f3";
const initCodeHash = keccak256(initCode);
getCreate2Address(from, salt, initCodeHash);
// '0x533ae9d683B10C02EbDb05471642F85230071FC3'
```

--------------------------------

### getContractAddress example

Source: https://docs.ethers.org/v5/api/utils/address

Computes the contract address that would result from a transaction with the given from and nonce. The example uses from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72" and nonce = 5, producing the address '0x082B6aC9e47d7D83ea3FaBbD1eC7DAba9D687b36'.

```javascript
const from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
const nonce = 5;
getContractAddress({ from, nonce });
// '0x082B6aC9e47d7D83ea3FaBbD1eC7DAba9D687b36'
```

--------------------------------

### Serve documentation locally

Source: https://docs.ethers.org/v5/contributing

Starts a built-in web server to preview the documentation locally. Remember to flush browser caches after rebuilding the docs.

```bash
/home/ricmoo/ethers.js> npm run serve-docs
```

--------------------------------

### Get Network with provider.getNetwork()

Source: https://docs.ethers.org/v5/api/providers/provider

Returns the Network this Provider is connected to. The example shows the expected output for the Ethereum mainnet (homestead).

```javascript
await provider.getNetwork() // {
// chainId: 1,
// ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
// name: 'homestead'
// }
```

--------------------------------

### Get Block Number with provider.getBlockNumber()

Source: https://docs.ethers.org/v5/api/providers/provider

Returns the block number (or height) of the most recently mined block. The example shows a sample output.

```javascript
await provider.getBlockNumber() // 16987688
```

--------------------------------

### Get Gas Price with provider.getGasPrice()

Source: https://docs.ethers.org/v5/api/providers/provider

Returns a best guess of the Gas Price to use in a transaction. The example shows the raw wei value and how to format it to gwei using utils.formatUnits.

```javascript
// The gas price (in wei)...
gasPrice = await provider.getGasPrice() // { BigNumber: "23238878592" }

// ...often this gas price is easier to understand or
// display to the user in gwei
utils.formatUnits(gasPrice, "gwei") // '23.238878592'
```

--------------------------------

### Example command line with flag, option, and arguments

Source: https://docs.ethers.org/v5/cli/plugin

Shows a sample command line for the ethers CLI. The --account option takes a value (wallet.json), --yes is a flag, and the remaining tokens are arguments.

```bash
/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0 # An Option ----------^ ^ ^ # - name = "account" | | # - value = "wallet.json" | | # A Flag -----------------------------------+ | # - name = "yes" | # - value = true | # Arguments ------------------------------------+ # - count = 3 # - [ "send", "ricmoo.eth", "1.0" ]
```

--------------------------------

### Get ENS resolver with provider.getResolver

Source: https://docs.ethers.org/v5/api/providers/provider

Returns an EnsResolver instance for the given ENS name, which can be used to query specific entries. The comment indicates that examples of using this object are provided below in the Resolver section.

```javascript
const resolver = await provider.getResolver("ricmoo.eth");
```

--------------------------------

### Get storage at a position with provider.getStorageAt

Source: https://docs.ethers.org/v5/single-page

Returns the Bytes32 value of the position pos at address addr, as of the blockTag. The example shows a call to getStorageAt with a domain name and position 0, returning a hex string.

```javascript
provider.getStorageAt( addr , pos [ , blockTag = latest ] ) ⇒ Promise< string< DataHexString > >
```

```javascript
await provider.getStorageAt("registrar.firefly.eth", 0) // '0x000000000000000000000000314159265dd8dbb310642f98f50c066173c1259b'
```

--------------------------------

### ethers init FILENAME

Source: https://docs.ethers.org/v5/cli/ethers

Create a new JSON wallet file.

```APIDOC
## ethers init FILENAME

### Description
Create a new JSON wallet and save it to the specified filename.

### Usage
`ethers init FILENAME [--force]`

### Parameters
- **FILENAME** (string) - Required - The filename for the new wallet.

### Options
- **--force** - Overwrite any existing files.

### Example
`ethers init wallet.json`

```

--------------------------------

### Get Fee Data with provider.getFeeData()

Source: https://docs.ethers.org/v5/api/providers/provider

Returns the current recommended FeeData to use in a transaction. For EIP-1559 transactions, use maxFeePerGas and maxPriorityFeePerGas; for legacy transactions, use gasPrice. The example shows the returned object and formatting maxFeePerGas to gwei.

```javascript
// The gas price (in wei)...
feeData = await provider.getFeeData() // {
// gasPrice: { BigNumber: "23238878592" },
// lastBaseFeePerGas: { BigNumber: "23169890320" },
// maxFeePerGas: { BigNumber: "47839780640" },
// maxPriorityFeePerGas: { BigNumber: "1500000000" }
// }

// ...often these values are easier to understand or
// display to the user in gwei
utils.formatUnits(feeData.maxFeePerGas, "gwei") // '47.83978064'
```

--------------------------------

### Example Human-Readable ABI

Source: https://docs.ethers.org/v5/api/utils/abi/fragments

Shows a Human-Readable ABI array with constructor, functions, event, and error signatures. Tuples can be specified with `tuple(...)` or bare parentheses. When parsing, inferred properties are injected (e.g., a payable method gets `constant` set to false).

```javascript
const ABI = [
  // Constructor
  "constructor(address ens)",

  // Constant functions (pure or view)
  "function balanceOf(address owner) view returns (uint)",

  // State-mutating functions (payable or non-payable)
  "function mint(uint amount) payable",
  "function transfer(address to, uint amount) returns (bool)",

  // Events
  "event Transfer(address indexed from, address indexed to, uint amount)",

  // Errors
  "error InsufficientFunds(address from, uint balance)",
]
```

--------------------------------

### Get transaction by hash with provider.getTransaction

Source: https://docs.ethers.org/v5/single-page

Fetches a transaction by its hash using the provider. The returned object includes fields such as blockHash, blockNumber, chainId, confirmations, creates, data, from, gasLimit, gasPrice, hash, nonce, r, s, to, transactionIndex, type, v, value, and wait. The example shows a transaction that creates a contract (to is null) and includes the contract creation data.

```javascript
await provider.getTransaction("0x5b73e239c55d790e3c9c3bbb84092652db01bb8dbf49ccc9e4a318470419d9a0");
```

--------------------------------

### Base64 encode examples

Source: https://docs.ethers.org/v5/api/utils/encoding

Encodes a hex string or byte array to a base-64 string. Both examples return 'EjQ='.

```javascript
base64.encode("0x1234"); // 'EjQ='
```

```javascript
base64.encode([ 0x12, 0x34 ]); // 'EjQ='
```

--------------------------------

### CloudflareProvider connection example

Source: https://docs.ethers.org/v5/api/providers/api-providers

Creates a CloudflareProvider connected to mainnet (homestead).

```javascript
// Connect to mainnet (homestead)
provider = new CloudflareProvider();
```

--------------------------------

### Base58 encode examples

Source: https://docs.ethers.org/v5/api/utils/encoding

Encodes a hex string or byte array to a base-58 string. Both examples return 'TzMhH'.

```javascript
base58.encode("0x12345678"); // 'TzMhH'
```

```javascript
base58.encode([ 0x12, 0x34, 0x56, 0x78 ]); // 'TzMhH'
```

--------------------------------

### Install @ethersproject/shims

Source: https://docs.ethers.org/v5/cookbook/react-native

Install the ethers.js shims package to provide missing functionality in React Native. Run this in your project directory.

```bash
/home/ricmoo/my-react-project> npm install @ethersproject/shims --save
```

--------------------------------

### Prepare distribution files

Source: https://docs.ethers.org/v5/single-page

Commands to prepare the distribution files: clean generated files, re-install dependencies, and update the version.

```bash
npm run clean
```

```bash
npm install
```

```bash
npm run update-version
```

--------------------------------

### Create a JSON wallet and fund it on Goerli

Source: https://docs.ethers.org/v5/single-page

Creates a new JSON wallet with ethers init and then funds the resulting address on the Goerli testnet. The init command prompts for a password, encrypts the wallet, and saves it to the specified file. The fund command sends testnet ether and prints the transaction hash.

```shell
/home/ethers> ethers init wallet.json
Creating a new JSON Wallet - wallet.json
Keep this password and file SAFE!! If lost or forgotten it CANNOT be recovered, by ANYone, EVER.
Choose a password: ******
Confirm password: ******
Encrypting... 100%
New account address: 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
Saved: wallet.json
# If you are planning to try out the Goerli testnet...
/home/ethers> ethers --network goerli fund 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
Transaction Hash: 0x8dc55b8f8dc8076acded97f9e3ed7d6162460c0221e2769806006b6d7d1156e0
```

--------------------------------

### formatUnits examples

Source: https://docs.ethers.org/v5/api/utils/display-logic

Converts a BigNumberish value to a string with the specified unit or decimal count. The examples show various unit specifications and their outputs.

```javascript
const oneGwei = BigNumber.from("1000000000");
const oneEther = BigNumber.from("1000000000000000000");

formatUnits(oneGwei, 0); // '1000000000'
formatUnits(oneGwei, "gwei"); // '1.0'
formatUnits(oneGwei, 9); // '1.0'
formatUnits(oneEther); // '1.0'
formatUnits(oneEther, 18); // '1.0'
```

--------------------------------

### Plugin.getHelp (static)

Source: https://docs.ethers.org/v5/cli/plugin

Static method that subclasses should implement to generate the help screen.

```APIDOC
## Plugin.getHelp (static)

### Description
Each subclass should implement this static method which is used to generate the help screen.

### Method
getHelp (static)

### Parameters
None

### Returns
Help
```

--------------------------------

### Provider Event Listener Example

Source: https://docs.ethers.org/v5/single-page

Shows how to use provider.on and provider.once with various event types: block, transaction hash, log filter, topic-set filter, pending, and error. The filter uses an address and topics array; the topic-set filter is an array of topic-sets and matches any address. The example includes comments explaining the behavior.

```javascript
provider.on("block", (blockNumber) => {
  // Emitted on every block change
})

provider.once(txHash, (transaction) => {
  // Emitted when the transaction has been mined
})

// This filter could also be generated with the Contract or
// Interface API. If address is not specified, any address
// matches and if topics is not specified, any log matches
filter = {
  address: "dai.tokens.ethers.eth",
  topics: [
    utils.id("Transfer(address,address,uint256)")
  ]
}

provider.on(filter, (log, event) => {
  // Emitted whenever a DAI token transfer occurs
})

// Notice this is an array of topic-sets and is identical to
// using a filter with no address (i.e. match any address)
topicSets = [
  utils.id("Transfer(address,address,uint256)"),
  null,
  [
    hexZeroPad(myAddress, 32),
    hexZeroPad(myOtherAddress, 32)
  ]
]

provider.on(topicSets, (log) => {
  // Emitted any token is sent TO either address
})

provider.on("pending", (tx) => {
  // Emitted when any new pending transaction is noticed
});

provider.on("error", (tx) => {
  // Emitted when any error occurs
});
```

--------------------------------

### Base64 decode example

Source: https://docs.ethers.org/v5/api/utils/encoding

Decodes a base-64 string to a Uint8Array. Example: base64.decode("EjQ=") returns Uint8Array [ 18, 52 ].

```javascript
base64.decode("EjQ="); // Uint8Array [ 18, 52 ]
```

--------------------------------

### getTransactionCount example

Source: https://docs.ethers.org/v5/api/providers/provider

Returns the number of transactions the address has sent, which is required as the nonce for the next transaction. The example shows the count for ricmoo.eth as 47.

```javascript
await provider.getTransactionCount("ricmoo.eth"); // 47
```

--------------------------------

### VoidSigner Pre-flight Example

Source: https://docs.ethers.org/v5/single-page

Example usage of VoidSigner for pre-flight checks using contract static calls to simulate transactions without a private key.

```APIDOC
## VoidSigner Pre-flight Example

### Description
Demonstrates using a VoidSigner with a contract to perform pre-flight checks (simulating transactions) to verify if a transaction would succeed or revert, without needing the private key.

### Usage
```javascript
address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
signer = new ethers.VoidSigner(address, provider)

// The DAI token contract
abi = [
  "function balanceOf(address) view returns (uint)",
  "function transfer(address, uint) returns (bool)"
]
contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)

// Get the number of tokens for this account
tokens = await contract.balanceOf(signer.getAddress())
// { BigNumber: "19862540059122458201631" }

// Pre-flight (check for revert) on DAI from the signer
// Note: We do not have the private key at this point, this
// simply allows us to check what would happen if we
// did. This can be useful to check before prompting
// a request in the UI

// This will pass since the token balance is available
await contract.callStatic.transfer("donations.ethers.eth", tokens)
// true

// This will fail since it is greater than the token balance
await contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
// [Error: call revert exception; VM Exception while processing transaction: reverted with reason string "Dai/insufficient-balance" [ See: https://links.ethers.org/v5-errors-CALL_EXCEPTION ]]
```

### Response
#### Success Response
- **true** (boolean) - Indicates the pre-flight check passed.

#### Error Response
- **Error** - Call revert exception with reason string "Dai/insufficient-balance" when the transfer amount exceeds the balance.
```

--------------------------------

### Deploy a Contract with ContractFactory

Source: https://docs.ethers.org/v5/single-page

Shows the full workflow: create a ContractFactory with an ABI that includes the constructor, deploy with constructor arguments, access the deployment transaction, wait for mining, and call a contract method. The contract address is available immediately but interactions must wait until the transaction is mined.

```javascript
// If your contract constructor requires parameters, the ABI
// must include the constructor
const abi = [
    "constructor(address owner, uint256 initialValue)",
    "function value() view returns (uint)"
];

// The factory we use for deploying contracts
factory = new ContractFactory(abi, bytecode, signer)

// Deploy an instance of the contract
contract = await factory.deploy("ricmoo.eth", 42);

// The address is available immediately, but the contract
// is NOT deployed yet
contract.address
// '0x00777F1b1439BDc7Ad1d4905A38Ec9f5400e0e26'

// The transaction that the signer sent to deploy
contract.deployTransaction
// {
//   accessList: [],
//   chainId: 123456,
//   confirmations: 0,
//   data: '0x608060405234801561001057600080fd5b5060405161012e38038061012e8339818101604052604081101561003357600080fd5b81019080805190602001909291908051906020019092919050505081600160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff1602179055508060008190555050506088806100a66000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80633fa4f24514602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000805490509056fea2646970667358221220926465385af0e8706644e1ff3db7161af699dc063beaadd55405f2ccd6478d7564736f6c634300070400330000000000000000000000005555763613a12d8f3e73be831dff8598089d3dca000000000000000000000000000000000000000000000000000000000000002a',
//   from: '0x46E0726Ef145d92DEA66D38797CF51901701926e',
//   gasLimit: { BigNumber: "129862" },
//   gasPrice: null,
//   hash: '0x293aeb5aaa782c45d56aa13e67c8dabe5a34726c68539302401c15a1699074fa',
//   maxFeePerGas: { BigNumber: "1500000014" },
//   maxPriorityFeePerGas: { BigNumber: "1500000000" },
//   nonce: 0,
//   r: '0x6708733f3523a5efc1a5bee891a3020c1d0a622f03ccaa437763241550d93ac7',
//   s: '0x3065f4437666753b4216bf8518e5c6221d0cf8f86b57857ac268c128a5c2d53c',
//   to: null,
//   type: 2,
//   v: 0,
//   value: { BigNumber: "0" },
//   wait: [Function (anonymous)]
// }

// Wait until the transaction is mined (i.e. contract is deployed)
// - returns the receipt
// - throws on failure (the reciept is on the error)
await contract.deployTransaction.wait()
// {
//   blockHash: '0x14b2744b8a923827c35827aa47c99942be21c94da4fe2e03451a662e3bd0dbe6',
//   blockNumber: 60328,
//   byzantium: true,
//   confirmations: 1,
//   contractAddress: '0x00777F1b1439BDc7Ad1d4905A38Ec9f5400e0e26',
//   cumulativeGasUsed: { BigNumber: "129862" },
//   effectiveGasPrice: { BigNumber: "1500000007" },
//   events: [],
//   from: '0x46E0726Ef145d92DEA66D38797CF51901701926e',
//   gasUsed: { BigNumber: "129862" },
//   logs: [],
//   logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
//   status: 1,
//   to: null,
//   transactionHash: '0x293aeb5aaa782c45d56aa13e67c8dabe5a34726c68539302401c15a1699074fa',
//   transactionIndex: 0,
//   type: 2
// }

// Now the contract is safe to interact with
await contract.value()
// { BigNumber: "42" }
```
Tokens:
Raw