Magneta Contract Risk

Magneta 合约风险（x402）

一项面向生产环境的小型服务，向 AI Agent 提供链上智能合约风险报告，按调用次数通过 x402 微支付（USDC、EIP-3009 exact 方案）收款。一个 Express 进程，提供两个付费入口：

入口	路由	价格
HTTP	GET /v1/risk/:chainId/:address	$0.02
MCP（Streamable HTTP，无状态）	POST /mcp，工具 contract_risk_summary(chainId, address)	$0.02
MCP	工具 supported_chains	免费
健康检查	GET /health	免费

两个付费入口都会调用 src/risk/analyze.ts 中的同一个 analyzeContract(chainId, address)。分析结果具有确定性，且仅使用公开数据（RPC、Blockscout、Sourcify、本地 aderyn 二进制文件）。分析不使用大模型，也不需要 API 密钥。 未知链或格式错误的地址会在请求支付之前返回 400。如果分析本身失败（不是合约、上游错误、超时），响应会返回错误状态，且买家不会被扣款（x402 只会结算成功的响应）。

支持的链（v1，src/chains.ts）：Base 8453、Base Sepolia 84532、Ethereum 1、Arbitrum One 42161。使用 RPC_URL_<chainId> 覆盖 RPC。

报告

{ chainId, address, analyzedAt, isContract, bytecodeSize, proxy, erc20, opcodes, selectors: { found },
  blockscout, sourcify?, aderyn, score, level, flags, notes }

• proxy：来自 EIP-1967（implementation/admin/beacon）、旧版 zeppelinos 槽位、EIP-1822、EIP-1167 克隆或 Blockscout 检测结果的 { type, implementation, admin? }。也会分析实现合约的字节码。
• erc20：名称、符号、小数位数、总供应量、owner()（以及是否为零地址）、paused()。每项探测都会单独进行 try/catch。
• opcodes：通过跳过 PUSH 数据的实际操作码遍历，检测是否存在 SELFDESTRUCT / DELEGATECALL（不进行子字符串匹配）。
• selectors.found：风险签名（mint、pause、blacklist、手续费/税费设置器、升级、所有权……），其 4 字节选择器以 PUSH4 形式出现在字节码中。这是一种启发式判断：存在并不能证明代码可达（notes 中也会说明）。
• blockscout / sourcify：验证状态、编译器、合约名称、创建者和创建交易。Blockscout 超时设为 5 s；失败时返回 blockscout: { available: false }。只有在 Blockscout 无法访问或报告“未验证”时，才会将 Sourcify 作为后备进行查询。对于代理合约，以实现合约的验证状态为准。
• aderyn：有已验证的 Solidity 源码时，会将源码写入临时目录（路径经过清理），并以 15 s 超时运行 aderyn：{ ran, counts: { high, low }, top: [{ title, severity, instances }] }；否则返回 { ran: false, reason }。它绝不会导致请求失败。
• 总预算：每次分析的硬性截止时间为 24 s。结果会按 chainId+address 在内存中缓存 10 分钟（每次调用仍会进行支付）。

评分规则（src/risk/score.ts）

分数为 0..100，分数越高风险越大，采用累加方式，最高为 100。

分值	条件
+25	逻辑合约的源码未通过验证（先查 Blockscout，再查 Sourcify）
+0（标记）	所有提供方都无法访问，导致验证状态未知
+15	代理 / 可升级
+10	存在 owner()，且其值不是零地址
+15	mint 选择器
+15	blacklist / bot-list 选择器
+10	手续费 / 税费 / 限额 / 交易开关设置器
+5（当前已暂停时 +5）	pause 选择器
+10	SELFDESTRUCT 操作码
每项 +5，最高 +20	aderyn 高严重性发现

等级：0-24 为 low，25-49 为 medium，50-74 为 high，75-100 为 critical。非合约地址会报错，而不是给出分数。该分数用于分诊，并非审计结果。

支持的链

主网：Ethereum（1）、OP Mainnet（10）、BNB Smart Chain（56）、Gnosis（100）、Unichain（130）、Polygon（137）、Sonic（146）、 World Chain（480）、Mantle（5000）、Base（8453）、Arbitrum One（42161）、Celo（42220）、Avalanche C-Chain（43114）、Linea（59144）、 Blast（81457）、Scroll（534352）。测试网：Base Sepolia（84532）、Sepolia（11155111）、OP Sepolia（11155420）、Arbitrum Sepolia（421614）。 没有 Blockscout 实例的链（BNB、Sonic、Mantle、Avalanche）依赖 Sourcify 获取已验证的源码。特意排除了 zkSync Era：EraVM 字节码会破坏操作码和选择器启发式分析。来自 Blockscout 或 Sourcify 的编译器 remapping 会写入 remappings.txt，以便 aderyn 解析 @openzeppelin/... 样式的导入。

支付网络

买家使用 Base 上的 USDC（eip155:8453）付款。设置 SOLANA_PAY_TO 后，相同的路由和工具也接受 Solana 主网上的 USDC（solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp），并由同一个 Coinbase CDP 付款服务商结算，由其支付 Solana 手续费。Solana 收款地址必须已拥有 USDC 代币账户（SDK 不会创建该账户）。pnpm buy-once-svm 使用 Solana 密钥对（SVM_PRIVATE_KEY，base58 编码的 64 字节私钥）支付一次调用。

免费层、Agent 技能和客户端包

• 免费预览：GET /v1/flags/:chainId/:address 和 MCP 工具 contract_quick_flags 无需付款即可返回报告中仅基于字节码的部分（代理、所有者／暂停状态、风险选择器、操作码、部分评分）。每个 IP 每分钟限 30 次请求。源码验证和 aderyn 检测结果仅包含在付费报告中。
• Agent 技能：npx skills add Bosacks/magneta-risk-x402 --skill magneta-contract-risk 安装 skills/magneta-contract-risk/SKILL.md，该技能会指导 Agent 何时以及如何通过 HTTP、MCP 或 Coinbase Agentic Wallet 购买报告。
• 客户端包：@magnetafinance/contract-risk （npm i @magnetafinance/contract-risk @x402/[email protected] @x402/[email protected] @x402/[email protected] [email protected]，源码位于 packages/contract-risk-client）将 x402 支付流程封装为类型化客户端，并提供适用于 LangChain.js、Vercel AI SDK 以及 OpenAI/Anthropic 函数调用的工具适配器。
• ElizaOS 插件：packages/plugin-elizaos（@magnetafinance/plugin-contract-risk）为 Eliza Agent 添加 CONTRACT_QUICK_FLAGS（免费）和 CONTRACT_RISK_REPORT（付费，每笔付款设有上限）操作。
• ERC-8004 身份：注册文件 erc8004/agent-registration.json 通过 /.well-known/agent-registration.json 提供；scripts/erc8004-register.ts 会输出 Base IdentityRegistry 的 register(string) 调用，地址为 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432。

运行

pnpm install --ignore-scripts
cp .env.example .env.local      # fill PAY_TO, X402_NETWORK, FACILITATOR_URL (+ CDP keys if cdp)
pnpm dev                        # tsx, or: pnpm build && pnpm start
pnpm type-check && pnpm test    # unit tests, no network
pnpm analyze 84532 0x036CbD53842c5426634e7929541eC2318f3dCF7e   # free local run, prints the report

购买（需要已注资的买家密钥，消费上限为 $0.05；切勿将此密钥放在服务器上）：

BUYER_PRIVATE_KEY=0x... pnpm buy-once        # HTTP; prints the report and the PAYMENT-RESPONSE tx hash
BUYER_PRIVATE_KEY=0x... pnpm buy-once-mcp    # same through the MCP tool

环境

• PUBLIC_URL（https，无末尾斜杠）：作为 Bazaar 发现使用的 MCP 资源 URL。位于反向代理后时，服务器会信任本地回环代理（trust proxy = loopback），因此资源 URL 会以 https:// 公告；否则，facilitator 会以“resource must start with https://”拒绝发现。

变量	含义
PORT	监听端口（默认值为 3011）
PAY_TO	收款地址（必填）
X402_NETWORK	CAIP-2 网络，默认值为 eip155:84532（Base Sepolia）；生产环境使用：eip155:8453
FACILITATOR_URL	cdp（Coinbase CDP facilitator，需要 CDP_API_KEY_ID + CDP_API_KEY_SECRET），或 HTTP facilitator URL，例如 https://x402.org/facilitator（测试网）
ADERYN_BIN	aderyn 0.6.8 二进制文件，默认值为 /home/dominique/bin/aderyn
RPC_URL_<chainId>	可选的各链 RPC 覆盖项
BUYER_PRIVATE_KEY、TARGET_URL、MCP_URL、CHAIN_ID、ADDRESS	仅供买家脚本使用

部署（systemd + Caddy）

pnpm install --ignore-scripts && pnpm build
rsync -a --exclude node_modules --exclude .env.local --exclude 'scripts/logs' ./ server:/srv/magneta/risk-x402/    # never overwrite the server's .env.local; then pnpm install --prod --ignore-scripts there
sudo cp deploy/magneta-risk-x402.service /etc/systemd/system/ && sudo systemctl enable --now magneta-risk-x402
# add deploy/Caddyfile.snippet to the Caddyfile (vhost x402.magneta.finance -> 127.0.0.1:3011), reload Caddy

该服务单元会读取 /srv/magneta/risk-x402/.env.local。在主网环境中，设置 X402_NETWORK=eip155:8453 和 FACILITATOR_URL=cdp。 Aderyn 需要能够在服务用户的环境中使用 solc 下载文件和缓存（HOME 必须可写）。

Bazaar 发现

两个付费入口都使用来自 @x402/extensions/bazaar 的 declareDiscoveryExtension 声明 x402 Bazaar 发现元数据（HTTP 路由包含路径参数架构和输出示例；MCP 工具包含输入架构），并在资源服务器上注册 bazaarResourceServerExtension。元数据会显示在 PAYMENT-REQUIRED 标头的 extensions.bazaar 中。实际目录收录取决于 facilitator：它会在结算付款时为资源编制索引，因此只有在通过支持 Bazaar 的 facilitator（CDP）进行首次真实付费调用后，列表才会显示。预计公开的 x402.org 测试网 facilitator 不会收录该资源。

生产状态（2026-10-16）

服务已在 Base 主网上线，地址为 https://x402.magneta.finance（`eip155:8453`），使用 Coinbase CDP facilitator，每次调用收费 $0.02，已收录到 x402 Bazaar（路由 /v1/risk/:chainId/:address）。买家需要在 Base 上持有 USDC，无需 ETH。如果付款方与 payTo 相同，facilitator 会拒绝付款（self_send_not_allowed）。

许可证

MIT，版权所有 (c) 2026 Magneta Finance。请参阅 LICENSE。