@tollxyz/guard 0.4.1 → 0.5.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 +465 -420
- package/dist/budget.d.ts +96 -0
- package/dist/budget.js +110 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/package.json +70 -70
package/dist/budget.d.ts
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { SpendPolicy } from "./policy.js";
|
|
2
|
+
/** The budget's EIP-712 domain: no verifyingContract (nothing on chain checks it). */
|
|
3
|
+
export declare const BUDGET_DOMAIN: {
|
|
4
|
+
readonly name: "Toll Facilitator Budget";
|
|
5
|
+
readonly version: "1";
|
|
6
|
+
readonly chainId: 4663;
|
|
7
|
+
};
|
|
8
|
+
export declare const BUDGET_TYPES: {
|
|
9
|
+
readonly Budget: readonly [{
|
|
10
|
+
readonly name: "payer";
|
|
11
|
+
readonly type: "address";
|
|
12
|
+
}, {
|
|
13
|
+
readonly name: "perPayment";
|
|
14
|
+
readonly type: "uint256";
|
|
15
|
+
}, {
|
|
16
|
+
readonly name: "perDay";
|
|
17
|
+
readonly type: "uint256";
|
|
18
|
+
}, {
|
|
19
|
+
readonly name: "perPayTo";
|
|
20
|
+
readonly type: "uint256";
|
|
21
|
+
}, {
|
|
22
|
+
readonly name: "payToCaps";
|
|
23
|
+
readonly type: "PayToCap[]";
|
|
24
|
+
}, {
|
|
25
|
+
readonly name: "allowedPayTos";
|
|
26
|
+
readonly type: "address[]";
|
|
27
|
+
}, {
|
|
28
|
+
readonly name: "validUntil";
|
|
29
|
+
readonly type: "uint64";
|
|
30
|
+
}, {
|
|
31
|
+
readonly name: "nonce";
|
|
32
|
+
readonly type: "uint256";
|
|
33
|
+
}];
|
|
34
|
+
readonly PayToCap: readonly [{
|
|
35
|
+
readonly name: "payTo";
|
|
36
|
+
readonly type: "address";
|
|
37
|
+
}, {
|
|
38
|
+
readonly name: "perDay";
|
|
39
|
+
readonly type: "uint256";
|
|
40
|
+
}];
|
|
41
|
+
};
|
|
42
|
+
/** at most this many payToCaps and allowedPayTos */
|
|
43
|
+
export declare const BUDGET_MAX_PAYTOS = 50;
|
|
44
|
+
export interface GuardBudgetOptions {
|
|
45
|
+
/** the agent's paying wallet (it signs the budget) */
|
|
46
|
+
payer: string;
|
|
47
|
+
/** newer wins at the facilitator: use a growing number, e.g. BigInt(Date.now()) */
|
|
48
|
+
nonce: bigint | number | string;
|
|
49
|
+
/** unix seconds the budget ends; 0 or unset = no end */
|
|
50
|
+
validUntil?: bigint | number | string;
|
|
51
|
+
/** the payTo of each perEndpoint prefix (same keys); a perEndpoint key that is itself an address is its own payTo */
|
|
52
|
+
endpointPayTo?: Record<string, string>;
|
|
53
|
+
/** one day cap for every payTo, base units; 0 or unset = not set */
|
|
54
|
+
perPayTo?: bigint;
|
|
55
|
+
/** perPayment when the policy has no assets[USDG].perCall (the facilitator needs one: 0 lets nothing through) */
|
|
56
|
+
perPayment?: bigint;
|
|
57
|
+
/** perDay when the policy has no assets[USDG].perDay */
|
|
58
|
+
perDay?: bigint;
|
|
59
|
+
}
|
|
60
|
+
export interface GuardBudgetMessage {
|
|
61
|
+
payer: string;
|
|
62
|
+
perPayment: bigint;
|
|
63
|
+
perDay: bigint;
|
|
64
|
+
perPayTo: bigint;
|
|
65
|
+
payToCaps: Array<{
|
|
66
|
+
payTo: string;
|
|
67
|
+
perDay: bigint;
|
|
68
|
+
}>;
|
|
69
|
+
allowedPayTos: string[];
|
|
70
|
+
validUntil: bigint;
|
|
71
|
+
nonce: bigint;
|
|
72
|
+
}
|
|
73
|
+
export interface GuardBudget {
|
|
74
|
+
/** the budget (the typed message), for @tollxyz/sdk's setBudget({ budget, signature }) */
|
|
75
|
+
budget: GuardBudgetMessage;
|
|
76
|
+
/** EIP-712 typed data for the payer to sign (viem: account.signTypedData(typedData)) */
|
|
77
|
+
typedData: {
|
|
78
|
+
domain: {
|
|
79
|
+
name: string;
|
|
80
|
+
version: string;
|
|
81
|
+
chainId: number;
|
|
82
|
+
};
|
|
83
|
+
types: typeof BUDGET_TYPES;
|
|
84
|
+
primaryType: "Budget";
|
|
85
|
+
message: GuardBudgetMessage;
|
|
86
|
+
};
|
|
87
|
+
/** guard rules the facilitator budget cannot hold (guard still enforces them in-process) */
|
|
88
|
+
notMirrored: string[];
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* The facilitator budget that mirrors a guard SpendPolicy. Throws when the policy has no USDG per-call or per-day cap
|
|
92
|
+
* and none is passed (the facilitator treats a missing cap as 0, which refuses every payment), or when a list is over 50.
|
|
93
|
+
*/
|
|
94
|
+
export declare function guardBudget(policy: SpendPolicy | {
|
|
95
|
+
spend?: SpendPolicy;
|
|
96
|
+
}, opts: GuardBudgetOptions): GuardBudget;
|
package/dist/budget.js
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Mirror guard's spend caps into a per-payer budget at Toll's x402 facilitator (x402.t0ll.xyz/budget, COMING: the
|
|
3
|
+
* facilitator answers 404 budgets_off until budgets are switched on). guard enforces caps in the agent's process; the
|
|
4
|
+
* facilitator budget enforces them again where the payment settles, so a second process, a leaked key used elsewhere or
|
|
5
|
+
* a bug in the agent cannot spend past them through that facilitator.
|
|
6
|
+
*
|
|
7
|
+
* The words match: guard's assets[USDG].perCall is the budget's perPayment, assets[USDG].perDay its perDay, perEndpoint
|
|
8
|
+
* day caps become payToCaps (the facilitator sees a payTo, not a URL, so each endpoint needs its payTo) and allow.payTo
|
|
9
|
+
* becomes allowedPayTos. Nothing here changes how guard itself behaves. Amounts are USDG base units (6 decimals).
|
|
10
|
+
*/
|
|
11
|
+
import { isAddress } from "./check.js";
|
|
12
|
+
import { USDG } from "./spend.js";
|
|
13
|
+
/** The budget's EIP-712 domain: no verifyingContract (nothing on chain checks it). */
|
|
14
|
+
export const BUDGET_DOMAIN = { name: "Toll Facilitator Budget", version: "1", chainId: 4663 };
|
|
15
|
+
export const BUDGET_TYPES = {
|
|
16
|
+
Budget: [
|
|
17
|
+
{ name: "payer", type: "address" },
|
|
18
|
+
{ name: "perPayment", type: "uint256" },
|
|
19
|
+
{ name: "perDay", type: "uint256" },
|
|
20
|
+
{ name: "perPayTo", type: "uint256" },
|
|
21
|
+
{ name: "payToCaps", type: "PayToCap[]" },
|
|
22
|
+
{ name: "allowedPayTos", type: "address[]" },
|
|
23
|
+
{ name: "validUntil", type: "uint64" },
|
|
24
|
+
{ name: "nonce", type: "uint256" },
|
|
25
|
+
],
|
|
26
|
+
PayToCap: [
|
|
27
|
+
{ name: "payTo", type: "address" },
|
|
28
|
+
{ name: "perDay", type: "uint256" },
|
|
29
|
+
],
|
|
30
|
+
};
|
|
31
|
+
/** at most this many payToCaps and allowedPayTos */
|
|
32
|
+
export const BUDGET_MAX_PAYTOS = 50;
|
|
33
|
+
const MAX_U64 = (1n << 64n) - 1n;
|
|
34
|
+
function uint(v, name, max = (1n << 256n) - 1n) {
|
|
35
|
+
let n = null;
|
|
36
|
+
if (typeof v === "bigint")
|
|
37
|
+
n = v;
|
|
38
|
+
else if (typeof v === "number" && Number.isSafeInteger(v))
|
|
39
|
+
n = BigInt(v);
|
|
40
|
+
else if (typeof v === "string" && /^\d{1,78}$/.test(v.trim()))
|
|
41
|
+
n = BigInt(v.trim());
|
|
42
|
+
if (n === null || n < 0n || n > max)
|
|
43
|
+
throw new Error(`guardBudget: ${name} must be a whole number from 0`);
|
|
44
|
+
return n;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* The facilitator budget that mirrors a guard SpendPolicy. Throws when the policy has no USDG per-call or per-day cap
|
|
48
|
+
* and none is passed (the facilitator treats a missing cap as 0, which refuses every payment), or when a list is over 50.
|
|
49
|
+
*/
|
|
50
|
+
export function guardBudget(policy, opts) {
|
|
51
|
+
const sp = (policy && "spend" in policy ? policy.spend : policy) ?? {};
|
|
52
|
+
if (!isAddress(opts.payer))
|
|
53
|
+
throw new Error("guardBudget: payer must be a 0x address");
|
|
54
|
+
const notMirrored = [];
|
|
55
|
+
const assets = sp.assets ?? {};
|
|
56
|
+
const usdgKey = Object.keys(assets).find((k) => k.toLowerCase() === USDG);
|
|
57
|
+
const caps = usdgKey ? assets[usdgKey] : undefined;
|
|
58
|
+
for (const k of Object.keys(assets))
|
|
59
|
+
if (k !== usdgKey)
|
|
60
|
+
notMirrored.push(`assets["${k}"]: the facilitator budget is USDG only`);
|
|
61
|
+
const perPayment = opts.perPayment ?? caps?.perCall;
|
|
62
|
+
const perDay = opts.perDay ?? caps?.perDay;
|
|
63
|
+
if (perPayment === undefined)
|
|
64
|
+
throw new Error("guardBudget: no USDG per-call cap (set spend.assets[USDG].perCall or pass perPayment)");
|
|
65
|
+
if (perDay === undefined)
|
|
66
|
+
throw new Error("guardBudget: no USDG per-day cap (set spend.assets[USDG].perDay or pass perDay)");
|
|
67
|
+
const byPayTo = new Map();
|
|
68
|
+
for (const [prefix, c] of Object.entries(sp.perEndpoint ?? {})) {
|
|
69
|
+
const payTo = opts.endpointPayTo?.[prefix] ?? (isAddress(prefix) ? prefix : undefined);
|
|
70
|
+
if (c.perCall !== undefined)
|
|
71
|
+
notMirrored.push(`perEndpoint["${prefix}"].perCall: the facilitator has no per-payTo per-payment cap (perPayment applies)`);
|
|
72
|
+
if (c.perDay === undefined)
|
|
73
|
+
continue;
|
|
74
|
+
if (!payTo) {
|
|
75
|
+
notMirrored.push(`perEndpoint["${prefix}"].perDay: no payTo known for it (pass endpointPayTo)`);
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
if (!isAddress(payTo))
|
|
79
|
+
throw new Error(`guardBudget: endpointPayTo["${prefix}"] must be a 0x address`);
|
|
80
|
+
const had = byPayTo.get(payTo.toLowerCase());
|
|
81
|
+
// two endpoints paying one wallet: the stricter day cap holds for both
|
|
82
|
+
if (!had || c.perDay < had.perDay)
|
|
83
|
+
byPayTo.set(payTo.toLowerCase(), { payTo, perDay: uint(c.perDay, `perEndpoint["${prefix}"].perDay`) });
|
|
84
|
+
}
|
|
85
|
+
const payToCaps = [...byPayTo.values()];
|
|
86
|
+
const allowed = [];
|
|
87
|
+
for (const a of sp.allow?.payTo ?? []) {
|
|
88
|
+
if (!isAddress(a))
|
|
89
|
+
throw new Error(`guardBudget: allow.payTo entry "${a}" is not an address`);
|
|
90
|
+
if (!allowed.some((x) => x.toLowerCase() === a.toLowerCase()))
|
|
91
|
+
allowed.push(a);
|
|
92
|
+
}
|
|
93
|
+
if (payToCaps.length > BUDGET_MAX_PAYTOS || allowed.length > BUDGET_MAX_PAYTOS)
|
|
94
|
+
throw new Error(`guardBudget: at most ${BUDGET_MAX_PAYTOS} payToCaps and allowed payTos`);
|
|
95
|
+
if (sp.allow?.to?.length || sp.allow?.spender?.length)
|
|
96
|
+
notMirrored.push("allow.to / allow.spender: the facilitator only sees x402 payments (payTo)");
|
|
97
|
+
if (sp.approveAbove || sp.approve)
|
|
98
|
+
notMirrored.push("approveAbove / approve: human approval stays in guard");
|
|
99
|
+
const budget = {
|
|
100
|
+
payer: opts.payer,
|
|
101
|
+
perPayment: uint(perPayment, "perPayment"),
|
|
102
|
+
perDay: uint(perDay, "perDay"),
|
|
103
|
+
perPayTo: uint(opts.perPayTo ?? 0n, "perPayTo"),
|
|
104
|
+
payToCaps,
|
|
105
|
+
allowedPayTos: allowed,
|
|
106
|
+
validUntil: uint(opts.validUntil ?? 0, "validUntil", MAX_U64),
|
|
107
|
+
nonce: uint(opts.nonce, "nonce"),
|
|
108
|
+
};
|
|
109
|
+
return { budget, typedData: { domain: { ...BUDGET_DOMAIN }, types: BUDGET_TYPES, primaryType: "Budget", message: budget }, notMirrored };
|
|
110
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -14,3 +14,5 @@ export { MemorySpendStore, dayStart } from "./store.js";
|
|
|
14
14
|
export type { SpendStore } from "./store.js";
|
|
15
15
|
export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";
|
|
16
16
|
export type { TicketAsk, AllowTicket, TicketResult } from "./ticket.js";
|
|
17
|
+
export { guardBudget, BUDGET_DOMAIN, BUDGET_TYPES, BUDGET_MAX_PAYTOS } from "./budget.js";
|
|
18
|
+
export type { GuardBudget, GuardBudgetOptions, GuardBudgetMessage } from "./budget.js";
|
package/dist/index.js
CHANGED
|
@@ -6,3 +6,4 @@ export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding,
|
|
|
6
6
|
export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
|
|
7
7
|
export { MemorySpendStore, dayStart } from "./store.js";
|
|
8
8
|
export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";
|
|
9
|
+
export { guardBudget, BUDGET_DOMAIN, BUDGET_TYPES, BUDGET_MAX_PAYTOS } from "./budget.js";
|
package/package.json
CHANGED
|
@@ -1,70 +1,70 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@tollxyz/guard",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, viem smart-account, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain: transactions, messages, typed data, batches, user operations, EIP-7702 authorizations. Spend caps, allowlists and human approval around the verdict; single-use ALLOW tickets for contracts that require one. Zero runtime dependencies.",
|
|
5
|
-
"license": "MIT",
|
|
6
|
-
"author": "Toll",
|
|
7
|
-
"type": "module",
|
|
8
|
-
"main": "./dist/index.js",
|
|
9
|
-
"types": "./dist/index.d.ts",
|
|
10
|
-
"exports": {
|
|
11
|
-
".": {
|
|
12
|
-
"types": "./dist/index.d.ts",
|
|
13
|
-
"import": "./dist/index.js"
|
|
14
|
-
}
|
|
15
|
-
},
|
|
16
|
-
"files": [
|
|
17
|
-
"dist",
|
|
18
|
-
"README.md"
|
|
19
|
-
],
|
|
20
|
-
"engines": {
|
|
21
|
-
"node": ">=20.19"
|
|
22
|
-
},
|
|
23
|
-
"publishConfig": {
|
|
24
|
-
"access": "public"
|
|
25
|
-
},
|
|
26
|
-
"repository": {
|
|
27
|
-
"type": "git",
|
|
28
|
-
"url": "git+https://github.com/t0ll-xyz/toll-plugins.git",
|
|
29
|
-
"directory": "packages/guard"
|
|
30
|
-
},
|
|
31
|
-
"homepage": "https://t0ll.xyz/agents/plugins",
|
|
32
|
-
"keywords": [
|
|
33
|
-
"agent-wallet",
|
|
34
|
-
"transaction-guard",
|
|
35
|
-
"pre-sign",
|
|
36
|
-
"x402",
|
|
37
|
-
"erc-8004",
|
|
38
|
-
"erc-8470",
|
|
39
|
-
"erc-8265",
|
|
40
|
-
"allow-ticket",
|
|
41
|
-
"robinhood-chain",
|
|
42
|
-
"viem",
|
|
43
|
-
"ethers",
|
|
44
|
-
"ai-agent",
|
|
45
|
-
"toll"
|
|
46
|
-
],
|
|
47
|
-
"scripts": {
|
|
48
|
-
"build": "tsc -p tsconfig.json",
|
|
49
|
-
"test": "tsc -p tsconfig.json --noEmit && tsx --test tests/*.test.ts",
|
|
50
|
-
"smoke": "node scripts/smoke.mjs",
|
|
51
|
-
"prepublishOnly": "npm run build"
|
|
52
|
-
},
|
|
53
|
-
"peerDependencies": {
|
|
54
|
-
"ethers": "^6.0.0",
|
|
55
|
-
"viem": "^2.0.0"
|
|
56
|
-
},
|
|
57
|
-
"peerDependenciesMeta": {
|
|
58
|
-
"ethers": {
|
|
59
|
-
"optional": true
|
|
60
|
-
},
|
|
61
|
-
"viem": {
|
|
62
|
-
"optional": true
|
|
63
|
-
}
|
|
64
|
-
},
|
|
65
|
-
"devDependencies": {
|
|
66
|
-
"@types/node": "^22.0.0",
|
|
67
|
-
"tsx": "^4.19.0",
|
|
68
|
-
"typescript": "^5.6.0"
|
|
69
|
-
}
|
|
70
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@tollxyz/guard",
|
|
3
|
+
"version": "0.5.0",
|
|
4
|
+
"description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, viem smart-account, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain: transactions, messages, typed data, batches, user operations, EIP-7702 authorizations. Spend caps, allowlists and human approval around the verdict; single-use ALLOW tickets for contracts that require one. Zero runtime dependencies.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Toll",
|
|
7
|
+
"type": "module",
|
|
8
|
+
"main": "./dist/index.js",
|
|
9
|
+
"types": "./dist/index.d.ts",
|
|
10
|
+
"exports": {
|
|
11
|
+
".": {
|
|
12
|
+
"types": "./dist/index.d.ts",
|
|
13
|
+
"import": "./dist/index.js"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"README.md"
|
|
19
|
+
],
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=20.19"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"access": "public"
|
|
25
|
+
},
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "git+https://github.com/t0ll-xyz/toll-plugins.git",
|
|
29
|
+
"directory": "packages/guard"
|
|
30
|
+
},
|
|
31
|
+
"homepage": "https://t0ll.xyz/agents/plugins",
|
|
32
|
+
"keywords": [
|
|
33
|
+
"agent-wallet",
|
|
34
|
+
"transaction-guard",
|
|
35
|
+
"pre-sign",
|
|
36
|
+
"x402",
|
|
37
|
+
"erc-8004",
|
|
38
|
+
"erc-8470",
|
|
39
|
+
"erc-8265",
|
|
40
|
+
"allow-ticket",
|
|
41
|
+
"robinhood-chain",
|
|
42
|
+
"viem",
|
|
43
|
+
"ethers",
|
|
44
|
+
"ai-agent",
|
|
45
|
+
"toll"
|
|
46
|
+
],
|
|
47
|
+
"scripts": {
|
|
48
|
+
"build": "tsc -p tsconfig.json",
|
|
49
|
+
"test": "tsc -p tsconfig.json --noEmit && tsx --test tests/*.test.ts",
|
|
50
|
+
"smoke": "node scripts/smoke.mjs",
|
|
51
|
+
"prepublishOnly": "npm run build"
|
|
52
|
+
},
|
|
53
|
+
"peerDependencies": {
|
|
54
|
+
"ethers": "^6.0.0",
|
|
55
|
+
"viem": "^2.0.0"
|
|
56
|
+
},
|
|
57
|
+
"peerDependenciesMeta": {
|
|
58
|
+
"ethers": {
|
|
59
|
+
"optional": true
|
|
60
|
+
},
|
|
61
|
+
"viem": {
|
|
62
|
+
"optional": true
|
|
63
|
+
}
|
|
64
|
+
},
|
|
65
|
+
"devDependencies": {
|
|
66
|
+
"@types/node": "^22.0.0",
|
|
67
|
+
"tsx": "^4.19.0",
|
|
68
|
+
"typescript": "^5.6.0"
|
|
69
|
+
}
|
|
70
|
+
}
|