Document methods in resolveInvitationData

Delegate input/output merging to the engine so mergesWith extensions and
transaction indices resolve correctly instead of flattening raw commits.

package-lock.json

@@ -24,6 +24,7 @@
         "prettier": "^3.8.1",
         "qrcode": "^1.5.4",
         "react": "^19.2.4",
+        "tsx": "^4.21.0",
         "zod": "^4.3.6"
       },
       "bin": {
@@ -37,7 +38,6 @@
         "@types/qrcode": "^1.5.6",
         "@types/react": "^19.2.14",
         "@vitest/coverage-v8": "^4.1.2",
-        "tsx": "^4.21.0",
         "typescript": "^5.9.3",
         "vitest": "^4.1.2"
       }
@@ -1686,7 +1686,6 @@
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
       "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -1738,7 +1737,6 @@
       "version": "4.13.0",
       "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.13.0.tgz",
       "integrity": "sha512-1VKTZJCwBrvbd+Wn3AOgQP/2Av+TfTCOlE4AcRJE72W1ksZXbAx8PPBR9RzgTeSPzlPMHrbANMH3LbltH73wxQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "resolve-pkg-maps": "^1.0.0"
@@ -2590,7 +2588,6 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
       "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
-      "dev": true,
       "license": "MIT",
       "funding": {
         "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
@@ -3013,7 +3010,6 @@
       "version": "4.21.0",
       "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
       "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "esbuild": "~0.27.0",
@@ -3036,7 +3032,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3053,7 +3048,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3070,7 +3064,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3087,7 +3080,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3104,7 +3096,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3121,7 +3112,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3138,7 +3128,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3155,7 +3144,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3172,7 +3160,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3189,7 +3176,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3206,7 +3192,6 @@
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3223,7 +3208,6 @@
       "cpu": [
         "loong64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3240,7 +3224,6 @@
       "cpu": [
         "mips64el"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3257,7 +3240,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3274,7 +3256,6 @@
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3291,7 +3272,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3308,7 +3288,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3325,7 +3304,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3342,7 +3320,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3359,7 +3336,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3376,7 +3352,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3393,7 +3368,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3410,7 +3384,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3427,7 +3400,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3444,7 +3416,6 @@
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3461,7 +3432,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3475,7 +3445,6 @@
       "version": "0.27.7",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
       "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "bin": {
@@ -4293,9 +4262,9 @@
       "license": "ISC"
     },
     "node_modules/ws": {
-      "version": "8.19.0",
+      "version": "8.21.0",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
-      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"

package.json

@@ -12,6 +12,7 @@
     "dev": "SYNC_SERVER_URL=https://sync.xo.harvmaster.com tsx src/index.ts",
     "build": "tsc && npm run build:copy-scripts",
     "build:copy-scripts": "cp -r src/cli/autocomplete/scripts dist/cli/autocomplete/",
+    "build:unsafe": "tsc --nocheck --noEmitOnError false || true && npm run build:copy-scripts",
     "start": "SYNC_SERVER_URL=https://sync.xo.harvmaster.com node dist/index.js",
     "test": "vitest --run --passWithNoTests",
     "test:watch": "vitest",

readme.md

@@ -3,6 +3,7 @@
 ## Installation
 
 ### Full Installation
+
 ```bash
 # Create a new directory since we are going to be pulling in engine too
 mkdir xo-terminal && cd xo-terminal
@@ -126,28 +127,37 @@ npm install -g .
 
 ### Install autocomplete completions (From the xo-cli directory)
 
+These commands add `XO_CONFIG_DIR` to your shell config with a default of
+`~/.config/xo-cli`. Set it to an absolute path before installing, or edit the
+generated assignment, to use a different wallet-state 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
@@ -155,3 +165,55 @@ xo-tui
 # If not globally installed
 npm run dev
 ```
+
+## TODO
+
+### Track invitation sync-server connectivity without blocking the UI
+
+Each `Invitation` currently owns a `SyncServer` instance for its invitation
+identifier. The invitation uses that instance to open an SSE connection, fetch
+remote state, and publish local changes. Publish requests are intentionally
+fire-and-forget so that invitation actions and the TUI stay responsive when the
+sync server is slow or unavailable.
+
+The tradeoff is that failed background requests and SSE connection changes are
+not represented as application state. `SyncServer` already emits `connected`,
+`disconnected`, and `error` events, and `Invitation` emits errors from failed
+publishes, but there is no app-level owner that aggregates those events. The UI
+therefore cannot reliably tell the user that an invitation may only be updated
+locally and is not currently syncing with other participants.
+
+Implement an app-owned `InvitationConnectivityService` (or similarly named
+invitation watcher) with the following responsibilities:
+
+- Register an invitation and its `SyncServer` when `AppService` creates or loads
+  it, and unregister it when the invitation is removed or stopped.
+- Listen for each sync server's `connected`, `disconnected`, and `error` events,
+  plus invitation publish failures.
+- Track connectivity separately from the invitation's business status
+  (`actionable`, `signed`, `ready`, and so on). Suggested transport states are
+  `connecting`, `online`, `offline`, and `degraded`, with the last error and
+  last successful connection timestamp available for diagnostics.
+- Expose both per-invitation state and an aggregate app-level state such as
+  "one or more invitations are not syncing".
+- Emit normalized connectivity-change events that the CLI can log and the TUI
+  can subscribe to without awaiting sync-server requests.
+
+Keep local persistence and local invitation actions independent from remote
+sync health. Failed sync attempts should not freeze normal wallet interaction.
+The service should provide a retry path, or observe retry events from the SSE
+client, and clear the warning after connectivity recovers. If publish retries
+are added, make the retry policy explicit and preserve commit idempotency.
+
+For UI integration, inject a small notification function or subscribe at the
+app-context layer rather than having invitation instances render UI directly.
+The first version can show an error dialog when the aggregate state becomes
+unhealthy. A less intrusive version can expose the same state as a warning icon
+or message in the TUI status bar and reserve dialogs for prolonged failures or
+explicit user actions.
+
+While making this change, consolidate invitation startup ownership. Startup is
+currently triggered during `Invitation.create()` and again by
+`AppService.createInvitation()`. The watcher should have one clear lifecycle
+point so connections, listeners, retries, and cleanup are registered exactly
+once.

src/cli/README.md

@@ -9,13 +9,13 @@ There are two global commands after install:
 
 ## Global config directory
 
-Wallet state lives under **`~/.config/xo-cli/`** (XDG-style), so you can run commands from any directory:
+Wallet state lives under **`${XO_CONFIG_DIR:-~/.config/xo-cli}`**, so you can run commands from any directory. Set `XO_CONFIG_DIR` to use a different wallet-state root.
 
 | Path                        | Purpose                                                                 |
-| ----------------------------- | ----------------------------------------------------------------------- |
+| --------------------------- | ----------------------------------------------------------------------- |
-| `~/.config/xo-cli/mnemonics/` | Mnemonic files (`mnemonic-*`)                                           |
+| `$XO_CONFIG_DIR/mnemonics/` | Mnemonic files (`mnemonic-*`)                                           |
-| `~/.config/xo-cli/data/`      | Engine DB (`xo-wallet.db`) and invitation storage (`xo-invitations.db`) |
+| `$XO_CONFIG_DIR/data/`      | Engine DB (`xo-wallet.db`) and invitation storage (`xo-invitations.db`) |
-| `~/.config/xo-cli/.wallet`    | JSON settings (`default-mnemonic`, `currency`)                          |
+| `$XO_CONFIG_DIR/.wallet`    | JSON settings (`default-mnemonic`, `currency`)                          |
 
 **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`).
 
@@ -39,21 +39,24 @@ npx tsx src/cli/index.ts <command> [options]
 npx tsx src/index.ts   # TUI
 ```
 
-### Environment variables (TUI / `xo-tui`)
+### Environment variables
 
 | Variable                  | Default                                 |
-| ------------------------- | ----------------------------------------- |
+| ------------------------- | --------------------------------------- |
+| `XO_CONFIG_DIR`           | `~/.config/xo-cli`                      |
 | `SYNC_SERVER_URL`         | `http://localhost:3000`                 |
-| `DB_PATH`                 | `~/.config/xo-cli/data`                   |
+| `DB_PATH`                 | `$XO_CONFIG_DIR/data`                   |
 | `DB_FILENAME`             | `xo-wallet.db`                          |
-| `INVITATION_STORAGE_PATH` | `~/.config/xo-cli/data/xo-invitations.db` |
+| `INVITATION_STORAGE_PATH` | `$XO_CONFIG_DIR/data/xo-invitations.db` |
+
+Use an absolute path for a custom root. Setting `XO_CONFIG_DIR` does not copy state from the default directory.
 
 ## Getting Started
 
 ### Wallet Setup
 
 ```bash
-# Generate a new mnemonic (saved under ~/.config/xo-cli/mnemonics/)
+# Generate a new mnemonic (saved under $XO_CONFIG_DIR/mnemonics/)
 xo-cli mnemonic create
 
 # Import an existing mnemonic seed phrase
@@ -68,7 +71,7 @@ xo-cli mnemonic list
 ### Wallet Persistence
 
 The first time you pass `-m <name>`, that reference is saved as
-`default-mnemonic` in `~/.config/xo-cli/.wallet`. Later runs can omit `-m`.
+`default-mnemonic` in `$XO_CONFIG_DIR/.wallet`. Later runs can omit `-m`.
 
 `currency` controls the fiat unit used when showing BCH/sats conversions in the TUI.
 
@@ -76,7 +79,7 @@ Mnemonic resolution order:
 
 1. Absolute path, if the file exists
 2. Path relative to the current working directory
-3. `~/.config/xo-cli/mnemonics/<basename>`
+3. `$XO_CONFIG_DIR/mnemonics/<basename>`
 
 ```bash
 xo-cli resource list -m mnemonic-nuclear
@@ -86,14 +89,14 @@ xo-cli resource list
 ## Global Options (`xo-cli`)
 
 | Flag                           | Description                                          |
-| ------------------------------ | --------------------------------------------------- |
+| ------------------------------ | ---------------------------------------------------- |
 | `-m`, `--mnemonic-file <file>` | Mnemonic file (basename, cwd-relative, or absolute)  |
 | `--currency <code>`            | Fiat display currency (e.g. `USD`, `AUD`)            |
 | `-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`).
+Advanced: you can pass `--database-path`, `--database-filename`, and `--invitation-storage-path` to override the defaults under `$XO_CONFIG_DIR/data/` (see `src/cli/index.ts`).
 
 ## Commands
 
@@ -201,9 +204,11 @@ eval "$(xo-cli completions zsh)"
 xo-cli completions fish | source
 ```
 
+`xo-cli completions <shell> --install` adds a default `XO_CONFIG_DIR` assignment to the shell startup file if one is not already present. Mnemonic aliases are completed directly from `$XO_CONFIG_DIR/mnemonics/`; database-backed suggestions still use `xo-complete`.
+
 ## File Conventions
 
 | Location         | Purpose                                    |
-| ------------------- | ------------------------------------------ |
+| ---------------- | ------------------------------------------ |
-| `~/.config/xo-cli/` | Global wallet state                        |
+| `$XO_CONFIG_DIR` | Global wallet state                        |
 | `./` (cwd)       | Templates, invitation JSON, explicit paths |

src/cli/autocomplete/completions.ts

@@ -19,11 +19,7 @@
  *   xo-cli completions fish --install
  */
 
-import {
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from "node:fs";
-  existsSync,
-  readFileSync,
-  appendFileSync,
-} from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -193,7 +189,7 @@ export function generateFishCompletions(binName: string): string {
   return loadAndProcessTemplate("fish.fish", binName);
 }
 
-type ShellType = "bash" | "zsh" | "fish";
+export type ShellType = "bash" | "zsh" | "fish";
 
 const generators: Record<ShellType, (binName: string) => string> = {
   bash: generateBashCompletions,
@@ -202,51 +198,76 @@ const generators: Record<ShellType, (binName: string) => string> = {
 };
 
 /**
- * Shell config file paths and eval commands for each shell type.
+ * Shell config file paths and startup commands for each shell type.
  */
 const shellConfigs: Record<
   ShellType,
-  { configFile: string; evalCommand: (binName: string) => string }
+  {
+    configFile: string;
+    configDirCommand: string;
+    configDirPattern: RegExp;
+    evalCommand: (binName: string) => string;
+  }
 > = {
   bash: {
     configFile: join(homedir(), ".bashrc"),
+    configDirCommand:
+      'export XO_CONFIG_DIR="${XO_CONFIG_DIR:-$HOME/.config/xo-cli}"',
+    configDirPattern: /^\s*(?:export\s+)?XO_CONFIG_DIR=/m,
     evalCommand: (binName) => `eval "$(${binName} completions bash)"`,
   },
   zsh: {
     configFile: join(homedir(), ".zshrc"),
+    configDirCommand:
+      'export XO_CONFIG_DIR="${XO_CONFIG_DIR:-$HOME/.config/xo-cli}"',
+    configDirPattern: /^\s*(?:export\s+)?XO_CONFIG_DIR=/m,
     evalCommand: (binName) => `eval "$(${binName} completions zsh)"`,
   },
   fish: {
     configFile: join(homedir(), ".config", "fish", "config.fish"),
+    configDirCommand:
+      'set -q XO_CONFIG_DIR; or set -gx XO_CONFIG_DIR "$HOME/.config/xo-cli"',
+    configDirPattern: /^\s*set\b[^\n]*\bXO_CONFIG_DIR\b/m,
     evalCommand: (binName) => `${binName} completions fish | source`,
   },
 };
 
 /**
  * Installs completions to the user's shell config file.
- * Adds the eval command if not already present.
+ * Adds a default config directory and the eval command if not already present.
  * @param shell - The shell type
  * @param binName - The CLI binary name
  * @returns true if installed, false if already present
  */
-function installCompletions(shell: ShellType, binName: string): boolean {
+export function installCompletions(
-  const config = shellConfigs[shell];
+  shell: ShellType,
+  binName: string,
+  configFile: string = shellConfigs[shell].configFile,
+): boolean {
+  const config = { ...shellConfigs[shell], configFile };
   const evalCommand = config.evalCommand(binName);
 
-  // Check if config file exists and already has the completion line
   let existingContent = "";
   if (existsSync(config.configFile)) {
     existingContent = readFileSync(config.configFile, "utf8");
-    if (existingContent.includes(evalCommand)) {
-      return false; // Already installed
-    }
   }
 
-  // Append the completion line
+  const commands: string[] = [];
+  if (!config.configDirPattern.test(existingContent)) {
+    commands.push(config.configDirCommand);
+  }
+  if (!existingContent.includes(evalCommand)) {
+    commands.push(evalCommand);
+  }
+  if (commands.length === 0) {
+    return false;
+  }
+
   const newLine =
     existingContent.endsWith("\n") || existingContent === "" ? "" : "\n";
-  const completionBlock = `${newLine}\n# ${binName} shell completions\n${evalCommand}\n`;
+  const completionBlock = `${newLine}\n# ${binName} shell completions\n${commands.join("\n")}\n`;
 
+  mkdirSync(dirname(config.configFile), { recursive: true });
   appendFileSync(config.configFile, completionBlock);
   return true;
 }

src/cli/autocomplete/scripts/bash.sh

@@ -26,6 +26,19 @@ __xo_complete() {
   [[ -n "${__xo_complete_bin}" ]] && "${__xo_complete_bin}" "$@" 2>/dev/null
 }
 
+# @description
+# Lists mnemonic aliases directly from the config directory without starting
+# the dynamic Node helper.
+__xo_complete_mnemonics() {
+  local config_dir="${XO_CONFIG_DIR:-${HOME}/.config/xo-cli}"
+  local file mnemonic
+  for file in "${config_dir}"/mnemonics/mnemonic-*; do
+    [[ -f "${file}" ]] || continue
+    mnemonic="${file##*/}"
+    [[ "${mnemonic}" == "$1"* ]] && printf '%s\n' "${mnemonic}"
+  done
+}
+
 # @description
 # Main completion dispatcher invoked by bash's `complete -F`.
 # It determines context (command/subcommand/argument position) and then mixes:
@@ -39,10 +52,10 @@ _{{FUNC_NAME}}_completions() {
   _init_completion || return
 
   # If the previous token is `-m/--mnemonic-file`, this argument expects a
-  # mnemonic file alias/path. Ask the helper for mnemonic suggestions.
+  # mnemonic file alias/path. List mnemonic aliases directly from disk.
   if [[ "${prev}" == "-m" || "${prev}" == "--mnemonic-file" ]]; then
     local mnemonics
-    mnemonics=$(__xo_complete mnemonics "${cur}")
+    mnemonics=$(__xo_complete_mnemonics "${cur}")
     if [[ -n "${mnemonics}" ]]; then
       while IFS= read -r line; do
         COMPREPLY+=("$line")
@@ -161,7 +174,7 @@ _{{FUNC_NAME}}_completions() {
               fi
             fi
             ;;
-          append|sign|broadcast|requirements|export|inspect)
+          append|sign|broadcast|requirements|export|inspect|delete)
             # These subcommands expect an invitation identifier as first arg.
             local pos=$((cword - subcmd_idx))
             if [[ $pos -eq 1 ]]; then

src/cli/autocomplete/scripts/fish.fish

@@ -28,6 +28,21 @@ function __{{FUNC_NAME}}_complete_dynamic
   end
 end
 
+# @description
+# Lists mnemonic aliases directly from the config directory without starting
+# the dynamic Node helper.
+function __{{FUNC_NAME}}_complete_mnemonics
+  set -l config_dir "$XO_CONFIG_DIR"
+  if test -z "$config_dir"
+    set config_dir "$HOME/.config/xo-cli"
+  end
+  for file in $config_dir/mnemonics/mnemonic-*
+    if test -f "$file"
+      string replace -r '.*/' '' "$file"
+    end
+  end
+end
+
 # Global option flags available across top-level command contexts.
 complete -c {{BIN_NAME}} -s h -d "Show help"
 complete -c {{BIN_NAME}} -l help -d "Show help"
@@ -37,8 +52,8 @@ complete -c {{BIN_NAME}} -s o -d "Output file"
 complete -c {{BIN_NAME}} -l output -d "Output file"
 complete -c {{BIN_NAME}} -l currency -d "Set fiat display currency"
 
-# Dynamic completion for `-m/--mnemonic-file`.
+# Shell-native completion for `-m/--mnemonic-file`.
-complete -c {{BIN_NAME}} -s m -l mnemonic-file -xa '(__{{FUNC_NAME}}_complete_dynamic mnemonics)'
+complete -c {{BIN_NAME}} -s m -l mnemonic-file -xa '(__{{FUNC_NAME}}_complete_mnemonics)'
 
 # Top-level command registrations inserted by template expansion.
 {{TOP_LEVEL_COMMANDS}}

src/cli/autocomplete/scripts/zsh.zsh

@@ -25,6 +25,19 @@ __xo_complete() {
   [[ -n "${__xo_complete_bin}" ]] && "${__xo_complete_bin}" "$@" 2>/dev/null
 }
 
+# @description
+# Lists mnemonic aliases directly from the config directory without starting
+# the dynamic Node helper.
+__xo_complete_mnemonics() {
+  local config_dir="${XO_CONFIG_DIR:-${HOME}/.config/xo-cli}"
+  local file mnemonic
+  for file in "${config_dir}"/mnemonics/mnemonic-*(N); do
+    [[ -f "${file}" ]] || continue
+    mnemonic="${file:t}"
+    [[ "${mnemonic}" == "$1"* ]] && print -r -- "${mnemonic}"
+  done
+}
+
 # @description
 # Main zsh completion dispatcher registered via `compdef`.
 # It resolves command context from `$words`/`$CURRENT` and serves:
@@ -38,7 +51,7 @@ _{{FUNC_NAME}}_completions() {
   # If previous token is `-m/--mnemonic-file`, complete mnemonic sources.
   if [[ "${words[CURRENT-1]}" == "-m" || "${words[CURRENT-1]}" == "--mnemonic-file" ]]; then
     local mnemonics
-    mnemonics=("${(@f)$(__xo_complete mnemonics "${words[CURRENT]}")}")
+    mnemonics=("${(@f)$(__xo_complete_mnemonics "${words[CURRENT]}")}")
     if [[ ${#mnemonics[@]} -gt 0 ]]; then
       compadd -- "${mnemonics[@]}"
       return

src/cli/commands/invitation.ts

@@ -23,7 +23,10 @@ const DUST_THRESHOLD = 546n;
 /**
  * Serializes an invitation to pretty-printed JSON for file export.
  */
-const formatInvitationForFile = (invitation: XOInvitation, indent = 2): string =>
+const formatInvitationForFile = (
+  invitation: XOInvitation,
+  indent = 2,
+): string =>
   JSON.stringify(JSON.parse(serializeInvitation(invitation)), null, indent);
 
 /**
@@ -295,6 +298,7 @@ ${bold("Sub-commands:")}
     - requirements <invitation-id> ${dim("Show requirements for an invitation")}
     - import <invitation-file> ${dim("Import an invitation from a file")}
     - export <invitation-id> [output-file] ${dim("Export an invitation to stdout or a file")}
+    - delete <invitation-id> ${dim("Delete an invitation")}
     - inspect <invitation-id | invitation-file> ${dim("Inspect an invitation")}
     - list ${dim("List all invitations")}
 
@@ -358,8 +362,7 @@ export const handleInvitationExportCommand = async (
   }
 
   const invitation = deps.app.invitations.find(
-    (candidate) =>
+    (candidate) => candidate.data.invitationIdentifier === invitationIdentifier,
-      candidate.data.invitationIdentifier === invitationIdentifier,
   );
 
   if (!invitation) {
@@ -499,7 +502,9 @@ export const handleInvitationCommand = async (
         hasMissingRequirements(missingRequirements.templateRequirements) ||
         missingRequirements.inputsMissingSignatures.length > 0;
 
-      deps.io.verbose(`Missing requirements: ${formatObject(missingRequirements)}`);
+      deps.io.verbose(
+        `Missing requirements: ${formatObject(missingRequirements)}`,
+      );
       deps.io.verbose(`Has missing requirements: ${hasMissing}`);
 
       // If there are missing requirements, print them out
@@ -951,6 +956,47 @@ export const handleInvitationCommand = async (
       return handleInvitationExportCommand(deps, args.slice(1), options);
     }
 
+    case "delete": {
+      // Get the invitation identifier from the arguments
+      const invitationIdentifier = args[1];
+      deps.io.verbose(`Invitation identifier: ${invitationIdentifier}`);
+
+      // If they didnt provide us with an invitation identifier, print the help message and throw an error
+      // TODO: Should probably print a specific help message for this command?
+      if (!invitationIdentifier) {
+        deps.io.verbose("No invitation identifier provided");
+        printInvitationHelp(deps.io);
+        throw new CommandError(
+          "invitation.delete.identifier_missing",
+          "No invitation identifier provided",
+        );
+      }
+
+      // Find the invitation instance in our list of invitations
+      const invitation = deps.app.invitations.find(
+        (candidate) =>
+          candidate.data.invitationIdentifier === invitationIdentifier,
+      );
+
+      // If the invitation is not found, print an error and throw an error
+      if (!invitation) {
+        deps.io.err(`Invitation not found: ${invitationIdentifier}`);
+        throw new CommandError(
+          "invitation.delete.not_found",
+          `Invitation not found: ${invitationIdentifier}`,
+        );
+      }
+      deps.io.verbose(`Invitation: ${formatObject(invitation.data)}`);
+
+      // Delete the invitation
+      await invitation.delete();
+      deps.io.verbose(`Invitation deleted: ${formatObject(invitation.data)}`);
+      deps.io.out(`Invitation deleted: ${invitationIdentifier}`);
+
+      // Return the invitation identifier
+      return { invitationIdentifier };
+    }
+
     case "list": {
       // List all the invitations
       const invitations = await Promise.all(

src/cli/commands/resource.ts

@@ -37,7 +37,9 @@ function formatResource(
   showReserved = false,
 ): string {
   // Format the template
-  const template = resource.template ? dim(`[${generateTemplateIdentifier(resource.template)}]`) : "";
+  const template = resource.template
+    ? dim(`[${generateTemplateIdentifier(resource.template)}]`)
+    : "";
 
   // Format the outpoint
   const outpoint = bold(

src/cli/commands/settings.ts

@@ -83,7 +83,7 @@ export const handleSettingsCommand = async (
       const value =
         key === "currency"
           ? settings.getCurrency()
-          : settings.getDefaultMnemonic() ?? "";
+          : (settings.getDefaultMnemonic() ?? "");
       deps.io.out(value);
       return { key, value };
     }

src/cli/commands/template.ts

@@ -4,7 +4,10 @@ import { generateTemplateIdentifier } from "@xo-cash/engine";
 import type { XOTemplate } from "@xo-cash/types";
 
 import { bold, dim, formatObject } from "../utils.js";
-import { loadTemplateFromFile, TemplateLoadError } from "../../utils/load-template-from-file.js";
+import {
+  loadTemplateFromFile,
+  TemplateLoadError,
+} from "../../utils/load-template-from-file.js";
 import { resolveTemplateReferences } from "../../utils/templates.js";
 import type { CommandDependencies, CommandIO } from "./types.js";
 import { CommandError } from "./types.js";

src/cli/index.ts

@@ -181,7 +181,9 @@ async function main(): Promise<void> {
 
   // Create an App instance
   io.verbose("Creating app instance...");
-  const app = await AppService.create(mnemonic, {
+  const app = await AppService.create(
+    mnemonic,
+    {
       syncServerUrl: options["syncServerUrl"] ?? "http://localhost:3000",
       engineConfig: {
         databasePath: options["databasePath"] ?? paths.dataDir,
@@ -190,7 +192,9 @@ async function main(): Promise<void> {
       invitationStoragePath:
         options["invitationStoragePath"] ??
         join(paths.dataDir, "xo-invitations.db"),
-  }, settings);
+    },
+    settings,
+  );
   io.verbose("App instance created");
 
   // Start the app

src/services/app.ts

@@ -67,6 +67,7 @@ export class AppService extends EventEmitter<AppEventMap> {
     {
       onUpdated: (invitation: XOInvitation) => void;
       onStatusChanged: (status: string) => void;
+      onRemoved: () => void;
     }
   >();
 
@@ -100,8 +101,12 @@ export class AppService extends EventEmitter<AppEventMap> {
       const templates = await engine.listImportedTemplates();
 
       templates.forEach(async (template) => {
-        engine.updateUnspentOutputsForTemplate(generateTemplateIdentifier(template));
+        engine.updateUnspentOutputsForTemplate(
-        engine.subscribeToScriptHashForTemplate(generateTemplateIdentifier(template));
+          generateTemplateIdentifier(template),
+        );
+        engine.subscribeToScriptHashForTemplate(
+          generateTemplateIdentifier(template),
+        );
       });
     };
 
@@ -127,7 +132,14 @@ export class AppService extends EventEmitter<AppEventMap> {
     });
     const rates = await RatesService.create(settings);
 
-    return new AppService(engine, walletStorage, config, electrum, rates, settings);
+    return new AppService(
+      engine,
+      walletStorage,
+      config,
+      electrum,
+      rates,
+      settings,
+    );
   }
 
   constructor(
@@ -173,7 +185,7 @@ export class AppService extends EventEmitter<AppEventMap> {
 
     // Attach listeners before SSE connects so updates are not missed.
     await this.addInvitation(invitationInstance);
-    await invitationInstance.start();
+    invitationInstance.start();
 
     return invitationInstance;
   }
@@ -183,6 +195,7 @@ export class AppService extends EventEmitter<AppEventMap> {
 
     // Add the invitation to the invitations array
     this.invitations.push(invitation);
+    this.bumpInvitationRevision(invitation.data.invitationIdentifier);
 
     // Emit the invitation-added event
     this.emit("invitation-added", invitation);
@@ -201,6 +214,7 @@ export class AppService extends EventEmitter<AppEventMap> {
     if (invitationIndex >= 0) {
       this.invitations.splice(invitationIndex, 1);
     }
+    this.bumpInvitationRevision(invitationIdentifier);
 
     // Emit the invitation-removed event
     this.emit("invitation-removed", invitation);
@@ -215,27 +229,53 @@ export class AppService extends EventEmitter<AppEventMap> {
     if (this.invitationEventCleanup.has(invitationIdentifier)) return;
 
     const onUpdated = () => {
+      this.bumpInvitationRevision(invitationIdentifier);
       this.emit("wallet-state-changed", {
         reason: "invitation-updated",
         invitationIdentifier,
       });
     };
     const onStatusChanged = () => {
+      this.bumpInvitationRevision(invitationIdentifier);
       this.emit("wallet-state-changed", {
         reason: "invitation-status-changed",
         invitationIdentifier,
       });
     };
+    const onRemoved = () => {
+      this.detachInvitationListeners(invitationIdentifier);
+      this.invitations.splice(this.invitations.indexOf(invitation), 1);
+      this.bumpInvitationRevision(invitationIdentifier);
+      this.emit("invitation-removed", invitation);
+      this.emit("wallet-state-changed", {
+        reason: "invitation-removed",
+        invitationIdentifier: invitationIdentifier,
+      });
+    };
 
     invitation.on("invitation-updated", onUpdated);
     invitation.on("invitation-status-changed", onStatusChanged);
+    invitation.on("invitation-removed", onRemoved);
 
     this.invitationEventCleanup.set(invitationIdentifier, {
       onUpdated,
       onStatusChanged,
+      onRemoved,
     });
   }
 
+  getInvitationRevision(invitationIdentifier: string): number {
+    return this.invitationRevisions.get(invitationIdentifier) ?? 0;
+  }
+
+  private bumpInvitationRevision(invitationIdentifier: string): void {
+    this.invitationsRevision += 1;
+    this.invitationRevisions.set(
+      invitationIdentifier,
+      this.getInvitationRevision(invitationIdentifier) + 1,
+    );
+  }
+
   private detachInvitationListeners(invitationIdentifier: string): void {
     const trackedInvitation = this.invitations.find(
       (candidate) =>
@@ -282,9 +322,9 @@ 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) =>
+    this.rates
-      console.error('Error starting rates service:', err),
+      .start()
-    );
+      .catch((err) => console.error("Error starting rates service:", err));
 
     // Get the invitations db
     const invitationsDb = this.storage.child("invitations");

src/services/history.ts

@@ -95,7 +95,6 @@ export class HistoryService {
     private invitations: Invitation[],
   ) {}
 
-
   /**
    * I Might swap this over to invitation based history before the event to make it a bit more evident... Really not happy with the UTXO for demo purposes
    * But for the actual usage, UTXO is easier to follow - just not good for demo
@@ -114,7 +113,10 @@ export class HistoryService {
 
     for (const context of utxoContexts) {
       const invitationIdentifier = context.utxo.reservedBy;
-      if (invitationIdentifier && invitationContexts.has(invitationIdentifier)) {
+      if (
+        invitationIdentifier &&
+        invitationContexts.has(invitationIdentifier)
+      ) {
         const group = reservedUtxosByInvitation.get(invitationIdentifier) ?? [];
         group.push(context);
         reservedUtxosByInvitation.set(invitationIdentifier, group);
@@ -141,13 +143,15 @@ export class HistoryService {
     });
   }
 
-  private async buildInvitationContextIndex(): Promise<Map<string, InvitationContext>> {
+  private async buildInvitationContextIndex(): Promise<
+    Map<string, InvitationContext>
+  > {
     const contexts = new Map<string, InvitationContext>();
 
     for (const invitation of this.invitations) {
       const templateIdentifier = invitation.data.templateIdentifier;
       const template = templateIdentifier
-        ? (await this.engine.getTemplate(templateIdentifier)) ?? null
+        ? ((await this.engine.getTemplate(templateIdentifier)) ?? null)
         : null;
       contexts.set(invitation.data.invitationIdentifier, {
         invitation,
@@ -181,9 +185,13 @@ export class HistoryService {
     }
 
     for (const templateIdentifier of templateIdentifiers) {
-      const scriptHashDataList = await this.engine.listScriptHashesForTemplate(templateIdentifier);
+      const scriptHashDataList =
+        await this.engine.listScriptHashesForTemplate(templateIdentifier);
       for (const scriptHashData of scriptHashDataList) {
-        scriptHashDataByScriptHash.set(scriptHashData.scriptHash, scriptHashData);
+        scriptHashDataByScriptHash.set(
+          scriptHashData.scriptHash,
+          scriptHashData,
+        );
       }
     }
 
@@ -194,10 +202,12 @@ export class HistoryService {
     utxo: UnspentOutputData,
     metadataIndex: WalletMetadataIndex,
   ): Promise<UtxoContext> {
-    const scriptHashData = metadataIndex.scriptHashDataByScriptHash.get(utxo.scriptHash);
+    const scriptHashData = metadataIndex.scriptHashDataByScriptHash.get(
+      utxo.scriptHash,
+    );
     const templateIdentifier = scriptHashData?.templateIdentifier;
     const template = templateIdentifier
-      ? (await this.engine.getTemplate(templateIdentifier)) ?? null
+      ? ((await this.engine.getTemplate(templateIdentifier)) ?? null)
       : null;
 
     return {
@@ -213,8 +223,15 @@ export class HistoryService {
   ): WalletHistoryItem {
     const invitation = context.invitation.data;
     const entityRoles = this.deriveInvitationEntityRoles(context);
-    const inputs = this.projectInvitationInputs(context, reservedContexts, entityRoles);
+    const inputs = this.projectInvitationInputs(
-    const inputUtxoIds = this.listInvitationInputUtxoIds(context, reservedContexts);
+      context,
+      reservedContexts,
+      entityRoles,
+    );
+    const inputUtxoIds = this.listInvitationInputUtxoIds(
+      context,
+      reservedContexts,
+    );
     const outputs = this.projectInvitationOutputs(
       context,
       reservedContexts,
@@ -263,7 +280,9 @@ export class HistoryService {
         const outpointIndex = input.outpointIndex;
         if (txid === undefined || outpointIndex === undefined) continue;
 
-        const utxoContext = reservedByOutpoint.get(this.getOutpointKey(txid, outpointIndex));
+        const utxoContext = reservedByOutpoint.get(
+          this.getOutpointKey(txid, outpointIndex),
+        );
         // TODO: Remove this reservation-based filter once Engine/library cleanup releases stale invitation reservations internally.
         if (!utxoContext) continue;
 
@@ -309,13 +328,18 @@ export class HistoryService {
         // UTXO-first: committed outputs only matter here if they resolve to a wallet UTXO currently reserved by this invitation.
         if (!matchingContext) continue;
 
-        const lockingBytecode = this.getOutputLockingBytecodeHex(output) ?? matchingContext.scriptHashData?.lockingBytecode;
+        const lockingBytecode =
-        const outputIdentifier = output.outputIdentifier ?? matchingContext.scriptHashData?.outputIdentifier;
+          this.getOutputLockingBytecodeHex(output) ??
+          matchingContext.scriptHashData?.lockingBytecode;
+        const outputIdentifier =
+          output.outputIdentifier ??
+          matchingContext.scriptHashData?.outputIdentifier;
         const role =
           output.roleIdentifier ??
           this.getFirstEntityRole(entityRoles, commit.entityIdentifier) ??
           matchingContext.scriptHashData?.roleIdentifier;
-        const valueSatoshis = output.valueSatoshis !== undefined
+        const valueSatoshis =
+          output.valueSatoshis !== undefined
             ? BigInt(output.valueSatoshis)
             : BigInt(matchingContext.utxo.valueSatoshis);
 
@@ -369,8 +393,11 @@ export class HistoryService {
         const outpointIndex = input.outpointIndex;
         if (txid === undefined || outpointIndex === undefined) continue;
 
-        const utxoContext = reservedByOutpoint.get(this.getOutpointKey(txid, outpointIndex));
+        const utxoContext = reservedByOutpoint.get(
-        if (utxoContext) invitationInputUtxoIds.add(this.getUtxoId(utxoContext.utxo));
+          this.getOutpointKey(txid, outpointIndex),
+        );
+        if (utxoContext)
+          invitationInputUtxoIds.add(this.getUtxoId(utxoContext.utxo));
       }
     }
 
@@ -390,9 +417,17 @@ export class HistoryService {
     return reservedContexts.find((context) => {
       if (usedUtxoIds.has(this.getUtxoId(context.utxo))) return false;
       if (scriptHash && context.utxo.scriptHash === scriptHash) return true;
-      if (lockingBytecode && context.scriptHashData?.lockingBytecode === lockingBytecode) return true;
+      if (
+        lockingBytecode &&
+        context.scriptHashData?.lockingBytecode === lockingBytecode
+      )
+        return true;
 
-      if (output.outputIdentifier && context.scriptHashData?.outputIdentifier === output.outputIdentifier) return true;
+      if (
+        output.outputIdentifier &&
+        context.scriptHashData?.outputIdentifier === output.outputIdentifier
+      )
+        return true;
       return false;
     });
   }
@@ -423,7 +458,11 @@ export class HistoryService {
       id: this.getUtxoId(context.utxo),
       outputIdentifier,
       role,
-      description: this.describeOutputFromTemplate(outputIdentifier, context.template, {}),
+      description: this.describeOutputFromTemplate(
+        outputIdentifier,
+        context.template,
+        {},
+      ),
       valueSatoshis: BigInt(context.utxo.valueSatoshis),
       outpoint: {
         txid: context.utxo.outpointTransactionHash,
@@ -435,17 +474,22 @@ export class HistoryService {
     };
   }
 
-  private deriveInvitationEntityRoles(context: InvitationContext): Map<string, string[]> {
+  private deriveInvitationEntityRoles(
+    context: InvitationContext,
+  ): Map<string, string[]> {
     const invitation = context.invitation.data;
     const rolesByEntity = new Map<string, Set<string>>();
-    const allEntities = new Set(invitation.commits.map((commit) => commit.entityIdentifier));
+    const allEntities = new Set(
+      invitation.commits.map((commit) => commit.entityIdentifier),
+    );
 
     for (const entityIdentifier of allEntities) {
       rolesByEntity.set(entityIdentifier, new Set());
     }
 
     for (const commit of invitation.commits) {
-      const roles = rolesByEntity.get(commit.entityIdentifier) ?? new Set<string>();
+      const roles =
+        rolesByEntity.get(commit.entityIdentifier) ?? new Set<string>();
       for (const input of commit.data.inputs ?? []) {
         if (input.roleIdentifier) roles.add(input.roleIdentifier);
       }
@@ -459,7 +503,8 @@ export class HistoryService {
     }
 
     const action = context.template?.actions?.[invitation.actionIdentifier];
-    const participantRoles = action?.requirements?.participants
+    const participantRoles =
+      action?.requirements?.participants
         ?.map((participant) => participant.role)
         .filter((role): role is string => typeof role === "string") ?? [];
     const explicitlyFilledRoles = new Set<string>();
@@ -473,7 +518,10 @@ export class HistoryService {
       .filter(([, roles]) => roles.size === 0)
       .map(([entityIdentifier]) => entityIdentifier);
 
-    if (unfilledParticipantRoles.length === 1 && entitiesWithoutRoles.length >= 1) {
+    if (
+      unfilledParticipantRoles.length === 1 &&
+      entitiesWithoutRoles.length >= 1
+    ) {
       const inferredRole = unfilledParticipantRoles[0];
       if (inferredRole !== undefined) {
         for (const entityIdentifier of entitiesWithoutRoles) {
@@ -517,12 +565,21 @@ export class HistoryService {
     inputs: WalletHistoryInput[],
     outputs: WalletHistoryOutput[],
   ): bigint {
-    const inputTotal = inputs.reduce((total, input) => total + (input.valueSatoshis ?? 0n), 0n);
+    const inputTotal = inputs.reduce(
-    const outputTotal = outputs.reduce((total, output) => total + (output.valueSatoshis ?? 0n), 0n);
+      (total, input) => total + (input.valueSatoshis ?? 0n),
+      0n,
+    );
+    const outputTotal = outputs.reduce(
+      (total, output) => total + (output.valueSatoshis ?? 0n),
+      0n,
+    );
     return inputTotal + outputTotal;
   }
 
-  private describeInvitation(context: InvitationContext, role?: string): string {
+  private describeInvitation(
+    context: InvitationContext,
+    role?: string,
+  ): string {
     const invitation = context.invitation.data;
     const template = context.template;
     if (!template) return invitation.actionIdentifier;
@@ -544,14 +601,27 @@ export class HistoryService {
     return this.compileDescription(descriptionTemplate, context.variables);
   }
 
-  private describeInput(inputIdentifier: string | undefined, context: InvitationContext): string {
+  private describeInput(
+    inputIdentifier: string | undefined,
+    context: InvitationContext,
+  ): string {
     if (!inputIdentifier) return "Input";
     const input = context.template?.inputs?.[inputIdentifier];
-    return this.compileDescription(input?.description ?? input?.name ?? inputIdentifier, context.variables);
+    return this.compileDescription(
+      input?.description ?? input?.name ?? inputIdentifier,
+      context.variables,
+    );
   }
 
-  private describeOutput(outputIdentifier: string | undefined, context: InvitationContext): string {
+  private describeOutput(
-    return this.describeOutputFromTemplate(outputIdentifier, context.template, context.variables);
+    outputIdentifier: string | undefined,
+    context: InvitationContext,
+  ): string {
+    return this.describeOutputFromTemplate(
+      outputIdentifier,
+      context.template,
+      context.variables,
+    );
   }
 
   private describeOutputFromTemplate(
@@ -561,7 +631,10 @@ export class HistoryService {
   ): string {
     if (!outputIdentifier) return "Output";
     const output = template?.outputs?.[outputIdentifier];
-    return this.compileDescription(output?.description ?? output?.name ?? outputIdentifier, variables);
+    return this.compileDescription(
+      output?.description ?? output?.name ?? outputIdentifier,
+      variables,
+    );
   }
 
   private compileDescription(
@@ -569,16 +642,25 @@ export class HistoryService {
     variables: Record<string, XOInvitationVariableValue>,
   ): string {
     try {
-      return compileCashAssemblyString({ cashAssemblyText: description, variables, evaluationDecodeMode: 'utf8' });
+      return compileCashAssemblyString({
+        cashAssemblyText: description,
+        variables,
+        evaluationDecodeMode: "utf8",
+      });
     } catch {
-      return this.interpolateSimpleCashAssemblyVariables(description, variables);
+      return this.interpolateSimpleCashAssemblyVariables(
+        description,
+        variables,
+      );
     }
   }
 
   private extractInvitationVariables(
     invitation: XOInvitation,
   ): Record<string, XOInvitationVariableValue> {
-    const committedVariables = invitation.commits.flatMap((c) => c.data.variables ?? []);
+    const committedVariables = invitation.commits.flatMap(
+      (c) => c.data.variables ?? [],
+    );
     return committedVariables.reduce(
       (acc, variable) => {
         if (!variable.variableIdentifier) return acc;
@@ -596,15 +678,21 @@ export class HistoryService {
       : String(input.outpointTransactionHash);
   }
 
-  private getOutputLockingBytecodeHex(output: XOInvitationOutput): string | undefined {
+  private getOutputLockingBytecodeHex(
+    output: XOInvitationOutput,
+  ): string | undefined {
     if (output.lockingBytecode === undefined) return undefined;
     return typeof output.lockingBytecode === "string"
       ? output.lockingBytecode
       : binToHex(output.lockingBytecode);
   }
 
-  private async getScriptHashData(scriptHash: string): Promise<ScriptHashData | undefined> {
+  private async getScriptHashData(
-    return (this.engine as unknown as { state: State }).state.getScriptHashData(scriptHash);
+    scriptHash: string,
+  ): Promise<ScriptHashData | undefined> {
+    return (this.engine as unknown as { state: State }).state.getScriptHashData(
+      scriptHash,
+    );
   }
 
   private getOutpointKey(txid: string, index: number): string {
@@ -627,7 +715,9 @@ export class HistoryService {
     return text.replace(
       /\$\(<([^>]+)>\)/g,
       (match, variableIdentifier: string) => {
-        if (!Object.prototype.hasOwnProperty.call(variables, variableIdentifier)) {
+        if (
+          !Object.prototype.hasOwnProperty.call(variables, variableIdentifier)
+        ) {
           return match;
         }
         return String(variables[variableIdentifier]);

src/services/invitation.ts

@@ -3,7 +3,13 @@ import type {
   Engine,
   GetSpendableResourcesParameters,
 } from "@xo-cash/engine";
-import { generateTemplateIdentifier, hasInvitationExpired, mergeInvitationCommits, serializeInvitation } from "@xo-cash/engine";
+import {
+  generateTemplateIdentifier,
+  hasInvitationExpired,
+  mergeInvitationCommits,
+  serializeInvitation,
+  deserializeInvitation,
+} from "@xo-cash/engine";
 import type {
   XOInvitation,
   XOInvitationCommit,
@@ -11,6 +17,7 @@ import type {
   XOInvitationOutput,
   XOInvitationVariable,
   XOInvitationVariableValue,
+  XOTemplate,
 } from "@xo-cash/types";
 import type { UnspentOutputData } from "@xo-cash/state";
 import {
@@ -28,11 +35,18 @@ import type { BlockchainService } from "./electrum.js";
 
 import { EventEmitter } from "../utils/event-emitter.js";
 import { decodeExtendedJsonObject } from "../utils/ext-json.js";
+import {
+  resolveCommitReferences,
+  type ResolvedInvitationData,
+} from "../utils/resolve-invitation-data.js";
 import { compileCashAssemblyString } from "@xo-cash/engine";
 
+export type { ResolvedInvitationData } from "../utils/resolve-invitation-data.js";
+
 export type InvitationEventMap = {
   "invitation-updated": XOInvitation;
   "invitation-status-changed": string;
+  "invitation-removed": void;
   error: Error;
 };
 
@@ -43,6 +57,13 @@ export type InvitationDependencies = {
   electrum: BlockchainService;
 };
 
+function stripLocalInvitationMetadata(invitation: XOInvitation): XOInvitation {
+  const { entityIdentifier: _entityIdentifier, ...sharedInvitation } =
+    invitation as XOInvitation & { entityIdentifier?: string };
+
+  return sharedInvitation;
+}
+
 export class Invitation extends EventEmitter<InvitationEventMap> {
   /**
    * Create an invitation and start the SSE Session required for it.
@@ -85,17 +106,38 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
     }
 
     // engine invitation (I have no idea if this is required)
-    const engineInvitation = await dependencies.engine.importInvitation(serializeInvitation(invitation));
+    const engineInvitation = await dependencies.engine.importInvitation(
+      serializeInvitation(invitation),
+    );
 
     // Create the invitation
-    const invitationInstance = new Invitation(engineInvitation, dependencies);
+    const invitationInstance = new Invitation(
-
+      engineInvitation,
-    // Start the invitation and its tracking
+      dependencies,
-    invitationInstance.start();
+      template,
+    );
 
     return invitationInstance;
   }
 
+  /**
+   * Flattened, template-enriched view of {@link Invitation.data}.
+   * Updated automatically whenever invitation data changes.
+   */
+  public resolvedData: ResolvedInvitationData = {
+    invitationIdentifier: "",
+    templateIdentifier: "",
+    actionIdentifier: "",
+    variables: [],
+    inputs: [],
+    outputs: [],
+  };
+
+  /**
+   * The template used to enrich {@link resolvedData}.
+   */
+  private template: XOTemplate;
+
   /**
    * The invitation data.
    */
@@ -123,6 +165,7 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    */
   private storage: BaseStorage;
   private electrum: BlockchainService;
+  private sseUpdateQueue: Promise<void> = Promise.resolve();
 
   /**
    * The status of the invitation (last emitted word: pending, actionable, signed, ready, complete, expired, unknown).
@@ -132,17 +175,45 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
   /**
    * Create an invitation and start the SSE Session required for it.
    */
-  constructor(invitation: XOInvitation, dependencies: InvitationDependencies) {
+  constructor(
+    invitation: XOInvitation,
+    dependencies: InvitationDependencies,
+    template: XOTemplate,
+  ) {
     super();
 
-    this.data = invitation;
+    this.template = template;
     this.engine = dependencies.engine;
     this.syncServer = dependencies.syncServer;
     this.storage = dependencies.storage;
     this.electrum = dependencies.electrum;
+    this.updateInvitationData(invitation);
 
-    // Create a listerner for the messages from the SSE Session (sync server)
+    // Apply SSE updates serially so each engine update sees the latest history.
-    this.syncServer.on("message", this.handleSSEMessage.bind(this));
+    this.syncServer.on("message", (event) => {
+      this.enqueueSyncUpdate(() => this.handleSSEMessage(event)).catch(
+        (error) => {
+          this.emit(
+            "error",
+            error instanceof Error ? error : new Error(String(error)),
+          );
+        },
+      );
+    });
+  }
+
+  /**
+   * Updates raw invitation data and recomputes {@link resolvedData}.
+   */
+  private updateInvitationData(invitation: XOInvitation): void {
+    this.data = invitation;
+    this.resolvedData = resolveCommitReferences(invitation, this.template);
+  }
+
+  private enqueueSyncUpdate(update: () => Promise<void>): Promise<void> {
+    const queuedUpdate = this.sseUpdateQueue.then(update);
+    this.sseUpdateQueue = queuedUpdate.catch(() => {});
+    return queuedUpdate;
   }
 
   /**
@@ -160,20 +231,34 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
         this.syncServer.getInvitation(this.data.invitationIdentifier),
       ]);
 
-      // There is a chance we get SSE messages before the invitation is returned, so we want to combine any commits
+      await this.enqueueSyncUpdate(async () => {
-      const sseCommits = this.data.commits;
+        // SSE messages can arrive before the GET request completes.
-
-      // Merge the commits
         const combinedCommits = this.mergeCommits(
-        sseCommits,
+          this.data.commits,
           invitation?.commits ?? [],
         );
 
-      // Set the invitation data with the combined commits
+        try {
-      this.data = { ...this.data, ...invitation, commits: combinedCommits };
+          // Prefer keeping the engine's local invitation state in sync.
+          this.updateInvitationData(
+            stripLocalInvitationMetadata(
+              await this.engine.updateInvitation({
+                ...this.data,
+                ...invitation,
+                commits: combinedCommits,
+              }),
+            ),
+          );
+        } catch (error) {
+          this.emit(
+            "error",
+            error instanceof Error ? error : new Error(String(error)),
+          );
+          this.updateInvitationData({ ...this.data, commits: combinedCommits });
+        }
 
-      // Store the invitation in the storage
         await this.storage.set(this.data.invitationIdentifier, this.data);
+      });
 
       // Publish the invitation to the sync server
       this.publishInvitation(this.data);
@@ -181,8 +266,6 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
       // Compute and emit initial status
       await this.updateStatus();
     } catch (err) {
-      // console.error(`Error starting invitation, could not connect to sync server or get invitation`, err);
-      // Emit the error event. We might want to throw? but we need a better way of handling errors in the invitation system because we need the invitation to successfully initialize.
       this.emit("error", err instanceof Error ? err : new Error(String(err)));
     }
   }
@@ -192,30 +275,87 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    *
    * TODO: Invitation should sync up the initial data (top level) then everything after that should be the commits. This makes it easier to merge as we go instead of just having to overwrite the entire invitation.
    */
-  private handleSSEMessage(event: SSEvent): void {
+  private async handleSSEMessage(event: SSEvent): Promise<void> {
-    const data = JSON.parse(event.data) as { topic?: string; data?: unknown };
+    const invitation = this.parseInvitationFromSSEMessage(event);
-    if (data.topic === "invitation-updated") {
+    if (
-      const invitation = decodeExtendedJsonObject(data.data) as XOInvitation;
+      !invitation ||
-
+      invitation.invitationIdentifier !== this.data.invitationIdentifier
-      if (invitation.invitationIdentifier !== this.data.invitationIdentifier) {
+    ) {
       return;
     }
 
-      // Filter out commits that already exist (probably a faster way to do this. This is n^2)
+    // Filter out commits that already exist
-      const newCommits = this.mergeCommits(
+    const newCommits = this.mergeCommits(this.data.commits, invitation.commits);
-        this.data.commits,
+
-        invitation.commits,
+    try {
+      this.updateInvitationData(
+        stripLocalInvitationMetadata(
+          await this.engine.updateInvitation({
+            ...this.data,
+            ...invitation,
+            commits: newCommits,
+          }),
+        ),
       );
+    } catch (error) {
+      this.emit(
+        "error",
+        error instanceof Error ? error : new Error(String(error)),
+      );
+      this.updateInvitationData({ ...this.data, commits: newCommits });
+    }
 
-      // Set the new commits
+    await this.storage.set(this.data.invitationIdentifier, this.data);
-      this.data = { ...this.data, commits: newCommits };
+    await this.updateStatus();
-
-      // Calculate the new status of the invitation (fire-and-forget; handler is sync)
-      this.updateStatus().catch(() => {});
-
-      // Emit the updated event
     this.emit("invitation-updated", this.data);
   }
+
+  private parseInvitationFromSSEMessage(event: SSEvent): XOInvitation | null {
+    try {
+      const parsed = JSON.parse(event.data) as unknown;
+      const payload =
+        event.event === "invitation-updated"
+          ? this.unwrapInvitationUpdatedPayload(parsed)
+          : this.unwrapLegacyInvitationUpdatedPayload(parsed);
+
+      if (!payload) return null;
+
+      const decoded = decodeExtendedJsonObject(payload) as XOInvitation;
+      return stripLocalInvitationMetadata(
+        deserializeInvitation(serializeInvitation(decoded)),
+      );
+    } catch {
+      return null;
+    }
+  }
+
+  private unwrapInvitationUpdatedPayload(payload: unknown): unknown | null {
+    if (
+      payload &&
+      typeof payload === "object" &&
+      "topic" in payload &&
+      "data" in payload
+    ) {
+      return this.unwrapLegacyInvitationUpdatedPayload(payload);
+    }
+
+    return payload;
+  }
+
+  private unwrapLegacyInvitationUpdatedPayload(
+    payload: unknown,
+  ): unknown | null {
+    if (
+      payload &&
+      typeof payload === "object" &&
+      "topic" in payload &&
+      "data" in payload &&
+      payload.topic === "invitation-updated"
+    ) {
+      return payload.data;
+    }
+
+    return null;
   }
 
   /**
@@ -224,12 +364,12 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
   private async publishInvitation(
     invitation: XOInvitation = this.data,
   ): Promise<void> {
-    try {
+    this.syncServer.publishInvitation(invitation).catch((error) => {
-      await this.syncServer.publishInvitation(invitation);
+      this.emit(
-    } catch (err) {
+        "error",
-      // Emit the error event. We might want to throw? but we need a better way of handling errors in the invitation system because we need the invitation to successfully initialize.
+        error instanceof Error ? error : new Error(String(error)),
-      this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      );
-    }
+    });
   }
 
   /**
@@ -282,7 +422,9 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
   private async computeStatusInternal(): Promise<string> {
     let missingReqs;
     try {
-      const missingRequirements = await this.engine.listMissingRequirements(this.data.invitationIdentifier);
+      const missingRequirements = await this.engine.listMissingRequirements(
+        this.data.invitationIdentifier,
+      );
       missingReqs = missingRequirements.templateRequirements;
     } catch {
       return "unknown";
@@ -374,9 +516,18 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    * Update the status of the invitation and emit the new single-word status.
    */
   private async updateStatus(): Promise<void> {
-    const status = await this.computeStatus();
+    this.computeStatus()
+      .then((status) => {
         this.status = status;
         this.emit("invitation-status-changed", status);
+      })
+      .catch((error) => {
+        this.status = `error (${error instanceof Error ? error.message : String(error)})`;
+        this.emit(
+          "error",
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      });
   }
 
   /**
@@ -384,21 +535,42 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    */
   async accept(acceptParams?: InvitationParameters): Promise<void> {
     // Accept the invitation
-    this.data = await this.engine.acceptInvitation(this.data, acceptParams);
+    this.updateInvitationData(
+      await this.engine.acceptInvitation(this.data, acceptParams),
+    );
 
     // Sync the invitation to the sync server
-    this.publishInvitation(this.data);
+    await this.publishInvitation(this.data);
+
+    // Store the accepted invitation and notify reactive consumers.
+    await this.storage.set(this.data.invitationIdentifier, this.data);
+    this.emit("invitation-updated", this.data);
 
     // Update the status of the invitation
     await this.updateStatus();
   }
 
+  /**
+   * Accept the invitation once for this engine entity so future appends have a root commit.
+   */
+  async ensureAccepted(): Promise<void> {
+    const ownCommits = await this.engine.findOwnCommits(
+      this.data.invitationIdentifier,
+    );
+
+    if (ownCommits.length === 0) {
+      await this.accept();
+    }
+  }
+
   /**
    * Sign the invitation
    */
   async sign(): Promise<void> {
     // Sign the invitation
-    const signedInvitation = await this.engine.signInvitation(this.data.invitationIdentifier);
+    const signedInvitation = await this.engine.signInvitation(
+      this.data.invitationIdentifier,
+    );
 
     // Publish the signed invitation to the sync server
     this.publishInvitation(signedInvitation);
@@ -406,7 +578,7 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
     // Store the signed invitation in the storage
     await this.storage.set(this.data.invitationIdentifier, signedInvitation);
 
-    this.data = signedInvitation;
+    this.updateInvitationData(signedInvitation);
 
     // Update the status of the invitation
     await this.updateStatus();
@@ -417,9 +589,12 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    * @returns The transaction hash returned by the network after broadcast.
    */
   async broadcast(): Promise<string> {
-    const txHash = await this.engine.executeAction(this.data.invitationIdentifier, {
+    const txHash = await this.engine.executeAction(
+      this.data.invitationIdentifier,
+      {
         broadcastTransaction: true,
-    });
+      },
+    );
 
     await this.updateStatus();
 
@@ -434,14 +609,15 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    * Append a commit to the invitation
    */
   async append(data: InvitationParameters): Promise<void> {
-    try {
+    await this.ensureAccepted();
-      await this.engine.acceptInvitation(this.data);
-    } catch (err) {
-      // Literally do nothing here. We are just trying to accept the invitation in case we haven't already
-    }
 
     // Append the commit to the invitation
-    this.data = await this.engine.appendInvitation(this.data.invitationIdentifier, data);
+    this.updateInvitationData(
+      await this.engine.appendInvitation(
+        this.data.invitationIdentifier,
+        data,
+      ),
+    );
 
     // Sync the invitation to the sync server
     await this.publishInvitation(this.data);
@@ -520,8 +696,8 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
     const templates = await this.engine.listImportedTemplates();
 
     // For each template, we need to create a 2d array of all the outputs
-    const outputs = templates.map(template => {
+    const outputs = templates.map((template) => {
-      return Object.keys(template.outputs).map(output => {
+      return Object.keys(template.outputs).map((output) => {
         const templateIdentifier = generateTemplateIdentifier(template);
 
         return {
@@ -532,14 +708,18 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
     });
 
     // then, for each output, we need to get the spendable resources
-    const spendableResources = await Promise.all(outputs.flat().map(output => {
+    const spendableResources = await Promise.all(
+      outputs.flat().map((output) => {
         return this.engine.getSpendableResources(this.data, {
           templateIdentifier: output.templateIdentifier,
           outputIdentifier: output.outputIdentifier,
         });
-    }));
+      }),
+    );
 
-    const unspentOutputs = spendableResources.flatMap(resource => resource.unspentOutputs);
+    const unspentOutputs = spendableResources.flatMap(
+      (resource) => resource.unspentOutputs,
+    );
 
     // Update the status of the invitation
     await this.updateStatus();
@@ -641,9 +821,11 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
       );
 
       // Compile the CashAssembly expression to get the value satoshis (It handles the variable replacement for us)
-      const valueSatoshis = compileCashAssemblyString(
+      const valueSatoshis = compileCashAssemblyString({
-        { cashAssemblyText: String(valueSatoshisExpression), variables: formattedVariables, evaluationDecodeMode: 'bigint' },
+        cashAssemblyText: String(valueSatoshisExpression),
-      );
+        variables: formattedVariables,
+        evaluationDecodeMode: "bigint",
+      });
 
       // Return the value satoshis as a bigint
       // TODO: Check this of a vulnerability or crash - I assume there might be one if someone made the `valueSatoshis` a malicious expression
@@ -699,7 +881,7 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
     for (const output of outputs) {
       if (typeof output === "string") {
         const sats = await this.getSatsOut(output);
-        totalSats += sats
+        totalSats += sats;
       } else {
         const sats = await this.getSatsOut(output.output);
         totalSats += sats;
@@ -708,4 +890,21 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
 
     return totalSats;
   }
+
+  /**
+   * Removes the invitation from the Local SQLite db as well as the Engine's internal DB
+   * NOTE: This uses methods that are marked "DANGEROUSLY" inside the engine and behaviour may change
+   */ 
+  public async delete() {
+    // Remove the invitation from our local db
+    this.storage.remove(this.data.invitationIdentifier);
+
+    // Remove the invitation from the engine's internal db
+    await this.engine.DANGEROUS_deleteStoredInvitation(this.data.invitationIdentifier);
+
+    this.emit("invitation-removed", this.data.invitationIdentifier);
+
+    // Update the status of the invitation
+    await this.updateStatus();
+  }
 }

src/services/rates.ts

@@ -1,16 +1,14 @@
-import { OracleClient } from '@generalprotocols/oracle-client';
+import { OracleClient } from "@generalprotocols/oracle-client";
-import { EventEmitter } from '../utils/event-emitter.js';
+import { EventEmitter } from "../utils/event-emitter.js";
-import {
+import { type RatesEventMap } from "../utils/rates/base-rates.js";
-  type RatesEventMap,
+import { RatesOracle } from "../utils/rates/rates-oracles.js";
-} from '../utils/rates/base-rates.js';
+import { SettingsService } from "./settings.js";
-import { RatesOracle } from '../utils/rates/rates-oracles.js';
-import { SettingsService } from './settings.js';
 
 /**
  * Event map emitted by {@link RatesService}.
  */
 export type RatesServiceEventMap = {
-  'rate-updated': {
+  "rate-updated": {
     numeratorUnitCode: string;
     denominatorUnitCode: string;
     price: number;
@@ -39,8 +37,8 @@ export interface RatesAdapter {
   listPairs(): Promise<Set<string>>;
   formatCurrency(amount: number, targetCurrency: string): string;
   on(
-    type: 'rateUpdated',
+    type: "rateUpdated",
-    listener: (detail: RatesEventMap['rateUpdated']) => void,
+    listener: (detail: RatesEventMap["rateUpdated"]) => void,
   ): () => void;
 }
 
@@ -96,7 +94,7 @@ export class RatesService extends EventEmitter<RatesServiceEventMap> {
     }
     this.started = true;
 
-    this.unsubscribeFromAdapter = this.adapter.on('rateUpdated', (event) => {
+    this.unsubscribeFromAdapter = this.adapter.on("rateUpdated", (event) => {
       this.handleRateUpdated(event);
     });
 
@@ -145,9 +143,9 @@ export class RatesService extends EventEmitter<RatesServiceEventMap> {
    */
   public convertBchToFiat(
     satoshis: bigint,
-    targetCurrency: string = 'USD',
+    targetCurrency: string = "USD",
   ): number | null {
-    const rate = this.getRate(targetCurrency, 'BCH');
+    const rate = this.getRate(targetCurrency, "BCH");
     if (rate === null) {
       return null;
     }
@@ -161,7 +159,7 @@ export class RatesService extends EventEmitter<RatesServiceEventMap> {
    */
   public formatBchToFiat(
     satoshis: bigint,
-    targetCurrency: string = 'USD',
+    targetCurrency: string = "USD",
   ): string | null {
     const normalizedCurrency = targetCurrency.toUpperCase();
     const amount = this.convertBchToFiat(satoshis, normalizedCurrency);
@@ -195,7 +193,7 @@ export class RatesService extends EventEmitter<RatesServiceEventMap> {
   /**
    * Handles normalized updates from the underlying adapter.
    */
-  private handleRateUpdated(event: RatesEventMap['rateUpdated']): void {
+  private handleRateUpdated(event: RatesEventMap["rateUpdated"]): void {
     const numeratorUnitCode = event.numeratorUnitCode.toUpperCase();
     const denominatorUnitCode = event.denominatorUnitCode.toUpperCase();
     const pair = this.getPairKey(numeratorUnitCode, denominatorUnitCode);
@@ -206,7 +204,7 @@ export class RatesService extends EventEmitter<RatesServiceEventMap> {
       updatedAt,
     });
 
-    this.emit('rate-updated', {
+    this.emit("rate-updated", {
       numeratorUnitCode,
       denominatorUnitCode,
       price: event.price,

src/services/settings.ts

@@ -32,7 +32,7 @@ const DEFAULT_SETTINGS: SettingsData = {
 /**
  * Handles loading, migrating, and persisting wallet settings.
  *
- * The backing file is `~/.config/xo-cli/.wallet`. Historically it stored a raw
+ * The backing file is `<XO_CONFIG_DIR>/.wallet`. Historically it stored a raw
  * mnemonic reference string. This service migrates that legacy format to JSON:
  * `{ "default-mnemonic": "<value>", "currency": "USD" }`.
  */
@@ -168,7 +168,9 @@ export class SettingsService extends EventEmitter<SettingsServiceEventMap> {
       return normalized;
     }
 
-    const maybeMnemonic = (input as Record<string, unknown>)["default-mnemonic"];
+    const maybeMnemonic = (input as Record<string, unknown>)[
+      "default-mnemonic"
+    ];
     if (typeof maybeMnemonic === "string" && maybeMnemonic.trim().length > 0) {
       normalized["default-mnemonic"] = maybeMnemonic.trim();
     }

src/templates/vending-machine.ts

@@ -1,4 +1,4 @@
-import type { XOTemplate } from '@xo-cash/types';
+import type { XOTemplate } from "@xo-cash/types";
 
 /**
  * Vending machine payment template.
@@ -7,104 +7,106 @@ import type { XOTemplate } from '@xo-cash/types';
  * customer funds and signs the composable transaction.
  */
 export const vendingMachineTemplate: XOTemplate = {
-    $schema: 'https://libauth.org/schemas/wallet-template-v0.schema.json',
+  $schema: "https://libauth.org/schemas/wallet-template-v0.schema.json",
-    name: 'Vending Machine',
+  name: "Vending Machine",
-    description: 'Purchase items from a vending machine with an itemized receipt.',
+  description:
-    icon: 'wallet',
+    "Purchase items from a vending machine with an itemized receipt.",
-    version: '1',
+  icon: "wallet",
-    supported: ['BCH_2023_05', 'BCH_2024_05', 'BCH_2025_05', 'BCH_2026_05'],
+  version: "1",
+  supported: ["BCH_2023_05", "BCH_2024_05", "BCH_2025_05", "BCH_2026_05"],
 
   defaults: {
     change: {
-            output: 'changeOutput',
+      output: "changeOutput",
-            role: 'merchant',
+      role: "merchant",
-            generate: ['merchantKey'],
+      generate: ["merchantKey"],
     },
   },
 
   roles: {
     merchant: {
-            name: 'Merchant',
+      name: "Merchant",
-            description: 'The vending machine operator receiving payment.',
+      description: "The vending machine operator receiving payment.",
-            icon: 'owner',
+      icon: "owner",
     },
     customer: {
-            name: 'Customer',
+      name: "Customer",
-            description: 'The customer paying for items.',
+      description: "The customer paying for items.",
-            icon: 'sender',
+      icon: "sender",
     },
   },
 
   start: [
     {
-            action: 'purchaseItems',
+      action: "purchaseItems",
-            role: 'merchant',
+      role: "merchant",
-            generate: ['merchantKey'],
+      generate: ["merchantKey"],
     },
   ],
 
   actions: {
     purchaseItems: {
-            name: 'Purchase Items',
+      name: "Purchase Items",
-            description: 'Purchase: $(<receiptSummary>) for $(<totalSatoshis>) sats',
+      description: "Purchase: $(<receiptSummary>) for $(<totalSatoshis>) sats",
-            icon: 'request',
+      icon: "request",
 
       roles: {
         merchant: {
-                    name: 'Sell Items',
+          name: "Sell Items",
-                    description: 'Receive payment for $(<receiptSummary>)',
+          description: "Receive payment for $(<receiptSummary>)",
-                    icon: 'request',
+          icon: "request",
           requirements: {
-                        secrets: ['merchantKey'],
+            secrets: ["merchantKey"],
             variables: [
-                            'totalSatoshis',
+              "totalSatoshis",
-                            'orderId',
+              "orderId",
-                            'merchantName',
+              "merchantName",
-                            'receiptSummary',
+              "receiptSummary",
-                            'lineItemsJson',
+              "lineItemsJson",
             ],
           },
         },
         customer: {
-                    name: 'Pay',
+          name: "Pay",
-                    description: 'Pay $(<totalSatoshis>) sats for $(<receiptSummary>)',
+          description: "Pay $(<totalSatoshis>) sats for $(<receiptSummary>)",
-                    icon: 'send',
+          icon: "send",
           requirements: {},
         },
       },
 
       requirements: {
         participants: [
-                    { role: 'merchant', slots: { min: 1, max: 1 } },
+          { role: "merchant", slots: { min: 1, max: 1 } },
-                    { role: 'customer', slots: { min: 1 } },
+          { role: "customer", slots: { min: 1 } },
         ],
       },
 
-            transaction: 'purchaseItemsTransaction',
+      transaction: "purchaseItemsTransaction",
     },
   },
 
   transactions: {
     purchaseItemsTransaction: {
-            name: 'Vending Purchase',
+      name: "Vending Purchase",
-            description: 'Order $(<orderId>): $(<receiptSummary>)',
+      description: "Order $(<orderId>): $(<receiptSummary>)",
-            icon: 'request',
+      icon: "request",
 
       roles: {
         merchant: {
-                    name: 'Received Payment',
+          name: "Received Payment",
-                    description: 'Received $(<totalSatoshis>) sats from $(<merchantName>) sale',
+          description:
-                    icon: 'receive',
+            "Received $(<totalSatoshis>) sats from $(<merchantName>) sale",
+          icon: "receive",
         },
         customer: {
-                    name: 'Sent Payment',
+          name: "Sent Payment",
-                    description: 'Paid $(<totalSatoshis>) sats for $(<receiptSummary>)',
+          description: "Paid $(<totalSatoshis>) sats for $(<receiptSummary>)",
-                    icon: 'send',
+          icon: "send",
         },
       },
 
       inputs: [],
-            outputs: [{ output: 'purchaseOutput' }],
+      outputs: [{ output: "purchaseOutput" }],
       version: 2,
       locktime: 0,
       composable: true,
@@ -116,41 +118,42 @@ export const vendingMachineTemplate: XOTemplate = {
 
   outputs: {
     changeOutput: {
-            name: 'Change',
+      name: "Change",
-            description: 'Funds returned as change.',
+      description: "Funds returned as change.",
-            icon: 'receive',
+      icon: "receive",
-            lockingScript: 'merchantReceivingLockingScript',
+      lockingScript: "merchantReceivingLockingScript",
     },
     purchaseOutput: {
-            name: 'Purchase Payment',
+      name: "Purchase Payment",
-            description: '$(<totalSatoshis>) sats to $(<merchantName>)',
+      description: "$(<totalSatoshis>) sats to $(<merchantName>)",
-            icon: 'request',
+      icon: "request",
 
       roles: {
         merchant: {
-                    name: 'Payment Received',
+          name: "Payment Received",
-                    description: 'Received $(<totalSatoshis>) sats for $(<receiptSummary>)',
+          description:
+            "Received $(<totalSatoshis>) sats for $(<receiptSummary>)",
         },
         customer: {
-                    name: 'Payment Sent',
+          name: "Payment Sent",
-                    description: 'Sent $(<totalSatoshis>) sats for $(<receiptSummary>)',
+          description: "Sent $(<totalSatoshis>) sats for $(<receiptSummary>)",
         },
       },
 
-            lockingScript: 'merchantReceivingLockingScript',
+      lockingScript: "merchantReceivingLockingScript",
-            valueSatoshis: '$(<totalSatoshis>)',
+      valueSatoshis: "$(<totalSatoshis>)",
       token: null,
     },
   },
 
   lockingScripts: {
     merchantReceivingLockingScript: {
-            name: 'Merchant Receive',
+      name: "Merchant Receive",
-            description: 'Funds received by the vending machine merchant.',
+      description: "Funds received by the vending machine merchant.",
-            icon: 'address',
+      icon: "address",
-            lockingType: 'p2pkh',
+      lockingType: "p2pkh",
-            lockingBytecode: 'lockMerchantP2PKH',
+      lockingBytecode: "lockMerchantP2PKH",
-            unlockingBytecode: 'unlockMerchantP2PKH',
+      unlockingBytecode: "unlockMerchantP2PKH",
       actions: [],
       state: { variables: [], secrets: [] },
       balance: {},
@@ -158,7 +161,7 @@ export const vendingMachineTemplate: XOTemplate = {
         merchant: {
           state: {
             variables: [],
-                        secrets: ['merchantKey'],
+            secrets: ["merchantKey"],
           },
           actions: [],
           balance: {
@@ -174,95 +177,98 @@ export const vendingMachineTemplate: XOTemplate = {
 
   scripts: {
     lockMerchantP2PKH:
-            'OP_DUP OP_HASH160 <$(<merchantKey.public_key> OP_HASH160)> OP_EQUALVERIFY OP_CHECKSIG',
+      "OP_DUP OP_HASH160 <$(<merchantKey.public_key> OP_HASH160)> OP_EQUALVERIFY OP_CHECKSIG",
     unlockMerchantP2PKH:
-            '<merchantKey.schnorr_signature.all_outputs> <merchantKey.public_key>',
+      "<merchantKey.schnorr_signature.all_outputs> <merchantKey.public_key>",
   },
 
   constants: {
     dustLimit: {
-            name: 'Dust Limit',
+      name: "Dust Limit",
-            description: 'Minimum satoshis for P2PKH outputs.',
+      description: "Minimum satoshis for P2PKH outputs.",
-            type: 'integer',
+      type: "integer",
       value: 546,
     },
   },
 
   variables: {
     merchantKey: {
-            name: 'Merchant Private Key',
+      name: "Merchant Private Key",
-            description: 'Private key for the vending machine merchant wallet.',
+      description: "Private key for the vending machine merchant wallet.",
-            type: 'bytes',
+      type: "bytes",
-            hint: 'private_key',
+      hint: "private_key",
     },
     totalSatoshis: {
-            name: 'Total Price',
+      name: "Total Price",
-            description: 'Total purchase price in satoshis',
+      description: "Total purchase price in satoshis",
-            type: 'integer',
+      type: "integer",
-            hint: 'satoshis',
+      hint: "satoshis",
     },
     orderId: {
-            name: 'Order ID',
+      name: "Order ID",
-            description: 'Unique order identifier',
+      description: "Unique order identifier",
-            type: 'string',
+      type: "string",
     },
     merchantName: {
-            name: 'Merchant Name',
+      name: "Merchant Name",
-            description: 'Display name of the vending machine',
+      description: "Display name of the vending machine",
-            type: 'string',
+      type: "string",
     },
     receiptSummary: {
-            name: 'Receipt Summary',
+      name: "Receipt Summary",
-            description: 'Human-readable list of purchased items',
+      description: "Human-readable list of purchased items",
-            type: 'string',
+      type: "string",
     },
     lineItemsJson: {
-            name: 'Line Items',
+      name: "Line Items",
-            description: 'JSON-encoded line items for the purchase',
+      description: "JSON-encoded line items for the purchase",
-            type: 'string',
+      type: "string",
     },
   },
 
   icons: [
-        { name: 'wallet', hash: '0000000000000000000000' },
+    { name: "wallet", hash: "0000000000000000000000" },
-        { name: 'owner', hash: '0000000000000000000000' },
+    { name: "owner", hash: "0000000000000000000000" },
-        { name: 'sender', hash: '0000000000000000000000' },
+    { name: "sender", hash: "0000000000000000000000" },
-        { name: 'request', hash: '0000000000000000000000' },
+    { name: "request", hash: "0000000000000000000000" },
-        { name: 'receive', hash: '0000000000000000000000' },
+    { name: "receive", hash: "0000000000000000000000" },
-        { name: 'send', hash: '0000000000000000000000' },
+    { name: "send", hash: "0000000000000000000000" },
   ],
 
   scenarios: [
     {
-            name: 'purchase items happy path',
+      name: "purchase items happy path",
-            description: 'Merchant requests payment for vending machine items.',
+      description: "Merchant requests payment for vending machine items.",
-            action: 'purchaseItems',
+      action: "purchaseItems",
       roles: [
         {
-                    role: 'merchant',
+          role: "merchant",
           values: {
             generated: {
-                            merchantKey: 'KyRQa5pEXuzVcDwnXRLpYAascjchQW5DoxVRMbj4DTxS83573mz8',
+              merchantKey:
+                "KyRQa5pEXuzVcDwnXRLpYAascjchQW5DoxVRMbj4DTxS83573mz8",
             },
             variables: {
               totalSatoshis: 3500,
-                            orderId: 'order-demo-1',
+              orderId: "order-demo-1",
-                            merchantName: 'XO Snack Machine',
+              merchantName: "XO Snack Machine",
-                            receiptSummary: '2× Cola, 1× Chips',
+              receiptSummary: "2× Cola, 1× Chips",
-                            lineItemsJson: '[{"name":"Cola","qty":2},{"name":"Chips","qty":1}]',
+              lineItemsJson:
+                '[{"name":"Cola","qty":2},{"name":"Chips","qty":1}]',
             },
             secrets: {},
             inputs: [],
             outputs: [
               {
-                                lockingBytecode: '76a91475c715ecb74178fe87933e57e947e5e92d904b8188ac',
+                lockingBytecode:
+                  "76a91475c715ecb74178fe87933e57e947e5e92d904b8188ac",
                 valueSatoshis: 3500,
               },
             ],
           },
         },
         {
-                    role: 'customer',
+          role: "customer",
           values: {
             generated: {},
             variables: {},

src/templates/wrap-template.ts

@@ -1,88 +1,87 @@
-import type { XOTemplate } from '@xo-cash/types';
+import type { XOTemplate } from "@xo-cash/types";
 
 export const wrapBCHTemplate: XOTemplate = {
-	$schema: 'https://libauth.org/schemas/wallet-template-v0.schema.json',
+  $schema: "https://libauth.org/schemas/wallet-template-v0.schema.json",
 
-	name: 'Wrapped BCH',
+  name: "Wrapped BCH",
-	description: 'Convert between BCH and wBCH tokens.',
+  description: "Convert between BCH and wBCH tokens.",
-	icon: 'wrap',
+  icon: "wrap",
 
-	version: '1',
+  version: "1",
-	supported: ['BCH_2023_05', 'BCH_2024_05', 'BCH_2025_05', 'BCH_2026_05'],
+  supported: ["BCH_2023_05", "BCH_2024_05", "BCH_2025_05", "BCH_2026_05"],
 
   roles: {
     user: {
-			name: 'User',
+      name: "User",
-			description: 'The person wrapping or unwrapping BCH.',
+      description: "The person wrapping or unwrapping BCH.",
-			icon: 'user',
+      icon: "user",
     },
   },
 
   start: [
     {
-			action: 'wrap',
+      action: "wrap",
-			role: 'user',
+      role: "user",
     },
     {
-			action: 'unwrap',
+      action: "unwrap",
-			role: 'user',
+      role: "user",
     },
   ],
 
   actions: {
     wrap: {
-			name: 'Wrap BCH',
+      name: "Wrap BCH",
-			description: 'Convert BCH into wBCH tokens.',
+      description: "Convert BCH into wBCH tokens.",
-			icon: 'wrap',
+      icon: "wrap",
 
       roles: {
         user: {
           requirements: {
-						variables: ['amountToWrap', 'recipientLockingScript'],
+            variables: ["amountToWrap", "recipientLockingScript"],
           },
         },
       },
 
       requirements: {
-				participants: [{ role: 'user', slots: { min: 1, max: 1 } }],
+        participants: [{ role: "user", slots: { min: 1, max: 1 } }],
       },
 
-			transaction: 'wrapTransaction',
+      transaction: "wrapTransaction",
     },
 
     unwrap: {
-			name: 'Unwrap wBCH',
+      name: "Unwrap wBCH",
-			description: 'Convert wBCH tokens back into BCH.',
+      description: "Convert wBCH tokens back into BCH.",
-			icon: 'unwrap',
+      icon: "unwrap",
 
       roles: {
         user: {
           requirements: {
-						variables: ['amountToUnwrap', 'recipientLockingScript'],
+            variables: ["amountToUnwrap", "recipientLockingScript"],
           },
         },
       },
 
       requirements: {
-				participants: [{ role: 'user', slots: { min: 1, max: 1 } }],
+        participants: [{ role: "user", slots: { min: 1, max: 1 } }],
       },
 
-			transaction: 'unwrapTransaction',
+      transaction: "unwrapTransaction",
     },
   },
 
   transactions: {
     wrapTransaction: {
-			name: 'Wrapped BCH',
+      name: "Wrapped BCH",
-			description: 'Wrapped $(<amountToWrap> <satoshisPerBCH> OP_DIV).$(<amountToWrap> <satoshisPerBCH> OP_MOD) BCH into wBCH tokens.',
+      description:
-			icon: 'wrap',
+        "Wrapped $(<amountToWrap> <satoshisPerBCH> OP_DIV).$(<amountToWrap> <satoshisPerBCH> OP_MOD) BCH into wBCH tokens.",
+      icon: "wrap",
 
-			inputs: [
+      inputs: [{ input: "covenantInput", inputIndex: 0 }],
-				{ input: 'covenantInput', inputIndex: 0 },
-			],
       outputs: [
-				{ output: 'covenantOutput', outputIndex: 0 },
+        { output: "covenantOutput", outputIndex: 0 },
-				{ output: 'wrappedTokensOutput', outputIndex: undefined },
+        { output: "wrappedTokensOutput", outputIndex: undefined },
       ],
 
       version: 2,
@@ -91,16 +90,15 @@ export const wrapBCHTemplate: XOTemplate = {
     },
 
     unwrapTransaction: {
-			name: 'Unwrapped wBCH',
+      name: "Unwrapped wBCH",
-			description: 'Unwrapped $(<amountToUnwrap> <satoshisPerBCH> OP_DIV).$(<amountToUnwrap> <satoshisPerBCH> OP_MOD) wBCH tokens back into BCH.',
+      description:
-			icon: 'unwrap',
+        "Unwrapped $(<amountToUnwrap> <satoshisPerBCH> OP_DIV).$(<amountToUnwrap> <satoshisPerBCH> OP_MOD) wBCH tokens back into BCH.",
+      icon: "unwrap",
 
-			inputs: [
+      inputs: [{ input: "covenantInput", inputIndex: 0 }],
-				{ input: 'covenantInput', inputIndex: 0 },
-			],
       outputs: [
-				{ output: 'covenantOutput', outputIndex: 0 },
+        { output: "covenantOutput", outputIndex: 0 },
-				{ output: 'unwrappedSatoshisOutput', outputIndex: undefined },
+        { output: "unwrappedSatoshisOutput", outputIndex: undefined },
       ],
 
       version: 2,
@@ -111,22 +109,23 @@ export const wrapBCHTemplate: XOTemplate = {
 
   outputs: {
     covenantOutput: {
-			name: 'wBCH Covenant',
+      name: "wBCH Covenant",
-			description: 'Holds BCH and wBCH tokens that can be freely converted.',
+      description: "Holds BCH and wBCH tokens that can be freely converted.",
-			icon: 'contract',
+      icon: "contract",
 
-			lockingScript: 'wrapBCHLockingScript',
+      lockingScript: "wrapBCHLockingScript",
     },
 
     wrappedTokensOutput: {
-			name: 'Wrapped wBCH',
+      name: "Wrapped wBCH",
-			description: 'Wrapped $(<amountToWrap> <satoshisPerBCH> OP_DIV).$(<amountToWrap> <satoshisPerBCH> OP_MOD) wBCH tokens.',
+      description:
-			icon: 'receive',
+        "Wrapped $(<amountToWrap> <satoshisPerBCH> OP_DIV).$(<amountToWrap> <satoshisPerBCH> OP_MOD) wBCH tokens.",
+      icon: "receive",
 
-			valueSatoshis: '$(<amountToWrap>)',
+      valueSatoshis: "$(<amountToWrap>)",
       token: {
-				category: '$(<wbchTokenCategory>)',
+        category: "$(<wbchTokenCategory>)",
-				amount: '$(<amountToWrap>)',
+        amount: "$(<amountToWrap>)",
         nft: null,
       },
 
@@ -141,15 +140,16 @@ export const wrapBCHTemplate: XOTemplate = {
         },
       },
 
-			lockingScript: '$(<recipientLockingScript>)',
+      lockingScript: "$(<recipientLockingScript>)",
     },
 
     unwrappedSatoshisOutput: {
-			name: 'Unwrapped BCH',
+      name: "Unwrapped BCH",
-			description: 'Unwrapped $(<amountToUnwrap> <satoshisPerBCH> OP_DIV).$(<amountToUnwrap> <satoshisPerBCH> OP_MOD) BCH.',
+      description:
-			icon: 'receive',
+        "Unwrapped $(<amountToUnwrap> <satoshisPerBCH> OP_DIV).$(<amountToUnwrap> <satoshisPerBCH> OP_MOD) BCH.",
+      icon: "receive",
 
-			valueSatoshis: '$(<amountToUnwrap>)',
+      valueSatoshis: "$(<amountToUnwrap>)",
       token: null,
 
       roles: {
@@ -163,32 +163,32 @@ export const wrapBCHTemplate: XOTemplate = {
         },
       },
 
-			lockingScript: '$(<recipientLockingScript>)',
+      lockingScript: "$(<recipientLockingScript>)",
     },
   },
 
   inputs: {
     covenantInput: {
-			name: 'wBCH Covenant',
+      name: "wBCH Covenant",
-			description: 'The covenant being updated.',
+      description: "The covenant being updated.",
-			icon: 'contract',
+      icon: "contract",
 
-			unlockingScript: 'unlockCovenant',
+      unlockingScript: "unlockCovenant",
     },
   },
 
   lockingScripts: {
     wrapBCHLockingScript: {
-			name: 'wBCH Covenant',
+      name: "wBCH Covenant",
-			description: 'Holds BCH and wBCH tokens that can be freely converted.',
+      description: "Holds BCH and wBCH tokens that can be freely converted.",
-			icon: 'contract',
+      icon: "contract",
 
-			lockingType: 'p2sh',
+      lockingType: "p2sh",
-			lockingBytecode: 'wrapBCHLockingBytecode',
+      lockingBytecode: "wrapBCHLockingBytecode",
 
       actions: [
-				{ action: 'wrap', role: 'user' },
+        { action: "wrap", role: "user" },
-				{ action: 'unwrap', role: 'user' },
+        { action: "unwrap", role: "user" },
       ],
 
       state: {
@@ -204,63 +204,67 @@ export const wrapBCHTemplate: XOTemplate = {
   },
 
   scripts: {
-		enforceCovenantPersists: 'OP_INPUTINDEX OP_DUP OP_OUTPUTBYTECODE OP_SWAP OP_UTXOBYTECODE OP_EQUAL OP_VERIFY',
+    enforceCovenantPersists:
-		enforceTokenCategoryPreserved: 'OP_INPUTINDEX OP_DUP OP_OUTPUTTOKENCATEGORY OP_SWAP OP_UTXOTOKENCATEGORY OP_EQUAL OP_VERIFY',
+      "OP_INPUTINDEX OP_DUP OP_OUTPUTBYTECODE OP_SWAP OP_UTXOBYTECODE OP_EQUAL OP_VERIFY",
-		enforceValueTokenSumConserved: 'OP_INPUTINDEX OP_UTXOVALUE OP_INPUTINDEX OP_UTXOTOKENAMOUNT OP_ADD OP_INPUTINDEX OP_OUTPUTVALUE OP_INPUTINDEX OP_OUTPUTTOKENAMOUNT OP_ADD OP_EQUAL OP_VERIFY',
+    enforceTokenCategoryPreserved:
+      "OP_INPUTINDEX OP_DUP OP_OUTPUTTOKENCATEGORY OP_SWAP OP_UTXOTOKENCATEGORY OP_EQUAL OP_VERIFY",
+    enforceValueTokenSumConserved:
+      "OP_INPUTINDEX OP_UTXOVALUE OP_INPUTINDEX OP_UTXOTOKENAMOUNT OP_ADD OP_INPUTINDEX OP_OUTPUTVALUE OP_INPUTINDEX OP_OUTPUTTOKENAMOUNT OP_ADD OP_EQUAL OP_VERIFY",
 
     // Direct script references — introspection opcodes must not use $(...) evaluations
     // because those are evaluated at compile time without transaction context.
-		wrapBCHLockingBytecode: 'enforceCovenantPersists enforceTokenCategoryPreserved enforceValueTokenSumConserved',
+    wrapBCHLockingBytecode:
-		unlockCovenant: '',
+      "enforceCovenantPersists enforceTokenCategoryPreserved enforceValueTokenSumConserved",
+    unlockCovenant: "",
   },
 
   constants: {
     wbchTokenCategory: {
-			name: 'wBCH Token Category',
+      name: "wBCH Token Category",
-			description: 'The official token category for Wrapped BCH.',
+      description: "The official token category for Wrapped BCH.",
-			type: 'bytes',
+      type: "bytes",
-			value: 'ff4d6e4b90aa8158d39c5dc874fd9411af1ac3b5ed6f354755e8362a0d02c6b3',
+      value: "ff4d6e4b90aa8158d39c5dc874fd9411af1ac3b5ed6f354755e8362a0d02c6b3",
     },
     satoshisPerBCH: {
-			name: 'Satoshis per BCH',
+      name: "Satoshis per BCH",
-			description: 'Used to display amounts in BCH with decimals.',
+      description: "Used to display amounts in BCH with decimals.",
-			type: 'integer',
+      type: "integer",
       value: 100000000,
     },
     tokenDust: {
-			name: 'Token Dust Limit',
+      name: "Token Dust Limit",
-			description: 'Minimal satoshis required for a token-bearing output.',
+      description: "Minimal satoshis required for a token-bearing output.",
-			type: 'integer',
+      type: "integer",
       value: 1000,
     },
   },
 
   variables: {
     amountToWrap: {
-			name: 'Amount to Wrap',
+      name: "Amount to Wrap",
-			description: 'How much BCH to convert to wBCH (in satoshis).',
+      description: "How much BCH to convert to wBCH (in satoshis).",
-			type: 'integer',
+      type: "integer",
-			hint: 'satoshis',
+      hint: "satoshis",
     },
     amountToUnwrap: {
-			name: 'Amount to Unwrap',
+      name: "Amount to Unwrap",
-			description: 'How much wBCH to convert back to BCH (in satoshis).',
+      description: "How much wBCH to convert back to BCH (in satoshis).",
-			type: 'integer',
+      type: "integer",
-			hint: 'satoshis',
+      hint: "satoshis",
     },
     recipientLockingScript: {
-			name: 'Destination',
+      name: "Destination",
-			description: 'Where to receive your BCH or wBCH tokens.',
+      description: "Where to receive your BCH or wBCH tokens.",
-			type: 'bytes',
+      type: "bytes",
-			hint: 'lockingScript',
+      hint: "lockingScript",
     },
   },
 
   icons: [
-		{ name: 'wrap', hash: '0000000000000000000000' },
+    { name: "wrap", hash: "0000000000000000000000" },
-		{ name: 'unwrap', hash: '0000000000000000000000' },
+    { name: "unwrap", hash: "0000000000000000000000" },
-		{ name: 'user', hash: '0000000000000000000000' },
+    { name: "user", hash: "0000000000000000000000" },
-		{ name: 'contract', hash: '0000000000000000000000' },
+    { name: "contract", hash: "0000000000000000000000" },
-		{ name: 'receive', hash: '0000000000000000000000' },
+    { name: "receive", hash: "0000000000000000000000" },
   ],
 };

src/tui/App.tsx

@@ -17,7 +17,6 @@ import { WalletStateScreen } from './screens/WalletState.js';
 import { TemplateListScreen } from './screens/TemplateList.js';
 import { ActionWizardScreen } from './screens/action-wizard/ActionWizardScreen.js';
 import { InvitationScreen } from './screens/invitations/InvitationScreen.js';
-import { TransactionScreen } from './screens/Transaction.js';
 
 import { MessageDialog } from './components/Dialog.js';
 
@@ -45,8 +44,6 @@ function Router(): React.ReactElement {
       return <ActionWizardScreen />;
     case 'invitations':
       return <InvitationScreen />;
-    case 'transaction':
-      return <TransactionScreen />;
     default:
       return <Text color={colors.error}>Unknown screen: {screen}</Text>;
   }

src/tui/hooks/useInvitations.tsx

@@ -10,7 +10,7 @@ import { useAppContext } from './useAppContext.js';
 
 /**
  * Get all invitations reactively.
- * Re-renders when invitations are added or removed.
+ * Re-renders when invitations are added, removed, or updated.
  */
 export function useInvitations(): Invitation[] {
   const { appService } = useAppContext();
@@ -21,26 +21,22 @@ export function useInvitations(): Invitation[] {
         return () => {};
       }
 
-      // Subscribe to invitation list changes
+      appService.on('wallet-state-changed', callback);
-      const onAdded = () => callback();
-      const onRemoved = () => callback();
-
-      appService.on('invitation-added', onAdded);
-      appService.on('invitation-removed', onRemoved);
 
       return () => {
-        appService.off('invitation-added', onAdded);
+        appService.off('wallet-state-changed', callback);
-        appService.off('invitation-removed', onRemoved);
       };
     },
     [appService]
   );
 
   const getSnapshot = useCallback(() => {
-    return appService?.invitations ?? [];
+    return appService?.invitationsRevision ?? 0;
   }, [appService]);
 
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const revision = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  return useMemo(() => [...(appService?.invitations ?? [])], [appService, revision]);
 }
 
 /**
@@ -56,36 +52,32 @@ export function useInvitation(invitationId: string | null): Invitation | null {
         return () => {};
       }
 
-      // Find the invitation instance
+      const onWalletStateChanged = ({
-      const invitation = appService.invitations.find(
+        invitationIdentifier,
-        (inv) => inv.data.invitationIdentifier === invitationId
+      }: {
-      );
+        invitationIdentifier: string;
-
+      }) => {
-      if (!invitation) {
+        if (invitationIdentifier === invitationId) {
-        return () => {};
+          callback();
         }
-
+      };
-      // Subscribe to this specific invitation's updates
+      appService.on('wallet-state-changed', onWalletStateChanged);
-      const onUpdated = () => callback();
-      const onStatusChanged = () => callback();
-
-      invitation.on('invitation-updated', onUpdated);
-      invitation.on('invitation-status-changed', onStatusChanged);
-
-      // Also subscribe to list changes in case the invitation is removed
-      const onRemoved = () => callback();
-      appService.on('invitation-removed', onRemoved);
 
       return () => {
-        invitation.off('invitation-updated', onUpdated);
+        appService.off('wallet-state-changed', onWalletStateChanged);
-        invitation.off('invitation-status-changed', onStatusChanged);
-        appService.off('invitation-removed', onRemoved);
       };
     },
     [appService, invitationId]
   );
 
   const getSnapshot = useCallback(() => {
+    return appService && invitationId
+      ? appService.getInvitationRevision(invitationId)
+      : 0;
+  }, [appService, invitationId]);
+
+  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
   if (!appService || !invitationId) {
     return null;
   }
@@ -95,9 +87,6 @@ export function useInvitation(invitationId: string | null): Invitation | null {
       (inv) => inv.data.invitationIdentifier === invitationId
     ) ?? null
   );
-  }, [appService, invitationId]);
-
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
 
 /**
@@ -109,7 +98,7 @@ export function useInvitationData(invitationId: string | null): XOInvitation | n
 
   return useMemo(() => {
     return invitation?.data ?? null;
-  }, [invitation?.data.invitationIdentifier, invitation?.data.commits?.length]);
+  }, [invitation?.data]);
 }
 
 /**

src/tui/screens/SeedInput.tsx

@@ -44,7 +44,7 @@ interface MnemonicFileEntry {
 type FocusSection = 'files' | 'input' | 'saveCheckbox' | 'generateRandomSeed' | 'button';
 
 /**
- * Reads mnemonic-* files from ~/.config/xo-cli/mnemonics/ (same as xo-cli),
+ * Reads mnemonic-* files from the configured mnemonics directory (same as xo-cli),
  * then from cwd for legacy installs. Parses each as a BCHMnemonicURL.
  */
 function loadMnemonicFiles(): MnemonicFileEntry[] {
@@ -101,7 +101,7 @@ export function SeedInputScreen(): React.ReactElement {
   const [mnemonicFiles, setMnemonicFiles] = useState<MnemonicFileEntry[]>([]);
   const [selectedFileIndex, setSelectedFileIndex] = useState(0);
 
-  /** When set, manual seed is written to ~/.config/xo-cli/mnemonics/ after a successful unlock. */
+  /** When set, manual seed is written to the configured mnemonics directory after a successful unlock. */
   const [saveMnemonicChecked, setSaveMnemonicChecked] = useState(false);
 
   // Focus: when saved wallets exist default to the file list, otherwise the input.
@@ -397,7 +397,7 @@ export function SeedInputScreen(): React.ReactElement {
             {saveMnemonicChecked ? '[x] ' : '[ ] '}
           </Text>
           <Text color={colors.text}>Save this mnemonic</Text>
-          <Text color={colors.textMuted}> (~/.config/xo-cli/mnemonics/)</Text>
+          <Text color={colors.textMuted}> ({getMnemonicsDir()}/)</Text>
         </Box>
         {focusedSection === 'saveCheckbox' && (
           <Box marginTop={0} paddingX={1}>

src/tui/screens/Transaction.tsx

@@ -1,413 +0,0 @@
-/**
- * Transaction Screen - Reviews and broadcasts transactions.
- * 
- * Provides:
- * - Transaction details review
- * - Input/output inspection
- * - Fee calculation display
- * - Broadcast confirmation
- */
-
-import React, { useState, useEffect, useCallback } from 'react';
-import { Box, Text } from 'ink';
-import { ConfirmDialog } from '../components/Dialog.js';
-import { useNavigation } from '../hooks/useNavigation.js';
-import { useAppContext, useStatus } from '../hooks/useAppContext.js';
-import { useBlockableInput } from '../hooks/useInputLayer.js';
-import { useInvitation } from '../hooks/useInvitations.js';
-import { colors, logoSmall, formatSatoshis, formatHex } from '../theme.js';
-import { copyToClipboard } from '../utils/clipboard.js';
-
-/**
- * Action menu items.
- */
-const actionItems = [
-  { label: 'Broadcast Transaction', value: 'broadcast' },
-  { label: 'Sign Transaction', value: 'sign' },
-  { label: 'Copy Transaction Hex', value: 'copy' },
-  { label: 'Back to Invitation', value: 'back' },
-];
-
-/**
- * Transaction Screen Component.
- */
-export function TransactionScreen(): React.ReactElement {
-  const { navigate, goBack, data: navData } = useNavigation();
-  const { showError, showInfo } = useAppContext();
-  const { setStatus } = useStatus();
-
-  // Extract invitation ID from navigation data
-  const invitationId = navData.invitationId as string | undefined;
-
-  // Use hook to get invitation reactively
-  const invitationInstance = useInvitation(invitationId ?? null);
-
-  // State
-  const [focusedPanel, setFocusedPanel] = useState<'inputs' | 'outputs' | 'actions'>('actions');
-  const [selectedActionIndex, setSelectedActionIndex] = useState(0);
-  const [isLoading, setIsLoading] = useState(false);
-  const [showBroadcastConfirm, setShowBroadcastConfirm] = useState(false);
-
-  // Check if invitation exists
-  useEffect(() => {
-    if (!invitationId) {
-      showError('No invitation ID provided');
-      goBack();
-      return;
-    }
-
-    if (invitationId && !invitationInstance) {
-      showError('Invitation not found');
-      goBack();
-    }
-  }, [invitationId, invitationInstance, showError, goBack]);
-
-  const invitation = invitationInstance?.data ?? null;
-
-  /**
-   * Broadcast transaction.
-   */
-  const broadcastTransaction = useCallback(async () => {
-    if (!invitationInstance) return;
-
-    setShowBroadcastConfirm(false);
-    setIsLoading(true);
-    setStatus('Broadcasting transaction...');
-
-    try {
-      await invitationInstance.broadcast();
-      showInfo(
-        `Transaction Broadcast Successful!\n\n` +
-        `The transaction has been submitted to the network.`
-      );
-      navigate('wallet');
-    } catch (error) {
-      showError(`Failed to broadcast: ${error instanceof Error ? error.message : String(error)}`);
-    } finally {
-      setIsLoading(false);
-      setStatus('Ready');
-    }
-  }, [invitationInstance, showInfo, showError, navigate, setStatus]);
-
-  /**
-   * Sign transaction.
-   */
-  const signTransaction = useCallback(async () => {
-    if (!invitationInstance) return;
-
-    setIsLoading(true);
-    setStatus('Signing transaction...');
-
-    try {
-      await invitationInstance.sign();
-      showInfo('Transaction signed successfully!');
-    } catch (error) {
-      showError(`Failed to sign: ${error instanceof Error ? error.message : String(error)}`);
-    } finally {
-      setIsLoading(false);
-      setStatus('Ready');
-    }
-  }, [invitationInstance, showInfo, showError, setStatus]);
-
-  /**
-   * Copy transaction hex.
-   */
-  const copyTransactionHex = useCallback(async () => {
-    if (!invitation) return;
-
-    try {
-      await copyToClipboard(invitation.invitationIdentifier);
-      showInfo(
-        `Copied Invitation ID!\n\n` +
-        `ID: ${invitation.invitationIdentifier}\n` +
-        `Commits: ${invitation.commits.length}`
-      );
-    } catch (error) {
-      showError(`Failed to copy: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }, [invitation, showInfo, showError]);
-
-  /**
-   * Handle action selection.
-   */
-  const handleAction = useCallback((action: string) => {
-    switch (action) {
-      case 'broadcast':
-        setShowBroadcastConfirm(true);
-        break;
-      case 'sign':
-        signTransaction();
-        break;
-      case 'copy':
-        copyTransactionHex();
-        break;
-      case 'back':
-        goBack();
-        break;
-    }
-  }, [signTransaction, copyTransactionHex, goBack]);
-
-  // Handle keyboard navigation — automatically blocked when the confirm dialog is open.
-  useBlockableInput((input, key) => {
-    // Tab to switch panels
-    if (key.tab) {
-      setFocusedPanel(prev => {
-        if (prev === 'inputs') return 'outputs';
-        if (prev === 'outputs') return 'actions';
-        return 'inputs';
-      });
-      return;
-    }
-
-    // Up/Down in actions
-    if (focusedPanel === 'actions') {
-      if (key.upArrow || input === 'k') {
-        setSelectedActionIndex(prev => Math.max(0, prev - 1));
-      } else if (key.downArrow || input === 'j') {
-        setSelectedActionIndex(prev => Math.min(actionItems.length - 1, prev + 1));
-      }
-    }
-
-    // Enter to select
-    if (key.return && focusedPanel === 'actions') {
-      const action = actionItems[selectedActionIndex];
-      if (action) {
-        handleAction(action.value);
-      }
-    }
-  });
-
-  // Extract transaction data from invitation
-  const commits = invitation?.commits ?? [];
-  const inputs: Array<{ txid: string; index: number; value?: bigint; inputIdentifier?: string }> = [];
-  const outputs: Array<{ value?: bigint; lockingBytecode: string; outputIdentifier?: string; isTemplate: boolean }> = [];
-  const variables: Array<{ id: string; value: string }> = [];
-
-  // Parse commits for inputs, outputs, and variables
-  for (const commit of commits) {
-    // Extract variables (to help understand output values)
-    if (commit.data?.variables) {
-      for (const variable of commit.data.variables) {
-        variables.push({
-          id: variable.variableIdentifier,
-          value: String(variable.value),
-        });
-      }
-    }
-
-    if (commit.data?.inputs) {
-      for (const input of commit.data.inputs) {
-        // Convert Uint8Array to hex string if needed
-        const txidHex = input.outpointTransactionHash 
-          ? typeof input.outpointTransactionHash === 'string'
-            ? input.outpointTransactionHash
-            : Buffer.from(input.outpointTransactionHash).toString('hex')
-          : undefined;
-        
-        // Skip inputs that are just placeholders (no txid)
-        if (txidHex) {
-          inputs.push({
-            txid: txidHex,
-            index: input.outpointIndex ?? 0,
-            value: undefined, // Will be looked up from UTXO data
-            inputIdentifier: (input as any).inputIdentifier,
-          });
-        }
-      }
-    }
-    if (commit.data?.outputs) {
-      for (const output of commit.data.outputs) {
-        // Convert Uint8Array to hex string if needed
-        const lockingBytecodeHex = output.lockingBytecode
-          ? typeof output.lockingBytecode === 'string'
-            ? output.lockingBytecode
-            : Buffer.from(output.lockingBytecode).toString('hex')
-          : undefined;
-        
-        // Check if this is a template-defined output (has outputIdentifier but no direct value)
-        const isTemplateOutput = !!(output as any).outputIdentifier && !output.valueSatoshis;
-        
-        outputs.push({
-          value: output.valueSatoshis,
-          lockingBytecode: lockingBytecodeHex ?? '(pending)',
-          outputIdentifier: (output as any).outputIdentifier,
-          isTemplate: isTemplateOutput,
-        });
-      }
-    }
-  }
-
-  // Try to resolve template output values from variables
-  const resolvedOutputs = outputs.map(output => {
-    if (output.isTemplate && output.outputIdentifier) {
-      // Look for a matching variable (e.g., requestSatoshisOutput -> requestedSatoshis)
-      const satoshiVar = variables.find(v => 
-        v.id.toLowerCase().includes('satoshi') || 
-        v.id.toLowerCase().includes('amount')
-      );
-      if (satoshiVar) {
-        return {
-          ...output,
-          value: BigInt(satoshiVar.value),
-          resolvedFrom: satoshiVar.id,
-        };
-      }
-    }
-    return output;
-  });
-
-  // Calculate totals (only for resolved values)
-  const totalOut = resolvedOutputs.reduce((sum, o) => sum + (o.value ?? 0n), 0n);
-  // Note: We can't calculate totalIn without UTXO lookup, so fee is unknown
-  const hasUnresolvedOutputs = resolvedOutputs.some(o => o.value === undefined);
-  const hasUnresolvedInputs = inputs.length > 0; // Input values are always unknown from commit data
-
-  return (
-    <Box flexDirection='column' flexGrow={1}>
-      {/* Header */}
-      <Box borderStyle='single' borderColor={colors.secondary} paddingX={1}>
-        <Text color={colors.primary} bold>{logoSmall} - Transaction Review</Text>
-      </Box>
-
-      {/* Summary box */}
-      <Box
-        borderStyle='single'
-        borderColor={colors.primary}
-        marginTop={1}
-        marginX={1}
-        paddingX={1}
-        flexDirection='column'
-      >
-        <Text color={colors.primary} bold> Transaction Summary </Text>
-        {invitation ? (
-          <Box flexDirection='column' marginTop={1}>
-            <Text color={colors.text}>Inputs: {inputs.length} | Outputs: {resolvedOutputs.length} | Commits: {commits.length}</Text>
-            {hasUnresolvedInputs && (
-              <Text color={colors.textMuted}>Total In: (requires UTXO lookup)</Text>
-            )}
-            <Text color={colors.warning}>Total Out: {formatSatoshis(totalOut)}{hasUnresolvedOutputs ? ' (partial)' : ''}</Text>
-            {hasUnresolvedInputs ? (
-              <Text color={colors.textMuted}>Fee: (calculated at broadcast)</Text>
-            ) : (
-              <Text color={colors.info}>Fee: {formatSatoshis(0n)}</Text>
-            )}
-          </Box>
-        ) : (
-          <Text color={colors.textMuted}>Loading...</Text>
-        )}
-      </Box>
-
-      {/* Inputs and Outputs */}
-      <Box flexDirection='row' marginTop={1} marginX={1} flexGrow={1}>
-        {/* Inputs */}
-        <Box
-          borderStyle='single'
-          borderColor={focusedPanel === 'inputs' ? colors.focus : colors.border}
-          width='50%'
-          flexDirection='column'
-          paddingX={1}
-        >
-          <Text color={colors.primary} bold> Inputs </Text>
-          <Box flexDirection='column' marginTop={1}>
-            {inputs.length === 0 ? (
-              <Text color={colors.textMuted}>No inputs</Text>
-            ) : (
-              inputs.map((input, index) => (
-                <Box key={`${input.txid}-${input.index}`} flexDirection='column' marginBottom={1}>
-                  <Text color={colors.text}>
-                    {index + 1}. {formatHex(input.txid, 12)}:{input.index}
-                  </Text>
-                  {input.value !== undefined && (
-                    <Text color={colors.textMuted}>   {formatSatoshis(input.value)}</Text>
-                  )}
-                </Box>
-              ))
-            )}
-          </Box>
-        </Box>
-
-        {/* Outputs */}
-        <Box
-          borderStyle='single'
-          borderColor={focusedPanel === 'outputs' ? colors.focus : colors.border}
-          width='50%'
-          flexDirection='column'
-          paddingX={1}
-          marginLeft={1}
-        >
-          <Text color={colors.primary} bold> Outputs </Text>
-          <Box flexDirection='column' marginTop={1}>
-            {resolvedOutputs.length === 0 ? (
-              <Text color={colors.textMuted}>No outputs</Text>
-            ) : (
-              resolvedOutputs.map((output, index) => (
-                <Box key={index} flexDirection='column' marginBottom={1}>
-                  <Text color={colors.text}>
-                    {index + 1}. {output.value !== undefined ? formatSatoshis(output.value) : '(pending)'}
-                    {output.outputIdentifier && (
-                      <Text color={colors.info}> [{output.outputIdentifier}]</Text>
-                    )}
-                  </Text>
-                  <Text color={colors.textMuted}>   {output.lockingBytecode !== '(pending)' ? formatHex(output.lockingBytecode, 20) : '(pending)'}</Text>
-                  {(output as any).resolvedFrom && (
-                    <Text color={colors.textMuted} dimColor>   (from ${(output as any).resolvedFrom})</Text>
-                  )}
-                </Box>
-              ))
-            )}
-          </Box>
-        </Box>
-      </Box>
-
-      {/* Actions */}
-      <Box
-        borderStyle='single'
-        borderColor={focusedPanel === 'actions' ? colors.focus : colors.border}
-        marginTop={1}
-        marginX={1}
-        paddingX={1}
-        flexDirection='column'
-      >
-        <Text color={colors.primary} bold> Actions </Text>
-        <Box flexDirection='column' marginTop={1}>
-          {actionItems.map((item, index) => (
-            <Text
-              key={item.value}
-              color={index === selectedActionIndex && focusedPanel === 'actions' ? colors.focus : colors.text}
-              bold={index === selectedActionIndex && focusedPanel === 'actions'}
-            >
-              {index === selectedActionIndex && focusedPanel === 'actions' ? '▸ ' : '  '}
-              {item.label}
-            </Text>
-          ))}
-        </Box>
-      </Box>
-
-      {/* Help text */}
-      <Box marginTop={1} marginX={1}>
-        <Text color={colors.textMuted} dimColor>
-          Tab: Switch focus • Enter: Select • Esc: Back
-        </Text>
-      </Box>
-
-      {/* Broadcast confirmation dialog */}
-      {showBroadcastConfirm && (
-        <Box
-          position='absolute'
-          flexDirection='column'
-          alignItems='center'
-          justifyContent='center'
-          width='100%'
-          height='100%'
-        >
-          <ConfirmDialog
-            title='Broadcast Transaction'
-            message='Are you sure you want to broadcast this transaction? This action cannot be undone.'
-            onConfirm={broadcastTransaction}
-            onCancel={() => setShowBroadcastConfirm(false)}
-          />
-        </Box>
-      )}
-    </Box>
-  );
-}

src/tui/screens/index.tsx

@@ -7,4 +7,3 @@ export { SeedInputScreen } from './SeedInput.js';
 export { WalletStateScreen } from './WalletState.js';
 export { TemplateListScreen } from './TemplateList.js';
 export { InvitationScreen } from './invitations/InvitationScreen.js';
-export { TransactionScreen } from './Transaction.js';

src/tui/screens/invitations/InvitationScreen.tsx

@@ -26,12 +26,10 @@ import type { XOInvitationCommit, XOInvitationVariableValue, XOTemplate } from '
 import {
   getInvitationState,
   getStateColorName,
-  getInvitationInputs,
-  getInvitationOutputs,
-  getInvitationVariables,
   formatInvitationListItem,
   formatInvitationId,
 } from '../../../utils/invitation-utils.js';
+import type { ResolvedInvitationVariable } from '../../../utils/resolve-invitation-data.js';
 
 import { InvitationImportFlow } from './invitation-import/InvitationImportFlow.js';
 import { compileCashAssemblyString } from '@xo-cash/engine';
@@ -63,8 +61,9 @@ const actionItems: ListItemData<string>[] = [
   { key: 'accept', label: 'Accept & Join', value: 'accept' },
   { key: 'fill', label: 'Fill Requirements', value: 'fill' },
   { key: 'sign', label: 'Sign Transaction', value: 'sign' },
-  { key: 'transaction', label: 'View Transaction', value: 'transaction' },
+  { key: 'broadcast', label: 'Broadcast Transaction', value: 'broadcast' },
   { key: 'copy', label: 'Copy Invitation ID', value: 'copy' },
+  { key: 'delete', label: 'Delete Invitation', value: 'delete' },
 ];
 
 /**
@@ -332,6 +331,52 @@ export function InvitationScreen(): React.ReactElement {
     }
   }, [selectedInvitation, showInfo, showError, setStatus]);
 
+  /**
+   * Broadcast transaction.
+   */
+  const broadcastTransaction = useCallback(async () => {
+    if (!selectedInvitation) return;
+
+    setIsLoading(true);
+    setStatus('Broadcasting transaction...');
+
+    try {
+      await selectedInvitation.broadcast();
+      showInfo(
+        `Transaction Broadcast Successful!\n\n` +
+        `The transaction has been submitted to the network.`
+      );
+      setStatus('Ready');
+    } catch (error) {
+      showError(`Failed to broadcast: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      setIsLoading(false);
+      setStatus('Ready');
+    }
+  }, [selectedInvitation, showInfo, showError, setStatus]);
+
+  /**
+   * Delete the selected invitation from both our SQLite db and the engine's db
+   * NOTE: This uses methods marked "DANGEROUSLY" internally, and may change in the future.
+   */
+  const deleteInvitation = useCallback(async () => {
+    if (!selectedInvitation) return;
+
+    setIsLoading(true)
+    setStatus('Removing invitation...')
+
+    try {
+      await selectedInvitation.delete();
+      showInfo('Invitation successfully deleted')
+      setStatus('Ready')
+    } catch (error) {
+      showError(`Failed to delete invitation: ${error instanceof Error ? error.message : String(error)}`)
+    } finally {
+      setIsLoading(false)
+      setStatus('Ready')
+    }
+  })
+
   const copyId = useCallback(async () => {
     if (!selectedInvitation) {
       showError('No invitation selected');
@@ -377,17 +422,12 @@ export function InvitationScreen(): React.ReactElement {
       setStatus('Analyzing invitation...');
 
       let requiredAmount = 0n;
-      const commits = selectedInvitation.data.commits || [];
+      for (const variable of selectedInvitation.resolvedData.variables) {
-      for (const commit of commits) {
+        if (variable.variableIdentifier.toLowerCase().includes('satoshi')) {
-        const variables = commit.data?.variables || [];
-        for (const variable of variables) {
-          if (variable.variableIdentifier?.toLowerCase().includes('satoshi')) {
           requiredAmount = BigInt(variable.value?.toString() || '0');
           break;
         }
       }
-        if (requiredAmount > 0n) break;
-      }
 
       const fee = 500n;
       const dust = 546n;
@@ -489,13 +529,14 @@ export function InvitationScreen(): React.ReactElement {
       case 'sign':
         signInvitation();
         break;
-      case 'transaction':
+      case 'broadcast':
-        if (selectedInvitation) {
+        broadcastTransaction();
-          navigate('transaction', { invitationId: selectedInvitation.data.invitationIdentifier });
+        break;
-        }
+      case 'delete':
+        deleteInvitation();
         break;
     }
-  }, [selectedInvitation, copyId, acceptInvitation, fillRequirements, signInvitation, navigate]);
+  }, [selectedInvitation, copyId, acceptInvitation, fillRequirements, signInvitation, broadcastTransaction, navigate]);
 
   const handleListItemActivate = useCallback((item: InvitationListItem, _index: number) => {
     if (item.key === 'import') {
@@ -573,14 +614,17 @@ export function InvitationScreen(): React.ReactElement {
 
     const state = getInvitationState(selectedInvitation);
     const action = selectedTemplate?.actions?.[selectedInvitation.data.actionIdentifier];
-    const inputs = getInvitationInputs(selectedInvitation);
+    const { inputs, outputs, variables } = selectedInvitation.resolvedData;
-    const outputs = getInvitationOutputs(selectedInvitation);
-    const variables = getInvitationVariables(selectedInvitation);
     const userEntityId = ownInvitationContext.entityIdentifier;
     const userRole = ownInvitationContext.roleIdentifier;
     const roleInfoRaw = userRole && selectedTemplate?.roles?.[userRole];
     const roleInfo = roleInfoRaw && typeof roleInfoRaw === 'object' ? roleInfoRaw : null;
 
+    const variableValues = variables.reduce((acc, variable) => {
+      acc[variable.variableIdentifier] = variable.value as XOInvitationVariableValue;
+      return acc;
+    }, {} as Record<string, XOInvitationVariableValue>);
+
     const getFiatSuffix = (satoshis: bigint): string => {
       const fiatValue = formatSatoshisToFiat(satoshis);
       return fiatValue ? ` (~${fiatValue})` : '';
@@ -603,11 +647,10 @@ export function InvitationScreen(): React.ReactElement {
       }
     };
 
-    const isSatoshisVariable = (variableIdentifier: string): boolean => {
+    const isSatoshisVariable = (variable: ResolvedInvitationVariable): boolean => {
-      const templateVariable = selectedTemplate?.variables?.[variableIdentifier];
+      const templateHint = variable.hint?.toLowerCase();
-      const templateType = templateVariable?.type?.toLowerCase();
+      const templateType = variable.type?.toLowerCase();
-      const templateHint = templateVariable?.hint?.toLowerCase();
+      const identifier = variable.variableIdentifier.toLowerCase();
-      const identifier = variableIdentifier.toLowerCase();
 
       if (templateHint?.includes('satoshi')) {
         return true;
@@ -619,6 +662,20 @@ export function InvitationScreen(): React.ReactElement {
       );
     };
 
+    const compileResolvedDescription = (description?: string): string | null => {
+      if (!description) return null;
+
+      try {
+        return compileCashAssemblyString({
+          cashAssemblyText: description,
+          variables: variableValues,
+          evaluationDecodeMode: 'bigint',
+        });
+      } catch {
+        return description;
+      }
+    };
+
     return (
       <Box flexDirection="column">
         {/* Type & Status */}
@@ -671,28 +728,21 @@ 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;
+                const inputDescription = compileResolvedDescription(input.description);
                 return (
                   <Text
                     key={`input-${idx}`}
                     color={isUserInput ? colors.success : colors.text}
                   >
-                    {/* Indicator for whether this is the user's input */}
                     {'  '}{isUserInput ? '• ' : '○ '}
-                    
+                    {input.name ?? input.inputIdentifier ?? `Input ${idx}`}
-                    {/* TODO: Why doesnt this stuff work? It just cant resolve inputs? */}
-                    {/* Input name */}
-                    {inputTemplate?.name ?? input.inputIdentifier ?? `Input ${idx}`}
-                    
-                    {/* Input role */}
                     {input.roleIdentifier && ` (${input.roleIdentifier})`}
-                    
+                    {inputDescription && ` - ${inputDescription}`}
-                    {/* Input value */}
                     {inputSatoshis !== null && ` ${formatSatoshis(inputSatoshis)}${getFiatSuffix(inputSatoshis)}`}
                   </Text>
                 );
@@ -707,32 +757,18 @@ 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;
+                const outputDescription = compileResolvedDescription(output.description);
                 return (
                   <Text
                     key={`output-${idx}`}
                     color={isUserOutput ? colors.success : colors.text}
                   >
-                    {/* Indicator for whether this is the user's output */}
                     {'  '}{isUserOutput ? '• ' : '○ '}
-
+                    {output.name ?? output.outputIdentifier ?? `Output ${idx}`}
-                    {/* Output name */}
+                    {outputDescription && ` - ${outputDescription}`}
-                    {outputTemplate?.name ?? output.outputIdentifier ?? `Output ${idx}`}
-                    
-                    {/* Output description */}
-                    {outputTemplate?.description && ' - ' + compileCashAssemblyString({
-                      cashAssemblyText: outputTemplate?.description,
-                      variables: variables.reduce((acc, variable) => {
-                        acc[variable.variableIdentifier] = variable.value as XOInvitationVariableValue;
-
-                        return acc;
-                      }, {} as Record<string, XOInvitationVariableValue>)
-                    })}
-                    
-                    {/* Output value */}
                     {outputSatoshis !== null && ` (${formatSatoshis(outputSatoshis)}${getFiatSuffix(outputSatoshis)})`}
                   </Text>
                 );
@@ -749,11 +785,10 @@ export function InvitationScreen(): React.ReactElement {
           ) : (
             variables.map((variable, idx) => {
               const isUserVariable = variable.entityIdentifier === userEntityId;
-              const varTemplate = selectedTemplate?.variables?.[variable.variableIdentifier];
               const displayValue = typeof variable.value === 'bigint'
                 ? variable.value.toString()
                 : String(variable.value);
-              const parsedVariableSatoshis = isSatoshisVariable(variable.variableIdentifier)
+              const parsedVariableSatoshis = isSatoshisVariable(variable)
                 ? parseNumberishToBigInt(variable.value)
                 : null;
               return (
@@ -762,11 +797,11 @@ export function InvitationScreen(): React.ReactElement {
                   color={isUserVariable ? colors.success : colors.text}
                 >
                   {'  '}{isUserVariable ? '• ' : '○ '}
-                  {varTemplate?.name ?? variable.variableIdentifier}: {displayValue}
+                  {variable.name ?? variable.variableIdentifier}: {displayValue}
                   {parsedVariableSatoshis !== null &&
                     ` (${formatSatoshis(parsedVariableSatoshis)}${getFiatSuffix(parsedVariableSatoshis)})`}
-                  {varTemplate?.description && (
+                  {variable.description && (
-                    <Text color={colors.textMuted} dimColor> - {varTemplate.description}</Text>
+                    <Text color={colors.textMuted} dimColor> - {variable.description}</Text>
                   )}
                 </Text>
               );

src/tui/screens/invitations/invitation-import/steps/PreviewInvitationStep.tsx

@@ -14,12 +14,29 @@ import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import {
   getInvitationState,
   getStateColorName,
-  getInvitationInputs,
-  getInvitationOutputs,
-  getInvitationVariables,
 } from '../../../../../utils/invitation-utils.js';
 import type { PreviewStepProps } from '../types.js';
 
+/**
+ * Map a semantic color name to an actual theme color value.
+ */
+function 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;
+  }
+}
+
 /**
  * Map a semantic color name to an actual theme color value.
  */
@@ -51,16 +68,18 @@ export function PreviewInvitationStep({
 
   const state = getInvitationState(invitation);
   const action = template?.actions?.[invitation.data.actionIdentifier];
-  const inputs = getInvitationInputs(invitation);
+  const { inputs, outputs, variables } = invitation.resolvedData;
-  const outputs = getInvitationOutputs(invitation);
-  const variables = getInvitationVariables(invitation);
 
-  // Collect role identifiers that appear across all commits
+  // Collect role identifiers that appear across resolved invitation data
   const filledRoles = new Set<string>();
-  for (const commit of invitation.data.commits ?? []) {
+  for (const input of inputs) {
-    for (const input of commit.data?.inputs ?? []) {
     if (input.roleIdentifier) filledRoles.add(input.roleIdentifier);
   }
+  for (const output of outputs) {
+    if (output.roleIdentifier) filledRoles.add(output.roleIdentifier);
+  }
+  for (const variable of variables) {
+    if (variable.roleIdentifier) filledRoles.add(variable.roleIdentifier);
   }
 
   return (
@@ -143,11 +162,10 @@ export function PreviewInvitationStep({
             </Box>
           ) : (
             inputs.map((input, idx) => {
-              const inputTemplate = template?.inputs?.[input.inputIdentifier ?? ''];
               return (
                 <Box key={`input-${idx}`}>
                   <Text color={colors.text}>
-                    {'  '}• {inputTemplate?.name ?? input.inputIdentifier ?? `Input ${idx}`}
+                    {'  '}• {input.name ?? input.inputIdentifier ?? `Input ${idx}`}
                     {input.roleIdentifier && ` (${input.roleIdentifier})`}
                   </Text>
                 </Box>
@@ -170,15 +188,17 @@ export function PreviewInvitationStep({
             </Box>
           ) : (
             outputs.map((output, idx) => {
-              const outputTemplate = template?.outputs?.[output.outputIdentifier ?? ''];
               const fiatValue = output.valueSatoshis !== undefined
                 ? formatSatoshisToFiat(output.valueSatoshis)
                 : null;
+              const outputSatoshis = output.valueSatoshis !== undefined
+                ? parseNumberishToBigInt(output.valueSatoshis)
+                : null;
               return (
                 <Box key={`output-${idx}`}>
                   <Text color={colors.text}>
-                    {'  '}• {outputTemplate?.name ?? output.outputIdentifier ?? `Output ${idx}`}
+                    {'  '}• {output.name ?? output.outputIdentifier ?? `Output ${idx}`}
-                    {output.valueSatoshis !== undefined && ` (${formatSatoshis(output.valueSatoshis)})`}
+                    {outputSatoshis !== null && ` (${formatSatoshis(outputSatoshis)})`}
                     {fiatValue && ` (~${fiatValue})`}
                   </Text>
                 </Box>
@@ -201,14 +221,13 @@ export function PreviewInvitationStep({
             </Box>
           ) : (
             variables.map((variable, idx) => {
-              const varTemplate = template?.variables?.[variable.variableIdentifier];
               const displayValue = typeof variable.value === 'bigint'
                 ? variable.value.toString()
                 : String(variable.value);
               return (
                 <Box key={`var-${idx}`}>
                   <Text color={colors.text}>
-                    {'  '}• {varTemplate?.name ?? variable.variableIdentifier}: {displayValue}
+                    {'  '}• {variable.name ?? variable.variableIdentifier}: {displayValue}
                   </Text>
                 </Box>
               );

src/tui/utils/clipboard.ts

@@ -13,30 +13,36 @@ const execAsync = promisify(exec);
 // 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',
+    platform: (platform: string) => platform === "darwin",
-    command: async (text: string) => execAsync(`printf '%s' '${text}' | pbcopy`),
+    command: async (text: string) =>
+      execAsync(`printf '%s' '${text}' | pbcopy`),
   },
   xclip: {
-    platform: (platform: string) => platform === 'linux',
+    platform: (platform: string) => platform === "linux",
-    command: async (text: string) => execAsync(`printf '%s' '${text}' | xclip -selection clipboard`),
+    command: async (text: string) =>
+      execAsync(`printf '%s' '${text}' | xclip -selection clipboard`),
   },
   xsel: {
-    platform: (platform: string) => platform === 'linux',
+    platform: (platform: string) => platform === "linux",
-    command: async (text: string) => execAsync(`printf '%s' '${text}' | xsel --clipboard --input`),
+    command: async (text: string) =>
+      execAsync(`printf '%s' '${text}' | xsel --clipboard --input`),
   },
   ssh: {
-    platform: (platform: string) => platform === 'linux',
+    platform: (platform: string) => platform === "linux",
-    command: async (text: string) => process.stdout.write(`\x1b]52;c;${Buffer.from(text, 'utf-8').toString('base64')}\x07`),
+    command: async (text: string) =>
+      process.stdout.write(
+        `\x1b]52;c;${Buffer.from(text, "utf-8").toString("base64")}\x07`,
+      ),
   },
   clip: {
-    platform: (platform: string) => platform === 'windows',
+    platform: (platform: string) => platform === "windows",
     command: async (text: string) => execAsync(`echo|set /p="${text}" | clip`),
   },
   clipboardy: {
-    platform: (platform: string) => platform === 'windows',
+    platform: (platform: string) => platform === "windows",
     command: async (text: string) => clipboardy.writeSync(text),
   },
-}
+};
 
 /**
  * Attempts to copy text to clipboard using multiple methods.
@@ -51,7 +57,9 @@ export async function copyToClipboard(text: string): Promise<void> {
   // Escape the text for shell commands
   const escapedText = text.replace(/'/g, "'\\''");
 
-  const availableMethods = Object.values(clipboardMethods).filter(method => method.platform(platform));
+  const availableMethods = Object.values(clipboardMethods).filter((method) =>
+    method.platform(platform),
+  );
 
   const errors: Error[] = [];
 
@@ -71,5 +79,7 @@ export async function copyToClipboard(text: string): Promise<void> {
   }
 
   // All methods failed
-  throw new Error(`Clipboard not available. ${errors.map(error => error.message).join('\n')}`);
+  throw new Error(
+    `Clipboard not available. ${errors.map((error) => error.message).join("\n")}`,
+  );
 }

src/tui/utils/list-directory-entries.ts

@@ -160,8 +160,7 @@ export function listDirectoryEntries(
       entries: [...entries, ...directories, ...files],
     };
   } catch (error) {
-    const message =
+    const message = error instanceof Error ? error.message : String(error);
-      error instanceof Error ? error.message : String(error);
     return {
       entries: [],
       error: `Unable to read directory: ${message}`,

src/utils/history-utils.ts

@@ -51,7 +51,7 @@ export function buildHistoryDisplayRows(
           type: "history_output",
           label: output.outpoint
             ? `${output.outpoint.txid}:${output.outpoint.index}`
-            : output.outputIdentifier ?? "Output",
+            : (output.outputIdentifier ?? "Output"),
           description: `${item.template} | ${roles} | ${output.description}`,
           timestamp: item.createdAtTimestamp,
           isNested: false,
@@ -96,7 +96,7 @@ export function buildHistoryDisplayRows(
         type: "history_output",
         label: output.outpoint
           ? `${output.outpoint.txid}:${output.outpoint.index}`
-          : output.outputIdentifier ?? "Output",
+          : (output.outputIdentifier ?? "Output"),
         description: output.description,
         isNested: true,
         valueSatoshis: output.valueSatoshis,

src/utils/invitation-flow.ts

@@ -65,8 +65,18 @@ export const roleRequiresInputs = (
 
   const actionRole = action.roles?.[roleIdentifier];
   const actionRequirements = action.requirements;
-  const actionRoleRequirements = actionRole && actionRequirements && actionRequirements.participants?.find((participant) => participant.role === roleIdentifier);
+  const actionRoleRequirements =
-  const roleSlotsMin = actionRoleRequirements && actionRoleRequirements.slots && actionRoleRequirements.slots.min > 0 ? actionRoleRequirements.slots.min : 0;
+    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;
 
   const transactionIdentifier = action.transaction;
@@ -78,7 +88,6 @@ export const roleRequiresInputs = (
   return (roleInputs?.length ?? 0) > 0;
 };
 
-
 export const getTransactionOutputIdentifier = (
   output: XOTemplateTransactionOutput,
 ): string | undefined => {
@@ -136,7 +145,8 @@ export const resolveProvidedLockingBytecodeHex = (
     return undefined;
   }
 
-  const lockingScriptDefinition = template.lockingScripts?.[outputDefinition.lockingScript];
+  const lockingScriptDefinition =
+    template.lockingScripts?.[outputDefinition.lockingScript];
   const scriptIdentifier = lockingScriptDefinition?.lockingBytecode;
   if (!scriptIdentifier) return undefined;
 

src/utils/load-template-from-file.ts

@@ -71,12 +71,7 @@ function resolveTemplateModuleLoaderPath(): string {
 }
 
 /** TypeScript extensions that require tsx to evaluate the template module. */
-const TYPESCRIPT_TEMPLATE_EXTENSIONS = new Set([
+const TYPESCRIPT_TEMPLATE_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts"]);
-  ".ts",
-  ".tsx",
-  ".mts",
-  ".cts",
-]);
 
 /**
  * Loads a TS/JS template module in an isolated child process.
@@ -155,7 +150,9 @@ async function loadTemplateModuleViaChildProcess(
       }
 
       if (stdout.trim().length === 0) {
-        reject(new TemplateLoadError("Template module loader returned no output."));
+        reject(
+          new TemplateLoadError("Template module loader returned no output."),
+        );
         return;
       }
 
@@ -174,7 +171,9 @@ export async function loadTemplateFromFile(filePath: string): Promise<string> {
   const absolutePath = path.resolve(filePath);
 
   if (!fs.existsSync(absolutePath)) {
-    throw new TemplateLoadError(`Template file does not exist: ${absolutePath}`);
+    throw new TemplateLoadError(
+      `Template file does not exist: ${absolutePath}`,
+    );
   }
 
   const extension = path.extname(absolutePath).toLowerCase();

src/utils/paths.ts

@@ -1,5 +1,5 @@
 /**
- * Global XO CLI config layout (XDG-style: ~/.config/xo-cli/).
+ * Global XO CLI config layout (`XO_CONFIG_DIR` or ~/.config/xo-cli/).
  * User-provided paths (templates, invitation JSON) stay relative to cwd.
  */
 
@@ -11,7 +11,8 @@ import { basename, isAbsolute, join, resolve } from "node:path";
  * Base config directory. Created on first access.
  */
 export function getConfigDir(): string {
-  const dir = join(homedir(), ".config", "xo-cli");
+  const dir =
+    process.env["XO_CONFIG_DIR"] || join(homedir(), ".config", "xo-cli");
   mkdirSync(dir, { recursive: true });
   return dir;
 }
@@ -50,7 +51,7 @@ export function getWalletConfigPath(): string {
 
 /**
  * Resolves a mnemonic reference to an absolute path.
- * Order: absolute path if it exists → path relative to cwd → ~/.config/xo-cli/mnemonics/<basename>.
+ * Order: absolute path if it exists → path relative to cwd → config mnemonics directory/<basename>.
  *
  * @param mnemonicRef - Path or basename (e.g. `mnemonic-nuclear`)
  * @returns Absolute path to the mnemonic file

src/utils/pick-template-export.ts

@@ -6,7 +6,9 @@
  * Returns true when `value` looks like an XOTemplate object (pre-schema check).
  * Used only to pick the correct export before {@link parseTemplate} validates fully.
  */
-export function isTemplateLike(value: unknown): value is Record<string, unknown> {
+export function isTemplateLike(
+  value: unknown,
+): value is Record<string, unknown> {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return false;
   }

src/utils/rates/base-rates.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from '../event-emitter.js';
+import { EventEmitter } from "../event-emitter.js";
 
 /**
  * Events emitted by our Rates Adapters
@@ -44,14 +44,15 @@ export abstract class BaseRates<
       BCH: 8,
       USD: 2,
     };
-    const minimumFractionDigits = minimumFractionDigitsMap[normalizedCurrency] ?? 2;
+    const minimumFractionDigits =
+      minimumFractionDigitsMap[normalizedCurrency] ?? 2;
     const maximumFractionDigits = Math.max(minimumFractionDigits, 8);
 
     try {
-      const formatter = new Intl.NumberFormat('en-US', {
+      const formatter = new Intl.NumberFormat("en-US", {
-        style: 'currency',
+        style: "currency",
         currency: normalizedCurrency,
-        currencyDisplay: 'narrowSymbol',
+        currencyDisplay: "narrowSymbol",
         minimumFractionDigits,
         maximumFractionDigits,
       });
@@ -61,7 +62,7 @@ export abstract class BaseRates<
       // Some numerator symbols from oracle pairs (e.g. DOGE/BCH) are not ISO-4217
       // fiat currency codes, so Intl currency formatting will throw a RangeError.
       // In that case we still return a human-readable formatted value.
-      const numericFormatter = new Intl.NumberFormat('en-US', {
+      const numericFormatter = new Intl.NumberFormat("en-US", {
         minimumFractionDigits,
         maximumFractionDigits,
       });

src/utils/rates/rates-oracles.ts

@@ -3,11 +3,11 @@ import {
   OracleMetadataMessage,
   OraclePriceMessage,
   type OracleMetadataMap,
-} from '@generalprotocols/oracle-client';
+} from "@generalprotocols/oracle-client";
 
-import { type RatesEventMap, BaseRates } from './base-rates.js';
+import { type RatesEventMap, BaseRates } from "./base-rates.js";
-import { type OffCallback } from '../event-emitter.js';
+import { type OffCallback } from "../event-emitter.js";
-import { SettingsService } from '../../services/settings.js';
+import { SettingsService } from "../../services/settings.js";
 
 // Add the Oracle Price Message to our Events for this Adapter.
 export type RatesOracleEventMap = RatesEventMap & {
@@ -42,7 +42,7 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
 
   private started: boolean = false;
   private targetNumeratorUnitCode: string;
-  private targetDenominatorUnitCode: string = 'BCH';
+  private targetDenominatorUnitCode: string = "BCH";
   private unsubscribeFromSettings: OffCallback | null = null;
 
   public constructor(client: OracleClient, settings: SettingsService) {
@@ -63,7 +63,7 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
     }
     this.started = true;
     this.unsubscribeFromSettings = this.settings.on(
-      'settings-updated',
+      "settings-updated",
       this.handleSettingsUpdated.bind(this),
     );
 
@@ -150,7 +150,11 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
             this.handlePriceMessage(message);
           }
         } catch (error) {
-          console.error('Error refreshing prices for oracle:', oracle.publicKey, error);
+          console.error(
+            "Error refreshing prices for oracle:",
+            oracle.publicKey,
+            error,
+          );
         }
       }),
     );
@@ -183,8 +187,10 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
       return;
     }
 
-    const sourceNumeratorUnitCode = oracle.SOURCE_NUMERATOR_UNIT_CODE.toUpperCase();
+    const sourceNumeratorUnitCode =
-    const sourceDenominatorUnitCode = oracle.SOURCE_DENOMINATOR_UNIT_CODE.toUpperCase();
+      oracle.SOURCE_NUMERATOR_UNIT_CODE.toUpperCase();
+    const sourceDenominatorUnitCode =
+      oracle.SOURCE_DENOMINATOR_UNIT_CODE.toUpperCase();
 
     // Only emit the pair currently selected in settings.
     if (
@@ -197,7 +203,7 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
     // Scale the price
     const priceValue = message.priceValue / oracle.ATTESTATION_SCALING;
 
-    this.emit('rateUpdated', {
+    this.emit("rateUpdated", {
       numeratorUnitCode: sourceNumeratorUnitCode,
       denominatorUnitCode: sourceDenominatorUnitCode,
       price: priceValue,
@@ -208,13 +214,11 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
   /**
    * Tracks updates to settings and switches the actively emitted fiat pair.
    */
-  private handleSettingsUpdated(
+  private handleSettingsUpdated(event: {
-    event: {
+    key: "currency" | "default-mnemonic";
-      key: 'currency' | 'default-mnemonic';
     value: string | undefined;
-    },
+  }) {
-  ) {
+    if (event.key !== "currency" || !event.value) {
-    if (event.key !== 'currency' || !event.value) {
       return;
     }
 
@@ -223,7 +227,7 @@ export class RatesOracle extends BaseRates<RatesOracleEventMap> {
     // Refresh so listeners get the latest value for the new currency quickly.
     if (this.started) {
       this.refreshPrices().catch((error) => {
-        console.error('Error refreshing prices after currency update:', error);
+        console.error("Error refreshing prices after currency update:", error);
       });
     }
   }

src/utils/resolve-invitation-data.ts

@@ -0,0 +1,452 @@
+/**
+ * Transforms a raw XO invitation into a flattened, template-enriched structure
+ * suitable for UI display without manually resolving template references.
+ *
+ * The original invitation format is unchanged in storage and transport; this
+ * function produces a read model that merges commit data with template metadata
+ * (names, descriptions, icons, roles, etc.).
+ */
+
+import { mergeInvitationCommits } from "@xo-cash/engine";
+import { binToHex } from "@bitauth/libauth";
+import type {
+  XOInvitation,
+  XOInvitationCommit,
+  XOInvitationInput,
+  XOInvitationOutput,
+  XOInvitationVariable,
+  XOInvitationVariableValue,
+  XOTemplate,
+  XOTemplateInput,
+  XOTemplateOutput,
+  XOTemplateVariable,
+} from "@xo-cash/types";
+
+/**
+ * A variable from invitation commits enriched with its template definition.
+ */
+export interface ResolvedInvitationVariable {
+  entityIdentifier: string;
+  variableIdentifier: string;
+  roleIdentifier?: string;
+  value: XOInvitationVariableValue;
+  name?: string;
+  description?: string;
+  type?: string;
+  hint?: string;
+}
+
+/**
+ * A transaction input from invitation commits enriched with its template definition.
+ */
+export type ResolvedInvitationInput = XOInvitationInput & {
+  entityIdentifier: string;
+  name?: string;
+  description?: string;
+  icon?: string;
+  unlockingScript?: string;
+  omitChangeAmounts?: XOTemplateInput["omitChangeAmounts"];
+};
+
+/**
+ * A transaction output from invitation commits enriched with its template definition.
+ */
+export type ResolvedInvitationOutput = XOInvitationOutput & {
+  entityIdentifier: string;
+  name?: string;
+  description?: string;
+  icon?: string;
+  roles?: Record<
+    string,
+    { name?: string; description?: string; icon?: string }
+  >;
+  lockingScript?: string;
+};
+
+/**
+ * Flattened, template-enriched invitation data for UI consumption.
+ */
+export interface ResolvedInvitationData {
+  invitationIdentifier: string;
+  templateIdentifier: string;
+  actionIdentifier: string;
+  variables: ResolvedInvitationVariable[];
+  inputs: ResolvedInvitationInput[];
+  outputs: ResolvedInvitationOutput[];
+}
+
+/**
+ * Picks human-readable view fields from a template definition.
+ */
+export const pickTemplateViewMetadata = (definition?: {
+  name?: string;
+  description?: string;
+  icon?: string;
+}) => {
+  if (!definition) return {};
+
+  // Only copy fields that are present so absent template metadata does not
+  // overwrite committed values when this object is spread onto a commit row.
+  return {
+    ...(definition.name !== undefined && { name: definition.name }),
+    ...(definition.description !== undefined && {
+      description: definition.description,
+    }),
+    ...(definition.icon !== undefined && { icon: definition.icon }),
+  };
+};
+
+/**
+ * Picks variable metadata from a template variable definition.
+ */
+export const pickTemplateVariableMetadata = (
+  definition?: XOTemplateVariable,
+) => {
+  if (!definition) return {};
+
+  return {
+    ...pickTemplateViewMetadata(definition),
+    ...(definition.type !== undefined && { type: definition.type }),
+    ...(definition.hint !== undefined && { hint: definition.hint }),
+  };
+};
+
+/**
+ * Picks input metadata from a template input definition.
+ */
+export const pickTemplateInputMetadata = (definition?: XOTemplateInput) => {
+  if (!definition) return {};
+
+  return {
+    ...pickTemplateViewMetadata(definition),
+    ...(definition.unlockingScript !== undefined && {
+      unlockingScript: definition.unlockingScript,
+    }),
+    ...(definition.omitChangeAmounts !== undefined && {
+      omitChangeAmounts: definition.omitChangeAmounts,
+    }),
+  };
+};
+
+/**
+ * Picks output metadata from a template output definition.
+ *
+ * Committed output values (e.g. lockingBytecode) take precedence over template
+ * defaults; display-oriented fields like name, description, and template
+ * valueSatoshis expressions are layered on for UI rendering.
+ */
+export const pickTemplateOutputMetadata = (definition?: XOTemplateOutput) => {
+  if (!definition) return {};
+
+  const roles = definition.roles
+    ? Object.fromEntries(
+        Object.entries(definition.roles).map(([roleId, roleDefinition]) => [
+          roleId,
+          pickTemplateViewMetadata(roleDefinition),
+        ]),
+      )
+    : undefined;
+
+  return {
+    ...pickTemplateViewMetadata(definition),
+    ...(roles !== undefined && Object.keys(roles).length > 0 && { roles }),
+    ...(definition.lockingScript !== undefined && {
+      lockingScript: definition.lockingScript,
+    }),
+    // Keep CashAssembly expressions (e.g. "$(<totalSatoshis>)") for UI compilation;
+    // committed bigint values on the output row take precedence when spread later.
+    ...(definition.valueSatoshis !== undefined && {
+      valueSatoshis: definition.valueSatoshis,
+    }),
+    ...(definition.token !== undefined && { token: definition.token }),
+  };
+};
+
+/**
+ * Enriches a committed variable with its template definition.
+ */
+export const resolveVariable = (
+  variable: XOInvitationVariable,
+  entityIdentifier: string,
+  template: XOTemplate,
+): ResolvedInvitationVariable => ({
+  entityIdentifier,
+  variableIdentifier: variable.variableIdentifier,
+  ...(variable.roleIdentifier !== undefined && {
+    roleIdentifier: variable.roleIdentifier,
+  }),
+  value: variable.value,
+  ...pickTemplateVariableMetadata(
+    template.variables?.[variable.variableIdentifier],
+  ),
+});
+
+/**
+ * Enriches a committed input with its template definition when an identifier is present.
+ */
+export const resolveInput = (
+  input: XOInvitationInput,
+  entityIdentifier: string,
+  template: XOTemplate,
+): ResolvedInvitationInput => ({
+  entityIdentifier,
+  ...input,
+  ...pickTemplateInputMetadata(
+    input.inputIdentifier
+      ? template.inputs?.[input.inputIdentifier]
+      : undefined,
+  ),
+});
+
+/**
+ * Enriches a committed output with its template definition when an identifier is present.
+ *
+ * Template metadata is spread after commit fields so display expressions (e.g.
+ * `valueSatoshis: "$(<totalSatoshis>)"`) layer on for the UI even when the merger
+ * already resolved a bigint for transaction encoding.
+ */
+export const resolveOutput = (
+  output: XOInvitationOutput,
+  entityIdentifier: string,
+  template: XOTemplate,
+): ResolvedInvitationOutput =>
+  ({
+    entityIdentifier,
+    ...output,
+    ...pickTemplateOutputMetadata(
+      output.outputIdentifier
+        ? template.outputs?.[output.outputIdentifier]
+        : undefined,
+    ),
+    // Template valueSatoshis may be a CashAssembly string while XOInvitationOutput
+    // expects bigint — the read model intentionally allows both for display.
+  }) as ResolvedInvitationOutput;
+
+/**
+ * Converts hex or binary invitation bytecode fields to hex strings for display.
+ */
+export const hexOrBinToHex = (value?: string | Uint8Array) => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return typeof value === "string" ? value : binToHex(value);
+};
+
+/**
+ * Normalizes a merged input row for UI display (hex strings, no encoding placeholders).
+ *
+ * The engine merger returns libauth-ready binary fields and fills in encoding
+ * defaults (empty unlocking bytecode, sequence 0) that are not useful in the TUI.
+ */
+export const normalizeMergedInputForDisplay = (input: XOInvitationInput) => {
+  const normalized = { ...input };
+
+  if (input.outpointTransactionHash !== undefined) {
+    normalized.outpointTransactionHash = hexOrBinToHex(
+      input.outpointTransactionHash,
+    ) as XOInvitationInput["outpointTransactionHash"];
+  }
+
+  if (input.unlockingBytecode !== undefined) {
+    // Engine uses an empty Uint8Array as a placeholder until the input is signed.
+    const isPlaceholder =
+      input.unlockingBytecode instanceof Uint8Array &&
+      input.unlockingBytecode.length === 0;
+
+    if (isPlaceholder) {
+      delete normalized.unlockingBytecode;
+    } else {
+      normalized.unlockingBytecode = hexOrBinToHex(
+        input.unlockingBytecode,
+      ) as XOInvitationInput["unlockingBytecode"];
+    }
+  }
+
+  // Default sequence from the merger is not meaningful for display.
+  if (normalized.sequenceNumber === 0) {
+    delete normalized.sequenceNumber;
+  }
+
+  return normalized;
+};
+
+/**
+ * Normalizes a merged output row for UI display (hex strings).
+ */
+export const normalizeMergedOutputForDisplay = (output: XOInvitationOutput) => {
+  const normalized = { ...output };
+
+  if (output.lockingBytecode !== undefined) {
+    normalized.lockingBytecode = hexOrBinToHex(
+      output.lockingBytecode,
+    ) as XOInvitationOutput["lockingBytecode"];
+  }
+
+  return normalized;
+};
+
+/**
+ * Recovers `outputIdentifier` from the source commit because the merger strips it
+ * after template resolution.
+ */
+export const findOutputIdentifierForMergedOutput = (
+  commit: XOInvitationCommit | undefined,
+  mergedOutput: XOInvitationOutput,
+) => {
+  const outputs = commit?.data?.outputs ?? [];
+  const mergedBytecodeHex = hexOrBinToHex(mergedOutput.lockingBytecode);
+
+  for (const commitOutput of outputs) {
+    if (commitOutput.outputIdentifier === undefined) {
+      continue;
+    }
+
+    const commitBytecodeHex = hexOrBinToHex(commitOutput.lockingBytecode);
+
+    // Match merged binary bytecode back to the committed row that carried the identifier.
+    if (
+      mergedBytecodeHex !== undefined &&
+      commitBytecodeHex !== undefined &&
+      mergedBytecodeHex === commitBytecodeHex
+    ) {
+      return commitOutput.outputIdentifier;
+    }
+  }
+
+  // Fall back when the commit has a single identified output (common case).
+  const outputsWithIdentifier = outputs.filter(
+    (commitOutput) => commitOutput.outputIdentifier !== undefined,
+  );
+
+  if (outputsWithIdentifier.length === 1) {
+    return outputsWithIdentifier[0]?.outputIdentifier;
+  }
+
+  return undefined;
+};
+
+/**
+ * Whether two invitation variable rows refer to the same template variable slot.
+ */
+export const matchesInvitationVariable = (
+  left: XOInvitationVariable,
+  right: XOInvitationVariable,
+) =>
+  left.variableIdentifier === right.variableIdentifier &&
+  left.roleIdentifier === right.roleIdentifier;
+
+/**
+ * Finds the entity that authored a merged variable by scanning invitation commits.
+ * Last matching commit in array order wins. Best-effort until the engine orders
+ * commits internally or exposes source attribution on merged variables.
+ */
+export const findVariableEntityIdentifier = (
+  variable: XOInvitationVariable,
+  commits: XOInvitationCommit[],
+) => {
+  let entityIdentifier = "";
+
+  // Merged variables do not carry sourceCommitIdentifier today; walk commits and
+  // let the last array match win (ordering deferred to the engine merger).
+  for (const commit of commits) {
+    for (const commitVariable of commit.data?.variables ?? []) {
+      if (matchesInvitationVariable(commitVariable, variable)) {
+        entityIdentifier = commit.entityIdentifier;
+      }
+    }
+  }
+
+  return entityIdentifier;
+};
+
+/**
+ * Returns template-enriched invitation data for UI display.
+ *
+ * Uses {@link mergeInvitationCommits} for inputs and outputs so `mergesWith`
+ * extensions and transaction indices are resolved. Variables come from the merged
+ * result and are enriched with template metadata. Commit ordering is delegated to
+ * the engine merger.
+ */
+export const resolveCommitReferences = (
+  invitation: XOInvitation,
+  template: XOTemplate,
+): ResolvedInvitationData => {
+  const commits = invitation.commits ?? [];
+  const commitsMap = new Map(
+    commits.map((commit) => [commit.commitIdentifier, commit]),
+  );
+
+  // Merge rather than flatten so mergesWith input extensions and transactionIndex
+  // ordering are handled by the engine (see signing flow in engine.append/sign).
+  const merged = mergeInvitationCommits(
+    invitation as Parameters<typeof mergeInvitationCommits>[0],
+    template,
+  );
+
+  if (merged === null) {
+    return {
+      invitationIdentifier: invitation.invitationIdentifier,
+      templateIdentifier: invitation.templateIdentifier,
+      actionIdentifier: invitation.actionIdentifier,
+      variables: [],
+      inputs: [],
+      outputs: [],
+    };
+  }
+
+  const variables = merged.variables.map((variable) =>
+    resolveVariable(
+      variable,
+      findVariableEntityIdentifier(variable, commits),
+      template,
+    ),
+  );
+
+  const inputs = merged.inputs.map((mergedInput) => {
+    const entityIdentifier =
+      commitsMap.get(mergedInput.sourceCommitIdentifier)?.entityIdentifier ??
+      "";
+    // Strip merger-only fields before normalization and template enrichment.
+    const {
+      sourceCommitIdentifier: _sourceCommitIdentifier,
+      mergesWith: _mergesWith,
+      ...input
+    } = mergedInput;
+
+    return resolveInput(
+      normalizeMergedInputForDisplay(input),
+      entityIdentifier,
+      template,
+    );
+  });
+
+  const outputs = merged.outputs.map((mergedOutput) => {
+    const commit = commitsMap.get(mergedOutput.sourceCommitIdentifier);
+    const entityIdentifier = commit?.entityIdentifier ?? "";
+    const {
+      sourceCommitIdentifier: _sourceCommitIdentifier,
+      mergesWith: _mergesWith,
+      ...output
+    } = mergedOutput;
+    const outputIdentifier = findOutputIdentifierForMergedOutput(
+      commit,
+      output,
+    );
+    // Re-attach outputIdentifier so pickTemplateOutputMetadata can resolve names/roles.
+    const outputForDisplay = normalizeMergedOutputForDisplay(
+      outputIdentifier !== undefined ? { ...output, outputIdentifier } : output,
+    );
+
+    return resolveOutput(outputForDisplay, entityIdentifier, template);
+  });
+
+  return {
+    invitationIdentifier: invitation.invitationIdentifier,
+    templateIdentifier: invitation.templateIdentifier,
+    actionIdentifier: invitation.actionIdentifier,
+    variables,
+    inputs,
+    outputs,
+  };
+};

src/utils/sync-server.ts

@@ -1,9 +1,15 @@
 import type { XOInvitation } from "@xo-cash/types";
 import { EventEmitter } from "./event-emitter.js";
-// import { SSESession, type SSEvent } from "./sse-client.js";
 import { SSESession, type SSEvent } from "@xo-cash/utils";
 import { deserializeInvitation, serializeInvitation } from "@xo-cash/engine";
 
+function stripLocalInvitationMetadata(invitation: XOInvitation): XOInvitation {
+  const { entityIdentifier: _entityIdentifier, ...sharedInvitation } =
+    invitation as XOInvitation & { entityIdentifier?: string };
+
+  return sharedInvitation;
+}
+
 export type SyncServerEventMap = {
   connected: void;
   disconnected: void;
@@ -21,62 +27,66 @@ export class SyncServer extends EventEmitter<SyncServerEventMap> {
     return server;
   }
 
-  private sse: SSESession;
+  private sse: SSESession | null = null;
 
   constructor(
     private readonly baseUrl: string,
     private readonly invitationIdentifier: string,
   ) {
     super();
+  }
 
-    // Create an SSE Session
+  async connect(): Promise<void> {
-    this.sse = new SSESession(
+    if (this.sse) {
-      `${baseUrl}/invitations?invitationIdentifier=${invitationIdentifier}`,
+      await this.sse.connect();
+      return;
+    }
+
+    await this.createSSESession();
+  }
+
+  async disconnect(): Promise<void> {
+    await this.sse?.disconnect();
+    this.sse = null;
+  }
+
+  private async createSSESession(): Promise<void> {
+    const sse = await SSESession.create(
+      `${this.baseUrl}/invitations?invitationIdentifier=${encodeURIComponent(this.invitationIdentifier)}`,
       {
         method: "GET",
         headers: {
           Accept: "text/event-stream",
         },
-
+        persistent: true,
-        // Create our event bubblers
+        onRequest: async (request) => {
-        onError: (error: unknown) =>
+          const { body: _body, ...requestWithoutBody } = request;
+          return requestWithoutBody;
+        },
+        onError: (error: unknown) => {
           this.emit(
             "error",
             error instanceof Error ? error : new Error(String(error)),
-          ),
+          );
-        onDisconnected: () => this.emit("disconnected", undefined),
+        },
-        onConnected: () => this.emit("connected", undefined),
+        onDisconnected: () => {
+          this.emit("disconnected", undefined);
+        },
+        onConnected: () => {
+          this.emit("connected", undefined);
+        },
       },
     );
 
-    this.sse.on("message", (event: SSEvent) => this.emit("message", event));
+    this.sse = sse;
+    sse.on("message", (event: SSEvent) => {
+      this.emit("message", event);
+    });
   }
 
-  /**
-   * Connect to the sync server.
-   */
-  async connect(): Promise<void> {
-    // Connect to the SSE Session
-    await this.sse.connect();
-  }
-
-  /**
-   * Disconnect from the sync server.
-   */
-  async disconnect(): Promise<void> {
-    // Disconnect from the SSE Session
-    await this.sse.disconnect();
-  }
-
-  /**
-   * Get the invitation by identifier.
-   * @param identifier - The invitation identifier.
-   * @returns The invitation.
-   */
   async getInvitation(identifier: string): Promise<XOInvitation | undefined> {
-    // Send a GET request to the sync server
     const response = await fetch(
-      `${this.baseUrl}/invitations?invitationIdentifier=${identifier}`,
+      `${this.baseUrl}/invitations?invitationIdentifier=${encodeURIComponent(identifier)}`,
     );
 
     if (!response.ok) {
@@ -84,33 +94,23 @@ export class SyncServer extends EventEmitter<SyncServerEventMap> {
     }
 
     const invitation = deserializeInvitation(await response.text());
-    return invitation;
+    return stripLocalInvitationMetadata(invitation);
   }
 
-  /**
-   * Publish an invitation.
-   * @param invitation - The invitation to create.
-   * @returns The invitation.
-   */
   async publishInvitation(invitation: XOInvitation): Promise<XOInvitation> {
-    // Send a POST request to the sync server
     const response = await fetch(`${this.baseUrl}/invitations`, {
       method: "POST",
-      body: serializeInvitation(invitation),
+      body: serializeInvitation(stripLocalInvitationMetadata(invitation)),
       headers: {
         "Content-Type": "application/json",
       },
     });
 
-    // Throw is there was an issue with the request
     if (!response.ok) {
       throw new Error(`Failed to publish invitation: ${response.statusText}`);
     }
 
-    // Read the returned JSON
-    // TODO: This should use zod to verify the response
     const data = deserializeInvitation(await response.text());
-
+    return stripLocalInvitationMetadata(data);
-    return data;
   }
 }

src/utils/template-module-loader.ts

@@ -27,8 +27,7 @@ try {
   const template = pickTemplateExport(loadedModule);
   process.stdout.write(serializeTemplate(template as XOTemplate));
 } catch (error) {
-  const message =
+  const message = error instanceof Error ? error.message : String(error);
-    error instanceof Error ? error.message : String(error);
   console.error(`Failed to load template module: ${message}`);
   process.exit(1);
 }

src/utils/template-utils.ts

@@ -188,13 +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 || '',
+      roleId: entry.role || "",
-      name: roleObj?.name || entry.role || '',
+      name: roleObj?.name || entry.role || "",
       description: roleObj?.description,
     };
   });

src/utils/utxo-metadata.ts

@@ -9,7 +9,8 @@ export type UnspentOutputMetadata = {
   outputIdentifier?: string;
 };
 
-export type UnspentOutputWithMetadata = UnspentOutputData & UnspentOutputMetadata;
+export type UnspentOutputWithMetadata = UnspentOutputData &
+  UnspentOutputMetadata;
 
 /**
  * Builds a lookup map from script hash to its stored metadata.

tests/cli/autocomplete-completions.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  generateBashCompletions,
+  generateFishCompletions,
+  generateZshCompletions,
+  installCompletions,
+} from "../../src/cli/autocomplete/completions";
+
+describe("shell completions", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const tempDir of tempDirs) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+    tempDirs.length = 0;
+  });
+
+  function createConfigFile(contents = ""): string {
+    const tempDir = mkdtempSync(join(tmpdir(), "xo-cli-completions-test-"));
+    tempDirs.push(tempDir);
+    const configFile = join(tempDir, "shellrc");
+    writeFileSync(configFile, contents);
+    return configFile;
+  }
+
+  test("uses shell-native mnemonic completion in bash", () => {
+    const completions = generateBashCompletions("xo-cli");
+
+    expect(completions).toContain(
+      'local config_dir="${XO_CONFIG_DIR:-${HOME}/.config/xo-cli}"',
+    );
+    expect(completions).toContain('__xo_complete_mnemonics "${cur}"');
+    expect(completions).not.toContain('__xo_complete mnemonics "${cur}"');
+  });
+
+  test("uses shell-native mnemonic completion in zsh", () => {
+    const completions = generateZshCompletions("xo-cli");
+
+    expect(completions).toContain(
+      'local config_dir="${XO_CONFIG_DIR:-${HOME}/.config/xo-cli}"',
+    );
+    expect(completions).toContain(
+      '__xo_complete_mnemonics "${words[CURRENT]}"',
+    );
+    expect(completions).not.toContain(
+      '__xo_complete mnemonics "${words[CURRENT]}"',
+    );
+  });
+
+  test("uses shell-native mnemonic completion in fish", () => {
+    const completions = generateFishCompletions("xo-cli");
+
+    expect(completions).toContain('set -l config_dir "$XO_CONFIG_DIR"');
+    expect(completions).toContain("(__xo_cli_complete_mnemonics)");
+    expect(completions).not.toContain("(__xo_cli_complete_dynamic mnemonics)");
+  });
+
+  test("installs the config default and completion loader once", () => {
+    const configFile = createConfigFile();
+
+    expect(installCompletions("bash", "xo-cli", configFile)).toBe(true);
+    expect(installCompletions("bash", "xo-cli", configFile)).toBe(false);
+
+    const contents = readFileSync(configFile, "utf8");
+    expect(contents.match(/XO_CONFIG_DIR/g)).toHaveLength(2);
+    expect(
+      contents.match(/eval "\$\(xo-cli completions bash\)"/g),
+    ).toHaveLength(1);
+  });
+
+  test("adds a missing default without duplicating an existing loader", () => {
+    const configFile = createConfigFile('eval "$(xo-cli completions bash)"\n');
+
+    expect(installCompletions("bash", "xo-cli", configFile)).toBe(true);
+
+    const contents = readFileSync(configFile, "utf8");
+    expect(
+      contents.match(/eval "\$\(xo-cli completions bash\)"/g),
+    ).toHaveLength(1);
+    expect(contents).toContain(
+      'export XO_CONFIG_DIR="${XO_CONFIG_DIR:-$HOME/.config/xo-cli}"',
+    );
+  });
+
+  test("preserves an existing custom config directory assignment", () => {
+    const configFile = createConfigFile(
+      "export XO_CONFIG_DIR=/tmp/custom-xo\n",
+    );
+
+    expect(installCompletions("zsh", "xo-cli", configFile)).toBe(true);
+
+    const contents = readFileSync(configFile, "utf8");
+    expect(contents).toContain("export XO_CONFIG_DIR=/tmp/custom-xo");
+    expect(contents).not.toContain("${XO_CONFIG_DIR:-$HOME/.config/xo-cli}");
+    expect(contents).toContain('eval "$(xo-cli completions zsh)"');
+  });
+
+  test("uses fish syntax when installing fish completions", () => {
+    const configFile = createConfigFile();
+
+    expect(installCompletions("fish", "xo-cli", configFile)).toBe(true);
+
+    const contents = readFileSync(configFile, "utf8");
+    expect(contents).toContain(
+      'set -q XO_CONFIG_DIR; or set -gx XO_CONFIG_DIR "$HOME/.config/xo-cli"',
+    );
+    expect(contents).toContain("xo-cli completions fish | source");
+  });
+});

tests/cli/commands/settings.test.ts

@@ -57,7 +57,9 @@ describe("settings command", () => {
       {},
     );
 
-    const persisted = JSON.parse(readFileSync(paths.walletConfigPath, "utf8")) as {
+    const persisted = JSON.parse(
+      readFileSync(paths.walletConfigPath, "utf8"),
+    ) as {
       currency: string;
       "default-mnemonic"?: string;
     };

tests/cli/commands/template.test.ts

@@ -103,7 +103,7 @@ const testCases: TestCase[] = [
     inputs: ["export", p2pkhTemplateIdentifier],
     shouldThrow: false,
     expectedData: {},
-    logs: [{ out: "\"name\":\"Wallet (P2PKH)\"" }],
+    logs: [{ out: '"name":"Wallet (P2PKH)"' }],
   },
   // Error cases - subcommand
   {

tests/cli/mnemonic.test.ts

@@ -113,7 +113,9 @@ describe("mnemonic utilities", () => {
 
         // Due to some weird MacOS behavior we need to use realpathSync to get the correct path
         // Basically, tmpDir() returns a symlink, but moving to that path puts us at `/private/${tmpDir()}`
-        const expectedPath = realpathSync(path.join(tempDir, "mnemonic-relative"));
+        const expectedPath = realpathSync(
+          path.join(tempDir, "mnemonic-relative"),
+        );
 
         // Compare to the expected path
         expect(resolved).toBe(expectedPath);

tests/cli/mocks/engine.ts

@@ -159,7 +159,9 @@ export const createMockEngine = async (seed: string) => {
 };
 
 export const createMockAppService = async (engine: Engine) => {
-  const settings = new SettingsService(`${tmpdir()}/xo-cli-tests-settings.json`);
+  const settings = new SettingsService(
+    `${tmpdir()}/xo-cli-tests-settings.json`,
+  );
   settings.setCurrency("USD");
 
   const storage = await InMemoryStorage.create();

tests/cli/mocks/rates-service.ts

@@ -5,7 +5,10 @@ export class MockRatesService extends BaseRates {
     super();
   }
 
-  async getRate(numeratorUnitCode: string, denominatorUnitCode: string): Promise<number> {
+  async getRate(
+    numeratorUnitCode: string,
+    denominatorUnitCode: string,
+  ): Promise<number> {
     return 1;
   }
 

tests/cli/paths.test.ts

@@ -1,5 +1,11 @@
 import { expect, test, describe, beforeEach, afterEach } from "vitest";
-import { existsSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  realpathSync,
+} from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 
@@ -12,6 +18,20 @@ import {
 } from "../../src/utils/paths";
 
 describe("paths utilities", () => {
+  const originalConfigDir = process.env["XO_CONFIG_DIR"];
+
+  beforeEach(() => {
+    delete process.env["XO_CONFIG_DIR"];
+  });
+
+  afterEach(() => {
+    if (originalConfigDir === undefined) {
+      delete process.env["XO_CONFIG_DIR"];
+    } else {
+      process.env["XO_CONFIG_DIR"] = originalConfigDir;
+    }
+  });
+
   describe("getConfigDir", () => {
     test("returns path under ~/.config/xo-cli", () => {
       const configDir = getConfigDir();
@@ -24,6 +44,26 @@ describe("paths utilities", () => {
 
       expect(existsSync(configDir)).toBe(true);
     });
+
+    test("uses XO_CONFIG_DIR when configured", () => {
+      const customDir = path.join(tmpdir(), `xo-cli-config-test-${Date.now()}`);
+      process.env["XO_CONFIG_DIR"] = customDir;
+
+      try {
+        expect(getConfigDir()).toBe(customDir);
+        expect(getMnemonicsDir()).toBe(path.join(customDir, "mnemonics"));
+        expect(getDataDir()).toBe(path.join(customDir, "data"));
+        expect(getWalletConfigPath()).toBe(path.join(customDir, ".wallet"));
+      } finally {
+        rmSync(customDir, { recursive: true, force: true });
+      }
+    });
+
+    test("uses the default when XO_CONFIG_DIR is empty", () => {
+      process.env["XO_CONFIG_DIR"] = "";
+
+      expect(getConfigDir()).toBe(path.join(homedir(), ".config", "xo-cli"));
+    });
   });
 
   describe("getMnemonicsDir", () => {
@@ -96,7 +136,9 @@ describe("paths utilities", () => {
 
         // Due to some weird MacOS behavior we need to use realpathSync to get the correct path
         // Basically, tmpDir() returns a symlink, but moving to that path puts us at `/private/${tmpDir()}`
-        const expectedPath = realpathSync(path.join(tempDir, "mnemonic-cwd-test"));
+        const expectedPath = realpathSync(
+          path.join(tempDir, "mnemonic-cwd-test"),
+        );
 
         // Compare to the expected path
         expect(resolved).toBe(expectedPath);
@@ -106,6 +148,7 @@ describe("paths utilities", () => {
     });
 
     test("resolves from global mnemonics dir when file exists there", () => {
+      process.env["XO_CONFIG_DIR"] = tempDir;
       const mnemonicsDir = getMnemonicsDir();
       const testFile = path.join(mnemonicsDir, "mnemonic-global-test");
 

tests/tui/format-dialog-message.test.ts

@@ -21,7 +21,7 @@ describe("formatDialogMessageLines", () => {
 
   test("breaks long dot-separated paths at segment boundaries", () => {
     const line =
-      "- actions.requestFungibleTokens.roles.receiver.requirements: Unrecognized key: \"generate\"";
+      '- actions.requestFungibleTokens.roles.receiver.requirements: Unrecognized key: "generate"';
     const lines = formatDialogMessageLines(line, 56);
 
     expect(lines.length).toBeGreaterThan(1);

tests/utils/resolve-invitation-data.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it } from "vitest";
+import type { XOInvitation } from "@xo-cash/types";
+
+import { vendingMachineTemplate } from "../../src/templates/vending-machine.js";
+import { resolveCommitReferences } from "../../src/utils/resolve-invitation-data.js";
+
+const MERCHANT_ENTITY =
+  "xpub6EUk69HMQk83Ay3QEFWhYgvqLvT6tGTnzWK33fao2fvnDyzhbBeoSc6JbQkvnKq33bH7HjqQmZ9H29hsesC53ZgxQfGBadBZL5jmSa7kbTD";
+const CUSTOMER_ENTITY =
+  "xpub6FHRsCb1ma6VFGZpRYZL8A3X1Gwwc8JjRcaDJR2vgirrttmdvJX5VNYceA84RDVjy1c2a2oYEwuayLDZ9gssDgU52UXDGFTDa19z5ceXfFh";
+
+/**
+ * Minimal reproduction of OriginalInvitation.json for the vending machine flow.
+ */
+const originalInvitation: XOInvitation = {
+  invitationIdentifier: "c57b1f8f8534df28b359e323c5fbd5ba",
+  createdAtTimestamp: 1779488689379,
+  templateIdentifier:
+    "feadd05c6566c5eded68f321efe7150cb765fda070d027c89f285e5b42a00652",
+  actionIdentifier: "purchaseItems",
+  commits: [
+    {
+      commitIdentifier: "76b935a35ca45f1065f9c66769d1a957",
+      previousCommitIdentifier: undefined,
+      entityIdentifier: MERCHANT_ENTITY,
+      data: {},
+      signature:
+        "5f487c045657f3939ecfeaaacf239a7cfd44b485c2be591f5280bf0cc3a6e5fe304e8ea23311d82b2afa4f0ad7e0a6d07ec1e0b1aaee9c44097613694390966b",
+      expiresAtTimestamp: 1779506689379,
+    },
+    {
+      commitIdentifier: "cbf2d6242144f6761d0efc3bbbbf6660",
+      previousCommitIdentifier: "76b935a35ca45f1065f9c66769d1a957",
+      entityIdentifier: MERCHANT_ENTITY,
+      data: {
+        variables: [
+          {
+            variableIdentifier: "totalSatoshis",
+            roleIdentifier: "merchant",
+            value: 3000,
+          },
+          {
+            variableIdentifier: "orderId",
+            roleIdentifier: "merchant",
+            value: "eb5a30b3-ec8c-4b81-89dd-c53371f55a0e",
+          },
+          {
+            variableIdentifier: "merchantName",
+            roleIdentifier: "merchant",
+            value: "XO Snack Machine",
+          },
+          {
+            variableIdentifier: "receiptSummary",
+            roleIdentifier: "merchant",
+            value: "2× Chips",
+          },
+          {
+            variableIdentifier: "lineItemsJson",
+            roleIdentifier: "merchant",
+            value:
+              '[{"id":"225e37f4-14f2-4b33-86fd-763018bbfd7c","name":"Chips","quantity":2,"price":1500}]',
+          },
+        ],
+      },
+      signature:
+        "7cfc53860ec81403a79a03521a7674ee8d2a11365ee031e4f7f2e36a045bd6e2999510264b29045582a74e1190f0176950a855361f02bc67ff7877fabcf794f4",
+      expiresAtTimestamp: 1779506689390,
+    },
+    {
+      commitIdentifier: "583208aa304c0aa9841d1400efe6b6aa",
+      previousCommitIdentifier: "cbf2d6242144f6761d0efc3bbbbf6660",
+      entityIdentifier: MERCHANT_ENTITY,
+      data: {
+        outputs: [
+          {
+            outputIdentifier: "purchaseOutput",
+            lockingBytecode:
+              "76a9146a4715fe1cc1ce228336502f1711b06045ef361088ac",
+          },
+        ],
+      },
+      signature:
+        "d9bdd3b24fef6afd13f12da92e832672c6c1b83fb372506faeb7fa4ea0e39e3a32ad74493fbe7a393aed58bc18226431dabae09948ce371ad3f77b0219cb3831",
+      expiresAtTimestamp: 1779506689412,
+    },
+    {
+      commitIdentifier: "4f3f9a3361c8070ab589cc44248a6a80",
+      previousCommitIdentifier: "583208aa304c0aa9841d1400efe6b6aa",
+      entityIdentifier: CUSTOMER_ENTITY,
+      data: {},
+      signature:
+        "63be8af81622da4fccc7eb6b81c6174879fe6aa113b8dae794bd42d4d5c87ae550a18be1e6cb5edf231e774bdc7883eb5a78bd02188579dce58da0d449c43865",
+      expiresAtTimestamp: 1779506979194,
+    },
+    {
+      commitIdentifier: "d18b9a0caa638eaa1d0711f333e9c114",
+      previousCommitIdentifier: "4f3f9a3361c8070ab589cc44248a6a80",
+      entityIdentifier: CUSTOMER_ENTITY,
+      data: {
+        inputs: [
+          {
+            outpointTransactionHash:
+              "b1e8f77cdc60efac19f668fc5c7177ace42a46e2532f230979559c7190c3c80a",
+            outpointIndex: 1,
+          },
+        ],
+      },
+      signature:
+        "e36942eb5f147e620659d20b7059630da871944e74fe5ffb3c4ff0298a5aedb101bc7468b19750114cbcfa56b99bd4a080453a31084f18173adcd9442fca4303",
+      expiresAtTimestamp: 1779507006272,
+    },
+    {
+      commitIdentifier: "7823f7ae7a365f87f6acdfee8896f508",
+      previousCommitIdentifier: "d18b9a0caa638eaa1d0711f333e9c114",
+      entityIdentifier: CUSTOMER_ENTITY,
+      data: {
+        outputs: [
+          {
+            valueSatoshis: 74881n,
+            lockingBytecode:
+              "76a9141730ca066d4b9c8d542f8c9bdce645f77697d46088ac",
+          },
+        ],
+      },
+      signature:
+        "2c1d1ed1259a2e4b1bc7187b93029e99e590a4e92ff9c39031319766b7fbcdabab9c3dc20b3d27d05eee198cbc717b9aedfbef92bd3e519c62c60e4731bd936a",
+      expiresAtTimestamp: 1779507008169,
+    },
+  ],
+};
+
+/**
+ * Customer input commit extended with unlocking bytecode via mergesWith (signing flow).
+ */
+const invitationWithSignedInput: XOInvitation = {
+  ...originalInvitation,
+  commits: [
+    ...originalInvitation.commits.slice(0, 5),
+    {
+      commitIdentifier: "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+      previousCommitIdentifier: "d18b9a0caa638eaa1d0711f333e9c114",
+      entityIdentifier: CUSTOMER_ENTITY,
+      data: {
+        inputs: [
+          {
+            mergesWith: {
+              commitIdentifier: "d18b9a0caa638eaa1d0711f333e9c114",
+              index: 0,
+            },
+            unlockingBytecode:
+              "41226b2be7c2890c8bbde2f79e79640e56d866843f2e822ec51c469019d13db0",
+          },
+        ],
+      },
+      signature:
+        "3045022001a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456789022100fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
+      expiresAtTimestamp: 1779507008000,
+    },
+  ],
+};
+
+describe("resolveCommitReferences", () => {
+  it("flattens commits and enriches items with template metadata", () => {
+    const resolved = resolveCommitReferences(
+      originalInvitation,
+      vendingMachineTemplate,
+    );
+
+    expect(resolved).toEqual({
+      invitationIdentifier: "c57b1f8f8534df28b359e323c5fbd5ba",
+      templateIdentifier:
+        "feadd05c6566c5eded68f321efe7150cb765fda070d027c89f285e5b42a00652",
+      actionIdentifier: "purchaseItems",
+      variables: [
+        {
+          entityIdentifier: MERCHANT_ENTITY,
+          name: "Total Price",
+          description: "Total purchase price in satoshis",
+          type: "integer",
+          hint: "satoshis",
+          variableIdentifier: "totalSatoshis",
+          roleIdentifier: "merchant",
+          value: 3000,
+        },
+        {
+          entityIdentifier: MERCHANT_ENTITY,
+          name: "Order ID",
+          description: "Unique order identifier",
+          type: "string",
+          variableIdentifier: "orderId",
+          roleIdentifier: "merchant",
+          value: "eb5a30b3-ec8c-4b81-89dd-c53371f55a0e",
+        },
+        {
+          entityIdentifier: MERCHANT_ENTITY,
+          name: "Merchant Name",
+          description: "Display name of the vending machine",
+          type: "string",
+          variableIdentifier: "merchantName",
+          roleIdentifier: "merchant",
+          value: "XO Snack Machine",
+        },
+        {
+          entityIdentifier: MERCHANT_ENTITY,
+          name: "Receipt Summary",
+          description: "Human-readable list of purchased items",
+          type: "string",
+          variableIdentifier: "receiptSummary",
+          roleIdentifier: "merchant",
+          value: "2× Chips",
+        },
+        {
+          entityIdentifier: MERCHANT_ENTITY,
+          name: "Line Items",
+          description: "JSON-encoded line items for the purchase",
+          type: "string",
+          variableIdentifier: "lineItemsJson",
+          roleIdentifier: "merchant",
+          value:
+            '[{"id":"225e37f4-14f2-4b33-86fd-763018bbfd7c","name":"Chips","quantity":2,"price":1500}]',
+        },
+      ],
+      inputs: [
+        {
+          entityIdentifier: CUSTOMER_ENTITY,
+          outpointTransactionHash:
+            "b1e8f77cdc60efac19f668fc5c7177ace42a46e2532f230979559c7190c3c80a",
+          outpointIndex: 1,
+        },
+      ],
+      outputs: [
+        {
+          entityIdentifier: MERCHANT_ENTITY,
+          outputIdentifier: "purchaseOutput",
+          lockingBytecode: "76a9146a4715fe1cc1ce228336502f1711b06045ef361088ac",
+          name: "Purchase Payment",
+          description: "$(<totalSatoshis>) sats to $(<merchantName>)",
+          icon: "request",
+          roles: {
+            merchant: {
+              name: "Payment Received",
+              description:
+                "Received $(<totalSatoshis>) sats for $(<receiptSummary>)",
+            },
+            customer: {
+              name: "Payment Sent",
+              description:
+                "Sent $(<totalSatoshis>) sats for $(<receiptSummary>)",
+            },
+          },
+          lockingScript: "merchantReceivingLockingScript",
+          valueSatoshis: "$(<totalSatoshis>)",
+          token: null,
+        },
+        {
+          entityIdentifier: CUSTOMER_ENTITY,
+          valueSatoshis: 74881n,
+          lockingBytecode: "76a9141730ca066d4b9c8d542f8c9bdce645f77697d46088ac",
+        },
+      ],
+    });
+  });
+
+  it("leaves unidentified inputs and outputs without template metadata", () => {
+    const resolved = resolveCommitReferences(
+      originalInvitation,
+      vendingMachineTemplate,
+    );
+
+    expect(resolved.inputs[0]).not.toHaveProperty("name");
+    expect(resolved.outputs[1]).not.toHaveProperty("name");
+    expect(resolved.outputs[1]).not.toHaveProperty("outputIdentifier");
+  });
+
+  it("merges input extension commits via mergesWith into a single input", () => {
+    const resolved = resolveCommitReferences(
+      invitationWithSignedInput,
+      vendingMachineTemplate,
+    );
+
+    expect(resolved.inputs).toHaveLength(1);
+    expect(resolved.inputs[0]).toMatchObject({
+      entityIdentifier: CUSTOMER_ENTITY,
+      outpointTransactionHash:
+        "b1e8f77cdc60efac19f668fc5c7177ace42a46e2532f230979559c7190c3c80a",
+      outpointIndex: 1,
+      unlockingBytecode:
+        "41226b2be7c2890c8bbde2f79e79640e56d866843f2e822ec51c469019d13db0",
+    });
+  });
+});