naracli 1.0.32 → 1.0.40

package/src/cli/utils/agent-config.ts

@@ -1,50 +1,155 @@
 /**
- * Agent config utilities - read/write ~/.config/nara/agent.json
+ * Agent config utilities
+ *
+ * Global config:  ~/.config/nara/config.json        — rpc_url, wallet
+ * Network config: ~/.config/nara/agent-{network}.json — agent_ids, zk_ids
+ *
+ * {network} is derived from the effective RPC URL:
+ *   https://mainnet-api.nara.build/ → mainnet-api-nara-build
+ *   https://devnet-api.nara.build/  → devnet-api-nara-build
+ *   http://127.0.0.1:8899/          → 127-0-0-1-8899
  */
 
-import { join, dirname } from "node:path";
+import { join } from "node:path";
 import { homedir } from "node:os";
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { DEFAULT_RPC_URL } from "nara-sdk";
 
-const AGENT_CONFIG_PATH = join(homedir(), ".config", "nara", "agent.json");
+const CONFIG_DIR = join(homedir(), ".config", "nara");
+const GLOBAL_CONFIG_PATH = join(CONFIG_DIR, "config.json");
 
-export interface AgentConfig {
-  agent_ids: string[];
-  zk_ids: string[];
+// ─── URL → filename ─────────────────────────────────────────────
+
+export function rpcUrlToNetworkName(url: string): string {
+  let name = url.replace(/^https?:\/\//, "");
+  name = name.replace(/\/+$/, "");
+  name = name.replace(/[^a-zA-Z0-9-]/g, "-");
+  name = name.replace(/-+/g, "-");
+  name = name.replace(/^-|-$/g, "");
+  return name;
+}
+
+function networkConfigPath(rpcUrl: string): string {
+  return join(CONFIG_DIR, `agent-${rpcUrlToNetworkName(rpcUrl)}.json`);
+}
+
+// ─── Global config (rpc_url, wallet) ─────────────────────────────
+
+export interface GlobalConfig {
   rpc_url?: string;
   wallet?: string;
 }
 
-const DEFAULT_CONFIG: AgentConfig = { agent_ids: [], zk_ids: [] };
+export function loadGlobalConfig(): GlobalConfig {
+  try {
+    const raw = readFileSync(GLOBAL_CONFIG_PATH, "utf-8");
+    const parsed = JSON.parse(raw);
+    return {
+      rpc_url: parsed.rpc_url ?? undefined,
+      wallet: parsed.wallet ?? undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function saveGlobalConfig(config: GlobalConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(GLOBAL_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+}
+
+/**
+ * Get the effective RPC URL (without CLI flag context).
+ * For use when no CLI flag is available.
+ */
+export function getConfiguredRpcUrl(): string {
+  const global = loadGlobalConfig();
+  return global.rpc_url || DEFAULT_RPC_URL;
+}
+
+// ─── Network config (agent_ids, zk_ids) ──────────────────────────
+
+export interface NetworkConfig {
+  agent_ids: string[];
+  zk_ids: string[];
+}
+
+const DEFAULT_NETWORK_CONFIG: NetworkConfig = { agent_ids: [], zk_ids: [] };
 
-export function loadAgentConfig(): AgentConfig {
+/**
+ * Load network-specific config.
+ * @param rpcUrl - effective RPC URL (determines which file to load)
+ */
+export function loadNetworkConfig(rpcUrl?: string): NetworkConfig {
+  const url = rpcUrl || getConfiguredRpcUrl();
+  const path = networkConfigPath(url);
   try {
-    const raw = readFileSync(AGENT_CONFIG_PATH, "utf-8");
+    const raw = readFileSync(path, "utf-8");
     const parsed = JSON.parse(raw);
     return {
       agent_ids: Array.isArray(parsed.agent_ids) ? parsed.agent_ids : [],
       zk_ids: Array.isArray(parsed.zk_ids) ? parsed.zk_ids : [],
-      rpc_url: parsed.rpc_url ?? undefined,
-      wallet: parsed.wallet ?? undefined,
     };
   } catch {
-    return { ...DEFAULT_CONFIG };
+    return { ...DEFAULT_NETWORK_CONFIG };
   }
 }
 
-export function saveAgentConfig(config: AgentConfig): void {
-  mkdirSync(dirname(AGENT_CONFIG_PATH), { recursive: true });
-  writeFileSync(AGENT_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+/**
+ * Save network-specific config.
+ */
+export function saveNetworkConfig(config: NetworkConfig, rpcUrl?: string): void {
+  const url = rpcUrl || getConfiguredRpcUrl();
+  const path = networkConfigPath(url);
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
 }
 
-export function addAgentId(id: string): void {
-  const config = loadAgentConfig();
+// ─── Convenience helpers ─────────────────────────────────────────
+
+export function addAgentId(id: string, rpcUrl?: string): void {
+  const config = loadNetworkConfig(rpcUrl);
   config.agent_ids = [id, ...config.agent_ids.filter((x) => x !== id)];
-  saveAgentConfig(config);
+  saveNetworkConfig(config, rpcUrl);
 }
 
-export function addZkId(name: string): void {
-  const config = loadAgentConfig();
+export function addZkId(name: string, rpcUrl?: string): void {
+  const config = loadNetworkConfig(rpcUrl);
   config.zk_ids = [name, ...config.zk_ids.filter((x) => x !== name)];
-  saveAgentConfig(config);
+  saveNetworkConfig(config, rpcUrl);
+}
+
+// ─── Migration: import old agent.json if network config doesn't exist ──
+
+const LEGACY_CONFIG_PATH = join(CONFIG_DIR, "agent.json");
+
+export function migrateIfNeeded(rpcUrl?: string): void {
+  const url = rpcUrl || getConfiguredRpcUrl();
+  const path = networkConfigPath(url);
+  if (existsSync(path)) return;
+  if (!existsSync(LEGACY_CONFIG_PATH)) return;
+
+  try {
+    const raw = readFileSync(LEGACY_CONFIG_PATH, "utf-8");
+    const parsed = JSON.parse(raw);
+
+    // Migrate network-specific fields
+    const networkConfig: NetworkConfig = {
+      agent_ids: Array.isArray(parsed.agent_ids) ? parsed.agent_ids : [],
+      zk_ids: Array.isArray(parsed.zk_ids) ? parsed.zk_ids : [],
+    };
+    saveNetworkConfig(networkConfig, url);
+
+    // Migrate global fields if config.json doesn't exist
+    if (!existsSync(GLOBAL_CONFIG_PATH)) {
+      const globalConfig: GlobalConfig = {};
+      if (parsed.rpc_url) globalConfig.rpc_url = parsed.rpc_url;
+      if (parsed.wallet) globalConfig.wallet = parsed.wallet;
+      if (Object.keys(globalConfig).length > 0) {
+        saveGlobalConfig(globalConfig);
+      }
+    }
+  } catch {
+    // Ignore migration errors
+  }
 }

package/src/cli/utils/wallet.ts

@@ -6,7 +6,7 @@ import { Keypair } from "@solana/web3.js";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { DEFAULT_RPC_URL } from "nara-sdk";
-import { loadAgentConfig } from "./agent-config";
+import { loadGlobalConfig, migrateIfNeeded } from "./agent-config";
 
 const DEFAULT_WALLET_PATH = join(homedir(), ".config", "nara", "id.json");
 
@@ -22,13 +22,13 @@ function resolvePath(p: string): string {
  *
  * Priority:
  * 1. CLI flag (walletPath parameter)
- * 2. Config file (~/.config/nara/agent.json wallet field)
+ * 2. Global config (~/.config/nara/config.json wallet field)
  * 3. Default path (~/.config/nara/id.json)
  */
 export async function loadWallet(walletPath?: string): Promise<Keypair> {
   let path = walletPath;
   if (!path) {
-    const config = loadAgentConfig();
+    const config = loadGlobalConfig();
     path = config.wallet ? resolvePath(config.wallet) : DEFAULT_WALLET_PATH;
   } else {
     path = resolvePath(path);
@@ -64,11 +64,13 @@ export async function loadWallet(walletPath?: string): Promise<Keypair> {
  *
  * Priority:
  * 1. CLI flag (rpcUrl parameter)
- * 2. Config file (~/.config/nara/agent.json rpc_url field)
+ * 2. Global config (~/.config/nara/config.json rpc_url field)
  * 3. Default (from SDK constants)
+ *
+ * Also triggers migration from legacy agent.json if needed.
  */
 export function getRpcUrl(rpcUrl?: string): string {
-  if (rpcUrl) return rpcUrl;
-  const config = loadAgentConfig();
-  return config.rpc_url || DEFAULT_RPC_URL;
+  const effective = rpcUrl || loadGlobalConfig().rpc_url || DEFAULT_RPC_URL;
+  migrateIfNeeded(effective);
+  return effective;
 }

package/src/tests/agent.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for `agent` CLI commands
+ *
+ * - Help / validation tests run without wallet or chain
+ * - On-chain tests require wallet + NARA balance
+ *
+ * Run: npm run test:agent-cli
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { runCli, hasWallet } from "./helpers.js";
+
+// ─── Help output ──────────────────────────────────────────────────
+
+describe("agent --help", () => {
+  it("shows all subcommands", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "--help"]);
+    assert.equal(exitCode, 0);
+    for (const cmd of [
+      "register", "get", "set-bio", "set-metadata",
+      "upload-memory", "memory", "transfer", "close-buffer",
+      "delete", "set-referral", "log",
+    ]) {
+      assert.ok(stdout.includes(cmd), `missing subcommand: ${cmd}`);
+    }
+  });
+
+  it("agent register --help shows --referral option", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "register", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("--referral"));
+    assert.ok(stdout.includes("<agent-id>"));
+  });
+
+  it("agent set-referral --help shows both args", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "set-referral", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<agent-id>"));
+    assert.ok(stdout.includes("<referral-agent-id>"));
+  });
+
+  it("agent log --help shows --model and --referral", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "log", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("--model"));
+    assert.ok(stdout.includes("--referral"));
+    assert.ok(stdout.includes("<agent-id>"));
+    assert.ok(stdout.includes("<activity>"));
+    assert.ok(stdout.includes("<log>"));
+  });
+
+  it("agent get --help shows <agent-id>", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "get", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<agent-id>"));
+  });
+
+  it("agent set-bio --help shows <bio>", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "set-bio", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<bio>"));
+  });
+
+  it("agent set-metadata --help shows <json>", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "set-metadata", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<json>"));
+  });
+
+  it("agent upload-memory --help shows <file>", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "upload-memory", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<file>"));
+  });
+
+  it("agent transfer --help shows <new-authority>", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "transfer", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<new-authority>"));
+  });
+
+  it("agent delete --help shows <agent-id>", async () => {
+    const { stdout, exitCode } = await runCli(["agent", "delete", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("<agent-id>"));
+  });
+});
+
+// ─── Argument validation (no chain needed) ────────────────────────
+
+describe("agent argument errors", () => {
+  it("agent get with no args exits non-zero", async () => {
+    const { exitCode } = await runCli(["agent", "get"]);
+    assert.notEqual(exitCode, 0);
+  });
+
+  it("agent register with no args exits non-zero", async () => {
+    const { exitCode } = await runCli(["agent", "register"]);
+    assert.notEqual(exitCode, 0);
+  });
+
+  it("agent set-referral with no args exits non-zero", async () => {
+    const { exitCode } = await runCli(["agent", "set-referral"]);
+    assert.notEqual(exitCode, 0);
+  });
+
+  it("agent set-referral with only one arg exits non-zero", async () => {
+    const { exitCode } = await runCli(["agent", "set-referral", "my-agent"]);
+    assert.notEqual(exitCode, 0);
+  });
+
+  it("agent log with missing args exits non-zero", async () => {
+    const { exitCode } = await runCli(["agent", "log"]);
+    assert.notEqual(exitCode, 0);
+  });
+
+  it("agent log with only one arg exits non-zero", async () => {
+    const { exitCode } = await runCli(["agent", "log", "my-agent"]);
+    assert.notEqual(exitCode, 0);
+  });
+});
+
+// ─── Name validation (lowercase) ─────────────────────────────────
+
+describe("agent name validation", () => {
+  it("rejects uppercase agent ID", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "register", "MyAgent"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("lowercase"), `stderr: ${stderr}`);
+  });
+
+  it("rejects agent ID starting with number", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "register", "123agent"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("lowercase"), `stderr: ${stderr}`);
+  });
+
+  it("rejects agent ID starting with hyphen", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "register", "-my-agent"]);
+    // Commander may interpret -m as a flag, so check for either parse error or validation error
+    assert.notEqual(exitCode, 0);
+  });
+
+  it("rejects agent ID with special characters", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "register", "my_agent"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("lowercase"), `stderr: ${stderr}`);
+  });
+
+  it("rejects agent ID with spaces", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "register", "my agent"]);
+    // Commander may treat "agent" as a separate arg
+    assert.notEqual(exitCode, 0);
+  });
+});
+
+// ─── Read-only chain queries ──────────────────────────────────────
+
+describe("agent get (read-only)", () => {
+  it("returns error for non-existent agent", async () => {
+    const { exitCode, stderr } = await runCli(["agent", "get", "definitely-does-not-exist-xyz999"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.length > 0);
+  });
+});
+
+// ─── Metadata validation ─────────────────────────────────────────
+
+describe("agent set-metadata validation", () => {
+  it("rejects invalid JSON", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "set-metadata", "any-agent", "not-valid-json"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Invalid JSON"), `stderr: ${stderr}`);
+  });
+});
+
+// ─── Upload validation ───────────────────────────────────────────
+
+describe("agent upload-memory validation", () => {
+  it("rejects non-existent file", async () => {
+    if (!hasWallet) return;
+    const { exitCode, stderr } = await runCli(["agent", "upload-memory", "any-agent", "/tmp/__no_such_file__.bin"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Failed to read file"), `stderr: ${stderr}`);
+  });
+});

package/src/tests/config.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Tests for `config` CLI commands and agent-config utilities
+ *
+ * - Config get/set/reset via CLI
+ * - rpcUrlToNetworkName conversion
+ * - Global and network config load/save
+ *
+ * Run: npm run test:config
+ */
+
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { runCli } from "./helpers.js";
+import { rpcUrlToNetworkName } from "../cli/utils/agent-config.js";
+
+const CONFIG_DIR = join(homedir(), ".config", "nara");
+const GLOBAL_CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+// Backup and restore global config around tests
+let originalConfig: string | null = null;
+
+before(() => {
+  try {
+    originalConfig = readFileSync(GLOBAL_CONFIG_PATH, "utf-8");
+  } catch {
+    originalConfig = null;
+  }
+});
+
+after(() => {
+  if (originalConfig !== null) {
+    writeFileSync(GLOBAL_CONFIG_PATH, originalConfig);
+  } else if (existsSync(GLOBAL_CONFIG_PATH)) {
+    // Restore to no config (delete if it didn't exist before)
+    unlinkSync(GLOBAL_CONFIG_PATH);
+  }
+});
+
+// ─── rpcUrlToNetworkName ──────────────────────────────────────────
+
+describe("rpcUrlToNetworkName", () => {
+  it("converts mainnet URL", () => {
+    assert.equal(rpcUrlToNetworkName("https://mainnet-api.nara.build/"), "mainnet-api-nara-build");
+  });
+
+  it("converts devnet URL", () => {
+    assert.equal(rpcUrlToNetworkName("https://devnet-api.nara.build/"), "devnet-api-nara-build");
+  });
+
+  it("converts localhost URL", () => {
+    assert.equal(rpcUrlToNetworkName("http://127.0.0.1:8899/"), "127-0-0-1-8899");
+  });
+
+  it("handles URL without trailing slash", () => {
+    assert.equal(rpcUrlToNetworkName("https://mainnet-api.nara.build"), "mainnet-api-nara-build");
+  });
+
+  it("handles URL with multiple slashes", () => {
+    const result = rpcUrlToNetworkName("https://example.com///");
+    assert.ok(!result.includes("/"));
+    assert.ok(!result.startsWith("-"));
+    assert.ok(!result.endsWith("-"));
+  });
+
+  it("replaces dots and special chars with hyphens", () => {
+    assert.equal(rpcUrlToNetworkName("https://my.custom.rpc:9090/"), "my-custom-rpc-9090");
+  });
+
+  it("collapses multiple hyphens", () => {
+    const result = rpcUrlToNetworkName("http://a...b///c/");
+    assert.ok(!result.includes("--"));
+  });
+});
+
+// ─── config get ───────────────────────────────────────────────────
+
+describe("config get", () => {
+  it("shows current config in text mode", async () => {
+    const { stdout, exitCode } = await runCli(["config", "get"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("RPC URL:"));
+    assert.ok(stdout.includes("Wallet:"));
+    assert.ok(stdout.includes("Network:"));
+  });
+
+  it("--json returns structured config", async () => {
+    const { stdout, exitCode } = await runCli(["config", "get", "--json"]);
+    assert.equal(exitCode, 0);
+    const data = JSON.parse(stdout);
+    assert.ok(typeof data.rpc_url === "string");
+    assert.ok(typeof data.wallet === "string");
+    assert.ok(typeof data.network === "string");
+    assert.ok(Array.isArray(data.agent_ids));
+    assert.ok(Array.isArray(data.zk_ids));
+  });
+});
+
+// ─── config set ───────────────────────────────────────────────────
+
+describe("config set", () => {
+  it("sets rpc-url", async () => {
+    const testUrl = "https://test-rpc.example.com/";
+    const { exitCode, stdout } = await runCli(["config", "set", "rpc-url", testUrl]);
+    assert.equal(exitCode, 0);
+
+    // Verify it was saved
+    const { stdout: getOut } = await runCli(["config", "get", "--json"]);
+    const data = JSON.parse(getOut);
+    assert.equal(data.rpc_url, testUrl);
+    assert.equal(data.rpc_url_custom, true);
+  });
+
+  it("sets wallet path", async () => {
+    const testPath = "/tmp/test-wallet.json";
+    const { exitCode } = await runCli(["config", "set", "wallet", testPath]);
+    assert.equal(exitCode, 0);
+
+    const { stdout } = await runCli(["config", "get", "--json"]);
+    const data = JSON.parse(stdout);
+    assert.equal(data.wallet, testPath);
+    assert.equal(data.wallet_custom, true);
+  });
+
+  it("rejects unknown config key", async () => {
+    const { exitCode, stderr } = await runCli(["config", "set", "unknown-key", "value"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Unknown config key"));
+  });
+
+  it("--json returns set confirmation", async () => {
+    const { stdout, exitCode } = await runCli(["config", "set", "rpc-url", "https://example.com/", "--json"]);
+    assert.equal(exitCode, 0);
+    const data = JSON.parse(stdout);
+    assert.equal(data.key, "rpc-url");
+    assert.equal(data.value, "https://example.com/");
+  });
+});
+
+// ─── config reset ─────────────────────────────────────────────────
+
+describe("config reset", () => {
+  before(async () => {
+    // Set both values first
+    await runCli(["config", "set", "rpc-url", "https://test.example.com/"]);
+    await runCli(["config", "set", "wallet", "/tmp/test.json"]);
+  });
+
+  it("resets a single key", async () => {
+    const { exitCode } = await runCli(["config", "reset", "rpc-url"]);
+    assert.equal(exitCode, 0);
+
+    const { stdout } = await runCli(["config", "get", "--json"]);
+    const data = JSON.parse(stdout);
+    assert.equal(data.rpc_url_custom, false);
+    // wallet should still be custom
+    assert.equal(data.wallet_custom, true);
+  });
+
+  it("resets all keys", async () => {
+    // Set again to ensure both are custom
+    await runCli(["config", "set", "rpc-url", "https://test.example.com/"]);
+    const { exitCode } = await runCli(["config", "reset"]);
+    assert.equal(exitCode, 0);
+
+    const { stdout } = await runCli(["config", "get", "--json"]);
+    const data = JSON.parse(stdout);
+    assert.equal(data.rpc_url_custom, false);
+    assert.equal(data.wallet_custom, false);
+  });
+
+  it("rejects unknown reset key", async () => {
+    const { exitCode, stderr } = await runCli(["config", "reset", "bad-key"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Unknown config key"));
+  });
+
+  it("--json returns reset confirmation", async () => {
+    const { stdout, exitCode } = await runCli(["config", "reset", "rpc-url", "--json"]);
+    assert.equal(exitCode, 0);
+    const data = JSON.parse(stdout);
+    assert.equal(data.key, "rpc-url");
+    assert.equal(data.reset, true);
+  });
+});
+
+// ─── config --help ────────────────────────────────────────────────
+
+describe("config --help", () => {
+  it("shows subcommands", async () => {
+    const { stdout, exitCode } = await runCli(["config", "--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("get"));
+    assert.ok(stdout.includes("set"));
+    assert.ok(stdout.includes("reset"));
+  });
+});

package/src/tests/helpers.ts

@@ -7,6 +7,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
+import type { Connection } from "@solana/web3.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI = join(__dirname, "../../bin/nara-cli.ts");
@@ -57,3 +58,22 @@ export const hasWallet = existsSync(join(homedir(), ".config", "nara", "id.json"
 export function uniqueName(prefix: string): string {
   return `${prefix}-${Date.now().toString(36)}`;
 }
+
+/**
+ * Poll for transaction confirmation (avoids WebSocket-based confirmTransaction
+ * which fails with TLS errors on some networks).
+ */
+export async function pollConfirmation(
+  connection: Connection,
+  signature: string,
+  maxRetries = 30,
+  intervalMs = 1000
+): Promise<void> {
+  for (let i = 0; i < maxRetries; i++) {
+    const { value } = await connection.getSignatureStatuses([signature]);
+    const status = value[0]?.confirmationStatus;
+    if (status === "confirmed" || status === "finalized") return;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(`Transaction ${signature} not confirmed after ${maxRetries}s`);
+}