presign-guard-wallet 0.10.1 → 0.11.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 +17 -0
- package/index.d.ts +10 -1
- package/index.js +76 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -233,6 +233,23 @@ client.register("xrpl:*", new ExactXrplScheme(xrpl)); // x402 payments in RLUSD,
|
|
|
233
233
|
|
|
234
234
|
`network` is `"xrpl:0"` (mainnet) or `"xrpl:1"` (testnet). The check itself is still paid on Base (or with credits).
|
|
235
235
|
|
|
236
|
+
## MPP sessions on Tempo
|
|
237
|
+
|
|
238
|
+
`tempoSessionAccount(account)` gives a guarded viem account to pay MPP **sessions** (TIP-1034) with mppx's session client: the agent opens a payment channel once and pays each call with a signed voucher, no transaction per call.
|
|
239
|
+
|
|
240
|
+
```js
|
|
241
|
+
import { sessionManager } from "mppx/client";
|
|
242
|
+
const session = sessionManager({
|
|
243
|
+
account: guarded.tempoSessionAccount(privateKeyToAccount(process.env.AGENT_KEY)), // { chainId: 42431 } for the testnet
|
|
244
|
+
credentialContext: { depositRaw: "1000000" }, // each deposit: 1 USDC.e
|
|
245
|
+
topUpAmount: "1",
|
|
246
|
+
});
|
|
247
|
+
const res = await session.fetch("https://presign-guard.fizzl.eu/v1/check", { method: "POST", body });
|
|
248
|
+
await session.close(); // the service settles what was used, the rest comes back
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
The account signs only a transaction with one call to Tempo's channel escrow that opens or tops up a channel in USDC.e for this account (nothing attached, the fee in USDC.e); that deposit counts toward your `USDC` limit, booked to the payee, when it is signed. Besides that it signs the channel's vouchers and close authorizations (EIP-712, the escrow's domain), which can only move money already deposited. Raw hashes, messages and anything else are refused, and `pause()` covers it. Unspent deposit comes back when the channel closes, but stays counted as spent in the current window.
|
|
252
|
+
|
|
236
253
|
## Signed verdicts
|
|
237
254
|
|
|
238
255
|
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.d.ts
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
|
-
import type { WalletClient } from "viem";
|
|
1
|
+
import type { LocalAccount, WalletClient } from "viem";
|
|
2
2
|
|
|
3
3
|
export declare const PRESIGN_URL: string;
|
|
4
4
|
export declare const PRESIGN_SIGNERS: string[];
|
|
5
5
|
export declare const SUPPORTED_CHAINS: number[];
|
|
6
6
|
/** Tempo chain id -> the stablecoins (lowercase) the wallet may transfer there, checked locally instead of by presign-guard. */
|
|
7
7
|
export declare const TEMPO_TOKENS: Record<number, string[]>;
|
|
8
|
+
/** Tempo's TIP-1034 channel escrow (MPP sessions). */
|
|
9
|
+
export declare const TEMPO_ESCROW: string;
|
|
10
|
+
/** What an MPP session transaction deposits ({ token, payee, deposit }), or throws PresignBlockedError when the wallet would not sign it. */
|
|
11
|
+
export declare function sessionDeposit(tx: any, chainId: number, address: string): { token: string; payee: string; deposit: bigint };
|
|
8
12
|
export declare const VERSION: string;
|
|
9
13
|
export declare const CREDIT_HEADER: string;
|
|
10
14
|
|
|
@@ -137,6 +141,11 @@ export interface GuardControls {
|
|
|
137
141
|
* wallet server's receipts, approval messages). Call report() with what happened afterwards.
|
|
138
142
|
*/
|
|
139
143
|
withPurchase<T>(info: Purchase, fn: (report: (outcome: PurchaseOutcome) => void) => Promise<T> | T, opts?: { onChecked?: (check: AnswerCheck, out: T) => Promise<T> | T }): Promise<T>;
|
|
144
|
+
/**
|
|
145
|
+
* A guarded viem account for MPP sessions on Tempo (mppx's session client): signs only a channel open/top-up in
|
|
146
|
+
* Tempo's escrow, in USDC.e, for this account (the deposit counts toward the USDC limits), plus its vouchers.
|
|
147
|
+
*/
|
|
148
|
+
tempoSessionAccount<A extends LocalAccount>(account: A, opts?: { chainId?: 4217 | 42431 }): A;
|
|
140
149
|
/** The same guard (checks, limits, pause, purchases) on another WalletClient, e.g. one for Tempo: both spend from one budget. */
|
|
141
150
|
wrap<W extends object>(wallet: W): W & GuardControls;
|
|
142
151
|
}
|
package/index.js
CHANGED
|
@@ -32,6 +32,11 @@
|
|
|
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
34
|
//
|
|
35
|
+
// MPP sessions on Tempo: tempoSessionAccount(account) gives a guarded viem account for mppx's
|
|
36
|
+
// session client. It signs one thing on chain, opening or topping up a payment channel in
|
|
37
|
+
// Tempo's escrow in USDC.e (the deposit counts toward the USDC limits), plus that channel's
|
|
38
|
+
// vouchers and close authorizations; raw hashes, messages and anything else are refused.
|
|
39
|
+
//
|
|
35
40
|
// XRP Ledger: xrplSigner(signer) wraps an XRPL signer ({ classicAddress, sign(tx) },
|
|
36
41
|
// e.g. createXrplWalletSigner from @x402/xrpl) the same way. It signs only
|
|
37
42
|
// Payment transactions, each checked by presign-guard first (type "xrpl": fake
|
|
@@ -39,7 +44,7 @@
|
|
|
39
44
|
// toward the limits (XRP toward an XRP limit, RLUSD toward USDC). Use it with
|
|
40
45
|
// @x402/xrpl's ExactXrplScheme to pay x402 services in RLUSD.
|
|
41
46
|
|
|
42
|
-
import { encodeFunctionData } from "viem";
|
|
47
|
+
import { decodeFunctionData, encodeFunctionData, parseAbi } from "viem";
|
|
43
48
|
import { verifyReceipt, AUTHORITY } from "x402-safe-fetch";
|
|
44
49
|
import { createLimiter, memoryStore } from "./limits.js";
|
|
45
50
|
import { createRemoteLimiter } from "./remote.js";
|
|
@@ -58,8 +63,16 @@ export const TEMPO_TOKENS = {
|
|
|
58
63
|
42431: ["0x20c0000000000000000000000000000000000000"],
|
|
59
64
|
};
|
|
60
65
|
const TEMPO_TRANSFERS = new Set(["transfer", "transferWithMemo"]);
|
|
66
|
+
// MPP sessions (TIP-1034): deposits into Tempo's channel escrow, and the vouchers that spend them.
|
|
67
|
+
export const TEMPO_ESCROW = "0x4d50500000000000000000000000000000000000";
|
|
68
|
+
const ESCROW_ABI = parseAbi([
|
|
69
|
+
"function open(address payee, address operator, address token, uint96 deposit, bytes32 salt, address authorizedSigner)",
|
|
70
|
+
"function topUp((address payer, address payee, address operator, address token, bytes32 salt, address authorizedSigner, bytes32 expiringNonceHash) descriptor, uint96 additionalDeposit)",
|
|
71
|
+
]);
|
|
72
|
+
const TRANSFER_ABI = parseAbi(["function transfer(address to, uint256 amount)"]);
|
|
73
|
+
const VOUCHER_DOMAIN = "TIP20 Channel Reserve";
|
|
61
74
|
export const XRPL_NETWORKS = ["xrpl:0", "xrpl:1"];
|
|
62
|
-
export const VERSION = "0.
|
|
75
|
+
export const VERSION = "0.11.0";
|
|
63
76
|
export const CREDIT_HEADER = "x-credit-key";
|
|
64
77
|
const ROUTE = "POST /v1/check";
|
|
65
78
|
|
|
@@ -97,6 +110,33 @@ export function checkRequestFor(method, args, { chainId, origin } = {}) {
|
|
|
97
110
|
return null;
|
|
98
111
|
}
|
|
99
112
|
|
|
113
|
+
// The one transaction an MPP session account signs: a single call to Tempo's escrow, open or topUp, in the
|
|
114
|
+
// chain's stablecoin, for this account, nothing attached. Returns what it deposits, or throws.
|
|
115
|
+
export function sessionDeposit(tx, chainId, address) {
|
|
116
|
+
const no = (why) => { throw new PresignBlockedError(`MPP session account: ${why}; nothing was signed`, { code: "unsupported_chain" }); };
|
|
117
|
+
const tokens = TEMPO_TOKENS[chainId];
|
|
118
|
+
if (Number(tx?.chainId ?? chainId) !== chainId) no(`the transaction is for chain ${tx?.chainId}, not ${chainId}`);
|
|
119
|
+
if (tx?.feeToken !== undefined && !tokens.includes(String(tx.feeToken).toLowerCase())) no("the fee is not paid in the session stablecoin");
|
|
120
|
+
const calls = Array.isArray(tx?.calls) ? tx.calls : tx?.to ? [{ to: tx.to, data: tx.data, value: tx.value }] : [];
|
|
121
|
+
if (calls.length !== 1) no(`only one escrow call is signed (got ${calls.length})`);
|
|
122
|
+
const [call] = calls;
|
|
123
|
+
if (String(call.to ?? "").toLowerCase() !== TEMPO_ESCROW) no("the call is not to Tempo's channel escrow");
|
|
124
|
+
if (BigInt(call.value ?? 0n) > 0n) no("value is attached");
|
|
125
|
+
let decoded;
|
|
126
|
+
try { decoded = decodeFunctionData({ abi: ESCROW_ABI, data: call.data }); } catch { no("only opening or topping up a channel is signed"); }
|
|
127
|
+
const me = String(address).toLowerCase();
|
|
128
|
+
if (decoded.functionName === "open") {
|
|
129
|
+
const [payee, , token, deposit, , signer] = decoded.args;
|
|
130
|
+
if (!tokens.includes(token.toLowerCase())) no("the channel is not in the session stablecoin");
|
|
131
|
+
if (signer.toLowerCase() !== me) no("the channel's voucher signer is not this account");
|
|
132
|
+
return { token: token.toLowerCase(), payee, deposit };
|
|
133
|
+
}
|
|
134
|
+
const [descriptor, deposit] = decoded.args;
|
|
135
|
+
if (!tokens.includes(descriptor.token.toLowerCase())) no("the channel is not in the session stablecoin");
|
|
136
|
+
if (descriptor.payer.toLowerCase() !== me) no("the channel is not this account's");
|
|
137
|
+
return { token: descriptor.token.toLowerCase(), payee: descriptor.payee, deposit };
|
|
138
|
+
}
|
|
139
|
+
|
|
100
140
|
const GUARDED = new Set(["sendTransaction", "writeContract", "signTypedData"]);
|
|
101
141
|
|
|
102
142
|
// What the agent says it is buying, for the signatures made inside withPurchase().
|
|
@@ -309,6 +349,40 @@ export function guardWallet(wallet, {
|
|
|
309
349
|
if (!XRPL_NETWORKS.includes(network)) throw new TypeError(`xrplSigner: network must be one of ${XRPL_NETWORKS.join(", ")}`);
|
|
310
350
|
return { classicAddress: signer.classicAddress, sign: (tx) => xrplSign(signer, network, tx) };
|
|
311
351
|
},
|
|
352
|
+
/**
|
|
353
|
+
* A guarded viem account for MPP sessions on Tempo (e.g. mppx's sessionManager): it signs only
|
|
354
|
+
* a transaction that opens or tops up a payment channel in Tempo's escrow, in USDC.e, for this
|
|
355
|
+
* account (the deposit counts toward the USDC limits, booked to the payee, when it is signed),
|
|
356
|
+
* and the channel's vouchers and close authorizations (EIP-712, escrow domain; they only move
|
|
357
|
+
* money already deposited). Raw hashes, messages and anything else are refused.
|
|
358
|
+
*/
|
|
359
|
+
tempoSessionAccount: (account, { chainId = 4217 } = {}) => {
|
|
360
|
+
if (!TEMPO_TOKENS[chainId]) throw new TypeError(`tempoSessionAccount: chainId must be ${Object.keys(TEMPO_TOKENS).join(" or ")}`);
|
|
361
|
+
if (!account || typeof account.signTransaction !== "function" || typeof account.signTypedData !== "function") throw new TypeError("tempoSessionAccount(account): account must be a local viem account (privateKeyToAccount)");
|
|
362
|
+
const refuse = (what) => async () => { throw new PresignBlockedError(`MPP session account: ${what} is not signed; nothing was signed`, { code: "unsupported_chain" }); };
|
|
363
|
+
return {
|
|
364
|
+
...account,
|
|
365
|
+
sign: refuse("a raw hash"),
|
|
366
|
+
signMessage: refuse("a message"),
|
|
367
|
+
signAuthorization: refuse("an EIP-7702 authorization"),
|
|
368
|
+
signTypedData: async (typedData) => {
|
|
369
|
+
if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
|
|
370
|
+
const d = typedData?.domain ?? {};
|
|
371
|
+
const ok = ["Voucher", "CloseAuthorization"].includes(typedData?.primaryType) && d.name === VOUCHER_DOMAIN
|
|
372
|
+
&& String(d.verifyingContract ?? "").toLowerCase() === TEMPO_ESCROW && Number(d.chainId) === chainId;
|
|
373
|
+
if (!ok) throw new PresignBlockedError(`MPP session account: only channel vouchers on Tempo's escrow are signed (got ${typedData?.primaryType ?? "nothing"}); nothing was signed`, { code: "unsupported_chain" });
|
|
374
|
+
return account.signTypedData(typedData);
|
|
375
|
+
},
|
|
376
|
+
signTransaction: async (tx, opts) => {
|
|
377
|
+
if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
|
|
378
|
+
const { token, payee, deposit } = sessionDeposit(tx, chainId, account.address);
|
|
379
|
+
const run = () => account.signTransaction(tx, opts);
|
|
380
|
+
if (!limiter) return run();
|
|
381
|
+
const request = checkRequestFor("writeContract", { address: token, abi: TRANSFER_ABI, functionName: "transfer", args: [payee, deposit] }, { chainId, origin });
|
|
382
|
+
return withinLimits("writeContract", request, null, run);
|
|
383
|
+
},
|
|
384
|
+
};
|
|
385
|
+
},
|
|
312
386
|
/** Stop every checked method until resume(). */
|
|
313
387
|
pause: () => { paused = true; },
|
|
314
388
|
resume: () => { paused = false; },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "presign-guard-wallet",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.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": {
|