Terminus v0.1.1 Terminus.Bitbus View Source
Module for interfacing with the Bitbus API.
Bitbus is a powerful API that allows you to crawl a filtered subset of the Bitcoin blockchain. Bitbus indexes blocks, thus can be used to crawl confirmed transactions.
We run a highly efficient bitcoin crawler which indexes the bitcoin blockchain. Then we expose the index as an API so anyone can easily crawl ONLY the subset of bitcoin by crawling bitbus.
Schema
Bitbus transaction documents have the following schema:
%{
"_id" => "...", # Bitbus document ID
"blk" => %{
"h" => "...", # Block hash
"i" => int, # Block height
"t" => int, # Block timestamp
},
"in" => [...], # List of inputs
"lock" => int, # Lock time
"out" => [...], # List of outputs
"tx" => %{
"h" => "..." # Transaction hash
}
}Terminus supports both of the Bitbus public enpoints. The endpoint can be
selected by passing the :host option to any API method.
The available endpoints are:
:txo- Query and return transactions in the Transaction Object schema. Default.:bob- Query and return transactions in the Bitcoin OP_RETURN Bytecode schema.
iex> Terminus.Bitbus.fetch(query, token: token, host: :bob)Usage
For smaller queries of limited results, fetch/2 can be used to return a list
of transactions:
iex> Terminus.Bitbus.fetch(%{
...> find: %{ "out.s2" => "1LtyME6b5AnMopQrBPLk4FGN8UBuhxKqrn" },
...> sort: %{ "blk.i": -1 },
...> limit: 5
...> }, token: token)
{:ok, [
%{
"tx" => %{"h" => "fca7bdd7658613418c54872212811cf4c5b4f8ee16864eaf70cb1393fb0df6ca"},
...
},
...
]}For larger crawl operations, use crawl/3 to stream results into your own
data processing pipeline.
iex> Terminus.Bitbus.crawl!(query, token: token)
...> |> Stream.map(&Terminus.BitFS.scan_tx/1)
...> |> Stream.each(&save_to_db/1)
...> |> Stream.run
:okLink to this section Summary
Functions
Crawls Bitbus for transactions using the given query and returns a stream.
As crawl/3 but returns the result or raises an exception if it fails.
Crawls Bitbus for transactions using the given query and returns a list of transactions.
As fetch/2 but returns the result or raises an exception if it fails.
Fetches and returns the current status of Bitbus.
As status/1 but returns the result or raises an exception if it fails.
Link to this section Functions
Specs
crawl(Terminus.bitquery(), keyword(), Terminus.callback()) :: {:ok, Enumerable.t() | pid()} | :ok | {:error, Exception.t()}
Crawls Bitbus for transactions using the given query and returns a stream.
Returns the result in an :ok / :error tuple pair.
All requests must provide a valid Planaria token.
By default a streaming Enumerable.t/0 is returned. Optionally a linked
GenStage pid can be returned for using in combination with your
own GenStage consumer.
If a callback is provided, the stream is
automatically run and the callback is called on each transaction.
Options
The accepted options are:
token- Planaria authentication token. Required.host- The Bitbus host. Defaults to "https://txo.bitbus.network".stage- Return a linked GenStagepid. Defaults tofalse.
Examples
Queries should be in the form of any valid Bitquery.
query = %{
find: %{ "out.s2" => "1LtyME6b5AnMopQrBPLk4FGN8UBuhxKqrn" }
}By default Terminus.Bitbus.crawl/3 returns a streaming Enumerable.t/0.
iex> Terminus.Bitbus.crawl(query, token: token)
{:ok, %Stream{}}Optionally the pid of the GenStage producer can be returned.
iex> Terminus.Bitbus.crawl(query, token: token, stage: true)
{:ok, #PID<>}If a callback is provided, the function
returns :ok and the callback is called on each transaction.
iex> Terminus.Bitbus.crawl(query, [token: token], fn tx ->
...> IO.inspect tx
...> end)
:okSpecs
crawl!(Terminus.bitquery(), keyword(), Terminus.callback()) :: Enumerable.t() | pid() | :ok
As crawl/3 but returns the result or raises an exception if it fails.
Specs
fetch(Terminus.bitquery(), keyword()) :: {:ok, list()} | {:error, Exception.t()}
Crawls Bitbus for transactions using the given query and returns a list of transactions.
Returns the result in an :ok / :error tuple pair.
This function is suitable for smaller limited queries as the entire result set
is loaded in to memory an returned. For large crawls, crawl/3 is preferred
as the results can be streamed and processed more efficiently.
Options
The accepted options are:
token- Planaria authentication token. Required.host- The Bitbus host. Defaults to "https://txo.bitbus.network".
Examples
iex> Terminus.Bitbus.fetch(query, token: token)
{:ok, [
%{
"tx" => %{"h" => "bbae7aa467cb34010c52033691f6688e00d9781b2d24620cab51827cd517afb8"},
...
},
...
]}Specs
fetch!(Terminus.bitquery(), keyword()) :: list()
As fetch/2 but returns the result or raises an exception if it fails.
Specs
status(keyword()) :: {:ok, map()} | {:error, Exception.t()}
Fetches and returns the current status of Bitbus.
Returns the result in an :ok / :error tuple pair. The returned map
of data includes the current block header as well as the total number of
transactions in the block (count).
Examples
iex> Terminus.Bitbus.status
{:ok, %{
"hash" => "00000000000000000249f9bd0e127ebc62125a72686a7470fe4a41e4add2deb1",
"prevHash" => "000000000000000001b3ea9c4c073226c6233583ab510ea10ce01faff17c89f3",
"merkleRoot" => "fb19b1ff5cd838cfca399f9f2e46fa3a0e9f0da0459f91bfd6d02a75756f3a4d",
"time" => 1586457301,
"bits" => 402821143,
"nonce" => 1471454449,
"height" => 629967,
"count" => 2193
}}Specs
As status/1 but returns the result or raises an exception if it fails.