clw-cash 0.1.21 → 0.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +5 -3
  2. package/SKILL.md +77 -23
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -21,11 +21,13 @@ cash login
21
21
  cash balance
22
22
 
23
23
  # Send funds
24
- cash send --amount 100000 --currency btc --where arkade --to ark1q...
24
+ cash send --amount 0.001 --currency btc --where arkade --to ark1q...
25
+ cash send --amount 100000 --currency sats --where arkade --to ark1q...
25
26
  cash send lnbc500n1...
26
27
 
27
28
  # Receive funds
28
- cash receive --amount 100000 --currency btc --where lightning
29
+ cash receive --amount 0.001 --currency btc --where lightning
30
+ cash receive --amount 100000 --currency sats --where lightning
29
31
  ```
30
32
 
31
33
  ## Commands
@@ -47,7 +49,7 @@ cash receive --amount 100000 --currency btc --where lightning
47
49
 
48
50
  ### Supported currencies and networks
49
51
 
50
- - **Currency:** `btc`, `usdt`, `usdc`
52
+ - **Currency:** `btc`, `sats`, `usdt`, `usdc`
51
53
  - **Where:** `onchain`, `lightning`, `arkade`, `polygon`, `arbitrum`, `ethereum`
52
54
 
53
55
  ## How It Works
package/SKILL.md CHANGED
@@ -13,22 +13,71 @@ Success output is JSON to stdout. Error output is JSON to stderr. Exit code 0 =
13
13
  - **Timeouts:** 30s default for quick commands (balance, receive), 120s for `cash init`.
14
14
  - **Default to Arkade for BTC receives.** When the user asks for a Bitcoin address, use `--where arkade`. Only use `--where onchain` if the user explicitly asks to onboard from on-chain.
15
15
 
16
- ### Reactive Polling
17
-
18
- For long-running operations (swaps, pending receives), keep the user informed:
19
-
20
- - **Run in background with short yield** — don't block the conversation for >15s without an update. Use `yieldMs=5000` or `background=true` for swap commands.
21
- - **Stream progress** — relay status lines as they appear:
22
- - "Executing swap BTC → USDC..."
23
- - "Waiting for on-chain confirmation..."
24
- - "Swap claimed! New balance: X sats"
25
- - **Poll with `process action=log`** — if a command is backgrounded, check its output periodically and report the latest status line to the user.
26
- - **Timeout strategy:**
27
- - Quick commands (balance, receive, config): 30s
28
- - Swaps/settlements: start with `yieldMs=10000`, then poll process log
29
- - If still running after 60s, tell user "still processing, I'll let you know when done"
30
- - **Never go silent** for >15s during a long operation. Always provide a status update.
31
- - **Never let a timeout kill a command silently** — if a command times out, tell the user what happened and suggest next steps (e.g., `cash swap <id>` to check status).
16
+ ### Reactive Behavior (Login → Payment Detection)
17
+
18
+ The agent must stay reactive at every stage. Never block silently. Every operation >5s gets a status update.
19
+
20
+ #### 1. Login & Init
21
+
22
+ - Run `cash init` with 120s timeout — it waits for Telegram 2FA.
23
+ - **Immediately tell the user** what's happening: "Authenticating — check Telegram for the login link."
24
+ - Poll every 10s. Relay progress: "Still waiting for Telegram confirmation..."
25
+ - On success: "Logged in! Checking your balance..." → auto-run `cash balance`.
26
+ - On failure/timeout: "Login timed out. Run `cash login` to try again."
27
+ - For bot mode (`--start`): return the deep link immediately, then register a webhook or poll `cash status` every 10s until session becomes active.
28
+
29
+ #### 2. Balance & Config (Quick Reads)
30
+
31
+ - 30s timeout max. These should return instantly.
32
+ - On success: report the balance clearly — "You have 50,000 sats available (70,000 total with pending)."
33
+ - On error: check session first — if expired, tell user "Session expired, re-authenticating..." and run `cash login`.
34
+
35
+ #### 3. Receiving — Waiting for Payment
36
+
37
+ This is the most important reactive flow. After generating an address/invoice:
38
+
39
+ - **Show the address/invoice/payment URL immediately** — don't wait.
40
+ - **Start polling for incoming payment:**
41
+ 1. Run `cash balance` every 15-30s to detect balance changes.
42
+ 2. For Lightning: the daemon auto-claims — poll `cash status` or register a webhook.
43
+ 3. For stablecoin receives: poll `cash swaps --pending` to detect when the sender funds the swap.
44
+ - **Keep the user informed:**
45
+ - "Waiting for payment... (checking every 15s)"
46
+ - "Still waiting — no payment detected yet."
47
+ - "Payment detected! 50,000 sats received. New balance: 120,000 sats."
48
+ - **Use webhooks when available** — register via the daemon's `/notify/register` endpoint for `swap.claimed` events instead of polling.
49
+ - **Timeout after 5 minutes** of no payment: "No payment detected after 5 min. The address/invoice is still valid — I'll stop polling but you can ask me to check again."
50
+
51
+ #### 4. Sending — Swap Execution
52
+
53
+ - **Always confirm** with user before executing `cash send`.
54
+ - Run the send command with `yieldMs=10000` for swap commands (BTC→stablecoin).
55
+ - Relay progress:
56
+ - "Sending 10 USDC to 0x... on Polygon..."
57
+ - "Swap initiated — waiting for settlement..."
58
+ - "Sent! Tx: 0x... — 10 USDC delivered."
59
+ - If backgrounded, poll `cash swap <id>` every 10s until status is `completed` or `failed`.
60
+ - On failure: report error, suggest `cash refund <id>` if applicable.
61
+
62
+ #### 5. Swap Monitoring
63
+
64
+ - For any active swap, poll `cash swap <id>` every 10-15s.
65
+ - Map status to user-friendly updates:
66
+ - `pending` / `awaiting_funding` → "Swap created, waiting for funding..."
67
+ - `funded` → "Funds received, processing swap..."
68
+ - `processing` → "Swap in progress, settling on-chain..."
69
+ - `completed` → "Swap complete! Funds delivered."
70
+ - `expired` → "Swap expired. You can refund with `cash refund <id>`."
71
+ - `failed` → "Swap failed: [error]. Check `cash swap <id>` for details."
72
+ - After `completed`: auto-run `cash balance` and report the new balance.
73
+
74
+ #### Never Do
75
+
76
+ - Block silently for >15s without a status update.
77
+ - Let a timeout kill a command without telling the user.
78
+ - Retry failed commands without asking (except `cash login` on session expiry).
79
+ - Go silent after generating a receive address — always poll for payment.
80
+ - Assume a swap succeeded without checking status.
32
81
 
33
82
  ## Setup
34
83
 
@@ -76,14 +125,17 @@ CLW_DAEMON_PORT=3457 # default: 3457
76
125
  ### Send Bitcoin
77
126
 
78
127
  ```bash
79
- # Send sats via Ark (instant, off-chain)
128
+ # Send via Ark (instant, off-chain) — use the unit that matches user input
80
129
  cash send --amount 100000 --currency sats --where arkade --to <ark-address>
130
+ cash send --amount 0.001 --currency btc --where arkade --to <ark-address>
81
131
 
82
- # Send sats on-chain
132
+ # Send on-chain
83
133
  cash send --amount 100000 --currency sats --where onchain --to <bitcoin-address>
134
+ cash send --amount 0.001 --currency btc --where onchain --to <bitcoin-address>
84
135
 
85
136
  # Pay a Lightning invoice
86
137
  cash send --amount 50000 --currency sats --where lightning --to <bolt11-invoice>
138
+ cash send --amount 0.001 --currency btc --where lightning --to <bolt11-invoice>
87
139
 
88
140
  # Auto-detect invoice format (bolt11 or BIP21, positional arg)
89
141
  cash send lnbc500n1pj...
@@ -105,15 +157,17 @@ cash send --amount 50 --currency usdc --where arbitrum --to <0x-address>
105
157
  ```bash
106
158
  # Get an Ark address
107
159
  cash receive --amount 100000 --currency sats --where arkade
108
- # -> {"ok": true, "data": {"address": "ark1q...", "type": "ark", "amount": 100000}}
160
+ cash receive --amount 0.001 --currency btc --where arkade
109
161
 
110
- # Create a Lightning invoice
162
+ # Create a Lightning invoice — use the unit that matches user input
111
163
  cash receive --amount 50000 --currency sats --where lightning
112
164
  # -> {"ok": true, "data": {"bolt11": "lnbc...", "paymentHash": "...", "amount": 50000}}
165
+ cash receive --amount 0.001 --currency btc --where lightning
166
+ # -> {"ok": true, "data": {"bolt11": "lnbc...", "paymentHash": "...", "amount": 100000}}
113
167
 
114
168
  # Get a boarding (on-chain) address
115
169
  cash receive --amount 100000 --currency sats --where onchain
116
- # -> {"ok": true, "data": {"address": "bc1q...", "type": "onchain", "amount": 100000}}
170
+ cash receive --amount 0.001 --currency btc --where onchain
117
171
  ```
118
172
 
119
173
  ### Receive Stablecoins (Stablecoin to BTC swap)
@@ -253,8 +307,8 @@ Error (stderr):
253
307
 
254
308
  | Currency | Networks | Notes |
255
309
  | -------- | --------------------------- | ----------------------------------------- |
256
- | sats | onchain, lightning, arkade | Amount in satoshis (use `sats` not `btc`) |
257
- | btc | onchain, lightning, arkade | Amount in BTC (e.g. 0.001) |
310
+ | sats | onchain, lightning, arkade | Amount in satoshis — use when user says "sats" |
311
+ | btc | onchain, lightning, arkade | Amount in BTC — use when user says "BTC" |
258
312
  | usdt | polygon, ethereum, arbitrum | |
259
313
  | usdc | polygon, ethereum, arbitrum | |
260
314
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clw-cash",
3
- "version": "0.1.21",
3
+ "version": "0.1.22",
4
4
  "description": "Bitcoin & Stablecoin agent wallet CLI. Keys held in a secure enclave.",
5
5
  "type": "module",
6
6
  "bin": {