Etherex (Etherex v1.0.0-rc19) View Source

Elixir high level library for the Ethereum blockchain. This library is based on the methods of the Json RPC API (https://eth.wiki/json-rpc/api).

All functions returns {:error, :econnrefused} if no client is listening in the configured URL.

You can directly use Elixir integers for quantities or atoms for tags. The library encode/decode Elixir primitive data to/from the blockchain.

Compiled code and contract instances are abstracted. The library can compile code and generate a value of type t:compiled_code/0 and that representation can be used to deploy the contact and get a value of contract/0 that can be used in call/5 and call_transaction/5.

Some operations allow options. Options are Keyword.t/0 that accepts optional data accepted by the API (see https://eth.wiki/json-rpc/api for details when no details are given in this documentation).

The result of some operations are maps with a direct representation of the returns of the operations in the API (see https://eth.wiki/json-rpc/api for details when no details are given in this documentation).

Link to this section Summary

Functions

Returns a list of addresses owned by client.

Works like accounts/0 but a exception is raised on error.

Returns the number of most recent block.

Works like block_number/0 but a exception is raised on error.

Performs a call to a function of a deployed contract. This call does not generate a transaction in the blockchain.

Performs a call to a function of a deployed contract, This call generates a transaction in the blockchain.

Returns the current client version.

Works like client_version/0 but a exception is raised on error.

Returns the byte code after compiling Solidity source code. Parameter source_or_filename can be the source code or a filename with the source code.

Works like compile_solidity/1 but a exception is raised on error.

Deploys a contract to the blockchain.

Works like deploy/4 but a exception is raised on error.

Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance.

Generates and returns an estimate the gas cost of a transaction. It uses estimate_gas/5 and gas_price/0.

Returns the gas cost of a transaction. If the transaction hasn't been processed yet (is pending), {:ok, nil} is returned.

Works like gas_cost/1 but a exception is raised on error.

Returns the current price per gas in wei.

Works like gas_price/0 but a exception is raised on error.

Returns the balance of the account of given address.

Works like get_balance/2 but a exception is raised on error.

Returns information about a block by block number or by block hash.

Works like get_block/1 but a exception is raised on error.

Returns the deployed bytecode of a contract.

Returns the address of a contract. If the creation transaction has not been mined yet, nil is returned.

Works like get_contract_creation_address/1 but a exception is raised on error.

Returns the hash of the creation transaction of a contract.

Returns the contract creator address.

Given a contract and a transaction of the contract, retrieves the list of events logged in it. Returns [] if no events. Returns nil if transaction is pending.

Works like get_events/2 but a exception is raised on error.

Returns the information about a transaction requested by transaction hash.

Works like get_transaction/1 but a exception is raised on error.

Returns the receipt of a transaction by transaction hash. The receipt is not available for pending transactions and {:ok, nil} is returned.

Works like get_transaction_receipt/1 but a exception is raised on error.

Returns true if client is actively listening for network connections, false otherwise.

Works like net_listening/0 but a exception is raised on error.

Returns the current network id.

Works like net_version/0 but a exception is raised on error.

Returns the current ethereum protocol version.

Works like protocol_version/0 but a exception is raised on error.

Returns syncing status.

Works like syncing/0 but a exception is raised on error.

Decimal representation of a value given an Ether unit.

String representation of a value given an Ether unit.

Link to this section Types

Link to this section Functions

Specs

accounts() :: {:ok, [address()]} | {:error, error()}

Returns a list of addresses owned by client.

Specs

accounts!() :: [address()]

Works like accounts/0 but a exception is raised on error.

Specs

block_number() :: {:ok, quantity()} | {:error, error()}

Returns the number of most recent block.

Specs

block_number!() :: quantity()

Works like block_number/0 but a exception is raised on error.

Link to this function

call(contract, caller, function, arguments, block \\ :latest, opts \\ [])

View Source

Specs

call(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  block :: block_parameter(),
  opts :: Keyword.t()
) :: {:ok, any()} | {:error, error()}

Performs a call to a function of a deployed contract. This call does not generate a transaction in the blockchain.

Examples

iex> owner = List.last(Etherex.accounts!())
iex> {:ok, [value]} = Etherex.compile_solidity!("priv/solidity/Counter.sol")
...> |> Etherex.deploy!(owner, [], gas: 1_000_000)
...> |> Etherex.call(owner, "get", [])
iex> value
0
Link to this function

call!(contract, caller, function, arguments, block \\ :latest, opts \\ [])

View Source

Specs

call!(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  block :: block_parameter(),
  opts :: Keyword.t()
) :: any()

Works like call/6 but a exception is raised on error.

Link to this function

call_transaction(contract, caller, function, arguments, opts \\ [])

View Source

Specs

call_transaction(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  opts :: opts()
) :: {:ok, hash()} | {:error, error()}

Performs a call to a function of a deployed contract, This call generates a transaction in the blockchain.

Examples

iex> owner = List.last(Etherex.accounts!())
iex> {:ok, "0x" <> _} = Etherex.compile_solidity!("priv/solidity/Counter.sol")
...> |> Etherex.deploy!(owner, [], gas: 1_000_000)
...> |> Etherex.call_transaction(owner, "get", [])
Link to this function

call_transaction!(contract, caller, function, arguments, opts \\ [])

View Source

Specs

call_transaction!(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  opts :: opts()
) :: hash()

Works like call_transaction/5 but a exception is raised on error.

Specs

client_version() :: {:ok, String.t()} | {:error, error()}

Returns the current client version.

Specs

client_version!() :: String.t()

Works like client_version/0 but a exception is raised on error.

Link to this function

compile_solidity(source_or_filename)

View Source

Specs

compile_solidity(String.t()) :: {:ok, bytecode()} | {:error, error()}

Returns the byte code after compiling Solidity source code. Parameter source_or_filename can be the source code or a filename with the source code.

If source code is passed, the function tries to send the code to the client to get the compiled contract.

If a filename is passed, a local compiler is used to compile the code. If no local compiler can be used or compilation fails then the source code in file is sent to the client.

Link to this function

compile_solidity!(source_or_filename)

View Source

Specs

compile_solidity!(String.t()) :: bytecode()

Works like compile_solidity/1 but a exception is raised on error.

Link to this function

deploy(contract, creator, arguments, opts \\ [])

View Source

Specs

deploy(
  contract :: bytecode(),
  creator :: address(),
  arguments :: list(),
  opts :: opts()
) :: {:ok, contract()} | {:error, error()}

Deploys a contract to the blockchain.

Examples

iex> owner = List.last(Etherex.accounts!())
iex> {:ok, _contract} = Etherex.compile_solidity!("priv/solidity/Counter.sol")
...> |> Etherex.deploy(owner, [], gas: 1_000_000)
Link to this function

deploy!(code, creator, arguments, opts \\ [])

View Source

Specs

deploy!(
  code :: bytecode(),
  creator :: address(),
  arguments :: list(),
  opts :: opts()
) :: contract()

Works like deploy/4 but a exception is raised on error.

Link to this function

estimate_gas(contract, caller, function, arguments, opts \\ [])

View Source

Specs

estimate_gas(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  opts :: opts()
) :: {:ok, any()} | {:error, error()}

Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance.

Examples

iex> owner = List.last(Etherex.accounts!())
iex> {:ok, estimated_gas} = Etherex.compile_solidity!("priv/solidity/Counter.sol")
...> |> Etherex.deploy!(owner, [], gas: 1_000_000)
...> |> Etherex.estimate_gas(owner, "get", [])
iex> is_integer(estimated_gas)
true
Link to this function

estimate_gas!(contract, caller, function, arguments, opts \\ [])

View Source

Specs

estimate_gas!(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  opts :: Keyword.t()
) :: any()

Works like estimate_gas/5 but a exception is raised on error.

Link to this function

estimate_gas_cost(contract, caller, function, arguments, opts \\ [])

View Source

Specs

estimate_gas_cost(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  opts :: opts()
) :: {:ok, any()} | {:error, error()}

Generates and returns an estimate the gas cost of a transaction. It uses estimate_gas/5 and gas_price/0.

Examples

iex> owner = List.last(Etherex.accounts!())
iex> {:ok, gas_cost} = Etherex.compile_solidity!("priv/solidity/Counter.sol")
...> |> Etherex.deploy!(owner, [], gas: 1_000_000)
...> |> Etherex.estimate_gas_cost(owner, "get", [])
iex> is_integer(gas_cost)
true
Link to this function

estimate_gas_cost!(contract, caller, function, arguments, opts \\ [])

View Source

Specs

estimate_gas_cost!(
  contract :: contract(),
  caller :: address(),
  function :: String.t(),
  arguments :: list(),
  opts :: Keyword.t()
) :: any()

Works like estimate_gas_cost/5 but a exception is raised on error.

Specs

gas_cost(hash()) :: {:ok, quantity() | nil} | {:error, error()}

Returns the gas cost of a transaction. If the transaction hasn't been processed yet (is pending), {:ok, nil} is returned.

Specs

gas_cost!(hash()) :: quantity() | nil

Works like gas_cost/1 but a exception is raised on error.

Specs

gas_price() :: {:ok, quantity()} | {:error, error()}

Returns the current price per gas in wei.

Specs

gas_price!() :: quantity()

Works like gas_price/0 but a exception is raised on error.

Link to this function

get_balance(address, block \\ :latest)

View Source

Specs

get_balance(address(), block_parameter()) ::
  {:ok, quantity()} | {:error, error()}

Returns the balance of the account of given address.

Link to this function

get_balance!(address, block \\ :latest)

View Source

Specs

get_balance!(address(), block_parameter()) :: quantity()

Works like get_balance/2 but a exception is raised on error.

Link to this function

get_block(number_or_hash \\ :latest)

View Source

Specs

get_block(hash() | block_parameter()) :: {:ok, map()} | {:error, error()}

Returns information about a block by block number or by block hash.

Link to this function

get_block!(number_or_hash)

View Source

Specs

get_block!(quantity() | hash() | tag()) :: map()

Works like get_block/1 but a exception is raised on error.

Specs

get_bytecode(contract()) :: bytecode()

Returns the deployed bytecode of a contract.

Link to this function

get_contract_address(contract)

View Source

Specs

get_contract_address(contract()) :: {:ok, address() | nil} | {:error, error()}

Returns the address of a contract. If the creation transaction has not been mined yet, nil is returned.

Link to this function

get_contract_address!(contract)

View Source

Specs

get_contract_address!(contract()) :: address() | nil

Works like get_contract_creation_address/1 but a exception is raised on error.

Link to this function

get_contract_creation_hash(contract)

View Source

Specs

get_contract_creation_hash(contract()) :: hash()

Returns the hash of the creation transaction of a contract.

Specs

get_creator(contract()) :: address()

Returns the contract creator address.

Link to this function

get_events(contract, hash)

View Source

Specs

get_events(contract(), hash()) :: {:ok, [event()] | nil} | {:error, error()}

Given a contract and a transaction of the contract, retrieves the list of events logged in it. Returns [] if no events. Returns nil if transaction is pending.

Link to this function

get_events!(contract, hash)

View Source

Specs

get_events!(contract(), hash()) :: [event()] | nil

Works like get_events/2 but a exception is raised on error.

Specs

get_transaction(hash()) :: {:ok, map()} | {:error, error()}

Returns the information about a transaction requested by transaction hash.

Specs

get_transaction!(hash()) :: map()

Works like get_transaction/1 but a exception is raised on error.

Link to this function

get_transaction_receipt(hash)

View Source

Specs

get_transaction_receipt(Etherex.Type.hash()) ::
  {:ok, map() | nil} | {:error, Etherex.Type.error()}

Returns the receipt of a transaction by transaction hash. The receipt is not available for pending transactions and {:ok, nil} is returned.

Link to this function

get_transaction_receipt!(hash)

View Source

Specs

get_transaction_receipt!(hash()) :: map() | nil

Works like get_transaction_receipt/1 but a exception is raised on error.

Specs

net_listening() :: {:ok, boolean()} | {:error, error()}

Returns true if client is actively listening for network connections, false otherwise.

Specs

net_listening!() :: boolean()

Works like net_listening/0 but a exception is raised on error.

Specs

net_version() :: {:ok, String.t()} | {:error, error()}

Returns the current network id.

Specs

net_version!() :: String.t()

Works like net_version/0 but a exception is raised on error.

Specs

protocol_version() :: {:ok, String.t()} | {:error, error()}

Returns the current ethereum protocol version.

Specs

protocol_version!() :: String.t()

Works like protocol_version/0 but a exception is raised on error.

Specs

syncing() :: {:ok, map() | nil} | {:error, error()}

Returns syncing status.

Specs

syncing!() :: map()

Works like syncing/0 but a exception is raised on error.

Link to this function

transfer(from, to, value, opts \\ [])

View Source

Specs

transfer(
  from :: address(),
  to :: address(),
  value :: quantity(),
  opts :: opts()
) :: {:ok, hash()} | {:error, error()}

Transfer funds.

Link to this function

wei_to_decimal(wei, currency \\ :WEI)

View Source

Specs

wei_to_decimal(quantity(), unit()) :: Decimal.t()

Decimal representation of a value given an Ether unit.

Examples

iex> Etherex.wei_to_decimal(0)
Decimal.new("0.0")

iex> Etherex.wei_to_decimal(0, :WEI)
Decimal.new("0.0")

iex> Etherex.wei_to_decimal(0, :ETH)
Decimal.new("0.0")

iex> Etherex.wei_to_decimal(20000000000)
Decimal.new("2E+10")

iex> Etherex.wei_to_decimal(20000000000, :WEI)
Decimal.new("2E+10")

iex> Etherex.wei_to_decimal(20000000000, :GWEI)
Decimal.new("20.0")

iex> Etherex.wei_to_decimal(20000000000, :PWEI)
Decimal.new("0.00002")

iex> Etherex.wei_to_decimal(20000000000, :ETH)
Decimal.new("2E-8")
Link to this function

wei_to_string(wei, currency \\ :WEI)

View Source

Specs

wei_to_string(quantity(), unit()) :: String.t()

String representation of a value given an Ether unit.

Examples

iex> Etherex.wei_to_string(0)
"0 WEI"

iex> Etherex.wei_to_string(0, :WEI)
"0 WEI"

iex> Etherex.wei_to_string(0, :GWEI)
"0.000000000 GWEI"

iex> Etherex.wei_to_string(0, :PWEI)
"0.000000000000000 PWEI"

iex> Etherex.wei_to_string(0, :ETH)
"0.000000000000000000 ETH"

iex> Etherex.wei_to_string(20000000000)
"20,000,000,000 WEI"

iex> Etherex.wei_to_string(20000000000, :WEI)
"20,000,000,000 WEI"

iex> Etherex.wei_to_string(20000000000, :GWEI)
"20.000000000 GWEI"

iex> Etherex.wei_to_string(20000000000, :PWEI)
"0.000020000000000 PWEI"

iex> Etherex.wei_to_string(20000000000, :ETH)
"0.000000020000000000 ETH"