# `Ethers.Utils`
[🔗](https://github.com/ExWeb3/elixir_ethers/blob/v0.6.12/lib/ethers/utils.ex#L1)

Utilities for interacting with ethereum blockchain

# `date_to_block_number`

```elixir
@spec date_to_block_number(
  Date.t() | DateTime.t() | non_neg_integer(),
  non_neg_integer() | nil,
  Keyword.t()
) :: {:ok, non_neg_integer()} | {:error, term()}
```

Returns the nearest block number to a given date and time.

## Parameters
- date_or_date_time: Can be a `Date`, `DateTime` or an integer unix timestamp.
- ref_block_number: A block number of reference which is closer to the target block.
  Can make search time faster if given. (Defaults to current block number)
- opts: Optional extra options.
  - acceptable_drift: Can be set to override the default acceptable_drift of
    120 seconds. This value can be reduced for more accurate results.
  - sample_size: Can be set to override the default sample_size of 5000 blocks.
  - backoff_timeout: An optional backoff in milliseconds that will happen between RPC calls.
    (Useful to prevent quote errors)

# `decode_address`

```elixir
@spec decode_address(Ethers.Types.t_address() | nil) ::
  {:ok, binary()} | {:error, :invalid_address}
```

Decode a hex-encoded Ethereum address to its binary form.
Returns error if the address is invalid (wrong length or invalid hex).

## Examples

    iex> Ethers.Utils.decode_address("0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1")
    {:ok, <<144, 248, 191, 106, 71, 159, 50, 14, 173, 7, 68, 17, 164, 176, 231, 148, 78, 168, 201, 193>>}

    iex> Ethers.Utils.decode_address(nil)
    {:error, :invalid_address}

    iex> Ethers.Utils.decode_address("0xinvalid")
    {:error, :invalid_address}

# `decode_address!`

```elixir
@spec decode_address!(Ethers.Types.t_address() | nil) :: binary() | no_return()
```

Same as `decode_address/1` but raises on error.

## Examples

    iex> Ethers.Utils.decode_address!("0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1")
    <<144, 248, 191, 106, 71, 159, 50, 14, 173, 7, 68, 17, 164, 176, 231, 148, 78, 168, 201, 193>>

# `encode_address`

```elixir
@spec encode_address(binary()) ::
  {:ok, Ethers.Types.t_address()} | {:error, :invalid_address}
```

Encode a binary Ethereum address to its hex form.
Returns error if the address is invalid (wrong length).

## Examples

    iex> address = <<144, 248, 191, 106, 71, 159, 50, 14, 173, 7, 68, 17, 164, 176, 231, 148, 78, 168, 201, 193>>
    iex> Ethers.Utils.encode_address(address)
    {:ok, "0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1"}

    iex> Ethers.Utils.encode_address(<<1, 2, 3>>)
    {:error, :invalid_address}

# `encode_address!`

```elixir
@spec encode_address!(binary()) :: Ethers.Types.t_address() | no_return()
```

Same as `encode_address/1` but raises on error.

## Examples

    iex> address = <<144, 248, 191, 106, 71, 159, 50, 14, 173, 7, 68, 17, 164, 176, 231, 148, 78, 168, 201, 193>>
    iex> Ethers.Utils.encode_address!(address)
    "0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1"

# `from_wei`

```elixir
@spec from_wei(integer()) :: float()
```

Convert WEI to ETH

## Examples

    iex> Ethers.Utils.from_wei(1000000000000000000)
    1.0

    iex> Ethers.Utils.from_wei(3140000000000000000)
    3.14

    iex> Ethers.Utils.from_wei(-10000000000000000000)
    -10.0

# `get_block_timestamp`

```elixir
@spec get_block_timestamp(non_neg_integer() | String.t(), Keyword.t()) ::
  {:ok, non_neg_integer()}
  | {:error, :negative_block_number | :block_not_found | term()}
```

Returns the timestamp for a given block number.

The block_number parameter can be a non negative integer or the hex encoded value of that integer.
(The hex encoding *must* start with 0x prefix)

# `hex_decode`

```elixir
@spec hex_decode(String.t()) :: {:ok, binary()} | :error
```

Decode from hex with (or without) 0x prefix.

## Examples

    iex> Ethers.Utils.hex_decode("0x6574686572735f6578")
    {:ok, "ethers_ex"}

    iex> Ethers.Utils.hex_decode("6574686572735f6578")
    {:ok, "ethers_ex"}

    iex> Ethers.Utils.hex_decode("0x686")
    {:ok, <<6, 134>>}

# `hex_decode!`

```elixir
@spec hex_decode!(String.t()) :: binary() | no_return()
```

Same as `hex_decode/1` but raises on error

## Examples

    iex> Ethers.Utils.hex_decode!("0x6574686572735f6578")
    "ethers_ex"

    iex> Ethers.Utils.hex_decode!("6574686572735f6578")
    "ethers_ex"

# `hex_encode`

Encode to hex with 0x prefix.

## Examples

    iex> Ethers.Utils.hex_encode("ethers_ex")
    "0x6574686572735f6578"

# `hex_to_integer`

```elixir
@spec hex_to_integer(String.t()) :: {:ok, non_neg_integer()} | {:error, :invalid_hex}
```

Converts a hexadecimal integer to integer form

## Examples

    iex> Ethers.Utils.hex_to_integer("0x11111")
    {:ok, 69905}

# `hex_to_integer!`

```elixir
@spec hex_to_integer!(String.t()) :: non_neg_integer() | no_return()
```

Same as `hex_to_integer/1` but raises on error

## Examples

    iex> Ethers.Utils.hex_to_integer!("0x11111")
    69905

# `human_arg`

```elixir
@spec human_arg(term(), ABI.FunctionSelector.type()) :: term()
```

Reverse of `prepare_arg/2`

## Examples
    iex> Ethers.Utils.human_arg(<<192, 42, 170, 57, 178, 35, 254, 141, 10, 14, 92, 79, 39,
    ...> 234, 217, 8, 60, 117, 108, 194>>, :address)
    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"

    iex> Ethers.Utils.human_arg("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", :address)
    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"

# `integer_to_hex`

```elixir
@spec integer_to_hex(non_neg_integer()) :: String.t()
```

Converts integer to its hexadecimal form

## Examples

    iex> Ethers.Utils.integer_to_hex(69905)
    "0x11111"

# `maybe_add_gas_limit`

> This function is deprecated. Use Ethers.estimate_gas/2 instead.

Adds gas limit estimation to the parameters if not already exists

If option `mult` is given, a gas limit multiplied by `mult` divided by 1000 will be used.
Default for `mult` is 100. (1%)

# `prepare_arg`

```elixir
@spec prepare_arg(term(), ABI.FunctionSelector.type()) :: term()
```

Converts human readable argument to the form required for ABI encoding.

For example the addresses in Ethereum are represented by hex strings in human readable format
but are in 160-bit binaries in ABI form.

## Examples
    iex> Ethers.Utils.prepare_arg("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", :address)
    <<192, 42, 170, 57, 178, 35, 254, 141, 10, 14, 92, 79, 39, 234, 217, 8, 60, 117, 108, 194>>

# `public_key_to_address`

Calculates address of a given public key. Public key can be in compressed or decompressed format
either with or without prefix. It can also be hex encoded.

## Examples

    iex> Utils.public_key_to_address("0x04e68acfc0253a10620dff706b0a1b1f1f5833ea3beb3bde2250d5f271f3563606672ebc45e0b7ea2e816ecb70ca03137b1c9476eec63d4632e990020b7b6fba39")
    "0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1"

    iex> Utils.public_key_to_address("0x03e68acfc0253a10620dff706b0a1b1f1f5833ea3beb3bde2250d5f271f3563606")
    "0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1"

# `remove_leading_zeros`

```elixir
@spec remove_leading_zeros(binary()) :: binary()
```

Removes leading zeros from a binary.

## Examples

    iex> Ethers.Utils.remove_leading_zeros(<<0, 0, 1, 2, 3>>)
    <<1, 2, 3>>

# `to_checksum_address`

```elixir
@spec to_checksum_address(Ethers.Types.t_address() | &lt;&lt;_::320&gt;&gt;, pos_integer() | nil) ::
  Ethers.Types.t_address()
```

Will convert an upper or lowercase Ethereum address to a checksum address.

If `chain_id` is specified, ERC-1191 checksum encoding will be used.
NOTE: ERC-1191 is generally NOT backwards compatible with ERC-55 encoding
      (encoding without `chain_id`).

## Examples

    iex> Ethers.Utils.to_checksum_address("0xc1912fee45d61c87cc5ea59dae31190fffff232d")
    "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d"

    iex> Ethers.Utils.to_checksum_address("0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D")
    "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d"

    iex> Ethers.Utils.to_checksum_address("0xde709f2102306220921060314715629080e2fb77", 31)
    "0xDE709F2102306220921060314715629080e2Fb77"

    iex> Ethers.Utils.to_checksum_address("0XDE709F2102306220921060314715629080e2Fb77", 30)
    "0xDe709F2102306220921060314715629080e2FB77"

# `to_wei`

```elixir
@spec to_wei(number()) :: integer()
```

Converts ETH to WEI

## Examples

    iex> Ethers.Utils.to_wei(1)
    1000000000000000000

    iex> Ethers.Utils.to_wei(3.14)
    3140000000000000000

    iex> Ethers.Utils.to_wei(0)
    0

    iex> Ethers.Utils.to_wei(-10)
    -10000000000000000000

# `valid_checksum_address?`

```elixir
@spec valid_checksum_address?(Ethers.Types.t_address()) :: boolean()
```

Checks the checksum of a given address. Will also return false on non-checksum addresses.

## Examples

    iex> Ethers.Utils.valid_checksum_address?("0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d")
    true

    iex> Ethers.Utils.valid_checksum_address?("0xc1912fee45d61C87Cc5EA59DaE31190FFFFf232d")
    false

---

*Consult [api-reference.md](api-reference.md) for complete listing*