clw-cash 0.1.0

package/SKILL.md

@@ -0,0 +1,219 @@
+# cash - Bitcoin & Stablecoin Agent Wallet
+
+A command-line tool for sending and receiving Bitcoin and stablecoins. Keys are held in a secure enclave — the CLI never touches private keys.
+
+All commands output JSON to stdout. Exit code 0 = success, 1 = error.
+
+## Setup
+
+```bash
+# First time — authenticates, creates identity, saves config, starts daemon
+cash init
+# Re-authenticate when session expires
+cash login
+```
+
+`init` handles authentication automatically (Telegram 2FA in production, auto-resolves in test mode). It creates an identity, saves config to `~/.clw-cash/config.json`, and **auto-starts a background daemon** for monitoring swaps (Lightning HTLC claiming and LendaSwap polling).
+
+If the session token expires, run `cash login` to re-authenticate. If the daemon stops, restart it with `cash start`.
+
+You can also pass a token explicitly: `cash init --api-url <url> --token <jwt> --ark-server <url>`.
+
+Or set environment variables:
+
+```bash
+CLW_API_URL=https://api.clw.cash
+CLW_SESSION_TOKEN=<jwt>
+CLW_IDENTITY_ID=<uuid>
+CLW_PUBLIC_KEY=<hex>
+CLW_ARK_SERVER_URL=https://ark.clw.cash
+```
+
+## Commands
+
+### Send Bitcoin
+
+```bash
+# Send sats via Ark (instant, off-chain)
+cash send --amount 100000 --currency btc --where arkade --to <ark-address>
+
+# Send sats on-chain
+cash send --amount 100000 --currency btc --where onchain --to <bitcoin-address>
+
+# Pay a Lightning invoice
+cash send --amount 50000 --currency btc --where lightning --to <bolt11-invoice>
+
+# Auto-detect invoice format (bolt11 or BIP21, positional arg)
+cash send lnbc500n1pj...
+cash send bitcoin:bc1q...?amount=0.001&lightning=lnbc...
+```
+
+### Send Stablecoins (BTC to Stablecoin swap)
+
+```bash
+# Swap BTC to USDT on Polygon
+cash send --amount 10 --currency usdt --where polygon --to <0x-address>
+
+# Swap BTC to USDC on Arbitrum
+cash send --amount 50 --currency usdc --where arbitrum --to <0x-address>
+```
+
+### Receive Bitcoin
+
+```bash
+# Get an Ark address
+cash receive --amount 100000 --currency btc --where arkade
+# -> {"ok": true, "data": {"address": "ark1q...", "type": "ark", "amount": 100000}}
+
+# Create a Lightning invoice
+cash receive --amount 50000 --currency btc --where lightning
+# -> {"ok": true, "data": {"bolt11": "lnbc...", "paymentHash": "...", "amount": 50000}}
+
+# Get a boarding (on-chain) address
+cash receive --amount 100000 --currency btc --where onchain
+# -> {"ok": true, "data": {"address": "bc1q...", "type": "onchain", "amount": 100000}}
+```
+
+### Receive Stablecoins (Stablecoin to BTC swap)
+
+```bash
+# Receive USDT from Polygon (swap to BTC)
+cash receive --amount 10 --currency usdt --where polygon --address <0x-sender-address>
+```
+
+### Check Balance
+
+```bash
+cash balance
+# -> {"ok": true, "data": {"total": 250000, "offchain": {"settled": 50000, "preconfirmed": 20000, "available": 70000}, "onchain": {"confirmed": 30000, "total": 30000}}}
+```
+
+### Swap Management
+
+```bash
+# Check a single swap by ID
+cash swap <swap-id>
+# -> {"ok": true, "data": {"id": "...", "status": "funded", "direction": "btc_to_stablecoin", "local": {...}, "remote": {...}}}
+
+# List swaps (grouped by status, last 5 per category)
+cash swaps
+# -> {"ok": true, "data": {"lendaswap": {"pending": [...], "claimed": [...], "refunded": [...], "expired": [...], "failed": [...]}}}
+
+# Filter by status
+cash swaps --pending
+cash swaps --claimed --limit 10
+
+# Manually claim a completed swap
+cash claim <swap-id>
+# -> {"ok": true, "data": {"success": true, "txHash": "0x...", "chain": "polygon"}}
+
+# Refund an expired swap
+cash refund <swap-id>
+# -> {"ok": true, "data": {"success": true, "txId": "...", "refundAmount": 95000}}
+```
+
+### Daemon (Swap Monitoring)
+
+The daemon runs in the background to automatically claim Lightning HTLCs and monitor LendaSwap swaps. It is **auto-started by `cash init`**. Use these commands to manage it manually:
+
+```bash
+# Start the daemon
+cash start
+# -> {"ok": true, "data": {"started": true, "pid": 12345, "port": 3457}}
+
+# Check daemon and session status
+cash status
+# -> {"ok": true, "data": {"session": "active", "sessionExpiresAt": 1739..., "daemon": {"running": true, "pid": 12345, "port": 3457}}}
+
+# List pending swaps
+cash swaps --pending
+
+# Stop the daemon
+cash stop
+# -> {"ok": true, "data": {"stopped": true, "pid": 12345}}
+```
+
+## Output Format
+
+Success:
+
+```json
+{"ok": true, "data": { ... }}
+```
+
+Error:
+
+```json
+{"ok": false, "error": "description of what went wrong"}
+```
+
+## Currency & Network Matrix
+
+| Currency | Networks                    |
+| -------- | --------------------------- |
+| btc      | onchain, lightning, arkade  |
+| usdt     | polygon, ethereum, arbitrum |
+| usdc     | polygon, ethereum, arbitrum |
+
+## Swap Status Lifecycle
+
+| Status             | Meaning                        |
+| ------------------ | ------------------------------ |
+| pending            | Swap created, awaiting funding |
+| awaiting_funding   | Initial state                  |
+| funded             | User has sent funds            |
+| processing         | Swap in progress               |
+| completed          | Swap done, claimed             |
+| expired            | Timelock expired               |
+| refunded           | Funds returned                 |
+| failed             | Swap failed                    |
+
+Directions: `btc_to_stablecoin` or `stablecoin_to_btc`.
+
+Token identifiers: `btc_arkade`, `usdc_pol`, `usdc_eth`, `usdc_arb`, `usdt0_pol`, `usdt_eth`, `usdt_arb`.
+
+## Agent Tips
+
+All output is JSON — pipe through `jq` to extract specific fields:
+
+```bash
+# Get just the swap status
+cash swap <swap-id> | jq .data.status
+
+# Get total balance in sats
+cash balance | jq .data.total
+
+# Get offchain available balance
+cash balance | jq .data.offchain.available
+
+# Check if daemon is running
+cash status | jq .data.daemon.running
+
+# Check session state (active or expired)
+cash status | jq .data.session
+
+# List only pending swap IDs
+cash swaps --pending | jq '[.data.lendaswap.pending[].id]'
+
+# Get the payment bolt11 invoice
+cash receive --amount 50000 --currency btc --where lightning | jq -r .data.bolt11
+
+# Get the ark address for receiving
+cash receive --amount 100000 --currency btc --where arkade | jq -r .data.address
+
+# Check if a command succeeded
+cash send ... && echo "sent" || echo "failed"
+```
+
+Common workflow for monitoring a stablecoin swap:
+
+```bash
+# 1. Initiate the swap
+cash send --amount 10 --currency usdc --where polygon --to 0x...
+
+# 2. Poll status until completed (daemon does this automatically)
+cash swap <swap-id> | jq .data.status
+
+# 3. If expired, refund
+cash refund <swap-id>
+```

package/dist/chunk-IXURARCD.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+// src/daemon.ts
+import { spawn } from "child_process";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { resolve } from "path";
+var CONFIG_DIR = join(homedir(), ".clw-cash");
+var PID_FILE = join(CONFIG_DIR, "daemon.pid");
+var LOG_FILE = join(CONFIG_DIR, "daemon.log");
+function getPort() {
+  const envPort = process.env.CLW_DAEMON_PORT;
+  if (envPort) {
+    const parsed = parseInt(envPort, 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return 3457;
+}
+function getDaemonStatus() {
+  let data;
+  try {
+    const raw = readFileSync(PID_FILE, "utf-8");
+    data = JSON.parse(raw);
+  } catch {
+    return { running: false };
+  }
+  try {
+    process.kill(data.pid, 0);
+    return { running: true, pid: data.pid, port: data.port };
+  } catch {
+    try {
+      unlinkSync(PID_FILE);
+    } catch {
+    }
+    return { running: false };
+  }
+}
+function saveDaemonPid(pid, port) {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  writeFileSync(PID_FILE, JSON.stringify({ pid, port }), { mode: 384 });
+}
+function removeDaemonPid() {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+  }
+}
+async function startDaemonInBackground(port) {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  const logFd = openSync(LOG_FILE, "a");
+  const entrypoint = resolve(process.cwd(), "cli/src/index.ts");
+  const tsxBin = resolve(process.cwd(), "node_modules/.bin/tsx");
+  const child = spawn(tsxBin, [entrypoint, "--daemon-internal", "--port", String(port)], {
+    cwd: process.cwd(),
+    env: { ...process.env },
+    detached: true,
+    stdio: ["ignore", logFd, logFd]
+  });
+  const pid = child.pid;
+  if (!pid) {
+    throw new Error("Failed to spawn daemon process");
+  }
+  child.unref();
+  const deadline = Date.now() + 3e4;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/health`);
+      if (res.ok) {
+        return { pid };
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+  }
+  throw new Error(`Daemon did not become healthy within 30s (pid: ${pid})`);
+}
+async function ensureDaemonRunning() {
+  const status = getDaemonStatus();
+  if (status.running && status.pid && status.port) {
+    return { pid: status.pid, port: status.port };
+  }
+  const port = getPort();
+  const { pid } = await startDaemonInBackground(port);
+  return { pid, port };
+}
+async function stopDaemon() {
+  const status = getDaemonStatus();
+  if (!status.running || !status.pid) {
+    return false;
+  }
+  process.kill(status.pid, "SIGTERM");
+  const deadline = Date.now() + 5e3;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(status.pid, 0);
+    } catch {
+      removeDaemonPid();
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  try {
+    process.kill(status.pid, "SIGKILL");
+  } catch {
+  }
+  removeDaemonPid();
+  return true;
+}
+
+export {
+  getPort,
+  getDaemonStatus,
+  saveDaemonPid,
+  removeDaemonPid,
+  startDaemonInBackground,
+  ensureDaemonRunning,
+  stopDaemon
+};

package/dist/daemon-2URHH37P.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import {
+  ensureDaemonRunning,
+  getDaemonStatus,
+  getPort,
+  removeDaemonPid,
+  saveDaemonPid,
+  startDaemonInBackground,
+  stopDaemon
+} from "./chunk-IXURARCD.js";
+export {
+  ensureDaemonRunning,
+  getDaemonStatus,
+  getPort,
+  removeDaemonPid,
+  saveDaemonPid,
+  startDaemonInBackground,
+  stopDaemon
+};