presign-guard-wallet 0.1.0 → 0.3.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/LICENSE +21 -21
- package/README.md +145 -80
- package/file-store.d.ts +4 -0
- package/file-store.js +29 -0
- package/index.d.ts +145 -49
- package/index.js +241 -149
- package/limits.js +245 -0
- package/package.json +65 -56
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Frits Zwager
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Frits Zwager
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,80 +1,145 @@
|
|
|
1
|
-
# presign-guard-wallet
|
|
2
|
-
|
|
3
|
-
A [viem](https://viem.sh) wallet for AI agents that asks [presign-guard](https://presign-guard.fizzl.eu) before it signs.
|
|
4
|
-
|
|
5
|
-
Before every `sendTransaction`, `writeContract` and `signTypedData`, the wallet pays **$0.01** (x402, USDC on Base) for a verdict on exactly what is about to be signed, and acts on it:
|
|
6
|
-
|
|
7
|
-
| Verdict | What the wallet does |
|
|
8
|
-
|---|---|
|
|
9
|
-
| 🟢 green | Signs |
|
|
10
|
-
| 🟠 orange | `onOrange`: `"stop"` (default, throws), `"allow"`, or your own function (e.g. ask the user) |
|
|
11
|
-
| 🔴 red | Throws `PresignBlockedError` with the reasons; **nothing is signed** |
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
import {
|
|
27
|
-
import {
|
|
28
|
-
import {
|
|
29
|
-
import {
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
const
|
|
38
|
-
|
|
39
|
-
const
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
|
56
|
-
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
##
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
1
|
+
# presign-guard-wallet
|
|
2
|
+
|
|
3
|
+
A [viem](https://viem.sh) wallet for AI agents that asks [presign-guard](https://presign-guard.fizzl.eu) before it signs.
|
|
4
|
+
|
|
5
|
+
Before every `sendTransaction`, `writeContract` and `signTypedData`, the wallet pays **$0.01** (x402, USDC on Base) for a verdict on exactly what is about to be signed, and acts on it:
|
|
6
|
+
|
|
7
|
+
| Verdict | What the wallet does |
|
|
8
|
+
|---|---|
|
|
9
|
+
| 🟢 green | Signs |
|
|
10
|
+
| 🟠 orange | `onOrange`: `"stop"` (default, throws), `"allow"`, or your own function (e.g. ask the user) |
|
|
11
|
+
| 🔴 red | Throws `PresignBlockedError` with the reasons; **nothing is signed** |
|
|
12
|
+
|
|
13
|
+
On top of that it can keep to **spending limits** you set per token (per transaction and per day), and ask a human for anything over them. See [Spending limits](#spending-limits).
|
|
14
|
+
|
|
15
|
+
presign-guard decodes approvals, `increaseAllowance`, `setApprovalForAll`, EIP-2612 and Permit2 permits, EIP-3009 transfer authorizations (what an x402 payment signs) and Seaport orders, and screens every spender, recipient and token: known drainers and phishing addresses, sanctions, unlimited approvals to a plain wallet, honeypot tokens, unverified or brand-new contracts, and, with `origin`, new or lookalike domains and phishing sites. See the [reason codes](https://github.com/Fizzl13/presign-guard#reason-codes).
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npm install presign-guard-wallet viem @x402/fetch @x402/evm
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Use
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import { createWalletClient, http } from "viem";
|
|
27
|
+
import { base } from "viem/chains";
|
|
28
|
+
import { privateKeyToAccount } from "viem/accounts";
|
|
29
|
+
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
|
|
30
|
+
import { ExactEvmScheme } from "@x402/evm/exact/client";
|
|
31
|
+
import { guardWallet, PresignBlockedError } from "presign-guard-wallet";
|
|
32
|
+
|
|
33
|
+
const account = privateKeyToAccount(process.env.AGENT_KEY); // the agent's wallet
|
|
34
|
+
const walletClient = createWalletClient({ account, chain: base, transport: http() });
|
|
35
|
+
|
|
36
|
+
// Pays for the checks: a few dollars of USDC on Base, capped per payment.
|
|
37
|
+
const payer = new x402Client().setSpendControls({ maxAmountPerPayment: "$0.02" });
|
|
38
|
+
payer.register("eip155:8453", new ExactEvmScheme(privateKeyToAccount(process.env.PAYER_KEY)));
|
|
39
|
+
const pay = wrapFetchWithPayment(fetch, payer);
|
|
40
|
+
|
|
41
|
+
const wallet = guardWallet(walletClient, { pay, onOrange: "stop" });
|
|
42
|
+
|
|
43
|
+
try {
|
|
44
|
+
await wallet.writeContract({ address: token, abi: erc20Abi, functionName: "approve", args: [spender, amount] });
|
|
45
|
+
} catch (err) {
|
|
46
|
+
if (err instanceof PresignBlockedError) console.log(err.code, err.message, err.verdict?.reasons);
|
|
47
|
+
else throw err;
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`wallet` is the same client: every other method (`getAddresses`, `signMessage`, `extend`, …) works as before, unchecked.
|
|
52
|
+
|
|
53
|
+
## Options
|
|
54
|
+
|
|
55
|
+
| Option | Default | |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `pay` | required (optional with `creditKey`) | A fetch that pays x402 (`wrapFetchWithPayment`); cap it with spend controls |
|
|
58
|
+
| `creditKey` | | A presign-guard credit key (`pgc_…`): checks are paid from prepaid credits first, then with `pay`. See [Prepaid credits](#prepaid-credits) |
|
|
59
|
+
| `fetch` | `globalThis.fetch` | Plain fetch used for credit-paid checks |
|
|
60
|
+
| `onOrange` | `"stop"` | `"stop"`, `"allow"` or `async (verdict, { method, request }) => boolean` |
|
|
61
|
+
| `onError` | `"stop"` | When the check cannot be done (outage, a chain presign-guard does not cover): `"stop"` or `"allow"` |
|
|
62
|
+
| `origin` | | The site asking for the signature: its domain age and phishing lists are checked too |
|
|
63
|
+
| `onVerdict` | | `(verdict, { method, request, paidWith, creditsLeft }) => void`, e.g. for logging; `paidWith` is `"credits"` or `"x402"` |
|
|
64
|
+
| `verifyReceipts` | `"require"` | Check presign-guard's signed receipt on every verdict; `"off"` skips it |
|
|
65
|
+
| `signers` | presign-guard's published signer | Accepted signer addresses |
|
|
66
|
+
| `authority` | the Fizzl payout wallet | Wallet whose certificates also make a signer trusted (key rotation); `null` accepts only `signers` |
|
|
67
|
+
| `limits` | | Spending limits per token, see [Spending limits](#spending-limits) |
|
|
68
|
+
| `onOverLimit` | | `async (info) => boolean`: asked when a limit would be crossed; `true` signs anyway. Without it the wallet stops |
|
|
69
|
+
| `onSpend` | | `(entry) => void` after each signed spend, e.g. for a log |
|
|
70
|
+
| `store` | in memory | Where spending is kept; `fileStore(path)` from `presign-guard-wallet/file-store`, or your own |
|
|
71
|
+
|
|
72
|
+
Chains: Ethereum (1), Optimism (10), BNB Chain (56), Polygon (137), Base (8453), Arbitrum (42161).
|
|
73
|
+
|
|
74
|
+
## Prepaid credits
|
|
75
|
+
|
|
76
|
+
Agents that sign a lot can prepay: one x402 payment of **$0.80 for 100 checks** or **$7.00 for 1000** (20% / 30% off), valid for a year.
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
// once: buy a pack with your x402 fetch and keep the key somewhere safe
|
|
80
|
+
const { credit_key } = await (await pay("https://presign-guard.fizzl.eu/v1/credits/100")).json();
|
|
81
|
+
|
|
82
|
+
const wallet = guardWallet(walletClient, { creditKey: credit_key, pay }); // pay = fallback when the credits run out
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Each check then sends the key instead of paying. When the credits are used up (or the key is unknown or expired) the wallet pays per check with `pay`; without `pay` it stops, and nothing is signed. Verdicts are signed and checked exactly as with per-check payment. Keep the key secret: anyone who has it can spend the credits.
|
|
86
|
+
|
|
87
|
+
## Spending limits
|
|
88
|
+
|
|
89
|
+
Give the agent a budget instead of a blank cheque:
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
import { guardWallet, PresignBlockedError } from "presign-guard-wallet";
|
|
93
|
+
import { fileStore } from "presign-guard-wallet/file-store";
|
|
94
|
+
|
|
95
|
+
const wallet = guardWallet(walletClient, {
|
|
96
|
+
pay,
|
|
97
|
+
limits: {
|
|
98
|
+
tokens: {
|
|
99
|
+
USDC: { perTx: "5", perDay: "20" }, // whole tokens; native and bridged USDC on every chain
|
|
100
|
+
ETH: { perTx: "0.002", perDay: "0.01" }, // the native coin; also BNB, POL
|
|
101
|
+
// any other token by address (any chain) or "chainId:0x…", with its decimals:
|
|
102
|
+
// "8453:0x4200…0006": { perDay: "0.01", decimals: 18 },
|
|
103
|
+
},
|
|
104
|
+
unknownTokens: "ask", // a token without a limit: "ask" (default), "stop" or "allow"
|
|
105
|
+
allow: ["0xShop…", "0xRouter…"], // optional: only these recipients, spenders and contracts
|
|
106
|
+
window: "24h", // the rolling window perDay applies to
|
|
107
|
+
},
|
|
108
|
+
// over a limit: a human decides (true = sign anyway); without it the wallet stops
|
|
109
|
+
onOverLimit: async ({ summary }) => askUserOnPhone(`Agent wants to sign: ${summary}. OK?`),
|
|
110
|
+
onSpend: (e) => console.log(`spent ${e.amount} ${e.budget} → ${e.to} (${e.result})`),
|
|
111
|
+
store: fileStore("./spending.json"), // survives restarts; default is in memory
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
await wallet.spending(); // [{ token: "USDC", perTx: "5", perDay: "20", used: "8.5", left: "11.5" }, …]
|
|
115
|
+
wallet.pause(); // emergency stop: nothing is signed until wallet.resume()
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The order for every signature: presign-guard's verdict first (red never reaches a human), then `onOrange`, then the limits. Over a limit, the wallet throws `PresignBlockedError` with code `over_limit` and `err.reasons` (`per_tx`, `per_day`, `unknown_token`, `unknown_spend`, `not_allowed`), unless `onOverLimit` returns `true`.
|
|
119
|
+
|
|
120
|
+
What counts as spending:
|
|
121
|
+
|
|
122
|
+
- the native value sent with a transaction, also with a contract deployment;
|
|
123
|
+
- an ERC-20 `transfer` or `transferFrom`;
|
|
124
|
+
- an **allowance** (`approve`, `increaseAllowance`, Permit, Permit2): whoever gets it can spend that amount, so it counts when it is given. An unlimited allowance or `setApprovalForAll` is over any limit, and if a human approves one anyway it uses up the rest of the window. Revoking costs nothing;
|
|
125
|
+
- an EIP-3009 payment or Permit2 transfer signature, read from presign-guard's signed verdict. A signature it cannot decode counts as unknown spending (`unknownTokens`).
|
|
126
|
+
|
|
127
|
+
Other contract calls (a swap that uses an allowance you already gave) spend nothing new: the allowance was counted when it was given. Budgets are shared across chains (`USDC: { perDay: "20" }` is 20 USDC in total), checked one at a time so parallel transactions cannot both fit in the last of a budget, booked before signing and given back when signing fails. A store that cannot be read stops the wallet (`limit_unavailable`).
|
|
128
|
+
|
|
129
|
+
These limits live in your agent's software: they stop a confused or manipulated agent, not someone who has the private key. For limits the chain enforces, use a smart account with session keys; the same budget can then be set there.
|
|
130
|
+
|
|
131
|
+
## Signed verdicts
|
|
132
|
+
|
|
133
|
+
presign-guard signs every paid verdict (EIP-191 over canonical JSON, with a hash of your request inside the signed body; see [Signed verdicts](https://github.com/Fizzl13/presign-guard#signed-verdicts)). The wallet checks that signature before it acts:
|
|
134
|
+
|
|
135
|
+
- the verdict must be signed by presign-guard's published signer, `0xf084Ea47Ca4D99BB4De3ECB0332b316bE6521EaE` (pinned in the package), or a key the Fizzl payout wallet (`0x6B0F4651eD42893ab58139938175E4a69f175F25`) certified for presign-guard;
|
|
136
|
+
- the signature must cover exactly the request that was checked;
|
|
137
|
+
- otherwise it throws `PresignBlockedError` with code `bad_receipt`, also with `onError: "allow"`: a forged or changed "green" is never a signature.
|
|
138
|
+
|
|
139
|
+
## Costs and coverage
|
|
140
|
+
|
|
141
|
+
- $0.01 per checked signature, paid with your `pay` fetch, or $0.008 / $0.007 with [prepaid credits](#prepaid-credits). Calls presign-guard does not cover (`signMessage`, contract deployments) are not checked and cost nothing.
|
|
142
|
+
- presign-guard reads public data (GoPlus, RugCheck, DexScreener, OFAC via PG1, phishing lists). A green verdict means no known problem was found, not a guarantee.
|
|
143
|
+
- The requests carry `user-agent: presign-guard-wallet/<version>` so the service can count how often the package is used.
|
|
144
|
+
|
|
145
|
+
MIT licensed.
|
package/file-store.d.ts
ADDED
package/file-store.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// A spending store in a JSON file, so limits survive a restart (Node only;
|
|
2
|
+
// one process per file). For several agents sharing one budget, pass your own
|
|
3
|
+
// store with the same three methods, backed by a database.
|
|
4
|
+
import { readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
5
|
+
|
|
6
|
+
const KEEP_MS = 31 * 86_400_000;
|
|
7
|
+
|
|
8
|
+
export function fileStore(path) {
|
|
9
|
+
if (typeof path !== "string" || !path) throw new TypeError("fileStore needs a file path");
|
|
10
|
+
const read = () => {
|
|
11
|
+
try {
|
|
12
|
+
const data = JSON.parse(readFileSync(path, "utf8"));
|
|
13
|
+
return Array.isArray(data) ? data : [];
|
|
14
|
+
} catch (err) {
|
|
15
|
+
if (err.code === "ENOENT") return [];
|
|
16
|
+
throw new Error(`spending file ${path} is unreadable (${err.message}); fix or remove it`);
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
const write = (entries) => {
|
|
20
|
+
const tmp = `${path}.tmp`;
|
|
21
|
+
writeFileSync(tmp, JSON.stringify(entries.filter((e) => e.at >= Date.now() - KEEP_MS), null, 1));
|
|
22
|
+
renameSync(tmp, path);
|
|
23
|
+
};
|
|
24
|
+
return {
|
|
25
|
+
async add(entry) { write([...read(), entry]); },
|
|
26
|
+
async remove(id) { write(read().filter((e) => e.id !== id)); },
|
|
27
|
+
async list(since) { return read().filter((e) => e.at >= since); },
|
|
28
|
+
};
|
|
29
|
+
}
|
package/index.d.ts
CHANGED
|
@@ -1,49 +1,145 @@
|
|
|
1
|
-
import type { WalletClient } from "viem";
|
|
2
|
-
|
|
3
|
-
export declare const PRESIGN_URL: string;
|
|
4
|
-
export declare const PRESIGN_SIGNERS: string[];
|
|
5
|
-
export declare const SUPPORTED_CHAINS: number[];
|
|
6
|
-
export declare const VERSION: string;
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
subject?: Record<string, unknown>;
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
| { type: "
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
/**
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
|
|
43
|
-
/**
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
export
|
|
1
|
+
import type { WalletClient } from "viem";
|
|
2
|
+
|
|
3
|
+
export declare const PRESIGN_URL: string;
|
|
4
|
+
export declare const PRESIGN_SIGNERS: string[];
|
|
5
|
+
export declare const SUPPORTED_CHAINS: number[];
|
|
6
|
+
export declare const VERSION: string;
|
|
7
|
+
export declare const CREDIT_HEADER: string;
|
|
8
|
+
|
|
9
|
+
/** A presign-guard verdict: see https://presign-guard.fizzl.eu/openapi.json */
|
|
10
|
+
export interface PresignVerdict {
|
|
11
|
+
verdict: "green" | "orange" | "red";
|
|
12
|
+
reasons?: Array<{ code: string; severity: "red" | "orange" | "info"; subject?: string; details?: Record<string, unknown> }>;
|
|
13
|
+
subject?: Record<string, unknown>;
|
|
14
|
+
receipt?: Record<string, unknown>;
|
|
15
|
+
[key: string]: unknown;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** What is sent to presign-guard's POST /v1/check. */
|
|
19
|
+
export type CheckRequest =
|
|
20
|
+
| { type: "transaction"; chainId: number; to: string; data: string; value: string; origin?: string }
|
|
21
|
+
| { type: "signature"; chainId: number; typedData: unknown; origin?: string };
|
|
22
|
+
|
|
23
|
+
export declare class PresignBlockedError extends Error {
|
|
24
|
+
code: "red" | "orange" | "check_failed" | "bad_receipt" | "unsupported_chain" | "over_limit" | "paused" | "limit_unavailable";
|
|
25
|
+
verdict: PresignVerdict | null;
|
|
26
|
+
request: CheckRequest | null;
|
|
27
|
+
/** With code "over_limit": which limits would be crossed. */
|
|
28
|
+
reasons?: LimitReason[];
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** A limit in whole tokens, e.g. "5" or "0.002". */
|
|
32
|
+
export type TokenAmount = string | number;
|
|
33
|
+
|
|
34
|
+
export interface SpendingLimits {
|
|
35
|
+
/**
|
|
36
|
+
* Per token: "USDC" (native and bridged USDC on every supported chain), "ETH", "BNB", "POL" (the native coin),
|
|
37
|
+
* a token address ("0x…", any chain) or "chainId:0x…"; tokens given by address need decimals.
|
|
38
|
+
* Budgets are shared across chains: { USDC: { perDay: "20" } } is 20 USDC in total.
|
|
39
|
+
*/
|
|
40
|
+
tokens?: Record<string, { perTx?: TokenAmount; perDay?: TokenAmount; decimals?: number }>;
|
|
41
|
+
/** Spending of a token without a limit, or a signature whose spending cannot be read. Default "ask" (onOverLimit, else stop). */
|
|
42
|
+
unknownTokens?: "stop" | "ask" | "allow";
|
|
43
|
+
/** Only these recipients, spenders and contracts; anything else goes to onOverLimit. */
|
|
44
|
+
allow?: string[];
|
|
45
|
+
/** The rolling window perDay applies to. Default "24h". */
|
|
46
|
+
window?: string | number;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface LimitReason {
|
|
50
|
+
code: "per_tx" | "per_day" | "unknown_token" | "unknown_spend" | "not_allowed";
|
|
51
|
+
message: string;
|
|
52
|
+
budget?: string;
|
|
53
|
+
amount?: string;
|
|
54
|
+
limit?: string;
|
|
55
|
+
used?: string;
|
|
56
|
+
token?: string;
|
|
57
|
+
to?: string | null;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export interface SpendingRow {
|
|
61
|
+
token: string;
|
|
62
|
+
perTx: string | null;
|
|
63
|
+
perDay: string | null;
|
|
64
|
+
used: string;
|
|
65
|
+
left: string | null;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface OverLimitInfo {
|
|
69
|
+
method: string;
|
|
70
|
+
request: CheckRequest;
|
|
71
|
+
verdict: PresignVerdict | null;
|
|
72
|
+
reasons: LimitReason[];
|
|
73
|
+
/** One line for a human, e.g. "8 USDC is over the limit of 20 per 24h (15 used)". */
|
|
74
|
+
summary: string;
|
|
75
|
+
spending: SpendingRow[];
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface SpendEntry {
|
|
79
|
+
id: string;
|
|
80
|
+
at: number;
|
|
81
|
+
budget: string;
|
|
82
|
+
/** In whole tokens. */
|
|
83
|
+
amount: string;
|
|
84
|
+
method: string;
|
|
85
|
+
chainId: number;
|
|
86
|
+
to: string | null;
|
|
87
|
+
/** What the wallet method returned (transaction hash or signature). */
|
|
88
|
+
result: unknown;
|
|
89
|
+
verdict: PresignVerdict | null;
|
|
90
|
+
receiptId: string | null;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** Where spending is kept. amount is a decimal string at 18 decimals. */
|
|
94
|
+
export interface SpendingStore {
|
|
95
|
+
add(entry: { id: string; at: number; budget: string; amount: string; [key: string]: unknown }): Promise<void>;
|
|
96
|
+
remove(id: string): Promise<void>;
|
|
97
|
+
list(since: number): Promise<Array<{ id: string; at: number; budget: string; amount: string }>>;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export declare function memoryStore(): SpendingStore;
|
|
101
|
+
|
|
102
|
+
/** Added to the guarded wallet. */
|
|
103
|
+
export interface GuardControls {
|
|
104
|
+
/** Stop every checked method (sendTransaction, writeContract, signTypedData) until resume(). */
|
|
105
|
+
pause(): void;
|
|
106
|
+
resume(): void;
|
|
107
|
+
paused(): boolean;
|
|
108
|
+
/** Per token: the limits, what was spent in the current window and what is left; null without limits. */
|
|
109
|
+
spending(): Promise<SpendingRow[] | null>;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface GuardOptions {
|
|
113
|
+
/** A fetch that pays x402, e.g. wrapFetchWithPayment(fetch, client) with spend controls. Each check costs $0.01. Optional when creditKey is set. */
|
|
114
|
+
pay?: typeof globalThis.fetch;
|
|
115
|
+
/** A presign-guard credit key (pgc_…, from GET https://presign-guard.fizzl.eu/v1/credits/100 or /1000): checks are paid from prepaid credits first, then with pay. */
|
|
116
|
+
creditKey?: string;
|
|
117
|
+
/** Plain fetch used for credit-paid checks. Default globalThis.fetch. */
|
|
118
|
+
fetch?: typeof globalThis.fetch;
|
|
119
|
+
/** What to do on an orange verdict. Default "stop". */
|
|
120
|
+
onOrange?: "stop" | "allow" | ((verdict: PresignVerdict, info: { method: string; request: CheckRequest }) => boolean | Promise<boolean>);
|
|
121
|
+
/** When the check cannot be done (outage, unsupported chain). Default "stop". A forged or changed verdict always stops. */
|
|
122
|
+
onError?: "stop" | "allow";
|
|
123
|
+
/** The site asking for the signature, if any: domain age and phishing lists are checked. */
|
|
124
|
+
origin?: string;
|
|
125
|
+
onVerdict?: (verdict: PresignVerdict, info: { method: string; request: CheckRequest; paidWith: "credits" | "x402"; creditsLeft: number | null }) => void;
|
|
126
|
+
presignUrl?: string;
|
|
127
|
+
/** Check presign-guard's signed receipt on every verdict. Default "require". */
|
|
128
|
+
verifyReceipts?: "require" | "off";
|
|
129
|
+
/** Accepted signer addresses. Default: the published signer (PRESIGN_SIGNERS). */
|
|
130
|
+
signers?: string[];
|
|
131
|
+
/** Wallet whose certificates also make a signer trusted (key rotation). Default: the Fizzl payout wallet; null accepts only `signers`. */
|
|
132
|
+
authority?: string | null;
|
|
133
|
+
/** Spending limits per token, checked after presign-guard's verdict and before signing. */
|
|
134
|
+
limits?: SpendingLimits;
|
|
135
|
+
/** Asked when a limit would be crossed (e.g. ask the user on their phone). true = sign anyway. Without it, the wallet stops. */
|
|
136
|
+
onOverLimit?: (info: OverLimitInfo) => boolean | Promise<boolean>;
|
|
137
|
+
/** Called after each signed spend, e.g. for a log. */
|
|
138
|
+
onSpend?: (entry: SpendEntry) => void;
|
|
139
|
+
/** Where spending is kept. Default in memory (gone on a restart); fileStore from "presign-guard-wallet/file-store" for a file. */
|
|
140
|
+
store?: SpendingStore;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** The same wallet client; sendTransaction, writeContract and signTypedData are checked first. */
|
|
144
|
+
export declare function guardWallet<W extends WalletClient>(wallet: W, options: GuardOptions): W & GuardControls;
|
|
145
|
+
export declare function checkRequestFor(method: string, args: unknown, options?: { chainId?: number; origin?: string }): CheckRequest | null;
|