fusebox-sdk 0.0.0-stage → 0.1.0

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.
package/README.md CHANGED
@@ -1,3 +1,77 @@
1
- # Temporary Holding Version
1
+ # fusebox-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ TypeScript client for [Fusebox](https://fusebox-xlayer.vercel.app) wallets on X Layer. An AI agent holds a key
4
+ that can only ask the wallet to pay, and every payment has to pass the wallet's **fuses**: small logic circuits
5
+ taped out on [TapeOut](https://tapeout.net) and evaluated on X Layer in the same transaction. One no, and nothing moves.
6
+
7
+ ```bash
8
+ npm install fusebox-sdk viem
9
+ ```
10
+
11
+ ## Check a payment (free, no key)
12
+
13
+ ```ts
14
+ import { Fusebox } from "fusebox-sdk";
15
+
16
+ const fb = new Fusebox(); // Atlas, the public demo wallet, on X Layer mainnet
17
+ const c = await fb.check("0x9f3e71b8D05A2c6E94f13B7d5E0A8C2F6B19c41A", "2.5");
18
+ console.log(c.allowed); // false
19
+ console.log(c.summary);
20
+ // Stopped: Payee Guard (not a saved payee); Breaker (a payment to a stranger trips it, and it stays blown
21
+ // until the owner resets it). Nothing would move.
22
+ ```
23
+
24
+ `check` runs the wallet's own `check()` on X Layer: every fuse answers, with the reason, and nothing is sent.
25
+
26
+ ## Pay as the agent
27
+
28
+ ```ts
29
+ const agent = new Fusebox({ wallet: "0xYourFuseboxWallet", account: process.env.FUSEBOX_AGENT_KEY as `0x${string}` });
30
+
31
+ const r = await agent.pay("0x69dB89385E8a69278a49335C432d0c70ec86A6C4", "12.5", "Invoice INV-7790, Kano Cotton");
32
+ if (r.paid) console.log(`paid, decision #${r.decisionId}`, r.txUrl);
33
+ else console.log(r.summary); // "Not sent. Stopped: Daily Cap (…)" — ask the owner, don't retry
34
+ ```
35
+
36
+ `pay` checks first and doesn't send a payment the fuses would refuse, because a refused payment is still recorded
37
+ on-chain and its checks are still paid for. Pass `{ checkFirst: false }` to record the attempt anyway. The memo
38
+ is stored with the decision; no fuse ever reads it, so a convincing story can't talk a payment through.
39
+
40
+ ## Follow the wallet
41
+
42
+ ```ts
43
+ const stop = fb.watch((d) => {
44
+ if (!d.paid) console.log(`Stopped ${d.amount} USDT0 to ${d.to}: ${d.fuses.filter((f) => f.verdict !== "pass").map((f) => f.name).join(", ")}`);
45
+ });
46
+
47
+ const s = await fb.status(); // balance, prepaid fees, each fuse (and whether it's blown), counts, daily budgets
48
+ const h = await fb.history(); // every decision, oldest first
49
+ ```
50
+
51
+ ## Approve and freeze
52
+
53
+ ```ts
54
+ const approver = new Fusebox({ wallet, account: approverKey });
55
+ await approver.approve(payee, "40"); // Two of Three: this exact payee and amount
56
+
57
+ await agent.freeze(); // agent, approver or owner: stop everything now (only the owner can reset)
58
+ ```
59
+
60
+ ## API
61
+
62
+ | | |
63
+ |---|---|
64
+ | `new Fusebox({ wallet?, rpc?, account?, api?, publicClient?, walletClient? })` | `account` is a private key or any viem `Account`; without it the client is read-only |
65
+ | `check(to, amount)` | `{ allowed, fuses: [{ name, verdict, why }], summary, block }` |
66
+ | `pay(to, amount, memo, { checkFirst? })` | `{ paid, sent, decisionId, txUrl, feePaid, fuses, summary }` |
67
+ | `status()` / `fuses()` | the wallet and its line of fuses |
68
+ | `history()` | decisions from Fusebox's indexed log (X Layer RPCs cap log ranges) |
69
+ | `watch(onDecision, { pollingInterval? })` | returns a function that stops watching |
70
+ | `approve(to, amount)` / `freeze()` | approver sign-off, emergency stop |
71
+ | `xLayer`, `ADDRESSES`, the contract ABIs | for your own viem calls |
72
+
73
+ Amounts are USDT0 with up to 6 decimals. Fuses from any designer work; ones that aren't Fusebox's own are named
74
+ from their on-chain metadata. For MCP clients (Claude Code, Cursor and others) there's
75
+ [`fusebox-mcp`](https://www.npmjs.com/package/fusebox-mcp). Docs: https://fusebox-xlayer.vercel.app/docs
76
+
77
+ MIT