A behaviour module for implementing Planaria-like state machines in Elixir.

A module using Terminus.Planaria is a GenStage consumer process that will automatically mangage its own producer processes to crawl and listen to Bitcoin transaction events. Developers only need to implement callback functions to handle transaction events.

Example

The following code demonstrates how a Twetch scraper can be built in a few lines of code.

defmodule TwetchScraper do
  @query %{
    "find" => %{
      "out.s2": "19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut",
      "out.s25": "twetch"
    }
  }

  use Terminus.Planaria, token: {:my_app, :planaria_token},
                         from: 600000,
                         query: @query

  def handle_data(:block, txns) do
    # Handle confirmed transactions
  end

  def handle_data(:mempool, txns) do
    # Handle unconfirmed transactions
  end
end

The handle_data/2 callback can be implemented for each tx_event, and is typically be used to persist required data from each transaction. The handle_tape/2 callback can also be implemented for loading and persisting the tape head so a re-crawl isn't necessary if the process is interrupted.

Options

When invoking use Terminus.Planaria, the following config options are accepted:

• :token - Planaria Token. Required.
• :host - The Bitbus/Bitsocket endpoint to use. Defaults to :txo.
• :from - The block height from which to crawl for transactions. Required.
• :query - Full or shorthand Bitquery map.
• :poll - Interval (in seconds) to poll Bitbus for new blocks. Defaults to 300 (5 minutes).
• :recycle - Interval (in seconds) to recycle quiet Bitsocket requests. Defaults to 900 (15 minutes).

Supervision

Each Terminus.Planaria will most commonly be started under your application's supervision tree. When you invoke use Terminus.Planaria, it automatically defines a child_spec/1 function so your Planaria modules can be started directly under a supervisor.

And this is where we can have some fun and take full advantage of Elixir's concurrency model. Why not run many Planarias concurrently in your app?

children = [
  TwetchScraper,
  PreevScraper,
  WeathersvScraper
]

Supervisor.start_link(children, strategy: :one_for_all)