Ethereumex

If your Ethereum node supports IPC (Inter-Process Communication), you can use Ethereumex.IpcClient instead of Ethereumex.HttpClient. All method signatures and usage patterns remain identical, allowing you to switch transport layers easily.

iex> Ethereumex.IpcClient.web3_client_version

When a subscription event occurs, a message is sent to your process. The message follows this structure:

%{
  "method" => "eth_subscription",
  "params" => %{
    "subscription" => subscription_id,
    "result" => result
  }
}

receive do
  %{
    "method" => "eth_subscription",
    "params" => %{
      "subscription" => subscription_id,
      "result" => result
    }
  } -> handle_notification(result)
end

Add :ethereumex to your mix.exs dependencies. The library uses a JSON library for processing, and :jason is recommended.

def deps do
  [
    {:ethereumex, "~> 0.14.0"},
    # json library is configurable
    {:jason, "~> 1.4"}
  ]
end

To use IPC, set client_type to :ipc and provide the ipc_path. You can also tune the IPC worker pool size and request timeouts.

config :ethereumex,
  client_type: :ipc,
  ipc_path: "/path/to/ipc",
  ipc_worker_size: 5,
  ipc_max_worker_overflow: 2,
  ipc_request_timeout: 60_000

The Ethereumex.Client.BaseClient module provides a macro __using__ that can be included in different client implementations (such as HTTP or IPC clients). When you include this macro, your module will implement the Ethereumex.Client.Behaviour and gain access to a wide range of Ethereum JSON-RPC methods.

All methods in the BaseClient accept an optional opts argument (a keyword list) to pass additional configuration to the underlying request mechanism.

defmodule MyCustomClient do
  use Ethereumex.Client.BaseClient
  # Your implementation of post_request/2 goes here
end

When a subscription event occurs, the notification is sent to your process as a message. The message follows the eth_subscription method format.

# Example of receiving a notification in a process loop
receive do
  %{
    "method" => "eth_subscription",
    "params" => %{
      "subscription" => "0x9cef478923ff08bf67fde6c64013158d",
      "result" => %{"number" => "0x1b4", ...}
    }
  } -> :ok
end

To use the WebSocket client for standard RPC calls and real-time subscriptions, set client_type to :websocket and provide the websocket_url.

config :ethereumex,
  websocket_url: "ws://localhost:8545",
  client_type: :websocket

To use the HTTP client, specify the url in your configuration. You can also configure connection pool timeouts and HTTP headers via http_options and http_headers.

config :ethereumex,
  url: "http://localhost:8545"

config :ethereumex,
  http_options: [pool_timeout: 5000, receive_timeout: 15_000],
  http_headers: [{"Content-Type", "application/json"}]

By default, ethereumex uses jason. You can override this by providing a module that implements encode/1, decode/2, encode!/1, and decode!/1 via the json_module configuration key.

config :ethereumex, json_module: MyCustomJson

You can deploy an OpenEthereum instance using the provided docker-compose.yml configuration. This setup exposes the JSON-RPC interfaces and maps a local directory to the container's data directory for persistence.

version: '3.8'

services:
  openethereum:
    image: openethereum/openethereum:v3.3.0
    command: '--chain=dev --unlock=0x00a329c0648769a73afac7f9381e08fb43dbea72 --password=/home/openethereum/.local/share/openethereum/passfile --jsonrpc-interface=0.0.0.0'
    ports:
      - '8545:8545'
      - '8546:8546'
    volumes:
      - ./docker:/home/openethereum/.local/share