# Elixir Ethers

[![example workflow](](
[![Module Version](](
[![Hex Docs](](
[![Last Updated](](

Elixir Ethers is a comprehensive library for interacting with the Ethereum blockchain and its ecosystem. 
Heavily inspired by the [ethers.js]( library, Elixir Ethers leverages macros to convert
Ethereum contract ABIs into first-class Elixir modules during compile time, complete with documentation and type-specs.

## Installation

You can install the package by adding `ethers` to the list of dependencies in your `mix.exs` file::

def deps do
    {:ethers, "~> 0.1.0-dev", github: "alisinabh/elixir_ethers"}

The complete documentation is available on [hexdocs](

## Requirements

To use Elixir Ethers, ensure you have a configured JSON-RPC endpoint.
By default, Ethers utilizes [Cloudflare's Ethereum Gateway](

To send transactions, you need a wallet client capable of signing transactions and exposing a JSON-RPC endpoint.
Configure the endpoint using the following config parameter (you can also specify the endpoint per-call):

# config.exs
import Config

config :ethereumex, url: "[URL_HERE]"

For more information, refer to [ethereumex](

## Usage

To use Elixir Ethers, you must have your contract's ABI, which can be obtained from []( 
This library also supports standard contract interfaces such as `ERC20`, `ERC721` and some more (refer to built-in contracts in hex-doc).

Create a module for your contract as follows:

defmodule MyERC20Token do
  use Ethers.Contract, abi_file: "path/to/abi.json", default_address: "[Token address here (optional)]"

### Calling contract functions

After defining the module, all the functions can be called like any other Elixir module.
The documentation is also available giving the developer a first-class experience.

iex> MyERC20Token.balance_of("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2")
{:ok, [654294510138460920346]}

iex> h MyERC20Token.balance_of
                     def balance_of(owner, overrides \\ [])

  @spec balance_of(Ethers.Types.t_address(), Keyword.t()) ::
          {:ok, [non_neg_integer()]}
          | {:ok, Ethers.Types.t_transaction_hash()}
          | {:ok, Ethers.Contract.t_function_output()}

Executes balanceOf(address _owner) on the contract.

## Parameters

  • _owner: `:address`
  • overrides: Overrides and options for the call.
    • :to: The address of the recipient contract. (Required)
    • :action: Type of action for this function (:call, :send or
      :prepare) Default: :call.
    • :rpc_opts: Options to pass to the RCP client e.g. :url.

## Return Types

  • {:uint, 256}

### Sending transaction

Sending transactions is also straightforward, as Elixir Ethers automatically determines whether a function is a view function or a state-changing function, using `eth_call` or `eth_sendTransaction` accordingly.
You can override this behavior with the `:action` override.

Ensure that you specify a `from` option to inform your client which account to use:

iex> MyERC20Token.transfer("0x[Recipient Address Here]", Ethers.Utils.to_wei(1), from: "0x[Your address here]")
{:ok, "0xf313ff7ff54c6db80ad44c3ad58f72ff0fea7ce88e5e9304991ebd35a6e76000"}

### Getting Logs (Events)

Elixir Ethers provides functionality for creating event filters and fetching events from the RPC endpoint using `eth_getLogs`. 
Each contract in Ethers generates an `EventFilters` module (e.g. `MyERC20Token.EventFilter`s) that can be used to create filters for events.

To create an event filter and use the `Ethers.get_logs` function, follow this example:

iex> {:ok, filter} = MyERC20Token.EventFilters.transfer("0x[From Address Here]", nil)

Also `nil` can be used for a parameter in EventFilters functions to show that it should not be filtered.

Then you can simply list the logs.

iex> Ethers.get_logs(filter)
      "address" => "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "blockHash" => "0xd04d7d39f0dd6913260f1682e1863eda9b5dc0a5d4cf2dca4ef6961147a77f39",
      "blockNumber" => "0x1046dd0",
      "data" => [1274604842999873536],
      "logIndex" => "0x0",
      "removed" => false,
      "topics" => ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "transactionHash" => "0xd00e58a817c42f46709bea153c44b7908d88d4763472836a85e7c740dd481d69",
      "transactionIndex" => "0x3"

## License

[Apache License 2.0](