Exth.Provider (Exth v0.4.2)
View SourceProvides 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:
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
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 typetype
- The subscription type (e.g., "newHeads", "logs", "newPendingTransactions")
unsubscribe(subscription_id)
- Unsubscribe from a specific subscriptionsubscription_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
Implements the provider behavior in the using module.
Generates the provider module with all RPC method implementations.
Functions
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
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