presign-guard-wallet 0.17.0 → 0.18.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
@@ -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
 
@@ -130,6 +130,7 @@ What counts as spending:
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
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 Algorand with `algorandSigner(…, { any: true })`: ALGO paid and assets sent by the account's own transactions in the group (ALGO toward `ALGO`, USDC toward `USDC`, other assets as tokens without a limit). A close-out, rekey or clawback counts as unknown spending;
133
134
  - 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.
134
135
 
135
136
  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`).
@@ -250,7 +251,7 @@ const xrpl = guarded.xrplSigner(createXrplWalletSigner(Wallet.fromSeed(process.e
250
251
  client.register("xrpl:*", new ExactXrplScheme(xrpl)); // x402 payments in RLUSD, checked and within limits
251
252
  ```
252
253
 
253
- `network` is `"xrpl:0"` (mainnet) or `"xrpl:1"` (testnet). The check itself is still paid on Base (or with credits).
254
+ `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.
254
255
 
255
256
  ## Algorand (USDC)
256
257
 
@@ -265,7 +266,14 @@ const algo = guarded.algorandSigner(toClientAvmSigner(process.env.AVM_PRIVATE_KE
265
266
  client.register("algorand:*", new ExactAvmScheme(algo)); // x402 payments in USDC on Algorand, within limits
266
267
  ```
267
268
 
268
- `network` is the mainnet id above (default) or `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` (testnet). The account must be opted in to USDC. Algorand transfers aren't sent to presign-guard (it checks EVM and XRPL); the local rules above are the check.
269
+ `network` is the mainnet id above (default) or `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` (testnet). The account must be opted in to USDC. An x402 USDC payment is checked by the local rules above, without a presign-guard call.
270
+
271
+ **Other Algorand transactions.** With `{ any: true }` the signer also signs other transactions and atomic groups: payments in ALGO, asset transfers, app calls, for an agent that does more than pay x402 APIs. The whole group goes to presign-guard first (`type: "algorand"`): a rekey to another key, closing the account or an asset holding to someone else, or fake USDC is red and never signed; clawbacks, risky opt-ins, app update/delete/clear-state and a group that would fail are orange (`onOrange`). Only this account's own transactions in the group are signed. What they send counts toward your limits: ALGO toward an `ALGO` limit, USDC toward `USDC`, other assets as tokens without a limit; a close-out, rekey or clawback counts as unknown spending, so it goes to `onOverLimit`.
272
+
273
+ ```js
274
+ const algo = guarded.algorandSigner(toClientAvmSigner(process.env.AVM_PRIVATE_KEY), { any: true });
275
+ // limits: { tokens: { USDC: { perDay: "5" }, ALGO: { perTx: "10", perDay: "25" } } }
276
+ ```
269
277
 
270
278
  ## Solana (USDC)
271
279
 
@@ -281,7 +289,7 @@ const sol = guarded.solanaSigner(keypair); // mainnet; { network: "solana:EtWTRA
281
289
  client.register("solana:*", new ExactSvmScheme(sol)); // x402 payments in USDC on Solana, checked and within limits
282
290
  ```
283
291
 
284
- The check itself is still paid on Base (or with credits).
292
+ The check itself is paid through `pay`, which can pay it in USDC on Solana too (or with credits).
285
293
 
286
294
  **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
295
 
package/index.d.ts CHANGED
@@ -153,7 +153,7 @@ export interface GuardControls {
153
153
  * A guarded Algorand signer for @x402/avm (ExactAvmScheme): signs only the agent's own USDC transfer in a
154
154
  * payment group (no close-out, rekey or clawback), counted toward the USDC limits; anything else is refused.
155
155
  */
156
- algorandSigner<S extends { address: string; signTransactions(txns: Uint8Array[], indexesToSign?: number[]): Promise<(Uint8Array | null)[]> }>(signer: S, opts?: { network?: string }): S;
156
+ algorandSigner<S extends { address: string; signTransactions(txns: Uint8Array[], indexesToSign?: number[]): Promise<(Uint8Array | null)[]> }>(signer: S, opts?: { network?: string; any?: boolean }): S;
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;
package/index.js CHANGED
@@ -39,7 +39,9 @@
39
39
  //
40
40
  // Algorand: algorandSigner(signer) wraps an x402 AVM client signer (toClientAvmSigner from @x402/avm). It
41
41
  // signs only an asset transfer of USDC from that account (no close-out, rekey or clawback), checked here
42
- // (presign-guard doesn't cover Algorand) and counted toward the USDC limits.
42
+ // and counted toward the USDC limits. With { any: true } it also signs other transactions and groups, each
43
+ // checked by presign-guard first (type "algorand": rekeys, closes, clawbacks, fake USDC, simulated); what
44
+ // the account's own transactions send counts toward the limits (ALGO toward ALGO, USDC toward USDC).
43
45
  //
44
46
  // XRP Ledger: xrplSigner(signer) wraps an XRPL signer ({ classicAddress, sign(tx) },
45
47
  // e.g. createXrplWalletSigner from @x402/xrpl) the same way. It signs only
@@ -79,7 +81,7 @@ const ESCROW_ABI = parseAbi([
79
81
  const TRANSFER_ABI = parseAbi(["function transfer(address to, uint256 amount)"]);
80
82
  const VOUCHER_DOMAIN = "TIP20 Channel Reserve";
81
83
  export const XRPL_NETWORKS = ["xrpl:0", "xrpl:1"];
82
- export const VERSION = "0.17.0";
84
+ export const VERSION = "0.18.0";
83
85
  export const CREDIT_HEADER = "x-credit-key";
84
86
  const ROUTE = "POST /v1/check";
85
87
 
@@ -292,7 +294,7 @@ export function guardWallet(wallet, {
292
294
 
293
295
  // The verdict for a request, or null when the check could not be done and onError is "allow".
294
296
  async function verdictFor(method, request, chainId) {
295
- if (request.type !== "message" && request.type !== "solana" && !SUPPORTED_CHAINS.includes(chainId) && !XRPL_NETWORKS.includes(chainId)) {
297
+ if (request.type !== "message" && request.type !== "solana" && request.type !== "algorand" && !SUPPORTED_CHAINS.includes(chainId) && !XRPL_NETWORKS.includes(chainId)) {
296
298
  if (onError === "allow") return null;
297
299
  throw new PresignBlockedError(`chain ${chainId} is not covered by presign-guard; nothing was signed`, { code: "unsupported_chain", request });
298
300
  }
@@ -396,11 +398,15 @@ export function guardWallet(wallet, {
396
398
  return limiter ? withinLimits("signXrplPayment", request, verdict, run) : run();
397
399
  }
398
400
 
399
- // Algorand: sign only a USDC transfer from this address, within the limits (Algorand is not covered by presign-guard).
400
- async function algorandSign(signer, network, txns, indexesToSign) {
401
+ // Algorand: sign only a USDC transfer from this address, within the limits (checked here, no presign-guard
402
+ // call); with any, anything else goes to presign-guard first (algorandSignAny).
403
+ async function algorandSign(signer, network, txns, indexesToSign, any) {
401
404
  if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
402
405
  const mine = (indexesToSign ?? txns.map((_, i) => i)).filter((i) => Number.isInteger(i) && i >= 0 && i < txns.length);
403
- if (mine.length !== 1) throw new PresignBlockedError(`on Algorand this wallet signs one USDC transfer per payment (asked for ${mine.length}); nothing was signed`, { code: "unsupported_chain" });
406
+ if (mine.length !== 1) {
407
+ if (any) return algorandSignAny(signer, network, txns, indexesToSign);
408
+ throw new PresignBlockedError(`on Algorand this wallet signs one USDC transfer per payment (asked for ${mine.length}); nothing was signed`, { code: "unsupported_chain" });
409
+ }
404
410
  let t;
405
411
  try { t = readAlgorandTxn(txns[mine[0]]); } catch (err) { throw new PresignBlockedError(`could not read the Algorand transaction (${err.message}); nothing was signed`, { code: "unsupported_chain" }); }
406
412
  const usdc = ALGORAND_USDC[network];
@@ -412,12 +418,36 @@ export function guardWallet(wallet, {
412
418
  : t.clawbackFrom ? "it is a clawback"
413
419
  : !t.receiver ? "it has no receiver"
414
420
  : null;
421
+ if (why && any) return algorandSignAny(signer, network, txns, indexesToSign);
415
422
  if (why) throw new PresignBlockedError(`on Algorand this wallet only sends USDC: ${why}; nothing was signed`, { code: "unsupported_chain" });
416
423
  const request = { type: "algorand", network, txn: { type: t.type, sender: t.sender, receiver: t.receiver, amount: String(t.amount), assetId: String(t.assetId) }, ...(origin ? { origin } : {}) };
417
424
  const run = () => signer.signTransactions(txns, mine);
418
425
  return limiter ? withinLimits("signAlgorandTransfer", request, null, run) : run();
419
426
  }
420
427
 
428
+ // Any other Algorand transaction or group (algorandSigner with any): the whole group goes to presign-guard (type
429
+ // "algorand", which also simulates it); red is never signed. What this account's own transactions send, read
430
+ // from the transactions themselves, counts toward the limits.
431
+ async function algorandSignAny(signer, network, txns, indexesToSign) {
432
+ let read;
433
+ try { read = txns.map((b) => readAlgorandTxn(b)); } catch (err) {
434
+ throw new PresignBlockedError(`could not read the Algorand transactions (${err.message}); nothing was signed`, { code: "unsupported_chain" });
435
+ }
436
+ const mine = indexesToSign ?? read.flatMap((t, i) => (t.sender === signer.address ? [i] : []));
437
+ if (!mine.length || mine.some((i) => !Number.isInteger(i) || i < 0 || i >= txns.length || read[i].sender !== signer.address)) {
438
+ throw new PresignBlockedError("on Algorand this wallet signs only transactions sent from its own account; nothing was signed", { code: "unsupported_chain" });
439
+ }
440
+ const request = { type: "algorand", transactions: txns.map((b) => Buffer.from(b).toString("base64")), from: signer.address, ...(origin ? { origin } : {}) };
441
+ const verdict = await verdictFor("signAlgorandTransaction", request, network);
442
+ if (verdict?.subject?.network && verdict.subject.network !== network) {
443
+ throw new PresignBlockedError(`the transactions are for ${verdict.subject.network}, not ${network}; nothing was signed`, { code: "unsupported_chain", verdict, request });
444
+ }
445
+ const str = (v) => (v === null || v === undefined ? null : String(v));
446
+ const group = mine.map((i) => read[i]).map((t) => ({ type: t.type, sender: t.sender, receiver: t.receiver, amount: str(t.amount), assetId: str(t.assetId), closeTo: t.closeTo, rekeyTo: t.rekeyTo, clawbackFrom: t.clawbackFrom }));
447
+ const run = () => signer.signTransactions(txns, mine);
448
+ return limiter ? withinLimits("signAlgorandTransaction", { type: "algorand", network, from: signer.address, group }, verdict, run) : run();
449
+ }
450
+
421
451
  // Solana: sign only an x402 payment (one USDC TransferChecked from this account, compute-budget settings and a
422
452
  // memo), each checked by presign-guard (decoded and simulated) and counted toward the USDC limit.
423
453
  async function solanaSign(signer, network, transactions, config, any) {
@@ -502,7 +532,9 @@ export function guardWallet(wallet, {
502
532
  * toClientAvmSigner from @x402/avm): of the transactions it is asked to sign it signs only an asset transfer
503
533
  * of USDC on that network from this address (no close-out, rekey or clawback), counted toward the USDC limit.
504
534
  * The facilitator's fee-payer transaction in the same group is not this signer's and is left unsigned.
505
- * network: the x402 id of Algorand mainnet (default) or testnet.
535
+ * network: the x402 id of Algorand mainnet (default) or testnet. any: also sign other transactions and
536
+ * groups (payments in ALGO, asset transfers, app calls), each group checked by presign-guard first; what
537
+ * this account's transactions send counts toward the limits (ALGO toward ALGO, USDC toward USDC).
506
538
  */
507
539
  /**
508
540
  * The same guard on a Solana signer for x402's SVM client (a @solana/kit TransactionPartialSigner, e.g.
@@ -516,10 +548,10 @@ export function guardWallet(wallet, {
516
548
  if (!SOLANA_USDC[network]) throw new TypeError(`solanaSigner: network must be one of ${Object.keys(SOLANA_USDC).join(", ")}`);
517
549
  return { address: signer.address, signTransactions: (transactions, config) => solanaSign(signer, network, transactions, config, any === true) };
518
550
  },
519
- algorandSigner: (signer, { network = "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=" } = {}) => {
551
+ algorandSigner: (signer, { network = "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=", any = false } = {}) => {
520
552
  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)");
521
553
  if (!ALGORAND_USDC[network]) throw new TypeError(`algorandSigner: network must be one of ${Object.keys(ALGORAND_USDC).join(", ")}`);
522
- return { address: signer.address, signTransactions: (txns, indexesToSign) => algorandSign(signer, network, txns, indexesToSign) };
554
+ return { address: signer.address, signTransactions: (txns, indexesToSign) => algorandSign(signer, network, txns, indexesToSign, any === true) };
523
555
  },
524
556
  /** Stop every checked method until resume(). */
525
557
  pause: () => { paused = true; },
package/limits.js CHANGED
@@ -44,8 +44,8 @@ const USDC = {
44
44
  4217: [["0x20c000000000000000000000b9537d11c60e8b50", 6]],
45
45
  42431: [["0x20c0000000000000000000000000000000000000", 6]],
46
46
  };
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"];
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"])), ...Object.fromEntries(Object.keys(ALGORAND_USDC).map((n) => [n, "ALGO"])) };
48
+ export const KNOWN_TOKENS = ["USDC", "ETH", "BNB", "POL", "XRP", "SOL", "ALGO"];
49
49
 
50
50
  // XRP Ledger networks and the RLUSD issuer on each (Ripple's).
51
51
  export const XRPL_RLUSD_ISSUERS = { "xrpl:0": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", "xrpl:1": "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV" };
@@ -103,6 +103,8 @@ export function normalizeLimits(limits) {
103
103
  for (const net of Object.keys(XRPL_RLUSD_ISSUERS)) put(`${net}:${NATIVE}`, { budget: name, decimals: 6 });
104
104
  } else if (symbol === "SOL") {
105
105
  for (const net of Object.keys(SOLANA_USDC)) put(`${net}:${NATIVE}`, { budget: name, decimals: 9 });
106
+ } else if (symbol === "ALGO") {
107
+ for (const net of Object.keys(ALGORAND_USDC)) put(`${net}:${NATIVE}`, { budget: name, decimals: 6 });
106
108
  } else if (["ETH", "BNB", "POL"].includes(symbol)) {
107
109
  for (const [chain, s] of Object.entries(NATIVE_SYMBOL)) if (s === symbol) put(`${chain}:${NATIVE}`, { budget: name, decimals: 18 });
108
110
  } else {
@@ -190,9 +192,26 @@ function xrplSpend(request, out) {
190
192
  }
191
193
 
192
194
  // An Algorand asset transfer (read from the unsigned transaction by algorandSigner): the asset, amount and receiver.
193
- // Anything else (a payment in ALGO, a close-out, a rekey, a clawback) can't be counted and is unknown.
195
+ // Anything else (a payment in ALGO, a close-out, a rekey, a clawback) can't be counted and is unknown. With any, a
196
+ // group of this account's transactions: ALGO paid and assets sent; a close-out, rekey or clawback is unknown.
194
197
  function algorandSpend(request, out) {
195
198
  const net = request.network;
199
+ if (Array.isArray(request.group)) {
200
+ const digits = (v) => /^\d+$/.test(String(v ?? ""));
201
+ for (const t of request.group) {
202
+ const to = typeof t.receiver === "string" ? t.receiver : null;
203
+ if (t.rekeyTo || t.closeTo || t.clawbackFrom) { out.unknown = true; out.counterparties.push(t.rekeyTo ?? t.closeTo ?? t.clawbackFrom); continue; }
204
+ if (t.type === "pay") {
205
+ if (!digits(t.amount)) { out.unknown = true; continue; }
206
+ if (BigInt(t.amount) > 0n && to !== t.sender) { out.items.push({ chainId: net, token: NATIVE, amount: BigInt(t.amount), to }); out.counterparties.push(to); }
207
+ } else if (t.type === "axfer") {
208
+ if (!digits(t.amount) || !digits(t.assetId)) { out.unknown = true; continue; }
209
+ if (BigInt(t.amount) > 0n && to !== t.sender) { out.items.push({ chainId: net, token: String(t.assetId), amount: BigInt(t.amount), to }); out.counterparties.push(to); }
210
+ }
211
+ // App calls, asset config and freeze, key registration: they move nothing out of this account by themselves.
212
+ }
213
+ return out;
214
+ }
196
215
  const t = request.txn ?? {};
197
216
  const to = typeof t.receiver === "string" ? lower(t.receiver) : null;
198
217
  out.counterparties.push(to);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "presign-guard-wallet",
3
- "version": "0.17.0",
4
- "description": "A viem wallet for AI agents that asks presign-guard ($0.01 over x402) before every transaction, contract write and typed-data signature, refuses to sign red, and keeps to per-token spending limits, with approval from your phone over the limit.",
3
+ "version": "0.18.0",
4
+ "description": "A wallet for AI agents (viem on EVM chains, Solana and Algorand) 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,8 @@
61
61
  "agents",
62
62
  "wallet",
63
63
  "viem",
64
+ "solana",
65
+ "algorand",
64
66
  "security",
65
67
  "presign",
66
68
  "approvals",