Fix change output and default locking script function

Fix history. Fix invitation accept
Add autocomplete installation scripts to package.json. Update readme.
2026-05-04 10:00:49 +00:00 · 2026-05-04 09:28:23 +00:00 · 2026-05-04 05:09:40 +00:00 · 2026-05-04 05:04:28 +00:00 · 2026-05-04 04:45:31 +00:00 · 2026-04-27 12:47:02 +00:00
59 changed files with 4970 additions and 2326 deletions
--- a/p2pkh-template.json
+++ b/p2pkh-template.json
--- a/package-lock.json
+++ b/package-lock.json
@@ -11,11 +11,12 @@
      "dependencies": {
        "@bitauth/libauth": "^3.0.0",
        "@electrum-cash/protocol": "^2.3.1",
-        "@xo-cash/crypto": "file:../crypto",
+        "@generalprotocols/oracle-client": "^0.0.1-development.11945476152",
+        "@xo-cash/crypto": "^0.0.1",
        "@xo-cash/engine": "file:../engine",
        "@xo-cash/state": "file:../state",
-        "@xo-cash/templates": "file:../templates",
-        "@xo-cash/types": "file:../types",
+        "@xo-cash/templates": "^0.0.1",
+        "@xo-cash/types": "^0.0.1",
        "better-sqlite3": "^12.6.2",
        "clipboardy": "^5.1.0",
        "ink": "^6.6.0",
@@ -40,38 +41,6 @@
        "vitest": "^4.1.2"
      }
    },
-    "../crypto": {
-      "name": "@xo-cash/crypto",
-      "version": "0.0.1",
-      "license": "MIT",
-      "dependencies": {
-        "@bitauth/libauth": "^3.1.0-next.8",
-        "@xo-cash/primitives": "0.0.1",
-        "@xo-cash/types": "0.0.1"
-      },
-      "devDependencies": {
-        "@chalp/eslint-airbnb": "^1.3.0",
-        "@generalprotocols/cspell-dictionary": "^1.0.1",
-        "@stylistic/eslint-plugin": "^5.7.0",
-        "@typescript-eslint/eslint-plugin": "^8.53.1",
-        "@typescript-eslint/parser": "^8.53.1",
-        "@vitest/coverage-v8": "^4.0.17",
-        "@viz-kit/esbuild-analyzer": "^1.0.0",
-        "@xo-cash/eslint-config": "1.0.1",
-        "cspell": "^9.6.0",
-        "eslint": "^9.39.2",
-        "prettier": "^3.6.2",
-        "tsdown": "^0.20.0-beta.4",
-        "typedoc": "^0.28.16",
-        "typedoc-plugin-coverage": "^4.0.2",
-        "typescript": "^5.3.2",
-        "typescript-eslint": "^8.53.1",
-        "vitest": "^4.0.17"
-      },
-      "engines": {
-        "node": ">=18.0.0"
-      }
-    },
    "../engine": {
      "name": "@xo-cash/engine",
      "version": "0.0.1",
@@ -84,7 +53,8 @@
        "@electrum-cash/servers": "^3.1.0",
        "@xo-cash/crypto": "0.0.1",
        "@xo-cash/primitives": "0.0.1",
-        "@xo-cash/state": "0.0.1",
+        "@xo-cash/state": "0.0.2",
+        "@xo-cash/templates": "0.0.1",
        "@xo-cash/types": "0.0.1",
        "@xo-cash/utils": "0.0.1",
        "eventemitter3": "^5.0.1"
@@ -107,18 +77,15 @@
        "typescript": "^5.3.2",
        "typescript-eslint": "^8.53.1",
        "vitest": "^4.0.17"
-      },
-      "engines": {
-        "node": ">=18.0.0"
      }
    },
    "../state": {
      "name": "@xo-cash/state",
-      "version": "0.0.1",
+      "version": "0.0.2",
      "license": "MIT",
      "dependencies": {
        "@bitauth/libauth": "^3.1.0-next.8",
-        "@xo-cash/types": "0.0.1-development.13730885533",
+        "@xo-cash/types": "0.0.1",
        "@xo-cash/utils": "0.0.1",
        "better-sqlite3": "^12.5.0",
        "idb": "^8.0.3",
@@ -146,60 +113,6 @@
        "vitest": "^4.0.17"
      }
    },
-    "../templates": {
-      "name": "@xo-cash/templates",
-      "version": "0.0.1",
-      "license": "MIT",
-      "dependencies": {
-        "@xo-cash/types": "0.0.1-development.13504604083"
-      },
-      "devDependencies": {
-        "@chalp/eslint-airbnb": "^1.3.0",
-        "@generalprotocols/cspell-dictionary": "^1.0.1",
-        "@stylistic/eslint-plugin": "^5.7.0",
-        "@typescript-eslint/eslint-plugin": "^8.53.1",
-        "@typescript-eslint/parser": "^8.53.1",
-        "@vitest/coverage-v8": "^4.0.17",
-        "@viz-kit/esbuild-analyzer": "^1.0.0",
-        "@xo-cash/eslint-config": "1.0.1",
-        "cspell": "^9.6.0",
-        "eslint": "^9.39.2",
-        "prettier": "^3.6.2",
-        "tsdown": "^0.20.0-beta.4",
-        "typedoc": "^0.28.16",
-        "typedoc-plugin-coverage": "^4.0.2",
-        "typescript": "^5.3.2",
-        "typescript-eslint": "^8.53.1",
-        "vitest": "^4.0.17"
-      }
-    },
-    "../types": {
-      "name": "@xo-cash/types",
-      "version": "0.0.1",
-      "license": "MIT",
-      "dependencies": {
-        "@bitauth/libauth": "^3.1.0-next.8"
-      },
-      "devDependencies": {
-        "@chalp/eslint-airbnb": "^1.3.0",
-        "@generalprotocols/cspell-dictionary": "^1.0.1",
-        "@stylistic/eslint-plugin": "^5.7.0",
-        "@typescript-eslint/eslint-plugin": "^8.53.1",
-        "@typescript-eslint/parser": "^8.53.1",
-        "@vitest/coverage-v8": "^4.0.17",
-        "@viz-kit/esbuild-analyzer": "^1.0.0",
-        "@xo-cash/eslint-config": "1.0.1",
-        "cspell": "^9.6.0",
-        "eslint": "^9.39.2",
-        "prettier": "^3.6.2",
-        "tsdown": "^0.20.0-beta.4",
-        "typedoc": "^0.28.16",
-        "typedoc-plugin-coverage": "^4.0.2",
-        "typescript": "^5.3.2",
-        "typescript-eslint": "^8.53.1",
-        "vitest": "^4.0.17"
-      }
-    },
    "node_modules/@alcalzone/ansi-tokenize": {
      "version": "0.2.4",
      "resolved": "https://registry.npmjs.org/@alcalzone/ansi-tokenize/-/ansi-tokenize-0.2.4.tgz",
@@ -330,6 +243,16 @@
        "ws": "^8.13.0"
      }
    },
+    "node_modules/@generalprotocols/oracle-client": {
+      "version": "0.0.1-development.11945476152",
+      "resolved": "https://registry.npmjs.org/@generalprotocols/oracle-client/-/oracle-client-0.0.1-development.11945476152.tgz",
+      "integrity": "sha512-1Q43NfacrVfSbatCREzIX7U3DgACBUegNjV977y+pql+Fve03bOyTiUQClevymCi7M3T6mCyMzSEGT8zA6EZtQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@bitauth/libauth": "^3.0.0",
+        "zod": "^4.1.12"
+      }
+    },
    "node_modules/@jridgewell/resolve-uri": {
      "version": "3.1.2",
      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
@@ -960,24 +883,77 @@
      }
    },
    "node_modules/@xo-cash/crypto": {
-      "resolved": "../crypto",
-      "link": true
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@xo-cash/crypto/-/crypto-0.0.1.tgz",
+      "integrity": "sha512-ZIa9MHAVCBJqo5uxyx/Tx/jTSyyJw1cfYfI48gEHqBIl5wyyxiZDx4eZvVWSr8uKgS5Tm3FXUkKQybvk5QGRIQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@bitauth/libauth": "^3.1.0-next.8",
+        "@xo-cash/primitives": "0.0.1",
+        "@xo-cash/types": "0.0.1"
+      }
+    },
+    "node_modules/@xo-cash/crypto/node_modules/@bitauth/libauth": {
+      "version": "3.1.0-next.8",
+      "resolved": "https://registry.npmjs.org/@bitauth/libauth/-/libauth-3.1.0-next.8.tgz",
+      "integrity": "sha512-Pm+Ju+YP3JeBLLTiVrBnia2wwE4G17r4XqpvPRMcklElJTe8J6x3JgKRg1by0Xm3ZY6UFxACkEAoSA+x419/zA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
    },
    "node_modules/@xo-cash/engine": {
      "resolved": "../engine",
      "link": true
    },
+    "node_modules/@xo-cash/primitives": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@xo-cash/primitives/-/primitives-0.0.1.tgz",
+      "integrity": "sha512-medxVK9Sawj7oIDhWvTjTgzwf6BjGao6CXtQYJOUFi6NOO1eclb1PDjEmkG/4NeK3v7LQIN8QS60mTAGyS9FXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@bitauth/libauth": "^3.1.0-next.8"
+      }
+    },
+    "node_modules/@xo-cash/primitives/node_modules/@bitauth/libauth": {
+      "version": "3.1.0-next.8",
+      "resolved": "https://registry.npmjs.org/@bitauth/libauth/-/libauth-3.1.0-next.8.tgz",
+      "integrity": "sha512-Pm+Ju+YP3JeBLLTiVrBnia2wwE4G17r4XqpvPRMcklElJTe8J6x3JgKRg1by0Xm3ZY6UFxACkEAoSA+x419/zA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
    "node_modules/@xo-cash/state": {
      "resolved": "../state",
      "link": true
    },
    "node_modules/@xo-cash/templates": {
-      "resolved": "../templates",
-      "link": true
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@xo-cash/templates/-/templates-0.0.1.tgz",
+      "integrity": "sha512-v5f0YeH9Bw6lNThdE0fI878T4L2jbM8RI1quxdKxnvqHn9hu2jzebqvveEB2TfJWG3sP1GpE1go0Yn87R4sXfw==",
+      "license": "MIT",
+      "dependencies": {
+        "@xo-cash/types": "0.0.1"
+      }
    },
    "node_modules/@xo-cash/types": {
-      "resolved": "../types",
-      "link": true
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@xo-cash/types/-/types-0.0.1.tgz",
+      "integrity": "sha512-BMwh2Y9+LqnTXYmdA7Nxi1NuK+AcsNWFoFGJVAvuY5TBfsbNIzWppjmrI2fAyj/RlSE3tATMxam+6CJb3RnDIA==",
+      "license": "MIT",
+      "dependencies": {
+        "@bitauth/libauth": "^3.1.0-next.8"
+      }
+    },
+    "node_modules/@xo-cash/types/node_modules/@bitauth/libauth": {
+      "version": "3.1.0-next.8",
+      "resolved": "https://registry.npmjs.org/@bitauth/libauth/-/libauth-3.1.0-next.8.tgz",
+      "integrity": "sha512-Pm+Ju+YP3JeBLLTiVrBnia2wwE4G17r4XqpvPRMcklElJTe8J6x3JgKRg1by0Xm3ZY6UFxACkEAoSA+x419/zA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
    },
    "node_modules/ansi-escapes": {
      "version": "7.2.0",
--- a/package.json
+++ b/package.json
@@ -19,7 +19,11 @@
    "nuke": "tsx scripts/rm-dbs.ts",
    "nuke:dry": "tsx scripts/rm-dbs.ts --dry",
    "format": "prettier --write \"**/*.{js,ts,md,json}\" --ignore-path .gitignore",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "autocomplete:install": "node dist/cli/index.js completions bash --install",
+    "autocomplete:install:bash": "node dist/cli/index.js completions bash --install",
+    "autocomplete:install:zsh": "node dist/cli/index.js completions zsh --install",
+    "autocomplete:install:fish": "node dist/cli/index.js completions fish --install"
  },
  "keywords": [
    "crypto",
@@ -33,11 +37,12 @@
  "dependencies": {
    "@bitauth/libauth": "^3.0.0",
    "@electrum-cash/protocol": "^2.3.1",
-    "@xo-cash/crypto": "file:../crypto",
+    "@generalprotocols/oracle-client": "^0.0.1-development.11945476152",
+    "@xo-cash/crypto": "^0.0.1",
    "@xo-cash/engine": "file:../engine",
    "@xo-cash/state": "file:../state",
-    "@xo-cash/templates": "file:../templates",
-    "@xo-cash/types": "file:../types",
+    "@xo-cash/templates": "^0.0.1",
+    "@xo-cash/types": "^0.0.1",
    "better-sqlite3": "^12.6.2",
    "clipboardy": "^5.1.0",
    "ink": "^6.6.0",
--- a/readme.md
+++ b/readme.md
@@ -0,0 +1,107 @@
+# XO-CLI & XO-TUI
+
+## Installation
+
+### Full Installation
+```bash
+# Create a new directory since we are going to be pulling in engine too
+mkdir xo-terminal && cd xo-terminal
+
+# ----- Start Engine Setup -----
+# Clone the Engine Repo (Note, this uses harvey's fork of the engine repo to access the cli-test branch)
+git clone git@gitlab.com:Harvmaster/engine.git
+
+# Move into teh engine directory
+cd engine
+
+# Checkout the cli-test branch
+git checkout cli-test
+
+# Install the dependencies
+npm ci
+
+# Build the engine
+npm run build
+# ----- End Engine Setup -----
+
+# Move back to the top level directory
+cd ..
+
+# ----- Start State Setup -----
+# Clone the State Repo
+git clone git@gitlab.com:Harvmaster/state.git
+
+# Move into the state directory
+cd state
+
+git checkout in-memory-adapter
+
+# Install the dependencies
+npm ci
+
+# Build the state
+npm run build
+# ----- End State Setup -----
+
+# Move back to the top level directory
+cd ..
+
+# ----- Start CLI Setup -----
+# Clone the CLI Repo
+git clone git@git.harvmaster.com:Harvmaster/xo-cli.git 
+
+# Move into the cli directory
+cd xo-cli
+
+# Install the dependencies
+npm ci
+
+# Build the cli
+npm run build
+# ----- End CLI Setup -----
+```
+
+### Run TUI in dev mode
+
+```bash
+npm run dev
+```
+
+### Install globally
+
+```bash
+# (From the xo-cli directory)
+npm install -g .
+```
+
+### Install autocomplete completions (From the xo-cli directory)
+
+#### Install for bash
+```bash
+npm run autocomplete:install:bash
+```
+
+#### Install for zsh
+```bash
+npm run autocomplete:install:zsh
+```
+
+#### Install for fish
+```bash
+npm run autocomplete:install:fish
+```
+
+### Run the CLI
+```bash
+# If globally installed (Not really usable if not globally installed)
+xo-cli
+```
+
+### Run the TUI
+```bash
+# If globally installed
+xo-tui
+
+# If not globally installed
+npm run dev
+```
--- a/scripts/template-to-json.ts
+++ b/scripts/template-to-json.ts
@@ -69,7 +69,9 @@ function resolveExportedValue(
  }

  if (keys.length === 0) {
-    console.error("No suitable exports found (need default or a non-function export).");
+    console.error(
+      "No suitable exports found (need default or a non-function export).",
+    );
  } else {
    console.error(
      `Multiple data exports found; pass exportName. Candidates: ${keys.join(", ")}`,
--- a/src/cli/README.md
+++ b/src/cli/README.md
@@ -11,11 +11,11 @@ There are two global commands after install:

 Wallet state lives under **`~/.config/xo-cli/`** (XDG-style), so you can run commands from any directory:

-| Path | Purpose |
-|------|---------|
-| `~/.config/xo-cli/mnemonics/` | Mnemonic files (`mnemonic-*`) |
-| `~/.config/xo-cli/data/` | Engine DB (`xo-wallet.db`) and invitation storage (`xo-invitations.db`) |
-| `~/.config/xo-cli/.wallet` | Last-used mnemonic reference (so `-m` can be omitted) |
+| Path                          | Purpose                                                                 |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `~/.config/xo-cli/mnemonics/` | Mnemonic files (`mnemonic-*`)                                           |
+| `~/.config/xo-cli/data/`      | Engine DB (`xo-wallet.db`) and invitation storage (`xo-invitations.db`) |
+| `~/.config/xo-cli/.wallet`    | Last-used mnemonic reference (so `-m` can be omitted)                   |

 **Local to your shell’s current directory:** template JSON paths, invitation JSON you create/import, and any path you pass explicitly (e.g. `-m /abs/path/to/file`).

@@ -41,11 +41,11 @@ npx tsx src/index.ts   # TUI

 ### Environment variables (TUI / `xo-tui`)

-| Variable | Default |
-|----------|---------|
-| `SYNC_SERVER_URL` | `http://localhost:3000` |
-| `DB_PATH` | `~/.config/xo-cli/data` |
-| `DB_FILENAME` | `xo-wallet.db` |
+| Variable                  | Default                                   |
+| ------------------------- | ----------------------------------------- |
+| `SYNC_SERVER_URL`         | `http://localhost:3000`                   |
+| `DB_PATH`                 | `~/.config/xo-cli/data`                   |
+| `DB_FILENAME`             | `xo-wallet.db`                            |
 | `INVITATION_STORAGE_PATH` | `~/.config/xo-cli/data/xo-invitations.db` |

 ## Getting Started
@@ -82,11 +82,12 @@ xo-cli resource list

 ## Global Options (`xo-cli`)

-| Flag | Description |
-|------|-------------|
+| Flag                           | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
 | `-m`, `--mnemonic-file <file>` | Mnemonic file (basename, cwd-relative, or absolute) |
-| `-v`, `--verbose` | Verbose output |
-| `-h`, `--help` | Help |
+| `-o`, `--output <filename>`    | Output filename (used by `mnemonic create`/`import`) |
+| `-v`, `--verbose`              | Verbose output                                      |
+| `-h`, `--help`                 | Help                                                |

 Advanced: you can pass `--database-path`, `--database-filename`, and `--invitation-storage-path` to override the defaults under `~/.config/xo-cli/data/` (see `src/cli/index.ts`).

@@ -98,6 +99,7 @@ Advanced: you can pass `--database-path`, `--database-filename`, and `--invitati
 xo-cli mnemonic create
 xo-cli mnemonic import <seed words...>
 xo-cli mnemonic list
+xo-cli mnemonic expose <mnemonic-file>
 ```

 ### `template` — Manage Templates
@@ -139,20 +141,21 @@ xo-cli invitation sign <invitation-id>
 xo-cli invitation broadcast <invitation-id>
 xo-cli invitation requirements <invitation-id>
 xo-cli invitation import <invitation-file>
+xo-cli invitation inspect <invitation-file>
 xo-cli invitation list
 ```

 **Create / append options:**

-| Flag | Description |
-|------|-------------|
-| `-var-<name> <value>` | Template variable |
-| `--add-input <txhash:vout>` | Inputs (comma-separated) |
-| `--add-output <id>` | Override outputs (omit to auto-discover) |
-| `--auto-inputs` | Auto-select UTXOs |
-| `-role <role>` | Role for variables / bytecode |
-| `--sign` | Auto-sign when complete |
-| `--broadcast` | Auto-broadcast (implies `--sign`) |
+| Flag                        | Description                              |
+| --------------------------- | ---------------------------------------- |
+| `-var-<name> <value>`       | Template variable                        |
+| `--add-input <txhash:vout>` | Inputs (comma-separated)                 |
+| `--add-output <id>`         | Override outputs (omit to auto-discover) |
+| `--auto-inputs`             | Auto-select UTXOs                        |
+| `-role <role>`              | Role for variables / bytecode            |
+| `--sign`                    | Auto-sign when complete                  |
+| `--broadcast`               | Auto-broadcast (implies `--sign`)        |

 Invitation JSON files from `create` / `append` are written to the **current working directory**.

@@ -186,7 +189,7 @@ xo-cli completions fish | source

 ## File Conventions

-| Location | Purpose |
-|----------|---------|
-| `~/.config/xo-cli/` | Global wallet state |
-| `./` (cwd) | Templates, invitation JSON, explicit paths |
+| Location            | Purpose                                    |
+| ------------------- | ------------------------------------------ |
+| `~/.config/xo-cli/` | Global wallet state                        |
+| `./` (cwd)          | Templates, invitation JSON, explicit paths |
--- a/src/cli/arguments.ts
+++ b/src/cli/arguments.ts
@@ -19,24 +19,27 @@ import { z } from "zod";
 * @param args - The CLI args to convert.
 * @returns The key-value object.
 */
-export function convertArgsToObject(args: string[]): { args: string[], options: Record<string, string> } {
+export function convertArgsToObject(args: string[]): {
+  args: string[];
+  options: Record<string, string>;
+} {
  // Map of single-character short flags to their canonical long names
  const shortToFull: Record<string, string> = {
-    'm': 'mnemonicFile',
-    'o': 'output',
-    'v': 'verbose',
-    'h': 'help',
+    m: "mnemonicFile",
+    o: "output",
+    v: "verbose",
+    h: "help",
  };

  // Flags that are always boolean and never consume the next argument as a value.
  // Uses the canonical (expanded) names so the check works after short-form resolution.
  const booleanFlags = new Set<string>([
-    'verbose',
-    'help',
-    'autoInputs',
-    'sign',
-    'broadcast',
-    'install',
+    "verbose",
+    "help",
+    "autoInputs",
+    "sign",
+    "broadcast",
+    "install",
  ]);

  const positionalArgs: string[] = [];
@@ -55,7 +58,9 @@ export function convertArgsToObject(args: string[]): { args: string[], options:
    // - Remove the leading `-`s
    // - Convert kebab-case to camelCase
    // - Expand known short forms to their full names
-    let key = arg.replace(/^-+/, "").replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    let key = arg
+      .replace(/^-+/, "")
+      .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
    key = shortToFull[key] ?? key;

    // Known boolean flags never take a value
--- a/src/cli/autocomplete/complete.ts
+++ b/src/cli/autocomplete/complete.ts
@@ -27,7 +27,11 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";

-import { getDataDir, getMnemonicsDir, getWalletConfigPath } from "../../utils/paths.js";
+import {
+  getDataDir,
+  getMnemonicsDir,
+  getWalletConfigPath,
+} from "../../utils/paths.js";
 import { loadMnemonic } from "../mnemonic.js";
 import { Storage } from "../../services/storage.js";
 import { COMMAND_TREE } from "./completions.js";
@@ -56,7 +60,9 @@ async function getEngineModule() {
 */
 function outputCompletions(items: readonly string[], prefix?: string): void {
  const filtered = prefix
-    ? items.filter((item) => item.toLowerCase().startsWith(prefix.toLowerCase()))
+    ? items.filter((item) =>
+        item.toLowerCase().startsWith(prefix.toLowerCase()),
+      )
    : items;

  for (const item of filtered) {
@@ -71,7 +77,9 @@ function outputCompletions(items: readonly string[], prefix?: string): void {
 function listMnemonics(prefix?: string): void {
  try {
    const mnemonicsDir = getMnemonicsDir();
-    const files = readdirSync(mnemonicsDir).filter((f) => f.startsWith("mnemonic-"));
+    const files = readdirSync(mnemonicsDir).filter((f) =>
+      f.startsWith("mnemonic-"),
+    );
    outputCompletions(files, prefix);
  } catch {
    // Silently fail - no completions available
@@ -155,7 +163,13 @@ async function listTemplates(prefix?: string): Promise<void> {
 * Resolves a template by name or ID.
 */
 async function resolveTemplate(
-  engine: Awaited<ReturnType<Awaited<ReturnType<typeof getOfflineEngineModule>>["tryCreateOfflineEngine"]>>,
+  engine: Awaited<
+    ReturnType<
+      Awaited<
+        ReturnType<typeof getOfflineEngineModule>
+      >["tryCreateOfflineEngine"]
+    >
+  >,
  templateQuery: string,
 ) {
  if (!engine) return null;
@@ -165,7 +179,9 @@ async function resolveTemplate(

  // Try exact match on name or ID
  let template = templates.find(
-    (t) => t.name === templateQuery || generateTemplateIdentifier(t) === templateQuery,
+    (t) =>
+      t.name === templateQuery ||
+      generateTemplateIdentifier(t) === templateQuery,
  );

  // Try partial match on name
@@ -181,7 +197,10 @@ async function resolveTemplate(
 /**
 * Lists actions for a specific template.
 */
-async function listActions(templateQuery: string, prefix?: string): Promise<void> {
+async function listActions(
+  templateQuery: string,
+  prefix?: string,
+): Promise<void> {
  const mnemonic = getCurrentMnemonic();
  if (!mnemonic) return;

@@ -210,7 +229,11 @@ async function listActions(templateQuery: string, prefix?: string): Promise<void
 * Lists fields (actions, transactions, outputs, etc.) for a specific template category.
 * Used for completing the 3rd argument of `template inspect <category> <template> <field>`.
 */
-async function listFields(category: string, templateQuery: string, prefix?: string): Promise<void> {
+async function listFields(
+  category: string,
+  templateQuery: string,
+  prefix?: string,
+): Promise<void> {
  const mnemonic = getCurrentMnemonic();
  if (!mnemonic) return;

@@ -300,7 +323,9 @@ async function listResources(prefix?: string): Promise<void> {

  try {
    const utxos = await engine.listUnspentOutputsData();
-    const outpoints = utxos.map((u) => `${u.outpointTransactionHash}:${u.outpointIndex}`);
+    const outpoints = utxos.map(
+      (u) => `${u.outpointTransactionHash}:${u.outpointIndex}`,
+    );
    outputCompletions(outpoints, prefix);
  } finally {
    await engine.stop();
--- a/src/cli/autocomplete/completions.ts
+++ b/src/cli/autocomplete/completions.ts
@@ -19,7 +19,12 @@
 *   xo-cli completions fish --install
 */

-import { existsSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  readFileSync,
+  appendFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -40,7 +45,16 @@ const MNEMONIC_SUBS = ["create", "import", "list", "expose"];
 /** Subcommands for the template command */
 const TEMPLATE_SUBS = ["import", "list", "inspect", "set-default"];
 /** Subcommands for the invitation command */
-const INVITATION_SUBS = ["create", "append", "sign", "broadcast", "requirements", "import", "inspect", "list"];
+const INVITATION_SUBS = [
+  "create",
+  "append",
+  "sign",
+  "broadcast",
+  "requirements",
+  "import",
+  "inspect",
+  "list",
+];
 /** Subcommands for the resource command */
 const RESOURCE_SUBS = ["list", "unreserve", "unreserve-all"];
 /** Subcommands for the completions command */
@@ -57,7 +71,16 @@ export const COMMAND_TREE = {
 } as const;

 /** Global option flags available on every command. */
-const GLOBAL_OPTIONS = ["-h", "--help", "-v", "--verbose", "-m", "--mnemonic-file", "-o", "--output"];
+const GLOBAL_OPTIONS = [
+  "-h",
+  "--help",
+  "-v",
+  "--verbose",
+  "-m",
+  "--mnemonic-file",
+  "-o",
+  "--output",
+];

 /**
 * Gets the path to the scripts directory containing shell templates.
@@ -92,13 +115,22 @@ function loadAndProcessTemplate(templateName: string, binName: string): string {
  content = content.replace(/\{\{OPTIONS\}\}/g, options);
  content = content.replace(/\{\{MNEMONIC_SUBS\}\}/g, MNEMONIC_SUBS.join(" "));
  content = content.replace(/\{\{TEMPLATE_SUBS\}\}/g, TEMPLATE_SUBS.join(" "));
-  content = content.replace(/\{\{INVITATION_SUBS\}\}/g, INVITATION_SUBS.join(" "));
+  content = content.replace(
+    /\{\{INVITATION_SUBS\}\}/g,
+    INVITATION_SUBS.join(" "),
+  );
  content = content.replace(/\{\{RESOURCE_SUBS\}\}/g, RESOURCE_SUBS.join(" "));

  // Fish-specific placeholders
  if (templateName.endsWith(".fish")) {
-    content = content.replace(/\{\{TOP_LEVEL_COMMANDS\}\}/g, generateFishTopLevelCommands(binName));
-    content = content.replace(/\{\{STATIC_SUBCOMMANDS\}\}/g, generateFishStaticSubcommands(binName));
+    content = content.replace(
+      /\{\{TOP_LEVEL_COMMANDS\}\}/g,
+      generateFishTopLevelCommands(binName),
+    );
+    content = content.replace(
+      /\{\{STATIC_SUBCOMMANDS\}\}/g,
+      generateFishStaticSubcommands(binName),
+    );
  }

  return content;
@@ -110,7 +142,9 @@ function loadAndProcessTemplate(templateName: string, binName: string): string {
 function generateFishTopLevelCommands(binName: string): string {
  const lines: string[] = [];
  for (const cmd of Object.keys(COMMAND_TREE)) {
-    lines.push(`complete -c ${binName} -n "__fish_use_subcommand" -a "${cmd}" -d "${cmd} command"`);
+    lines.push(
+      `complete -c ${binName} -n "__fish_use_subcommand" -a "${cmd}" -d "${cmd} command"`,
+    );
  }
  return lines.join("\n");
 }
@@ -122,7 +156,9 @@ function generateFishStaticSubcommands(binName: string): string {
  const lines: string[] = [];
  for (const [cmd, subs] of Object.entries(COMMAND_TREE)) {
    for (const sub of subs) {
-      lines.push(`complete -c ${binName} -n "__fish_seen_subcommand_from ${cmd}; and not __fish_seen_subcommand_from ${subs.join(" ")}" -a "${sub}" -d "${cmd} ${sub}"`);
+      lines.push(
+        `complete -c ${binName} -n "__fish_seen_subcommand_from ${cmd}; and not __fish_seen_subcommand_from ${subs.join(" ")}" -a "${sub}" -d "${cmd} ${sub}"`,
+      );
    }
  }
  return lines.join("\n");
@@ -163,7 +199,10 @@ const generators: Record<ShellType, (binName: string) => string> = {
 /**
 * Shell config file paths and eval commands for each shell type.
 */
-const shellConfigs: Record<ShellType, { configFile: string; evalCommand: (binName: string) => string }> = {
+const shellConfigs: Record<
+  ShellType,
+  { configFile: string; evalCommand: (binName: string) => string }
+> = {
  bash: {
    configFile: join(homedir(), ".bashrc"),
    evalCommand: (binName) => `eval "$(${binName} completions bash)"`,
@@ -199,7 +238,8 @@ function installCompletions(shell: ShellType, binName: string): boolean {
  }

  // Append the completion line
-  const newLine = existingContent.endsWith("\n") || existingContent === "" ? "" : "\n";
+  const newLine =
+    existingContent.endsWith("\n") || existingContent === "" ? "" : "\n";
  const completionBlock = `${newLine}\n# ${binName} shell completions\n${evalCommand}\n`;

  appendFileSync(config.configFile, completionBlock);
@@ -227,14 +267,26 @@ export function handleCompletionsCommand(
    console.error(`Usage: ${binName} completions <${supported}> [--install]`);
    console.error("");
    console.error("Examples:");
-    console.error(`  eval "$(${binName} completions bash)"   # Output to stdout (add to ~/.bashrc)`);
-    console.error(`  eval "$(${binName} completions zsh)"    # Output to stdout (add to ~/.zshrc)`);
-    console.error(`  ${binName} completions fish | source    # Output to stdout (add to fish config)`);
+    console.error(
+      `  eval "$(${binName} completions bash)"   # Output to stdout (add to ~/.bashrc)`,
+    );
+    console.error(
+      `  eval "$(${binName} completions zsh)"    # Output to stdout (add to ~/.zshrc)`,
+    );
+    console.error(
+      `  ${binName} completions fish | source    # Output to stdout (add to fish config)`,
+    );
    console.error("");
    console.error("Install directly to shell config:");
-    console.error(`  ${binName} completions bash --install   # Appends to ~/.bashrc`);
-    console.error(`  ${binName} completions zsh --install    # Appends to ~/.zshrc`);
-    console.error(`  ${binName} completions fish --install   # Appends to ~/.config/fish/config.fish`);
+    console.error(
+      `  ${binName} completions bash --install   # Appends to ~/.bashrc`,
+    );
+    console.error(
+      `  ${binName} completions zsh --install    # Appends to ~/.zshrc`,
+    );
+    console.error(
+      `  ${binName} completions fish --install   # Appends to ~/.config/fish/config.fish`,
+    );
    process.exit(1);
  }

--- a/src/cli/autocomplete/offline-engine.ts
+++ b/src/cli/autocomplete/offline-engine.ts
@@ -8,7 +8,11 @@
 * and instead constructs the engine directly with an in-memory blockchain provider.
 */

-import { BlockchainMonitor, Engine, InMemoryBlockchainProvider } from "@xo-cash/engine";
+import {
+  BlockchainMonitor,
+  Engine,
+  InMemoryBlockchainProvider,
+} from "@xo-cash/engine";
 import { createStorageAdapter, State, StorageType } from "@xo-cash/state";
 import { convertMnemonicToSeedBytes } from "@xo-cash/crypto";
 import { binToHex, hash256 } from "@bitauth/libauth";
--- a/src/cli/cli-utils.ts
+++ b/src/cli/cli-utils.ts
@@ -1,44 +0,0 @@
-import util from "node:util";
-
-/**
- * Text formatting utilities for the CLI.
- * 
- * Uses ANSI escape codes to format text.
- * 
- * AI Generated links:
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Formatting
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Cursor_movement
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Screen_manipulation
- */
-
-const BOLD = "\x1b[1m";
-export const bold = (text: string) => `${BOLD}${text}${RESET}`;
-
-const DIM = "\x1b[2m";
-export const dim = (text: string) => `${DIM}${text}${RESET}`;
-
-const UNDERLINE = "\x1b[4m";
-export const underline = (text: string) => `${UNDERLINE}${text}${RESET}`;
-
-const INVERSE = "\x1b[7m";
-export const inverse = (text: string) => `${INVERSE}${text}${RESET}`;
-
-const HIDDEN = "\x1b[8m";
-export const hidden = (text: string) => `${HIDDEN}${text}${RESET}`;
-
-const STRIKETHROUGH = "\x1b[9m";
-export const strikethrough = (text: string) => `${STRIKETHROUGH}${text}${RESET}`;
-
-const RESET = "\x1b[0m";
-export const reset = (text: string) => `${RESET}${text}${RESET}`;
-
-export const formatObject = (obj: unknown) => {
-  return util.inspect(obj, {
-    depth: null,
-    colors: true,
-    compact: false
-  });
-};
--- a/src/cli/commands/invitation.ts
+++ b/src/cli/commands/invitation.ts
@@ -3,7 +3,7 @@ import path from "path";
 import { generateTemplateIdentifier } from "@xo-cash/engine";
 import { binToHex, hexToBin } from "@bitauth/libauth";

-import { bold, dim, formatObject } from "../cli-utils.js";
+import { bold, dim, formatObject } from "../utils.js";
 import type { CommandDependencies, CommandIO } from "./types.js";
 import { CommandError } from "./types.js";
 import type { Invitation } from "../../services/invitation.js";
@@ -73,14 +73,16 @@ async function buildAppendParams(
  // --- Inputs ---
  // Accepts comma-separated <txhash>:<vout> pairs via --add-input,
  // OR automatic selection via --auto-inputs.
-  let inputs: { outpointTransactionHash: Uint8Array; outpointIndex: number }[] = [];
+  let inputs: { outpointTransactionHash: Uint8Array; outpointIndex: number }[] =
+    [];

  if (options["autoInputs"] === "true") {
    // Auto-select UTXOs using the greedy algorithm from invitation-flow.
    const suitableResources = await invitation.findSuitableResources();
    const selectable = mapUnspentOutputsToSelectable(suitableResources);

-    const requiredWithFee = (await invitation.getSatsOut().catch(() => 0n)) + DEFAULT_FEE;
+    const requiredWithFee =
+      (await invitation.getSatsOut().catch(() => 0n)) + DEFAULT_FEE;
    autoSelectGreedyUtxos(selectable, requiredWithFee);

    inputs = selectable
@@ -99,12 +101,16 @@ async function buildAppendParams(
    inputs = options["addInput"].split(",").map((entry) => {
      const separatorIndex = entry.lastIndexOf(":");
      if (separatorIndex === -1) {
-        throw new Error(`Invalid input format "${entry}". Expected <txhash>:<vout> (e.g. abc123:0)`);
+        throw new Error(
+          `Invalid input format "${entry}". Expected <txhash>:<vout> (e.g. abc123:0)`,
+        );
      }
      const txHash = entry.substring(0, separatorIndex);
      const vout = parseInt(entry.substring(separatorIndex + 1), 10);
      if (!txHash || isNaN(vout)) {
-        throw new Error(`Invalid input format "${entry}". Expected <txhash>:<vout> (e.g. abc123:0)`);
+        throw new Error(
+          `Invalid input format "${entry}". Expected <txhash>:<vout> (e.g. abc123:0)`,
+        );
      }
      return {
        outpointTransactionHash: hexToBin(txHash),
@@ -112,7 +118,9 @@ async function buildAppendParams(
      };
    });
  }
-  deps.io.verbose(`Inputs: ${formatObject(inputs.map(i => ({ txHash: binToHex(i.outpointTransactionHash), vout: i.outpointIndex })))}`);
+  deps.io.verbose(
+    `Inputs: ${formatObject(inputs.map((i) => ({ txHash: binToHex(i.outpointTransactionHash), vout: i.outpointIndex })))}`,
+  );

  // --- Outputs ---
  // When --add-output is provided, use those identifiers explicitly.
@@ -135,7 +143,9 @@ async function buildAppendParams(
    }
    outputIdentifiers = [...discovered];
    if (outputIdentifiers.length > 0) {
-      deps.io.verbose(`Auto-discovered output(s) from template: ${outputIdentifiers.join(", ")}`);
+      deps.io.verbose(
+        `Auto-discovered output(s) from template: ${outputIdentifiers.join(", ")}`,
+      );
    }
  }

@@ -151,40 +161,58 @@ async function buildAppendParams(
    }
  }

-  const template = await deps.app.engine.getTemplate(invitation.data.templateIdentifier);
+  const template = await deps.app.engine.getTemplate(
+    invitation.data.templateIdentifier,
+  );

  const outputs: any[] = await Promise.all(
    outputIdentifiers.map(async (outputId) => {
      // Try variable-based resolution first (e.g. sendSatoshis → recipientLockingscript)
      const providedHex = template
-        ? resolveProvidedLockingBytecodeHex(template, outputId, variableValuesByIdentifier)
+        ? resolveProvidedLockingBytecodeHex(
+            template,
+            outputId,
+            variableValuesByIdentifier,
+          )
        : undefined;

-      const lockingBytecodeHex = providedHex
-        ?? await invitation.generateLockingBytecode(outputId, roleIdentifier);
+      const lockingBytecodeHex =
+        providedHex ??
+        (await invitation.generateLockingBytecode(outputId, roleIdentifier));

-      deps.io.verbose(`Locking bytecode for output "${outputId}": ${lockingBytecodeHex}`);
+      deps.io.verbose(
+        `Locking bytecode for output "${outputId}": ${lockingBytecodeHex}`,
+      );
      return {
        outputIdentifier: outputId,
        lockingBytecode: new Uint8Array(Buffer.from(lockingBytecodeHex, "hex")),
      };
    }),
  );
-  deps.io.verbose(`Outputs: ${formatObject(outputs.map(o => o.outputIdentifier))}`);
+  deps.io.verbose(
+    `Outputs: ${formatObject(outputs.map((o) => o.outputIdentifier))}`,
+  );

  // --- Auto change output ---
  // When inputs are provided, look up each UTXO's value, compute the
  // required sats, and return the excess minus fees back to the user.
  if (inputs.length > 0) {
    const allUtxos = await deps.app.engine.listUnspentOutputsData();
-    const utxoMap = new Map(allUtxos.map(u => [`${u.outpointTransactionHash}:${u.outpointIndex}`, u]));
+    const utxoMap = new Map(
+      allUtxos.map((u) => [
+        `${u.outpointTransactionHash}:${u.outpointIndex}`,
+        u,
+      ]),
+    );

    let totalInputSats = 0n;
    for (const input of inputs) {
      const txHashHex = binToHex(input.outpointTransactionHash);
      const utxo = utxoMap.get(`${txHashHex}:${input.outpointIndex}`);
      if (!utxo) {
-        deps.io.err(`UTXO not found: ${txHashHex}:${input.outpointIndex}. Make sure it exists in your wallet.`);
+        deps.io.err(
+          `UTXO not found: ${txHashHex}:${input.outpointIndex}. Make sure it exists in your wallet.`,
+        );
        return null;
      }
      totalInputSats += BigInt(utxo.valueSatoshis);
@@ -195,10 +223,14 @@ async function buildAppendParams(
    deps.io.verbose(`Required output value: ${requiredSats} satoshis`);

    const changeAmount = totalInputSats - requiredSats - DEFAULT_FEE;
-    deps.io.verbose(`Change amount: ${changeAmount} satoshis (fee: ${DEFAULT_FEE})`);
+    deps.io.verbose(
+      `Change amount: ${changeAmount} satoshis (fee: ${DEFAULT_FEE})`,
+    );

    if (changeAmount < 0n) {
-      deps.io.err(`Insufficient funds. Inputs total ${totalInputSats} sats, but need ${requiredSats + DEFAULT_FEE} sats (${requiredSats} required + ${DEFAULT_FEE} fee).`);
+      deps.io.err(
+        `Insufficient funds. Inputs total ${totalInputSats} sats, but need ${requiredSats + DEFAULT_FEE} sats (${requiredSats} required + ${DEFAULT_FEE} fee).`,
+      );
      return null;
    }

@@ -206,7 +238,9 @@ async function buildAppendParams(
      outputs.push({ valueSatoshis: changeAmount });
      deps.io.out(`Auto-adding change output: ${changeAmount} satoshis`);
    } else if (changeAmount > 0n) {
-      deps.io.out(`Change ${changeAmount} sats is below dust threshold (${DUST_THRESHOLD} sats), donating to miners as fee.`);
+      deps.io.out(
+        `Change ${changeAmount} sats is below dust threshold (${DUST_THRESHOLD} sats), donating to miners as fee.`,
+      );
    }
  }

@@ -218,7 +252,7 @@ async function buildAppendParams(
 */
 export const printInvitationHelp = (io: CommandIO): void => {
  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli invitation <sub-command>

 ${bold("Sub-commands:")}
@@ -228,6 +262,7 @@ ${bold("Sub-commands:")}
    - broadcast <invitation-id> ${dim("Broadcast an invitation")}
    - requirements <invitation-id> ${dim("Show requirements for an invitation")}
    - import <invitation-file> ${dim("Import an invitation from a file")}
+    - inspect <invitation-id | invitation-file> ${dim("Inspect an invitation")}
    - list ${dim("List all invitations")}

 ${bold("Create / Append options:")}
@@ -241,7 +276,8 @@ ${bold("Create / Append options:")}

    ${dim("When inputs are provided, a change output is automatically added if the")}
    ${dim("input total exceeds the required amount + fee.")}
-  `);
+  `,
+  );
 };

 /**
@@ -278,19 +314,27 @@ export const handleInvitationCommand = async (
  if (!subCommand) {
    deps.io.verbose("No sub-command provided");
    printInvitationHelp(deps.io);
-    throw new CommandError("invitation.subcommand.missing", "No sub-command provided");
+    throw new CommandError(
+      "invitation.subcommand.missing",
+      "No sub-command provided",
+    );
  }

  switch (subCommand) {
    case "create": {
      const templateQuery = args[1];
      const actionIdentifier = args[2];
-      deps.io.verbose(`Template query: ${templateQuery}, action identifier: ${actionIdentifier}`);
+      deps.io.verbose(
+        `Template query: ${templateQuery}, action identifier: ${actionIdentifier}`,
+      );

      if (!templateQuery || !actionIdentifier) {
        deps.io.verbose("No template file or action identifier provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.create.arguments_missing", "No template file or action identifier provided");
+        throw new CommandError(
+          "invitation.create.arguments_missing",
+          "No template file or action identifier provided",
+        );
      }

      const template = await resolveTemplate(deps, templateQuery);
@@ -302,7 +346,9 @@ export const handleInvitationCommand = async (
      deps.io.verbose(`XOInvitation created: ${formatObject(rawInvitation)}`);

      const invitationInstance = await deps.app.createInvitation(rawInvitation);
-      deps.io.verbose(`Invitation created: ${formatObject(invitationInstance.data)}`);
+      deps.io.verbose(
+        `Invitation created: ${formatObject(invitationInstance.data)}`,
+      );

      const variables = parseVariablesFromOptions(options);
      deps.io.verbose(`Variables: ${formatObject(variables)}`);
@@ -312,7 +358,10 @@ export const handleInvitationCommand = async (

      const params = await buildAppendParams(deps, invitationInstance, options);
      if (!params) {
-        throw new CommandError("invitation.create.append_params_failed", "Failed to build append parameters");
+        throw new CommandError(
+          "invitation.create.append_params_failed",
+          "Failed to build append parameters",
+        );
      }

      const { inputs, outputs } = params;
@@ -322,36 +371,50 @@ export const handleInvitationCommand = async (

      const invitationFilePath = `${deps.paths.workingDir}/inv-${invitationInstance.data.invitationIdentifier}.json`;
      deps.io.verbose(`Invitation file path: ${invitationFilePath}`);
-      writeFileSync(invitationFilePath, encodeExtendedJson(invitationInstance.data, 2));
-      deps.io.out(`Invitation created: ${path.basename(invitationFilePath)} (${invitationInstance.data.invitationIdentifier})`);
+      writeFileSync(
+        invitationFilePath,
+        encodeExtendedJson(invitationInstance.data, 2),
+      );
+      deps.io.out(
+        `Invitation created: ${path.basename(invitationFilePath)} (${invitationInstance.data.invitationIdentifier})`,
+      );

-      const missingRequirements = await invitationInstance.getMissingRequirements();
+      const missingRequirements =
+        await invitationInstance.getMissingRequirements();
      const hasMissing =
        (missingRequirements.variables?.length ?? 0) > 0 ||
        (missingRequirements.inputs?.length ?? 0) > 0 ||
        (missingRequirements.outputs?.length ?? 0) > 0 ||
-        (missingRequirements.roles !== undefined && Object.keys(missingRequirements.roles).length > 0);
+        (missingRequirements.roles !== undefined &&
+          Object.keys(missingRequirements.roles).length > 0);

      if (hasMissing) {
        deps.io.out(`\n${bold("Remaining requirements:")}`);
        deps.io.out(formatObject(missingRequirements));
      } else {
-        const shouldSign = options["sign"] === "true" || options["broadcast"] === "true";
+        const shouldSign =
+          options["sign"] === "true" || options["broadcast"] === "true";
        const shouldBroadcast = options["broadcast"] === "true";

        if (shouldSign) {
          await invitationInstance.sign();
-          deps.io.out(`Invitation signed: ${invitationInstance.data.invitationIdentifier}`);
+          deps.io.out(
+            `Invitation signed: ${invitationInstance.data.invitationIdentifier}`,
+          );
        }

        if (shouldBroadcast) {
          const txHash = await invitationInstance.broadcast();
          deps.io.out(`Transaction broadcast: ${bold(txHash)}`);
        } else if (!shouldSign) {
-          deps.io.out(`\n${bold("All requirements satisfied.")} You can now sign with: xo-cli invitation sign ${invitationInstance.data.invitationIdentifier}`);
+          deps.io.out(
+            `\n${bold("All requirements satisfied.")} You can now sign with: xo-cli invitation sign ${invitationInstance.data.invitationIdentifier}`,
+          );
        }
      }
-      return { invitationIdentifier: invitationInstance.data.invitationIdentifier };
+      return {
+        invitationIdentifier: invitationInstance.data.invitationIdentifier,
+      };
    }

    case "append": {
@@ -361,7 +424,10 @@ export const handleInvitationCommand = async (
      if (!invitationIdentifier) {
        deps.io.verbose("No invitation identifier provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.append.identifier_missing", "No invitation identifier provided");
+        throw new CommandError(
+          "invitation.append.identifier_missing",
+          "No invitation identifier provided",
+        );
      }

      const invitation = deps.app.invitations.find(
@@ -369,7 +435,10 @@ export const handleInvitationCommand = async (
      );
      if (!invitation) {
        deps.io.err(`Invitation not found: ${invitationIdentifier}`);
-        throw new CommandError("invitation.append.not_found", `Invitation not found: ${invitationIdentifier}`);
+        throw new CommandError(
+          "invitation.append.not_found",
+          `Invitation not found: ${invitationIdentifier}`,
+        );
      }
      deps.io.verbose(`Invitation: ${formatObject(invitation.data)}`);

@@ -381,12 +450,20 @@ export const handleInvitationCommand = async (

      const params = await buildAppendParams(deps, invitation, options);
      if (!params) {
-        throw new CommandError("invitation.append.params_failed", "Failed to build append parameters");
+        throw new CommandError(
+          "invitation.append.params_failed",
+          "Failed to build append parameters",
+        );
      }

      const { inputs, outputs } = params;
-      if (variables.length === 0 && inputs.length === 0 && outputs.length === 0) {
-        const error = "Nothing to append. Provide variables (-var-<name> <value>), inputs (--add-input <txhash>:<vout>), or outputs (--add-output <identifier>).";
+      if (
+        variables.length === 0 &&
+        inputs.length === 0 &&
+        outputs.length === 0
+      ) {
+        const error =
+          "Nothing to append. Provide variables (-var-<name> <value>), inputs (--add-input <txhash>:<vout>), or outputs (--add-output <identifier>).";
        deps.io.err(error);
        throw new CommandError("invitation.append.empty", error);
      }
@@ -399,20 +476,24 @@ export const handleInvitationCommand = async (

      const invitationFilePath = `${deps.paths.workingDir}/inv-${invitation.data.invitationIdentifier}.json`;
      writeFileSync(invitationFilePath, encodeExtendedJson(invitation.data, 2));
-      deps.io.out(`Invitation updated: ${path.basename(invitationFilePath)} (${invitation.data.invitationIdentifier})`);
+      deps.io.out(
+        `Invitation updated: ${path.basename(invitationFilePath)} (${invitation.data.invitationIdentifier})`,
+      );

      const missingRequirements = await invitation.getMissingRequirements();
      const hasMissing =
        (missingRequirements.variables?.length ?? 0) > 0 ||
        (missingRequirements.inputs?.length ?? 0) > 0 ||
        (missingRequirements.outputs?.length ?? 0) > 0 ||
-        (missingRequirements.roles !== undefined && Object.keys(missingRequirements.roles).length > 0);
+        (missingRequirements.roles !== undefined &&
+          Object.keys(missingRequirements.roles).length > 0);

      if (hasMissing) {
        deps.io.out(`\n${bold("Remaining requirements:")}`);
        deps.io.out(formatObject(missingRequirements));
      } else {
-        const shouldSign = options["sign"] === "true" || options["broadcast"] === "true";
+        const shouldSign =
+          options["sign"] === "true" || options["broadcast"] === "true";
        const shouldBroadcast = options["broadcast"] === "true";

        if (shouldSign) {
@@ -424,7 +505,9 @@ export const handleInvitationCommand = async (
          const txHash = await invitation.broadcast();
          deps.io.out(`Transaction broadcast: ${bold(txHash)}`);
        } else if (!shouldSign) {
-          deps.io.out(`\n${bold("All requirements satisfied.")} You can now sign with: xo-cli invitation sign ${invitationIdentifier}`);
+          deps.io.out(
+            `\n${bold("All requirements satisfied.")} You can now sign with: xo-cli invitation sign ${invitationIdentifier}`,
+          );
        }
      }
      return { invitationIdentifier };
@@ -436,15 +519,22 @@ export const handleInvitationCommand = async (
      if (!invitationIdentifier) {
        deps.io.verbose("No invitation identifier provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.sign.identifier_missing", "No invitation identifier provided");
+        throw new CommandError(
+          "invitation.sign.identifier_missing",
+          "No invitation identifier provided",
+        );
      }

      const invitation = deps.app.invitations.find(
-        (candidate) => candidate.data.invitationIdentifier === invitationIdentifier,
+        (candidate) =>
+          candidate.data.invitationIdentifier === invitationIdentifier,
      );
      if (!invitation) {
        deps.io.err(`Invitation not found: ${invitationIdentifier}`);
-        throw new CommandError("invitation.sign.not_found", `Invitation not found: ${invitationIdentifier}`);
+        throw new CommandError(
+          "invitation.sign.not_found",
+          `Invitation not found: ${invitationIdentifier}`,
+        );
      }
      deps.io.verbose(`Invitation: ${formatObject(invitation.data)}`);

@@ -460,20 +550,29 @@ export const handleInvitationCommand = async (
      if (!invitationIdentifier) {
        deps.io.verbose("No invitation identifier provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.broadcast.identifier_missing", "No invitation identifier provided");
+        throw new CommandError(
+          "invitation.broadcast.identifier_missing",
+          "No invitation identifier provided",
+        );
      }

      const invitation = deps.app.invitations.find(
-        (candidate) => candidate.data.invitationIdentifier === invitationIdentifier,
+        (candidate) =>
+          candidate.data.invitationIdentifier === invitationIdentifier,
      );
      if (!invitation) {
        deps.io.err(`Invitation not found: ${invitationIdentifier}`);
-        throw new CommandError("invitation.broadcast.not_found", `Invitation not found: ${invitationIdentifier}`);
+        throw new CommandError(
+          "invitation.broadcast.not_found",
+          `Invitation not found: ${invitationIdentifier}`,
+        );
      }
      deps.io.verbose(`Invitation: ${formatObject(invitation.data)}`);

      const txHash = await invitation.broadcast();
-      deps.io.verbose(`Invitation broadcasted: ${formatObject(invitation.data)}`);
+      deps.io.verbose(
+        `Invitation broadcasted: ${formatObject(invitation.data)}`,
+      );
      deps.io.out(`Transaction broadcast: ${bold(txHash)}`);
      return { invitationIdentifier, txHash };
    }
@@ -484,19 +583,28 @@ export const handleInvitationCommand = async (
      if (!invitationIdentifier) {
        deps.io.verbose("No invitation identifier provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.requirements.identifier_missing", "No invitation identifier provided");
+        throw new CommandError(
+          "invitation.requirements.identifier_missing",
+          "No invitation identifier provided",
+        );
      }

      const invitation = deps.app.invitations.find(
-        (candidate) => candidate.data.invitationIdentifier === invitationIdentifier,
+        (candidate) =>
+          candidate.data.invitationIdentifier === invitationIdentifier,
      );
      if (!invitation) {
        deps.io.err(`Invitation not found: ${invitationIdentifier}`);
-        throw new CommandError("invitation.requirements.not_found", `Invitation not found: ${invitationIdentifier}`);
+        throw new CommandError(
+          "invitation.requirements.not_found",
+          `Invitation not found: ${invitationIdentifier}`,
+        );
      }
      deps.io.verbose(`Invitation: ${formatObject(invitation.data)}`);

-      const requirements = await deps.app.engine.listRequirements(invitation.data);
+      const requirements = await deps.app.engine.listRequirements(
+        invitation.data,
+      );
      deps.io.verbose(`Requirements: ${formatObject(requirements)}`);
      deps.io.out(formatObject(requirements));
      return { invitationIdentifier };
@@ -509,7 +617,10 @@ export const handleInvitationCommand = async (
      if (!invitationFilePath) {
        deps.io.verbose("No invitation file provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.inspect.file_missing", "No invitation file provided");
+        throw new CommandError(
+          "invitation.inspect.file_missing",
+          "No invitation file provided",
+        );
      }

      const invitationFile = await readFileSync(invitationFilePath, "utf8");
@@ -519,43 +630,74 @@ export const handleInvitationCommand = async (
      deps.io.verbose(`Invitation: ${formatObject(invitation)}`);

      const invitationInstance = await deps.app.createInvitation(invitation);
-      deps.io.verbose(`Invitation created: ${formatObject(invitationInstance.data)}`);
+      deps.io.verbose(
+        `Invitation created: ${formatObject(invitationInstance.data)}`,
+      );

-      const template = await deps.app.engine.getTemplate(invitationInstance.data.templateIdentifier);
+      const template = await deps.app.engine.getTemplate(
+        invitationInstance.data.templateIdentifier,
+      );

-      const action = template?.actions[invitationInstance.data.actionIdentifier];
+      const action =
+        template?.actions[invitationInstance.data.actionIdentifier];
      deps.io.verbose(`Action: ${formatObject(action)}`);
      if (!action) {
-        deps.io.err(`Action not found: ${invitationInstance.data.actionIdentifier}`);
-        throw new CommandError("invitation.inspect.action_not_found", `Action not found: ${invitationInstance.data.actionIdentifier}`);
+        deps.io.err(
+          `Action not found: ${invitationInstance.data.actionIdentifier}`,
+        );
+        throw new CommandError(
+          "invitation.inspect.action_not_found",
+          `Action not found: ${invitationInstance.data.actionIdentifier}`,
+        );
      }

      const status = invitationInstance.status;
      deps.io.verbose(`Status: ${status}`);

-      const entities = Array.from(new Set(invitationInstance.data.commits.map((commit) => commit.entityIdentifier)));
+      const entities = Array.from(
+        new Set(
+          invitationInstance.data.commits.map(
+            (commit) => commit.entityIdentifier,
+          ),
+        ),
+      );
      deps.io.verbose(`Entities: ${formatObject(entities)}`);

      const entitiesWithRoles = entities.map((entity) => {
        return {
          entityIdentifier: entity,
-          roles: invitationInstance.data.commits.filter((commit) => commit.entityIdentifier === entity).map((commit) => {
-            return [
-              ...(commit.data.inputs?.map((input) => input.roleIdentifier) ?? []),
-              ...(commit.data.outputs?.map((output) => output.roleIdentifier) ?? []),
-              ...(commit.data.variables?.map((variable) => variable.roleIdentifier) ?? []),
-            ];
-          }).flat().filter((role) => role !== undefined)
+          roles: invitationInstance.data.commits
+            .filter((commit) => commit.entityIdentifier === entity)
+            .map((commit) => {
+              return [
+                ...(commit.data.inputs?.map((input) => input.roleIdentifier) ??
+                  []),
+                ...(commit.data.outputs?.map(
+                  (output) => output.roleIdentifier,
+                ) ?? []),
+                ...(commit.data.variables?.map(
+                  (variable) => variable.roleIdentifier,
+                ) ?? []),
+              ];
+            })
+            .flat()
+            .filter((role) => role !== undefined),
        };
      });

-      const inputs = invitationInstance.data.commits.flatMap((commit) => commit.data.inputs ?? []);
+      const inputs = invitationInstance.data.commits.flatMap(
+        (commit) => commit.data.inputs ?? [],
+      );
      deps.io.verbose(`Inputs: ${formatObject(inputs)}`);

-      const outputs = invitationInstance.data.commits.flatMap((commit) => commit.data.outputs ?? []);
+      const outputs = invitationInstance.data.commits.flatMap(
+        (commit) => commit.data.outputs ?? [],
+      );
      deps.io.verbose(`Outputs: ${formatObject(outputs)}`);

-      const variables = invitationInstance.data.commits.flatMap((commit) => commit.data.variables ?? []);
+      const variables = invitationInstance.data.commits.flatMap(
+        (commit) => commit.data.variables ?? [],
+      );
      deps.io.verbose(`Variables: ${formatObject(variables)}`);

      return {
@@ -576,7 +718,10 @@ export const handleInvitationCommand = async (
      if (!invitationFilePath) {
        deps.io.verbose("No invitation file provided");
        printInvitationHelp(deps.io);
-        throw new CommandError("invitation.import.file_missing", "No invitation file provided");
+        throw new CommandError(
+          "invitation.import.file_missing",
+          "No invitation file provided",
+        );
      }

      const invitationFile = await readFileSync(invitationFilePath, "utf8");
@@ -585,14 +730,20 @@ export const handleInvitationCommand = async (
      deps.io.verbose(`Invitation: ${formatObject(invitation)}`);
      const xoInvitation = await deps.app.engine.createInvitation(invitation);
      const invitationInstance = await deps.app.createInvitation(xoInvitation);
-      deps.io.verbose(`Invitation created: ${formatObject(invitationInstance.data)}`);
-      return { invitationIdentifier: invitationInstance.data.invitationIdentifier };
+      deps.io.verbose(
+        `Invitation created: ${formatObject(invitationInstance.data)}`,
+      );
+      return {
+        invitationIdentifier: invitationInstance.data.invitationIdentifier,
+      };
    }

    case "list": {
      const invitations = await Promise.all(
        deps.app.invitations.map(async (invitation) => {
-          const template = await deps.app.engine.getTemplate(invitation.data.templateIdentifier);
+          const template = await deps.app.engine.getTemplate(
+            invitation.data.templateIdentifier,
+          );
          return {
            invitationIdentifier: invitation.data.invitationIdentifier,
            templateIdentifier: invitation.data.templateIdentifier,
@@ -615,6 +766,9 @@ export const handleInvitationCommand = async (
    default:
      deps.io.verbose(`Unknown invitation sub-command: ${subCommand}`);
      printInvitationHelp(deps.io);
-      throw new CommandError("invitation.subcommand.unknown", `Unknown invitation sub-command: ${subCommand}`);
+      throw new CommandError(
+        "invitation.subcommand.unknown",
+        `Unknown invitation sub-command: ${subCommand}`,
+      );
  }
 };
--- a/src/cli/commands/mnemonic.ts
+++ b/src/cli/commands/mnemonic.ts
@@ -1,5 +1,10 @@
-import { bold, dim } from "../cli-utils.js";
-import { listMnemonicFiles, createMnemonicFile, createMnemonicSeed, loadMnemonic } from "../mnemonic.js";
+import { bold, dim } from "../utils.js";
+import {
+  listMnemonicFiles,
+  createMnemonicFile,
+  createMnemonicSeed,
+  loadMnemonic,
+} from "../mnemonic.js";
 import type { BaseCommandDependencies, CommandIO } from "./types.js";
 import { CommandError } from "./types.js";

@@ -8,17 +13,20 @@ import { CommandError } from "./types.js";
 */
 export const printMnemonicHelp = (io: CommandIO): void => {
  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli mnemonic <sub-command>

 ${bold("Sub-commands:")}
    - create <mnemonic-seed> ${dim("Create a new mnemonic file")}
    - list ${dim("List all mnemonic files")}
+    - import <mnemonic-seed> ${dim("Import a mnemonic seed from a file")}
+    - expose <mnemonic-file> ${dim("Expose a mnemonic file")}

 ${bold("Options:")}
    -o --output <output-filename> ${dim("Output filename for the mnemonic file")}
    -h --help ${dim("Show this help message")}
-`);
+`,
+  );
 };

 /**
@@ -39,13 +47,20 @@ export const handleMnemonicCommand = async (
  if (!subCommand) {
    deps.io.verbose("No sub-command provided");
    printMnemonicHelp(deps.io);
-    throw new CommandError("mnemonic.subcommand.missing", "No sub-command provided");
+    throw new CommandError(
+      "mnemonic.subcommand.missing",
+      "No sub-command provided",
+    );
  }

  switch (subCommand) {
    case "create": {
      const mnemonicSeed = createMnemonicSeed();
-      const savedAs = createMnemonicFile(mnemonicsDir, mnemonicSeed, options["output"]);
+      const savedAs = createMnemonicFile(
+        mnemonicsDir,
+        mnemonicSeed,
+        options["output"],
+      );

      deps.io.out(`Mnemonic file created: ${savedAs} (${mnemonicSeed})`);
      return { savedAs };
@@ -57,18 +72,25 @@ export const handleMnemonicCommand = async (
      if (!mnemonicSeed) {
        deps.io.verbose("No mnemonic seed provided");
        printMnemonicHelp(deps.io);
-        throw new CommandError("mnemonic.import.seed_missing", "No mnemonic seed provided");
+        throw new CommandError(
+          "mnemonic.import.seed_missing",
+          "No mnemonic seed provided",
+        );
      }

      deps.io.verbose(`Mnemonic seed: ${mnemonicSeed}`);
-      const savedAs = createMnemonicFile(mnemonicsDir, mnemonicSeed, options["output"]);
+      const savedAs = createMnemonicFile(
+        mnemonicsDir,
+        mnemonicSeed,
+        options["output"],
+      );
      deps.io.out(`Mnemonic file created: ${savedAs}`);
      return { savedAs };
    }

    case "list": {
      const mnemonicFiles = listMnemonicFiles(mnemonicsDir);
-      deps.io.out(mnemonicFiles.join('\n'));
+      deps.io.out(mnemonicFiles.join("\n"));
      return { count: mnemonicFiles.length };
    }

@@ -78,7 +100,10 @@ export const handleMnemonicCommand = async (
      if (!mnemonicFile) {
        deps.io.verbose("No mnemonic file provided");
        printMnemonicHelp(deps.io);
-        throw new CommandError("mnemonic.expose.file_missing", "No mnemonic file provided");
+        throw new CommandError(
+          "mnemonic.expose.file_missing",
+          "No mnemonic file provided",
+        );
      }

      try {
@@ -96,6 +121,9 @@ export const handleMnemonicCommand = async (
    default:
      deps.io.err(`Unknown sub-command: ${subCommand}`);
      printMnemonicHelp(deps.io);
-      throw new CommandError("mnemonic.subcommand.unknown", `Unknown sub-command: ${subCommand}`);
+      throw new CommandError(
+        "mnemonic.subcommand.unknown",
+        `Unknown sub-command: ${subCommand}`,
+      );
  }
 };
--- a/src/cli/commands/receive.ts
+++ b/src/cli/commands/receive.ts
@@ -1,7 +1,7 @@
 import { generateTemplateIdentifier } from "@xo-cash/engine";
 import { hexToBin, lockingBytecodeToCashAddress } from "@bitauth/libauth";

-import { bold, dim } from "../cli-utils.js";
+import { bold, dim } from "../utils.js";
 import type { CommandDependencies, CommandIO } from "./types.js";
 import { CommandError } from "./types.js";

@@ -12,7 +12,7 @@ import { resolveTemplate } from "../utils.js";
 */
 export const printReceiveHelp = (io: CommandIO): void => {
  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli receive <template-file> <output-identifier> [role-identifier]

 ${bold("Description:")}
@@ -25,7 +25,8 @@ ${bold("Arguments:")}

 ${bold("Options:")}
    -h --help ${dim("Show this help message")}
-`);
+`,
+  );
 };

 /**
@@ -47,12 +48,17 @@ export const handleReceiveCommand = async (
  const outputIdentifier = args[1];
  const roleIdentifier = args[2];

-  deps.io.verbose(`Receive args - template: ${templateQuery}, output: ${outputIdentifier}, role: ${roleIdentifier}`);
+  deps.io.verbose(
+    `Receive args - template: ${templateQuery}, output: ${outputIdentifier}, role: ${roleIdentifier}`,
+  );

  if (!templateQuery || !outputIdentifier) {
    deps.io.verbose("Missing required arguments");
    printReceiveHelp(deps.io);
-    throw new CommandError("receive.arguments.missing", "Missing required arguments");
+    throw new CommandError(
+      "receive.arguments.missing",
+      "Missing required arguments",
+    );
  }

  // Resolve and read the template file
@@ -69,11 +75,17 @@ export const handleReceiveCommand = async (
  deps.io.verbose(`Locking bytecode hex: ${lockingBytecodeHex}`);

  // Convert the locking bytecode to a BCH cash address
-  const result = lockingBytecodeToCashAddress({ bytecode: hexToBin(lockingBytecodeHex), prefix: 'bitcoincash' });
+  const result = lockingBytecodeToCashAddress({
+    bytecode: hexToBin(lockingBytecodeHex),
+    prefix: "bitcoincash",
+  });

-  if (typeof result === 'string') {
+  if (typeof result === "string") {
    deps.io.err(`Failed to encode address: ${result}`);
-    throw new CommandError("receive.address.encode_failed", `Failed to encode address: ${result}`);
+    throw new CommandError(
+      "receive.address.encode_failed",
+      `Failed to encode address: ${result}`,
+    );
  }

  deps.io.out(result.address);
--- a/src/cli/commands/resource.ts
+++ b/src/cli/commands/resource.ts
@@ -1,6 +1,6 @@
 import { hexToBin } from "@bitauth/libauth";

-import { bold, dim } from "../cli-utils.js";
+import { bold, dim } from "../utils.js";
 import type { CommandDependencies, CommandIO } from "./types.js";
 import type { UnspentOutputData } from "@xo-cash/state";
 import { CommandError } from "./types.js";
@@ -10,7 +10,7 @@ import { CommandError } from "./types.js";
 */
 export const printResourceHelp = (io: CommandIO): void => {
  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli resource <sub-command>

 ${bold("Sub-commands:")}
@@ -19,14 +19,20 @@ ${bold("Sub-commands:")}
    - list all              ${dim("List all resources (reserved + unreserved)")}
    - unreserve <txhash:vout> ${dim("Unreserve a specific UTXO")}
    - unreserve-all         ${dim("Unreserve all reserved UTXOs")}
-  `);
+  `,
+  );
 };

 /**
 * Formats a single UTXO for display, optionally including reservation info.
 */
-function formatResource(resource: UnspentOutputData, showReserved = false): string {
-  const outpoint = bold(`${resource.outpointTransactionHash}:${resource.outpointIndex}`);
+function formatResource(
+  resource: UnspentOutputData,
+  showReserved = false,
+): string {
+  const outpoint = bold(
+    `${resource.outpointTransactionHash}:${resource.outpointIndex}`,
+  );
  const value = dim(`${resource.valueSatoshis} sats`);
  const output = dim(resource.outputIdentifier);
  const height = dim(`(height ${resource.minedAtHeight})`);
@@ -57,7 +63,10 @@ export const handleResourceCommand = async (
  if (!subCommand) {
    deps.io.verbose("No sub-command provided");
    printResourceHelp(deps.io);
-    throw new CommandError("resource.subcommand.missing", "No sub-command provided");
+    throw new CommandError(
+      "resource.subcommand.missing",
+      "No sub-command provided",
+    );
  }

  switch (subCommand) {
@@ -80,9 +89,13 @@ export const handleResourceCommand = async (
      }

      const showReserved = qualifier === "all" || qualifier === "reserved";
-      const formattedResources = filtered.map((r) => formatResource(r, showReserved));
+      const formattedResources = filtered.map((r) =>
+        formatResource(r, showReserved),
+      );
      deps.io.out(formattedResources.join("\n"));
-      deps.io.out(`Total satoshis: ${filtered.reduce((acc, r) => acc + r.valueSatoshis, 0)}`);
+      deps.io.out(
+        `Total satoshis: ${filtered.reduce((acc, r) => acc + r.valueSatoshis, 0)}`,
+      );
      deps.io.out(`Total resources: ${filtered.length}`);
      return { count: filtered.length };
    }
@@ -92,20 +105,33 @@ export const handleResourceCommand = async (
      if (!outpointArg) {
        deps.io.err("Please provide a UTXO in <txhash>:<vout> format.");
        printResourceHelp(deps.io);
-        throw new CommandError("resource.unreserve.outpoint_missing", "Please provide a UTXO in <txhash>:<vout> format.");
+        throw new CommandError(
+          "resource.unreserve.outpoint_missing",
+          "Please provide a UTXO in <txhash>:<vout> format.",
+        );
      }

      const separatorIndex = outpointArg.lastIndexOf(":");
      if (separatorIndex === -1) {
-        deps.io.err(`Invalid format "${outpointArg}". Expected <txhash>:<vout>.`);
-        throw new CommandError("resource.unreserve.outpoint_invalid", `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`);
+        deps.io.err(
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
+        throw new CommandError(
+          "resource.unreserve.outpoint_invalid",
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
      }

      const txHash = outpointArg.substring(0, separatorIndex);
      const vout = parseInt(outpointArg.substring(separatorIndex + 1), 10);
      if (!txHash || isNaN(vout)) {
-        deps.io.err(`Invalid format "${outpointArg}". Expected <txhash>:<vout>.`);
-        throw new CommandError("resource.unreserve.outpoint_invalid", `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`);
+        deps.io.err(
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
+        throw new CommandError(
+          "resource.unreserve.outpoint_invalid",
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
      }

      const allResources = await deps.app.engine.listUnspentOutputsData();
@@ -115,7 +141,10 @@ export const handleResourceCommand = async (

      if (!target) {
        deps.io.err(`UTXO not found: ${txHash}:${vout}`);
-        throw new CommandError("resource.unreserve.utxo_missing", `UTXO not found: ${txHash}:${vout}`);
+        throw new CommandError(
+          "resource.unreserve.utxo_missing",
+          `UTXO not found: ${txHash}:${vout}`,
+        );
      }

      if (!target.reservedBy) {
@@ -125,9 +154,11 @@ export const handleResourceCommand = async (

      await deps.app.engine.unreserveResources(
        [{ outpointTransactionHash: hexToBin(txHash), outpointIndex: vout }],
-        target.reservedBy ,
+        target.reservedBy,
+      );
+      deps.io.out(
+        `Unreserved ${bold(`${txHash}:${vout}`)} (was reserved for ${target.reservedBy})`,
      );
-      deps.io.out(`Unreserved ${bold(`${txHash}:${vout}`)} (was reserved for ${target.reservedBy})`);
      return {};
    }

@@ -144,7 +175,10 @@ export const handleResourceCommand = async (
    default: {
      deps.io.verbose(`Unknown resource sub-command: ${subCommand}`);
      printResourceHelp(deps.io);
-      throw new CommandError("resource.subcommand.unknown", `Unknown resource sub-command: ${subCommand}`);
+      throw new CommandError(
+        "resource.subcommand.unknown",
+        `Unknown resource sub-command: ${subCommand}`,
+      );
    }
  }
 };
--- a/src/cli/commands/template.ts
+++ b/src/cli/commands/template.ts
@@ -3,7 +3,7 @@ import path from "path";
 import { generateTemplateIdentifier } from "@xo-cash/engine";
 import type { XOTemplate } from "@xo-cash/types";

-import { bold, dim, formatObject } from "../cli-utils.js";
+import { bold, dim, formatObject } from "../utils.js";
 import { resolveTemplateReferences } from "../../utils/templates.js";
 import type { CommandDependencies, CommandIO } from "./types.js";
 import { CommandError } from "./types.js";
@@ -14,7 +14,7 @@ import { resolveTemplate } from "../utils.js";
 */
 export const printTemplateHelp = (io: CommandIO): void => {
  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli template <sub-command>

 ${bold("Sub-commands:")}
@@ -23,7 +23,8 @@ ${bold("Sub-commands:")}
    - list <category> <identifier> ${dim("List all options of the field type in a template")}
    - inspect <category> <identifier> <field> ${dim("Inspect a field in a template")}
    - set-default <template-file> <output-identifier> <role-identifier> ${dim("Set the default template")}
-  `);
+  `,
+  );
 };

 /**
@@ -41,8 +42,11 @@ export const handleTemplateListCommand = async (

  if (!templateCategory) {
    const templates = await deps.app.engine.listImportedTemplates();
-    const formattedTemplates = templates.map((template: XOTemplate) => `${bold(generateTemplateIdentifier(template))} - ${dim(template.name)} ${dim(template.description)}`);
-    deps.io.out(formattedTemplates.join('\n'));
+    const formattedTemplates = templates.map(
+      (template: XOTemplate) =>
+        `${bold(generateTemplateIdentifier(template))} - ${dim(template.name)} ${dim(template.description)}`,
+    );
+    deps.io.out(formattedTemplates.join("\n"));
    return { count: templates.length };
  }

@@ -51,13 +55,19 @@ export const handleTemplateListCommand = async (

  if (!templateIdentifier) {
    deps.io.err("No template identifier provided");
-    throw new CommandError("template.list.identifier_missing", "No template identifier provided");
+    throw new CommandError(
+      "template.list.identifier_missing",
+      "No template identifier provided",
+    );
  }

  const rawTemplate = await deps.app.engine.getTemplate(templateIdentifier);
  if (!rawTemplate) {
    deps.io.err(`No template found: ${templateIdentifier}`);
-    throw new CommandError("template.list.not_found", `No template found: ${templateIdentifier}`);
+    throw new CommandError(
+      "template.list.not_found",
+      `No template found: ${templateIdentifier}`,
+    );
  }

  const template = await resolveTemplateReferences(rawTemplate);
@@ -66,47 +76,65 @@ export const handleTemplateListCommand = async (
  switch (templateCategory) {
    case "action": {
      const actions = template.actions;
-      const formattedActions = Object.entries(actions).map(([actionIdentifier, action]) => `${bold(actionIdentifier)} ${dim(action.name)} ${dim(action.description)}`);
-      deps.io.out(formattedActions.join('\n'));
+      const formattedActions = Object.entries(actions).map(
+        ([actionIdentifier, action]) =>
+          `${bold(actionIdentifier)} ${dim(action.name)} ${dim(action.description)}`,
+      );
+      deps.io.out(formattedActions.join("\n"));
      return {};
    }
    case "transaction": {
      const transactions = template.transactions;
-      const formattedTransactions = Object.entries(transactions).map(([transactionIdentifier, transaction]) => `${bold(transactionIdentifier)} ${dim(transaction.name)} ${dim(transaction.description)}`);
-      deps.io.out(formattedTransactions.join('\n'));
+      const formattedTransactions = Object.entries(transactions).map(
+        ([transactionIdentifier, transaction]) =>
+          `${bold(transactionIdentifier)} ${dim(transaction.name)} ${dim(transaction.description)}`,
+      );
+      deps.io.out(formattedTransactions.join("\n"));
      return {};
    }
    case "output": {
      const outputs = template.outputs;
-      const formattedOutputs = Object.entries(outputs).map(([outputIdentifier, output]) => `${bold(outputIdentifier)} ${dim(output.name)} ${dim(output.description)}`);
-      deps.io.out(formattedOutputs.join('\n'));
+      const formattedOutputs = Object.entries(outputs).map(
+        ([outputIdentifier, output]) =>
+          `${bold(outputIdentifier)} ${dim(output.name)} ${dim(output.description)}`,
+      );
+      deps.io.out(formattedOutputs.join("\n"));
      return {};
    }
    case "lockingscript": {
      const lockingscripts = template.lockingScripts;
-      const formattedLockingscripts = Object.entries(lockingscripts).map(([lockingScriptIdentifier, lockingScript]) => `${bold(lockingScriptIdentifier)} ${dim(lockingScript.name)} ${dim(lockingScript.description)}`);
-      deps.io.out(formattedLockingscripts.join('\n'));
+      const formattedLockingscripts = Object.entries(lockingscripts).map(
+        ([lockingScriptIdentifier, lockingScript]) =>
+          `${bold(lockingScriptIdentifier)} ${dim(lockingScript.name)} ${dim(lockingScript.description)}`,
+      );
+      deps.io.out(formattedLockingscripts.join("\n"));
      return {};
    }
    case "variable": {
      const variables = template.variables || {};
-      const formattedVariables = Object.entries(variables).map(([variableIdentifier, variable]) => `${bold(variableIdentifier)} ${dim(variable.name)} ${dim(variable.description)}`);
-      deps.io.out(formattedVariables.join('\n'));
+      const formattedVariables = Object.entries(variables).map(
+        ([variableIdentifier, variable]) =>
+          `${bold(variableIdentifier)} ${dim(variable.name)} ${dim(variable.description)}`,
+      );
+      deps.io.out(formattedVariables.join("\n"));
      return {};
    }
    default: {
      deps.io.verbose(`Unknown template category: ${templateCategory}`);
-      throw new CommandError("template.list.category_unknown", `Unknown template category: ${templateCategory}`);
+      throw new CommandError(
+        "template.list.category_unknown",
+        `Unknown template category: ${templateCategory}`,
+      );
    }
  }
-}
+};

 /**
 * Prints the help message for the template inspect command
 */
 export const printTemplateInspectHelp = (io: CommandIO): void => {
  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli template inspect <category> <identifier> <field>

 ${bold("Arguments:")}
@@ -120,7 +148,8 @@ ${bold("Categories:")}
    - output <output-identifier> ${dim("Inspect an output")}
    - lockingscript <lockingscript-identifier> ${dim("Inspect a lockingscript")}
    - variable <variable-identifier> ${dim("Inspect a variable")}
-  `);
+  `,
+  );
 };

 /**
@@ -137,12 +166,17 @@ export const handleTemplateInspectCommand = async (
  const templateQuery = args[1];
  const templateField = args[2];

-  deps.io.verbose(`Template inspect args - category: ${templateCategory}, identifier: ${templateQuery}, field: ${templateField}`);
+  deps.io.verbose(
+    `Template inspect args - category: ${templateCategory}, identifier: ${templateQuery}, field: ${templateField}`,
+  );

  if (!templateCategory || !templateQuery || !templateField) {
    deps.io.err("No template category, identifier, or field provided");
    printTemplateInspectHelp(deps.io);
-    throw new CommandError("template.inspect.arguments_missing", "No template category, identifier, or field provided");
+    throw new CommandError(
+      "template.inspect.arguments_missing",
+      "No template category, identifier, or field provided",
+    );
  }

  const originalTemplate = await resolveTemplate(deps, templateQuery);
@@ -156,7 +190,10 @@ export const handleTemplateInspectCommand = async (
      const action = template.actions[templateField];
      if (!action) {
        deps.io.err(`No action found: ${templateField}`);
-        throw new CommandError("template.inspect.action_missing", `No action found: ${templateField}`);
+        throw new CommandError(
+          "template.inspect.action_missing",
+          `No action found: ${templateField}`,
+        );
      }
      deps.io.out(formatObject(action));
      return {};
@@ -165,7 +202,10 @@ export const handleTemplateInspectCommand = async (
      const transaction = template.transactions?.[templateField];
      if (!transaction) {
        deps.io.err(`No transaction found: ${templateField}`);
-        throw new CommandError("template.inspect.transaction_missing", `No transaction found: ${templateField}`);
+        throw new CommandError(
+          "template.inspect.transaction_missing",
+          `No transaction found: ${templateField}`,
+        );
      }
      deps.io.out(formatObject(transaction));
      return {};
@@ -174,7 +214,10 @@ export const handleTemplateInspectCommand = async (
      const output = template.outputs[templateField];
      if (!output) {
        deps.io.err(`No output found: ${templateField}`);
-        throw new CommandError("template.inspect.output_missing", `No output found: ${templateField}`);
+        throw new CommandError(
+          "template.inspect.output_missing",
+          `No output found: ${templateField}`,
+        );
      }
      deps.io.out(formatObject(output));
      return {};
@@ -183,7 +226,10 @@ export const handleTemplateInspectCommand = async (
      const lockingscript = template.lockingScripts[templateField];
      if (!lockingscript) {
        deps.io.err(`No lockingscript found: ${templateField}`);
-        throw new CommandError("template.inspect.lockingscript_missing", `No lockingscript found: ${templateField}`);
+        throw new CommandError(
+          "template.inspect.lockingscript_missing",
+          `No lockingscript found: ${templateField}`,
+        );
      }
      deps.io.out(formatObject(lockingscript));
      return {};
@@ -192,17 +238,23 @@ export const handleTemplateInspectCommand = async (
      const variable = template.variables?.[templateField];
      if (!variable) {
        deps.io.err(`No variable found: ${templateField}`);
-        throw new CommandError("template.inspect.variable_missing", `No variable found: ${templateField}`);
+        throw new CommandError(
+          "template.inspect.variable_missing",
+          `No variable found: ${templateField}`,
+        );
      }
      deps.io.out(formatObject(variable));
      return {};
    }
    default: {
      deps.io.verbose(`Unknown template category: ${templateCategory}`);
-      throw new CommandError("template.inspect.category_unknown", `Unknown template category: ${templateCategory}`);
+      throw new CommandError(
+        "template.inspect.category_unknown",
+        `Unknown template category: ${templateCategory}`,
+      );
    }
  }
-}
+};

 /**
 * Handles the template command.
@@ -221,7 +273,10 @@ export const handleTemplateCommand = async (
  if (!subCommand) {
    deps.io.verbose("No sub-command provided");
    printTemplateHelp(deps.io);
-    throw new CommandError("template.subcommand.missing", "No sub-command provided");
+    throw new CommandError(
+      "template.subcommand.missing",
+      "No sub-command provided",
+    );
  }

  switch (subCommand) {
@@ -232,7 +287,10 @@ export const handleTemplateCommand = async (
      if (!templateFile) {
        deps.io.verbose("No template file provided");
        printTemplateHelp(deps.io);
-        throw new CommandError("template.import.file_missing", "No template file provided");
+        throw new CommandError(
+          "template.import.file_missing",
+          "No template file provided",
+        );
      }

      const templatePath = path.resolve(`${process.cwd()}/${templateFile}`);
@@ -241,7 +299,10 @@ export const handleTemplateCommand = async (
      if (!existsSync(templatePath)) {
        deps.io.err(`Template file does not exist: ${templatePath}`);
        printTemplateHelp(deps.io);
-        throw new CommandError("template.import.file_not_found", `Template file does not exist: ${templatePath}`);
+        throw new CommandError(
+          "template.import.file_not_found",
+          `Template file does not exist: ${templatePath}`,
+        );
      }

      const template = await readFileSync(templatePath, "utf8");
@@ -262,17 +323,31 @@ export const handleTemplateCommand = async (
      const outputIdentifier = args[2];
      const roleIdentifier = args[3];
      if (!templateFile || !outputIdentifier || !roleIdentifier) {
-        deps.io.verbose("No template file, output identifier, or role identifier provided");
+        deps.io.verbose(
+          "No template file, output identifier, or role identifier provided",
+        );
        printTemplateHelp(deps.io);
-        throw new CommandError("template.default.arguments_missing", "No template file, output identifier, or role identifier provided");
+        throw new CommandError(
+          "template.default.arguments_missing",
+          "No template file, output identifier, or role identifier provided",
+        );
      }
-      deps.io.verbose(`Template file: ${templateFile}, output identifier: ${outputIdentifier}, role identifier: ${roleIdentifier}`);
-      await deps.app.engine.setDefaultLockingParameters(templateFile, outputIdentifier, roleIdentifier);
+      deps.io.verbose(
+        `Template file: ${templateFile}, output identifier: ${outputIdentifier}, role identifier: ${roleIdentifier}`,
+      );
+      await deps.app.engine.setDefaultLockingParameters(
+        templateFile,
+        outputIdentifier,
+        roleIdentifier,
+      );
      return {};
    }
    default:
      deps.io.verbose(`Unknown template sub-command: ${subCommand}`);
      printTemplateHelp(deps.io);
-      throw new CommandError("template.subcommand.unknown", `Unknown template sub-command: ${subCommand}`);
+      throw new CommandError(
+        "template.subcommand.unknown",
+        `Unknown template sub-command: ${subCommand}`,
+      );
  }
 };
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -40,9 +40,13 @@ import { join } from "path";

 import { AppService } from "../services/app.js";
 import { convertArgsToObject } from "./arguments.js";
-import { bold, dim, formatObject } from "./cli-utils.js";
+import { bold, dim, formatObject } from "./utils.js";
 import { listGlobalMnemonicFiles, loadMnemonic } from "./mnemonic.js";
-import { getDataDir, getMnemonicsDir, getWalletConfigPath } from "../utils/paths.js";
+import {
+  getDataDir,
+  getMnemonicsDir,
+  getWalletConfigPath,
+} from "../utils/paths.js";

 import {
  type CommandDependencies,
@@ -138,8 +142,12 @@ async function main(): Promise<void> {
  }
  if (!mnemonicFile) {
    io.err("No mnemonic file provided");
-    io.out(`You can create a mnemonic file with the following command: xo-cli mnemonic create <mnemonic-seed> or use one of the following files: \n${listGlobalMnemonicFiles().join("\n")}`);
-    io.out(`\nTip: pass -m <file> once and it will be remembered in ${paths.walletConfigPath}`);
+    io.out(
+      `You can create a mnemonic file with the following command: xo-cli mnemonic create <mnemonic-seed> or use one of the following files: \n${listGlobalMnemonicFiles().join("\n")}`,
+    );
+    io.out(
+      `\nTip: pass -m <file> once and it will be remembered in ${paths.walletConfigPath}`,
+    );
    process.exit(1);
  }

@@ -158,7 +166,8 @@ async function main(): Promise<void> {
      databaseFilename: options["databaseFilename"] ?? "xo-wallet.db",
    },
    invitationStoragePath:
-      options["invitationStoragePath"] ?? join(paths.dataDir, "xo-invitations.db"),
+      options["invitationStoragePath"] ??
+      join(paths.dataDir, "xo-invitations.db"),
  });
  io.verbose("App instance created");

@@ -179,23 +188,42 @@ async function main(): Promise<void> {
    let result: unknown;
    switch (command) {
      case "template":
-        result = await handleTemplateCommand(commandDependencies, subArgs, options);
+        result = await handleTemplateCommand(
+          commandDependencies,
+          subArgs,
+          options,
+        );
        break;
      case "invitation":
-        result = await handleInvitationCommand(commandDependencies, subArgs, options);
+        result = await handleInvitationCommand(
+          commandDependencies,
+          subArgs,
+          options,
+        );
        break;
      case "receive":
-        result = await handleReceiveCommand(commandDependencies, subArgs, options);
+        result = await handleReceiveCommand(
+          commandDependencies,
+          subArgs,
+          options,
+        );
        break;
      case "resource":
-        result = await handleResourceCommand(commandDependencies, subArgs, options);
+        result = await handleResourceCommand(
+          commandDependencies,
+          subArgs,
+          options,
+        );
        break;
      case "help":
        result = await handleHelpCommand(commandDependencies, subArgs, options);
        break;
      default:
        io.err(`Unknown command: ${command}`);
-        throw new CommandError("cli.command.unknown", `Unknown command: ${command}`);
+        throw new CommandError(
+          "cli.command.unknown",
+          `Unknown command: ${command}`,
+        );
    }

    // console.log(result);
@@ -217,7 +245,7 @@ const handleHelpCommand = async (
  _options: Record<string, string>,
 ): Promise<Record<string, never>> => {
  deps.io.out(
-`${bold("XO-CLI Help:")}
+    `${bold("XO-CLI Help:")}

 ${bold("Usage:")} xo-cli <command> [options]

@@ -228,11 +256,12 @@ Commands:
  receive     ${dim("Generate a single-use receiving address")}
  resource    ${dim("Manage resources")}
  completions ${dim("Generate shell completion scripts (bash, zsh, fish)")}
+  help        ${dim("Show this help message")}

 Options:
  -h, --help    ${dim("Show this help message")}
  -m, --mnemonic-file <mnemonic-file>  ${dim("Use a specific mnemonic file")}
-  -v, --verbose   ${dim("Show verbose output")}`
+  -v, --verbose   ${dim("Show verbose output")}`,
  );
  return {};
 };
--- a/src/cli/mnemonic.ts
+++ b/src/cli/mnemonic.ts
@@ -28,9 +28,11 @@ export const createMnemonicFile = (

  let fileName = outputFilename;
  if (!fileName) {
-    const firstWord = mnemonic.split(' ')[0]?.toLowerCase();
+    const firstWord = mnemonic.split(" ")[0]?.toLowerCase();
    if (!firstWord) {
-      throw new Error("Failed to create mnemonic file: Unable to extract first word from the mnemonic");
+      throw new Error(
+        "Failed to create mnemonic file: Unable to extract first word from the mnemonic",
+      );
    }
    fileName = `mnemonic-${firstWord}`;
  }
@@ -80,9 +82,14 @@ export const resolveMnemonicFilePath = (
 * @param mnemonicFile - The filename of the mnemonic file
 * @returns The mnemonic seed
 */
-export const loadMnemonic = (mnemonicsDir: string, mnemonicFile: string): string => {
+export const loadMnemonic = (
+  mnemonicsDir: string,
+  mnemonicFile: string,
+): string => {
  const resolvedPath = resolveMnemonicFilePath(mnemonicsDir, mnemonicFile);
-  const mnemonicUrl = BCHMnemonicURL.fromURL(readFileSync(resolvedPath, "utf8"));
+  const mnemonicUrl = BCHMnemonicURL.fromURL(
+    readFileSync(resolvedPath, "utf8"),
+  );
  const { entropy } = mnemonicUrl.toObject();

  const mnemonic = encodeBip39Mnemonic(entropy);
--- a/src/cli/utils.ts
+++ b/src/cli/utils.ts
@@ -1,7 +1,10 @@
+import util from "node:util";
+
 import type { XOTemplate } from "@xo-cash/types";
+import { generateTemplateIdentifier } from "@xo-cash/engine";
+
 import type { CommandDependencies } from "./commands/types.js";
 import { CommandError } from "./commands/types.js";
-import { generateTemplateIdentifier } from "@xo-cash/engine";

 /**
 * Iterate through the templates, trying to match the id or the name with the given input.
@@ -16,7 +19,10 @@ import { generateTemplateIdentifier } from "@xo-cash/engine";
 * @throws CommandError if no template is found.
 * @throws CommandError if multiple templates are found.
 */
-export const resolveTemplate = async (deps: CommandDependencies, query: string): Promise<XOTemplate> => {
+export const resolveTemplate = async (
+  deps: CommandDependencies,
+  query: string,
+): Promise<XOTemplate> => {
  const templates = await deps.app.engine.listImportedTemplates();

  const matches = new Set<XOTemplate>();
@@ -36,7 +42,12 @@ export const resolveTemplate = async (deps: CommandDependencies, query: string):
  if (matches.size > 1) {
    throw new CommandError(
      "template.resolve.multiple_matches",
-      `Multiple templates found for "${query}": ${Array.from(matches).map(template => `${template.name} (${generateTemplateIdentifier(template)})`).join(", ")}`,
+      `Multiple templates found for "${query}": ${Array.from(matches)
+        .map(
+          (template) =>
+            `${template.name} (${generateTemplateIdentifier(template)})`,
+        )
+        .join(", ")}`,
    );
  }

@@ -44,5 +55,52 @@ export const resolveTemplate = async (deps: CommandDependencies, query: string):
    return matches.values().next().value!;
  }

-  throw new CommandError("template.resolve.not_found", `Template not found: ${query}`);
-}
+  throw new CommandError(
+    "template.resolve.not_found",
+    `Template not found: ${query}`,
+  );
+};
+
+/**
+ * Text formatting utilities for the CLI.
+ *
+ * Uses ANSI escape codes to format text.
+ *
+ * AI Generated links:
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Formatting
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Cursor_movement
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Screen_manipulation
+ */
+
+const BOLD = "\x1b[1m";
+export const bold = (text: string) => `${BOLD}${text}${RESET}`;
+
+const DIM = "\x1b[2m";
+export const dim = (text: string) => `${DIM}${text}${RESET}`;
+
+const UNDERLINE = "\x1b[4m";
+export const underline = (text: string) => `${UNDERLINE}${text}${RESET}`;
+
+const INVERSE = "\x1b[7m";
+export const inverse = (text: string) => `${INVERSE}${text}${RESET}`;
+
+const HIDDEN = "\x1b[8m";
+export const hidden = (text: string) => `${HIDDEN}${text}${RESET}`;
+
+const STRIKETHROUGH = "\x1b[9m";
+export const strikethrough = (text: string) =>
+  `${STRIKETHROUGH}${text}${RESET}`;
+
+const RESET = "\x1b[0m";
+export const reset = (text: string) => `${RESET}${text}${RESET}`;
+
+export const formatObject = (obj: unknown) => {
+  return util.inspect(obj, {
+    depth: null,
+    colors: true,
+    compact: false,
+  });
+};
--- a/src/services/app.ts
+++ b/src/services/app.ts
@@ -11,6 +11,7 @@ import { BaseStorage, Storage } from "./storage.js";
 import { SyncServer } from "../utils/sync-server.js";
 import { HistoryService } from "./history.js";
 import { type BlockchainService, ElectrumService } from "./electrum.js";
+import { RatesService } from "./rates.js";

 import { EventEmitter } from "../utils/event-emitter.js";

@@ -18,6 +19,7 @@ import { EventEmitter } from "../utils/event-emitter.js";
 import { createHash } from "crypto";
 import { p2pkhTemplate } from "@xo-cash/templates";
 import { hexToBin } from "@bitauth/libauth";
+import { parseTemplate } from "@xo-cash/engine";

 export type AppEventMap = {
  "invitation-added": Invitation;
@@ -46,6 +48,7 @@ export class AppService extends EventEmitter<AppEventMap> {
  public config: AppConfig;
  public history: HistoryService;
  public electrum: BlockchainService;
+  public rates: RatesService;

  public invitations: Invitation[] = [];
  private invitationEventCleanup = new Map<
@@ -74,14 +77,26 @@ export class AppService extends EventEmitter<AppEventMap> {
    // Import the default P2PKH template
    const { templateIdentifier } = await engine.importTemplate(p2pkhTemplate);

-    engine.subscribeToLockingBytecodesForTemplate(templateIdentifier).catch(err => console.error(`Error subscribing to locking bytecodes for template ${templateIdentifier}: ${err}`));
-    engine.updateUnspentOutputsForTemplate(templateIdentifier).catch(err => console.error(`Error updating unspent outputs for template ${templateIdentifier}: ${err}`));
+    engine
+      .subscribeToLockingBytecodesForTemplate(templateIdentifier)
+      .catch((err) =>
+        console.error(
+          `Error subscribing to locking bytecodes for template ${templateIdentifier}: ${err}`,
+        ),
+      );
+    engine
+      .updateUnspentOutputsForTemplate(templateIdentifier)
+      .catch((err) =>
+        console.error(
+          `Error updating unspent outputs for template ${templateIdentifier}: ${err}`,
+        ),
+      );

    // Set default locking parameters for P2PKH
    // To my knowledge, this doesnt generate any lockscript, so discovery of funds will not work automatically.
    // TODO: Add discovery for funds in the first index? Or until we return 0 TXs?
    await engine.setDefaultLockingParameters(
-      generateTemplateIdentifier(p2pkhTemplate),
+      generateTemplateIdentifier(parseTemplate(p2pkhTemplate)),
      "receiveOutput",
      "receiver",
    );
@@ -95,8 +110,9 @@ export class AppService extends EventEmitter<AppEventMap> {
      host: config.electrumHost,
      applicationIdentifier: config.electrumApplicationIdentifier,
    });
+    const rates = await RatesService.create();

-    return new AppService(engine, walletStorage, config, electrum);
+    return new AppService(engine, walletStorage, config, electrum, rates);
  }

  constructor(
@@ -104,6 +120,7 @@ export class AppService extends EventEmitter<AppEventMap> {
    storage: BaseStorage,
    config: AppConfig,
    electrum: BlockchainService,
+    rates: RatesService,
  ) {
    super();

@@ -111,6 +128,7 @@ export class AppService extends EventEmitter<AppEventMap> {
    this.storage = storage;
    this.config = config;
    this.electrum = electrum;
+    this.rates = rates;
    this.history = new HistoryService(engine, this.invitations);
  }

@@ -209,10 +227,7 @@ export class AppService extends EventEmitter<AppEventMap> {
    if (!trackedInvitation || !cleanup) return;

    trackedInvitation.off("invitation-updated", cleanup.onUpdated);
-    trackedInvitation.off(
-      "invitation-status-changed",
-      cleanup.onStatusChanged,
-    );
+    trackedInvitation.off("invitation-status-changed", cleanup.onStatusChanged);
    this.invitationEventCleanup.delete(invitationIdentifier);
  }

@@ -248,6 +263,11 @@ export class AppService extends EventEmitter<AppEventMap> {
  }

  async start(): Promise<void> {
+    // Start rates in the background so BCH -> fiat conversions become reactive in the TUI.
+    this.rates.start().catch((err) =>
+      console.error('Error starting rates service:', err),
+    );
+
    // Get the invitations db
    const invitationsDb = this.storage.child("invitations");

@@ -259,7 +279,9 @@ export class AppService extends EventEmitter<AppEventMap> {

    await Promise.all(
      invitations.map(async ({ key }) => {
-        await this.createInvitation(key).catch(err => console.error(`Error creating invitation ${key}: ${err}`));
+        await this.createInvitation(key).catch((err) =>
+          console.error(`Error creating invitation ${key}: ${err}`),
+        );
      }),
    );
  }
--- a/src/services/history.ts
+++ b/src/services/history.ts
@@ -1,5 +1,9 @@
 import { binToHex } from "@bitauth/libauth";
-import { compileCashAssemblyString, type Engine } from "@xo-cash/engine";
+import {
+  compileCashAssemblyString,
+  type Engine,
+  listInvitationCommitsByEntity,
+} from "@xo-cash/engine";
 import type { UnspentOutputData } from "@xo-cash/state";
 import type {
  XOInvitation,
@@ -59,6 +63,7 @@ interface InvitationContext {
  invitation: Invitation;
  template: XOTemplate | null;
  variables: Record<string, XOInvitationVariableValue>;
+  walletCommits: XOInvitationCommit[];
  walletEntityIdentifier?: string;
 }

@@ -73,12 +78,8 @@ export class HistoryService {
    private invitations: Invitation[],
  ) {}

-  async extractEntities(invitation: XOInvitation): Promise<string[]> {
-    const entities = new Set<string>();
-    for (const commit of invitation.commits) {
-      entities.add(commit.entityIdentifier);
-    }
-    return Array.from(entities);
+  extractEntities(invitation: XOInvitation): Record<string, XOInvitationCommit[]> {
+    return listInvitationCommitsByEntity(invitation);
  }

  // Entities are currently static per invitation. So, we can try to match the roles to entities by:
@@ -127,8 +128,6 @@ export class HistoryService {

  async getHistory(): Promise<HistoryItem[]> {
    const allUtxos = await this.engine.listUnspentOutputsData();
-    const ownOutpoints = new Set<string>();
-    const ownLockingBytecodes = new Set<string>();
    const invitationByOrigin = new Map<string, UtxoOriginContext>();
    const outpointValueSatoshis = new Map<string, bigint>();

@@ -137,8 +136,6 @@ export class HistoryService {
        utxo.outpointTransactionHash,
        utxo.outpointIndex,
      );
-      ownOutpoints.add(outpointKey);
-      ownLockingBytecodes.add(utxo.lockingBytecode);
      outpointValueSatoshis.set(outpointKey, BigInt(utxo.valueSatoshis));
    }

@@ -148,15 +145,15 @@ export class HistoryService {
      const template =
        (await this.engine.getTemplate(invitation.data.templateIdentifier)) ??
        null;
-      const walletEntityIdentifier = this.resolveWalletEntityIdentifier(
-        invitation,
-        ownOutpoints,
-        ownLockingBytecodes,
+      const walletCommits = await this.getWalletCommitsForInvitation(
+        invitation.data,
      );
+      const walletEntityIdentifier = walletCommits[0]?.entityIdentifier;
      contexts.set(invitation.data.invitationIdentifier, {
        invitation,
        template,
        variables,
+        walletCommits,
        walletEntityIdentifier,
      });
      this.indexInvitationOutputsByUtxoOrigin(invitationByOrigin, invitation);
@@ -186,7 +183,6 @@ export class HistoryService {
      const invitationInputs = this.buildWalletInputItemsForInvitation(
        context,
        roles[0],
-        invitationOutputs.length > 0,
        outpointValueSatoshis,
      );
      const invitationDescription = this.deriveInvitationDescription(
@@ -287,51 +283,25 @@ export class HistoryService {
    return outputs;
  }

+  private async getWalletCommitsForInvitation(
+    invitation: XOInvitation,
+  ): Promise<XOInvitationCommit[]> {
+    try {
+      return await this.engine.getOwnCommits(invitation);
+    } catch {
+      return [];
+    }
+  }
+
  private buildWalletInputItemsForInvitation(
    context: InvitationContext,
    walletRole?: string,
-    hasWalletOutputs: boolean = false,
    outpointValueSatoshis: Map<string, bigint> = new Map(),
  ): HistoryUtxoItem[] {
    const invitation = context.invitation.data;
-    const commits = invitation.commits ?? [];
-    const commitsByEntity = context.walletEntityIdentifier
-      ? commits.filter(
-          (commit) =>
-            commit.entityIdentifier === context.walletEntityIdentifier,
-        )
-      : [];
-    const commitsByRole = walletRole
-      ? commits.filter(
-          (commit) =>
-            this.deriveCommitRoleIdentifier(
-              commit,
-              invitation,
-              context.template,
-            ) === walletRole,
-        )
-      : [];
-
-    let relevantCommits = commitsByEntity.filter(
+    const relevantCommits = context.walletCommits.filter(
      (commit) => (commit.data.inputs?.length ?? 0) > 0,
    );
-    if (relevantCommits.length === 0) {
-      relevantCommits = commitsByRole.filter(
-        (commit) => (commit.data.inputs?.length ?? 0) > 0,
-      );
-    }
-    if (relevantCommits.length === 0 && walletRole === "sender") {
-      relevantCommits = commits.filter(
-        (commit) => (commit.data.inputs?.length ?? 0) > 0,
-      );
-    }
-    // Sender fallback only when no wallet outputs were matched.
-    if (relevantCommits.length === 0 && !hasWalletOutputs) {
-      relevantCommits = commits.filter(
-        (commit) => (commit.data.inputs?.length ?? 0) > 0,
-      );
-    }
-
    const txDescription = this.deriveTransactionActivityDescription(
      invitation,
      context.template,
@@ -355,7 +325,10 @@ export class HistoryService {
          context.variables,
        );
        const templateName = context.template?.name ?? "UnknownTemplate";
-        const role = walletRole ?? "sender";
+        const role =
+          this.deriveCommitRoleIdentifier(commit, invitation, context.template) ??
+          walletRole ??
+          "sender";
        const inputValue = this.resolveInputSatoshis(
          txHash,
          inputIndex,
@@ -422,13 +395,6 @@ export class HistoryService {
    };
  }

-  /**
-   * TODO: This is completely incorrect. It should be deriving the roles of the user based on the entity IDs in the commits, then mapping each commit to Inputs/Outputs so we know what belongs to the user.
-   *       There are a few changes that will need to be made to make this work:
-   *         1. Provide a way to derive all entity IDs of the user for the invitation (If we are going with XPub)
-   *         2. Provide a way to get only the User's commits (and their inputs/outputs)
-   *         3. (Maybe) Include role on inputs and outputs - This one might be fine with just using the commit entity id
-   */
  private deriveWalletRolesForInvitation(
    context: InvitationContext,
    outputs: HistoryUtxoItem[],
@@ -444,33 +410,20 @@ export class HistoryService {
      roles.add("receiver");
    }

-    const hasInputCommit = (
-      context.walletEntityIdentifier
-        ? context.invitation.data.commits.filter(
-            (c) => c.entityIdentifier === context.walletEntityIdentifier,
-          )
-        : context.invitation.data.commits
-    ).some((c) => (c.data.inputs?.length ?? 0) > 0);
-
-    if (hasInputCommit) roles.add("sender");
-    if (
-      !hasInputCommit &&
-      outputs.length === 0 &&
-      context.invitation.data.commits.some(
-        (c) => (c.data.inputs?.length ?? 0) > 0,
-      )
-    ) {
-      roles.add("sender");
-    }
-    if (roles.size === 0) {
-      const inferred = this.extractInvitationRoleIdentifier(
+    for (const commit of context.walletCommits) {
+      const role = this.deriveCommitRoleIdentifier(
+        commit,
        context.invitation.data,
        context.template,
-        context.walletEntityIdentifier,
      );
-      if (inferred) roles.add(inferred);
+      if (role) roles.add(role);
    }

+    const hasInputCommit = context.walletCommits.some(
+      (c) => (c.data.inputs?.length ?? 0) > 0,
+    );
+    if (hasInputCommit) roles.add("sender");
+
    return roles.size > 0 ? Array.from(roles) : ["unknown"];
  }

@@ -521,7 +474,7 @@ export class HistoryService {
    const originKey = this.getUtxoOriginKey(
      utxo.templateIdentifier,
      utxo.outputIdentifier,
-      utxo.lockingBytecode,
+      utxo.scriptHash,
    );
    return invitationByUtxoOrigin.get(originKey)?.invitationIdentifier;
  }
@@ -533,59 +486,11 @@ export class HistoryService {
    const originKey = this.getUtxoOriginKey(
      utxo.templateIdentifier,
      utxo.outputIdentifier,
-      utxo.lockingBytecode,
+      utxo.scriptHash,
    );
    return invitationByUtxoOrigin.get(originKey)?.roleIdentifier;
  }

-  private resolveWalletEntityIdentifier(
-    invitation: Invitation,
-    ownUtxoOutpointKeys: Set<string>,
-    ownLockingBytecodes: Set<string>,
-  ): string | undefined {
-    const scores = new Map<string, number>();
-    const addScore = (entityIdentifier: string, delta: number): void => {
-      scores.set(entityIdentifier, (scores.get(entityIdentifier) ?? 0) + delta);
-    };
-
-    for (const commit of invitation.data.commits) {
-      for (const input of commit.data.inputs ?? []) {
-        const txHash = input.outpointTransactionHash
-          ? input.outpointTransactionHash instanceof Uint8Array
-            ? binToHex(input.outpointTransactionHash)
-            : String(input.outpointTransactionHash)
-          : undefined;
-        if (!txHash || input.outpointIndex === undefined) continue;
-        if (
-          ownUtxoOutpointKeys.has(
-            this.getOutpointKey(txHash, input.outpointIndex),
-          )
-        ) {
-          addScore(commit.entityIdentifier, 3);
-        }
-      }
-      for (const output of commit.data.outputs ?? []) {
-        const lockingBytecodeHex = output.lockingBytecode
-          ? this.toLockingBytecodeHex(output.lockingBytecode)
-          : undefined;
-        if (!lockingBytecodeHex) continue;
-        if (ownLockingBytecodes.has(lockingBytecodeHex)) {
-          addScore(commit.entityIdentifier, 2);
-        }
-      }
-    }
-
-    let bestEntity: string | undefined;
-    let bestScore = 0;
-    for (const [entity, score] of scores.entries()) {
-      if (score > bestScore) {
-        bestScore = score;
-        bestEntity = entity;
-      }
-    }
-    return bestEntity;
-  }
-
  private deriveUtxoDescription(
    utxo: UnspentOutputData,
    template: XOTemplate | null,
@@ -715,27 +620,6 @@ export class HistoryService {
    return undefined;
  }

-  private extractInvitationRoleIdentifier(
-    invitation: XOInvitation,
-    template: XOTemplate | null,
-    walletEntityIdentifier?: string,
-  ): string | undefined {
-    if (walletEntityIdentifier) {
-      const commits = invitation.commits.filter(
-        (commit) => commit.entityIdentifier === walletEntityIdentifier,
-      );
-      for (const commit of commits) {
-        const role = this.deriveCommitRoleIdentifier(
-          commit,
-          invitation,
-          template,
-        );
-        if (role) return role;
-      }
-    }
-    return undefined;
-  }
-
  private inferRoleFromOutputIdentifier(
    outputIdentifier: string,
  ): string | undefined {
--- a/src/services/invitation.ts
+++ b/src/services/invitation.ts
@@ -2,7 +2,7 @@ import type {
  AcceptInvitationParameters,
  AppendInvitationParameters,
  Engine,
-  FindSuitableResourcesParameters,
+  GetSpendableResourcesParameters,
 } from "@xo-cash/engine";
 import { hasInvitationExpired, mergeInvitationCommits } from "@xo-cash/engine";
 import type {
@@ -34,7 +34,7 @@ import { compileCashAssemblyString } from "@xo-cash/engine";
 export type InvitationEventMap = {
  "invitation-updated": XOInvitation;
  "invitation-status-changed": string;
-  "error": Error;
+  error: Error;
 };

 export type InvitationDependencies = {
@@ -85,8 +85,11 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
      throw new Error(`Template not found: ${invitation.templateIdentifier}`);
    }

+    // engine invitation (I have no idea if this is required)
+    const engineInvitation = await dependencies.engine.acceptInvitation(invitation);
+
    // Create the invitation
-    const invitationInstance = new Invitation(invitation, dependencies);
+    const invitationInstance = new Invitation(engineInvitation, dependencies);

    // Start the invitation and its tracking
    await invitationInstance.start();
@@ -215,7 +218,9 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
  /**
   * Publish the invitation to the sync server
   */
-  private async publishInvitation(invitation: XOInvitation = this.data): Promise<void> {
+  private async publishInvitation(
+    invitation: XOInvitation = this.data,
+  ): Promise<void> {
    try {
      await this.syncServer.publishInvitation(invitation);
    } catch (err) {
@@ -481,12 +486,27 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
  }

  async findSuitableResources(
-    options: Partial<FindSuitableResourcesParameters> = {},
+    options: Partial<GetSpendableResourcesParameters> = {},
  ): Promise<UnspentOutputData[]> {
+    const templateIdentifier =
+      options.templateIdentifier ?? this.data.templateIdentifier;
+    const template = await this.engine.getTemplate(templateIdentifier);
+    const fallbackOutputIdentifier = Object.keys(template?.outputs ?? {})[0];
+    if (!fallbackOutputIdentifier && !options.outputIdentifier) {
+      throw new Error(
+        `No output identifiers found for template: ${templateIdentifier}`,
+      );
+    }
+
+    const resolvedOptions: GetSpendableResourcesParameters = {
+      templateIdentifier,
+      outputIdentifier: options.outputIdentifier ?? fallbackOutputIdentifier ?? "",
+    };
+
    // Find the suitable resources
-    const { unspentOutputs } = await this.engine.findSuitableResources(
+    const { unspentOutputs } = await this.engine.getSpendableResources(
      this.data,
-      options,
+      resolvedOptions,
    );

    // Update the status of the invitation
--- a/src/services/rates.ts
+++ b/src/services/rates.ts
@@ -0,0 +1,197 @@
+import { EventEmitter } from '../utils/event-emitter.js';
+import {
+  type RatesEventMap,
+} from '../utils/rates/base-rates.js';
+import { RatesOracle } from '../utils/rates/rates-oracles.js';
+
+/**
+ * Event map emitted by {@link RatesService}.
+ */
+export type RatesServiceEventMap = {
+  'rate-updated': {
+    numeratorUnitCode: string;
+    denominatorUnitCode: string;
+    price: number;
+    pair: string;
+    updatedAt: number;
+  };
+};
+
+/**
+ * In-memory representation of a market rate.
+ */
+type CachedRate = {
+  price: number;
+  updatedAt: number;
+};
+
+/**
+ * Minimal adapter contract that RatesService depends on.
+ *
+ * Using a small interface keeps the service decoupled and avoids inheriting
+ * implementation-specific type constraints from concrete adapters.
+ */
+export interface RatesAdapter {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  listPairs(): Promise<Set<string>>;
+  formatCurrency(amount: number, targetCurrency: string): string;
+  on(
+    type: 'rateUpdated',
+    listener: (detail: RatesEventMap['rateUpdated']) => void,
+  ): () => void;
+}
+
+/**
+ * Orchestrates the rates adapter lifecycle and provides BCH -> fiat helpers
+ * for the TUI.
+ *
+ * This service keeps a small in-memory snapshot of the latest prices and emits
+ * a normalized event whenever a pair changes. React components can subscribe
+ * through `useSyncExternalStore` for clean and predictable reactivity.
+ */
+export class RatesService extends EventEmitter<RatesServiceEventMap> {
+  private readonly adapter: RatesAdapter;
+  private readonly ratesByPair = new Map<string, CachedRate>();
+  private unsubscribeFromAdapter: (() => void) | null = null;
+  private started = false;
+
+  constructor(adapter: RatesAdapter) {
+    super();
+    this.adapter = adapter;
+  }
+
+  /**
+   * Creates a rates service.
+   *
+   * If no adapter is passed, this defaults to the Oracle-backed adapter.
+   */
+  public static async create(adapter?: RatesAdapter): Promise<RatesService> {
+    const resolvedAdapter = adapter ?? (await RatesOracle.from());
+    return new RatesService(resolvedAdapter);
+  }
+
+  /**
+   * Starts the underlying adapter and begins collecting live updates.
+   */
+  public async start(): Promise<void> {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+
+    this.unsubscribeFromAdapter = this.adapter.on('rateUpdated', (event) => {
+      this.handleRateUpdated(event);
+    });
+
+    try {
+      await this.adapter.start();
+    } catch (error) {
+      this.unsubscribeFromAdapter?.();
+      this.unsubscribeFromAdapter = null;
+      this.started = false;
+      throw error;
+    }
+  }
+
+  /**
+   * Stops live rate collection.
+   */
+  public async stop(): Promise<void> {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+
+    this.unsubscribeFromAdapter?.();
+    this.unsubscribeFromAdapter = null;
+
+    await this.adapter.stop();
+  }
+
+  /**
+   * Returns the latest price for a pair in NUMERATOR/DENOMINATOR form.
+   *
+   * Example: `getRate("USD", "BCH")`.
+   */
+  public getRate(
+    numeratorUnitCode: string,
+    denominatorUnitCode: string,
+  ): number | null {
+    const pair = this.getPairKey(numeratorUnitCode, denominatorUnitCode);
+    return this.ratesByPair.get(pair)?.price ?? null;
+  }
+
+  /**
+   * Converts satoshis to fiat using the latest BCH/fiat rate.
+   *
+   * Example: `convertBchToFiat(1234n, "USD")`.
+   */
+  public convertBchToFiat(
+    satoshis: bigint,
+    targetCurrency: string = 'USD',
+  ): number | null {
+    const rate = this.getRate(targetCurrency, 'BCH');
+    if (rate === null) {
+      return null;
+    }
+
+    const amountInBch = Number(satoshis) / 100_000_000;
+    return amountInBch * rate;
+  }
+
+  /**
+   * Formats a BCH -> fiat converted amount using the adapter formatter.
+   */
+  public formatBchToFiat(
+    satoshis: bigint,
+    targetCurrency: string = 'USD',
+  ): string | null {
+    const normalizedCurrency = targetCurrency.toUpperCase();
+    const amount = this.convertBchToFiat(satoshis, normalizedCurrency);
+    if (amount === null) {
+      return null;
+    }
+    return this.adapter.formatCurrency(amount, normalizedCurrency);
+  }
+
+  /**
+   * Formats an arbitrary fiat amount in a currency-aware way.
+   */
+  public formatCurrency(amount: number, currencyCode: string): string {
+    return this.adapter.formatCurrency(amount, currencyCode.toUpperCase());
+  }
+
+  /**
+   * Handles normalized updates from the underlying adapter.
+   */
+  private handleRateUpdated(event: RatesEventMap['rateUpdated']): void {
+    const numeratorUnitCode = event.numeratorUnitCode.toUpperCase();
+    const denominatorUnitCode = event.denominatorUnitCode.toUpperCase();
+    const pair = this.getPairKey(numeratorUnitCode, denominatorUnitCode);
+    const updatedAt = Date.now();
+
+    this.ratesByPair.set(pair, {
+      price: event.price,
+      updatedAt,
+    });
+
+    this.emit('rate-updated', {
+      numeratorUnitCode,
+      denominatorUnitCode,
+      price: event.price,
+      pair,
+      updatedAt,
+    });
+  }
+
+  /**
+   * Creates a stable key for pair lookups.
+   */
+  private getPairKey(
+    numeratorUnitCode: string,
+    denominatorUnitCode: string,
+  ): string {
+    return `${numeratorUnitCode.toUpperCase()}/${denominatorUnitCode.toUpperCase()}`;
+  }
+}
--- a/src/tui/components/VariableInputField.tsx
+++ b/src/tui/components/VariableInputField.tsx
@@ -1,6 +1,7 @@
-import React from "react";
+import React, { useMemo } from "react";
 import { Box, Text } from "ink";
 import TextInput from "./TextInput.js";
+import { useSatoshisConversion } from "../hooks/useSatoshisConversion.js";

 interface VariableInputFieldProps {
  variable: {
@@ -18,6 +19,45 @@ interface VariableInputFieldProps {
  focusColor: string;
 }

+const SATOSHIS_PER_BCH = 100_000_000n;
+
+/**
+ * Returns true when the variable is an integer satoshis field.
+ */
+function isSatoshisVariable(variable: VariableInputFieldProps["variable"]): boolean {
+  return (
+    variable.type === "integer" &&
+    variable.hint?.toLowerCase().includes("satoshi") === true
+  );
+}
+
+/**
+ * Parse a strict integer string into bigint.
+ */
+function parseSatoshis(value: string): bigint | null {
+  const trimmed = value.trim();
+  if (!/^[-]?\d+$/.test(trimmed)) {
+    return null;
+  }
+
+  try {
+    return BigInt(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format satoshis as BCH with fixed 8 decimals, preserving bigint precision.
+ */
+function formatBchFromSatoshis(satoshis: bigint): string {
+  const sign = satoshis < 0n ? "-" : "";
+  const absolute = satoshis < 0n ? satoshis * -1n : satoshis;
+  const whole = absolute / SATOSHIS_PER_BCH;
+  const fractional = absolute % SATOSHIS_PER_BCH;
+  return `${sign}${whole.toString()}.${fractional.toString().padStart(8, "0")} BCH`;
+}
+
 export function VariableInputField({
  variable,
  index,
@@ -27,6 +67,26 @@ export function VariableInputField({
  borderColor,
  focusColor,
 }: VariableInputFieldProps): React.ReactElement {
+  const { currencyCode, formattedFiatPerBchRate, formatSatoshisToFiat } =
+    useSatoshisConversion("USD");
+  const satoshisValue = useMemo(
+    () => parseSatoshis(variable.value),
+    [variable.value],
+  );
+  const formattedBch = useMemo(() => {
+    if (satoshisValue === null) {
+      return null;
+    }
+    return formatBchFromSatoshis(satoshisValue);
+  }, [satoshisValue]);
+  const formattedFiat = useMemo(() => {
+    if (satoshisValue === null) {
+      return null;
+    }
+    return formatSatoshisToFiat(satoshisValue);
+  }, [satoshisValue, formatSatoshisToFiat]);
+  const shouldShowSatoshisConversion = isSatoshisVariable(variable);
+
  return (
    <Box flexDirection="column" marginBottom={1}>
      <Text color={focusColor}>{variable.name}</Text>
@@ -54,12 +114,29 @@ export function VariableInputField({
        <Text color={borderColor} dimColor>{variable.hint}</Text>
        
      </Box>
-      {variable.type === 'integer' && variable.hint === 'satoshis' && (
-        <Box>
-          <Text color={borderColor} dimColor>
-            {/* Convert from sats to bch. NOTE: we can't use the formatSatoshis function because it is too verbose and returns too many values in the string*/}
-            {(Number(variable.value) / 100_000_000).toFixed(8)} BCH
-          </Text>
+      {shouldShowSatoshisConversion && (
+        <Box flexDirection="column">
+          {formattedBch ? (
+            <>
+              <Text color={borderColor} dimColor>
+                {formattedBch}
+              </Text>
+              <Text color={borderColor} dimColor>
+                {formattedFiat
+                  ? `Approx. ${currencyCode}: ${formattedFiat}`
+                  : `Approx. ${currencyCode}: waiting for live rate...`}
+              </Text>
+              {formattedFiatPerBchRate && (
+                <Text color={borderColor} dimColor>
+                  1 BCH = {formattedFiatPerBchRate}
+                </Text>
+              )}
+            </>
+          ) : (
+            <Text color={borderColor} dimColor>
+              Enter a whole satoshi amount to preview BCH/{currencyCode} conversion.
+            </Text>
+          )}
        </Box>
      )}
    </Box>
--- a/src/tui/hooks/index.ts
+++ b/src/tui/hooks/index.ts
@@ -23,3 +23,5 @@ export {
  useBlockableInput,
  useIsInputCaptured,
 } from "./useInputLayer.js";
+export { useRate, useBchToFiatRate } from "./useRates.js";
+export { useSatoshisConversion } from "./useSatoshisConversion.js";
--- a/src/tui/hooks/useRates.tsx
+++ b/src/tui/hooks/useRates.tsx
@@ -0,0 +1,68 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import type { RatesServiceEventMap } from '../../services/rates.js';
+import { useAppContext } from './useAppContext.js';
+
+/**
+ * Reactive hook for a single market pair.
+ *
+ * Pair format is NUMERATOR / DENOMINATOR, e.g. USD / BCH.
+ */
+export function useRate(
+  numeratorUnitCode: string,
+  denominatorUnitCode: string,
+): number | null {
+  const { appService } = useAppContext();
+
+  const normalizedNumerator = useMemo(
+    () => numeratorUnitCode.toUpperCase(),
+    [numeratorUnitCode],
+  );
+  
+  const normalizedDenominator = useMemo(
+    () => denominatorUnitCode.toUpperCase(),
+    [denominatorUnitCode],
+  );
+
+  const subscribe = useCallback(
+    (callback: () => void) => {
+      if (!appService) {
+        return () => {};
+      }
+
+      const onRateUpdated = (event: RatesServiceEventMap['rate-updated']) => {
+        if (
+          event.numeratorUnitCode === normalizedNumerator &&
+          event.denominatorUnitCode === normalizedDenominator
+        ) {
+          callback();
+        }
+      };
+
+      const unsubscribe = appService.rates.on('rate-updated', onRateUpdated);
+
+      return () => {
+        unsubscribe();
+      };
+    },
+    [appService, normalizedNumerator, normalizedDenominator],
+  );
+
+  const getSnapshot = useCallback(() => {
+    if (!appService) {
+      return null;
+    }
+
+    return appService.rates.getRate(normalizedNumerator, normalizedDenominator);
+  }, [appService, normalizedNumerator, normalizedDenominator]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Convenience hook for BCH -> fiat market rates.
+ */
+export function useBchToFiatRate(
+  targetCurrency: string = 'USD',
+): number | null {
+  return useRate(targetCurrency, 'BCH');
+}
--- a/src/tui/hooks/useSatoshisConversion.tsx
+++ b/src/tui/hooks/useSatoshisConversion.tsx
@@ -0,0 +1,42 @@
+import { useCallback, useMemo } from 'react';
+import { useAppContext } from './useAppContext.js';
+import { useBchToFiatRate } from './useRates.js';
+
+/**
+ * Reactive BCH satoshis -> fiat conversion helpers for TUI screens.
+ *
+ * This hook subscribes to rate updates through `useBchToFiatRate`, so any
+ * component using it will re-render automatically when the selected pair
+ * receives a new quote.
+ */
+export function useSatoshisConversion(targetCurrency: string = 'USD') {
+  const { appService } = useAppContext();
+  const currencyCode = useMemo(() => targetCurrency.toUpperCase(), [targetCurrency]);
+  const fiatPerBchRate = useBchToFiatRate(currencyCode);
+
+  const formattedFiatPerBchRate = useMemo(() => {
+    if (!appService || fiatPerBchRate === null) {
+      return null;
+    }
+
+    return appService.rates.formatCurrency(fiatPerBchRate, currencyCode);
+  }, [appService, fiatPerBchRate, currencyCode]);
+
+  const formatSatoshisToFiat = useCallback(
+    (satoshis: bigint): string | null => {
+      if (!appService || fiatPerBchRate === null) {
+        return null;
+      }
+
+      return appService.rates.formatBchToFiat(satoshis, currencyCode);
+    },
+    [appService, fiatPerBchRate, currencyCode],
+  );
+
+  return {
+    currencyCode,
+    fiatPerBchRate,
+    formattedFiatPerBchRate,
+    formatSatoshisToFiat,
+  } as const;
+}
--- a/src/tui/screens/TemplateList.tsx
+++ b/src/tui/screens/TemplateList.tsx
@@ -100,8 +100,8 @@ export function TemplateListScreen(): React.ReactElement {
          for (const startingAction of rawStartingActions) {
            const existing = actionMap.get(startingAction.action);
            if (existing) {
-              if (!existing.roles.includes(startingAction.role)) {
-                existing.roles.push(startingAction.role);
+              if (!existing.roles.includes(startingAction.role ?? '')) {
+                existing.roles.push(startingAction.role ?? '');
              }
              continue;
            }
@@ -111,7 +111,7 @@ export function TemplateListScreen(): React.ReactElement {
              actionIdentifier: startingAction.action,
              name: actionDef?.name || startingAction.action,
              description: actionDef?.description,
-              roles: [startingAction.role],
+              roles: [startingAction.role ?? ''],
              source: 'starting',
            });
          }
@@ -119,9 +119,9 @@ export function TemplateListScreen(): React.ReactElement {
          const ownedOutputIdentifiers = ownedOutputsByTemplate.get(templateIdentifier) ?? new Set<string>();
          for (const outputIdentifier of ownedOutputIdentifiers) {
            const outputDef = template.outputs?.[outputIdentifier];
-            if (!outputDef || typeof outputDef.lockscript !== 'string') continue;
+            if (!outputDef || typeof outputDef.lockingScript !== 'string') continue;

-            const lockingScriptDefinition = (template.lockingScripts as Record<string, unknown> | undefined)?.[outputDef.lockscript] as
+            const lockingScriptDefinition = (template.lockingScripts as Record<string, unknown> | undefined)?.[outputDef.lockingScript] as
              | { roles?: Record<string, { actions?: Array<{ action?: string; role?: string } | string> }> }
              | undefined;
            if (!lockingScriptDefinition?.roles) continue;
@@ -217,14 +217,10 @@ export function TemplateListScreen(): React.ReactElement {
        action.roles.length,
        index
      );
-      const sourceSuffix = action.source === 'next'
-        ? ' [next]'
-        : action.source === 'starting+next'
-          ? ' [start+next]'
-          : '';
+
      return {
        key: action.actionIdentifier,
-        label: `${formatted.label}${sourceSuffix}`,
+        label: `${formatted.label}`,
        description: formatted.description,
        value: action,
        hidden: !formatted.isValid,
--- a/src/tui/screens/WalletState.tsx
+++ b/src/tui/screens/WalletState.tsx
@@ -13,6 +13,7 @@ import { ScrollableList, type ListItemData } from '../components/List.js';
 import { QRCode } from '../components/QRCode.js';
 import { useNavigation } from '../hooks/useNavigation.js';
 import { useAppContext, useStatus } from '../hooks/useAppContext.js';
+import { useSatoshisConversion } from '../hooks/useSatoshisConversion.js';
 import { useInputLayer, useLayeredInput, useBlockableInput, useIsInputCaptured } from '../hooks/useInputLayer.js';
 import { colors, formatSatoshis, formatHex, logoSmall } from '../theme.js';
 import type { HistoryItem } from '../../services/history.js';
@@ -108,6 +109,12 @@ export function WalletStateScreen(): React.ReactElement {
  const { navigate } = useNavigation();
  const { appService, showError, showInfo } = useAppContext();
  const { setStatus } = useStatus();
+  const {
+    currencyCode,
+    fiatPerBchRate,
+    formattedFiatPerBchRate,
+    formatSatoshisToFiat,
+  } = useSatoshisConversion('USD');

  // State
  const [balance, setBalance] = useState<{ totalSatoshis: bigint; utxoCount: number } | null>(null);
@@ -297,6 +304,26 @@ export function WalletStateScreen(): React.ReactElement {
    });
  }, [history]);

+  /**
+   * Fiat values are memoized so we only recompute when balance or rate changes.
+   */
+  const formattedUsdPerBchRate = useMemo(() => {
+    return formattedFiatPerBchRate;
+  }, [formattedFiatPerBchRate]);
+
+  const formattedUsdBalance = useMemo(() => {
+    if (!balance || fiatPerBchRate === null) {
+      return null;
+    }
+
+    return formatSatoshisToFiat(balance.totalSatoshis);
+  }, [balance, fiatPerBchRate, formatSatoshisToFiat]);
+
+  const getFiatSuffix = useCallback((satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  }, [formatSatoshisToFiat]);
+
  // Screen input — automatically blocked when any dialog/overlay is capturing.
  const isCaptured = useIsInputCaptured();

@@ -335,11 +362,16 @@ export function WalletStateScreen(): React.ReactElement {
    }

    if (row.type === 'invitation_input') {
+      const inputSatoshis = row.utxo?.valueSatoshis;
+      const inputFiatSuffix = inputSatoshis !== undefined
+        ? getFiatSuffix(inputSatoshis)
+        : '';
      return (
        <Box flexDirection="row" justifyContent="space-between">
          <Box>
            <Text color={itemColor}>
              {indicator}{groupingPrefix}[Input] {row.label}
+              {inputFiatSuffix}
            </Text>
            {row.description && <Text color={colors.textMuted}> {row.description}</Text>}
          </Box>
@@ -355,6 +387,7 @@ export function WalletStateScreen(): React.ReactElement {
          <Box flexDirection="row">
            <Text color={itemColor}>
              {indicator}{groupingPrefix}[Output] {formatSatoshis(sats)}
+              {getFiatSuffix(sats)}
            </Text>
            {row.description && <Text color={colors.textMuted}> {row.description}</Text>}
          </Box>
@@ -369,7 +402,10 @@ export function WalletStateScreen(): React.ReactElement {
      return (
        <Box flexDirection="row" justifyContent="space-between">
          <Box flexDirection="row">
-            <Text color={itemColor}>{indicator}{formatSatoshis(sats)}</Text>
+            <Text color={itemColor}>
+              {indicator}{formatSatoshis(sats)}
+              {getFiatSuffix(sats)}
+            </Text>
            {row.description && <Text color={colors.textMuted}> {row.description}{reservedTag}</Text>}
          </Box>
          {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
@@ -386,7 +422,7 @@ export function WalletStateScreen(): React.ReactElement {
        {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
      </Box>
    );
-  }, []);
+  }, [getFiatSuffix]);

  return (
    <Box flexDirection="column" flexGrow={1}>
@@ -418,6 +454,20 @@ export function WalletStateScreen(): React.ReactElement {
                  <Text color={colors.success} bold>
                    {formatSatoshis(balance.totalSatoshis)}
                  </Text>
+                  {formattedUsdBalance ? (
+                    <Text color={colors.info}>
+                      Approx. Fiat ({currencyCode}): {formattedUsdBalance}
+                    </Text>
+                  ) : (
+                    <Text color={colors.textMuted}>
+                      Approx. Fiat ({currencyCode}): Waiting for BCH/{currencyCode} rate...
+                    </Text>
+                  )}
+                  {formattedUsdPerBchRate && (
+                    <Text color={colors.textMuted}>
+                      1 BCH = {formattedUsdPerBchRate}
+                    </Text>
+                  )}
                  <Text color={colors.textMuted}>
                    UTXOs: {balance.utxoCount}
                  </Text>
--- a/src/tui/screens/action-wizard/flows/index.ts
+++ b/src/tui/screens/action-wizard/flows/index.ts
@@ -15,7 +15,7 @@ export { DataWizardFlow } from "./DataWizardFlow.js";
 */
 export function createWizardFlow(action: XOTemplateAction): WizardFlow {
  if (action.data?.length && !action.transaction) {
-    return new DataWizardFlow(action.data);
+    return new DataWizardFlow([action.data]);
  }
  return new TransactionWizardFlow();
 }
--- a/src/tui/screens/action-wizard/steps/InputsStep.tsx
+++ b/src/tui/screens/action-wizard/steps/InputsStep.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis, formatHex } from '../../../theme.js';
+import { useSatoshisConversion } from '../../../hooks/useSatoshisConversion.js';
 import type { SelectableUTXO, FocusArea } from '../types.js';

 interface Props {
@@ -22,6 +23,13 @@ export function InputsStep({
  changeAmount,
  focusArea,
 }: Props): React.ReactElement {
+  const { formatSatoshisToFiat } = useSatoshisConversion('USD');
+
+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
  return (
    <Box flexDirection='column'>
      <Text color={colors.text} bold>
@@ -32,6 +40,7 @@ export function InputsStep({
        <Text color={colors.textMuted}>
          Required: {formatSatoshis(requiredAmount)} +{' '}
          {formatSatoshis(fee)} fee
+          {getFiatSuffix(requiredAmount + fee)}
        </Text>
        <Text
          color={
@@ -41,10 +50,12 @@ export function InputsStep({
          }
        >
          Selected: {formatSatoshis(selectedAmount)}
+          {getFiatSuffix(selectedAmount)}
        </Text>
        {selectedAmount > requiredAmount + fee && (
          <Text color={colors.info}>
            Change: {formatSatoshis(changeAmount)}
+            {getFiatSuffix(changeAmount)}
          </Text>
        )}
      </Box>
@@ -65,6 +76,7 @@ export function InputsStep({
            return (
              <Box
                key={`${utxo.outpointTransactionHash}:${utxo.outpointIndex}`}
+                flexDirection='column'
              >
                <Text
                  color={isCursor ? colors.focus : colors.text}
@@ -75,6 +87,15 @@ export function InputsStep({
                  {formatHex(utxo.outpointTransactionHash, 12)}:
                  {utxo.outpointIndex}
                </Text>
+                {(() => {
+                  const fiatValue = formatSatoshisToFiat(utxo.valueSatoshis);
+                  if (!fiatValue) return null;
+                  return (
+                    <Text color={colors.textMuted}>
+                      {'   '}≈ {fiatValue}
+                    </Text>
+                  );
+                })()}
              </Box>
            );
          })
--- a/src/tui/screens/action-wizard/steps/ReviewStep.tsx
+++ b/src/tui/screens/action-wizard/steps/ReviewStep.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../theme.js';
+import { useSatoshisConversion } from '../../../hooks/useSatoshisConversion.js';
 import type { VariableInput, SelectableUTXO } from '../types.js';
 import type { XOTemplate } from '@xo-cash/types';

@@ -22,6 +23,32 @@ export function ReviewStep({
  changeAmount,
 }: ReviewStepProps): React.ReactElement {
  const selectedUtxos = availableUtxos.filter((u) => u.selected);
+  const { formatSatoshisToFiat } = useSatoshisConversion('USD');
+
+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
+  const getVariableFiatSuffix = (variable: VariableInput): string => {
+    if (variable.type !== 'integer') {
+      return '';
+    }
+
+    if (variable.hint?.toLowerCase().includes('satoshi') !== true) {
+      return '';
+    }
+
+    if (!/^[-]?\d+$/.test(variable.value.trim())) {
+      return '';
+    }
+
+    try {
+      return getFiatSuffix(BigInt(variable.value));
+    } catch {
+      return '';
+    }
+  };

  return (
    <Box flexDirection='column'>
@@ -44,6 +71,7 @@ export function ReviewStep({
            <Text key={v.id} color={colors.textMuted}>
              {'  '}
              {v.name}: {v.value || '(empty)'}
+              {v.value ? getVariableFiatSuffix(v) : ''}
            </Text>
          ))}
        </Box>
@@ -62,6 +90,7 @@ export function ReviewStep({
            >
              {'  '}
              {formatSatoshis(u.valueSatoshis)}
+              {getFiatSuffix(u.valueSatoshis)}
            </Text>
          ))}
          {selectedUtxos.length > 3 && (
@@ -78,6 +107,7 @@ export function ReviewStep({
          <Text color={colors.text}>Outputs:</Text>
          <Text color={colors.textMuted}>
            {'  '}Change: {formatSatoshis(changeAmount)}
+            {getFiatSuffix(changeAmount)}
          </Text>
        </Box>
      )}
--- a/src/tui/screens/action-wizard/steps/RoleSelectStep.tsx
+++ b/src/tui/screens/action-wizard/steps/RoleSelectStep.tsx
@@ -61,13 +61,16 @@ export function RoleSelectStep({
        {availableRoles.length === 0 ? (
          <Text color={colors.textMuted}>No roles available</Text>
        ) : (
-          availableRoles.map((roleId, index) => {
+          availableRoles.map((roleId: string, index: number) => {
            const isCursor =
              selectedRoleIndex === index && focusArea === 'content';
            const roleDef = template.roles?.[roleId];
            const actionRole = action?.roles?.[roleId];
            const requirements = actionRole?.requirements;

+            const actionRequirements = action?.requirements;
+            const actionRoleRequirements = actionRole && actionRequirements && actionRequirements.participants?.find((participant) => participant.role === roleId);
+
            return (
              <Box key={roleId} flexDirection="column" marginY={0}>
                <Text
@@ -96,10 +99,10 @@ export function RoleSelectStep({
                        {'  '}
                      </Text>
                    )}
-                    {requirements.slots && requirements.slots.min > 0 && (
+                    {actionRoleRequirements && actionRoleRequirements.slots && actionRoleRequirements.slots.min > 0 && (
                      <Text color={colors.textMuted} dimColor>
-                        {requirements.slots.min} input slot
-                        {requirements.slots.min !== 1 ? 's' : ''}
+                        {actionRoleRequirements.slots.min} input slot
+                        {actionRoleRequirements.slots.min !== 1 ? 's' : ''}
                      </Text>
                    )}
                  </Box>
--- a/src/tui/screens/invitations/InvitationScreen.tsx
+++ b/src/tui/screens/invitations/InvitationScreen.tsx
@@ -17,6 +17,7 @@ import { useNavigation } from '../../hooks/useNavigation.js';
 import { useAppContext, useStatus } from '../../hooks/useAppContext.js';
 import { useBlockableInput, useIsInputCaptured } from '../../hooks/useInputLayer.js';
 import { useInvitations } from '../../hooks/useInvitations.js';
+import { useSatoshisConversion } from '../../hooks/useSatoshisConversion.js';
 import { colors, logoSmall, formatSatoshis } from '../../theme.js';
 import { copyToClipboard } from '../../utils/clipboard.js';
 import type { Invitation } from '../../../services/invitation.js';
@@ -88,6 +89,8 @@ export function InvitationScreen(): React.ReactElement {
  const { setStatus } = useStatus();

  const invitations = useInvitations();
+  const { currencyCode, formattedFiatPerBchRate, formatSatoshisToFiat } =
+    useSatoshisConversion('USD');

  // ── UI state ─────────────────────────────────────────────────────────────
  const [selectedIndex, setSelectedIndex] = useState(0);
@@ -99,6 +102,7 @@ export function InvitationScreen(): React.ReactElement {
  // Two phases: first the ID input dialog, then the multi-step import flow.
  const [showIdDialog, setShowIdDialog] = useState(false);
  const [importingId, setImportingId] = useState<string | null>(null);
+  const [pendingImportedInvitationId, setPendingImportedInvitationId] = useState<string | null>(null);

  // ── Template cache ───────────────────────────────────────────────────────
  const [templateCache, setTemplateCache] = useState<Map<string, XOTemplate>>(new Map());
@@ -158,7 +162,7 @@ export function InvitationScreen(): React.ReactElement {
    });

    return [importItem, ...invitationItems];
-  }, [invitations, templateCache]);
+  }, [invitations.length, templateCache]);

  const selectedItem = listItems[selectedIndex];
  const selectedInvitation = selectedItem?.value ?? null;
@@ -193,10 +197,30 @@ export function InvitationScreen(): React.ReactElement {
  /**
   * Import flow closed (completed or cancelled).
   */
-  const handleImportFlowClose = useCallback(() => {
+  const handleImportFlowClose = useCallback((importedInvitationId?: string) => {
+    if (importedInvitationId) {
+      setPendingImportedInvitationId(importedInvitationId);
+    }
    setImportingId(null);
  }, []);

+  /**
+   * Once imported invitation is visible in the list, select and focus it.
+   */
+  useEffect(() => {
+    if (!pendingImportedInvitationId) return;
+
+    const importedIndex = listItems.findIndex((item) => {
+      return item.value?.data.invitationIdentifier === pendingImportedInvitationId;
+    });
+
+    if (importedIndex >= 0) {
+      setSelectedIndex(importedIndex);
+      setFocusedPanel('list');
+      setPendingImportedInvitationId(null);
+    }
+  }, [pendingImportedInvitationId, listItems]);
+
  // ── Action handlers ────────────────────────────────────────────────────

  const acceptInvitation = useCallback(async () => {
@@ -327,10 +351,10 @@ export function InvitationScreen(): React.ReactElement {
      const seenLockingBytecodes = new Set<string>();

      for (const utxo of utxos) {
-        const lockingBytecodeHex = utxo.lockingBytecode
-          ? typeof utxo.lockingBytecode === 'string'
-            ? utxo.lockingBytecode
-            : Buffer.from(utxo.lockingBytecode).toString('hex')
+        const lockingBytecodeHex = utxo.scriptHash
+          ? typeof utxo.scriptHash === 'string'
+            ? utxo.scriptHash
+            : Buffer.from(utxo.scriptHash).toString('hex')
          : undefined;

        if (lockingBytecodeHex && seenLockingBytecodes.has(lockingBytecodeHex)) continue;
@@ -494,6 +518,44 @@ export function InvitationScreen(): React.ReactElement {
    const roleInfoRaw = userRole && selectedTemplate?.roles?.[userRole];
    const roleInfo = roleInfoRaw && typeof roleInfoRaw === 'object' ? roleInfoRaw : null;

+    const getFiatSuffix = (satoshis: bigint): string => {
+      const fiatValue = formatSatoshisToFiat(satoshis);
+      return fiatValue ? ` (~${fiatValue})` : '';
+    };
+
+    const parseNumberishToBigInt = (value: unknown): bigint | null => {
+      if (typeof value === 'bigint') {
+        return value;
+      }
+
+      const asString = String(value).trim();
+      if (!/^[-]?\d+$/.test(asString)) {
+        return null;
+      }
+
+      try {
+        return BigInt(asString);
+      } catch {
+        return null;
+      }
+    };
+
+    const isSatoshisVariable = (variableIdentifier: string): boolean => {
+      const templateVariable = selectedTemplate?.variables?.[variableIdentifier];
+      const templateType = templateVariable?.type?.toLowerCase();
+      const templateHint = templateVariable?.hint?.toLowerCase();
+      const identifier = variableIdentifier.toLowerCase();
+
+      if (templateHint?.includes('satoshi')) {
+        return true;
+      }
+
+      return (
+        templateType === 'integer' &&
+        (identifier.includes('satoshi') || identifier.includes('amount'))
+      );
+    };
+
    return (
      <Box flexDirection="column">
        {/* Type & Status */}
@@ -514,6 +576,11 @@ export function InvitationScreen(): React.ReactElement {
              <Text color={colors.textMuted}>
                Action: {action?.name ?? selectedInvitation.data.actionIdentifier}
              </Text>
+              {formattedFiatPerBchRate && (
+                <Text color={colors.textMuted}>
+                  1 BCH = {formattedFiatPerBchRate}
+                </Text>
+              )}
              {action?.description && (
                <Text color={colors.textMuted} dimColor>{action.description}</Text>
              )}
@@ -542,6 +609,11 @@ export function InvitationScreen(): React.ReactElement {
              inputs.map((input, idx) => {
                const isUserInput = input.entityIdentifier === userEntityId;
                const inputTemplate = selectedTemplate?.inputs?.[input.inputIdentifier ?? ''];
+                const inputSatoshis = (
+                  'valueSatoshis' in input && input.valueSatoshis !== undefined
+                )
+                  ? parseNumberishToBigInt(input.valueSatoshis)
+                  : null;
                return (
                  <Text
                    key={`input-${idx}`}
@@ -550,6 +622,7 @@ export function InvitationScreen(): React.ReactElement {
                    {'  '}{isUserInput ? '• ' : '○ '}
                    {inputTemplate?.name ?? input.inputIdentifier ?? `Input ${idx}`}
                    {input.roleIdentifier && ` (${input.roleIdentifier})`}
+                    {inputSatoshis !== null && ` ${formatSatoshis(inputSatoshis)}${getFiatSuffix(inputSatoshis)}`}
                  </Text>
                );
              })
@@ -564,6 +637,9 @@ export function InvitationScreen(): React.ReactElement {
              outputs.map((output, idx) => {
                const isUserOutput = output.entityIdentifier === userEntityId;
                const outputTemplate = selectedTemplate?.outputs?.[output.outputIdentifier ?? ''];
+                const outputSatoshis = output.valueSatoshis !== undefined
+                  ? parseNumberishToBigInt(output.valueSatoshis)
+                  : null;
                return (
                  <Text
                    key={`output-${idx}`}
@@ -571,7 +647,7 @@ export function InvitationScreen(): React.ReactElement {
                  >
                    {'  '}{isUserOutput ? '• ' : '○ '}
                    {outputTemplate?.name ?? output.outputIdentifier ?? `Output ${idx}`}
-                    {output.valueSatoshis !== undefined && ` (${formatSatoshis(output.valueSatoshis)})`}
+                    {outputSatoshis !== null && ` (${formatSatoshis(outputSatoshis)}${getFiatSuffix(outputSatoshis)})`}
                  </Text>
                );
              })
@@ -591,6 +667,9 @@ export function InvitationScreen(): React.ReactElement {
              const displayValue = typeof variable.value === 'bigint'
                ? variable.value.toString()
                : String(variable.value);
+              const parsedVariableSatoshis = isSatoshisVariable(variable.variableIdentifier)
+                ? parseNumberishToBigInt(variable.value)
+                : null;
              return (
                <Text
                  key={`var-${idx}`}
@@ -598,6 +677,8 @@ export function InvitationScreen(): React.ReactElement {
                >
                  {'  '}{isUserVariable ? '• ' : '○ '}
                  {varTemplate?.name ?? variable.variableIdentifier}: {displayValue}
+                  {parsedVariableSatoshis !== null &&
+                    ` (${formatSatoshis(parsedVariableSatoshis)}${getFiatSuffix(parsedVariableSatoshis)})`}
                  {varTemplate?.description && (
                    <Text color={colors.textMuted} dimColor> - {varTemplate.description}</Text>
                  )}
--- a/src/tui/screens/invitations/invitation-import/InvitationImportFlow.tsx
+++ b/src/tui/screens/invitations/invitation-import/InvitationImportFlow.tsx
@@ -148,7 +148,7 @@ export function InvitationImportFlow({
      `Action: ${invitation?.data.actionIdentifier ?? 'Unknown'}`
    );
    setStatus('Ready');
-    onClose();
+    onClose(invitation?.data.invitationIdentifier);
  }, [selectedRole, template, invitation, showInfo, setStatus, onClose]);

  // ── Keyboard handling ────────────────────────────────────────────────────
--- a/src/tui/screens/invitations/invitation-import/steps/InputsSelectStep.tsx
+++ b/src/tui/screens/invitations/invitation-import/steps/InputsSelectStep.tsx
@@ -9,6 +9,7 @@
 import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../../theme.js';
+import { useSatoshisConversion } from '../../../../hooks/useSatoshisConversion.js';
 import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import type { InputsSelectStepProps, SelectableUTXO } from '../types.js';
 import { autoSelectGreedyUtxos, mapUnspentOutputsToSelectable } from '../../../../../utils/invitation-flow.js';
@@ -32,6 +33,7 @@ export function InputsSelectStep({
  const [requiredAmount, setRequiredAmount] = useState(0n);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
+  const { formatSatoshisToFiat } = useSatoshisConversion('USD');

  const fee = DEFAULT_FEE;

@@ -42,6 +44,11 @@ export function InputsSelectStep({
  const changeAmount = selectedAmount - requiredAmount - fee;
  const hasEnough = selectedAmount >= requiredAmount + fee;

+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
  /**
   * Determine the required satoshi amount from the invitation's variables.
   */
@@ -193,18 +200,32 @@ export function InputsSelectStep({
      {/* Summary bar */}
      <Box flexDirection="row" marginBottom={1}>
        <Text color={colors.primary} bold>Required: </Text>
-        <Text color={colors.text}>{formatSatoshis(requiredAmount + fee)}</Text>
+        <Text color={colors.text}>
+          {formatSatoshis(requiredAmount + fee)}
+          {getFiatSuffix(requiredAmount + fee)}
+        </Text>
        <Text color={colors.textMuted}> (amount {formatSatoshis(requiredAmount)} + fee {formatSatoshis(fee)})</Text>
      </Box>

      <Box flexDirection="row" marginBottom={1}>
        <Text color={colors.primary} bold>Selected: </Text>
-        <Text color={hasEnough ? colors.success : colors.error}>{formatSatoshis(selectedAmount)}</Text>
+        <Text color={hasEnough ? colors.success : colors.error}>
+          {formatSatoshis(selectedAmount)}
+          {getFiatSuffix(selectedAmount)}
+        </Text>
        {hasEnough && changeAmount >= DUST_THRESHOLD && (
-          <Text color={colors.textMuted}> (change: {formatSatoshis(changeAmount)})</Text>
+          <Text color={colors.textMuted}>
+            {' '}
+            (change: {formatSatoshis(changeAmount)}
+            {getFiatSuffix(changeAmount)})
+          </Text>
        )}
        {!hasEnough && (
-          <Text color={colors.error}> — need {formatSatoshis(requiredAmount + fee - selectedAmount)} more</Text>
+          <Text color={colors.error}>
+            {' '}
+            — need {formatSatoshis(requiredAmount + fee - selectedAmount)}
+            {getFiatSuffix(requiredAmount + fee - selectedAmount)} more
+          </Text>
        )}
      </Box>

@@ -216,13 +237,22 @@ export function InputsSelectStep({
        const txShort = utxo.outpointTransactionHash.slice(0, 8);

        return (
-          <Text
+          <Box
            key={`${utxo.outpointTransactionHash}:${utxo.outpointIndex}`}
-            color={isFocused ? colors.focus : utxo.selected ? colors.success : colors.text}
-            bold={isFocused}
+            flexDirection="column"
          >
-            {isFocused ? '▸ ' : '  '}{checkMark} {formatSatoshis(utxo.valueSatoshis)} ({txShort}…:{utxo.outpointIndex})
-          </Text>
+            <Text
+              color={isFocused ? colors.focus : utxo.selected ? colors.success : colors.text}
+              bold={isFocused}
+            >
+              {isFocused ? '▸ ' : '  '}{checkMark} {formatSatoshis(utxo.valueSatoshis)} ({txShort}…:{utxo.outpointIndex})
+            </Text>
+            {formatSatoshisToFiat(utxo.valueSatoshis) && (
+              <Text color={colors.textMuted}>
+                {'   '}≈ {formatSatoshisToFiat(utxo.valueSatoshis)}
+              </Text>
+            )}
+          </Box>
        );
      })}

--- a/src/tui/screens/invitations/invitation-import/steps/PreviewInvitationStep.tsx
+++ b/src/tui/screens/invitations/invitation-import/steps/PreviewInvitationStep.tsx
@@ -9,6 +9,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../../theme.js';
+import { useSatoshisConversion } from '../../../../hooks/useSatoshisConversion.js';
 import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import {
  getInvitationState,
@@ -41,6 +42,8 @@ export function PreviewInvitationStep({
  onCancel,
  isActive,
 }: PreviewStepProps): React.ReactElement {
+  const { formatSatoshisToFiat } = useSatoshisConversion('USD');
+
  useLayeredInput('import-flow', (_input, key) => {
    if (key.return) onComplete();
    if (key.escape) onCancel();
@@ -168,11 +171,15 @@ export function PreviewInvitationStep({
          ) : (
            outputs.map((output, idx) => {
              const outputTemplate = template?.outputs?.[output.outputIdentifier ?? ''];
+              const fiatValue = output.valueSatoshis !== undefined
+                ? formatSatoshisToFiat(output.valueSatoshis)
+                : null;
              return (
                <Box key={`output-${idx}`}>
                  <Text color={colors.text}>
                    {'  '}• {outputTemplate?.name ?? output.outputIdentifier ?? `Output ${idx}`}
                    {output.valueSatoshis !== undefined && ` (${formatSatoshis(output.valueSatoshis)})`}
+                    {fiatValue && ` (~${fiatValue})`}
                  </Text>
                </Box>
              );
--- a/src/tui/screens/invitations/invitation-import/steps/ReviewStep.tsx
+++ b/src/tui/screens/invitations/invitation-import/steps/ReviewStep.tsx
@@ -10,6 +10,7 @@
 import React, { useState, useCallback } from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../../theme.js';
+import { useSatoshisConversion } from '../../../../hooks/useSatoshisConversion.js';
 import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import type { ReviewStepProps, SelectableUTXO } from '../types.js';

@@ -32,6 +33,7 @@ export function ReviewStep({
 }: ReviewStepProps): React.ReactElement {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState<string | null>(null);
+  const { formatSatoshisToFiat } = useSatoshisConversion('USD');

  const fee = DEFAULT_FEE;
  const action = template?.actions?.[invitation.data.actionIdentifier];
@@ -39,6 +41,11 @@ export function ReviewStep({
  // Compute totals from selected inputs
  const totalSelected = selectedInputs.reduce((sum, u) => sum + u.valueSatoshis, 0n);

+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
  /**
   * Execute the import: add inputs (with role) and optional change output.
   */
@@ -85,14 +92,34 @@ export function ReviewStep({
      <Box marginTop={1} flexDirection="column">
        <Text color={colors.primary} bold>Funding:</Text>
        <Text color={colors.text}>  • UTXOs: {selectedInputs.length}</Text>
-        <Text color={colors.text}>  • Total: {formatSatoshis(totalSelected)}</Text>
-        <Text color={colors.text}>  • Required: {formatSatoshis(requiredAmount)}</Text>
-        <Text color={colors.text}>  • Fee: {formatSatoshis(fee)}</Text>
+        <Text color={colors.text}>  • Total: {formatSatoshis(totalSelected)}{getFiatSuffix(totalSelected)}</Text>
+        <Text color={colors.text}>  • Required: {formatSatoshis(requiredAmount)}{getFiatSuffix(requiredAmount)}</Text>
+        <Text color={colors.text}>  • Fee: {formatSatoshis(fee)}{getFiatSuffix(fee)}</Text>
        {changeAmount >= DUST_THRESHOLD && (
-          <Text color={colors.text}>  • Change: {formatSatoshis(changeAmount)}</Text>
+          <Text color={colors.text}>  • Change: {formatSatoshis(changeAmount)}{getFiatSuffix(changeAmount)}</Text>
        )}
      </Box>

+      {selectedInputs.length > 0 && (
+        <Box marginTop={1} flexDirection="column">
+          <Text color={colors.primary} bold>Selected UTXOs:</Text>
+          {selectedInputs.slice(0, 3).map((utxo) => (
+            <Text
+              key={`${utxo.outpointTransactionHash}:${utxo.outpointIndex}`}
+              color={colors.textMuted}
+            >
+              {'  '}• {formatSatoshis(utxo.valueSatoshis)}
+              {getFiatSuffix(utxo.valueSatoshis)}
+            </Text>
+          ))}
+          {selectedInputs.length > 3 && (
+            <Text color={colors.textMuted}>
+              {'  '}...and {selectedInputs.length - 3} more
+            </Text>
+          )}
+        </Box>
+      )}
+
      {/* Error display */}
      {error && (
        <Box marginTop={1}>
--- a/src/tui/screens/invitations/invitation-import/types.ts
+++ b/src/tui/screens/invitations/invitation-import/types.ts
@@ -116,8 +116,12 @@ export interface ImportFlowProps {
  mode: ImportFlowMode;
  /** The application service — injected, not pulled from context. */
  appService: AppService;
-  /** Called when the flow completes or is cancelled. */
-  onClose: () => void;
+  /**
+   * Called when the flow completes or is cancelled.
+   * When import succeeds, the invitation identifier is provided so callers can
+   * select/focus the imported invitation in their UI.
+   */
+  onClose: (importedInvitationId?: string) => void;
  /** Display an error message to the user. */
  showError: (message: string) => void;
  /** Display an info message to the user. */
--- a/src/tui/utils/clipboard.ts
+++ b/src/tui/utils/clipboard.ts
@@ -8,6 +8,36 @@ import { promisify } from "util";

 const execAsync = promisify(exec);

+// Define a list of clipboard methods with their platform and command.
+// The platform is a function that returns true if the method is available on the current platform.
+// The command is a function that returns a promise that resolves to the result of the command.
+const clipboardMethods = {
+  pbCopy: {
+    platform: (platform: string) => platform === 'darwin',
+    command: async (text: string) => execAsync(`printf '%s' '${text}' | pbcopy`),
+  },
+  xclip: {
+    platform: (platform: string) => platform === 'linux',
+    command: async (text: string) => execAsync(`printf '%s' '${text}' | xclip -selection clipboard`),
+  },
+  xsel: {
+    platform: (platform: string) => platform === 'linux',
+    command: async (text: string) => execAsync(`printf '%s' '${text}' | xsel --clipboard --input`),
+  },
+  ssh: {
+    platform: (platform: string) => platform === 'linux',
+    command: async (text: string) => process.stdout.write(`\x1b]52;c;${Buffer.from(text, 'utf-8').toString('base64')}\x07`),
+  },
+  clip: {
+    platform: (platform: string) => platform === 'windows',
+    command: async (text: string) => execAsync(`echo|set /p="${text}" | clip`),
+  },
+  clipboardy: {
+    platform: (platform: string) => platform === 'windows',
+    command: async (text: string) => clipboardy.writeSync(text),
+  },
+}
+
 /**
 * Attempts to copy text to clipboard using multiple methods.
 * Tries native commands first (most reliable), then clipboardy as fallback.
@@ -21,46 +51,25 @@ export async function copyToClipboard(text: string): Promise<void> {
  // Escape the text for shell commands
  const escapedText = text.replace(/'/g, "'\\''");

-  // Try native commands first - they're more reliable
-  try {
-    if (platform === "darwin") {
-      // macOS - use pbcopy directly
-      await execAsync(`printf '%s' '${escapedText}' | pbcopy`);
-      return;
-    } else if (platform === "linux") {
-      // Linux - try xclip, then xsel
-      try {
-        await execAsync(
-          `printf '%s' '${escapedText}' | xclip -selection clipboard`,
-        );
-        return;
-      } catch {
-        try {
-          await execAsync(
-            `printf '%s' '${escapedText}' | xsel --clipboard --input`,
-          );
-          return;
-        } catch {
-          // Fall through to clipboardy
-        }
-      }
-    } else if (platform === "win32") {
-      // Windows - use clip.exe
-      await execAsync(`echo|set /p="${text}" | clip`);
-      return;
-    }
-  } catch {
-    // Native command failed, try clipboardy
-  }
+  const availableMethods = Object.values(clipboardMethods).filter(method => method.platform(platform));

-  // Fallback to clipboardy
-  try {
-    clipboardy.writeSync(text);
-    return;
-  } catch {
-    // clipboardy also failed
+  const errors: Error[] = [];
+
+  for (const method of availableMethods) {
+    try {
+      if (method.platform(platform)) {
+        await method.command(escapedText);
+      } else {
+        continue;
+      }
+      return;
+    } catch(error) {
+      if (error instanceof Error) {
+        errors.push(error);
+      }
+    }
  }

  // All methods failed
-  throw new Error(`Clipboard not available. Install xclip or xsel on Linux.`);
+  throw new Error(`Clipboard not available. ${errors.map(error => error.message).join('\n')}`);
 }
--- a/src/utils/invitation-flow.ts
+++ b/src/utils/invitation-flow.ts
@@ -45,7 +45,8 @@ export const resolveActionRoles = (
  const starts = template.start ?? [];
  const roleIds = starts
    .filter((entry) => entry.action === actionIdentifier)
-    .map((entry) => entry.role);
+    .map((entry) => entry.role)
+    .filter((roleId) => roleId !== undefined);

  return [...new Set(roleIds)];
 };
@@ -60,17 +61,11 @@ export const roleRequiresInputs = (
  if (!action) return false;

  const actionRole = action.roles?.[roleIdentifier];
-  const roleSlotsMin = actionRole?.requirements?.slots?.min ?? 0;
+  const actionRequirements = action.requirements;
+  const actionRoleRequirements = actionRole && actionRequirements && actionRequirements.participants?.find((participant) => participant.role === roleIdentifier);
+  const roleSlotsMin = actionRoleRequirements && actionRoleRequirements.slots && actionRoleRequirements.slots.min > 0 ? actionRoleRequirements.slots.min : 0;
  if (roleSlotsMin > 0) return true;

-  // Some templates specify slot/input requirements at action.requirements.roles
-  // instead of role.requirements. Respect those as well.
-  const roleRequirement = action.requirements?.roles?.find(
-    (requirement) => requirement.role === roleIdentifier,
-  );
-  const actionLevelSlotsMin = roleRequirement?.slots?.min ?? 0;
-  if (actionLevelSlotsMin > 0) return true;
-
  const transactionIdentifier = action.transaction;
  const transaction = transactionIdentifier
    ? template.transactions?.[transactionIdentifier]
@@ -132,13 +127,12 @@ export const resolveProvidedLockingBytecodeHex = (
  variableValues: Record<string, string>,
 ): string | undefined => {
  const outputDefinition = template.outputs?.[outputIdentifier];
-  if (!outputDefinition || typeof outputDefinition.lockscript !== "string")
+  if (!outputDefinition || typeof outputDefinition.lockingScript !== "string") {
    return undefined;
+  }

-  const lockingScriptDefinition = (
-    template.lockingScripts as Record<string, unknown> | undefined
-  )?.[outputDefinition.lockscript] as { lockingScript?: string } | undefined;
-  const scriptIdentifier = lockingScriptDefinition?.lockingScript;
+  const lockingScriptDefinition = template.lockingScripts?.[outputDefinition.lockingScript];
+  const scriptIdentifier = lockingScriptDefinition?.lockingBytecode;
  if (!scriptIdentifier) return undefined;

  const scriptExpression = (
--- a/src/utils/rates/base-rates.ts
+++ b/src/utils/rates/base-rates.ts
@@ -0,0 +1,56 @@
+import { EventEmitter } from '../event-emitter.js';
+
+/**
+ * Events emitted by our Rates Adapters
+ */
+export type RatesEventMap = {
+  rateUpdated: {
+    numeratorUnitCode: string;
+    denominatorUnitCode: string;
+    price: number;
+  };
+};
+
+export abstract class BaseRates<
+  T extends RatesEventMap = RatesEventMap,
+> extends EventEmitter<T> {
+  /** Starts the given rates adapter so that it will emit events on price updates. */
+  public abstract start(): Promise<void>;
+
+  /** Stops the given rates adapter so that it will stop checking for price updates. */
+  public abstract stop(): Promise<void>;
+
+  /**
+   * List all available market products (pairs).
+   * @returns A set of strings in the format "NUMERATOR/DENOMINATOR"
+   */
+  public abstract listPairs(): Promise<Set<string>>;
+
+  // TODO: Consider whether we actually want the below.
+  //       Ideally, we will want to replace this with something like the Units class:
+  //       See: https://gitlab.com/GeneralProtocols/xo/stack/-/issues/44
+  /**
+   * Format the amount in the target currency to the correct number of decimal places.
+   *
+   * @param {number} amount - The amount to format.
+   * @param {string} targetCurrency - The target currency.
+   *
+   * @returns The formatted amount.
+   */
+  public formatCurrency(amount: number, targetCurrency: string): string {
+    const minimumFractionDigitsMap: { [currency: string]: number } = {
+      AUD: 2,
+      BCH: 8,
+      USD: 2,
+    };
+
+    const formatter = new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: targetCurrency,
+      currencyDisplay: 'narrowSymbol',
+      minimumFractionDigits: minimumFractionDigitsMap[targetCurrency] || 0,
+    });
+
+    return formatter.format(amount);
+  }
+}
--- a/src/utils/rates/rates-oracles.ts
+++ b/src/utils/rates/rates-oracles.ts
@@ -0,0 +1,170 @@
+import {
+  OracleClient,
+  OracleMetadataMessage,
+  OraclePriceMessage,
+  type OracleMetadataMap,
+} from '@generalprotocols/oracle-client';
+
+import { type RatesEventMap, BaseRates } from './base-rates.js';
+
+// Add the Oracle Price Message to our Events for this Adapter.
+export type RatesOracleEventMap = RatesEventMap & {
+  rateUpdated: {
+    oraclePriceMessage: OraclePriceMessage;
+  };
+};
+
+// TODO: Add RatesHistorical trait since Oracles can provide historical rates.
+export class RatesOracle extends BaseRates<RatesOracleEventMap> {
+  /**
+   * Create a new rates oracle.
+   *
+   * @param client The underlying oracle client. If not provided, a new client will be created.
+   * @returns The rates oracle.
+   */
+  static async from(client?: OracleClient) {
+    const ratesOracle = new RatesOracle(client ?? (await OracleClient.from()));
+
+    return ratesOracle;
+  }
+
+  private client: OracleClient;
+  private oracles: OracleMetadataMap;
+
+  private started: boolean = false;
+
+  private constructor(client: OracleClient) {
+    super();
+
+    this.client = client;
+    this.oracles = {};
+  }
+
+  /**
+   * Start the rates oracle and the underlying client.
+   */
+  async start() {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+
+    // Create event listeners for the client.
+    this.client.setOnMetadataMessage(this.handleMetadataMessage.bind(this));
+    this.client.setOnPriceMessage(this.handlePriceMessage.bind(this));
+
+    // Get the metadata for the client.
+    this.oracles = await this.client.getMetadataMap();
+
+    // Start the client.
+    await this.client.start();
+
+    // Refresh the prices.
+    await this.refreshPrices();
+  }
+
+  /**
+   * Stop the rates oracle and the underlying client.
+   */
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+
+    // Remove event listeners by setting them to empty functions.
+    this.client.setOnMetadataMessage(() => {});
+    this.client.setOnPriceMessage(() => {});
+
+    await this.client.stop();
+  }
+
+  /**
+   * List the pairs that we are tracking.
+   *
+   * @returns A set of pairs.
+   */
+  async listPairs() {
+    return new Set(
+      Object.values(this.oracles).map((oracle) => {
+        return `${oracle.SOURCE_NUMERATOR_UNIT_CODE}/${oracle.SOURCE_DENOMINATOR_UNIT_CODE}`;
+      }),
+    );
+  }
+
+  /**
+   * Get the latest prices for all the pairs and emit a rate updated event for each.
+   */
+  public async refreshPrices() {
+    const oracles = await this.client.getOracles();
+
+    // For each oracle, get the lastest dataSequence (price) message and emit a rate updated event.
+    await Promise.allSettled(
+      oracles.map(async (oracle) => {
+        try {
+          const messages = await this.client.getOracleMessages({
+            publicKey: oracle.publicKey,
+            minDataSequence: 1,
+            count: 1,
+          });
+
+          // We are only expecting a single message back. Just in case, we take the latest one.
+          const message = messages.reduce((latest, msg) => {
+            if (
+              msg instanceof OraclePriceMessage &&
+              msg.messageSequence > (latest?.messageSequence ?? 0)
+            ) {
+              return msg;
+            }
+            return latest;
+          }, messages[0]);
+
+          // If the message is a price message, handle it.
+          if (message instanceof OraclePriceMessage) {
+            this.handlePriceMessage(message);
+          }
+        } catch (error) {
+          console.error('Error refreshing prices for oracle:', oracle.publicKey, error);
+        }
+      }),
+    );
+  }
+
+  /**
+   * Update the metadata map that we use to track the pairs.
+   *
+   * @param message The metadata message.
+   */
+  private handleMetadataMessage(message: OracleMetadataMessage) {
+    this.oracles = OracleClient.updateMetadataMap(this.oracles, message);
+  }
+
+  /**
+   * Emit a rate updated event for the given pair.
+   *
+   * @param message The price message.
+   */
+  private handlePriceMessage(message: OraclePriceMessage) {
+    const oracle = this.oracles[message.toHexObject().publicKey];
+
+    // If the oracle doesn't have the required metadata, we can't use it.
+    if (
+      !oracle ||
+      !oracle.SOURCE_NUMERATOR_UNIT_CODE ||
+      !oracle.SOURCE_DENOMINATOR_UNIT_CODE ||
+      !oracle.ATTESTATION_SCALING
+    ) {
+      return;
+    }
+
+    // Scale the price
+    const priceValue = message.priceValue / oracle.ATTESTATION_SCALING;
+
+    this.emit('rateUpdated', {
+      numeratorUnitCode: oracle.SOURCE_NUMERATOR_UNIT_CODE,
+      denominatorUnitCode: oracle.SOURCE_DENOMINATOR_UNIT_CODE,
+      price: priceValue,
+      oraclePriceMessage: message,
+    });
+  }
+}
--- a/src/utils/template-utils.ts
+++ b/src/utils/template-utils.ts
@@ -188,11 +188,13 @@ export function getRolesForAction(
  );

  return startEntries.map((entry) => {
-    const roleDef = template.roles?.[entry.role];
+    const roleDef = template.roles?.[entry.role || ''];
    const roleObj = typeof roleDef === "object" ? roleDef : null;
+
+    // TODO: This is ugly. Lot of conditionals. Need to take a much closer look at this.
    return {
-      roleId: entry.role,
-      name: roleObj?.name || entry.role,
+      roleId: entry.role || '',
+      name: roleObj?.name || entry.role || '',
      description: roleObj?.description,
    };
  });
--- a/tests/cli/arguments.test.ts
+++ b/tests/cli/arguments.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest"
+import { describe, it, expect } from "vitest";

 import { convertArgsToObject } from "../../src/cli/arguments";

@@ -11,45 +11,59 @@ const testCases = [
    },
  },
  {
-    input: ['-var-requested-satohis', '1000', '-role', 'receiver'],
+    input: ["-var-requested-satohis", "1000", "-role", "receiver"],
    expected: {
      args: [],
-      options: { "varRequestedSatohis": "1000", role: "receiver" },
+      options: { varRequestedSatohis: "1000", role: "receiver" },
    },
  },
  {
-    input: ['-o', 'output.json', '-var-requested-satohis', '1000', '-role', 'receiver'],
+    input: [
+      "-o",
+      "output.json",
+      "-var-requested-satohis",
+      "1000",
+      "-role",
+      "receiver",
+    ],
    expected: {
      args: [],
-      options: { output: "output.json", "varRequestedSatohis": "1000", role: "receiver" },
+      options: {
+        output: "output.json",
+        varRequestedSatohis: "1000",
+        role: "receiver",
+      },
    },
  },
  {
-    input: ['mnemonic', 'create', 'page', 'pencil', '-v', '-o', 'mnemonic.txt'],
+    input: ["mnemonic", "create", "page", "pencil", "-v", "-o", "mnemonic.txt"],
    expected: {
-      args: ['mnemonic', 'create', 'page', 'pencil'],
+      args: ["mnemonic", "create", "page", "pencil"],
      options: { verbose: "true", output: "mnemonic.txt" },
    },
  },
  {
-    input: ['-v', 'invitation', 'list', '-m', 'mnemonicFile'],
+    input: ["-v", "invitation", "list", "-m", "mnemonicFile"],
    expected: {
-      args: ['invitation', 'list'],
+      args: ["invitation", "list"],
      options: { verbose: "true", mnemonicFile: "mnemonicFile" },
    },
  },
  {
-    input: ['--help', 'template', 'import', 'template.json'],
+    input: ["--help", "template", "import", "template.json"],
    expected: {
-      args: ['template', 'import', 'template.json'],
+      args: ["template", "import", "template.json"],
      options: { help: "true" },
    },
  },
 ];

 describe("convertArgsToObject", () => {
-  it.each(testCases)("should split positional args from options", ({ input, expected }) => {
-    const result = convertArgsToObject(input);
-    expect(result).toEqual(expected);
-  });
+  it.each(testCases)(
+    "should split positional args from options",
+    ({ input, expected }) => {
+      const result = convertArgsToObject(input);
+      expect(result).toEqual(expected);
+    },
+  );
 });
--- a/tests/cli/commands/handler-contracts.test.ts
+++ b/tests/cli/commands/handler-contracts.test.ts
@@ -73,11 +73,19 @@ describe("command handler contracts", () => {
    const { io } = createMockIO();

    await expect(
-      handleResourceCommand(createCommandDeps(fakeApp, io), ["does-not-exist"], {}),
+      handleResourceCommand(
+        createCommandDeps(fakeApp, io),
+        ["does-not-exist"],
+        {},
+      ),
    ).rejects.toThrow(CommandError);

    try {
-      await handleResourceCommand(createCommandDeps(fakeApp, io), ["does-not-exist"], {});
+      await handleResourceCommand(
+        createCommandDeps(fakeApp, io),
+        ["does-not-exist"],
+        {},
+      );
    } catch (error) {
      expect(error).toBeInstanceOf(CommandError);
      expect((error as CommandError).event).toBe("resource.subcommand.unknown");
--- a/tests/cli/commands/invitation.test.ts
+++ b/tests/cli/commands/invitation.test.ts
@@ -11,18 +11,41 @@
 */

 import { expect, test, describe, beforeEach, afterEach } from "vitest";
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

-import { addFakeResource, createMockAppService, createMockEngine, DEFAULT_SEED, randomTxHash } from "../mocks/engine";
+import {
+  addFakeResource,
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+  randomTxHash,
+} from "../mocks/engine";
 import { type Engine } from "@xo-cash/engine";
-import { p2pkhTemplate, p2pkhTemplateIdentifier } from "../mocks/template-p2pkh";
+import {
+  p2pkhTemplate,
+  p2pkhTemplateIdentifier,
+} from "../mocks/template-p2pkh";
 import { AppService } from "../../../src/services/app";

 import { handleInvitationCommand } from "../../../src/cli/commands/invitation";
 import { CommandError, CommandPaths } from "../../../src/cli/commands/types";
-import { createCommandDeps, createMockIO, createMockPaths, expectLogs, type LogExpectation } from "../mocks/command";
+import {
+  createCommandDeps,
+  createMockIO,
+  createMockPaths,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
+import { State } from "@xo-cash/state";

 // ============================================================================
 // Error Cases - Validate argument parsing and error handling
@@ -134,7 +157,8 @@ describe("invitation command - error cases", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-errors-"));
@@ -150,7 +174,11 @@ describe("invitation command - error cases", () => {
    const { io } = createMockIO();

    try {
-      await handleInvitationCommand(createCommandDeps(app, io, paths), inputs, {});
+      await handleInvitationCommand(
+        createCommandDeps(app, io, paths),
+        inputs,
+        {},
+      );
      expect.fail("Expected command to throw");
    } catch (error) {
      expect(error).toBeInstanceOf(CommandError);
@@ -170,7 +198,8 @@ describe("invitation command - receive flow", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-receive-"));
@@ -211,7 +240,10 @@ describe("invitation command - receive flow", () => {
      {},
    );

-    const expectedFile = path.join(tempDir, `inv-${result.invitationIdentifier}.json`);
+    const expectedFile = path.join(
+      tempDir,
+      `inv-${result.invitationIdentifier}.json`,
+    );
    expect(existsSync(expectedFile)).toBe(true);
  });

@@ -279,7 +311,8 @@ describe("invitation command - request satoshis flow", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-request-"));
@@ -325,8 +358,12 @@ describe("invitation command - request satoshis flow", () => {
    );
    expect(invitation).toBeDefined();

-    const variables = invitation?.data.commits.flatMap((c) => c.data.variables ?? []);
-    const requestedSatoshis = variables?.find((v) => v.variableIdentifier === "requestedSatoshis");
+    const variables = invitation?.data.commits.flatMap(
+      (c) => c.data.variables ?? [],
+    );
+    const requestedSatoshis = variables?.find(
+      (v) => v.variableIdentifier === "requestedSatoshis",
+    );
    expect(requestedSatoshis).toBeDefined();
    expect(requestedSatoshis?.value).toBe("10000");
  });
@@ -347,8 +384,12 @@ describe("invitation command - request satoshis flow", () => {
      (inv) => inv.data.invitationIdentifier === result.invitationIdentifier,
    );

-    const variables = invitation?.data.commits.flatMap((c) => c.data.variables ?? []);
-    const requestedSatoshis = variables?.find((v) => v.variableIdentifier === "requestedSatoshis");
+    const variables = invitation?.data.commits.flatMap(
+      (c) => c.data.variables ?? [],
+    );
+    const requestedSatoshis = variables?.find(
+      (v) => v.variableIdentifier === "requestedSatoshis",
+    );
    expect(requestedSatoshis?.roleIdentifier).toBe("receiver");
  });
 });
@@ -359,12 +400,15 @@ describe("invitation command - request satoshis flow", () => {

 describe("invitation command - send flow with resources", () => {
  let engine: Engine;
+  let state: State;
  let app: AppService;
  let tempDir: string;
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
+    state = mockEngine.state;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-send-"));
@@ -388,7 +432,8 @@ describe("invitation command - send flow with resources", () => {
      ["create", "Wallet (P2PKH)", "sendSatoshis"],
      {
        varTransferredSatoshis: "10000",
-        varRecipientLockingscript: "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
+        varRecipientLockingscript:
+          "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
        role: "sender",
      },
    );
@@ -408,7 +453,8 @@ describe("invitation command - send flow with resources", () => {
      ["create", "Wallet (P2PKH)", "sendSatoshis"],
      {
        varTransferredSatoshis: "10000",
-        varRecipientLockingscript: "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
+        varRecipientLockingscript:
+          "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
        role: "sender",
      },
    );
@@ -418,8 +464,12 @@ describe("invitation command - send flow with resources", () => {
    );
    expect(invitation).toBeDefined();

-    const variables = invitation?.data.commits.flatMap((c) => c.data.variables ?? []);
-    const transferredSatoshis = variables?.find((v) => v.variableIdentifier === "transferredSatoshis");
+    const variables = invitation?.data.commits.flatMap(
+      (c) => c.data.variables ?? [],
+    );
+    const transferredSatoshis = variables?.find(
+      (v) => v.variableIdentifier === "transferredSatoshis",
+    );
    expect(transferredSatoshis).toBeDefined();
    expect(transferredSatoshis?.value).toBe("10000");
  });
@@ -436,8 +486,10 @@ describe("invitation command - send flow with resources", () => {
        ["create", "Wallet (P2PKH)", "sendSatoshis"],
        {
          varTransferredSatoshis: "10000",
-          varRecipientLockingscript: "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
-          addInput: "0000000000000000000000000000000000000000000000000000000000000000:0",
+          varRecipientLockingscript:
+            "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
+          addInput:
+            "0000000000000000000000000000000000000000000000000000000000000000:0",
          role: "sender",
        },
      );
@@ -452,7 +504,7 @@ describe("invitation command - send flow with resources", () => {
   * This validates our test infrastructure works correctly.
   */
  test("fake resources are accessible via engine", async () => {
-    const resource = await addFakeResource(engine, {
+    const resource = await addFakeResource(state!, {
      valueSatoshis: 50000,
      templateIdentifier: p2pkhTemplateIdentifier,
      outputIdentifier: "receiveOutput",
@@ -481,7 +533,8 @@ describe("invitation command - multi-step append", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-append-"));
@@ -516,10 +569,15 @@ describe("invitation command - multi-step append", () => {
    expectLogs(spies, [{ out: "Invitation appended" }]);

    const invitation = app.invitations.find(
-      (inv) => inv.data.invitationIdentifier === createResult.invitationIdentifier,
+      (inv) =>
+        inv.data.invitationIdentifier === createResult.invitationIdentifier,
+    );
+    const variables = invitation?.data.commits.flatMap(
+      (c) => c.data.variables ?? [],
+    );
+    const requestedSatoshis = variables?.find(
+      (v) => v.variableIdentifier === "requestedSatoshis",
    );
-    const variables = invitation?.data.commits.flatMap((c) => c.data.variables ?? []);
-    const requestedSatoshis = variables?.find((v) => v.variableIdentifier === "requestedSatoshis");
    expect(requestedSatoshis?.value).toBe("25000");
  });

@@ -569,7 +627,10 @@ describe("invitation command - multi-step append", () => {

    expectLogs(spies, [{ out: "Invitation updated" }]);

-    const expectedFile = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const expectedFile = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );
    expect(existsSync(expectedFile)).toBe(true);
  });

@@ -594,12 +655,17 @@ describe("invitation command - multi-step append", () => {
    );

    const invitation = app.invitations.find(
-      (inv) => inv.data.invitationIdentifier === createResult.invitationIdentifier,
+      (inv) =>
+        inv.data.invitationIdentifier === createResult.invitationIdentifier,
    );
    expect(invitation?.data.commits.length).toBeGreaterThan(1);

-    const variables = invitation?.data.commits.flatMap((c) => c.data.variables ?? []);
-    const requestedSatoshis = variables?.find((v) => v.variableIdentifier === "requestedSatoshis");
+    const variables = invitation?.data.commits.flatMap(
+      (c) => c.data.variables ?? [],
+    );
+    const requestedSatoshis = variables?.find(
+      (v) => v.variableIdentifier === "requestedSatoshis",
+    );
    expect(requestedSatoshis?.value).toBe("10000");
  });
 });
@@ -615,7 +681,8 @@ describe("invitation command - list and inspect", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-list-"));
@@ -724,7 +791,10 @@ describe("invitation command - list and inspect", () => {
      {},
    );

-    const invitationFilePath = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const invitationFilePath = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );

    const { io: inspectIO } = createMockIO();

@@ -780,7 +850,8 @@ describe("invitation command - sign flow", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-sign-"));
@@ -813,7 +884,9 @@ describe("invitation command - sign flow", () => {
      {},
    );

-    expect(signResult.invitationIdentifier).toBe(createResult.invitationIdentifier);
+    expect(signResult.invitationIdentifier).toBe(
+      createResult.invitationIdentifier,
+    );
    expectLogs(spies, [{ out: "Invitation signed" }]);
  });

@@ -840,7 +913,8 @@ describe("invitation command - sign flow", () => {
    );

    const invitation = app.invitations.find(
-      (inv) => inv.data.invitationIdentifier === createResult.invitationIdentifier,
+      (inv) =>
+        inv.data.invitationIdentifier === createResult.invitationIdentifier,
    );

    expect(invitation).toBeDefined();
@@ -897,7 +971,8 @@ describe("invitation command - import flow", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-import-"));
@@ -921,7 +996,10 @@ describe("invitation command - import flow", () => {
      {},
    );

-    const invitationFilePath = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const invitationFilePath = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );

    const secondApp = await createMockAppService(engine);
    const { io: importIO } = createMockIO();
@@ -965,7 +1043,10 @@ describe("invitation command - import flow", () => {
      {},
    );

-    const invitationFilePath = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const invitationFilePath = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );

    const secondApp = await createMockAppService(engine);
    const { io: importIO } = createMockIO();
@@ -991,7 +1072,10 @@ describe("invitation command - import flow", () => {
      {},
    );

-    const invitationFilePath = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const invitationFilePath = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );

    const secondApp = await createMockAppService(engine);
    const { io: importIO } = createMockIO();
@@ -1019,7 +1103,8 @@ describe("invitation command - auto-inputs flow", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-autoinputs-"));
@@ -1044,7 +1129,8 @@ describe("invitation command - auto-inputs flow", () => {
        ["create", "Wallet (P2PKH)", "sendSatoshis"],
        {
          varTransferredSatoshis: "10000",
-          varRecipientLockingscript: "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
+          varRecipientLockingscript:
+            "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
          role: "sender",
          autoInputs: "true",
        },
@@ -1052,7 +1138,9 @@ describe("invitation command - auto-inputs flow", () => {
      expect.fail("Expected command to throw");
    } catch (error) {
      expect(error).toBeInstanceOf(CommandError);
-      expect((error as CommandError).event).toBe("invitation.create.append_params_failed");
+      expect((error as CommandError).event).toBe(
+        "invitation.create.append_params_failed",
+      );
    }
  });

@@ -1068,7 +1156,8 @@ describe("invitation command - auto-inputs flow", () => {
        ["create", "Wallet (P2PKH)", "sendSatoshis"],
        {
          varTransferredSatoshis: "10000",
-          varRecipientLockingscript: "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
+          varRecipientLockingscript:
+            "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac",
          role: "sender",
          autoInputs: "true",
        },
@@ -1090,7 +1179,8 @@ describe("invitation command - broadcast flow", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-broadcast-"));
@@ -1117,7 +1207,9 @@ describe("invitation command - broadcast flow", () => {
      expect.fail("Expected command to throw");
    } catch (error) {
      expect(error).toBeInstanceOf(CommandError);
-      expect((error as CommandError).event).toBe("invitation.broadcast.not_found");
+      expect((error as CommandError).event).toBe(
+        "invitation.broadcast.not_found",
+      );
    }
  });

@@ -1152,7 +1244,8 @@ describe("invitation command - full lifecycle", () => {
  let paths: CommandPaths;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-invitation-lifecycle-"));
@@ -1188,11 +1281,14 @@ describe("invitation command - full lifecycle", () => {
      {},
    );

-    expect(signResult.invitationIdentifier).toBe(createResult.invitationIdentifier);
+    expect(signResult.invitationIdentifier).toBe(
+      createResult.invitationIdentifier,
+    );
    expectLogs(signSpies, [{ out: "Invitation signed" }]);

    const invitation = app.invitations.find(
-      (inv) => inv.data.invitationIdentifier === createResult.invitationIdentifier,
+      (inv) =>
+        inv.data.invitationIdentifier === createResult.invitationIdentifier,
    );
    expect(invitation).toBeDefined();
    expect(invitation?.data.commits.length).toBeGreaterThan(0);
@@ -1210,7 +1306,10 @@ describe("invitation command - full lifecycle", () => {
      {},
    );

-    const invitationFilePath = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const invitationFilePath = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );
    expect(existsSync(invitationFilePath)).toBe(true);

    const { io: inspectIO } = createMockIO();
@@ -1254,7 +1353,9 @@ describe("invitation command - full lifecycle", () => {
      {},
    );

-    expect(signResult.invitationIdentifier).toBe(createResult.invitationIdentifier);
+    expect(signResult.invitationIdentifier).toBe(
+      createResult.invitationIdentifier,
+    );
    expectLogs(signSpies, [{ out: "Invitation signed" }]);
  });

@@ -1270,7 +1371,10 @@ describe("invitation command - full lifecycle", () => {
      {},
    );

-    const invitationFilePath = path.join(tempDir, `inv-${createResult.invitationIdentifier}.json`);
+    const invitationFilePath = path.join(
+      tempDir,
+      `inv-${createResult.invitationIdentifier}.json`,
+    );

    const afterCreate = JSON.parse(readFileSync(invitationFilePath, "utf-8"));
    const createCommitCount = afterCreate.commits?.length ?? 0;
@@ -1335,7 +1439,9 @@ describe("invitation command - full lifecycle", () => {
      {},
    );

-    expect(reqResult.invitationIdentifier).toBe(createResult.invitationIdentifier);
+    expect(reqResult.invitationIdentifier).toBe(
+      createResult.invitationIdentifier,
+    );
    expect(spies.out).toHaveBeenCalled();
  });
 });
--- a/tests/cli/commands/mnemonic.test.ts
+++ b/tests/cli/commands/mnemonic.test.ts
@@ -7,7 +7,12 @@ import { DEFAULT_SEED } from "../mocks/engine";

 import { handleMnemonicCommand } from "../../../src/cli/commands/mnemonic";
 import { CommandError } from "../../../src/cli/commands/types";
-import { createMockIO, createMockPaths, expectLogs, type LogExpectation } from "../mocks/command";
+import {
+  createMockIO,
+  createMockPaths,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
 import { BCHMnemonicURL } from "../../../src/utils/bch-mnemonic-url";

 type TestCase = {
@@ -116,31 +121,45 @@ describe("mnemonic commands", () => {
    rmSync(tempDir, { recursive: true, force: true });
  });

-  test.each(testCases)("mnemonic command: $inputs", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
-    const { io, spies } = createMockIO();
-    const paths = createMockPaths(tempDir);
+  test.each(testCases)(
+    "mnemonic command: $inputs",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();
+      const paths = createMockPaths(tempDir);

-    if (shouldThrow) {
-      try {
-        await handleMnemonicCommand({ io, paths }, inputs, options ?? {});
-        expect.fail("Expected command to throw");
-      } catch (error) {
-        if (expectedEvent) {
-          expect(error).toBeInstanceOf(CommandError);
-          expect((error as CommandError).event).toBe(expectedEvent);
+      if (shouldThrow) {
+        try {
+          await handleMnemonicCommand({ io, paths }, inputs, options ?? {});
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleMnemonicCommand(
+          { io, paths },
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
        }
      }
-    } else {
-      const result = await handleMnemonicCommand({ io, paths }, inputs, options ?? {});
-      if (expectedData) {
-        Object.entries(expectedData).forEach(([key, value]) => {
-          expect(result[key as keyof typeof result]).toEqual(value);
-        });
-      }
-    }

-    if (logs) {
-      expectLogs(spies, logs);
-    }
-  });
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
 });
--- a/tests/cli/commands/receive.test.ts
+++ b/tests/cli/commands/receive.test.ts
@@ -3,14 +3,23 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

-import { createMockAppService, createMockEngine, DEFAULT_SEED } from "../mocks/engine";
+import {
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+} from "../mocks/engine";
 import { type Engine } from "@xo-cash/engine";
 import { p2pkhTemplate } from "../mocks/template-p2pkh";
 import { AppService } from "../../../src/services/app";

 import { handleReceiveCommand } from "../../../src/cli/commands/receive";
 import { CommandError } from "../../../src/cli/commands/types";
-import { createCommandDeps, createMockIO, expectLogs, type LogExpectation } from "../mocks/command";
+import {
+  createCommandDeps,
+  createMockIO,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";

 type TestCase = {
  name: string;
@@ -72,7 +81,8 @@ describe("receive command", () => {
  let tempDir: string;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);

    app = await createMockAppService(engine);
@@ -85,30 +95,48 @@ describe("receive command", () => {
    rmSync(tempDir, { recursive: true, force: true });
  });

-  test.each(testCases)("$name", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
-    const { io, spies } = createMockIO();
+  test.each(testCases)(
+    "$name",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();

-    if (shouldThrow) {
-      try {
-        await handleReceiveCommand(createCommandDeps(app, io), inputs, options ?? {});
-        expect.fail("Expected command to throw");
-      } catch (error) {
-        if (expectedEvent) {
-          expect(error).toBeInstanceOf(CommandError);
-          expect((error as CommandError).event).toBe(expectedEvent);
+      if (shouldThrow) {
+        try {
+          await handleReceiveCommand(
+            createCommandDeps(app, io),
+            inputs,
+            options ?? {},
+          );
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleReceiveCommand(
+          createCommandDeps(app, io),
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
        }
      }
-    } else {
-      const result = await handleReceiveCommand(createCommandDeps(app, io), inputs, options ?? {});
-      if (expectedData) {
-        Object.entries(expectedData).forEach(([key, value]) => {
-          expect(result[key as keyof typeof result]).toEqual(value);
-        });
-      }
-    }

-    if (logs) {
-      expectLogs(spies, logs);
-    }
-  });
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
 });
--- a/tests/cli/commands/resource.test.ts
+++ b/tests/cli/commands/resource.test.ts
@@ -3,14 +3,26 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

-import { addFakeResource, createMockAppService, createMockEngine, DEFAULT_SEED, reserveResource } from "../mocks/engine";
+import {
+  addFakeResource,
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+  reserveResource,
+} from "../mocks/engine";
 import { type Engine } from "@xo-cash/engine";
 import { p2pkhTemplate } from "../mocks/template-p2pkh";
 import { AppService } from "../../../src/services/app";

 import { handleResourceCommand } from "../../../src/cli/commands/resource";
 import { CommandError } from "../../../src/cli/commands/types";
-import { createCommandDeps, createMockIO, expectLogs, type LogExpectation } from "../mocks/command";
+import {
+  createCommandDeps,
+  createMockIO,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
+import { State } from "@xo-cash/state";

 type TestCase = {
  name: string;
@@ -94,7 +106,10 @@ const testCases: TestCase[] = [
  },
  {
    name: "throws when unreserve called with non-existent UTXO",
-    inputs: ["unreserve", "0000000000000000000000000000000000000000000000000000000000000000:0"],
+    inputs: [
+      "unreserve",
+      "0000000000000000000000000000000000000000000000000000000000000000:0",
+    ],
    shouldThrow: true,
    expectedEvent: "resource.unreserve.utxo_missing",
  },
@@ -106,7 +121,8 @@ describe("resource command", () => {
  let tempDir: string;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);

    app = await createMockAppService(engine);
@@ -119,41 +135,62 @@ describe("resource command", () => {
    rmSync(tempDir, { recursive: true, force: true });
  });

-  test.each(testCases)("$name", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
-    const { io, spies } = createMockIO();
+  test.each(testCases)(
+    "$name",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();

-    if (shouldThrow) {
-      try {
-        await handleResourceCommand(createCommandDeps(app, io), inputs, options ?? {});
-        expect.fail("Expected command to throw");
-      } catch (error) {
-        if (expectedEvent) {
-          expect(error).toBeInstanceOf(CommandError);
-          expect((error as CommandError).event).toBe(expectedEvent);
+      if (shouldThrow) {
+        try {
+          await handleResourceCommand(
+            createCommandDeps(app, io),
+            inputs,
+            options ?? {},
+          );
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleResourceCommand(
+          createCommandDeps(app, io),
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
        }
      }
-    } else {
-      const result = await handleResourceCommand(createCommandDeps(app, io), inputs, options ?? {});
-      if (expectedData) {
-        Object.entries(expectedData).forEach(([key, value]) => {
-          expect(result[key as keyof typeof result]).toEqual(value);
-        });
-      }
-    }

-    if (logs) {
-      expectLogs(spies, logs);
-    }
-  });
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
 });

 describe("resource command with populated data", () => {
  let engine: Engine;
+  let state: State;
  let app: AppService;
  let tempDir: string;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
+    state = mockEngine.state;
    await engine.importTemplate(p2pkhTemplate);
    app = await createMockAppService(engine);
    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-resource-tests-"));
@@ -165,19 +202,23 @@ describe("resource command with populated data", () => {
  });

  test("list returns count when resources exist", async () => {
-    await addFakeResource(engine, { valueSatoshis: 50000 });
-    await addFakeResource(engine, { valueSatoshis: 25000 });
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, { valueSatoshis: 25000 });

    const { io, spies } = createMockIO();
-    const result = await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list"],
+      {},
+    );

    expect(result.count).toBe(2);
    expectLogs(spies, [{ out: "Total resources: 2" }]);
  });

  test("list shows total satoshis", async () => {
-    await addFakeResource(engine, { valueSatoshis: 50000 });
-    await addFakeResource(engine, { valueSatoshis: 25000 });
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, { valueSatoshis: 25000 });

    const { io, spies } = createMockIO();
    await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
@@ -186,63 +227,99 @@ describe("resource command with populated data", () => {
  });

  test("list excludes reserved resources by default", async () => {
-    await addFakeResource(engine, { valueSatoshis: 50000 });
-    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });

    const { io } = createMockIO();
-    const result = await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list"],
+      {},
+    );

    expect(result.count).toBe(1);
  });

  test("list reserved shows only reserved resources", async () => {
-    await addFakeResource(engine, { valueSatoshis: 50000 });
-    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
-    await addFakeResource(engine, { valueSatoshis: 10000, reservedBy: "inv-456" });
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+    await addFakeResource(state, {
+      valueSatoshis: 10000,
+      reservedBy: "inv-456",
+    });

    const { io, spies } = createMockIO();
-    const result = await handleResourceCommand(createCommandDeps(app, io), ["list", "reserved"], {});
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list", "reserved"],
+      {},
+    );

    expect(result.count).toBe(2);
    expectLogs(spies, [{ out: "reserved for inv-123" }]);
  });

  test("list all shows both reserved and unreserved", async () => {
-    await addFakeResource(engine, { valueSatoshis: 50000 });
-    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });

    const { io } = createMockIO();
-    const result = await handleResourceCommand(createCommandDeps(app, io), ["list", "all"], {});
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list", "all"],
+      {},
+    );

    expect(result.count).toBe(2);
  });

  test("unreserve releases a reserved UTXO", async () => {
-    const resource = await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+    const resource = await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });

    const { io, spies } = createMockIO();
    await handleResourceCommand(
      createCommandDeps(app, io),
-      ["unreserve", `${resource.outpointTransactionHash}:${resource.outpointIndex}`],
+      [
+        "unreserve",
+        `${resource.outpointTransactionHash}:${resource.outpointIndex}`,
+      ],
      {},
    );

-    expectLogs(spies, [{ out: "Unreserved" }, { out: "was reserved for inv-123" }]);
+    expectLogs(spies, [
+      { out: "Unreserved" },
+      { out: "was reserved for inv-123" },
+    ]);

    const resources = await engine.listUnspentOutputsData();
    const target = resources.find(
-      r => r.outpointTransactionHash === resource.outpointTransactionHash,
+      (r) => r.outpointTransactionHash === resource.outpointTransactionHash,
    );
    expect(target?.reservedBy).toBeUndefined();
  });

  test("unreserve reports when UTXO is not reserved", async () => {
-    const resource = await addFakeResource(engine, { valueSatoshis: 25000 });
+    const resource = await addFakeResource(state, { valueSatoshis: 25000 });

    const { io, spies } = createMockIO();
    await handleResourceCommand(
      createCommandDeps(app, io),
-      ["unreserve", `${resource.outpointTransactionHash}:${resource.outpointIndex}`],
+      [
+        "unreserve",
+        `${resource.outpointTransactionHash}:${resource.outpointIndex}`,
+      ],
      {},
    );

@@ -250,23 +327,33 @@ describe("resource command with populated data", () => {
  });

  test("unreserve-all releases all reserved UTXOs", async () => {
-    await addFakeResource(engine, { valueSatoshis: 50000 });
-    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
-    await addFakeResource(engine, { valueSatoshis: 10000, reservedBy: "inv-456" });
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+    await addFakeResource(state, {
+      valueSatoshis: 10000,
+      reservedBy: "inv-456",
+    });

    const { io, spies } = createMockIO();
-    const result = await handleResourceCommand(createCommandDeps(app, io), ["unreserve-all"], {});
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["unreserve-all"],
+      {},
+    );

    expect(result.count).toBe(2);
    expectLogs(spies, [{ out: "Unreserved" }, { out: "2" }]);

    const resources = await engine.listUnspentOutputsData();
-    const reserved = resources.filter(r => r.reservedBy);
+    const reserved = resources.filter((r) => r.reservedBy);
    expect(reserved).toHaveLength(0);
  });

  test("list displays outpoint information", async () => {
-    const resource = await addFakeResource(engine, { valueSatoshis: 12345 });
+    const resource = await addFakeResource(state, { valueSatoshis: 12345 });

    const { io, spies } = createMockIO();
    await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
--- a/tests/cli/commands/template.test.ts
+++ b/tests/cli/commands/template.test.ts
@@ -3,14 +3,26 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

-import { createMockAppService, createMockEngine, DEFAULT_SEED } from "../mocks/engine";
+import {
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+} from "../mocks/engine";
 import { type Engine } from "@xo-cash/engine";
-import { p2pkhTemplate, p2pkhTemplateIdentifier } from "../mocks/template-p2pkh";
+import {
+  p2pkhTemplate,
+  p2pkhTemplateIdentifier,
+} from "../mocks/template-p2pkh";
 import { AppService } from "../../../src/services/app";

 import { handleTemplateCommand } from "../../../src/cli/commands/template";
 import { CommandError } from "../../../src/cli/commands/types";
-import { createCommandDeps, createMockIO, expectLogs, type LogExpectation } from "../mocks/command";
+import {
+  createCommandDeps,
+  createMockIO,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";

 type TestCase = {
  name: string;
@@ -171,7 +183,8 @@ describe("template command", () => {
  let tempDir: string;

  beforeEach(async () => {
-    engine = await createMockEngine(DEFAULT_SEED);
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
    await engine.importTemplate(p2pkhTemplate);

    app = await createMockAppService(engine);
@@ -184,32 +197,50 @@ describe("template command", () => {
    rmSync(tempDir, { recursive: true, force: true });
  });

-  test.each(testCases)("$name", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
-    const { io, spies } = createMockIO();
+  test.each(testCases)(
+    "$name",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();

-    if (shouldThrow) {
-      try {
-        await handleTemplateCommand(createCommandDeps(app, io), inputs, options ?? {});
-        expect.fail("Expected command to throw");
-      } catch (error) {
-        if (expectedEvent) {
-          expect(error).toBeInstanceOf(CommandError);
-          expect((error as CommandError).event).toBe(expectedEvent);
+      if (shouldThrow) {
+        try {
+          await handleTemplateCommand(
+            createCommandDeps(app, io),
+            inputs,
+            options ?? {},
+          );
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleTemplateCommand(
+          createCommandDeps(app, io),
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
        }
      }
-    } else {
-      const result = await handleTemplateCommand(createCommandDeps(app, io), inputs, options ?? {});
-      if (expectedData) {
-        Object.entries(expectedData).forEach(([key, value]) => {
-          expect(result[key as keyof typeof result]).toEqual(value);
-        });
-      }
-    }

-    if (logs) {
-      expectLogs(spies, logs);
-    }
-  });
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );

  test("import imports template from file", async () => {
    const templatePath = path.join(tempDir, "test-template.json");
--- a/tests/cli/mnemonic.test.ts
+++ b/tests/cli/mnemonic.test.ts
@@ -1,5 +1,11 @@
 import { expect, test, describe, beforeEach, afterEach } from "vitest";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

@@ -12,7 +18,8 @@ import {
 } from "../../src/cli/mnemonic";
 import { BCHMnemonicURL } from "../../src/utils/bch-mnemonic-url";

-const TEST_SEED = "page pencil stock planet limb cluster assault speak off joke private pioneer";
+const TEST_SEED =
+  "page pencil stock planet limb cluster assault speak off joke private pioneer";

 describe("mnemonic utilities", () => {
  let tempDir: string;
@@ -68,7 +75,11 @@ describe("mnemonic utilities", () => {
    });

    test("sanitizes filename to basename only", () => {
-      const filename = createMnemonicFile(tempDir, TEST_SEED, "../../../evil-path");
+      const filename = createMnemonicFile(
+        tempDir,
+        TEST_SEED,
+        "../../../evil-path",
+      );

      expect(filename).toBe("evil-path");
      expect(existsSync(path.join(tempDir, "evil-path"))).toBe(true);
@@ -95,7 +106,10 @@ describe("mnemonic utilities", () => {

      try {
        writeFileSync(path.join(tempDir, "mnemonic-relative"), "test");
-        const resolved = resolveMnemonicFilePath("/nonexistent", "mnemonic-relative");
+        const resolved = resolveMnemonicFilePath(
+          "/nonexistent",
+          "mnemonic-relative",
+        );
        expect(resolved).toBe(path.join(tempDir, "mnemonic-relative"));
      } finally {
        process.chdir(originalCwd);
@@ -110,15 +124,18 @@ describe("mnemonic utilities", () => {
    });

    test("throws when file not found anywhere", () => {
-      expect(() => resolveMnemonicFilePath(tempDir, "nonexistent-file")).toThrow(
-        /Mnemonic file not found/,
-      );
+      expect(() =>
+        resolveMnemonicFilePath(tempDir, "nonexistent-file"),
+      ).toThrow(/Mnemonic file not found/);
    });

    test("strips path components and looks up basename in mnemonicsDir", () => {
      writeFileSync(path.join(tempDir, "mnemonic-basename"), "test");

-      const resolved = resolveMnemonicFilePath(tempDir, "some/path/mnemonic-basename");
+      const resolved = resolveMnemonicFilePath(
+        tempDir,
+        "some/path/mnemonic-basename",
+      );
      expect(resolved).toBe(path.join(tempDir, "mnemonic-basename"));
    });
  });
@@ -140,11 +157,16 @@ describe("mnemonic utilities", () => {
    });

    test("throws when file not found", () => {
-      expect(() => loadMnemonic(tempDir, "nonexistent")).toThrow(/Mnemonic file not found/);
+      expect(() => loadMnemonic(tempDir, "nonexistent")).toThrow(
+        /Mnemonic file not found/,
+      );
    });

    test("throws when file contains invalid data", () => {
-      writeFileSync(path.join(tempDir, "mnemonic-invalid"), "not a valid mnemonic url");
+      writeFileSync(
+        path.join(tempDir, "mnemonic-invalid"),
+        "not a valid mnemonic url",
+      );

      expect(() => loadMnemonic(tempDir, "mnemonic-invalid")).toThrow();
    });
--- a/tests/cli/mocks/command.ts
+++ b/tests/cli/mocks/command.ts
@@ -92,27 +92,36 @@ export const createMockIO = (): MockIO => {
 * @param spies - The mock IO spies from createMockIO
 * @param logs - Array of log expectations to validate
 */
-export const expectLogs = (spies: MockIOSpies, logs: LogExpectation[]): void => {
+export const expectLogs = (
+  spies: MockIOSpies,
+  logs: LogExpectation[],
+): void => {
  for (const log of logs) {
    if (log.out !== undefined) {
      if (log.exact) {
        expect(spies.out).toHaveBeenCalledWith(log.out);
      } else {
-        expect(spies.out).toHaveBeenCalledWith(expect.stringContaining(log.out));
+        expect(spies.out).toHaveBeenCalledWith(
+          expect.stringContaining(log.out),
+        );
      }
    }
    if (log.err !== undefined) {
      if (log.exact) {
        expect(spies.err).toHaveBeenCalledWith(log.err);
      } else {
-        expect(spies.err).toHaveBeenCalledWith(expect.stringContaining(log.err));
+        expect(spies.err).toHaveBeenCalledWith(
+          expect.stringContaining(log.err),
+        );
      }
    }
    if (log.verbose !== undefined) {
      if (log.exact) {
        expect(spies.verbose).toHaveBeenCalledWith(log.verbose);
      } else {
-        expect(spies.verbose).toHaveBeenCalledWith(expect.stringContaining(log.verbose));
+        expect(spies.verbose).toHaveBeenCalledWith(
+          expect.stringContaining(log.verbose),
+        );
      }
    }
  }
--- a/tests/cli/mocks/electrum-service.ts
+++ b/tests/cli/mocks/electrum-service.ts
@@ -1,3 +1,8 @@
+/**
+ * Mock Electrum service for testing.
+ * NOTE & TODO: Do we even need this in the actual app? I forget why we had this, but it seems like its just overly complicating things
+ *              And we end up in stupid situations where we are creating a mock for a single function class.
+ */
 export class MockElectrumService {
  constructor() {}

--- a/tests/cli/mocks/engine.ts
+++ b/tests/cli/mocks/engine.ts
@@ -1,6 +1,12 @@
 import { BlockchainMonitor, Engine } from "@xo-cash/engine";

-import { createStorageAdapter, State, StorageType, type UnspentOutputData } from "@xo-cash/state";
+import {
+  createStorageAdapter,
+  State,
+  StorageType,
+  UnspentOutputStatus,
+  type UnspentOutputData,
+} from "@xo-cash/state";
 import { InMemoryBlockchainProvider } from "@xo-cash/engine";
 import { convertMnemonicToSeedBytes } from "@xo-cash/crypto";

@@ -8,8 +14,11 @@ import { binToHex, sha256 } from "@bitauth/libauth";
 import { AppService } from "../../../src/services/app";
 import { InMemoryStorage } from "../../../src/services/storage";
 import { MockElectrumService } from "./electrum-service";
+import { MockRatesService } from "./rates-service";
+import { RatesService } from "../../../src/services/rates";

-export const DEFAULT_SEED = "page pencil stock planet limb cluster assault speak off joke private pioneer";
+export const DEFAULT_SEED =
+  "page pencil stock planet limb cluster assault speak off joke private pioneer";

 /**
 * Options for creating a fake resource (UTXO) in tests.
@@ -39,7 +48,9 @@ export type FakeResourceOptions = {
 export const randomTxHash = (): string => {
  const bytes = new Uint8Array(32);
  crypto.getRandomValues(bytes);
-  return Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
 };

 /**
@@ -49,11 +60,11 @@ export const randomTxHash = (): string => {
 * @returns The created UnspentOutputData object.
 */
 export const addFakeResource = async (
-  engine: Engine,
+  state: State,
  options: FakeResourceOptions = {},
 ): Promise<UnspentOutputData> => {
  const resource: UnspentOutputData = {
-    status: "confirmed",
+    status: UnspentOutputStatus.CONFIRMED,
    selectable: true,
    privacy: false,
    templateIdentifier: options.templateIdentifier ?? "test-template",
@@ -62,11 +73,13 @@ export const addFakeResource = async (
    outpointTransactionHash: options.outpointTransactionHash ?? randomTxHash(),
    minedAtHeight: options.minedAtHeight ?? 800000,
    valueSatoshis: options.valueSatoshis ?? 10000,
-    lockingBytecode: options.lockingBytecode ?? "76a914000000000000000000000000000000000000000088ac",
+    scriptHash:
+      options.lockingBytecode ??
+      "76a914000000000000000000000000000000000000000088ac",
    reservedBy: options.reservedBy,
  };

-  await engine.state.storeUnspentOutputData(resource);
+  await state.storeUnspentOutputData(resource);
  return resource;
 };

@@ -78,12 +91,12 @@ export const addFakeResource = async (
 * @param invitationIdentifier - The invitation identifier to reserve for.
 */
 export const reserveResource = async (
-  engine: Engine,
+  state: State,
  outpointTransactionHash: string,
  outpointIndex: number,
  invitationIdentifier: string,
 ): Promise<void> => {
-  await engine.state.executeBulkUnspentOutputReservation(
+  await state.executeBulkUnspentOutputReservation(
    [{ outpointTransactionHash, outpointIndex }],
    true,
    invitationIdentifier,
@@ -98,12 +111,12 @@ export const reserveResource = async (
 * @param invitationIdentifier - The invitation identifier to unreserve from.
 */
 export const unreserveResource = async (
-  engine: Engine,
+  state: State,
  outpointTransactionHash: string,
  outpointIndex: number,
  invitationIdentifier: string,
 ): Promise<void> => {
-  await engine.state.executeBulkUnspentOutputReservation(
+  await state.executeBulkUnspentOutputReservation(
    [{ outpointTransactionHash, outpointIndex }],
    false,
    invitationIdentifier,
@@ -118,7 +131,7 @@ export const unreserveResource = async (
 export const createMockEngine = async (seed: string) => {
  // Create the in-memory storage adapter.
  const storage = await createStorageAdapter({
-    storageType: StorageType.INMEMORY,
+    storageType: "inmemory",
    accountHash: binToHex(sha256.hash(convertMnemonicToSeedBytes(seed))),
  });

@@ -143,13 +156,16 @@ export const createMockEngine = async (seed: string) => {
  const engine = new Engine(seed, state, blockchainMonitor, blockchainProvider);
  await engine.initializeStateSync();

-  return engine;
+  return { engine, state, blockchainMonitor, blockchainProvider };
 };

 export const createMockAppService = async (engine: Engine) => {
  const storage = await InMemoryStorage.create();

-  const electrum = new MockElectrumService();
+  const mockRates = new MockRatesService();
+  const rates = new RatesService(mockRates);
+
+  const mockElectrum = new MockElectrumService();

  const config = {
    syncServerUrl: "http://localhost:3000",
@@ -160,5 +176,5 @@ export const createMockAppService = async (engine: Engine) => {
    invitationStoragePath: "test-invitations.db",
  };

-  return new AppService(engine, storage, config, electrum);
+  return new AppService(engine, storage, config, mockElectrum, rates);
 };
--- a/tests/cli/mocks/rates-service.ts
+++ b/tests/cli/mocks/rates-service.ts
@@ -0,0 +1,23 @@
+import { BaseRates } from "../../../src/utils/rates/base-rates";
+
+export class MockRatesService extends BaseRates {
+  constructor() {
+    super();
+  }
+
+  async getRate(numeratorUnitCode: string, denominatorUnitCode: string): Promise<number> {
+    return 1;
+  }
+
+  async start(): Promise<void> {
+    return;
+  }
+
+  async stop(): Promise<void> {
+    return;
+  }
+
+  async listPairs(): Promise<Set<string>> {
+    return new Set();
+  }
+}
--- a/tests/cli/mocks/template-p2pkh.ts
+++ b/tests/cli/mocks/template-p2pkh.ts
--- a/tests/cli/paths.test.ts
+++ b/tests/cli/paths.test.ts
@@ -30,7 +30,9 @@ describe("paths utilities", () => {
    test("returns path under config dir", () => {
      const mnemonicsDir = getMnemonicsDir();

-      expect(mnemonicsDir).toBe(path.join(homedir(), ".config", "xo-cli", "mnemonics"));
+      expect(mnemonicsDir).toBe(
+        path.join(homedir(), ".config", "xo-cli", "mnemonics"),
+      );
    });

    test("creates the directory if it does not exist", () => {
@@ -58,7 +60,9 @@ describe("paths utilities", () => {
    test("returns .wallet file path under config dir", () => {
      const walletConfigPath = getWalletConfigPath();

-      expect(walletConfigPath).toBe(path.join(homedir(), ".config", "xo-cli", ".wallet"));
+      expect(walletConfigPath).toBe(
+        path.join(homedir(), ".config", "xo-cli", ".wallet"),
+      );
    });
  });

@@ -111,9 +115,9 @@ describe("paths utilities", () => {
    });

    test("throws when file not found anywhere", () => {
-      expect(() => resolveMnemonicFilePath("nonexistent-mnemonic-file-xyz")).toThrow(
-        /Mnemonic file not found/,
-      );
+      expect(() =>
+        resolveMnemonicFilePath("nonexistent-mnemonic-file-xyz"),
+      ).toThrow(/Mnemonic file not found/);
    });

    test("does not resolve absolute path if file does not exist", () => {
Author	SHA1	Message	Date
Harvmaster	2f2e515d72	Fix change output and default locking script function	2026-05-04 10:00:49 +00:00
Harvmaster	7ffb5c44b5	Fix history. Fix invitation accept	2026-05-04 09:28:23 +00:00
Harvmaster	f978d740fe	Add autocomplete installation scripts to package.json. Update readme.	2026-05-04 05:09:40 +00:00
Harvmaster	6196d33b2a	Fix build issues	2026-05-04 05:04:28 +00:00
Harvmaster	ccfaf3fd70	Update to use published packages. Update types. Update readme. Fix tests.	2026-05-04 04:45:31 +00:00
Harvmaster	531e53d2ae	Fix test	2026-04-27 12:47:02 +00:00
Harvmaster	b708c8c1f8	Fix invitation import reactivity and focus imported invitation	2026-04-27 12:46:52 +00:00
Harvmaster	53ad7b729e	Fix clipboard actions over ssh	2026-04-27 12:45:04 +00:00
Harvmaster	e73fb24422	Add installation instruction as readme	2026-04-27 12:35:54 +00:00
Harvmaster	b282bbf5d6	Update readme for cli and command parsing	2026-04-27 09:48:10 +00:00
Harvmaster	bd1ae909b5	Fix tests	2026-04-27 09:45:38 +00:00
Harvmaster	e97054fa34	Fix help docs	2026-04-27 09:45:07 +00:00
Harvmaster	a43a45831c	Missed the utils file during previous commit	2026-04-27 09:44:42 +00:00
Harvmaster	1bbc21c742	Remove [next] from template actions	2026-04-27 09:14:44 +00:00
Harvmaster	9fa87d01b3	Combine cli-utils with utils	2026-04-27 09:14:30 +00:00
Harvmaster	7ad17a7c0e	Add oracle rates	2026-04-27 08:42:51 +00:00
Harvmaster	dbfb2c68d2	Formatting	2026-04-20 12:26:35 +00:00