@celorodrigues/x402-conformance 2.1.0 → 2.2.0

package/README.md

@@ -47,7 +47,7 @@ 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).
+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).
 

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,6 +22,7 @@ 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 || '';
@@ -49,6 +50,8 @@ 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: '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.',
@@ -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.0",
   "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",

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 };