Terminus

Terminus v0.1.1 Terminus.BitFS View Source

Module for interfacing with the BitFS API.

BitFS crawls the Bitcoin blockchain to find and store all the bitcoin script pushdata chunks larger than 512 bytes.

BitFS is an autonomous file system constructed from Bitcoin transactions.

BitFS URI scheme

Files are referenced using the BitFS URI scheme.

# bitfs://<TRANSACTION_ID>.(in|out).<SCRIPT_INDEX>.<CHUNK_INDEX>
"bitfs://13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4"

Terminus accepts given BitFS URI strings with or without the bitfs:// prefix.

Usage

To simply return the binary data for any BitFS URI use fetch/2.

iex> Terminus.BitFS.fetch(uri)
{:ok, <<...>>}

It is also possible to scan entire transactions and automatically fetch the binary data for any BitFS URIs discovered in the transaction. The binary data is added to the same output script at the same index with a d prefixed attribute.

iex> tx = %{
...>   "out" => [%{
...>     "f4" => "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4",
...>     ...
...>   }]
...> }
iex> Terminus.BitFS.scan_tx(tx)
%{
  "out" => [%{
    "f4" => "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4",
    "d4" => <<...>>,
    ...
  }]
}

Link to this section Summary

Functions

fetch(uri, options \\ [])

Fetches the binary blob data from BitFS using the given BitFS URI.

fetch!(uri, options \\ [])

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

scan_script(output)

Scans the given transaction script map, fetches data for any BitFS URI references, and returns a modified map with the data added.

scan_tx(tx)

Scans the given transaction map, fetches data for any BitFS URI references, and returns a modified map with the data added.

Link to this section Functions

Link to this function

fetch(uri, options \\ [])

View Source

Specs

fetch(Terminus.bitfs_uri(), keyword()) ::
  {:ok, binary()} | {:error, Exception.t()}

Fetches the binary blob data from BitFS using the given BitFS URI.

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

By default the entire data response is returned, although optionally a streaming Enumerable.t/0 can be returned or a linked GenStage pid.

Options

The accepted options are:

  • stream - Return a streaming Enumerable.t/0. Defaults to false.
  • stage - Return a linked GenStage pid. Defaults to false.

Examples

Files are references using the BitFS URI scheme.

# <TRANSACTION_ID>.(in|out).<SCRIPT_INDEX>.<CHUNK_INDEX>
"13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4"

By default Terminus.BitFS.fetch/2 returns the binary data of the file.

iex> Terminus.BitFS.fetch(uri)
{:ok, <<...>>}

Optionally a streaming Enumerable.t/0 can be returned.

iex> Terminus.BitFS.fetch(uri, stream: true)
{:ok, %Stream{}}

Or the pid of the GenStage producer can be returned.

iex> Terminus.BitFS.fetch(uri, stage: true)
{:ok, #PID<>}
Link to this function

fetch!(uri, options \\ [])

View Source

Specs

fetch!(Terminus.bitfs_uri(), keyword()) :: binary()

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

Link to this function

scan_script(output)

View Source

Specs

scan_script(map()) :: map()

Scans the given transaction script map, fetches data for any BitFS URI references, and returns a modified map with the data added.

Handles both txo and bob schema scripts.

Examples

Where a BitFS reference is found in a txo script, the fetched data is added to the script at the same index as the reference. For example, if a BitFS reference is found at f4, a new attribute d4 is put into the script containing the data.

iex> output = %{
...>   "f4" => "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4",
...>   ...
...> }
iex> Terminus.BitFS.scan_script(output)
%{
  "f4" => "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4",
  "d4" => <<...>>, # binary data added
  ...
}

With bob scripts, each cell is scanned and where a BitFS reference is found, a new d attribute is added to that cell containing the fetched data.

iex> output = %{"tape" => [
...>   %{"cell" => %{
...>     "f" => "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4",
...>     ...
...>   }},
...>   ...
...> ]}
iex> Terminus.BitFS.scan_script(output)
%{"tape" => [
  %{"cell" => %{
    "f" => "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4",
    "d" => <<...>>, # binary data added
    ...
  }},
  ...
]}
Link to this function

scan_tx(tx)

View Source

Specs

scan_tx(map()) :: map()

Scans the given transaction map, fetches data for any BitFS URI references, and returns a modified map with the data added.

The function handles both txo and bob schema transactions. See the examples for scan_script/1.