presign-guard-wallet 0.16.0 → 0.17.1
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 +13 -5
- package/index.d.ts +3 -2
- package/index.js +23 -7
- package/limits.js +33 -3
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# presign-guard-wallet
|
|
2
2
|
|
|
3
|
-
A [viem](https://viem.sh) wallet for AI agents that asks [presign-guard](https://presign-guard.fizzl.eu) before it signs.
|
|
3
|
+
A [viem](https://viem.sh) wallet for AI agents that asks [presign-guard](https://presign-guard.fizzl.eu) before it signs. Solana signers too: see [Solana](#solana-usdc).
|
|
4
4
|
|
|
5
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
6
|
|
|
@@ -104,7 +104,7 @@ const wallet = guardWallet(walletClient, {
|
|
|
104
104
|
limits: {
|
|
105
105
|
tokens: {
|
|
106
106
|
USDC: { perTx: "5", perDay: "20" }, // whole tokens; native and bridged USDC on every chain
|
|
107
|
-
ETH: { perTx: "0.002", perDay: "0.01" }, // the native coin; also BNB, POL
|
|
107
|
+
ETH: { perTx: "0.002", perDay: "0.01" }, // the native coin; also BNB, POL, XRP, SOL
|
|
108
108
|
// any other token by address (any chain) or "chainId:0x…", with its decimals:
|
|
109
109
|
// "8453:0x4200…0006": { perDay: "0.01", decimals: 18 },
|
|
110
110
|
},
|
|
@@ -129,7 +129,8 @@ What counts as spending:
|
|
|
129
129
|
- the native value sent with a transaction, also with a contract deployment;
|
|
130
130
|
- an ERC-20 `transfer` or `transferFrom`;
|
|
131
131
|
- 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;
|
|
132
|
-
- 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`)
|
|
132
|
+
- 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`);
|
|
133
|
+
- on Solana with `solanaSigner(…, { any: true })`: what presign-guard's signed simulation shows leaving the wallet. SOL beyond the network fee counts toward `SOL`, USDC toward `USDC`, other tokens as tokens without a limit. A token delegate is over any limit, and a transaction without a complete simulation counts as unknown spending.
|
|
133
134
|
|
|
134
135
|
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`).
|
|
135
136
|
|
|
@@ -249,7 +250,7 @@ const xrpl = guarded.xrplSigner(createXrplWalletSigner(Wallet.fromSeed(process.e
|
|
|
249
250
|
client.register("xrpl:*", new ExactXrplScheme(xrpl)); // x402 payments in RLUSD, checked and within limits
|
|
250
251
|
```
|
|
251
252
|
|
|
252
|
-
`network` is `"xrpl:0"` (mainnet) or `"xrpl:1"` (testnet). The check itself is
|
|
253
|
+
`network` is `"xrpl:0"` (mainnet) or `"xrpl:1"` (testnet). The check itself is paid through `pay` (Base, Solana, XRPL or Algorand, whatever your x402 client can pay) or with credits.
|
|
253
254
|
|
|
254
255
|
## Algorand (USDC)
|
|
255
256
|
|
|
@@ -280,7 +281,14 @@ const sol = guarded.solanaSigner(keypair); // mainnet; { network: "solana:EtWTRA
|
|
|
280
281
|
client.register("solana:*", new ExactSvmScheme(sol)); // x402 payments in USDC on Solana, checked and within limits
|
|
281
282
|
```
|
|
282
283
|
|
|
283
|
-
The check itself is
|
|
284
|
+
The check itself is paid through `pay`, which can pay it in USDC on Solana too (or with credits).
|
|
285
|
+
|
|
286
|
+
**Other Solana transactions.** With `{ any: true }` the signer also signs transfers, swaps and other transactions, for an agent that does more than pay x402 APIs (an AgentKit Solana wallet, for example). Each one is checked by presign-guard first: every instruction is read and the transaction is simulated, so a token account handed to someone else is red, and a hidden owner or delegate change is orange. What the simulation shows leaving the wallet counts toward your limits: SOL beyond the network fee toward a `SOL` limit, USDC toward `USDC`. Without a complete simulation the spending counts as unknown, so it goes to `onOverLimit`.
|
|
287
|
+
|
|
288
|
+
```js
|
|
289
|
+
const sol = guarded.solanaSigner(keypair, { any: true });
|
|
290
|
+
// limits: { tokens: { USDC: { perDay: "5" }, SOL: { perTx: "0.1", perDay: "0.5" } } }
|
|
291
|
+
```
|
|
284
292
|
|
|
285
293
|
## MPP sessions on Tempo
|
|
286
294
|
|
package/index.d.ts
CHANGED
|
@@ -157,9 +157,10 @@ export interface GuardControls {
|
|
|
157
157
|
/**
|
|
158
158
|
* A guarded Solana signer for @x402/svm (ExactSvmScheme): signs only an x402 USDC payment from this account
|
|
159
159
|
* (compute budget, one TransferChecked, memo), checked by presign-guard and counted toward the USDC limits;
|
|
160
|
-
* anything else is refused
|
|
160
|
+
* anything else is refused, unless `any`: then it is checked by presign-guard and what its simulation shows
|
|
161
|
+
* leaving the wallet counts toward the limits (SOL, USDC; other tokens as unknown).
|
|
161
162
|
*/
|
|
162
|
-
solanaSigner<S extends { address: string; signTransactions(txs: readonly { messageBytes: Uint8Array }[], config?: unknown): Promise<readonly Record<string, Uint8Array>[]> }>(signer: S, opts?: { network?: string }): Pick<S, "address" | "signTransactions">;
|
|
163
|
+
solanaSigner<S extends { address: string; signTransactions(txs: readonly { messageBytes: Uint8Array }[], config?: unknown): Promise<readonly Record<string, Uint8Array>[]> }>(signer: S, opts?: { network?: string; any?: boolean }): Pick<S, "address" | "signTransactions">;
|
|
163
164
|
/** The same guard (checks, limits, pause, purchases) on another WalletClient, e.g. one for Tempo: both spend from one budget. */
|
|
164
165
|
wrap<W extends object>(wallet: W): W & GuardControls;
|
|
165
166
|
}
|
package/index.js
CHANGED
|
@@ -56,7 +56,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
|
|
|
56
56
|
|
|
57
57
|
import { mandateFor } from "./mandate.js";
|
|
58
58
|
import { ALGORAND_USDC, readAlgorandTxn } from "./algorand.js";
|
|
59
|
-
import { SOLANA_USDC, readSolanaPayment, wireTransaction } from "./solana.js";
|
|
59
|
+
import { SOLANA_USDC, readSolanaMessage, readSolanaPayment, wireTransaction } from "./solana.js";
|
|
60
60
|
export { ALGORAND_USDC } from "./algorand.js";
|
|
61
61
|
export { mandatePayer, mandateDigest, mandateBinding } from "./mandate.js";
|
|
62
62
|
export { memoryStore };
|
|
@@ -79,7 +79,7 @@ const ESCROW_ABI = parseAbi([
|
|
|
79
79
|
const TRANSFER_ABI = parseAbi(["function transfer(address to, uint256 amount)"]);
|
|
80
80
|
const VOUCHER_DOMAIN = "TIP20 Channel Reserve";
|
|
81
81
|
export const XRPL_NETWORKS = ["xrpl:0", "xrpl:1"];
|
|
82
|
-
export const VERSION = "0.
|
|
82
|
+
export const VERSION = "0.17.1";
|
|
83
83
|
export const CREDIT_HEADER = "x-credit-key";
|
|
84
84
|
const ROUTE = "POST /v1/check";
|
|
85
85
|
|
|
@@ -420,13 +420,15 @@ export function guardWallet(wallet, {
|
|
|
420
420
|
|
|
421
421
|
// Solana: sign only an x402 payment (one USDC TransferChecked from this account, compute-budget settings and a
|
|
422
422
|
// memo), each checked by presign-guard (decoded and simulated) and counted toward the USDC limit.
|
|
423
|
-
async function solanaSign(signer, network, transactions, config) {
|
|
423
|
+
async function solanaSign(signer, network, transactions, config, any) {
|
|
424
424
|
const out = [];
|
|
425
425
|
for (const tx of transactions) {
|
|
426
426
|
if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
|
|
427
427
|
let payment;
|
|
428
428
|
try { payment = readSolanaPayment(tx.messageBytes, signer.address, network); } catch (err) {
|
|
429
|
-
throw new PresignBlockedError(`on Solana this wallet only signs x402 USDC payments: ${err.message}; nothing was signed`, { code: "unsupported_chain" });
|
|
429
|
+
if (!any) throw new PresignBlockedError(`on Solana this wallet only signs x402 USDC payments: ${err.message}; nothing was signed`, { code: "unsupported_chain" });
|
|
430
|
+
out.push(await solanaSignAny(signer, network, tx, config));
|
|
431
|
+
continue;
|
|
430
432
|
}
|
|
431
433
|
const request = { type: "solana", transaction: wireTransaction(tx.messageBytes, payment.numSigners), from: signer.address, ...(origin ? { origin } : {}) };
|
|
432
434
|
const verdict = await verdictFor("signSolanaTransfer", request, network);
|
|
@@ -437,6 +439,19 @@ export function guardWallet(wallet, {
|
|
|
437
439
|
return out;
|
|
438
440
|
}
|
|
439
441
|
|
|
442
|
+
// Any other Solana transaction (solanaSigner with any): checked by presign-guard, which also simulates it;
|
|
443
|
+
// what the signed simulation shows leaving the wallet counts toward the limits.
|
|
444
|
+
async function solanaSignAny(signer, network, tx, config) {
|
|
445
|
+
let numSigners;
|
|
446
|
+
try { ({ numSigners } = readSolanaMessage(tx.messageBytes)); } catch (err) {
|
|
447
|
+
throw new PresignBlockedError(`not a Solana transaction this wallet can read (${err.message}); nothing was signed`, { code: "unsupported_chain" });
|
|
448
|
+
}
|
|
449
|
+
const request = { type: "solana", transaction: wireTransaction(tx.messageBytes, numSigners), from: signer.address, ...(origin ? { origin } : {}) };
|
|
450
|
+
const verdict = await verdictFor("signSolanaTransaction", request, network);
|
|
451
|
+
const run = async () => (await signer.signTransactions([tx], config))[0];
|
|
452
|
+
return limiter ? withinLimits("signSolanaTransaction", { type: "solana", network, simulated: true, from: signer.address }, verdict, run) : run();
|
|
453
|
+
}
|
|
454
|
+
|
|
440
455
|
const extras = {
|
|
441
456
|
/**
|
|
442
457
|
* The same guard on an XRP Ledger signer ({ classicAddress, sign(tx) }, e.g. createXrplWalletSigner
|
|
@@ -493,12 +508,13 @@ export function guardWallet(wallet, {
|
|
|
493
508
|
* The same guard on a Solana signer for x402's SVM client (a @solana/kit TransactionPartialSigner, e.g.
|
|
494
509
|
* createKeyPairSignerFromBytes): it signs only an x402 payment (one USDC TransferChecked from this account),
|
|
495
510
|
* checked by presign-guard (decoded and simulated) and counted toward the USDC limit. network: mainnet
|
|
496
|
-
* (default) or devnet, as x402 CAIP-2 ids.
|
|
511
|
+
* (default) or devnet, as x402 CAIP-2 ids. any: also sign other transactions (transfers, swaps), each
|
|
512
|
+
* checked by presign-guard; what its simulation shows leaving the wallet counts toward the limits.
|
|
497
513
|
*/
|
|
498
|
-
solanaSigner: (signer, { network = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" } = {}) => {
|
|
514
|
+
solanaSigner: (signer, { network = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", any = false } = {}) => {
|
|
499
515
|
if (!signer || typeof signer.signTransactions !== "function" || typeof signer.address !== "string") throw new TypeError("solanaSigner(signer): signer needs address and signTransactions(transactions) (a @solana/kit TransactionPartialSigner, e.g. createKeyPairSignerFromBytes)");
|
|
500
516
|
if (!SOLANA_USDC[network]) throw new TypeError(`solanaSigner: network must be one of ${Object.keys(SOLANA_USDC).join(", ")}`);
|
|
501
|
-
return { address: signer.address, signTransactions: (transactions, config) => solanaSign(signer, network, transactions, config) };
|
|
517
|
+
return { address: signer.address, signTransactions: (transactions, config) => solanaSign(signer, network, transactions, config, any === true) };
|
|
502
518
|
},
|
|
503
519
|
algorandSigner: (signer, { network = "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=" } = {}) => {
|
|
504
520
|
if (!signer || typeof signer.signTransactions !== "function" || typeof signer.address !== "string") throw new TypeError("algorandSigner(signer): signer needs address and signTransactions(txns, indexesToSign) (e.g. toClientAvmSigner from @x402/avm)");
|
package/limits.js
CHANGED
|
@@ -12,6 +12,10 @@
|
|
|
12
12
|
// - an EIP-3009 payment or Permit2 transfer signature;
|
|
13
13
|
// - an Algorand asset transfer: USDC (ASA 31566704) counts toward the USDC limit;
|
|
14
14
|
// - a Solana USDC transfer (x402 SVM payment): counts toward the USDC limit;
|
|
15
|
+
// - any other Solana transaction (solanaSigner with any): what presign-guard's signed simulation shows
|
|
16
|
+
// leaving the wallet, SOL (beyond the network fee) toward a SOL limit, USDC toward the USDC limit,
|
|
17
|
+
// other tokens as unknown; a token delegate is over any limit, and no or an incomplete simulation
|
|
18
|
+
// counts as unknown spending;
|
|
15
19
|
// - an XRP Ledger Payment: XRP (drops) counts toward an XRP limit, RLUSD from
|
|
16
20
|
// Ripple's issuer toward the USDC limit (a dollar is a dollar), any other
|
|
17
21
|
// issued currency as an unknown token. SendMax, when set, is what can leave.
|
|
@@ -40,8 +44,8 @@ const USDC = {
|
|
|
40
44
|
4217: [["0x20c000000000000000000000b9537d11c60e8b50", 6]],
|
|
41
45
|
42431: [["0x20c0000000000000000000000000000000000000", 6]],
|
|
42
46
|
};
|
|
43
|
-
const NATIVE_SYMBOL = { 1: "ETH", 10: "ETH", 8453: "ETH", 42161: "ETH", 56: "BNB", 137: "POL", "xrpl:0": "XRP", "xrpl:1": "XRP" };
|
|
44
|
-
export const KNOWN_TOKENS = ["USDC", "ETH", "BNB", "POL", "XRP"];
|
|
47
|
+
const NATIVE_SYMBOL = { 1: "ETH", 10: "ETH", 8453: "ETH", 42161: "ETH", 56: "BNB", 137: "POL", "xrpl:0": "XRP", "xrpl:1": "XRP", ...Object.fromEntries(Object.keys(SOLANA_USDC).map((n) => [n, "SOL"])) };
|
|
48
|
+
export const KNOWN_TOKENS = ["USDC", "ETH", "BNB", "POL", "XRP", "SOL"];
|
|
45
49
|
|
|
46
50
|
// XRP Ledger networks and the RLUSD issuer on each (Ripple's).
|
|
47
51
|
export const XRPL_RLUSD_ISSUERS = { "xrpl:0": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", "xrpl:1": "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV" };
|
|
@@ -97,6 +101,8 @@ export function normalizeLimits(limits) {
|
|
|
97
101
|
for (const [net, mint] of Object.entries(SOLANA_USDC)) put(`${net}:${mint}`, { budget: name, decimals: 6 });
|
|
98
102
|
} else if (symbol === "XRP") {
|
|
99
103
|
for (const net of Object.keys(XRPL_RLUSD_ISSUERS)) put(`${net}:${NATIVE}`, { budget: name, decimals: 6 });
|
|
104
|
+
} else if (symbol === "SOL") {
|
|
105
|
+
for (const net of Object.keys(SOLANA_USDC)) put(`${net}:${NATIVE}`, { budget: name, decimals: 9 });
|
|
100
106
|
} else if (["ETH", "BNB", "POL"].includes(symbol)) {
|
|
101
107
|
for (const [chain, s] of Object.entries(NATIVE_SYMBOL)) if (s === symbol) put(`${chain}:${NATIVE}`, { budget: name, decimals: 18 });
|
|
102
108
|
} else {
|
|
@@ -121,7 +127,7 @@ export function spendFor(request, verdict) {
|
|
|
121
127
|
const out = { items: [], counterparties: [], unknown: false };
|
|
122
128
|
if (request.type === "xrpl") return xrplSpend(request, out);
|
|
123
129
|
if (request.type === "algorand") return algorandSpend(request, out);
|
|
124
|
-
if (request.type === "solana") return solanaSpend(request, out);
|
|
130
|
+
if (request.type === "solana") return request.simulated ? solanaSimulatedSpend(request, verdict, out) : solanaSpend(request, out);
|
|
125
131
|
const chainId = request.chainId;
|
|
126
132
|
if (request.type === "transaction") {
|
|
127
133
|
const to = lower(request.to ?? null);
|
|
@@ -204,6 +210,30 @@ function solanaSpend(request, out) {
|
|
|
204
210
|
return out;
|
|
205
211
|
}
|
|
206
212
|
|
|
213
|
+
// Any Solana transaction: what leaves the wallet in presign-guard's signed simulation (base units).
|
|
214
|
+
function solanaSimulatedSpend(request, verdict, out) {
|
|
215
|
+
const sim = verdict?.simulation;
|
|
216
|
+
out.counterparties.push(null); // no single receiver to hold against an allow list
|
|
217
|
+
if (!sim || !sim.ok || sim.partial || !Array.isArray(sim.changes)) { out.unknown = true; return out; }
|
|
218
|
+
const chainId = request.network;
|
|
219
|
+
const fee = typeof sim.fee === "number" ? BigInt(Math.round(sim.fee * 1e9)) : 0n;
|
|
220
|
+
for (const c of sim.changes) {
|
|
221
|
+
if (c.type === "sol" && c.account === request.from) {
|
|
222
|
+
if (!/^-?\d+$/.test(String(c.lamports ?? ""))) { out.unknown = true; continue; }
|
|
223
|
+
const leaving = -BigInt(c.lamports) - fee;
|
|
224
|
+
if (leaving > 0n) out.items.push({ chainId, token: NATIVE, amount: leaving, to: null });
|
|
225
|
+
} else if (c.type === "token") {
|
|
226
|
+
if (!/^-?\d+$/.test(String(c.raw ?? ""))) { out.unknown = true; continue; }
|
|
227
|
+
if (BigInt(c.raw) < 0n) out.items.push({ chainId, token: c.mint, amount: -BigInt(c.raw), to: null });
|
|
228
|
+
} else if (c.type === "delegate") {
|
|
229
|
+
out.items.push({ chainId, token: c.mint, amount: null, to: c.delegate }); // someone else may spend it later
|
|
230
|
+
} else if (c.type === "owner") {
|
|
231
|
+
out.unknown = true;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
return out;
|
|
235
|
+
}
|
|
236
|
+
|
|
207
237
|
const fmt = (x) => (x === null ? "unlimited" : formatUnits(x, SCALE));
|
|
208
238
|
const short = (a) => (a ? `${a.slice(0, 6)}…${a.slice(-4)}` : "a new contract");
|
|
209
239
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "presign-guard-wallet",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "A
|
|
3
|
+
"version": "0.17.1",
|
|
4
|
+
"description": "A wallet for AI agents (viem on EVM chains, and Solana) that asks presign-guard ($0.01 over x402) before every transaction, contract write and signature, refuses to sign red, and keeps to per-token spending limits, with approval from your phone over the limit.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
7
7
|
".": {
|
|
@@ -61,6 +61,7 @@
|
|
|
61
61
|
"agents",
|
|
62
62
|
"wallet",
|
|
63
63
|
"viem",
|
|
64
|
+
"solana",
|
|
64
65
|
"security",
|
|
65
66
|
"presign",
|
|
66
67
|
"approvals",
|