Ethers.Transaction behaviour (Ethers v0.6.4)

View Source

Transaction struct and helper functions for handling EVM transactions.

This module provides functionality to:

  • Create and manipulate transaction structs
  • Encode transactions for network transmission
  • Handle different transaction types (legacy, EIP-1559, etc.)

Summary

Types

t()

EVM Transaction type

t_payload()

EVM Transaction payload type

Callbacks

auto_fetchable_fields()

Returns a list of fields that can be auto-fetched from the network.

from_rlp_list(list)

Constructs a transaction from a decoded RLP list

new(map)

Creates a new transaction struct with the given parameters.

type_envelope()

Returns the type envelope for the transaction.

type_id()

Returns the type ID for the transaction. e.g Legacy: 0, EIP-1559: 2

Functions

add_auto_fetchable_fields(params, opts)

Fills missing transaction fields with default values from the network based on transaction type.

decode(raw_transaction_bin)

Decodes a raw transaction from a binary or hex-encoded string.

encode(transaction)

Encodes a transaction for network transmission following EIP-155/EIP-1559.

from_rpc_map(tx)

Converts a map (typically from JSON-RPC response) into a Transaction struct.

new(params)

Creates a new transaction struct with the given parameters.

to_rpc_map(transaction)

Converts a Transaction struct into a map suitable for JSON-RPC.

transaction_hash(transaction, format \\ :hex)

Calculates the transaction hash.

Types

t()

@type t() :: t_payload() | Ethers.Transaction.Signed.t()

EVM Transaction type

t_payload()

@type t_payload() ::
  Ethers.Transaction.Legacy.t()
  | Ethers.Transaction.Eip4844.t()
  | Ethers.Transaction.Eip2930.t()
  | Ethers.Transaction.Eip1559.t()

EVM Transaction payload type

Callbacks

auto_fetchable_fields()

@callback auto_fetchable_fields() :: [atom()]

Returns a list of fields that can be auto-fetched from the network.

from_rlp_list(list)

@callback from_rlp_list([binary() | [binary()]]) ::
  {:ok, t(), rest :: [binary() | [binary()]]} | {:error, reason :: term()}

Constructs a transaction from a decoded RLP list

new(map)

@callback new(map()) :: {:ok, t()} | {:error, reason :: atom()}

Creates a new transaction struct with the given parameters.

type_envelope()

@callback type_envelope() :: binary()

Returns the type envelope for the transaction.

type_id()

@callback type_id() :: non_neg_integer()

Returns the type ID for the transaction. e.g Legacy: 0, EIP-1559: 2

Functions

add_auto_fetchable_fields(params, opts)

@spec add_auto_fetchable_fields(
  map(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Fills missing transaction fields with default values from the network based on transaction type.

Parameters

  • params - Updated Transaction params
  • opts - Options to pass to the RPC client

Returns

  • {:ok, params} - Filled transaction struct
  • {:error, reason} - If fetching defaults fails

decode(raw_transaction_bin)

@spec decode(String.t() | binary()) :: {:ok, t()} | {:error, term()}

Decodes a raw transaction from a binary or hex-encoded string.

Transaction strings must be prefixed with "0x" for hex-encoded inputs. Handles both legacy and typed transactions (EIP-1559, etc).

Parameters

  • raw_transaction - Raw transaction data as a binary or hex string starting with "0x"

Returns

  • {:ok, transaction} - Decoded transaction struct
  • {:error, reason} - Error decoding transaction

encode(transaction)

@spec encode(t()) :: binary()

Encodes a transaction for network transmission following EIP-155/EIP-1559.

Handles both legacy and EIP-1559 transaction types, including signature data if present.

Parameters

  • transaction - Transaction struct to encode

Returns

  • binary - RLP encoded transaction with appropriate type envelope

from_rpc_map(tx)

@spec from_rpc_map(map()) :: {:ok, t()} | {:error, :unsupported_type}

Converts a map (typically from JSON-RPC response) into a Transaction struct.

Handles different field naming conventions and transaction types.

Parameters

  • tx - Map containing transaction data. Keys can be snakeCase strings or atoms. (e.g :chainId, "gasPrice")

Returns

  • {:ok, transaction} - Converted transaction struct
  • {:error, :unsupported_type} - If transaction type is not supported

new(params)

@spec new(map()) :: {:ok, t()} | {:error, reason :: term()}

Creates a new transaction struct with the given parameters.

Type of transaction is determined by the type field in the params map or defaults to EIP-1559.

Examples 

iex> Ethers.Transaction.new(%{type: Ethers.Transaction.Eip1559, from: "0x123...", to: "0x456...", value: "0x0"})
{:ok, %Ethers.Transaction.Eip1559{from: "0x123...", to: "0x456...", value: "0x0"}}

to_rpc_map(transaction)

@spec to_rpc_map(t()) :: map()

Converts a Transaction struct into a map suitable for JSON-RPC.

Parameters

  • transaction - Transaction struct to convert

Returns

  • map containing transaction parameters with RPC field names and "0x" prefixed hex values

transaction_hash(transaction, format \\ :hex)

@spec transaction_hash(t(), :bin | :hex) :: binary() | String.t()

Calculates the transaction hash.

Parameters

  • transaction - Transaction struct to hash
  • format - Format to return the hash in. Either :hex or :bin. (default: :hex)

Returns Either

  • binary - Transaction hash in binary format (when format is :bin)
  • String.t() - Transaction hash in hex format prefixed with "0x" (when format is :hex)