View Source Xogmios

CI Status Version

Docs

An Elixir client for Ogmios.

Ogmios is a lightweight bridge interface for a Cardano node. It offers a WebSockets API that enables local clients to speak Ouroboros' mini-protocols via JSON/RPC. - https://ogmios.dev/

Mini-Protocols supported by this library:

  • [x] Chain Synchronization
  • [x] State Query (partially supported)
  • [ ] Mempool Monitoring
  • [ ] Tx Submission

See Examples section below for information on how to use this library.

Installing

Add the dependency to mix.exs:

defp deps do
  [
    {:xogmios, "~> 0.1.0"}
  ]
end

Add your client module(s) to your application's supervision tree as such:

# file: application.ex
def start(_type, _args) do
  children = [
    {ChainSyncClient, url: "ws://..."},
    {StateQueryClient, url: "ws://..."},
  ]
  #...
end

The value for the url option should be set to the address of your Ogmios instance.

See section below for examples of client modules.

Examples

The following is an example of a module that implement the Chain Sync behaviour. This module syncs with the tip of the chain, reads the next 3 blocks and then closes the connection with the server.

defmodule ChainSyncClient do
  use Xogmios, :chain_sync

  def start_link(opts) do
    initial_state = [counter: 3]
    opts = Keyword.merge(opts, initial_state)
    Xogmios.start_chain_sync_link(__MODULE__, opts)
  end

  @impl true
  def handle_block(block, %{counter: counter} = state) when counter > 1 do
    IO.puts("handle_block #{block["height"]}")
    {:ok, :next_block, %{state | counter: counter - 1}}
  end

  @impl true
  def handle_block(block, state) do
    IO.puts("final handle_block #{block["height"]}")
    {:close, state}
  end
end

The following example implements the State Query behaviour and runs queries against the tip of the chain.

defmodule StateQueryClient do
  use Xogmios, :state_query
  alias Xogmios.StateQuery

  def start_link(opts) do
    Xogmios.start_state_link(__MODULE__, opts)
  end

  def get_current_epoch(pid \\ __MODULE__) do
    StateQuery.send_query(pid, :get_current_epoch)
  end

  def get_era_start(pid \\ __MODULE__) do
    StateQuery.send_query(pid, :get_era_start)
  end
end

For examples of applications using this library, see Blocks and xogmios_watcher.

Test

Run mix test. Tests do NOT rely on a running Ogmios instance.