fusebox-sdk 0.1.0 → 0.2.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
@@ -48,6 +48,17 @@ const s = await fb.status(); // balance, prepaid fees, each fuse (and whether
48
48
  const h = await fb.history(); // every decision, oldest first
49
49
  ```
50
50
 
51
+ ## Approvals
52
+
53
+ When an approval fuse is what said no, `check` and `pay` say so and give the page where approvers sign:
54
+
55
+ ```ts
56
+ const r = await agent.pay(payee, "40", "Q4 bulk order");
57
+ if (r.needsApproval) notifyApprovers(r.needsApproval.url); // then retry once two have signed
58
+
59
+ const waiting = await fb.pending(approverAddress); // everything waiting on this approver, across wallets
60
+ ```
61
+
51
62
  ## Approve and freeze
52
63
 
53
64
  ```ts
@@ -68,6 +79,7 @@ await agent.freeze(); // agent, approver or owner: stop everyth
68
79
  | `history()` | decisions from Fusebox's indexed log (X Layer RPCs cap log ranges) |
69
80
  | `watch(onDecision, { pollingInterval? })` | returns a function that stops watching |
70
81
  | `approve(to, amount)` / `freeze()` | approver sign-off, emergency stop |
82
+ | `pending(approver)` | payments waiting on an approver, across wallets |
71
83
  | `xLayer`, `ADDRESSES`, the contract ABIs | for your own viem calls |
72
84
 
73
85
  Amounts are USDT0 with up to 6 decimals. Fuses from any designer work; ones that aren't Fusebox's own are named
package/dist/index.d.ts CHANGED
@@ -54,6 +54,8 @@ export interface CheckResult {
54
54
  to: Address;
55
55
  amount: string;
56
56
  block: number;
57
+ /** set when an approval fuse is what said no: where the wallet's approvers sign this exact payment */
58
+ approvalUrl?: string;
57
59
  fuses: {
58
60
  name: string;
59
61
  verdict: Verdict;
@@ -77,6 +79,24 @@ export interface PayResult {
77
79
  }[];
78
80
  summary: string;
79
81
  check?: CheckResult;
82
+ /** the payment needs approvers' signatures before a retry can pass */
83
+ needsApproval?: {
84
+ url: string;
85
+ };
86
+ }
87
+ /** A payment waiting on an approver (from pending()). */
88
+ export interface PendingApproval {
89
+ wallet: Address;
90
+ to: Address;
91
+ amount: string;
92
+ memo: string;
93
+ attempts: number;
94
+ last: number;
95
+ seats: Address[];
96
+ mySeat: number;
97
+ signed: number;
98
+ threshold: number | null;
99
+ url: string;
80
100
  }
81
101
  export interface Decision {
82
102
  id: number;
@@ -133,6 +153,8 @@ export declare class Fusebox {
133
153
  approve(to: string, amount: string | number): Promise<Hash>;
134
154
  /** As the agent, an approver or the owner: stop every payment now (only the owner can undo it). */
135
155
  freeze(): Promise<Hash>;
156
+ /** Payments waiting on `approver`'s signature, across every Fusebox wallet where they hold a seat. */
157
+ pending(approver: string): Promise<PendingApproval[]>;
136
158
  /** The wallet's decisions, oldest first, from Fusebox's indexed log (X Layer RPCs cap log ranges). */
137
159
  history(): Promise<Decision[]>;
138
160
  /** Call `onDecision` for every new decision as it lands on X Layer. Returns a function that stops watching. */
package/dist/index.js CHANGED
@@ -137,8 +137,10 @@ export class Fusebox {
137
137
  return { name: f.name, verdict: v, why };
138
138
  });
139
139
  const no = verdicts.filter((x) => x.verdict !== "pass");
140
- const summary = allowed ? `Every fuse holds: the wallet would pay ${a} USDT0 to ${payee}.` : `Stopped: ${no.map((x) => `${x.name} (${x.why})`).join("; ")}. Nothing would move.`;
141
- return { allowed, to: payee, amount: String(a), block: Number(block), fuses: verdicts, summary };
140
+ // when an approval fuse (socket 4) is among the no's, point at the page where approvers sign this exact payment
141
+ const approvalUrl = !allowed && fuses.some((f, i) => f.socket === 4 && verdicts[i].verdict === "blew") ? `${this.api}/app/approve?wallet=${this.wallet}&to=${payee}&amount=${a}` : undefined;
142
+ const summary = allowed ? `Every fuse holds: the wallet would pay ${a} USDT0 to ${payee}.` : `Stopped: ${no.map((x) => `${x.name} (${x.why})`).join("; ")}. Nothing would move.${approvalUrl && no.length === 1 ? ` Two of the wallet's approvers can sign it at ${approvalUrl}; retry once they have.` : ""}`;
143
+ return { allowed, to: payee, amount: String(a), block: Number(block), fuses: verdicts, summary, approvalUrl };
142
144
  }
143
145
  /**
144
146
  * Pay in USDT0 through the fuses with the agent's key. By default it checks first and doesn't send a payment the
@@ -155,9 +157,17 @@ export class Fusebox {
155
157
  throw new FuseboxError(`${this.account.address} isn't an agent of ${this.wallet}.`);
156
158
  if (opts.checkFirst !== false) {
157
159
  const c = await this.check(payee, usd(amt));
160
+ // needsApproval only when signatures alone would let the retry through
161
+ const onlyApproval = !!c.approvalUrl && c.fuses.filter((f) => f.verdict !== "pass").length === 1;
158
162
  if (!c.allowed)
159
- return { paid: false, sent: false, fuses: c.fuses.map(({ name, verdict }) => ({ name, verdict })), summary: `Not sent. ${c.summary}`, check: c };
163
+ return { paid: false, sent: false, fuses: c.fuses.map(({ name, verdict }) => ({ name, verdict })), summary: `Not sent. ${c.summary}`, check: c, needsApproval: onlyApproval ? { url: c.approvalUrl } : undefined };
160
164
  }
165
+ // a decision is charged up front from the prepaid fee balance: say so plainly instead of sending a doomed tx
166
+ const [line, registry] = await Promise.all([this.fuses(), this.public.readContract({ ...this.W, functionName: "registry" })]);
167
+ const per = line.reduce((t, f) => t + Math.min(Number(f.fee), Number(f.maxFee)), 0);
168
+ const have = Number(usd(await this.public.readContract({ address: registry, abi: fuseRegistryAbi, functionName: "feeBalance", args: [this.wallet] })));
169
+ if (have + 1e-9 < per)
170
+ throw new FuseboxError(`The wallet's prepaid fee balance (${have} USDT0) can't cover one decision (${per.toFixed(6)} USDT0): the owner needs to top it up before the agent can pay.`);
161
171
  const args = [ADDRESSES.usdt0, payee, amt, memo];
162
172
  const gas = await this.public.estimateContractGas({ ...this.W, functionName: "pay", args, account: this.account }).then((g) => (g * 13n) / 10n).catch(() => 3000000n);
163
173
  const hash = await this.walletClient.writeContract({ ...this.W, functionName: "pay", args, gas, account: this.account, chain: this.walletClient.chain ?? xLayer });
@@ -201,6 +211,15 @@ export class Fusebox {
201
211
  await this.public.waitForTransactionReceipt({ hash });
202
212
  return hash;
203
213
  }
214
+ /** Payments waiting on `approver`'s signature, across every Fusebox wallet where they hold a seat. */
215
+ async pending(approver) {
216
+ const a = parseTo(approver);
217
+ const r = await fetch(`${this.api}/api/approvals?approver=${a}`);
218
+ if (!r.ok)
219
+ throw new FuseboxError(`Approvals unavailable (${r.status}).`);
220
+ const j = (await r.json());
221
+ return j.open.map(({ mask, ...x }) => ({ ...x, signed: [0, 1, 2].filter((i) => (mask >> i) & 1).length, url: `${this.api}/app/approve?wallet=${x.wallet}&to=${x.to}&amount=${x.amount}` }));
222
+ }
204
223
  /** The wallet's decisions, oldest first, from Fusebox's indexed log (X Layer RPCs cap log ranges). */
205
224
  async history() {
206
225
  const r = await fetch(`${this.api}/api/wallet/${this.wallet}/history`);
package/package.json CHANGED
@@ -1,24 +1,52 @@
1
1
  {
2
2
  "name": "fusebox-sdk",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "TypeScript client for Fusebox wallets on X Layer: AI-agent payments that must pass logic-circuit fuses taped out on TapeOut. Check for free, pay (checked first), approve, freeze, watch decisions.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "types": "./dist/index.d.ts",
8
- "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
9
- "files": ["dist", "README.md"],
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js"
12
+ }
13
+ },
14
+ "files": [
15
+ "dist",
16
+ "README.md"
17
+ ],
10
18
  "sideEffects": false,
11
- "engines": { "node": ">=20" },
19
+ "engines": {
20
+ "node": ">=20"
21
+ },
12
22
  "license": "MIT",
13
- "repository": { "type": "git", "url": "https://github.com/0xdopewilly/fusebox", "directory": "sdk" },
23
+ "repository": {
24
+ "type": "git",
25
+ "url": "git+https://github.com/0xdopewilly/fusebox.git",
26
+ "directory": "sdk"
27
+ },
14
28
  "homepage": "https://fusebox-xlayer.vercel.app/docs",
15
- "keywords": ["x-layer", "tapeout", "ai-agents", "agent-wallet", "payments", "fusebox", "viem"],
29
+ "keywords": [
30
+ "x-layer",
31
+ "tapeout",
32
+ "ai-agents",
33
+ "agent-wallet",
34
+ "payments",
35
+ "fusebox",
36
+ "viem"
37
+ ],
16
38
  "scripts": {
17
39
  "build": "tsc -p .",
18
40
  "typecheck": "tsc -p . --noEmit",
19
41
  "test": "node --test test/*.test.mjs",
20
42
  "prepublishOnly": "npm run build"
21
43
  },
22
- "peerDependencies": { "viem": "^2.30.0" },
23
- "devDependencies": { "typescript": "5.9.3", "viem": "2.57.12", "@types/node": "24.19.2" }
44
+ "peerDependencies": {
45
+ "viem": "^2.30.0"
46
+ },
47
+ "devDependencies": {
48
+ "typescript": "5.9.3",
49
+ "viem": "2.57.12",
50
+ "@types/node": "24.19.2"
51
+ }
24
52
  }