presign-guard-wallet 0.22.0 → 0.23.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
@@ -298,7 +298,9 @@ Only single payments are checked; the cumulative spend against the cap needs the
298
298
 
299
299
  ## XRP Ledger (RLUSD and XRP)
300
300
 
301
- `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.
301
+ `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, unless you pass `{ any: true }`.
302
+
303
+ **Other XRPL transactions.** With `xrplSigner(signer, { any: true })` the signer also signs other transactions from its own account: a trust line for RLUSD, a DEX order, an escrow, a `Batch`. Each goes to presign-guard first. presign-guard judges every transaction inside a Batch on its own, so a new regular key, signer list or account delete hidden next to a payment is red and never signed; a `DelegateSet` that lets another account send payments for you is red too. What the transaction can take out counts toward your limits: a `Payment` (SendMax or Amount), a check (SendMax), an escrow or payment channel (Amount), a DEX order (TakerGets), an AMM deposit, an NFT buy offer, and in a Batch this account's own inner transactions together (the other accounts' parts are their money). Trust lines, cancellations and other types that move nothing out add nothing; anything else (an `AccountDelete`, a `DelegateSet`, a `SetRegularKey`) counts as unknown spending and goes to `onOverLimit`.
302
304
 
303
305
  ```js
304
306
  import { Wallet } from "xrpl";
package/index.d.ts CHANGED
@@ -152,6 +152,13 @@ export interface GuardControls {
152
152
  * Tempo's escrow, in USDC.e, for this account (the deposit counts toward the USDC limits), plus its vouchers.
153
153
  */
154
154
  tempoSessionAccount<A extends LocalAccount>(account: A, opts?: { chainId?: 4217 | 42431 }): A;
155
+ /**
156
+ * A guarded XRP Ledger signer for @x402/xrpl (ExactXrplScheme): signs only Payment transactions from this account,
157
+ * each checked by presign-guard (type xrpl) and counted toward the limits (RLUSD toward USDC, drops toward XRP);
158
+ * anything else is refused, unless `any`: then every transaction (trust lines, DEX orders, a Batch, whose inner
159
+ * transactions presign-guard judges one by one) is checked first and what it can take out counts toward the limits.
160
+ */
161
+ xrplSigner<S extends { classicAddress: string; sign(tx: Record<string, unknown>): unknown }>(signer: S, opts?: { network?: "xrpl:0" | "xrpl:1"; any?: boolean }): S;
155
162
  /**
156
163
  * A guarded Algorand signer for @x402/avm (ExactAvmScheme): signs only the agent's own USDC transfer in a
157
164
  * payment group (no close-out, rekey or clawback), counted toward the USDC limits; anything else is refused.
package/index.js CHANGED
@@ -54,7 +54,9 @@
54
54
  // Payment transactions, each checked by presign-guard first (type "xrpl": fake
55
55
  // RLUSD, partial payments, missing destination tags, issuer risks) and counted
56
56
  // toward the limits (XRP toward an XRP limit, RLUSD toward USDC). Use it with
57
- // @x402/xrpl's ExactXrplScheme to pay x402 services in RLUSD.
57
+ // @x402/xrpl's ExactXrplScheme to pay x402 services in RLUSD. With { any: true }
58
+ // it also signs other transactions (a trust line, a DEX order, a Batch), each
59
+ // checked by presign-guard first; what they can take out counts toward the limits.
58
60
 
59
61
  import { bytesToHex, decodeFunctionData, encodeFunctionData, parseAbi } from "viem";
60
62
  import { recoverAuthorizationAddress } from "viem/utils";
@@ -88,7 +90,7 @@ const ESCROW_ABI = parseAbi([
88
90
  const TRANSFER_ABI = parseAbi(["function transfer(address to, uint256 amount)"]);
89
91
  const VOUCHER_DOMAIN = "TIP20 Channel Reserve";
90
92
  export const XRPL_NETWORKS = ["xrpl:0", "xrpl:1"];
91
- export const VERSION = "0.22.0";
93
+ export const VERSION = "0.23.0";
92
94
  export const CREDIT_HEADER = "x-credit-key";
93
95
  const ROUTE = "POST /v1/check";
94
96
 
@@ -521,19 +523,21 @@ export function guardWallet(wallet, {
521
523
  return limiter ? withinLimits(method, request, verdict, run) : run();
522
524
  }
523
525
 
524
- // XRP Ledger: sign a Payment only after presign-guard's check and within the limits.
525
- async function xrplSign(signer, network, tx) {
526
+ // XRP Ledger: sign a Payment (with any, any transaction) only after presign-guard's check and within the limits.
527
+ // presign-guard judges every transaction inside a Batch, so a new key can't hide in one; red is never signed.
528
+ async function xrplSign(signer, network, tx, any) {
526
529
  if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
527
- if (!tx || typeof tx !== "object" || tx.TransactionType !== "Payment") {
528
- throw new PresignBlockedError(`on the XRP Ledger this wallet only signs Payment transactions (got ${tx?.TransactionType ?? "nothing"}); nothing was signed`, { code: "unsupported_chain" });
530
+ if (!tx || typeof tx !== "object" || typeof tx.TransactionType !== "string" || (tx.TransactionType !== "Payment" && !any)) {
531
+ throw new PresignBlockedError(`on the XRP Ledger this wallet only signs Payment transactions (got ${tx?.TransactionType ?? "nothing"}; xrplSigner with { any: true } signs others after presign-guard's check); nothing was signed`, { code: "unsupported_chain" });
529
532
  }
530
533
  if (tx.Account && signer.classicAddress && tx.Account !== signer.classicAddress) {
531
534
  throw new PresignBlockedError(`the transaction's Account ${tx.Account} is not this signer (${signer.classicAddress}); nothing was signed`, { code: "unsupported_chain" });
532
535
  }
533
536
  const request = { type: "xrpl", network, tx: JSON.parse(JSON.stringify(tx)), ...(origin ? { origin } : {}) };
534
- const verdict = await verdictFor("signXrplPayment", request, network);
537
+ const method = tx.TransactionType === "Payment" ? "signXrplPayment" : "signXrplTransaction";
538
+ const verdict = await verdictFor(method, request, network);
535
539
  const run = () => signer.sign(tx);
536
- return limiter ? withinLimits("signXrplPayment", request, verdict, run) : run();
540
+ return limiter ? withinLimits(method, request, verdict, run) : run();
537
541
  }
538
542
 
539
543
  // Algorand: sign only a USDC transfer from this address, within the limits (checked here, no presign-guard
@@ -624,12 +628,13 @@ export function guardWallet(wallet, {
624
628
  /**
625
629
  * The same guard on an XRP Ledger signer ({ classicAddress, sign(tx) }, e.g. createXrplWalletSigner
626
630
  * from @x402/xrpl): only Payment transactions, each checked by presign-guard and counted toward the
627
- * limits (RLUSD toward USDC, XRP toward an XRP limit). network: "xrpl:0" (default) or "xrpl:1".
631
+ * limits (RLUSD toward USDC, XRP toward an XRP limit). network: "xrpl:0" (default) or "xrpl:1". any: also
632
+ * sign other transactions (trust lines, DEX orders, a Batch), each checked by presign-guard first.
628
633
  */
629
- xrplSigner: (signer, { network = "xrpl:0" } = {}) => {
634
+ xrplSigner: (signer, { network = "xrpl:0", any = false } = {}) => {
630
635
  if (!signer || typeof signer.sign !== "function") throw new TypeError("xrplSigner(signer): signer needs a sign(tx) function (e.g. createXrplWalletSigner from @x402/xrpl)");
631
636
  if (!XRPL_NETWORKS.includes(network)) throw new TypeError(`xrplSigner: network must be one of ${XRPL_NETWORKS.join(", ")}`);
632
- return { classicAddress: signer.classicAddress, sign: (tx) => xrplSign(signer, network, tx) };
637
+ return { classicAddress: signer.classicAddress, sign: (tx) => xrplSign(signer, network, tx, any === true) };
633
638
  },
634
639
  /**
635
640
  * A guarded viem account for MPP sessions on Tempo (e.g. mppx's sessionManager): it signs only
package/limits.js CHANGED
@@ -171,25 +171,64 @@ export function spendFor(request, verdict) {
171
171
  return out;
172
172
  }
173
173
 
174
- // An XRP Ledger Payment: what can leave the account (SendMax if set, else Amount) and who receives it.
174
+ // XRP Ledger: what can leave the account and who receives it. A Payment: SendMax if set, else Amount. With any
175
+ // (xrplSigner { any: true }), also a check (SendMax), escrow or payment channel (Amount), DEX order (TakerGets), AMM
176
+ // deposit, NFT buy offer and bridge commit, and the account's own transactions inside a Batch (the others are their
177
+ // accounts' money). Types that move nothing out by themselves add nothing; anything else is unknown.
178
+ const XRPL_MOVES_NOTHING = new Set(["TrustSet", "AccountSet", "OfferCancel", "EscrowFinish", "EscrowCancel", "CheckCash", "CheckCancel", "TicketCreate", "NFTokenMint", "NFTokenBurn", "NFTokenCancelOffer", "NFTokenModify", "AMMWithdraw", "AMMVote", "AMMDelete", "AMMClawback", "Clawback", "CredentialCreate", "CredentialAccept", "CredentialDelete", "PermissionedDomainSet", "PermissionedDomainDelete", "DepositPreauth", "DIDSet", "DIDDelete", "OracleSet", "OracleDelete", "MPTokenAuthorize", "MPTokenIssuanceCreate", "MPTokenIssuanceSet", "MPTokenIssuanceDestroy"]);
179
+ const TF_SELL_NFTOKEN = 0x00000001;
180
+
175
181
  function xrplSpend(request, out) {
176
182
  const net = request.network ?? "xrpl:0";
177
183
  const tx = request.tx ?? {};
184
+ if (tx.TransactionType === "Batch") {
185
+ const inner = Array.isArray(tx.RawTransactions) ? tx.RawTransactions.map((r) => r?.RawTransaction ?? {}) : [];
186
+ if (!inner.length) out.unknown = true;
187
+ for (const t of inner) if (!t.Account || t.Account === tx.Account) xrplTxSpend(t, net, out);
188
+ } else xrplTxSpend(tx, net, out);
189
+ return out;
190
+ }
191
+
192
+ function xrplTxSpend(tx, net, out) {
178
193
  const to = typeof tx.Destination === "string" && XRPL_ADDRESS_RE.test(tx.Destination) ? lower(tx.Destination) : null;
179
- out.counterparties.push(to);
180
- if (tx.TransactionType !== "Payment") { out.unknown = true; return out; }
181
- const amt = tx.SendMax ?? tx.Amount;
182
- if (typeof amt === "string" && /^\d+$/.test(amt)) {
183
- out.items.push({ chainId: net, token: NATIVE, amount: BigInt(amt), to });
184
- } else if (amt && typeof amt === "object" && /^\d+(\.\d+)?$/.test(String(amt.value ?? ""))) {
185
- const currency = String(amt.currency ?? "").toUpperCase();
186
- const rlusd = (currency === "RLUSD" || currency === RLUSD_HEX) && amt.issuer === XRPL_RLUSD_ISSUERS[net];
187
- const value = String(amt.value).replace(/^(\d+\.\d{18})\d+$/, "$1"); // RLUSD has at most 15 significant digits; keep 18 decimals
188
- out.items.push({ chainId: net, token: rlusd ? "rlusd" : `${currency}.${amt.issuer}`, amount: parseUnits(value, SCALE), to });
189
- } else {
190
- out.unknown = true;
194
+ const take = (amt, receiver) => {
195
+ if (typeof amt === "string" && /^\d+$/.test(amt)) {
196
+ out.items.push({ chainId: net, token: NATIVE, amount: BigInt(amt), to: receiver });
197
+ } else if (amt && typeof amt === "object" && typeof amt.mpt_issuance_id === "string" && /^\d+$/.test(String(amt.value ?? ""))) {
198
+ out.items.push({ chainId: net, token: `mpt.${amt.mpt_issuance_id}`, amount: BigInt(amt.value), to: receiver });
199
+ } else if (amt && typeof amt === "object" && /^\d+(\.\d+)?$/.test(String(amt.value ?? ""))) {
200
+ const currency = String(amt.currency ?? "").toUpperCase();
201
+ const rlusd = (currency === "RLUSD" || currency === RLUSD_HEX) && amt.issuer === XRPL_RLUSD_ISSUERS[net];
202
+ const value = String(amt.value).replace(/^(\d+\.\d{18})\d+$/, "$1"); // RLUSD has at most 15 significant digits; keep 18 decimals
203
+ out.items.push({ chainId: net, token: rlusd ? "rlusd" : `${currency}.${amt.issuer}`, amount: parseUnits(value, SCALE), to: receiver });
204
+ } else {
205
+ out.unknown = true;
206
+ }
207
+ };
208
+ switch (tx.TransactionType) {
209
+ case "Payment": out.counterparties.push(to); take(tx.SendMax ?? tx.Amount, to); break;
210
+ case "CheckCreate": out.counterparties.push(to); take(tx.SendMax, to); break;
211
+ case "EscrowCreate":
212
+ case "PaymentChannelCreate": out.counterparties.push(to); take(tx.Amount, to); break;
213
+ case "PaymentChannelFund":
214
+ case "XChainCommit": out.counterparties.push(null); take(tx.Amount, null); break;
215
+ case "OfferCreate": out.counterparties.push(null); take(tx.TakerGets, null); break;
216
+ case "AMMCreate":
217
+ case "AMMDeposit":
218
+ out.counterparties.push(null);
219
+ if (tx.Amount === undefined && tx.Amount2 === undefined) out.unknown = true;
220
+ for (const a of [tx.Amount, tx.Amount2]) if (a !== undefined) take(a, null);
221
+ break;
222
+ case "NFTokenCreateOffer":
223
+ // A buy offer pays Amount to the owner; a sell offer gives the NFT, which no limit counts.
224
+ if (Number(tx.Flags) & TF_SELL_NFTOKEN) out.counterparties.push(to);
225
+ else { const owner = typeof tx.Owner === "string" ? lower(tx.Owner) : null; out.counterparties.push(owner); take(tx.Amount, owner); }
226
+ break;
227
+ default:
228
+ if (XRPL_MOVES_NOTHING.has(tx.TransactionType)) break;
229
+ out.counterparties.push(to);
230
+ out.unknown = true;
191
231
  }
192
- return out;
193
232
  }
194
233
 
195
234
  // An Algorand asset transfer (read from the unsigned transaction by algorandSigner): the asset, amount and receiver.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "presign-guard-wallet",
3
- "version": "0.22.0",
3
+ "version": "0.23.0",
4
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 (Telegram, or signed in your own wallet over AC2).",
5
5
  "type": "module",
6
6
  "exports": {