Manic.Fees (Manic v0.1.1) View Source

Query dynamic fee rates from Bitcoin miners, and calculate accurate transaction fees.

Miners are moving to a model where they will fix their fees in Fiat terms. In addition, miners will compete with each other and some may specialise in different types on transactions. All of this will lead to a fluid fee market where the rates offered by miners will differ and shift over time.

This module allows developers to query miners directly for up to date fee rates, plus calculate accurate fees for any given transaction.

Link to this section Summary

Types

fee_quote()

A simplified miner fee quote.

fee_rates()

Fee rates broken down by fee types.

fee_type()

The type of transaction data any given fee applies to.

Functions

calculate(miner, tx)

Calculates the fee of the given transaction using the specified rates.

calculate(miner, tx, fee_quote)

calculate!(miner, tx)

As calculate/2 but returns the result or raises an exception if it fails.

calculate!(miner, tx, fee_quote)

get(miner, options \\ [])

Get a fee quote from the given miner.

get!(miner, options \\ [])

As get/2 but returns the result or raises an exception if it fails.

Link to this section Types

fee_quote()

Specs

fee_quote() :: %{expires: DateTime.t(), mine: fee_rates(), relay: fee_rates()}

A simplified miner fee quote.

The quote contains an expiry date, allowing developers to know when the quoted fees remain valid until. Fee rates are further broken down by:

:mine - Minimum threshold where a miner would be willing to mine the transaction
:relay - Minimum threshold where a miner would be willing to relay and hold a transaction in their mempool

fee_rates()

Specs

fee_rates() :: %{optional(fee_type()) => float()}

Fee rates broken down by fee types.

fee_type()

Specs

fee_type() :: :standard | :data | atom()

The type of transaction data any given fee applies to.

Currently fees are broken down by standard and data types. data fees are applied to any data carrier output (OP_RETURN) whereas all other transaction data is priced at the standard rate. In future other fee types may be introduced.

Link to this section Functions

calculate(miner, tx)

Specs

calculate(Manic.miner(), BSV.Tx.t() | String.t()) ::
  {:ok, integer()} | {:error, Exception.t()}

Calculates the fee of the given transaction using the specified rates.

Returns the fee in satoshis as an integer/0.

If a miner is passed as the first argument, the function firstly gets the rates for that miner, before calculating the fee for the given transaction. The transaction can be passed as either a BSV.Tx.t/0 or as a hex encoded binary.

Example

iex> Manic.Fees.calculate(%{data: 0.5, standard: 0.5}, tx)
346

calculate(miner, tx, fee_quote)

Specs

calculate(Manic.miner(), BSV.Tx.t() | String.t(), fee_quote()) ::
  {:ok, integer()} | {:error, Exception.t()}

calculate!(miner, tx)

Specs

calculate!(Manic.miner(), BSV.Tx.t() | String.t()) :: integer()

As calculate/2 but returns the result or raises an exception if it fails.

calculate!(miner, tx, fee_quote)

Specs

calculate!(Manic.miner(), BSV.Tx.t() | String.t(), fee_quote()) :: integer()

get(miner, options \\ [])

Specs

get(
  Manic.miner() | Manic.multi_miner(),
  keyword()
) ::
  {:ok, fee_quote() | Manic.JSONEnvelope.payload() | Manic.JSONEnvelope.t()}
  | {:error, Exception.t()}
  | Manic.Multi.result()

Get a fee quote from the given miner.

Returns the result in an :ok / :error tuple pair.

Options

The :as option can be used to speficy how to recieve the fees. The accepted values are:

:fees - The structured fee quote data (Default)
:payload - The decoded JSON payload
:envelope - The raw JSON envolope

Examples

To get a fee quote from the given miner.

iex> Manic.Fees.get(miner)
{:ok, %{
  mine: %{data: 0.5, standard: 0.5},
  relay: %{data: 0.25, standard: 0.25},
  verified: true
}}

Using the :as option to return the JSON envolope.

iex> Manic.Fees.get(miner, as: :envelope)
{:ok, %Manic.JSONEnvelope{
  encoding: "UTF-8",
  mimetype: "application/json",
  payload: "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-04-20T14:10:15.079Z\",\"expiryTime\":\"2020-04-20T14:20:15.079Z\",\"minerId\":\"03e92d3e5c3f7bd945dfbf48e7a99393b1bfb3f11f380ae30d286e7ff2aec5a270\",\"currentHighestBlockHash\":\"00000000000000000020900d959b83325068f28ff635cb541888ef16ec8ebaf7\",\"currentHighestBlockHeight\":631451,\"minerReputation\":null,\"fees\":[{\"feeType\":\"standard\",\"miningFee\":{\"satoshis\":5,\"bytes\":10},\"relayFee\":{\"satoshis\":25,\"bytes\":100}},{\"feeType\":\"data\",\"miningFee\":{\"satoshis\":5,\"bytes\":10},\"relayFee\":{\"satoshis\":25,\"bytes\":100}}]}",
  public_key: "03e92d3e5c3f7bd945dfbf48e7a99393b1bfb3f11f380ae30d286e7ff2aec5a270",
  signature: "304402206fc2744bc3626e5becbc3a708760917c6f78f83a61fd557b238c613862929412022047d22f89bd6fe98ca50e819452db81318641f74544252b1f04536cc689cf5f55",
  verified: true
}}

get!(miner, options \\ [])

Specs

get!(
  Manic.miner() | Manic.multi_miner(),
  keyword()
) :: fee_quote() | Manic.JSONEnvelope.payload() | Manic.JSONEnvelope.t()

As get/2 but returns the result or raises an exception if it fails.