presign-guard-wallet 0.9.0 → 0.10.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
@@ -215,6 +215,22 @@ client.register("eip155:8453", mandatePayer(new ExactEvmScheme(signer), mandate)
215
215
 
216
216
  Only single payments are checked; the cumulative spend against the cap needs the mandate's accountant. Permit2 payments pass through unbound. The draft is still open, so details may change.
217
217
 
218
+ ## XRP Ledger (RLUSD and XRP)
219
+
220
+ `xrplSigner` guards an XRPL signer the same way: before a `Payment` is signed it goes to presign-guard as `{ type: "xrpl", network, tx }` (destination, issuer of the token, flags), and red or orange stops it. Spending limits apply too: RLUSD from Ripple's issuer counts toward your `USDC` limit, drops toward `XRP`, any other token is unknown (`onUnknown`). The agent keeps its own XRPL key; anything but a `Payment` is refused.
221
+
222
+ ```js
223
+ import { Wallet } from "xrpl";
224
+ import { createXrplWalletSigner } from "@x402/xrpl";
225
+ import { ExactXrplScheme } from "@x402/xrpl/exact/client";
226
+
227
+ const guarded = guardWallet(walletClient, { pay, limits: { tokens: { USDC: { perDay: "5" } } } });
228
+ const xrpl = guarded.xrplSigner(createXrplWalletSigner(Wallet.fromSeed(process.env.XRPL_SEED)), { network: "xrpl:0" });
229
+ client.register("xrpl:*", new ExactXrplScheme(xrpl)); // x402 payments in RLUSD, checked and within limits
230
+ ```
231
+
232
+ `network` is `"xrpl:0"` (mainnet) or `"xrpl:1"` (testnet). The check itself is still paid on Base (or with credits).
233
+
218
234
  ## Signed verdicts
219
235
 
220
236
  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:
package/index.js CHANGED
@@ -31,6 +31,13 @@
31
31
  // transferWithMemo of USDC.e (pathUSD on the testnet), with no value attached,
32
32
  // which counts toward the USDC limits like any other USDC transfer. Anything
33
33
  // else on Tempo is refused (code "unsupported_chain").
34
+ //
35
+ // XRP Ledger: xrplSigner(signer) wraps an XRPL signer ({ classicAddress, sign(tx) },
36
+ // e.g. createXrplWalletSigner from @x402/xrpl) the same way. It signs only
37
+ // Payment transactions, each checked by presign-guard first (type "xrpl": fake
38
+ // RLUSD, partial payments, missing destination tags, issuer risks) and counted
39
+ // toward the limits (XRP toward an XRP limit, RLUSD toward USDC). Use it with
40
+ // @x402/xrpl's ExactXrplScheme to pay x402 services in RLUSD.
34
41
 
35
42
  import { encodeFunctionData } from "viem";
36
43
  import { verifyReceipt, AUTHORITY } from "x402-safe-fetch";
@@ -51,7 +58,8 @@ export const TEMPO_TOKENS = {
51
58
  42431: ["0x20c0000000000000000000000000000000000000"],
52
59
  };
53
60
  const TEMPO_TRANSFERS = new Set(["transfer", "transferWithMemo"]);
54
- export const VERSION = "0.9.0";
61
+ export const XRPL_NETWORKS = ["xrpl:0", "xrpl:1"];
62
+ export const VERSION = "0.10.0";
55
63
  export const CREDIT_HEADER = "x-credit-key";
56
64
  const ROUTE = "POST /v1/check";
57
65
 
@@ -192,7 +200,7 @@ export function guardWallet(wallet, {
192
200
 
193
201
  // The verdict for a request, or null when the check could not be done and onError is "allow".
194
202
  async function verdictFor(method, request, chainId) {
195
- if (!SUPPORTED_CHAINS.includes(chainId)) {
203
+ if (!SUPPORTED_CHAINS.includes(chainId) && !XRPL_NETWORKS.includes(chainId)) {
196
204
  if (onError === "allow") return null;
197
205
  throw new PresignBlockedError(`chain ${chainId} is not covered by presign-guard; nothing was signed`, { code: "unsupported_chain", request });
198
206
  }
@@ -275,7 +283,32 @@ export function guardWallet(wallet, {
275
283
  return limiter ? withinLimits(method, request, verdict, run) : run();
276
284
  }
277
285
 
286
+ // XRP Ledger: sign a Payment only after presign-guard's check and within the limits.
287
+ async function xrplSign(signer, network, tx) {
288
+ if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
289
+ if (!tx || typeof tx !== "object" || tx.TransactionType !== "Payment") {
290
+ throw new PresignBlockedError(`on the XRP Ledger this wallet only signs Payment transactions (got ${tx?.TransactionType ?? "nothing"}); nothing was signed`, { code: "unsupported_chain" });
291
+ }
292
+ if (tx.Account && signer.classicAddress && tx.Account !== signer.classicAddress) {
293
+ throw new PresignBlockedError(`the transaction's Account ${tx.Account} is not this signer (${signer.classicAddress}); nothing was signed`, { code: "unsupported_chain" });
294
+ }
295
+ const request = { type: "xrpl", network, tx: JSON.parse(JSON.stringify(tx)), ...(origin ? { origin } : {}) };
296
+ const verdict = await verdictFor("signXrplPayment", request, network);
297
+ const run = () => signer.sign(tx);
298
+ return limiter ? withinLimits("signXrplPayment", request, verdict, run) : run();
299
+ }
300
+
278
301
  const extras = {
302
+ /**
303
+ * The same guard on an XRP Ledger signer ({ classicAddress, sign(tx) }, e.g. createXrplWalletSigner
304
+ * from @x402/xrpl): only Payment transactions, each checked by presign-guard and counted toward the
305
+ * limits (RLUSD toward USDC, XRP toward an XRP limit). network: "xrpl:0" (default) or "xrpl:1".
306
+ */
307
+ xrplSigner: (signer, { network = "xrpl:0" } = {}) => {
308
+ if (!signer || typeof signer.sign !== "function") throw new TypeError("xrplSigner(signer): signer needs a sign(tx) function (e.g. createXrplWalletSigner from @x402/xrpl)");
309
+ if (!XRPL_NETWORKS.includes(network)) throw new TypeError(`xrplSigner: network must be one of ${XRPL_NETWORKS.join(", ")}`);
310
+ return { classicAddress: signer.classicAddress, sign: (tx) => xrplSign(signer, network, tx) };
311
+ },
279
312
  /** Stop every checked method until resume(). */
280
313
  pause: () => { paused = true; },
281
314
  resume: () => { paused = false; },
package/limits.js CHANGED
@@ -9,7 +9,10 @@
9
9
  // - an allowance (approve, increaseAllowance, Permit, Permit2): whoever gets
10
10
  // it can spend that amount, so it counts when it is given; an unlimited
11
11
  // one or setApprovalForAll is over any limit;
12
- // - an EIP-3009 payment or Permit2 transfer signature.
12
+ // - an EIP-3009 payment or Permit2 transfer signature;
13
+ // - an XRP Ledger Payment: XRP (drops) counts toward an XRP limit, RLUSD from
14
+ // Ripple's issuer toward the USDC limit (a dollar is a dollar), any other
15
+ // issued currency as an unknown token. SendMax, when set, is what can leave.
13
16
  // Transactions are decoded here; typed-data signatures are read from the
14
17
  // signed subject of presign-guard's verdict. A signature presign-guard could
15
18
  // not decode (or one signed without a verdict) counts as unknown spending.
@@ -33,8 +36,13 @@ const USDC = {
33
36
  4217: [["0x20c000000000000000000000b9537d11c60e8b50", 6]],
34
37
  42431: [["0x20c0000000000000000000000000000000000000", 6]],
35
38
  };
36
- const NATIVE_SYMBOL = { 1: "ETH", 10: "ETH", 8453: "ETH", 42161: "ETH", 56: "BNB", 137: "POL" };
37
- export const KNOWN_TOKENS = ["USDC", "ETH", "BNB", "POL"];
39
+ const NATIVE_SYMBOL = { 1: "ETH", 10: "ETH", 8453: "ETH", 42161: "ETH", 56: "BNB", 137: "POL", "xrpl:0": "XRP", "xrpl:1": "XRP" };
40
+ export const KNOWN_TOKENS = ["USDC", "ETH", "BNB", "POL", "XRP"];
41
+
42
+ // XRP Ledger networks and the RLUSD issuer on each (Ripple's).
43
+ export const XRPL_RLUSD_ISSUERS = { "xrpl:0": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", "xrpl:1": "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV" };
44
+ const RLUSD_HEX = "524C555344000000000000000000000000000000";
45
+ const XRPL_ADDRESS_RE = /^r[1-9A-HJ-NP-Za-km-z]{24,34}$/;
38
46
 
39
47
  const ERC20_ABI = parseAbi([
40
48
  "function approve(address spender, uint256 amount)",
@@ -45,7 +53,7 @@ const ERC20_ABI = parseAbi([
45
53
  "function setApprovalForAll(address operator, bool approved)",
46
54
  ]);
47
55
 
48
- const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
56
+ const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$|^r[1-9A-HJ-NP-Za-km-z]{24,34}$/;
49
57
  const lower = (a) => (typeof a === "string" ? a.toLowerCase() : a);
50
58
 
51
59
  export function parseWindow(window) {
@@ -67,7 +75,7 @@ export function normalizeLimits(limits) {
67
75
  if (!limits || typeof limits !== "object") throw new TypeError("limits must be an object");
68
76
  const { tokens = {}, unknownTokens = "ask", allow, window } = limits;
69
77
  if (!["stop", "ask", "allow"].includes(unknownTokens)) throw new TypeError('limits.unknownTokens must be "stop", "ask" or "allow"');
70
- if (allow !== undefined && (!Array.isArray(allow) || allow.some((a) => !ADDRESS_RE.test(a)))) throw new TypeError("limits.allow must be a list of 0x addresses");
78
+ if (allow !== undefined && (!Array.isArray(allow) || allow.some((a) => !ADDRESS_RE.test(a)))) throw new TypeError("limits.allow must be a list of 0x (or XRPL r…) addresses");
71
79
  const budgets = new Map();
72
80
  const index = new Map(); // "chainId:token" or "*:token" -> { budget, decimals }
73
81
  const put = (k, v) => { if (index.has(k)) throw new TypeError(`limits.tokens: ${k} is covered twice`); index.set(k, v); };
@@ -80,6 +88,9 @@ export function normalizeLimits(limits) {
80
88
  const symbol = name.toUpperCase();
81
89
  if (symbol === "USDC") {
82
90
  for (const [chain, list] of Object.entries(USDC)) for (const [addr, decimals] of list) put(`${chain}:${addr}`, { budget: name, decimals });
91
+ for (const net of Object.keys(XRPL_RLUSD_ISSUERS)) put(`${net}:rlusd`, { budget: name, decimals: SCALE });
92
+ } else if (symbol === "XRP") {
93
+ for (const net of Object.keys(XRPL_RLUSD_ISSUERS)) put(`${net}:${NATIVE}`, { budget: name, decimals: 6 });
83
94
  } else if (["ETH", "BNB", "POL"].includes(symbol)) {
84
95
  for (const [chain, s] of Object.entries(NATIVE_SYMBOL)) if (s === symbol) put(`${chain}:${NATIVE}`, { budget: name, decimals: 18 });
85
96
  } else {
@@ -102,6 +113,7 @@ const scaled = (raw, decimals) => (decimals <= SCALE ? raw * 10n ** BigInt(SCALE
102
113
  // the addresses that receive value or rights, and whether anything could not be read.
103
114
  export function spendFor(request, verdict) {
104
115
  const out = { items: [], counterparties: [], unknown: false };
116
+ if (request.type === "xrpl") return xrplSpend(request, out);
105
117
  const chainId = request.chainId;
106
118
  if (request.type === "transaction") {
107
119
  const to = lower(request.to ?? null);
@@ -142,6 +154,27 @@ export function spendFor(request, verdict) {
142
154
  return out;
143
155
  }
144
156
 
157
+ // An XRP Ledger Payment: what can leave the account (SendMax if set, else Amount) and who receives it.
158
+ function xrplSpend(request, out) {
159
+ const net = request.network ?? "xrpl:0";
160
+ const tx = request.tx ?? {};
161
+ const to = typeof tx.Destination === "string" && XRPL_ADDRESS_RE.test(tx.Destination) ? lower(tx.Destination) : null;
162
+ out.counterparties.push(to);
163
+ if (tx.TransactionType !== "Payment") { out.unknown = true; return out; }
164
+ const amt = tx.SendMax ?? tx.Amount;
165
+ if (typeof amt === "string" && /^\d+$/.test(amt)) {
166
+ out.items.push({ chainId: net, token: NATIVE, amount: BigInt(amt), to });
167
+ } else if (amt && typeof amt === "object" && /^\d+(\.\d+)?$/.test(String(amt.value ?? ""))) {
168
+ const currency = String(amt.currency ?? "").toUpperCase();
169
+ const rlusd = (currency === "RLUSD" || currency === RLUSD_HEX) && amt.issuer === XRPL_RLUSD_ISSUERS[net];
170
+ const value = String(amt.value).replace(/^(\d+\.\d{18})\d+$/, "$1"); // RLUSD has at most 15 significant digits; keep 18 decimals
171
+ out.items.push({ chainId: net, token: rlusd ? "rlusd" : `${currency}.${amt.issuer}`, amount: parseUnits(value, SCALE), to });
172
+ } else {
173
+ out.unknown = true;
174
+ }
175
+ return out;
176
+ }
177
+
145
178
  const fmt = (x) => (x === null ? "unlimited" : formatUnits(x, SCALE));
146
179
  const short = (a) => (a ? `${a.slice(0, 6)}…${a.slice(-4)}` : "a new contract");
147
180
 
package/mandate.js CHANGED
@@ -48,7 +48,8 @@ function cleanEnvelope(envelope) {
48
48
  export function mandatePayer(scheme, mandate) {
49
49
  const envelope = cleanEnvelope(mandate);
50
50
  const digest = mandateDigest(envelope.mandate);
51
- return {
51
+ // Everything else (scheme name, findDefaultAsset, …) comes from the wrapped scheme.
52
+ return Object.assign(Object.create(scheme), {
52
53
  scheme: scheme.scheme ?? "exact",
53
54
  async createPaymentPayload(x402Version, requirements, context) {
54
55
  if ((requirements.extra?.assetTransferMethod ?? "eip3009") !== "eip3009") return scheme.createPaymentPayload(x402Version, requirements, context);
@@ -74,5 +75,5 @@ export function mandatePayer(scheme, mandate) {
74
75
  bound.delete(nonce);
75
76
  }
76
77
  },
77
- };
78
+ });
78
79
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "presign-guard-wallet",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
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.",
5
5
  "type": "module",
6
6
  "exports": {