@celorodrigues/x402-conformance 2.0.0 → 2.2.0

package/README.md

@@ -29,6 +29,30 @@ npx @celorodrigues/x402-conformance https://your-service.com/v1/paid --svg > bad
 
 ---
 
+## 🤖 MCP Server (Claude Desktop, Cursor)
+
+The same package runs as an MCP stdio server:
+
+```json
+{
+  "mcpServers": {
+    "automaton-x402": {
+      "command": "npx",
+      "args": ["-y", "@celorodrigues/x402-conformance", "--mcp"]
+    }
+  }
+}
+```
+
+- 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), `simulate_base_transaction` (free, EVM dry-run via Base RPC with revert reason decoding), `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 - 0.05 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).
+
+---
+
 ## 🧪 Battery of Checks
 
 | Code | Level | Check | Requirement |

package/bin/cli.js

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 'use strict';
-const engine = require('../index.js');
-
 const args = process.argv.slice(2);
+
+// MCP stdio server mode: npx -y @celorodrigues/x402-conformance --mcp
+if (args.includes('--mcp')) {
+  require('../mcp-server.js').startStdio();
+  return;
+}
+
+const engine = require('../index.js');
 const target = args.find(a => !a.startsWith('--'));
 const jsonMode = args.includes('--json');
 const svgMode = args.includes('--svg');
 
 if (!target) {
   console.error('\nUsage: npx @celorodrigues/x402-conformance <endpoint-url> [--json] [--svg]');
+  console.error('       npx -y @celorodrigues/x402-conformance --mcp   (run as an MCP stdio server)');
   console.error('Example: npx @celorodrigues/x402-conformance https://api.myservice.com/v1/paid --json\n');
   process.exit(2);
 }

package/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * x402-conformance  v2.0.0 -- Autonomous x402 Protocol Conformance Linter & Certification Engine
+ * x402-conformance -- Autonomous x402 Protocol Conformance Linter & Certification Engine
  * Conforms strictly to official Coinbase x402 specifications (v1 and v2 CAIP-2) & EIP-3009.
  * Author: Automaton-Sovereign (Base: 0x71DEAc098914A009E3720524642A6bE6F65EE528)
  * 
@@ -23,6 +23,7 @@
 const https = require('https');
 const http = require('http');
 const { URL } = require('url');
+const VERSION = require('./package.json').version;
 
 function fetchUrl(targetUrl, options = {}) {
   return new Promise((resolve, reject) => {
@@ -30,7 +31,7 @@ function fetchUrl(targetUrl, options = {}) {
       const u = new URL(targetUrl);
       const lib = u.protocol === 'http:' ? http : https;
       const headers = Object.assign({
-        'User-Agent': 'Automaton-x402-Conformance-Linter/2.0.0',
+        'User-Agent': 'Automaton-x402-Conformance-Linter/' + VERSION,
         'Accept': 'application/json, text/plain, */*'
       }, options.headers || {});
 
@@ -271,7 +272,7 @@ function finish(results, targetUrl) {
 
   return {
     suite: '@celorodrigues/x402-conformance',
-    version: '2.0.0',
+    version: VERSION,
     target: targetUrl,
     timestamp: new Date().toISOString(),
     verdict: isConformant ? 'CONFORMANT' : 'NON_CONFORMANT',

package/mcp-server.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Automaton-Sovereign Value API — MCP server (stdio transport, zero deps, JSON-RPC 2.0)
+ *
+ * Exposes the x402-paid Value API as native MCP tools so any MCP-capable agent
+ * can call it directly. Paid tools forward the caller's X-PAYMENT tx hash;
+ * free tools need nothing.
+ *
+ * Also exposes the local x402 conformance linter (index.js) as a free tool.
+ *
+ * Config via env:
+ *   VALUE_API_BASE      base URL of the API (default https://api.automaton-sovereign.workers.dev)
+ *   VALUE_API_PAYMENT   default X-PAYMENT tx hash to attach to paid calls (optional)
+ *
+ * Usage (Claude Desktop / Cursor MCP config):
+ *   { "mcpServers": { "automaton-x402": { "command": "npx",
+ *       "args": ["-y", "@celorodrigues/x402-conformance", "--mcp"] } } }
+ */
+const http = require('http');
+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 PAYMENT = process.env.VALUE_API_PAYMENT || '';
+
+function httpJson(method, urlStr, headers, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(urlStr);
+    const lib = u.protocol === 'http:' ? http : https;
+    const payload = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : null;
+    const h = Object.assign({ 'Accept': 'application/json', 'User-Agent': 'automaton-mcp/1.0' }, headers || {});
+    if (payload) { h['Content-Type'] = 'application/json'; h['Content-Length'] = Buffer.byteLength(payload); }
+    const req = lib.request({ hostname: u.hostname, port: u.port || (u.protocol === 'http:' ? 80 : 443), path: u.pathname + u.search, method, headers: h }, (res) => {
+      let d = ''; res.on('data', c => d += c);
+      res.on('end', () => {
+        let parsed = null; try { parsed = JSON.parse(d); } catch (e) {}
+        resolve({ status: res.statusCode, headers: res.headers, body: parsed !== null ? parsed : d });
+      });
+    });
+    req.on('error', reject); req.setTimeout(30000, () => req.destroy(new Error('timeout')));
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+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: '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.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.',
+    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.',
+    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' } } } },
+  { name: 'attestation_pubkey', description: 'FREE. Get the ECDSA P-256 public key (PEM) and keyId used to sign ledger entries.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'read_ledger', description: 'FREE. Read the attestation ledger (paginated).',
+    inputSchema: { type: 'object', properties: { from: { type: 'integer' }, limit: { type: 'integer' } } } },
+  { name: 'oracle_base', description: 'PAID 0.001 USDC/call. Get real-time Base L2 gas estimates and asset prices (ETH, USDC, cbBTC, AERO, VIRTUAL) with an ECDSA P-256 digital signature from the sovereign agent.',
+    inputSchema: { type: 'object', properties: { payment: { type: 'string', description: 'Optional X-PAYMENT base tx hash of the USDC payment.' } } } },
+  { name: 'merkle_prove', description: 'PAID 0.001 USDC/call. Generate a cryptographic Merkle inclusion proof for a list of items and target element.',
+    inputSchema: { type: 'object', properties: { items: { type: 'array', items: { type: 'string' }, description: 'Array of items' }, target: { type: 'string', description: 'Target item or index' }, payment: { type: 'string' } }, required: ['items'] } },
+  { name: 'merkle_verify', description: 'FREE. Verify a cryptographic Merkle inclusion proof against a root.',
+    inputSchema: { type: 'object', properties: { item: { type: 'string' }, proof: { type: 'array', items: { type: 'object' } }, root: { type: 'string' } }, required: ['item', 'proof', 'root'] } },
+  { name: 'sentiment_analysis', description: 'PAID 0.001 USDC/call. Web3 token risk, security checks, and sentiment scoring with signed verdict.',
+    inputSchema: { type: 'object', properties: { asset: { type: 'string', description: 'Asset symbol (e.g. ETH, AERO, VIRTUAL)' }, payment: { type: 'string' } }, required: ['asset'] } },
+  { name: 'hash_sha256', description: 'PAID 0.001 USDC/call. SHA-256 hex of a string.',
+    inputSchema: { type: 'object', properties: { input: { type: 'string' }, payment: { type: 'string' } }, required: ['input'] } },
+  { name: 'uuid', description: 'PAID 0.001 USDC/call. Generate a UUIDv4.', inputSchema: { type: 'object', properties: { payment: { type: 'string' } } } },
+  { name: 'pricing', description: 'FREE. Full pricing terms, endpoints, and payment mechanics.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'health', description: 'FREE. Service liveness and version.', inputSchema: { type: 'object', properties: {} } }
+];
+
+function q(o) { return Object.entries(o || {}).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => k + '=' + encodeURIComponent(v)).join('&'); }
+
+// 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 || {};
+  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 '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);
+  }
+}
+
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+/**
+ * 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 } });
+    }
+    case 'ping': return ok({});
+    case 'tools/list': return ok({ tools: TOOLS });
+    case 'tools/call': {
+      const { name, arguments: a } = msg.params || {};
+      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);
+        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 } };
+  }
+}
+
+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,16 +1,19 @@
 {
   "name": "@celorodrigues/x402-conformance",
-  "version": "2.0.0",
-  "description": "Zero-dependency CLI & testing suite for official x402 AI agent micropayment protocol & EIP-3009 compliance",
+  "version": "2.2.0",
+  "description": "Zero-dependency CLI, MCP server and testing suite for x402 AI agent micropayment protocol & EIP-3009 compliance",
   "main": "index.js",
   "bin": {
     "x402-conformance": "bin/cli.js"
   },
   "files": [
     "index.js",
+    "mcp-server.js",
+    "tx-simulator.js",
     "bin/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "smithery.yaml"
   ],
   "keywords": [
     "x402",
@@ -21,7 +24,10 @@
     "micropayments",
     "usdc",
     "linter",
-    "conformance"
+    "conformance",
+    "mcp",
+    "model-context-protocol",
+    "claude"
   ],
   "author": "Automaton-Sovereign (0x71DEAc098914A009E3720524642A6bE6F65EE528)",
   "license": "MIT",

package/smithery.yaml

@@ -0,0 +1,26 @@
+# Smithery configuration: https://smithery.ai/docs/config#smitheryyaml
+# MCP stdio server shipped in the npm package (`x402-conformance --mcp`).
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      valueApiBase:
+        type: string
+        default: https://api.automaton-sovereign.workers.dev
+        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.
+  commandFunction:
+    |-
+    (config) => ({
+      command: 'npx',
+      args: ['-y', '@celorodrigues/x402-conformance', '--mcp'],
+      env: Object.assign(
+        { VALUE_API_BASE: config.valueApiBase || 'https://api.automaton-sovereign.workers.dev' },
+        config.valueApiPayment ? { VALUE_API_PAYMENT: config.valueApiPayment } : {}
+      )
+    })
+  exampleConfig:
+    valueApiBase: https://api.automaton-sovereign.workers.dev

package/tx-simulator.js

@@ -0,0 +1,165 @@
+'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.BASE_RPC_URL || 'https://mainnet.base.org';
+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);
+      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;
+}
+
+async function simulate(input, opts) {
+  input = input || {};
+  opts = opts || {};
+  const rpcUrl = opts.rpcUrl || DEFAULT_RPC;
+  const out = { ok: false, network: 'base', chainId: 8453, willRevert: null, revertReason: null, estimatedGas: null, returnData: null };
+
+  if (!isAddr(input.to)) { out.error = 'to must be a 0x-prefixed 20-byte address'; return out; }
+  if (input.from !== undefined && input.from !== null && input.from !== '' && !isAddr(input.from)) { out.error = 'from must be a 0x-prefixed 20-byte address'; return out; }
+  const data = input.data === undefined || input.data === null || input.data === '' ? '0x' : String(input.data);
+  if (!/^0x([0-9a-fA-F]{2})*$/.test(data)) { out.error = 'data must be 0x-prefixed even-length hex'; return out; }
+  let value; try { value = toQuantity(input.value); } catch (e) { out.error = e.message; return out; }
+
+  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;
+  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; }
+
+  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.
+    if (out.willRevert === false) {
+      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, decodeRevert, toQuantity, PANIC_CODES };