agentwallet-mcp 1.14.0 → 1.14.2

package/README.md

@@ -373,17 +373,18 @@ A per-transaction cap bounds one signature. It cannot see that the five hundredt
 }
 ```
 
-- **`budget`**: rolling dollar budgets (last 24 hours, last 30 days, lifetime) across every chain, counting x402 payments and stablecoin transfers in registry stablecoins. A spend the budget cannot price (a token outside the registry) is refused while a budget is set, unless `"unpriced_spends": "allow"`.
-- **`native_budget`**: the same per chain, in the chain's own coin.
+- **`budget`**: rolling dollar budgets (last 24 hours, last 30 days, lifetime) across every chain, counting x402 payments, stablecoin transfers and stablecoin approvals in registry stablecoins. A spend the budget cannot price (a token outside the registry) is refused while a budget is set, unless `"unpriced_spends": "allow"`.
+- **`native_budget`**: the same per chain, in the chain's own coin, counting native transfers and the native value sent into any contract (`wrap_eth`, `send_transaction` with value and calldata).
+- **Approvals are spends.** An ERC-20 allowance (`approve_token`, `approve_permit2`, `increaseAllowance`, `approveAndCall`, Permit2 `approve`, or the same calldata through `send_transaction`) is what the spender will take later, so it is priced, checked and reserved on the ledger when it is granted, the spender is checked against the recipient lists, and an unlimited approval (2^128 base units or more) is refused outright, since no budget can count it; grant an exact amount. A zero-value call to any other contract (a router, a bridge) reserves nothing: it can only pull what an approval already granted.
 - **`hosts`**, **`per_host`**: which endpoints `pay_x402` may pay, and how much per host per day, per month and per payment. A denied host is never contacted, not even for a quote.
-- **`recipients`**: where funds may go (transfers, x402 `payTo`). The allow list covers funds destinations; contract targets (approve, wrap, arbitrary calldata) are checked against the deny list and the chain list.
+- **`recipients`**: where funds may go (transfers, x402 `payTo`, approval spenders, contracts that receive native value). The allow list covers those funds destinations; the contract a zero-value call is aimed at (a token being approved, a router) is checked against the deny list and the chain list.
 - **`chains`**, **`assets`**: allow lists; an asset entry can be scoped `"8453:0x..."` or be the word `native`.
 - **`approval`**: above `above`, every x402 payment is put to the human at the MCP client through [elicitation](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation) (the client shows the amount, token, recipient and resource and asks yes or no; a client that declared no elicitation support cannot answer, so the payment is refused). In local mode an accepted answer may admit a payment above the per-payment cap, up to `max`. Budgets are never lifted by anyone's approval.
 - **`tools`**: the tools the model sees. A payer-only deployment exposes seven; the rest are not registered. `wallet_mode` and `spend_policy` are always present so the operator can see what the server is.
 
 An unknown key stops the server, so a misspelled `budgets` cannot run unbounded. `spend_policy` reports the file, its sha256 (compare it with the file you reviewed), what each budget has spent and has left, and which tools the policy hid. `quote_x402` answers "would this be paid?" for a URL before anything is signed.
 
-**The ledger.** Budgets are enforced from an append-only, hash-chained JSONL file (`AGENTWALLET_LEDGER`, or the policy's `ledger`, or `agentwallet-ledger.jsonl` beside the policy when a budget needs one). A spend is reserved on it before the signature exists; a reservation whose signing fails is voided by a later line; the endpoint's or chain's answer is settled onto it afterwards. On startup the chain is verified, and a ledger that does not verify refuses every spend until the operator has looked at it. `list_payments` reads it, `export_receipts` turns it into CSV or JSONL, and `AGENTWALLET_WEBHOOK_URL` receives every line as it is written.
+**The ledger.** Budgets are enforced from an append-only, hash-chained JSONL file (`AGENTWALLET_LEDGER`, or the policy's `ledger`, or `agentwallet-ledger.jsonl` beside the policy when a budget needs one). A spend is reserved on it before the signature exists; a reservation whose signing fails is voided by a later line; the endpoint's or chain's answer is settled onto it afterwards. The chain is verified on every read, and a ledger that does not verify refuses every spend until the operator has looked at it. Several agentwallet-mcp processes may share one ledger (two MCP clients on one wallet): the file is re-read before every check, and the check-and-append step holds an exclusive lock file (`<ledger>.lock`) across processes, so the budget is one budget however many processes enforce it; a lock older than 30 seconds is treated as left by a dead process. A transaction signed without being broadcast (`sign_transaction`) is reserved and counted like a send, since whoever holds it can broadcast it. `list_payments` reads it, `export_receipts` turns it into CSV or JSONL, and `AGENTWALLET_WEBHOOK_URL` receives every line as it is written.
 
 ### Encrypted keyfiles
 

package/build/index.js

@@ -115,7 +115,21 @@ function spendVerdict(input) {
 function usdOf(chainId, asset, raw, decimals) {
     return autopayAssetAllowed(chainId, asset).via === 'stablecoin' ? policyHuman(rawToUnits(raw, decimals)) : null;
 }
-/** Decode the spend a /send body describes: native value, an ERC-20 transfer, or an SPL transfer. */
+/* Calldata the policy prices: which word holds the amount, which the recipient
+   or spender, and for Permit2.approve which the token (there `to` is Permit2).
+   The same functions the local token cap prices, so the two guards agree. */
+const SPEND_LAYOUTS = {
+    a9059cbb: { kind: 'token', what: 'transfer', toIndex: 0, amountIndex: 1 }, // transfer(address,uint256)
+    '23b872dd': { kind: 'token', what: 'transferFrom', toIndex: 1, amountIndex: 2 }, // transferFrom(address,address,uint256)
+    '4000aea0': { kind: 'token', what: 'transferAndCall', toIndex: 0, amountIndex: 1 }, // transferAndCall(address,uint256,bytes)
+    '9bd9bbc6': { kind: 'token', what: 'ERC-777 send', toIndex: 0, amountIndex: 1 }, // send(address,uint256,bytes)
+    '62ad1b83': { kind: 'token', what: 'ERC-777 operatorSend', toIndex: 1, amountIndex: 2 }, // operatorSend(address,address,uint256,bytes,bytes)
+    '095ea7b3': { kind: 'approval', what: 'approve', toIndex: 0, amountIndex: 1 }, // approve(address,uint256)
+    '39509351': { kind: 'approval', what: 'increaseAllowance', toIndex: 0, amountIndex: 1 }, // increaseAllowance(address,uint256)
+    cae9ca51: { kind: 'approval', what: 'approveAndCall', toIndex: 0, amountIndex: 1 }, // approveAndCall(address,uint256,bytes)
+    '87517c45': { kind: 'approval', what: 'Permit2 approve', toIndex: 1, amountIndex: 2, tokenIndex: 0, permit2Only: true }, // Permit2.approve(address,address,uint160,uint48)
+};
+const UNBOUNDED_APPROVAL = 1n << 128n;
 async function describeSend(body, chainId) {
     if (body.token_mint) {
         const mint = String(body.token_mint);
@@ -124,14 +138,86 @@ async function describeSend(body, chainId) {
     }
     const data = String(body.data || '');
     const to = String(body.to || '');
-    if (!isSolanaChain(chainId) && /^0xa9059cbb[0-9a-fA-F]{128}$/.test(data)) {
-        const recipient = '0x' + data.slice(34, 74);
-        const raw = BigInt('0x' + data.slice(74, 138)).toString();
-        return { kind: 'token', to: recipient, asset: to, raw, decimals: await resolveTrustedDecimals(chainId, to) };
+    const value = String(body.value ?? '0');
+    if (!isSolanaChain(chainId) && /^0x[0-9a-fA-F]{8}/.test(data)) {
+        const layout = SPEND_LAYOUTS[data.slice(2, 10).toLowerCase()];
+        const isPermit2 = to.toLowerCase() === permit2Address(chainId).toLowerCase();
+        if (layout && (!layout.permit2Only || isPermit2)) {
+            // A short word is refused, never read as "not a transfer after all": the
+            // local guard treats truncated calldata the same way, for the same reason.
+            const wordAt = (i) => {
+                const w = data.slice(10 + i * 64, 10 + (i + 1) * 64);
+                if (w.length !== 64)
+                    throw new Error(`policy: calldata for ${layout.what} is truncated (word ${i} has ${w.length / 2} bytes, expected 32); refused rather than treated as a plain contract call. Nothing was signed.`);
+                return w;
+            };
+            const token = layout.tokenIndex === undefined ? to : '0x' + wordAt(layout.tokenIndex).slice(24);
+            const counterparty = '0x' + wordAt(layout.toIndex).slice(24);
+            const amount = BigInt('0x' + wordAt(layout.amountIndex));
+            if (layout.kind === 'approval' && amount >= UNBOUNDED_APPROVAL) {
+                return { kind: 'approval', to: counterparty, asset: token, raw: amount.toString(), decimals: 0, unbounded: true };
+            }
+            // Decimals matter here only to price a registry stablecoin (resolved
+            // offline) and to print the ledger amount. A token the registry and the
+            // node cannot place is unpriced whatever its decimals, so a failed lookup
+            // is evaluated at 0 (the fail-closed figure the local cap uses) and the
+            // call goes on to the local guard or the hosted signer, which refuse on
+            // their own terms (audit-11312: transferAndCall on a not-a-token target).
+            let decimals = 0;
+            try {
+                decimals = await resolveTrustedDecimals(chainId, token);
+            }
+            catch {
+                decimals = 0;
+            }
+            return { kind: layout.kind, to: counterparty, asset: token, raw: amount.toString(), decimals };
+        }
     }
     if (data && data !== '0x')
-        return { kind: 'contract', to, asset: '', raw: String(body.value ?? '0'), decimals: nativeDecimals(chainId) };
-    return { kind: 'native', to, asset: '', raw: String(body.value ?? '0'), decimals: nativeDecimals(chainId) };
+        return { kind: 'contract', to, asset: '', raw: value, decimals: nativeDecimals(chainId) };
+    return { kind: 'native', to, asset: '', raw: value, decimals: nativeDecimals(chainId) };
+}
+/** The ledger method a decoded send is recorded under, unless the caller named one. */
+function methodOf(kind) {
+    return kind === 'spl' ? 'spl' : kind === 'token' ? 'transfer' : kind === 'approval' ? 'approval' : 'native';
+}
+/**
+ * The list checks every send gets before anything is reserved: the chain, and
+ * for a contract call or an approval the contract itself against the deny
+ * list (an approval's contract is the token; its spender is checked as a
+ * recipient when the spend is reserved). Throws the refusal.
+ */
+function assertSendTarget(d, chainId) {
+    const c = chainAllowed(POL(), chainId);
+    if (!c.ok)
+        throw new Error(c.reason + ' Nothing was signed.');
+    if (d.kind === 'contract' || d.kind === 'approval') {
+        const t = targetAllowed(POL(), d.kind === 'approval' ? d.asset : d.to);
+        if (!t.ok)
+            throw new Error(t.reason + ' Nothing was signed.');
+    }
+}
+/**
+ * The spend a decoded send makes against the policy, or null when nothing
+ * leaves the wallet: a zero-value contract call can only pull what an
+ * approval already granted, and approvals are counted when they are granted.
+ * An approval's recipient is its spender, so recipients.allow and .deny bind
+ * who may be allowed to pull; the native value of a contract call is a spend
+ * to that contract. Throws for an unbounded approval under a policy.
+ */
+function spendInputOf(d, chainId, tool, wallet, ctx = {}) {
+    if (d.kind === 'contract' && BigInt(d.raw) === 0n)
+        return null;
+    if (d.kind === 'approval' && d.unbounded && POLICY.path) {
+        throw new Error(`policy: an unlimited approval of ${assetLabel(chainId, d.asset)} to ${d.to} cannot be counted against any budget, and under a spend policy every approval is a bounded spend. ` +
+            `Approve an exact amount instead. Nothing was signed.`);
+    }
+    return {
+        tool, mode: anyLocalMode() ? 'local' : 'hosted', wallet: anyLocalMode() ? 'local' : wallet, chainId,
+        asset: d.asset, assetLabel: assetLabel(chainId, d.asset), raw: d.raw, decimals: d.decimals,
+        usd: d.unbounded ? null : usdOf(chainId, d.asset, d.raw, d.decimals),
+        to: d.to, host: ctx.host ?? null, resource: ctx.resource ?? null, method: ctx.method ?? methodOf(d.kind),
+    };
 }
 // ─── Configuration ──────────────────────────────────────────────
 const API_BASE = (process.env.AGENTWALLET_API_URL || 'https://hifriendbot.com/wp-json/agentwallet/v1').trim().replace(/\/+$/, '');
@@ -341,9 +427,11 @@ async function api(path, method = 'GET', body, extraHeaders) {
     /* Spend policy at the one choke point every broadcast funds path passes
        through (transfer, transfer_token, send_transaction, wrap, approve, the
        x402 broadcast paths, hosted auto-pay): the body is decoded into what it
-       moves, checked against the policy, reserved in the ledger before anything
-       is signed, and settled or voided afterwards. X-AGW-CTX carries the calling
-       tool's context for the ledger and never leaves this process. */
+       moves or allows, checked against the policy, reserved in the ledger before
+       anything is signed, and settled or voided afterwards. Approvals and the
+       native value of a contract call are spends too (1.14.1); only a zero-value
+       contract call reserves nothing. X-AGW-CTX carries the calling tool's
+       context for the ledger and never leaves this process. */
     let ctx = {};
     if (extraHeaders && extraHeaders['X-AGW-CTX'] !== undefined) {
         try {
@@ -356,31 +444,27 @@ async function api(path, method = 'GET', body, extraHeaders) {
         delete extraHeaders['X-AGW-CTX'];
     }
     let reserved = null;
-    const m = /^\/wallets\/([^/]+)\/send(\?|$)/.exec(path);
-    if (method === 'POST' && m && body) {
+    // /sign with a transaction body is the same spend as /send: the caller gets
+    // a broadcast-ready raw transaction (2026-10-14 report, 1.14.2). A message
+    // signature (body.message) moves nothing and is not gated.
+    const m = /^\/wallets\/([^/]+)\/(send|sign)(\?|$)/.exec(path);
+    const signsTx = m !== null && (m[2] === 'send' || typeof body?.message !== 'string');
+    if (method === 'POST' && m && body && signsTx) {
         const chainId = localChainId(body, new URLSearchParams(path.split('?')[1] || ''));
         const d = await describeSend(body, chainId);
-        if (d.kind === 'contract') {
-            const c = chainAllowed(POL(), chainId);
-            if (!c.ok)
-                throw new Error(c.reason + ' Nothing was signed.');
-            const t = targetAllowed(POL(), d.to);
-            if (!t.ok)
-                throw new Error(t.reason + ' Nothing was signed.');
-        }
-        else {
-            reserved = reserveSpend({
-                tool: ctx.tool || 'send', mode: anyLocalMode() ? 'local' : 'hosted', wallet: anyLocalMode() ? 'local' : m[1], chainId,
-                asset: d.asset, assetLabel: assetLabel(chainId, d.asset), raw: d.raw, decimals: d.decimals, usd: usdOf(chainId, d.asset, d.raw, d.decimals),
-                to: d.to, host: ctx.host ?? null, resource: ctx.resource ?? null, method: ctx.method ?? (d.kind === 'spl' ? 'spl' : d.kind === 'token' ? 'transfer' : 'native'),
-            });
-        }
+        assertSendTarget(d, chainId);
+        const input = spendInputOf(d, chainId, ctx.tool || (m[2] === 'sign' ? 'sign_transaction' : 'send'), m[1], ctx);
+        if (input)
+            reserved = reserveSpend(input);
     }
     try {
         const out = await apiInner(path, method, body, extraHeaders);
         if (reserved !== null) {
             const r = out;
-            LEDGER.settle(reserved, 'broadcast', typeof r?.tx_hash === 'string' ? r.tx_hash : typeof r?.signature === 'string' ? r.signature : null);
+            if (m[2] === 'sign')
+                LEDGER.settle(reserved, 'signed', 'raw transaction returned to the caller; not broadcast by this process, so it stays counted');
+            else
+                LEDGER.settle(reserved, 'broadcast', typeof r?.tx_hash === 'string' ? r.tx_hash : typeof r?.signature === 'string' ? r.signature : null);
         }
         return out;
     }
@@ -1034,7 +1118,7 @@ function resolveChainId(network) {
 const AddressSchema = z.string().regex(/^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/, 'Must be a 0x-prefixed 40-hex EVM address or a base58 Solana address');
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.14.0',
+    version: '1.14.2',
 }, {
     instructions: `AgentWallet gives AI agents their own blockchain wallets. ${anyLocalMode()
         ? 'This server runs in LOCAL (self-custody) mode: the operator supplied the key, signing happens in this process, and the only spend guards are the environment caps (AGENTWALLET_MAX_TX_NATIVE / _TOKEN / _SOL per transaction, AGENTWALLET_MAX_AUTOPAY and AGENTWALLET_AUTOPAY_ASSETS for x402, AGENTWALLET_X402_MAX_TIMEOUT for authorization windows). There is no server-side pause, daily limit or approval email; pause_wallet, unpause_wallet and delete_wallet are refused.'
@@ -1148,7 +1232,8 @@ tool('get_balance', 'Get the native token balance for a wallet on a specific cha
 // ─── Tool: sign_transaction ──────────────────────────────────────
 tool('sign_transaction', 'Sign a transaction with a wallet\'s private key. ' +
     'For EVM: returns signed raw transaction hex. For Solana: returns base64 signed transaction. ' +
-    'Does NOT broadcast — use send_transaction for sign + broadcast.', {
+    'Does NOT broadcast. Use send_transaction for sign + broadcast. ' +
+    'A signed transaction is a spend: under a spend policy it is checked, reserved on the ledger and counted against the budgets exactly as send_transaction is, because the caller can broadcast it.', {
     wallet_id: z.number().int().describe('Wallet ID'),
     to: AddressSchema.describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
     chain_id: z.number().int().optional().describe('Chain ID (defaults to wallet\'s default)'),
@@ -1378,7 +1463,8 @@ tool('call_contract', 'Execute a read-only call against a smart contract (eth_ca
 // ─── Tool: approve_token ────────────────────────────────────────
 tool('approve_token', 'Approve a spender contract to transfer ERC-20 tokens on your behalf. ' +
     'Required before interacting with any DeFi protocol (DEXs, lending, etc.). ' +
-    'Use amount "max" for unlimited approval, or specify an exact amount.', {
+    'Use amount "max" for unlimited approval, or specify an exact amount. ' +
+    'Under a spend policy an approval is a spend: it counts against the budgets, the spender is checked as a recipient, and "max" is refused.', {
     wallet_id: z.number().int().describe('Wallet ID'),
     token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
     spender: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Contract address to approve as spender'),
@@ -2283,7 +2369,7 @@ tool('check_approval', 'Status of a payment approval created when pay_x402 excee
 // ─── Tool: approve_permit2 ──────────────────────────────────────
 tool('approve_permit2', 'One-time ERC-20 approval of a token to the Permit2 contract, needed before paying x402 "upto" endpoints with that token. ' +
     'A normal on-chain transaction (needs gas). By default approves the maximum, the ecosystem norm, so it never has to be repeated; ' +
-    'pass amount to grant a bounded allowance instead (required under AGENTWALLET_MAX_TX_TOKEN, which refuses a max approval). ' +
+    'pass amount to grant a bounded allowance instead (required under AGENTWALLET_MAX_TX_TOKEN and under a spend policy, both of which refuse a max approval; under a policy the allowance counts against the budgets). ' +
     'Permit2 itself only moves what each signed authorization allows.', {
     wallet_id: z.number().int().describe('Wallet ID'),
     token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token address (e.g. USDC on Base)'),
@@ -2700,12 +2786,22 @@ tool('simulate_transaction', 'Dry-run an EVM transaction with nothing signed: th
         throw new Error('simulate_transaction is EVM-only.');
     const valueRaw = parseUnits(value, 18);
     const d = await describeSend({ to, value: valueRaw, data: data || '', chain_id }, chain_id);
-    const policy = d.kind === 'contract'
-        ? (() => { for (const r of [chainAllowed(POL(), chain_id), targetAllowed(POL(), d.to)])
-            if (!r.ok)
-                return r; return { ok: true }; })()
-        : spendVerdict({ tool: 'simulate_transaction', mode: anyLocalMode() ? 'local' : 'hosted', wallet: anyLocalMode() ? 'local' : String(wallet_id), chainId: chain_id, asset: d.asset, assetLabel: assetLabel(chain_id, d.asset), raw: d.raw, decimals: d.decimals, usd: usdOf(chain_id, d.asset, d.raw, d.decimals), to: d.to, host: null, resource: null, method: d.kind === 'token' ? 'transfer' : 'native' });
-    const moves = { kind: d.kind, to: d.to, asset: d.asset || 'native', asset_label: assetLabel(chain_id, d.asset), amount: formatUnits(d.raw, d.decimals) };
+    // The same gate the send path runs, with nothing recorded.
+    const policy = (() => {
+        try {
+            assertSendTarget(d, chain_id);
+            const input = spendInputOf(d, chain_id, 'simulate_transaction', String(wallet_id));
+            return input ? spendVerdict(input) : { ok: true };
+        }
+        catch (e) {
+            return { ok: false, reason: e.message };
+        }
+    })();
+    const moves = {
+        kind: d.kind, to: d.to, asset: d.asset || 'native', asset_label: assetLabel(chain_id, d.asset),
+        amount: d.unbounded ? 'unlimited' : formatUnits(d.raw, d.decimals),
+        ...(d.kind === 'approval' ? { note: 'an approval: `to` is the spender being allowed to pull `amount` of `asset`' } : {}),
+    };
     if (isLocalMode()) {
         const sim = await localSimulate(chain_id, to, BigInt(valueRaw), data && data !== '0x' ? data : undefined);
         return jsonResponse({ ...sim, ok: Boolean(sim.ok) && policy.ok, moves, policy: policy.ok ? 'ok' : policy.reason, mode: 'local' });

package/build/ledger.d.ts

@@ -1,5 +1,6 @@
 import { type Spent } from './policy.js';
-export type SpendMethod = 'eip3009' | 'permit2' | 'transfer' | 'native' | 'spl' | 'autopay';
+/** 'approval' is an ERC-20 allowance granted (approve, increaseAllowance, Permit2.approve): a spend the spender executes later, counted when granted. */
+export type SpendMethod = 'eip3009' | 'permit2' | 'transfer' | 'native' | 'spl' | 'autopay' | 'approval';
 export interface SpendEntry {
     seq: number;
     ts: string;
@@ -75,42 +76,59 @@ export interface Limits {
     } | null;
     unpriced: 'refuse' | 'allow';
 }
+export interface LedgerOptions {
+    /** Tests shorten the wait for a held lock. */
+    lockWaitMs?: number;
+}
 export declare class Ledger {
     readonly path: string | null;
     private entries;
     private last;
     private seq;
-    /** null = intact; otherwise what broke. */
+    /** null = intact; otherwise what broke. Refreshed from the file on every read. */
     integrity: string | null;
     private webhook;
+    private lockWaitMs;
     constructor(path: string | null, webhook?: {
         url: string;
         secret: string;
-    } | null);
-    private load;
+    } | null, opts?: LedgerOptions);
+    /**
+     * Re-read the file so the sums include what every other process wrote.
+     * The file must still begin with what this process has seen, line for
+     * line; otherwise it was rewritten underneath us and nothing is adopted.
+     */
+    private sync;
+    /** Take the exclusive lock file; returns the release. A lock a dead process left behind is cleared after LOCK_STALE_MS. */
+    private lock;
     private append;
     private notify;
     /** Spends not voided, newest last. */
     private liveSpends;
-    /** Dollar sums over rolling windows; nowMs for tests. */
+    /** Dollar sums over rolling windows from a fresh read of the file; nowMs for tests. */
     spentUsd(nowMs?: number, host?: string): Spent;
     spentNative(chainId: number, nowMs?: number): Spent;
+    private sumUsd;
+    private sumNative;
     private sum;
-    /** Would this spend fit every limit? The reason names the first it does not. */
+    /** Would this spend fit every limit, given what every process has written so far? The reason names the first limit it does not. */
     check(input: ReserveInput, limits: Limits, nowMs?: number): {
         ok: true;
     } | {
         ok: false;
         reason: string;
     };
-    /** Check and record in one synchronous step. Returns the spend's seq. */
+    private evaluate;
+    /** Re-read, check and record in one step under the lock. Returns the spend's seq. */
     reserve(input: ReserveInput, limits: Limits): number;
+    /** A follow-up line, written under the lock after a fresh read so it chains onto whatever any process wrote last. */
+    private follow;
     /** The spend never happened (signing or broadcast failed before anything left this process). */
     void(ref: number, detail: string): void;
     /** What the endpoint or chain said afterwards. Never throws: the payment already happened. */
     settle(ref: number, outcome: string, detail: string | null): void;
     size(): number;
-    /** Spends newest first with their latest follow-up folded in. */
+    /** Spends newest first with their latest follow-up folded in, from a fresh read. */
     payments(opts: {
         limit: number;
         host?: string;

package/build/ledger.js

@@ -3,69 +3,146 @@
  * process reserved, and what became of it.
  *
  * Budgets are enforced from it, so a reservation is written BEFORE the
- * signature exists: check and append happen in one synchronous step, which in
- * a single-threaded process means two concurrent calls cannot both fit the
- * last dollar. A reservation whose signing fails is voided by a later line;
- * the spend line itself is never edited, so the chain stays verifiable.
+ * signature exists. Check and append happen in one step under an exclusive
+ * lock file, after the file has been re-read and the chain re-verified, so
+ * two concurrent calls cannot both fit the last dollar, whether they come
+ * from one process or from several agentwallet-mcp processes sharing the
+ * file (two MCP clients configured with the same wallet and ledger). A
+ * reservation whose signing fails is voided by a later line; the spend line
+ * itself is never edited, so the chain stays verifiable.
  *
  * Each line carries the sha256 of the previous line's hash plus its own body.
- * On load the chain is verified; a broken chain with a budget configured
- * refuses every spend until the operator looks at the file.
+ * The chain is verified on every read; a broken chain with a budget
+ * configured refuses every spend until the operator looks at the file, and a
+ * file that no longer holds what this process wrote is refused the same way.
  */
-import { appendFileSync, existsSync, readFileSync, openSync, closeSync } from 'node:fs';
+import { appendFileSync, existsSync, readFileSync, openSync, closeSync, writeSync, unlinkSync, statSync } from 'node:fs';
 import { createHash, createHmac } from 'node:crypto';
 import { DAY_MS, MONTH_MS, units, rawToUnits, human } from './policy.js';
 const GENESIS = '0'.repeat(64);
 const MAX_LINE = 16 * 1024;
+/** How long a spend waits for another process to finish its own check-and-append. */
+const LOCK_WAIT_MS = 10_000;
+/** A lock older than this was left by a process that died holding it. */
+const LOCK_STALE_MS = 30_000;
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) { Atomics.wait(sleeper, 0, 0, ms); }
 function hashOf(prev, body) {
     return createHash('sha256').update(prev + '\n' + JSON.stringify(body)).digest('hex');
 }
+/** Parse and verify a ledger file's text. A trailing line without its newline is still being written by another process and is not read. */
+function parseChain(text) {
+    const complete = text.endsWith('\n') || !text.includes('\n') && text.trim() === '' ? text : text.slice(0, text.lastIndexOf('\n') + 1);
+    const lines = complete.split('\n').filter(l => l.trim());
+    const out = { entries: [], last: GENESIS, seq: 0, integrity: null };
+    let prev = GENESIS;
+    for (let i = 0; i < lines.length; i++) {
+        let e;
+        try {
+            e = JSON.parse(lines[i]);
+        }
+        catch {
+            out.integrity = `line ${i + 1} is not JSON`;
+            break;
+        }
+        const { hash, ...body } = e;
+        if (e.prev !== prev || hashOf(prev, body) !== hash) {
+            out.integrity = `chain broken at line ${i + 1} (seq ${e.seq})`;
+            break;
+        }
+        if (e.seq !== out.seq + 1) {
+            out.integrity = `sequence gap at line ${i + 1}`;
+            break;
+        }
+        out.entries.push(e);
+        out.seq = e.seq;
+        prev = hash;
+    }
+    out.last = prev;
+    return out;
+}
 export class Ledger {
     path;
     entries = [];
     last = GENESIS;
     seq = 0;
-    /** null = intact; otherwise what broke. */
+    /** null = intact; otherwise what broke. Refreshed from the file on every read. */
     integrity = null;
     webhook = null;
-    constructor(path, webhook) {
+    lockWaitMs = LOCK_WAIT_MS;
+    constructor(path, webhook, opts) {
         this.path = path;
         this.webhook = webhook ?? null;
-        if (path)
-            this.load();
+        if (opts?.lockWaitMs !== undefined)
+            this.lockWaitMs = opts.lockWaitMs;
+        if (path) {
+            // Create it now so a permissions problem shows at startup, not at the first spend.
+            if (!existsSync(path))
+                closeSync(openSync(path, 'a', 0o600));
+            this.sync();
+        }
     }
-    load() {
+    /**
+     * Re-read the file so the sums include what every other process wrote.
+     * The file must still begin with what this process has seen, line for
+     * line; otherwise it was rewritten underneath us and nothing is adopted.
+     */
+    sync() {
+        if (!this.path)
+            return;
         if (!existsSync(this.path)) {
-            // Create it now so a permissions problem shows at startup, not at the first spend.
-            closeSync(openSync(this.path, 'a', 0o600));
+            this.integrity = `the file was removed while this process was running (it held seq ${this.seq})`;
             return;
         }
-        const text = readFileSync(this.path, 'utf8');
-        const lines = text.split('\n').filter(l => l.trim());
-        let prev = GENESIS;
-        for (let i = 0; i < lines.length; i++) {
-            let e;
+        const c = parseChain(readFileSync(this.path, 'utf8'));
+        const n = this.entries.length;
+        if (c.entries.length < n || (n > 0 && c.entries[n - 1].hash !== this.last)) {
+            this.integrity = c.integrity && c.entries.length < n ? c.integrity : `the file was rewritten underneath this process (it held seq ${this.seq} ending ${this.last.slice(0, 12)}, the file now ends at seq ${c.seq})`;
+            return;
+        }
+        this.entries = c.entries;
+        this.seq = c.seq;
+        this.last = c.last;
+        this.integrity = c.integrity;
+    }
+    /** Take the exclusive lock file; returns the release. A lock a dead process left behind is cleared after LOCK_STALE_MS. */
+    lock() {
+        if (!this.path)
+            return () => { };
+        const lockPath = this.path + '.lock';
+        const deadline = Date.now() + this.lockWaitMs;
+        for (;;) {
             try {
-                e = JSON.parse(lines[i]);
+                const fd = openSync(lockPath, 'wx', 0o600);
+                try {
+                    writeSync(fd, `${process.pid} ${new Date().toISOString()}\n`);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                return () => { try {
+                    unlinkSync(lockPath);
+                }
+                catch { /* already gone */ } };
             }
-            catch {
-                this.integrity = `line ${i + 1} is not JSON`;
-                break;
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
             }
-            const { hash, ...body } = e;
-            if (e.prev !== prev || hashOf(prev, body) !== hash) {
-                this.integrity = `chain broken at line ${i + 1} (seq ${e.seq})`;
-                break;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                    unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch {
+                continue; /* released between the two calls */
             }
-            if (e.seq !== this.seq + 1) {
-                this.integrity = `sequence gap at line ${i + 1}`;
-                break;
+            if (Date.now() >= deadline) {
+                throw new Error(`The ledger at ${this.path} is locked by another agentwallet-mcp process (${lockPath}) that did not finish within ${this.lockWaitMs} ms. Nothing was signed. If no other process is running, remove the lock file.`);
             }
-            this.entries.push(e);
-            this.seq = e.seq;
-            prev = hash;
+            sleepSync(5);
         }
-        this.last = prev;
     }
     append(body) {
         if (this.integrity)
@@ -103,11 +180,19 @@ export class Ledger {
         const voided = new Set(this.entries.filter(e => e.kind === 'void').map(e => e.ref));
         return this.entries.filter((e) => e.kind === 'spend' && !voided.has(e.seq));
     }
-    /** Dollar sums over rolling windows; nowMs for tests. */
+    /** Dollar sums over rolling windows from a fresh read of the file; nowMs for tests. */
     spentUsd(nowMs = Date.now(), host) {
-        return this.sum(nowMs, e => (host === undefined || e.host === host) && e.usd !== null ? units(e.usd) : 0n);
+        this.sync();
+        return this.sumUsd(nowMs, host);
     }
     spentNative(chainId, nowMs = Date.now()) {
+        this.sync();
+        return this.sumNative(chainId, nowMs);
+    }
+    sumUsd(nowMs, host) {
+        return this.sum(nowMs, e => (host === undefined || e.host === host) && e.usd !== null ? units(e.usd) : 0n);
+    }
+    sumNative(chainId, nowMs) {
         return this.sum(nowMs, e => e.chain_id === chainId && e.asset === '' ? rawToUnits(e.raw, nativeDecimalsOf(chainId)) : 0n);
     }
     sum(nowMs, f) {
@@ -125,13 +210,17 @@ export class Ledger {
         }
         return out;
     }
-    /** Would this spend fit every limit? The reason names the first it does not. */
+    /** Would this spend fit every limit, given what every process has written so far? The reason names the first limit it does not. */
     check(input, limits, nowMs = Date.now()) {
+        this.sync();
+        return this.evaluate(input, limits, nowMs);
+    }
+    evaluate(input, limits, nowMs) {
         if (this.integrity)
             return { ok: false, reason: `The ledger at ${this.path} is not intact (${this.integrity}); every spend is refused until the operator has looked at it.` };
         const amount18 = rawToUnits(input.raw, input.decimals);
         if (input.asset === '') {
-            const r = refusal(limits.native, this.spentNative(input.chainId, nowMs), amount18, `native_budget.${input.chainId}`);
+            const r = refusal(limits.native, this.sumNative(input.chainId, nowMs), amount18, `native_budget.${input.chainId}`);
             if (r)
                 return { ok: false, reason: r };
         }
@@ -142,33 +231,51 @@ export class Ledger {
         }
         if (input.usd !== null) {
             const usd18 = units(input.usd);
-            const r = refusal(limits.usd, this.spentUsd(nowMs), usd18, 'budget');
+            const r = refusal(limits.usd, this.sumUsd(nowMs), usd18, 'budget');
             if (r)
                 return { ok: false, reason: r };
             if (limits.host && input.host) {
-                const h = refusal({ daily: limits.host.daily, monthly: limits.host.monthly }, this.spentUsd(nowMs, input.host), usd18, `per_host["${limits.host.pattern}"]`);
+                const h = refusal({ daily: limits.host.daily, monthly: limits.host.monthly }, this.sumUsd(nowMs, input.host), usd18, `per_host["${limits.host.pattern}"]`);
                 if (h)
                     return { ok: false, reason: h };
             }
         }
         return { ok: true };
     }
-    /** Check and record in one synchronous step. Returns the spend's seq. */
+    /** Re-read, check and record in one step under the lock. Returns the spend's seq. */
     reserve(input, limits) {
-        const c = this.check(input, limits);
-        if (!c.ok)
-            throw new Error(c.reason);
-        const amount = human(rawToUnits(input.raw, input.decimals));
-        const e = this.append({
-            kind: 'spend', tool: input.tool, mode: input.mode, wallet: input.wallet, chain_id: input.chainId, asset: input.asset, asset_label: input.assetLabel,
-            amount, raw: input.raw, usd: input.usd, to: input.to, host: input.host, resource: input.resource, method: input.method, proof: input.proof ?? null,
-        });
-        return e.seq;
+        const unlock = this.lock();
+        try {
+            this.sync();
+            const c = this.evaluate(input, limits, Date.now());
+            if (!c.ok)
+                throw new Error(c.reason);
+            const amount = human(rawToUnits(input.raw, input.decimals));
+            const e = this.append({
+                kind: 'spend', tool: input.tool, mode: input.mode, wallet: input.wallet, chain_id: input.chainId, asset: input.asset, asset_label: input.assetLabel,
+                amount, raw: input.raw, usd: input.usd, to: input.to, host: input.host, resource: input.resource, method: input.method, proof: input.proof ?? null,
+            });
+            return e.seq;
+        }
+        finally {
+            unlock();
+        }
+    }
+    /** A follow-up line, written under the lock after a fresh read so it chains onto whatever any process wrote last. */
+    follow(body) {
+        const unlock = this.lock();
+        try {
+            this.sync();
+            this.append(body);
+        }
+        finally {
+            unlock();
+        }
     }
     /** The spend never happened (signing or broadcast failed before anything left this process). */
     void(ref, detail) {
         try {
-            this.append({ kind: 'void', ref, outcome: 'void', detail: detail.slice(0, 300) });
+            this.follow({ kind: 'void', ref, outcome: 'void', detail: detail.slice(0, 300) });
         }
         catch (e) {
             console.error(`[agentwallet] ledger void failed: ${e.message}`);
@@ -177,15 +284,16 @@ export class Ledger {
     /** What the endpoint or chain said afterwards. Never throws: the payment already happened. */
     settle(ref, outcome, detail) {
         try {
-            this.append({ kind: 'settle', ref, outcome: outcome.slice(0, 40), detail: detail ? detail.slice(0, 300) : null });
+            this.follow({ kind: 'settle', ref, outcome: outcome.slice(0, 40), detail: detail ? detail.slice(0, 300) : null });
         }
         catch (e) {
             console.error(`[agentwallet] ledger settle failed: ${e.message}`);
         }
     }
-    size() { return this.entries.length; }
-    /** Spends newest first with their latest follow-up folded in. */
+    size() { this.sync(); return this.entries.length; }
+    /** Spends newest first with their latest follow-up folded in, from a fresh read. */
     payments(opts) {
+        this.sync();
         const follow = new Map();
         for (const e of this.entries)
             if (e.kind !== 'spend')

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "git+https://github.com/hifriendbot/agentwallet-mcp.git"
   },
-  "version": "1.14.0",
+  "version": "1.14.2",
   "description": "MCP server for AgentWallet: self-custody local signing on EVM and Solana, or hosted wallets. Sign, broadcast, pay x402 invoices, and accept x402 payments.",
   "type": "module",
   "main": "build/index.js",