Run The Report

This page is the executable path for the May 2026 report. It prepares the bounded graph from the 85 transaction ids, then runs the SPARQL queries against that graph and the live UTxO snapshot.

The commands below assume a checkout of this repository. The only external secret is the Blockfrost project id used by tx-fetch. The provider responsibilities and API requests are listed on the Blockfrost provider page.

One-Time Environment

Set the Blockfrost key and, optionally, the working directory where CBOR and Turtle files will be written.

export BLOCKFROST_PROJECT_ID=mainnet...
export MAY_2026_WORK_DIR=/tmp/cardano-tx-tools-may-2026-lattice

Run One Query

Pass a single .rq path to run only that query. The setup script still prepares the graph first, so the query sees the same data as the published result.

bash docs/may-2026-amaru-lattice/setup.sh \
  docs/may-2026-amaru-lattice/swaps-and-exchange-rates/19-swap-receipts-and-rates.rq

Run All Queries

With no query arguments, the script discovers every report query under the May report directory and runs them in path order.

bash docs/may-2026-amaru-lattice/setup.sh

Path Setup

The script finds the repository root, the report directory, and the working directory. MAY_2026_WORK_DIR is intentionally outside the docs tree so fetched CBOR and generated Turtle do not pollute the published site.

ROOT="${CARDANO_TX_TOOLS_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
REPORT_DIR="${MAY_2026_REPORT_DIR:-$ROOT/docs/may-2026-amaru-lattice}"
WORK_DIR="${MAY_2026_WORK_DIR:-${TMPDIR:-/tmp}/cardano-tx-tools-may-2026-lattice}"
NETWORK="${CARDANO_NETWORK:-mainnet}"

Preflight

The fetch stage needs Blockfrost only for transaction CBOR. The txid boundary is fixed by the checked-in network-txs.txt file rendered on the report index.

if [[ -z "${BLOCKFROST_PROJECT_ID:-}" ]]; then
  echo "BLOCKFROST_PROJECT_ID is required for tx-fetch" >&2
  exit 2
fi

if [[ ! -f "$REPORT_DIR/network-txs.txt" ]]; then
  echo "missing report boundary file: $REPORT_DIR/network-txs.txt" >&2
  exit 2
fi

Fetch CBOR

tx-fetch reads the 85 txids from the boundary file, uses depth 0, and writes verified transaction CBOR files under $WORK_DIR/cbor.

mapfile -t TXIDS <"$REPORT_DIR/network-txs.txt"
mkdir -p "$WORK_DIR/ttl"

nix run "$ROOT#tx-fetch" -- \
  --out-dir "$WORK_DIR" \
  --network "$NETWORK" \
  --depth 0 \
  "${TXIDS[@]}"

Emit Turtle

tx-graph indexes the fetched CBOR set in memory and emits one Turtle file per transaction under $WORK_DIR/ttl.

rm -f "$WORK_DIR"/ttl/*.ttl
nix run "$ROOT#tx-graph" -- \
  --rules "$REPORT_DIR/rules.yaml" \
  --in-dir "$WORK_DIR/cbor" \
  --out-dir "$WORK_DIR/ttl"

Build Query Inputs

Every query runs against all emitted transaction Turtle files. The live snapshot is also loaded for the live-state comparison queries; queries that do not use it simply ignore those triples.

DATA_ARGS=()
for ttl in "$WORK_DIR"/ttl/*.ttl; do
  [[ -e "$ttl" ]] || {
    echo "tx-graph produced no Turtle files in $WORK_DIR/ttl" >&2
    exit 1
  }
  DATA_ARGS+=(--data "$ttl")
done
DATA_ARGS+=(--data "$REPORT_DIR/live-utxos.ttl")

Select Queries

Passing explicit query paths runs only those queries. Passing no query paths runs the whole report.

if (($#)); then
  QUERIES=("$@")
else
  mapfile -t QUERIES < <(find "$REPORT_DIR" -mindepth 2 -maxdepth 2 -name '*.rq' | sort)
fi

Execute SPARQL

If sparql is already on PATH, the script uses it directly. If not, it runs Apache Jena from Nix for the query invocation.

run_query() {
  local query="$1"
  if [[ "$query" != /* ]]; then
    query="$ROOT/$query"
  fi

  echo
  echo "== ${query#$ROOT/}"

  local cmd=(sparql "${DATA_ARGS[@]}" --query "$query")
  if command -v sparql >/dev/null 2>&1; then
    "${cmd[@]}"
  else
    local quoted
    printf -v quoted '%q ' "${cmd[@]}"
    nix-shell -p apache-jena --run "$quoted"
  fi
}

for query in "${QUERIES[@]}"; do
  run_query "$query"
done