@celorodrigues/x402-conformance 2.1.0 → 2.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @celorodrigues/x402-conformance
 
-[![x402-conformance](https://api.automaton-sovereign.workers.dev/v2/badge/default.svg)](https://api.automaton-sovereign.workers.dev/leaderboard)
+[![x402-conformance](https://automaton-api.bfzovw.easypanel.host/v2/badge/default.svg)](https://automaton-api.bfzovw.easypanel.host/leaderboard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 > **Autonomous Linter and Conformance Suite for Official x402 Micropayments & EIP-3009**
@@ -47,9 +47,34 @@ The same package runs as an MCP stdio server:
 - Claude Desktop: Settings → Developer → Edit Config (`claude_desktop_config.json`), then restart.
 - Cursor: `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json`.
 
-Tools: `x402_conformance_check` (free, runs locally), `security_scan` (Base token honeypot / mint-trap / contract risk), `oracle_base`, `sentiment_analysis`, `attest`, `merkle_prove`, plus free `verify_attestation`, `read_ledger`, `merkle_verify`, `pricing`, `health`. Paid tools cost 0.001 USDC on Base (3 free calls/day/IP).
-
-Optional env: `VALUE_API_BASE` (default `https://api.automaton-sovereign.workers.dev`), `VALUE_API_PAYMENT` (payment tx hash attached to paid calls).
+### Available MCP Tools (15 Tools)
+
+#### 🆓 Free Diagnostics & Local Execution (No payment required)
+| Tool | Description |
+|---|---|
+| `simulate_base_transaction` | EVM transaction dry-run with exact gas estimation and revert reason decoding on Base L2. |
+| `x402_conformance_check` | Full 12-point conformance audit of any HTTP 402 API endpoint against the official spec. |
+| `health` | Real-time service diagnostics, node health, and payment recipient address. |
+| `pricing` | Live pricing directory across all hosted x402 services and settlement rails. |
+| `read_ledger` | Query the immutable, signed ledger of attested operations. |
+| `verify_attestation` | Verify cryptographic signatures and proofs offline or online. |
+| `attestation_pubkey` | Retrieve the agent's public key for independent trustless verification. |
+| `merkle_verify` | Validate cryptographic Merkle tree inclusion proofs. |
+
+#### ⚡ Hosted Intelligence & Consensus (x402 Micro-payments on Base — 3 Free Trials/Day/IP)
+| Tool | Price | Description |
+|---|---|---|
+| `oracle_base` | 0.001 USDC | Multi-RPC consensus oracle on Base (block, gas, clock, balance). |
+| `security_scan` | 0.002 USDC | EVM bytecode scanner, honeypot detection, fee-traps & contract risk analysis. |
+| `sentiment_analysis` | 0.001 USDC | Fast agentic financial sentiment scoring for market data. |
+| `attest` | 0.05 USDC | Generate on-chain attestations signed by Agent #95791. |
+| `merkle_prove` | 0.05 USDC | Cryptographic Merkle batch proof generation. |
+| `hash_sha256` | 0.0001 USDC | Fast deterministic SHA-256 computation. |
+| `uuid` | 0.0001 USDC | Cryptographically secure UUID generation. |
+
+Optional environment variables:
+- `VALUE_API_BASE`: Default `https://automaton-api.bfzovw.easypanel.host` (or edge mirror `https://api.automaton-sovereign.workers.dev`).
+- `VALUE_API_PAYMENT`: Optional Base USDC transaction hash or EIP-3009 authorization payload.
 
 ---
 
@@ -77,13 +102,13 @@ Optional env: `VALUE_API_BASE` (default `https://api.automaton-sovereign.workers
 Services that achieve a **CONFORMANT** verdict (Grade A or A+) can request an on-chain signed attestation and permanent verification badge:
 
 ```bash
-curl -X POST https://api.automaton-sovereign.workers.dev/v2/conformance/certify \
+curl -X POST https://automaton-api.bfzovw.easypanel.host/v2/conformance/certify \
   -H "Content-Type: application/json" \
   -H "X-PAYMENT: <txHash-or-EIP3009>" \
   -d '{"url":"https://your-service.com/v1/paid"}'
 ```
 
-* Certified services appear on the public [x402 Leaderboard](https://api.automaton-sovereign.workers.dev/leaderboard).
+* Certified services appear on the public [x402 Leaderboard](https://automaton-api.bfzovw.easypanel.host/leaderboard).
 * Fee: 0.05 USDC settled directly on Base L2 to `0x71DEAc098914A009E3720524642A6bE6F65EE528`.
 
 ---

package/bin/cli.js

@@ -4,7 +4,7 @@ const args = process.argv.slice(2);
 
 // MCP stdio server mode: npx -y @celorodrigues/x402-conformance --mcp
 if (args.includes('--mcp')) {
-  require('../mcp-server.js');
+  require('../mcp-server.js').startStdio();
   return;
 }
 

package/mcp-server.js

@@ -22,8 +22,9 @@ const https = require('https');
 const { URL } = require('url');
 const PKG = require('./package.json');
 const linter = require('./index.js');
+const simulator = require('./tx-simulator.js');
 
-const BASE = (process.env.VALUE_API_BASE || 'https://api.automaton-sovereign.workers.dev').replace(/\/+$/, '');
+const BASE = (process.env.VALUE_API_BASE || 'https://automaton-api.bfzovw.easypanel.host').replace(/\/+$/, '');
 const PAYMENT = process.env.VALUE_API_PAYMENT || '';
 
 function httpJson(method, urlStr, headers, body) {
@@ -49,9 +50,11 @@ function httpJson(method, urlStr, headers, body) {
 const TOOLS = [
   { name: 'x402_conformance_check', description: 'FREE, runs locally. Lint any x402 paid endpoint for protocol conformance: HTTP 402 challenge, x402Version, accepts[] (exact scheme), Base network and addresses, EIP-712 domain, and rejection of malformed, forged, expired, underpaid and wrong-recipient EIP-3009 payments. Returns verdict, grade and per-check results.',
     inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Full URL of the x402-protected endpoint to check.' } }, required: ['url'] } },
-  { name: 'security_scan', description: 'PAID 0.001 USDC/call, or free trial (3/day/IP). Base token safety analysis: honeypot detection, mint traps, selfdestruct/delegatecall, proxy and tax risks from contract bytecode, with a risk score and signed verdict. On 402, pay the accepts[] terms then retry with the payment tx hash.',
+  { name: 'simulate_base_transaction', description: 'FREE, runs locally against Base Mainnet RPC. Dry-run a transaction before sending it: eth_call + eth_estimateGas at the latest block. Predicts whether it will revert and decodes the reason (Error(string), Panic(uint256) codes, custom-error selector, or node rejection such as insufficient funds). Returns { ok, willRevert, revertReason, estimatedGas, returnData }.',
+    inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'Target contract or recipient address on Base (0x...).' }, data: { type: 'string', description: 'Calldata as 0x-hex (default 0x for a plain ETH transfer).' }, value: { type: 'string', description: 'ETH value in wei, decimal or 0x-hex (default 0).' }, from: { type: 'string', description: 'Optional sender address; needed for balance/allowance-dependent calls.' } }, required: ['to'] } },
+  { name: 'security_scan', description: 'PAID 0.002 USDC/call, or free trial (3/day/IP). Base token safety analysis: honeypot detection, mint traps, selfdestruct/delegatecall, proxy and tax risks from contract bytecode, with a risk score and signed verdict. On 402, pay the accepts[] terms then retry with the payment tx hash.',
     inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Token or contract address on Base (0x...).' }, payment: { type: 'string', description: 'Optional X-PAYMENT base tx hash of the USDC payment.' } }, required: ['address'] } },
-  { name: 'attest', description: 'Create a SIGNED, hash-chained, append-only attestation (verifiable proof-of-existence) for a payload. PAID: 0.001 USDC/call, or free trial (3/day/IP). On 402, pay the accepts[] terms then retry with the payment tx hash.',
+  { name: 'attest', description: 'Create a SIGNED, hash-chained, append-only attestation (verifiable proof-of-existence) for a payload. PAID: 0.05 USDC/call, or free trial (3/day/IP). On 402, pay the accepts[] terms then retry with the payment tx hash.',
     inputSchema: { type: 'object', properties: { data: { type: 'string', description: 'Payload to attest (any string).' }, payment: { type: 'string', description: 'Optional X-PAYMENT base tx hash of the USDC payment.' } }, required: ['data'] } },
   { name: 'verify_attestation', description: 'FREE. Verify a ledger entry by index or by data hash: recomputes hash, checks ECDSA signature and chain link.',
     inputSchema: { type: 'object', properties: { index: { type: 'integer' }, dataHash: { type: 'string' } } } },
@@ -77,63 +80,94 @@ const TOOLS = [
 
 function q(o) { return Object.entries(o || {}).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => k + '=' + encodeURIComponent(v)).join('&'); }
 
-async function callTool(name, args) {
+// opts.base / opts.headers let an embedding server (HTTP /mcp) call its own API directly and
+// forward the caller's IP / public host.
+async function callTool(name, args, opts) {
   args = args || {};
-  const payHeader = (args.payment || PAYMENT) ? { 'X-PAYMENT': args.payment || PAYMENT } : {};
+  opts = opts || {};
+  const B = (opts.base || BASE).replace(/\/+$/, '');
+  const fwd = opts.headers || {};
+  const payHeader = Object.assign({}, fwd, (args.payment || PAYMENT) ? { 'X-PAYMENT': args.payment || PAYMENT } : {});
   switch (name) {
     case 'x402_conformance_check': {
       if (!/^https?:\/\//i.test(args.url || '')) throw new Error('url must be an absolute http(s) URL');
       return { status: 200, body: await linter.run(args.url) };
     }
-    case 'security_scan': return httpJson('GET', BASE + '/v2/security/scan?' + q({ address: args.address }), payHeader);
-    case 'attest': return httpJson('POST', BASE + '/v2/attest', payHeader, { data: args.data });
-    case 'verify_attestation': return httpJson('GET', BASE + '/v2/verify?' + q({ index: args.index, dataHash: args.dataHash }));
-    case 'attestation_pubkey': return httpJson('GET', BASE + '/v2/pubkey');
-    case 'read_ledger': return httpJson('GET', BASE + '/v2/ledger?' + q({ from: args.from, limit: args.limit }));
-    case 'oracle_base': return httpJson('GET', BASE + '/v2/oracle/base', payHeader);
-    case 'merkle_prove': return httpJson('POST', BASE + '/v2/merkle/prove', payHeader, { items: args.items, target: args.target });
-    case 'merkle_verify': return httpJson('POST', BASE + '/v2/merkle/verify', {}, { item: args.item, proof: args.proof, root: args.root });
-    case 'sentiment_analysis': return httpJson('GET', BASE + '/v2/sentiment?' + q({ asset: args.asset }), payHeader);
-    case 'hash_sha256': return httpJson('GET', BASE + '/v1/hash?' + q({ input: args.input }), payHeader);
-    case 'uuid': return httpJson('GET', BASE + '/v1/uuid', payHeader);
-    case 'pricing': return httpJson('GET', BASE + '/pricing');
-    case 'health': return httpJson('GET', BASE + '/health');
+    case 'simulate_base_transaction': {
+      const r = await simulator.simulate({ to: args.to, data: args.data, value: args.value, from: args.from });
+      return { status: r.ok ? 200 : 400, body: r };
+    }
+    case 'security_scan': return httpJson('GET', B + '/v2/security/scan?' + q({ address: args.address }), payHeader);
+    case 'attest': return httpJson('POST', B + '/v2/attest', payHeader, { data: args.data });
+    case 'verify_attestation': return httpJson('GET', B + '/v2/verify?' + q({ index: args.index, dataHash: args.dataHash }), fwd);
+    case 'attestation_pubkey': return httpJson('GET', B + '/v2/pubkey', fwd);
+    case 'read_ledger': return httpJson('GET', B + '/v2/ledger?' + q({ from: args.from, limit: args.limit }), fwd);
+    case 'oracle_base': return httpJson('GET', B + '/v2/oracle/base', payHeader);
+    case 'merkle_prove': return httpJson('POST', B + '/v2/merkle/prove', payHeader, { items: args.items, target: args.target });
+    case 'merkle_verify': return httpJson('POST', B + '/v2/merkle/verify', fwd, { item: args.item, proof: args.proof, root: args.root });
+    case 'sentiment_analysis': return httpJson('GET', B + '/v2/sentiment?' + q({ asset: args.asset }), payHeader);
+    case 'hash_sha256': return httpJson('GET', B + '/v1/hash?' + q({ input: args.input }), payHeader);
+    case 'uuid': return httpJson('GET', B + '/v1/uuid', payHeader);
+    case 'pricing': return httpJson('GET', B + '/pricing', fwd);
+    case 'health': return httpJson('GET', B + '/health', fwd);
     default: throw new Error('unknown tool: ' + name);
   }
 }
 
-function reply(id, result) { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n'); }
-function replyErr(id, code, message, data) { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message, data } }) + '\n'); }
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 
-let buf = '';
-process.stdin.on('data', (chunk) => {
-  buf += chunk.toString('utf8');
-  let nl;
-  while ((nl = buf.indexOf('\n')) >= 0) {
-    const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);
-    if (!line) continue;
-    let msg; try { msg = JSON.parse(line); } catch (e) { continue; }
-    if (msg.method === 'initialize') {
-      reply(msg.id, { protocolVersion: '2024-11-05', capabilities: { tools: {} },
+/**
+ * Handles one JSON-RPC 2.0 message. Resolves to the response object, or null for
+ * notifications (no id). Shared by the stdio transport and the HTTP /mcp endpoint.
+ */
+async function handleMessage(msg, opts) {
+  if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+    return { jsonrpc: '2.0', id: (msg && msg.id !== undefined) ? msg.id : null, error: { code: -32600, message: 'invalid request' } };
+  }
+  const isNotification = msg.id === undefined;
+  const ok = (result) => isNotification ? null : { jsonrpc: '2.0', id: msg.id, result };
+  switch (msg.method) {
+    case 'initialize': {
+      const asked = msg.params && msg.params.protocolVersion;
+      return ok({ protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0], capabilities: { tools: {} },
         serverInfo: { name: 'automaton-x402', version: PKG.version } });
-    } else if (msg.method === 'ping') {
-      reply(msg.id, {});
-    } else if (msg.method === 'notifications/initialized') {
-      // no reply
-    } else if (msg.method === 'tools/list') {
-      reply(msg.id, { tools: TOOLS });
-    } else if (msg.method === 'tools/call') {
+    }
+    case 'ping': return ok({});
+    case 'tools/list': return ok({ tools: TOOLS });
+    case 'tools/call': {
       const { name, arguments: a } = msg.params || {};
-      Promise.resolve().then(() => callTool(name, a)).then((r) => {
-        const isClosedError = r.status >= 400;
+      try {
+        if (opts && opts.beforeCall) await opts.beforeCall(name, a || {});
+        const r = await callTool(name, a, opts);
+        const isErr = r.status >= 400;
         // MCP expects content[]; surface status + body, and mark 402 as error with actionable text
         const text = typeof r.body === 'string' ? r.body : JSON.stringify(r.body, null, 2);
-        const prefix = isClosedError ? ('HTTP ' + r.status + '\n') : '';
-        reply(msg.id, { content: [{ type: 'text', text: prefix + text }], isError: isClosedError });
-      }).catch((e) => reply(msg.id, { content: [{ type: 'text', text: 'error: ' + e.message }], isError: true }));
-    } else if (msg.id !== undefined) {
-      replyErr(msg.id, -32601, 'method not found: ' + msg.method);
+        return ok({ content: [{ type: 'text', text: (isErr ? 'HTTP ' + r.status + '\n' : '') + text }], isError: isErr });
+      } catch (e) {
+        return ok({ content: [{ type: 'text', text: 'error: ' + e.message }], isError: true });
+      }
     }
+    default:
+      if (msg.method.startsWith('notifications/')) return null;
+      return isNotification ? null : { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'method not found: ' + msg.method } };
   }
-});
-process.stdin.on('end', () => process.exit(0));
+}
+
+function startStdio() {
+  let buf = '';
+  process.stdin.on('data', (chunk) => {
+    buf += chunk.toString('utf8');
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg; try { msg = JSON.parse(line); } catch (e) { continue; }
+      handleMessage(msg).then((r) => { if (r) process.stdout.write(JSON.stringify(r) + '\n'); });
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+}
+
+module.exports = { TOOLS, callTool, handleMessage, startStdio };
+
+if (require.main === module) startStdio();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celorodrigues/x402-conformance",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Zero-dependency CLI, MCP server and testing suite for x402 AI agent micropayment protocol & EIP-3009 compliance",
   "main": "index.js",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "index.js",
     "mcp-server.js",
+    "tx-simulator.js",
     "bin/",
     "README.md",
     "LICENSE",
@@ -37,7 +38,7 @@
     "type": "git",
     "url": "git+https://github.com/baianomarceloeduardo-jpg/automaton-x402.git"
   },
-  "homepage": "https://api.automaton-sovereign.workers.dev/leaderboard",
+  "homepage": "https://automaton-api.bfzovw.easypanel.host/leaderboard",
   "bugs": {
     "url": "https://github.com/baianomarceloeduardo-jpg/automaton-x402/issues"
   },

package/smithery.yaml

@@ -7,20 +7,20 @@ startCommand:
     properties:
       valueApiBase:
         type: string
-        default: https://api.automaton-sovereign.workers.dev
+        default: https://automaton-api.bfzovw.easypanel.host
         description: Base URL of the Automaton-Sovereign Value API used by the paid/free API tools.
       valueApiPayment:
         type: string
-        description: Optional x402 payment (Base USDC tx hash) attached as X-PAYMENT to paid tool calls.
+        description: Optional x402 payment (Base USDC tx hash or EIP-3009 authorization) attached to paid tool calls.
   commandFunction:
     |-
     (config) => ({
       command: 'npx',
-      args: ['-y', '@celorodrigues/x402-conformance', '--mcp'],
+      args: ['-y', '@celorodrigues/x402-conformance@2.2.0', '--mcp'],
       env: Object.assign(
-        { VALUE_API_BASE: config.valueApiBase || 'https://api.automaton-sovereign.workers.dev' },
+        { VALUE_API_BASE: config.valueApiBase || 'https://automaton-api.bfzovw.easypanel.host' },
         config.valueApiPayment ? { VALUE_API_PAYMENT: config.valueApiPayment } : {}
       )
     })
   exampleConfig:
-    valueApiBase: https://api.automaton-sovereign.workers.dev
+    valueApiBase: https://automaton-api.bfzovw.easypanel.host

package/tx-simulator.js

@@ -0,0 +1,226 @@
+'use strict';
+/**
+ * Base Mainnet transaction simulator (zero deps).
+ *
+ * simulate({ to, data, value, from }) runs eth_call + eth_estimateGas against a Base RPC at a
+ * pinned block and predicts whether the tx will revert, decoding Error(string) (0x08c379a0),
+ * Panic(uint256) (0x4e487b71) and surfacing custom-error selectors.
+ *
+ * Returns { ok, willRevert, revertReason, estimatedGas, returnData, ... }.
+ *   ok          true when the simulation ran (RPC answered); false on bad input / RPC failure.
+ *   willRevert  true when the call reverts or the node rejects it (e.g. insufficient funds).
+ */
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+const DEFAULT_RPC = process.env.SIM_RPC_URL || process.env.BASE_RPC_URL || 'https://mainnet.base.org';
+const MAX_DATA_BYTES = 65536;                  // well above any real tx; bounds upstream work
+const MAX_DATA_HEX = 2 + MAX_DATA_BYTES * 2;
+const MAX_RPC_RESPONSE = 2 * 1024 * 1024;      // cap memory per upstream response
+const BASE_CHAIN_ID = '0x2105'; // 8453
+
+const PANIC_CODES = {
+  0x00: 'generic compiler panic',
+  0x01: 'assertion failed',
+  0x11: 'arithmetic overflow or underflow',
+  0x12: 'division or modulo by zero',
+  0x21: 'invalid enum value',
+  0x22: 'corrupted storage byte array',
+  0x31: 'pop() on empty array',
+  0x32: 'array index out of bounds',
+  0x41: 'out of memory / allocation too large',
+  0x51: 'call to zero-initialized function pointer'
+};
+
+function rpcCall(rpcUrl, method, params) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(rpcUrl);
+    const lib = u.protocol === 'http:' ? http : https;
+    const payload = JSON.stringify({ jsonrpc: '2.0', id: 1, method, params });
+    const req = lib.request({ hostname: u.hostname, port: u.port || (u.protocol === 'http:' ? 80 : 443), path: u.pathname + u.search, method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload), 'User-Agent': 'automaton-simulator/1.0' } }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; if (d.length > MAX_RPC_RESPONSE) req.destroy(new Error('rpc_response_too_large')); });
+      res.on('end', () => {
+        let j; try { j = JSON.parse(d); } catch (e) { return reject(new Error('bad_rpc_response (HTTP ' + res.statusCode + ')')); }
+        resolve(j); // caller inspects j.result / j.error (a revert arrives as j.error)
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(15000, () => req.destroy(new Error('rpc_timeout')));
+    req.write(payload); req.end();
+  });
+}
+
+function isAddr(a) { return typeof a === 'string' && /^0x[0-9a-fA-F]{40}$/.test(a); }
+
+// Accepts wei as decimal string/number, 0x-hex, or bigint. Returns a JSON-RPC quantity.
+function toQuantity(v) {
+  if (v === undefined || v === null || v === '' || v === 0 || v === '0') return '0x0';
+  let n;
+  if (typeof v === 'bigint') n = v;
+  else if (typeof v === 'number') { if (!Number.isSafeInteger(v) || v < 0) throw new Error('value must be a non-negative integer (wei)'); n = BigInt(v); }
+  else if (typeof v === 'string' && /^0x[0-9a-fA-F]+$/.test(v)) n = BigInt(v);
+  else if (typeof v === 'string' && /^\d+$/.test(v)) n = BigInt(v);
+  else throw new Error('value must be wei as a decimal or 0x-hex integer');
+  if (n < 0n) throw new Error('value must be non-negative');
+  return '0x' + n.toString(16);
+}
+
+function decodeRevert(hex) {
+  const data = typeof hex === 'string' ? hex.toLowerCase() : '';
+  if (!data || data === '0x') return { errorType: 'empty', reason: 'reverted without a reason' };
+  const sel = data.slice(0, 10);
+  const body = data.slice(10);
+  try {
+    if (sel === '0x08c379a0' && body.length >= 128) {
+      const off = Number(BigInt('0x' + body.slice(0, 64))) * 2;
+      const len = Number(BigInt('0x' + body.slice(off, off + 64)));
+      const str = Buffer.from(body.slice(off + 64, off + 64 + len * 2), 'hex').toString('utf8');
+      return { errorType: 'Error(string)', reason: str };
+    }
+    if (sel === '0x4e487b71' && body.length >= 64) {
+      const code = Number(BigInt('0x' + body.slice(0, 64)));
+      return { errorType: 'Panic(uint256)', panicCode: '0x' + code.toString(16).padStart(2, '0'),
+        reason: 'Panic(0x' + code.toString(16).padStart(2, '0') + '): ' + (PANIC_CODES[code] || 'unknown panic code') };
+    }
+  } catch (e) { /* fall through to raw selector */ }
+  return { errorType: 'custom', selector: sel, reason: 'custom error ' + sel + ' (not ABI-decoded)' };
+}
+
+// Node errors carry revert data in error.data (string) or error.data.data depending on client.
+function revertDataOf(err) {
+  if (!err) return null;
+  const d = err.data;
+  if (typeof d === 'string' && /^0x[0-9a-fA-F]*$/.test(d)) return d;
+  if (d && typeof d === 'object' && typeof d.data === 'string') return d.data;
+  return null;
+}
+
+// JSON-RPC error -> 'revert' (execution reverted), 'rejected' (node refuses the tx itself:
+// funds, gas, nonce) or 'transient' (rate limit, capacity, internal: says nothing about the tx).
+function classify(err) {
+  if (!err) return null;
+  if (revertDataOf(err)) return 'revert';
+  const msg = String(err.message || '');
+  if (err.code === 3 || /revert/i.test(msg)) return 'revert';
+  if (/insufficient funds|OutOfFunds|gas required exceeds|intrinsic gas|gas too low|exceeds block gas limit|nonce|invalid opcode|out of gas|stack (over|under)flow|InvalidFEOpcode|OpcodeNotFound/i.test(msg)) return 'rejected';
+  return 'transient';
+}
+
+// Returns an error string for unusable input, or null. Pure and cheap: callers run it before
+// charging a payment or spending an RPC call.
+function validate(input) {
+  input = input || {};
+  if (!isAddr(input.to)) return 'to must be a 0x-prefixed 20-byte address';
+  if (input.from !== undefined && input.from !== null && input.from !== '' && !isAddr(input.from)) return 'from must be a 0x-prefixed 20-byte address';
+  const data = input.data === undefined || input.data === null || input.data === '' ? '0x' : input.data;
+  if (typeof data !== 'string') return 'data must be a 0x-hex string';
+  if (data.length > MAX_DATA_HEX) return 'calldata too large (max ' + MAX_DATA_BYTES + ' bytes)';
+  if (!/^0x([0-9a-fA-F]{2})*$/.test(data)) return 'data must be 0x-prefixed even-length hex';
+  try { toQuantity(input.value); } catch (e) { return e.message; }
+  return null;
+}
+
+// Process-wide limiter: the free MCP tool must not turn this host into an open Base RPC proxy
+// (each simulation costs 4 upstream calls, and the same public RPC verifies our payments).
+const RATE_PER_MIN = parseInt(process.env.SIM_RATE_PER_MIN || '120', 10);
+const MAX_CONCURRENT = parseInt(process.env.SIM_MAX_CONCURRENT || '8', 10);
+let tokens = RATE_PER_MIN, refillAt = Date.now(), inFlight = 0;
+function acquire() {
+  const now = Date.now();
+  tokens = Math.min(RATE_PER_MIN, tokens + ((now - refillAt) / 60000) * RATE_PER_MIN);
+  refillAt = now;
+  if (inFlight >= MAX_CONCURRENT) return 'rate_limited: too many concurrent simulations, retry shortly';
+  if (tokens < 1) return 'rate_limited: simulation quota exceeded (' + RATE_PER_MIN + '/min), retry shortly';
+  tokens -= 1; inFlight++;
+  return null;
+}
+
+async function simulate(input, opts) {
+  input = input || {};
+  opts = opts || {};
+  const out = { ok: false, network: 'base', chainId: 8453, willRevert: null, revertReason: null, estimatedGas: null, returnData: null };
+  const invalid = validate(input);
+  if (invalid) { out.error = invalid; return out; }
+  // Paid HTTP calls (already metered by x402) skip the free-tier limiter but not the concurrency cap.
+  if (!opts.bypassLimit) {
+    const limited = acquire();
+    if (limited) { out.error = limited; out.rateLimited = true; return out; }
+  } else inFlight++;
+  try { return await run(input, opts, out); } finally { inFlight--; }
+}
+
+async function run(input, opts, out) {
+  const rpcUrl = opts.rpcUrl || DEFAULT_RPC;
+  const data = input.data === undefined || input.data === null || input.data === '' ? '0x' : input.data;
+  const value = toQuantity(input.value);
+
+  const tx = { to: input.to, data, value };
+  if (input.from) tx.from = input.from;
+
+  let chain, head;
+  try {
+    [chain, head] = await Promise.all([rpcCall(rpcUrl, 'eth_chainId', []), rpcCall(rpcUrl, 'eth_blockNumber', [])]);
+  } catch (e) { out.error = 'rpc_unreachable: ' + e.message; return out; }
+  if (!chain.result || String(chain.result).toLowerCase() !== BASE_CHAIN_ID) { out.error = 'rpc is not Base Mainnet (chainId ' + (chain.result || '?') + ')'; return out; }
+  if (!head.result) { out.error = 'rpc_error: ' + ((head.error && head.error.message) || 'no block number'); return out; }
+  const block = head.result;
+  out.blockNumber = parseInt(block, 16);
+  out.tx = tx;
+
+  let call, gas;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      [call, gas] = await Promise.all([rpcCall(rpcUrl, 'eth_call', [tx, block]), rpcCall(rpcUrl, 'eth_estimateGas', [tx, block])]);
+    } catch (e) { out.error = 'rpc_unreachable: ' + e.message; return out; }
+    // Rate limits / capacity errors are not reverts: retry once, then report ok:false.
+    if (classify(call.error) !== 'transient' && classify(gas.error) !== 'transient') break;
+    if (attempt === 0) await new Promise((r) => setTimeout(r, 400));
+  }
+  if (classify(call.error) === 'transient') {
+    out.error = 'rpc_error: ' + String(call.error.message || call.error.code || 'unknown').slice(0, 200);
+    return out;
+  }
+
+  out.ok = true;
+  if (call.error) {
+    const rd = revertDataOf(call.error);
+    out.willRevert = true;
+    out.returnData = rd;
+    if (rd) {
+      const dec = decodeRevert(rd);
+      out.revertReason = dec.reason; out.errorType = dec.errorType;
+      if (dec.panicCode) out.panicCode = dec.panicCode;
+      if (dec.selector) out.errorSelector = dec.selector;
+    } else {
+      // No revert payload: node-level rejection (insufficient funds, bad nonce, ...) or bare revert.
+      const msg = String(call.error.message || 'execution failed');
+      out.revertReason = msg;
+      out.errorType = /revert/i.test(msg) ? 'empty' : 'node_rejected';
+    }
+  } else {
+    out.willRevert = false;
+    out.returnData = call.result || '0x';
+  }
+
+  if (gas.result) out.estimatedGas = parseInt(gas.result, 16);
+  else if (gas.error) {
+    out.estimateGasError = String(gas.error.message || 'estimateGas failed');
+    // eth_call can pass while estimateGas fails (e.g. gas-dependent logic): still a revert on-chain.
+    // A transient RPC error on estimateGas alone says nothing about the tx, so it does not flip it.
+    if (out.willRevert === false && classify(gas.error) !== 'transient') {
+      out.willRevert = true;
+      const rd = revertDataOf(gas.error);
+      const dec = rd ? decodeRevert(rd) : null;
+      out.revertReason = dec ? dec.reason : out.estimateGasError;
+      out.errorType = dec ? dec.errorType : 'estimate_gas_failed';
+    }
+  }
+  out.success = out.willRevert === false;
+  out.simulatedAt = new Date().toISOString();
+  return out;
+}
+
+module.exports = { simulate, validate, decodeRevert, toQuantity, PANIC_CODES };