Exth.Provider (Exth v0.4.2)

View Source

Provides a macro for generating Ethereum JSON-RPC client methods with built-in client caching.

This module automatically generates functions for common Ethereum JSON-RPC methods, handling the client lifecycle, request formatting, and response parsing.

Features

  • Automatic client caching and reuse
  • Standard Ethereum JSON-RPC method implementations
  • Type-safe function signatures
  • Consistent error handling
  • Automatic request ID management
  • Connection pooling and reuse
  • Configurable transport layer
  • Dynamic configuration through both inline options and application config
  • Support for WebSocket subscriptions

Architecture

The Provider module works as follows:

  1. When use Exth.Provider is called, it:

    • Validates the required configuration options
    • Merges inline options with application config (inline takes precedence)
    • Generates a set of standardized RPC method functions
    • Sets up client caching mechanisms
  2. For each RPC call:

    • Reuses cached clients when possible
    • Automatically formats parameters
    • Handles request/response lifecycle
    • Provides consistent error handling

Usage

Basic Usage

defmodule MyProvider do
  use Exth.Provider,
    transport_type: :http,
    rpc_url: "https://my-eth-node.com"
end

# Then use the generated functions
{:ok, balance} = MyProvider.eth_getBalance("0x742d35Cc6634C0532925a3b844Bc454e4438f44e")
{:ok, block} = MyProvider.eth_getBlockByNumber(12345)

Subscription Usage

For WebSocket-based subscriptions, use the :websocket transport type:

defmodule MyProvider do
  use Exth.Provider,
    transport_type: :websocket,
    rpc_url: "wss://my-eth-node.com"
end

# Subscribe to new blocks
{:ok, subscription_id} = MyProvider.subscribe("newHeads")

# Unsubscribe when done
{:ok, true} = MyProvider.unsubscribe(subscription_id)

Dynamic Configuration

You can configure providers through both inline options and application config. Inline options take precedence over application config.

# In your config/config.exs or similar:
config :my_app, MyProvider,
  rpc_url: "https://config-rpc-url",
  timeout: 30_000

# In your provider module:
defmodule MyProvider do
  use Exth.Provider,
    otp_app: :my_app,
    transport_type: :http,
    rpc_url: "https://override-rpc-url" # This will override the config value
end

Configuration Options

Required Options

  • :transport_type - The transport type to use (:http, :websocket, or :custom)
  • :rpc_url - The URL of the Ethereum JSON-RPC endpoint
  • :otp_app - The application name for config lookup (required when using application config)

Generated Functions

All generated functions follow these conventions:

  • Return {:ok, result} for successful calls
  • Return {:error, reason} for failures
  • Accept an optional block_tag parameter (defaults to "latest") where applicable

Subscription Methods

The following subscription methods are available when using WebSocket transport:

  • subscribe(type) - Subscribe to a specific event type
    • type - The subscription type (e.g., "newHeads", "logs", "newPendingTransactions")
  • unsubscribe(subscription_id) - Unsubscribe from a specific subscription
    • subscription_id - The ID returned from a previous subscribe call

Error Handling

Possible error responses:

  • {:error, %{code: code, message: msg}} - RPC method error
  • {:error, reason} - Other errors with description

Examples

# Get balance for specific block
{:ok, balance} = MyProvider.eth_getBalance(
  "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "0x1b4"
)

# Get latest block
{:ok, block} = MyProvider.eth_getBlockByNumber("latest", true)

# Send raw transaction
{:ok, tx_hash} = MyProvider.eth_sendRawTransaction("0x...")

# Subscribe to new blocks
{:ok, subscription_id} = MyProvider.subscribe("newHeads")

# Unsubscribe from subscription
{:ok, true} = MyProvider.unsubscribe(subscription_id)

See Exth.Provider.Methods for a complete list of available RPC methods.

Summary

Functions

__using__(opts)

(macro)

Implements the provider behavior in the using module.

This macro is the entry point for creating an Ethereum JSON-RPC provider. It validates the provided options and generates all the necessary functions for interacting with an Ethereum node.

Options

See the moduledoc for complete configuration options.

Examples

defmodule MyProvider do
  use Exth.Provider,
    transport_type: :http,
    rpc_url: "https://mainnet.infura.io/v3/YOUR-PROJECT-ID"
end

generate_get_client()

(macro)

generate_handle_response()

(macro)

generate_provider(opts)

(macro)

Generates the provider module with all RPC method implementations.

This macro creates the actual provider implementation by:

  • Setting up the client cache
  • Generating functions for each RPC method
  • Implementing response handling
  • Creating helper functions

Parameters

  • opts - Keyword list of provider options

Generated Functions

For each RPC method defined in Exth.Provider.Methods, this macro generates:

  • A public function with proper type specs
  • Documentation with parameters and return values
  • Automatic parameter validation
  • Response handling and formatting

generate_rpc_method(method_name, rpc_method, param_types, accepts_block)

(macro)

generate_subscription_rpc_methods()

(macro)