Terminus v0.0.1 Terminus.Bitsocket View Source
Module for interfacing with the Bitsocket API.
Bitsocket sends you realtime events from the Bitcoin blockchain. It uses Server Sent Events to stream new unconfirmed transactions as soon as they appear on the Bitcoin network.
Bitsocket is like Websocket, but for Bitcoin. With just a single Bitsocket connection, you get access to a live, filterable stream of all transaction events across the entire bitcoin peer network.
Schema
Realtime transactions have a similar schema to Bitbus documents. However, as
these are unconfirmed transactions, they have no blk
infomation and provide
a timestamp
attribute reflecting when Bitsocket first saw the transaction.
%{
"_id" => "...", # Bitbus document ID
"in" => [...], # List of inputs
"lock" => int, # Lock time
"out" => [...], # List of outputs
"timestamp" => int, # Timestamp of when tx seen
"tx" => %{
"h" => "..." # Transaction hash
}
}
Bitsocket offers alternative endpoints for querying documents with inputs and
outputs represented using either the TXO schema
OR the BOB schema. Terminus
defaults to using the TXO endpoint, but the BOB endpoint can be used by
specifying the :host
option.
Terminus.Bitsocket.listen(query, host: 'bob.bitsocket.network')
Usage
Subscribe to realtime Bitcoin transactions using listen/3
and stream the
results into your own data processing pipeline.
iex> Terminus.Bitsocket.listen!(query)
...> |> Stream.map(&Terminus.BitFS.scan_tx/1)
...> |> Stream.each(&save_to_db/1)
...> |> Stream.run
:ok
Bitsocket also provides an API for querying and crawling the transaction event
database which indexes all transactions in the previous 24 hours. Both crawl/3
and fetch/2
can be used to query these events.
iex> Terminus.Bitsocket.fetch(%{
...> find: %{
...> "out.s2" => "1LtyME6b5AnMopQrBPLk4FGN8UBuhxKqrn",
...> "timestamp" => %{"$gt": :os.system_time(:millisecond) - 60000}
...> },
...> sort: %{ "timestamp": -1 }
...> }, token: token)
{:ok, [
%{
"tx" => %{"h" => "fca7bdd7658613418c54872212811cf4c5b4f8ee16864eaf70cb1393fb0df6ca"},
...
},
...
]}
Link to this section Summary
Functions
Crawls the Bitsocket event database 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 the Bitsocket event database for transactions using the given query and returns a stream.
As fetch/2
but returns the result or raises an exception if it fails.
Subscribes to Bitsocket and streams realtime transaction events using the given query.
As listen/3
but returns the result or raises an exception if it fails.
Link to this section Functions
crawl(query, options \\ [], ondata \\ nil)
View Sourcecrawl(map() | String.t(), keyword(), Terminus.Streamer.callback()) :: {:ok, Enumerable.t() | pid()} | :ok | {:error, String.t()}
Crawls the Bitsocket event database 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 Bitsocket host. Defaults totxo.bitsocket.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.Bitsocket.crawl/2
returns a streaming Enumerable.t/0
.
iex> Terminus.Bitsocket.crawl(query, token: token)
{:ok, %Stream{}}
Optionally the pid
of the GenStage producer can be returned.
iex> Terminus.Bitsocket.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.Bitsocket.crawl(query, [token: token], fn tx ->
...> IO.inspect tx
...> end)
:ok
crawl!(query, options \\ [], ondata \\ nil)
View Sourcecrawl!(map() | String.t(), keyword(), Terminus.Streamer.callback()) :: Enumerable.t() | pid() | :ok
As crawl/3
but returns the result or raises an exception if it fails.
Crawls the Bitsocket event database for transactions using the given query and returns a stream.
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 Bitsocket host. Defaults totxo.bitsocket.network
.
Examples
iex> Terminus.Bitsocket.fetch(query, token: token)
[
%{
"tx" => %{"h" => "bbae7aa467cb34010c52033691f6688e00d9781b2d24620cab51827cd517afb8"},
...
},
...
]
As fetch/2
but returns the result or raises an exception if it fails.
listen(query, options \\ [], ondata \\ nil)
View Sourcelisten(map() | String.t(), keyword(), Terminus.Streamer.callback()) :: {:ok, Enumerable.t() | pid()} | :ok | {:error, String.t()}
Subscribes to Bitsocket and streams realtime transaction events using the given query.
Returns the result in an :ok
/ :error
tuple pair.
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.
As Bitsocket streams transactions using Server Sent Events, the stream will stay open (and blocking) permanently. This is best managed inside a long-running Elixir process.
Options
The accepted options are:
host
- The Bitsocket host. Defaults totxo.bitsocket.network
.stage
- Return a linked GenStagepid
instead of a stream.
Examples
Queries should be in the form of any valid Bitquery.
query = %{
find: %{ "out.s2" => "1LtyME6b5AnMopQrBPLk4FGN8UBuhxKqrn" }
}
By default Terminus.Bitsocket.listen/2
returns a streaming Enumerable.t/0
.
iex> Terminus.Bitsocket.listen(query, token: token)
{:ok, %Stream{}}
Optionally the pid
of the GenStage producer can be returned.
iex> Terminus.Bitsocket.listen(query, token: token, stage: true)
{:ok, #PID<>}
If a callback
is provided, the stream returns :ok
and the callback is called on each transaction.
iex> Terminus.Bitsocket.listen(query, [token: token], fn tx ->
...> IO.inspect tx
...> end)
:ok
listen!(query, options \\ [])
View Sourcelisten!(map() | String.t(), keyword()) :: Enumerable.t() | pid() | :ok
As listen/3
but returns the result or raises an exception if it fails.