@spec batch([t_batch_request()], Keyword.t()) ::
  {:ok, ok: term(), error: term()} | {:error, term()}

Combines multiple requests and make a batch json RPC request.

It returns {:ok, results} in case of success or {:error, reason} in case of RPC failure.

Each action will have an entry in the results. Each entry is again a tuple and either {:ok, result} or {:error, reason} in case of action failure.

Checkout Batching Requests sections in Ethers module for more examples.

Parameters

• requests: A list of requests to execute.
• opts: RPC related options. (No account and block options are accepted in batch)

Action

An action can be in either of the following formats.

• {action_name_atom, action_data, action_overrides}
• {action_name_atom, action_data}
• action_name_atom

Examples

Ethers.batch([
  {:call, WETH.name()},
  {:call, WETH.symbol(), to: "[WETH ADDRESS]"},
  {:send_transaction, WETH.transfer("[RECEIVER]", 1000), from: "[SENDER]"},
  :current_block_number
])
{:ok, [ok: "Weapped Ethereum", ok: "WETH", ok: "0xhash...", ok: 182394532]}

@spec batch!([t_batch_request()], Keyword.t()) :: [ok: term(), error: term()]

Same as Ethers.batch/2 but raises on error.

@spec blob_base_fee(Keyword.t()) ::
  {:ok, non_neg_integer()} | {:error, reason :: term()}

Returns the current blob base fee from the RPC API

@spec blob_base_fee!(Keyword.t()) :: non_neg_integer() | no_return()

Same as Ethers.blob_base_fee/1 but raises on error.

@spec call(Ethers.TxData.t(), Keyword.t()) ::
  {:ok, [term()]} | {:ok, term()} | {:error, term()}

Makes an eth_call to with the given Ethers.TxData struct and overrides. It then parses the response using the selector in the TxData struct.

Overrides and Options

Other than what stated below, any other option given in the overrides keyword list will be merged with the map that the RPC client will receive.

• :to: Indicates recipient address. (Contract address in this case)
• :block: The block number or block alias. Defaults to latest
• :rpc_client: The RPC Client to use. It should implement ethereum jsonRPC API. default: Ethereumex.HttpClient
• :rpc_opts: Extra options to pass to rpc_client. (Like timeout, Server URL, etc.)
• :state_overrides: Execute the call against a modified chain state (spoofed balances, injected contract code, rewritten storage slots, ...). See Ethers.StateOverride for the accepted structure. Not supported in Ethers.batch/2.

Return structure

For contract functions which return a single value (e.g. function test() returns (uint)) this returns {:ok, value} and for the functions which return multiple values it will return {:ok, [value0, value1]} (A list).

Examples

Ethers.Contract.ERC20.total_supply() |> Ethers.call(to: "0xa0b...ef6")
{:ok, 100000000000000}

@spec call!(Ethers.TxData.t(), Keyword.t()) :: term() | no_return()

Same as Ethers.call/2 but raises on error.

@spec chain_id!(Keyword.t()) :: non_neg_integer() | no_return()

Same as Ethers.chain_id/1 but raises on error.

@spec create_access_list(map() | Ethers.TxData.t(), Keyword.t()) ::
  {:ok, map()} | {:error, term()}

Makes an eth_createAccessList rpc call with the given parameters and overrides.

Simulates the transaction and returns the list of addresses and storage slots it accesses, in the format transaction functions accept as the :access_list override — so the result can be fed straight back into Ethers.send_transaction/2 (with an EIP-2930 or later transaction type) to reduce gas usage of the transaction.

Also works with Ethers.batch/2 as {:create_access_list, tx_data, overrides}.

Overrides and Options

• :to: Indicates recipient address. (Contract address in this case)
• :block: The block number or block alias. Defaults to latest
• :rpc_client: The RPC Client to use. It should implement ethereum jsonRPC API. default: Ethereumex.HttpClient
• :rpc_opts: Extra options to pass to rpc_client. (Like timeout, Server URL, etc.)

Returns

{:ok, result} where result is a map with these keys:

• :access_list: The generated access list.
• :gas_used: Gas consumed by the simulated transaction (with the access list applied).
• :error: Only present when the simulated transaction reverts; holds the node's error message. The access list is still generated in that case.

Examples

MyContract.some_function() |> Ethers.create_access_list(from: address)
{:ok, %{access_list: [[<<_::160>>, [<<_::256>>, ...]], ...], gas_used: 25000}}

@spec create_access_list!(map() | Ethers.TxData.t(), Keyword.t()) ::
  map() | no_return()

Same as Ethers.create_access_list/2 but raises on error.

@spec current_block_number(Keyword.t()) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the current block number of the blockchain.

@spec current_gas_price(Keyword.t()) :: {:ok, non_neg_integer()}

Returns the current gas price from the RPC API

@spec deploy(atom() | binary(), Keyword.t()) ::
  {:ok, Ethers.Types.t_hash()} | {:error, term()}

Deploys a contract to the blockchain.

This will return the transaction hash for the deployment transaction. To get the address of your deployed contract, use Ethers.deployed_address/2.

To deploy a cotract you must have the binary related to it. It can either be a part of the ABI File you have or as a separate file.

Parameters

• contract_module_or_binary: Either the contract module which was already loaded or the compiled binary of the contract. The binary MUST be hex encoded.
• overrides: A keyword list containing options and overrides.
  • :encoded_constructor: Hex encoded value for constructor parameters. (See constructor function of the contract module)
  • All other options from Ethers.send_transaction/2

@spec deployed_address(binary(), Keyword.t()) ::
  {:ok, Ethers.Types.t_address()}
  | {:error, :no_contract_address | :transaction_not_found | term()}

Returns the address of the deployed contract if the deployment is finished and successful

Parameters

• tx_hash: Hash of the Transaction which created a contract.
• opts: RPC and account options.

@spec estimate_fees(Keyword.t()) ::
  {:ok,
   %{
     max_fee_per_gas: non_neg_integer(),
     max_priority_fee_per_gas: non_neg_integer()
   }}
  | {:error, term()}

Estimates EIP-1559 fees (max_fee_per_gas and max_priority_fee_per_gas) based on recent blocks using Ethers.fee_history/4.

The priority fee is the median of the recent blocks' priority fees sampled at the percentile selected by :speed, and the max fee adds headroom for base fee growth:

max_priority_fee_per_gas = median(reward at percentile over recent blocks)
max_fee_per_gas          = 2 * next_block_base_fee + max_priority_fee_per_gas

This is also what transaction auto-fill uses to price EIP-1559 transactions when the fees are not explicitly provided (with a fallback to the legacy gas price based estimation on RPC clients without eth_feeHistory support).

Options

• :speed: :slow, :standard or :fast — samples priority fees at the 25th, 50th or 75th percentile respectively. Also accepts a raw percentile number (0-100). (default :standard)
• :block_count: Number of recent blocks to sample. (default 10)
• :rpc_client / :rpc_opts: RPC related options.

Returns

• {:ok, %{max_fee_per_gas: integer, max_priority_fee_per_gas: integer}} on success.
• {:error, :invalid_speed} if :speed is not recognized.
• {:error, :no_fee_history_data} if the node returned no usable fee history.
• {:error, reason} on RPC failures.

@spec estimate_fees!(Keyword.t()) ::
  %{
    max_fee_per_gas: non_neg_integer(),
    max_priority_fee_per_gas: non_neg_integer()
  }
  | no_return()

Same as Ethers.estimate_fees/1 but raises on error.

@spec estimate_gas(map(), Keyword.t()) :: {:ok, non_neg_integer()} | {:error, term()}

Makes an eth_estimate_gas rpc call with the given parameters and overrides.

Overrides and Options

• :to: Indicates recipient address. (Contract address in this case)
• :block: The block number or block alias. Only sent to the RPC server when :state_overrides are given. Defaults to latest
• :rpc_client: The RPC Client to use. It should implement ethereum jsonRPC API. default: Ethereumex.HttpClient
• :rpc_opts: Extra options to pass to rpc_client. (Like timeout, Server URL, etc.)
• :state_overrides: Estimate against a modified chain state (spoofed balances, injected contract code, rewritten storage slots, ...). See Ethers.StateOverride for the accepted structure. Not supported in Ethers.batch/2.

Ethers.Contract.ERC20.transfer("0xff0...ea2", 1000) |> Ethers.estimate_gas(to: "0xa0b...ef6")
{:ok, 12345}

@spec estimate_gas!(map(), Keyword.t()) :: non_neg_integer() | no_return()

Same as Ethers.estimate_gas/2 but raises on error.

@spec fee_history(
  pos_integer(),
  binary() | non_neg_integer(),
  [number()],
  Keyword.t()
) ::
  {:ok, map()} | {:error, term()}

Returns the fee history from the RPC API (eth_feeHistory).

Also works with Ethers.batch/2 as {:fee_history, [block_count, newest_block, reward_percentiles]}.

Parameters

• block_count: Number of blocks to look back. (positive integer)
• newest_block: Highest block of the requested range — a block number (integer) or one of the block tags "latest", "earliest", "pending", "safe" or "finalized". Hex encoded block numbers are not accepted. (default "latest")
• reward_percentiles: List of percentiles (0-100) to sample the priority fees of the transactions in each block at. When empty, no :reward data is returned. (default [])
• opts: RPC related options.

Returns

{:ok, fee_history} where fee_history is a map with these keys (quantities decoded to integers):

• :oldest_block: Number of the first block in the range.
• :base_fee_per_gas: Base fee per gas for each block in the range, plus one extra entry: the expected base fee of the next block.
• :gas_used_ratio: Gas used ratio (0..1) of each block in the range.
• :reward: For each block, the transaction priority fees at each requested percentile. nil (or sometimes [], depending on the node) when reward_percentiles is empty.
• :base_fee_per_blob_gas / :blob_gas_used_ratio: Same as their gas counterparts, for blob gas (EIP-4844). nil when the node does not report them.

Returns {:error, :not_supported} if the configured RPC client does not implement the optional eth_fee_history/4 callback.

@spec fee_history!(
  pos_integer(),
  binary() | non_neg_integer(),
  [number()],
  Keyword.t()
) ::
  map() | no_return()

Same as Ethers.fee_history/4 but raises on error.

@spec get_balance(Ethers.Types.t_address(), Keyword.t()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Returns the native token (ETH) balance of an account in wei.

Parameters

• account: Account which the balance is queried for.
• overrides:
  • block: The block you want to query the balance of account in (defaults to latest).
  • rpc_client: The RPC module to use for this request (overrides default).
  • rpc_opts: Specific RPC options to specify for this request.

@spec get_balance!(Ethers.Types.t_address(), Keyword.t()) ::
  non_neg_integer() | no_return()

Same as Ethers.get_balance/2 but raises on error.

@spec get_logs(map() | module(), Keyword.t()) ::
  {:ok, [Ethers.Event.t()]} | {:error, term()}

Fetches the event logs with the given filter.

The filter can be one of:

• A single event filter. (e.g. MyContract.EventFilters.transfer(nil, nil))
• A combined event filter matching multiple events in one request, created with Ethers.EventFilter.combine/1.
• An EventFilters module of a contract (e.g. MyContract.EventFilters) to match all events of that contract.

Overrides and Options

• :address: Indicates event emitter contract address. (nil means all contracts)
• :rpc_client: The RPC Client to use. It should implement ethereum jsonRPC API. default: Ethereumex.HttpClient
• :rpc_opts: Extra options to pass to rpc_client. (Like timeout, Server URL, etc.)

• :fromBlock | :from_block: Minimum block number of logs to filter.

• :toBlock | :to_block: Maximum block number of logs to filter.

@spec get_logs!(map() | module(), Keyword.t()) :: [Ethers.Event.t()] | no_return()

Same as Ethers.get_logs/2 but raises on error.

@spec get_transaction(Ethers.Types.t_hash(), Keyword.t()) ::
  {:ok, Ethers.Transaction.t()} | {:error, term()}

Returns the native transaction (ETH) by transaction hash.

Parameters

• tx_hash: Transaction hash which the transaction is queried for.
• overrides:
  • rpc_client: The RPC module to use for this request (overrides default).
  • rpc_opts: Specific RPC options to specify for this request.

@spec get_transaction!(Ethers.Types.t_hash(), Keyword.t()) ::
  Ethers.Transaction.t() | no_return()

Same as Ethers.get_transaction/2 but raises on error.

@spec get_transaction_count(Ethers.Types.t_address(), Keyword.t()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Returns the transaction count of an address.

Parameters

• account: Account which the transaction count is queried for.
• overrides:
  • block: The block you want to query the transaction count in (defaults to latest).
  • rpc_client: The RPC module to use for this request (overrides default).
  • rpc_opts: Specific RPC options to specify for this request.

@spec get_transaction_receipt(Ethers.Types.t_hash(), Keyword.t()) ::
  {:ok, map()} | {:error, term()}

Returns the receipt of a transaction by it's hash.

Parameters

• tx_hash: Transaction hash which the transaction receipt is queried for.
• overrides:
  • rpc_client: The RPC module to use for this request (overrides default).
  • rpc_opts: Specific RPC options to specify for this request.

@spec get_transaction_receipt!(Ethers.Types.t_hash(), Keyword.t()) ::
  map() | no_return()

Same as Ethers.get_transaction_receipt/2 but raises on error.

@spec max_priority_fee_per_gas(Keyword.t()) ::
  {:ok, non_neg_integer()} | {:error, reason :: term()}

Returns the current max priority fee per gas from the RPC API

@spec max_priority_fee_per_gas!(Keyword.t()) :: non_neg_integer() | no_return()

Same as Ethers.max_priority_fee_per_gas/1 but raises on error.

@spec personal_sign(binary(), Keyword.t()) :: {:ok, binary()} | {:error, term()}

Signs an EIP-191 personal message (the personal_sign scheme) and returns the signature as a 0x-prefixed hex string (65 bytes: r ‖ s ‖ v).

The message is treated as raw bytes, exactly as given — a "0x..."-prefixed string is signed as literal text, not hex-decoded. See Ethers.PersonalMessage for the hashing scheme and the pure recover/verify counterparts.

The signer is resolved the same way as for transactions: the :signer option, otherwise the :default_signer application env, otherwise Ethers.Signer.JsonRPC.

Options

• :signer: The signer module to use. (e.g. Ethers.Signer.Local or Ethers.Signer.JsonRPC)
• :signer_opts: Options passed to the signer. Use :from here (and :private_key for Ethers.Signer.Local) so the signer knows which account signs.

Examples

Ethers.personal_sign("Hello world",
  signer: Ethers.Signer.Local,
  signer_opts: [private_key: "0x...", from: "0x..."]
)
#=> {:ok, "0x..."}

@spec personal_sign!(binary(), Keyword.t()) :: binary() | no_return()

Same as Ethers.personal_sign/2 but raises on error.

@spec send_transaction(map() | Ethers.TxData.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, term()}

Makes an eth_send rpc call to with the given data and overrides, Then returns the transaction hash.

Overrides and Options

Other than what stated below, any other option given in the overrides keyword list will be merged with the map that the RPC client will receive.

Required Options

• :from: The address of the account to sign the transaction with.

Optional Options

• :access_list: List of storage slots that this transaction accesses (optional)
• :chain_id: Chain id for the transaction (defaults to chain id from RPC server).
• :gas_price: (legacy only) max price willing to pay for each gas.
• :gas: Gas limit for execution of this transaction.
• :max_fee_per_gas: (EIP-1559 only) max fee per gas (estimated with Ethers.estimate_fees/1 from recent blocks, falling back to 120% of the current gas price on RPC clients without eth_feeHistory support).
• :max_priority_fee_per_gas: (EIP-1559 only) max priority fee per gas or validator tip. (estimated with Ethers.estimate_fees/1 from recent blocks, falling back to eth_maxPriorityFeePerGas)
• :nonce: Nonce of the transaction. (defaults to number of transactions of from address)
• :rpc_client: The RPC Client to use. It should implement ethereum jsonRPC API. default: Ethereumex.HttpClient
• :rpc_opts: Extra options to pass to rpc_client. (Like timeout, Server URL, etc.)
• :signer: The signer module to use for signing transaction. Default is nil and will rely on the RPC server for signing.
• :signer_opts: Options for signer module. See your signer docs for more details.
• :type: Transaction type. Either Ethers.Transaction.Eip1559 (default) or Ethers.Transaction.Legacy.
• :to: Address of the contract or a receiver of this transaction. (required if TxData does not have default_address)
• :value: Ether value to send with the transaction to the receiver (from => to).

Examples

Ethers.Contract.ERC20.transfer("0xff0...ea2", 1000) |> Ethers.send_transaction(to: "0xa0b...ef6")
{:ok, _tx_hash}

@spec send_transaction!(map() | Ethers.TxData.t(), Keyword.t()) ::
  String.t() | no_return()

Same as Ethers.send_transaction/2 but raises on error.

@spec sign_authorization(Ethers.Authorization.t() | map() | Keyword.t(), Keyword.t()) ::
  {:ok, Ethers.Authorization.Signed.t()} | {:error, term()}

Signs an EIP-7702 authorization and returns an Ethers.Authorization.Signed struct ready for use in the authorization_list of a type-4 transaction (Ethers.Transaction.Eip7702).

Accepts either a ready Ethers.Authorization struct (signed as-is) or a map/keyword list of authorization params. With params, missing fields are auto-fetched from the network: chain_id via eth_chainId and nonce via eth_getTransactionCount of the authority (the signing account, resolved from signer_opts[:from] or the signer's accounts).

The signer is resolved the same way as for transactions: the :signer option, otherwise the :default_signer application env, otherwise Ethers.Signer.JsonRPC. Note that Ethers.Signer.JsonRPC does not support authorization signing (no standard RPC method exists) and returns {:error, :not_supported}.

Options

• :executor: Set to :self when the authority itself will send the type-4 transaction (self-sponsoring). The transaction increments the account nonce before authorizations are applied, so the auto-fetched nonce is bumped by one. Defaults to nil (another account — a sponsor/relayer — sends the transaction). An explicitly given nonce is never adjusted.
• :signer: The signer module to use. (e.g. Ethers.Signer.Local)
• :signer_opts: Options passed to the signer. Use :from here (and :private_key for Ethers.Signer.Local) so the signer knows which account signs.
• :rpc_client: The RPC Client to use for auto-fetching missing fields.
• :rpc_opts: Specific RPC options to specify for auto-fetch requests.

Examples

# Fully specified authorization
{:ok, authorization} = Ethers.Authorization.new(chain_id: 1, address: delegate, nonce: 42)
Ethers.sign_authorization(authorization,
  signer: Ethers.Signer.Local,
  signer_opts: [private_key: "0x..."]
)
#=> {:ok, %Ethers.Authorization.Signed{...}}

# Auto-fetch chain_id and nonce; the authority sends the transaction itself
Ethers.sign_authorization(%{address: delegate},
  executor: :self,
  signer: Ethers.Signer.Local,
  signer_opts: [private_key: "0x..."]
)

@spec sign_authorization!(Ethers.Authorization.t() | map() | Keyword.t(), Keyword.t()) ::
  Ethers.Authorization.Signed.t() | no_return()

Same as Ethers.sign_authorization/2 but raises on error.

@spec sign_transaction(map(), Keyword.t()) :: {:ok, binary()} | {:error, term()}

Signs a transaction and returns the encoded signed transaction hex.

Parameters

Accepts same parameters as Ethers.send_transaction/2.

@spec sign_transaction!(map(), Keyword.t()) :: binary() | no_return()

Same as Ethers.sign_transaction/2 but raises on error.

@spec sign_typed_data(Ethers.TypedData.t(), Keyword.t()) ::
  {:ok, binary()} | {:error, term()}

Signs an EIP-712 typed-data payload and returns the signature as a 0x-prefixed hex string (65 bytes: r ‖ s ‖ v).

Unlike sign_transaction/2, no transaction fields are auto-fetched; the given Ethers.TypedData is signed as-is. The signer is resolved the same way as for transactions: the :signer option, otherwise the :default_signer application env, otherwise Ethers.Signer.JsonRPC.

Options

• :signer: The signer module to use. (e.g. Ethers.Signer.Local or Ethers.Signer.JsonRPC)
• :signer_opts: Options passed to the signer. Use :from here (and :private_key for Ethers.Signer.Local) so the signer knows which account signs.

Examples

typed_data = Ethers.TypedData.new!(...)

Ethers.sign_typed_data(typed_data,
  signer: Ethers.Signer.Local,
  signer_opts: [private_key: "0x...", from: "0x..."]
)
#=> {:ok, "0x..."}

@spec sign_typed_data!(Ethers.TypedData.t(), Keyword.t()) :: binary() | no_return()

Same as Ethers.sign_typed_data/2 but raises on error.