View Source Xogmios
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)
- [x] Tx Submission
- [ ] Mempool Monitoring
See Examples section below for information on how to use this library.
Installing
Add the dependency to mix.exs
:
defp deps do
[
{:xogmios, "~> 0.2.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
Chain Sync
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
State Query
The following illustrates working with the State Query protocol. It 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
Tx Submission
The following illustrates working with the Transaction Submission protocol. It submits a signed transaction, represented as a CBOR, to the Ogmios server.
defmodule TxSubmissionClient do
use Xogmios, :tx_submission
alias Xogmios.TxSubmission
def start_link(opts) do
Xogmios.start_tx_submission_link(__MODULE__, opts)
end
def submit_tx(pid \\ __MODULE__, cbor) do
# The CBOR must be a valid transaction,
# properly built and signed
TxSubmission.submit_tx(pid, cbor)
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.