Publish v0.2 (#32)

* Updates for v0.2.0

Author: caike

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.2.0](https://github.com/wowica/xander/releases/tag/v0.2.0) (2025-05-08)
+
+### Added
+
+- Support for TxSubmission mini-protocol.
+- Integration tests on CI using Yaci DevKit.
+
 ## [v0.1.1](https://github.com/wowica/xander/releases/tag/v0.1.1) (2025-02-19)
 
 ### Fixed

README.md

@@ -3,9 +3,9 @@
 ![CI Status](https://github.com/wowica/xander/actions/workflows/ci.yml/badge.svg)
 [![Version](https://img.shields.io/hexpm/v/xander.svg)](https://hex.pm/packages/xander)
 
-Elixir client for Cardano's Ouroboros networking protocol.
+Elixir client for Cardano's Ouroboros networking protocol. This library can be used to build Elixir applications that connect to a Cardano node using the Node-to-Client protocol.
 
-⚠️ This project is under active development. For a more stable solution to connect to a Cardano node using Elixir, see [Xogmios](https://github.com/wowica/xogmios).
+⚠️ This project is under active development. See [Xogmios](https://github.com/wowica/xogmios) for a more stable solution to connect to a Cardano node through [Ogmios](https://ogmios.dev/).
 
 ## Mini-Protocols currently supported by this library:
 
@@ -23,7 +23,7 @@ Below is an example of how to connect to a Cardano node and run a query that ret
 
 ```elixir
 $ iex
-> Mix.install([{:xander, "~> 0.1.0"}])
+> Mix.install([{:xander, "~> 0.2.0"}])
 > # Must be a valid Unix socket path
 > # to a fully synced Cardano node
 > socket_path = "/path/to/cardano-node.socket"
@@ -44,6 +44,160 @@ $ iex
 For a more detailed description of different ways to use this library, read the following sections:
 
 
-1. [Running queries via Docker](docs/running-via-docker.md)
-2. [Running queries with native Elixir install](docs/running-natively.md)
-3. [Submitting transactions](docs/submitting-tx.md)
+<details>
+  <summary><i>Running Queries via Docker</i></summary>
+
+  ## Running Queries via Docker
+
+  In order to run queries via Docker, you need to build the image first:
+
+  ```
+  docker build -t xander .
+  ```
+
+  With the image built, you can now connect to either a local Cardano node via a UNIX socket or to a node at Demeter.run.
+
+  #### 1. Connecting via a local UNIX socket
+
+  This assumes you have access to a fully synced Cardano node.
+
+  🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X.
+
+  Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to 
+  the container's default socket path (`/tmp/cardano-node.socket`):
+
+  ```
+  docker run --rm \
+    -v /your/local/node.socket:/tmp/cardano-node.socket \
+    xander elixir run_queries.exs
+  ```
+
+  #### 2. Connecting to a node at Demeter.run
+
+  The demo application can connect to a Cardano node at [Demeter.run](https://demeter.run/) 🪄 
+
+  First, create a Node on Demeter and grab the Node's URL.
+
+  Then, run the Docker image with the `DEMETER_URL` environment variable set to your Node's URL:
+
+  ```bash
+  docker run --rm \
+    -e DEMETER_URL=https://your-node-at.demeter.run \
+    xander elixir run_with_demeter.exs
+  ```
+</details>
+
+<details>
+  <summary><i>Running Queries with native Elixir install</i></summary>
+  
+  ## Running Queries with native Elixir install
+
+  For those with Elixir already installed, simply run the commands below:
+
+  ```
+  # Must set a local unix socket
+  elixir run_queries.exs
+
+  # Must set a Demeter URL
+  elixir run_queries_with_demeter.exs
+  ```
+
+  More information on connection below:
+
+  #### a) Connecting via local UNIX socket
+
+  Run the following command using your own Cardano node's socket path:
+
+  ```bash
+  CARDANO_NODE_PATH=/your/cardano/node.socket elixir run_queries.exs
+  ```
+
+  ##### Setting up Unix socket mapping (optional when no direct access to Cardano node)
+
+  This is useful if you want to run the application on a server different from your Cardano node.
+
+  🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X.
+
+  1. Run socat on the remote server with the following command:
+
+  ```bash
+  socat TCP-LISTEN:3002,reuseaddr,fork UNIX-CONNECT:/home/cardano_node/socket/node.socket
+  ```
+
+  2. Run socat on the local machine with the following command:
+
+  ```bash
+  socat UNIX-LISTEN:/tmp/cardano_node.socket,reuseaddr,fork TCP:localhost:3002
+  ```
+
+  3. Start an SSH tunnel from the local machine to the remote server with the following command:
+
+  ```bash
+  ssh -N -L 3002:localhost:3002 user@remote-server-ip
+  ```
+
+  4. Run the example script:
+
+  ```bash
+  CARDANO_NODE_PATH=/tmp/cardano_node.socket elixir run.exs
+  ```
+
+  #### b) Connecting via Demeter.run
+
+  To connect to a node at Demeter.run, set `DEMETER_URL` to your Node Demeter URL.
+
+  ```bash
+  DEMETER_URL=https://your-node-at.demeter.run elixir run_with_demeter.exs
+  ```
+</details>
+
+<details>
+  <summary><i>Submitting Transactions</i></summary>
+
+  ## Submitting Transactions
+
+  ⚠️ This project does not provide off-chain transaction functionality such as building and signing of transactions.
+
+  In order to submit transactions via Xander, you can either run the `submit_tx.exs` script directly or use Docker. 
+
+
+  ## Running the script
+
+  This assumes you have Elixir installed. In order to run the script directly, follow the steps below:
+
+  1. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library)
+  2. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced Cardano node.
+  3. Ensure the `Config.default_config!` function call matches the network being used:
+    - `Config.default_config!(socket_path)` defaults to Mainnet
+    - `Config.default_config!(socket_path, :preview)` for Preview network
+  4. Run `elixir submit_tx.exs <transaction-CBOR-hex>` providing the CBOR hex as its single argument.
+
+  A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer.
+
+  ## Using Docker
+
+  This assumes you have Docker installed. No Elixir installation is required.
+
+  1. First, build the image:
+
+  ```
+  docker build -t xander .
+  ```
+
+  2. Ensure the `Config.default_config!` function inside the `submit_tx.exs` file matches the network being used:  
+    - `Config.default_config!(socket_path)` defaults to Mainnet  
+    - `Config.default_config!(socket_path, :preview)` for Preview network
+
+  3. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library)
+
+  Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to 
+  the container's default socket path (`/tmp/cardano-node-preview.socket`):
+
+  ```
+  docker run --rm \
+  -v /your/local/preview-node.socket:/tmp/cardano-node-preview.socket \
+  xander elixir submit_tx.exs <transaction-CBOR-hex>
+  ```
+
+  A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer.
+</details>

docs/running-natively.md

@@ -6,7 +6,7 @@ defmodule Xander.Transaction.Hash do
   require Logger
 
   @doc """
-  Extracts a transaction ID from a transaction CBOR hex
+  Extracts a transaction ID from a transaction CBOR hex.
   Returns the transaction ID as a string, or nil if there's an error.
 
   ## Examples

docs/running-via-docker.md

@@ -1,7 +1,3 @@
 defmodule Xander do
   @moduledoc false
-
-  def get_current_era do
-    Xander.Query.run(:get_current_era)
-  end
 end

docs/submitting-tx.md

@@ -3,7 +3,7 @@ defmodule Xander.MixProject do
 
   @description "An Elixir library for communicating with a Cardano node"
   @source_url "https://github.com/wowica/xander"
-  @version "0.1.1"
+  @version "0.2.0"
 
   def project do
     [