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 +12 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.js +22 -3
- package/package.json +36 -8
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
|
-
|
|
141
|
-
|
|
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.
|
|
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": {
|
|
9
|
-
|
|
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": {
|
|
19
|
+
"engines": {
|
|
20
|
+
"node": ">=20"
|
|
21
|
+
},
|
|
12
22
|
"license": "MIT",
|
|
13
|
-
"repository": {
|
|
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": [
|
|
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": {
|
|
23
|
-
|
|
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
|
}
|